fluid-core/spec/FluidHypothesisRevisionSchema.md

FLUID Hypothesis and Revision Schema

Document: FluidHypothesisRevisionSchema.md
Version: 0.1.0
Status: Working Implementation Schema
Companion to: FluidAPIStandards.md

---

1. Purpose

This document defines a concrete persistence and exchange model for two core FLUID artifacts:

1. Hypothesis Record — why an interface change should be explored.
2. Revision Record — what deterministic interface state was built, verified, exposed, and measured.

The schema is intentionally technology-neutral.

An implementation MAY persist the model as:

• JSON;
• YAML;
• relational tables;
• event streams;
• graph records;
• document storage.

Field names and semantics SHOULD remain stable enough to support tooling interoperability.

---

Part I — Hypothesis Record

2. Hypothesis Lifecycle

A hypothesis progresses through states such as:

DRAFT
→ READY
→ PRIORITIZED
→ DESIGNING
→ EXPERIMENTING
→ EVALUATING
→ ACCEPTED | REJECTED | SUPERSEDED | DEFERRED

A hypothesis MAY produce multiple candidate revisions.

Multiple hypotheses MAY compete to explain the same interface pressure.

---

3. Hypothesis Record

fluid_hypothesis:
  schema_version: "0.1"

  id: "H-000184"
  interface_id: "customer-finance-api"

  state: "PRIORITIZED"

  created_at: "2026-09-04T12:00:00Z"
  created_by:
    type: "daimon"
    id: "fluid-daimon/customer-finance-api"
    model_or_agent: "optional"

  title: "Provide direct latest-invoice capability"

  observation:
    summary: >
      A significant consumer cohort retrieves invoice collections,
      sorts them by issue date, and discards all but the first item.
    evidence_refs:
      - "telemetry:invoice-pattern-2026w36"
      - "feedback:F-9821"
    affected_cohorts:
      - "partner-integrations"
      - "coding-agents"
    observation_window:
      start: "2026-08-15T00:00:00Z"
      end: "2026-09-01T00:00:00Z"

  pressure:
    classes:
      - "successful_but_inefficient_usage"
      - "repeated_expectation_mismatch"
    severity: 0.61
    confidence: 0.88

  explanation:
    claim: >
      Consumers treat "latest invoice" as a domain-level concept
      and the existing generic collection interface does not present
      that concept directly.
    reach:
      score: 0.42
      explains:
        - "P-1831"
        - "P-1834"
      notes: >
        Medium reach: explains several related request patterns
        but not broader financial-context pressure.

  proposed_adaptation:
    class: "contract"
    summary: >
      Add an explicit latest-invoice retrieval capability.
    candidate_contract:
      method: "GET"
      path: "/customers/{id}/invoices/latest"
    implementation_scope: "interface_only"

  backend_requirements:
    required: false
    requirement_refs: []

  expected_outcomes:
    - metric: "requests_per_completed_task"
      cohort: "all"
      baseline: 2.7
      target: 1.2
      direction: "lower"
    - metric: "client_side_sort_workarounds"
      cohort: "all"
      baseline: 1.0
      target: 0.2
      direction: "lower"

  guardrails:
    - metric: "p95_latency_ms"
      operator: "<="
      threshold: 315
    - metric: "authorization_scope_change"
      operator: "=="
      threshold: false
    - metric: "backend_query_count_delta"
      operator: "<="
      threshold: 0

  fitness_dimensions:
    expected:
      client_utility: 0.70
      correctness: 0.00
      reliability: 0.00
      performance: 0.10
      discoverability: 0.65
      simplicity: -0.15
      compatibility: 0.00
      security: 0.00
      maintainability: -0.05
      operational_cost: 0.00

  complexity:
    expected_delta:
      surface_area: 1
      concept_count: 0
      operation_count: 1
      semantic_overlap: 0.1
      cognitive_load: -0.2
    score: 0.18

  risk:
    level: "LOW"
    reasons:
      - "read-only operation"
      - "no authorization expansion"

  economics:
    estimated_experiment_cost: 18.00
    estimated_implementation_cost: 40.00
    currency: "EUR"
    expected_value_class: "MEDIUM"

  learning_value:
    score: 0.56
    notes: >
      Useful signal for whether first-class convenience resources
      improve agent and partner integration behavior.

  priority:
    score: 0.71
    decided_by: "optimization-policy-v3"

  success_criteria:
    expression: >
      requests_per_completed_task <= 1.2
      AND no hard guardrail violation

  failure_criteria:
    expression: >
      any hard guardrail violation
      OR adoption below 5% after 30 days when equally discoverable

  candidate_revision_refs:
    - "R-000221"

  experiment_refs:
    - "E-000093"

  outcome:
    status: null
    summary: null
    evidence_refs: []

  audit:
    decision_refs:
      - "D-2811"
    immutable_event_refs:
      - "EV-990218"

---

4. Required Hypothesis Fields

The following fields SHOULD be treated as mandatory for nontrivial adaptations:

Field	Purpose
id	stable hypothesis identity
interface_id	owning interface
title	concise human-readable description
observation.summary	observed pressure
observation.evidence_refs	traceable evidence
pressure.classes	pressure taxonomy
explanation.claim	explanatory theory
proposed_adaptation	proposed response
expected_outcomes	measurable prediction
guardrails	non-negotiable constraints
complexity.expected_delta	complexity impact
risk.level	operational risk
success_criteria	evaluation condition
state	lifecycle state

---

5. Hypothesis Reach

explanation.reach MAY be used to compare hypotheses.

Suggested structure:

reach:
  score: 0.0        # implementation-defined scale
  explains:
    - "<pressure-id>"
  notes: "<why this hypothesis has broader explanatory power>"

Implementations SHOULD NOT equate reach with correctness.

---

6. Competing Hypotheses

A hypothesis MAY declare:

competition:
  group_id: "CG-0017"
  alternatives:
    - "H-000184"
    - "H-000185"
    - "H-000186"

A competition group represents multiple explanations or candidate designs for substantially the same pressure.

---

Part II — Revision Record

7. Revision Lifecycle

A revision may progress through:

CREATED
→ VERIFIED
→ EXPERIMENT
→ CANDIDATE
→ STABLE
→ DEPRECATED
→ RETIRED

A revision SHOULD be immutable once published.

State transitions SHOULD be recorded as events rather than rewriting history.

---

8. Revision Record

fluid_revision:
  schema_version: "0.1"

  id: "R-000221"
  interface_id: "customer-finance-api"

  revision_number: 22
  parent_revision: "R-000220"

  state: "CANDIDATE"

  created_at: "2026-09-04T13:10:00Z"
  created_by:
    type: "daimon"
    id: "fluid-daimon/customer-finance-api"

  contract:
    type: "openapi"
    version: "3.1"
    artifact_ref: "artifact:openapi/customer-finance-api/r22"
    digest: "sha256:<digest>"

  implementation:
    artifact_ref: "artifact:adapter/customer-finance-api/r22"
    source_ref: "git:<commit>"
    build_ref: "build:<id>"
    digest: "sha256:<digest>"

  interface_evolution_intent:
    version: "IEI-7"
    artifact_ref: "artifact:intent/customer-finance-api/IEI-7"

  originating_hypotheses:
    - "H-000184"

  backend_requirements:
    - id: null

  compatibility:
    class: "BACKWARD_COMPATIBLE"
    breaking_changes: []
    deprecations: []
    supersedes: []
    compatibility_evidence_refs:
      - "test:compat-suite-775"

  adaptation_classes:
    - "contract"

  verification:
    status: "PASSED"
    test_refs:
      - "test:unit-12081"
      - "test:contract-8821"
      - "test:security-610"
      - "test:compat-suite-775"
    security_check: "PASSED"
    policy_check: "PASSED"

  complexity:
    before:
      surface_area: 41
      operation_count: 39
    after:
      surface_area: 42
      operation_count: 40
    delta_score: 0.18
    budget_status: "WITHIN_BUDGET"

  deployment:
    environments:
      - name: "production"
        started_at: "2026-09-05T08:00:00Z"
        routing_policy_ref: "route-policy:rp-118"
    current_exposure:
      traffic_share: 0.28
      cohorts:
        - "partner-integrations"
        - "coding-agents"

  fitness:
    baseline_revision: "R-000220"
    measurement_window:
      start: "2026-09-05T08:00:00Z"
      end: null
    metrics:
      requests_per_completed_task:
        baseline: 2.7
        current: 1.15
        target: 1.2
      p95_latency_ms:
        baseline: 300
        current: 302
        guardrail: 315
      error_rate:
        baseline: 0.008
        current: 0.007

  adoption:
    eligible_consumers: 412
    active_consumers: 119
    adoption_rate: 0.289
    retained_adoption_rate: null

  economics:
    build_cost: 38.20
    experiment_cost_to_date: 12.40
    currency: "EUR"

  promotion:
    eligible: true
    recommended_state: "STABLE"
    recommendation_reason: >
      Target fitness reached with no guardrail violations.
    authorized_by: null
    authorized_at: null

  rollback:
    supported: true
    target_revision: "R-000220"
    procedure_ref: "runbook:rollback-r22"

  provenance:
    decision_refs:
      - "D-2811"
    experiment_refs:
      - "E-000093"
    telemetry_refs:
      - "telemetry:invoice-pattern-2026w36"

  audit:
    immutable_event_refs:
      - "EV-990221"
      - "EV-990244"
      - "EV-990281"

---

9. Required Revision Fields

A published revision SHOULD contain:

Field	Purpose
id	stable identity
interface_id	owning interface
revision_number	human-readable sequence
parent_revision	lineage
state	lifecycle state
contract	deterministic external semantics
implementation	adapter artifact
interface_evolution_intent	governing intent
originating_hypotheses	why it exists
compatibility	compatibility status
verification	release evidence
deployment	exposure
rollback	restoration path
provenance	audit chain

---

10. Compatibility Classes

Recommended values:

BACKWARD_COMPATIBLE
FORWARD_COMPATIBLE
ADDITIVE
BEHAVIORAL_CHANGE
BREAKING
MIGRATION_ONLY
INTERNAL_ONLY

An implementation MAY use multiple classes where necessary.

---

11. Revision States

Recommended states:

CREATED

Artifact exists but has not passed verification.

VERIFIED

Required verification passed.

EXPERIMENT

Revision is exposed only under experimental policy.

CANDIDATE

Revision is eligible for broader production evaluation.

STABLE

Revision is an accepted production interface.

DEPRECATED

Supported but scheduled or expected for retirement.

RETIRED

No longer exposed for normal traffic.

---

12. Experiment Record

A minimal experiment record SHOULD connect hypotheses and revisions.

fluid_experiment:
  schema_version: "0.1"

  id: "E-000093"
  interface_id: "customer-finance-api"

  hypothesis_refs:
    - "H-000184"

  control_revision: "R-000220"
  candidate_revisions:
    - "R-000221"

  cohorts:
    - "partner-integrations"
    - "coding-agents"

  allocation:
    control: 0.72
    candidate: 0.28

  start_at: "2026-09-05T08:00:00Z"
  planned_end_at: "2026-10-05T08:00:00Z"

  metrics:
    primary:
      - "requests_per_completed_task"
    guardrails:
      - "p95_latency_ms"
      - "error_rate"
      - "authorization_scope_change"

  stop_conditions:
    - "hard_guardrail_violation"
    - "security_failure"
    - "manual_stop"

  result:
    state: "RUNNING"
    preferred_revision: null
    evidence_refs: []

---

13. Pressure Record

A FLUID implementation SHOULD persist material interface-pressure observations.

fluid_pressure:
  schema_version: "0.1"

  id: "P-1831"
  interface_id: "customer-finance-api"

  class: "successful_but_inefficient_usage"

  first_seen: "2026-08-15T10:11:00Z"
  last_seen: "2026-09-01T12:15:00Z"

  affected_cohorts:
    - "partner-integrations"

  frequency:
    observations: 1740
    independent_consumers: 83

  summary: >
    Consumers repeatedly retrieve complete invoice collections
    to determine the latest invoice.

  evidence_refs:
    - "telemetry:query-pattern-712"

  status: "OPEN"

  linked_hypotheses:
    - "H-000184"

---

14. Backend Capability Requirement Record

fluid_backend_requirement:
  schema_version: "0.1"

  id: "BR-0041"
  originating_interface: "customer-context-api"
  originating_revision: "R-0081"
  originating_hypothesis: "H-0212"

  backend_service: "payments-service"

  capability:
    title: "Historical payment-state query"
    description: >
      Retrieve payment state as of a specified timestamp.

  semantics:
    consistency: "snapshot"
    required_fields:
      - "payment_id"
      - "state"
      - "effective_at"

  quality:
    p95_latency_ms: 250
    availability: 0.999

  security:
    authorization_scope: "payments.read"
    tenant_isolation: "required"

  expected_usage:
    requests_per_day: 120000

  disposition:
    state: "PLANNED"
    reason: null
    target_ref: "payments-service/roadmap#412"

---

15. Event-Sourced Audit Model

FLUID SHOULD preserve material lifecycle transitions as append-only audit events.

Example:

fluid_event:
  schema_version: "0.1"

  id: "EV-990281"
  occurred_at: "2026-09-09T11:31:02Z"

  entity_type: "revision"
  entity_id: "R-000221"

  event_type: "PROMOTION_RECOMMENDED"

  actor:
    type: "daimon"
    id: "fluid-daimon/customer-finance-api"

  inputs:
    - "H-000184"
    - "E-000093"

  reason: >
    Candidate met primary success target and violated no guardrails.

  evidence_refs:
    - "metrics:E-000093/window-4"

The audit event model is strongly recommended because FLUID evolution is itself a system behavior that must remain reconstructable.

---

16. Identifier Conventions

Recommended prefixes:

Artifact	Prefix
Hypothesis	H-
Revision	R-
Experiment	E-
Pressure	P-
Backend requirement	BR-
Decision	D-
Audit event	EV-
Feedback	F-
Consumer cohort	C-

Implementations MAY use UUIDs or other identifiers internally.

Human-readable prefixes are recommended for operational tooling.

---

17. Minimum Persistent Model

An early FLUID implementation can start with only:

Pressure
   ↓
Hypothesis
   ↓
Revision
   ↓
Experiment
   ↓
Outcome

The following minimum relationships SHOULD exist:

Pressure ──supports────► Hypothesis
Hypothesis ──creates───► Revision
Revision ──tested-by───► Experiment
Experiment ──measures─► Revision
Revision ──governed-by► InterfaceEvolutionIntent

This is sufficient to implement the first scientific adaptation loop without requiring the full future FLUID ecosystem.

---

18. Design Rule

The schema deliberately separates:

what we observed
what we think explains it
what we changed
what happened afterwards

These MUST NOT be collapsed into one AI-generated narrative.

Keeping them separate is fundamental to:

• criticism;
• auditability;
• competing hypotheses;
• rollback;
• learning;
• governance;
• reproducibility.

---

19. Initial Implementation Recommendation

For the first FLUID implementation, persist:

1. fluid_pressure;
2. fluid_hypothesis;
3. fluid_revision;
4. fluid_experiment;
5. fluid_event.

Add backend requirements only when cross-service evolution is implemented.

This yields a compact but complete foundation for a deterministic, hypothesis-driven FLUID control loop.