coulomb/fluid-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
fluid-core/spec/FluidHypothesisRevisionSchema.md
tegwick c2cfe86d88 Establish fluid-core scaffold, intent, and phased workplans 
Adds the repository structure, INTENT.md declaring the wire-contract
boundary, and seven workplans covering Blueprint Phases A-C plus the
fluid-telegram handover.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014KmVxhJ35tCo7rE7UnLwWu

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 1116572@bnt-lap001
Assistant-Session: 8ba9bb93-a72a-4883-b189-2499cce5c400
2026-09-04 01:49:12 +02:00

773 lines
15 KiB
Markdown
Executable file
Raw Blame History

# 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.
Reference in a new issue View git blame Copy permalink