# 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:

```text
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

```yaml
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:

```yaml
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:

```yaml
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:

```text
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

```yaml
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:

```text
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.

```yaml
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.

```yaml
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

```yaml
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:

```yaml
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:

```text
Pressure
   ↓
Hypothesis
   ↓
Revision
   ↓
Experiment
   ↓
Outcome
```

The following minimum relationships SHOULD exist:

```text
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:

```text
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.