diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..24bad2b --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +/bin/ +*.db +*.sqlite +.env diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..f6926ae --- /dev/null +++ b/INTENT.md @@ -0,0 +1,85 @@ +--- +project: fluid-core +product: FLUID +status: draft +intent_version: 0.1.0 +date: 2026-09-04 +standard: FluidAPIStandards +standard_version: 0.1.0 +--- + +# INTENT.md — fluid-core + +> **FLUID envisions interfaces that learn when they should change, why, how to +> test the change, and whether the result deserves to become part of their +> evolving contract.** + +## 1. Repository intent + +`fluid-core` exists to make FLUID — *Flow Utilizing Interface Daimon* — +executable. It is the reference framework for operating deterministic service +interfaces inside a governed evolutionary control loop. + +The framework's defining commitment is stated in `spec/FluidAPIStandards.md` §3: + +> **Deterministic execution, adaptive evolution.** + +The production request path stays deterministic and auditable. Observation, +analysis, hypothesis formation, experimentation and promotion happen *around* +the interface, never inside the request path. + +## 2. What this repository owns + +- the deterministic data plane: gateway, revision resolver, revision router, + contract validation, backend connectors, response policy, telemetry emission; +- the observation plane: telemetry ingest, redaction, cohorts, interaction + topology, pressure classification; +- the evolution control plane through Blueprint Phase C: pressure registry, + hypothesis records, experiment control, fitness evaluation, promotion + decisions; +- the evidence, artifact and intent stores; +- the wire contract by which any interface, in any language, becomes FLUID. + +## 3. What this repository does not own + +- the interfaces themselves — those live in consumer repositories + (`fluid-telegram`, `fluid-x`, `fluid-substack`); +- backend systems reached through connectors; +- the Daimon's generative capability (Blueprint Phase D), deliberately deferred + until real telemetry exists for it to learn from. + +## 4. The boundary is a wire contract + +fluid-core is integrated **out of process**. A target API contributes no code, +imports no library, and may be written in any stack. Integration happens through +four artifacts: + +1. the revision descriptor (Blueprint §36); +2. the routing policy (Blueprint §17); +3. the telemetry envelope; +4. the control APIs (Blueprint §44). + +Any change that leaks Go types across this boundary is a design failure. This +constraint is what allows adapters, Daimons and future gateways to be written in +whatever language suits them. + +## 5. Governing invariants + +The sixteen architectural invariants in `spec/ArchitectureBlueprint.md` §55 are +constitutional for this repository. The four that most often get eroded and must +be defended hardest: + +- **Runtime behavior remains deterministic.** No LLM in the mandatory request path. +- **Evolution can stop without stopping the API.** Every control-plane component + must be killable in production with no runtime effect. +- **AI-generated artifacts are untrusted until verified.** The deterministic + policy gate is not advisory. +- **Backend authority does not leak into the interface Daimon.** Missing backend + capability is escalated as a structured requirement, never taken. + +## 6. Success + +`fluid-core` succeeds when an interface owner can put an existing API behind it +without modifying that API, and then answer — from evidence, months later — the +eleven auditability questions in `spec/FluidAPIStandards.md` §25 about any change +the interface underwent. diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..c33a0cd --- /dev/null +++ b/go.mod @@ -0,0 +1,3 @@ +module github.com/tegwick/fluid-core + +go 1.22.2 diff --git a/history/260820-ideaFluidInterfaces.md b/history/260820-ideaFluidInterfaces.md new file mode 100644 index 0000000..d83dd6d --- /dev/null +++ b/history/260820-ideaFluidInterfaces.md @@ -0,0 +1,14 @@ +Fluid interfaces is a framework to establish a dynamic adaptive interface between services +that integrates self healing and self optimization based on interface telemetrie. + +FLUID stands for FlowUtilizingInterfaceDaemon. + +The idea is about having an actively developing interface that learns and evolves from mesuring +interface usage and responsibility. + +The interface can implent REST, GRAPH or other API flavors and functions as a classic deterministic +API but on error or detection of missing functionality can trigger AI review, planning of the missing +endpoints or endpoint extensions connecting them to backend implementation or even requesting new +backend implementation. + + diff --git a/spec/ArchitectureBlueprint.md b/spec/ArchitectureBlueprint.md new file mode 100755 index 0000000..258a64b --- /dev/null +++ b/spec/ArchitectureBlueprint.md @@ -0,0 +1,2362 @@ +# FLUID Architecture Blueprint + +**Document:** `ArchitectureBlueprint.md` +**Version:** 0.1.0 +**Status:** Initial Architecture Blueprint +**Framework:** FLUID — Flow Utilizing Interface Daimon +**Companions:** `FluidAPIStandards.md`, `InterfaceEvolutionIntent.md`, `FluidHypothesisRevisionSchema.md` + +--- + +# 1. Purpose + +This document translates the FLUID API Standards into an implementable architecture. + +The blueprint defines how to build a system in which: + +- the exposed API remains deterministic; +- multiple API revisions can coexist; +- usage is observed continuously; +- interface pressure is derived from telemetry and explicit feedback; +- hypotheses are created and evaluated scientifically; +- candidate revisions can be generated and deployed safely; +- adaptation authority remains bounded; +- backend capability gaps are escalated rather than silently crossed; +- every evolutionary decision is auditable; +- adaptive intelligence may stop without interrupting normal API operation. + +The architecture is intentionally modular. + +A minimal FLUID deployment should be useful with only telemetry and revision identity. More advanced analysis, experimentation, construction, and autonomous optimization can be added incrementally. + +--- + +# 2. Architectural Thesis + +The central architectural separation is: + +```text + EVOLUTION PLANE + probabilistic where useful + analytical, scientific, adaptive + │ + │ controlled change + ▼ +CLIENT ─────────► DETERMINISTIC INTERFACE ─────────► BACKENDS + DATA PLANE + │ + │ telemetry + ▼ + OBSERVATION +``` + +The production request path and the evolutionary control loop are distinct systems. + +The interface runtime MUST continue to function if: + +- the Daimon is unavailable; +- the model provider is unavailable; +- telemetry processing is delayed; +- the hypothesis store is unavailable; +- the experiment controller is paused; +- the AI budget is exhausted. + +This isolation is one of the most important FLUID architectural invariants. + +--- + +# 3. Architectural Planes + +FLUID is organized into five primary planes. + +```text +┌────────────────────────────────────────────────────────────┐ +│ 1. CONSUMER PLANE │ +│ humans · applications · services · agents · partners │ +└────────────────────────────┬───────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────┐ +│ 2. INTERFACE DATA PLANE │ +│ gateway · revision router · deterministic adapters │ +│ schemas · validation · auth context · response handling │ +└─────────────┬──────────────────────────────────────┬───────┘ + │ │ + │ telemetry │ calls + ▼ ▼ +┌─────────────────────────────┐ ┌───────────────────┐ +│ 3. OBSERVATION PLANE │ │ BACKEND SERVICES │ +│ events · metrics · traces │ │ independent intent │ +│ cohorts · feedback │ │ & responsibility │ +└─────────────┬───────────────┘ └─────────┬─────────┘ + │ │ + ▼ │ requirements +┌──────────────────────────────────────────────────┴─────────┐ +│ 4. EVOLUTION CONTROL PLANE │ +│ pressure engine · hypothesis engine · Daimon · fitness │ +│ experiment controller · optimization policy · promotion │ +└────────────────────────────┬───────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────┐ +│ 5. EVIDENCE & ARTIFACT PLANE │ +│ revisions · hypotheses · experiments · events · builds │ +│ contracts · tests · provenance · intent · requirements │ +└────────────────────────────────────────────────────────────┘ +``` + +Each plane has a distinct responsibility and failure model. + +--- + +# 4. Consumer Plane + +The Consumer Plane contains all actors using the interface. + +Examples: + +- human developers; +- browser applications; +- mobile applications; +- internal services; +- partner integrations; +- legacy systems; +- coding agents; +- autonomous operational agents. + +The Consumer Plane is not trusted merely because its behavior is observable. + +Consumer behavior produces evidence, not authority. + +Consumers MAY additionally provide structured FLUID feedback such as: + +```yaml +goal: retrieve latest invoice +attempt: GET /customers/4711/invoices/latest +outcome: unavailable +workaround: query-all-sort-locally +impact: additional calls and client complexity +``` + +Explicit feedback enters the Observation Plane and is evaluated alongside implicit telemetry. + +--- + +# 5. Interface Data Plane + +The Interface Data Plane is the deterministic execution environment. + +It contains: + +1. Edge Gateway +2. Revision Resolver +3. Revision Router +4. Contract Validator +5. Deterministic Adapter Runtime +6. Backend Connector Layer +7. Response Policy +8. Telemetry Emitter + +The Data Plane MUST NOT require the Evolution Plane for ordinary request processing. + +--- + +## 5.1 Edge Gateway + +The Edge Gateway receives interface traffic. + +Responsibilities: + +- transport termination; +- protocol handling; +- authentication handoff; +- request correlation; +- coarse rate limiting; +- request size and shape limits; +- deterministic security enforcement; +- forwarding to the Revision Resolver. + +The gateway MUST NOT dynamically invent interface semantics. + +--- + +## 5.2 Revision Resolver + +The Revision Resolver determines which published revision applies to a request. + +Inputs MAY include: + +- explicit API version; +- URL version; +- protocol negotiation; +- client contract binding; +- cohort assignment; +- experiment assignment; +- tenant policy; +- migration state. + +Example: + +```text +request + │ + ├─ explicit revision? ──────────────► use requested revision if allowed + │ + ├─ bound client contract? ──────────► use bound revision + │ + ├─ active experiment assignment? ──► use experiment revision + │ + └─ otherwise ──────────────────────► stable default revision +``` + +Revision resolution MUST be deterministic and auditable. + +--- + +## 5.3 Revision Router + +The Revision Router maps the resolved revision to a deterministic adapter implementation. + +Example: + +```text +R-41 ──► adapter-image:41 +R-42 ──► adapter-image:42 +R-43 ──► adapter-image:43 +``` + +The router MUST reject routing to: + +- unpublished revisions; +- failed revisions; +- revisions not allowed for the consumer; +- retired revisions unless explicitly supported by migration policy. + +Traffic allocation MAY be percentage-based, cohort-based, tenant-based, or explicitly opt-in. + +The allocation rule itself MUST be deterministic. + +--- + +## 5.4 Contract Validator + +Each revision MUST have an identifiable contract. + +The validator may enforce: + +- request shape; +- field types; +- required parameters; +- enum constraints; +- protocol semantics; +- compatibility constraints; +- response shape. + +Supported contract forms MAY include: + +- OpenAPI; +- GraphQL schema; +- protobuf; +- AsyncAPI; +- JSON Schema; +- custom deterministic interface specifications. + +The contract is part of the revision artifact and SHOULD be content-addressed. + +--- + +## 5.5 Deterministic Adapter Runtime + +This is the core implementation of each revision. + +Responsibilities MAY include: + +- field mapping; +- protocol translation; +- backend composition; +- validation; +- transformation; +- aggregation; +- pagination; +- caching; +- batching; +- deterministic fallback; +- error normalization. + +The runtime MUST NOT require an LLM to determine the meaning of an ordinary API request. + +Agentic generation may have created the adapter earlier, but the deployed artifact behaves deterministically. + +--- + +## 5.6 Backend Connector Layer + +Backend connectors isolate protocol and dependency details. + +A connector SHOULD define: + +- backend identity; +- capability contract; +- authentication mechanism; +- timeout policy; +- retry policy; +- circuit-breaker behavior; +- expected quality constraints; +- tenant propagation rules; +- error mapping. + +The interface may compose multiple backend services. + +The connector layer does not grant FLUID authority to modify those services. + +--- + +## 5.7 Response Policy + +The Response Policy standardizes interface behavior for: + +- success; +- validation error; +- authorization failure; +- unavailable backend; +- unsupported operation; +- missing capability; +- deprecated capability. + +Errors SHOULD contain enough structured information to improve observability without leaking sensitive backend details. + +Errors MAY include a FLUID correlation reference that allows downstream analysis of interface pressure. + +--- + +# 6. Observation Plane + +The Observation Plane converts runtime interaction into evidence. + +It contains: + +1. Telemetry Ingest +2. Event Normalizer +3. Privacy / Redaction Filter +4. Interaction Topology Analyzer +5. Consumer Cohort Engine +6. Explicit Feedback Collector +7. Pressure Classifier +8. Observation Store + +--- + +## 6.1 Telemetry Sources + +FLUID SHOULD support: + +### Request events + +- route; +- revision; +- operation; +- status; +- latency; +- payload size; +- caller cohort; +- correlation ID. + +### Error events + +- validation failures; +- unknown path; +- unknown field; +- unsupported parameter; +- authorization failure; +- backend failure; +- timeout; +- policy rejection. + +### Sequence events + +- call chains; +- repeated round trips; +- fallback behavior; +- compensating requests. + +### Adoption events + +- revision first use; +- revision continued use; +- migration; +- reversion; +- deprecation response. + +### Explicit feedback + +- intended goal; +- attempted operation; +- workaround; +- desired capability; +- impact. + +--- + +## 6.2 Telemetry Boundary + +Telemetry SHOULD be designed for interface learning without becoming unrestricted behavioral capture. + +The Observation Plane MUST provide deterministic controls for: + +- redaction; +- field exclusion; +- tenant isolation; +- retention; +- pseudonymization; +- aggregation; +- cohort minimum sizes; +- sensitive-data handling. + +Raw payload capture SHOULD NOT be the default. + +Semantic learning SHOULD rely on minimized evidence where possible. + +--- + +## 6.3 Consumer Cohort Engine + +The Cohort Engine groups consumers into analytically useful populations. + +A cohort may be based on: + +- declared client type; +- SDK; +- contract version; +- protocol; +- tenant class; +- organization; +- automation level; +- usage pattern; +- commercial plan. + +Cohorts SHOULD be stable enough to compare over time. + +Cohorts SHOULD NOT be more granular than necessary. + +Example: + +```text +C-17: human-developer / REST / SDK-python +C-22: autonomous-agent / tool-protocol +C-31: legacy-partner / API-v1 +``` + +--- + +## 6.4 Interaction Topology Analyzer + +The analyzer looks beyond individual requests. + +It detects recurring patterns such as: + +```text +GET customer +GET invoices +GET payments +GET contracts +``` + +or: + +```text +GET invoices +sort locally +discard N-1 records +``` + +or: + +```text +invalid request +schema lookup +retry with corrected request +``` + +These interaction topologies are often more informative than simple error counts. + +--- + +## 6.5 Pressure Classifier + +The classifier maps evidence into FLUID pressure classes. + +Initial classes: + +```text +NATURAL_USAGE +INEFFICIENT_USAGE +RECOVERABLE_MISUNDERSTANDING +EXPECTATION_MISMATCH +POOR_DISCOVERABILITY +MISSING_INTERFACE_CAPABILITY +MISSING_BACKEND_CAPABILITY +OUT_OF_SCOPE_DEMAND +PROHIBITED_DEMAND +IMPLEMENTATION_FAILURE +``` + +Classification MAY use deterministic heuristics, statistical models, agentic reasoning, or a combination. + +The resulting pressure record MUST retain evidence references. + +--- + +# 7. Evolution Control Plane + +The Evolution Control Plane is where the Daimon operates. + +It contains: + +1. Pressure Registry +2. Hypothesis Engine +3. Hypothesis Competition Manager +4. Optimization Policy +5. Complexity Evaluator +6. Candidate Planner +7. Builder +8. Verification Controller +9. Experiment Controller +10. Fitness Evaluator +11. Promotion Controller +12. Migration Controller +13. Backend Requirement Broker +14. Evolution Velocity Controller +15. Daimon Orchestrator + +--- + +# 8. Daimon Orchestrator + +The Daimon Orchestrator coordinates evolutionary work. + +It does not need to be a single process or agent. + +A practical implementation may use: + +- deterministic workflow engine; +- event-driven controller; +- queue workers; +- LLM agents; +- CI/CD pipelines; +- human approval steps. + +The Daimon SHOULD be understood as a logical role rather than one monolithic AI process. + +Example orchestration: + +```text +Pressure event + ↓ +deterministic eligibility rules + ↓ +agentic analysis + ↓ +hypothesis persisted + ↓ +policy evaluation + ↓ +candidate generation + ↓ +deterministic tests + ↓ +bounded experiment + ↓ +metrics + ↓ +fitness evaluation + ↓ +promotion recommendation +``` + +--- + +# 9. Pressure Registry + +The Pressure Registry is the durable inventory of material interface pressure. + +It SHOULD support: + +- deduplication; +- aggregation; +- cohort segmentation; +- frequency tracking; +- severity; +- confidence; +- linked hypotheses; +- disposition. + +Example lifecycle: + +```text +OPEN +→ ANALYZING +→ EXPLAINED +→ ADDRESSED +→ DISMISSED +→ OUT_OF_SCOPE +``` + +Pressure MAY remain unresolved intentionally. + +Not every observed mismatch deserves adaptation. + +--- + +# 10. Hypothesis Engine + +The Hypothesis Engine converts pressure into explicit explanations and proposed changes. + +Every nontrivial candidate SHOULD derive from a hypothesis. + +The engine SHOULD separate: + +```text +Observation +Explanation +Prediction +Intervention +Result +``` + +This prevents reasoning from becoming self-validating. + +--- + +## 10.1 Hypothesis Generation + +Inputs MAY include: + +- pressure records; +- interface contract; +- `InterfaceEvolutionIntent.md`; +- current revision topology; +- backend capability contracts; +- consumer cohorts; +- historical experiments; +- complexity state; +- optimization preference; +- economic budget. + +Output is a structured hypothesis record. + +--- + +## 10.2 Hypothesis Reach + +The engine SHOULD estimate how many observations a hypothesis explains. + +Example: + +```text +H-A: add /latest endpoint +explains pressures P1, P2 + +H-B: introduce customer financial context abstraction +explains P1, P2, P3, P4, P5 +``` + +Higher reach may justify exploration even where implementation cost is higher. + +Reach MUST NOT replace empirical validation. + +--- + +## 10.3 Competing Hypotheses + +Multiple hypotheses SHOULD be allowed to coexist. + +The system SHOULD be able to form competition groups: + +```text +Pressure cluster PC-81 + ├─ H-100: documentation improvement + ├─ H-101: convenience endpoint + └─ H-102: new resource abstraction +``` + +The competition manager helps decide which candidates deserve experimentation. + +--- + +# 11. Optimization Policy + +The Optimization Policy defines what "better" currently means. + +Inputs include: + +- `InterfaceEvolutionIntent.md`; +- operator tuning; +- automatic recommendation; +- current operational regime; +- risk posture; +- economic budget. + +Example: + +```yaml +regime: CONSOLIDATION + +weights: + simplicity: high + maintainability: high + client_utility: medium + performance: medium + cost: medium + +hard_guardrails: + security_regression: false + compatibility_break_without_revision: false +``` + +Automatic recommendations SHOULD eventually become normal, but the active policy MUST remain explicit and inspectable. + +--- + +# 12. Complexity Evaluator + +The Complexity Evaluator measures candidate impact. + +Standard dimensions: + +- surface area; +- concept count; +- operation count; +- parameter dimensionality; +- semantic overlap; +- alternative-path count; +- dependency count; +- backend composition count; +- exception count; +- active revision count; +- cognitive load. + +Implementations define their own scoring. + +The evaluator MUST distinguish: + +```text +useful capability growth +``` + +from: + +```text +uncontrolled interface accretion +``` + +The evaluator SHOULD trigger an abstraction review when repeated local fixes accumulate. + +--- + +# 13. Candidate Planner + +The Candidate Planner converts an accepted hypothesis into an implementation plan. + +A plan SHOULD define: + +- affected revision; +- adaptation class; +- target contract change; +- adapter change; +- required backend capabilities; +- tests; +- expected fitness effects; +- rollout strategy; +- rollback strategy; +- experiment design; +- complexity impact. + +If required backend capability is unavailable, candidate construction SHOULD stop at a proposed interface plus structured backend requirement. + +--- + +# 14. Builder + +The Builder constructs candidate artifacts. + +It MAY generate: + +- OpenAPI changes; +- GraphQL schema changes; +- adapter code; +- routing configuration; +- tests; +- documentation; +- migration notes; +- examples. + +The Builder MAY be heavily agentic. + +Generated output MUST pass deterministic verification. + +The Builder MUST NOT deploy merely because generation succeeded. + +--- + +# 15. Verification Controller + +Verification is the primary safety barrier between adaptive generation and deterministic runtime. + +It SHOULD run: + +### Contract tests + +Does implementation match the declared contract? + +### Regression tests + +Does the candidate preserve required prior behavior? + +### Security tests + +Are authorization and tenancy constraints preserved? + +### Backend contract tests + +Are backend assumptions valid? + +### Performance tests + +Does the candidate remain inside guardrails? + +### Complexity checks + +Does the candidate exceed its budget? + +### Static policy checks + +Does it violate prohibited interface or governance rules? + +Only verified candidates may become experimental revisions. + +--- + +# 16. Experiment Controller + +The Experiment Controller exposes verified candidates under bounded conditions. + +Supported mechanisms MAY include: + +- sandbox; +- shadow traffic; +- synthetic traffic; +- replay; +- canary; +- explicit opt-in; +- cohort allocation; +- tenant allocation; +- percentage rollout. + +Experiments MUST declare: + +- hypothesis; +- control revision; +- candidate revision; +- eligible cohorts; +- allocation; +- metrics; +- guardrails; +- start condition; +- stop condition; +- maximum duration. + +Experiments MUST be interruptible. + +--- + +# 17. Revision Router and Experiment Controller Interaction + +The Experiment Controller does not directly process traffic. + +It writes deterministic routing policy consumed by the Revision Router. + +Example: + +```yaml +routing_policy: + interface: customer-finance-api + + default_revision: R-41 + + rules: + - cohort: coding-agents + experiment: E-19 + allocation: + R-41: 0.80 + R-42: 0.20 +``` + +This separation keeps experimental intent out of the runtime decision mechanism. + +--- + +# 18. Fitness Evaluator + +The Fitness Evaluator compares revisions against explicit hypotheses. + +It SHOULD distinguish: + +### Primary metrics + +The outcomes the hypothesis predicts. + +### Guardrails + +Metrics that must not regress beyond allowed thresholds. + +### Secondary metrics + +Useful observations not central to the decision. + +### Learning metrics + +Signals that improve future hypothesis formation. + +The evaluator MUST retain the baseline and measurement window. + +It SHOULD NOT retroactively change success criteria after seeing results without recording the amendment. + +--- + +# 19. Promotion Controller + +The Promotion Controller decides whether a candidate may progress. + +Possible outcomes: + +```text +PROMOTE +EXPAND_EXPERIMENT +RETAIN_AS_OPTION +MODIFY +REVERT +ABANDON +DEFER +``` + +The decision MAY be: + +- human; +- deterministic policy; +- agent recommendation plus human approval; +- bounded autonomous. + +The applicable FLUID authority mode determines who or what may authorize promotion. + +--- + +# 20. Migration Controller + +The Migration Controller implements the transition from versioned evolution toward managed migration. + +It tracks: + +- revision adoption; +- cohort migration; +- clients pinned to old revisions; +- deprecation state; +- compatibility blockers; +- migration communication; +- retirement eligibility. + +Example lifecycle: + +```text +R-41 STABLE + │ + ├─ R-42 introduced + │ + ├─ migration guidance published + │ + ├─ default changed to R-42 + │ + ├─ R-41 deprecated + │ + └─ R-41 retired when policy allows +``` + +The controller SHOULD avoid forced migration where evidence or contractual constraints argue against it. + +--- + +# 21. Backend Requirement Broker + +When the interface needs capability outside its responsibility boundary, the Requirement Broker creates an explicit request. + +Flow: + +```text +Hypothesis + ↓ +Candidate design + ↓ +missing backend capability + ↓ +Backend Requirement + ↓ +backend disposition + ├─ AVAILABLE + ├─ ACCEPTED + ├─ PLANNED + ├─ PARTIALLY_AVAILABLE + ├─ OUT_OF_SCOPE + ├─ REJECTED + └─ SUPERSEDED +``` + +The requirement MUST retain: + +- originating hypothesis; +- intended interface; +- expected usage; +- quality requirements; +- security requirements; +- semantic requirements. + +Repeated `OUT_OF_SCOPE` responses SHOULD feed Boundary Learning. + +--- + +# 22. Boundary Learning + +Boundary Learning asks whether recurring demand indicates: + +- misunderstanding; +- weak presentation; +- missing neighboring service; +- wrong interface composition; +- incorrect interface intent; +- genuinely out-of-scope demand. + +The Daimon MAY propose changes to `InterfaceEvolutionIntent.md`. + +Intent changes require a separate governance process. + +The Daimon MUST NOT silently expand its own mission. + +--- + +# 23. Evolution Velocity Controller + +The Evolution Velocity Controller manages the pace of adaptation. + +Inputs MAY include: + +- experiment success rate; +- regression frequency; +- reliability; +- open incidents; +- consumer adoption; +- backlog pressure; +- economic budget; +- human review capacity; +- complexity trend. + +Example policy: + +```text +high experiment success ++ low incident rate ++ budget available +→ increase experiment concurrency + +rising regressions +→ reduce concurrency + +security incident +→ freeze autonomous promotion + +high uncertainty +→ increase observation before construction +``` + +Evolution velocity is therefore part of system control rather than a project-management afterthought. + +--- + +# 24. Evidence and Artifact Plane + +FLUID evolution depends on durable artifacts. + +The initial model SHOULD contain: + +```text +Pressure +Hypothesis +Revision +Experiment +Event +``` + +Later additions MAY include: + +```text +Feedback +Decision +Backend Requirement +Cohort +Optimization Policy +Complexity Snapshot +Migration +``` + +Artifacts SHOULD be immutable or event-sourced where practical. + +--- + +# 25. Artifact Store + +The Artifact Store contains build outputs: + +- API contracts; +- adapter source; +- container images; +- test reports; +- schema diffs; +- migration documentation; +- generated examples. + +Artifacts SHOULD be content-addressed or digest-verified. + +A revision MUST be reproducibly associated with the artifacts that implement it. + +--- + +# 26. Evidence Store + +The Evidence Store contains: + +- pressure observations; +- telemetry references; +- hypotheses; +- experiments; +- fitness results; +- decisions; +- audit events; +- backend dispositions. + +The Evidence Store SHOULD favor append-only history. + +Mutable summary views MAY be derived from immutable events. + +--- + +# 27. Intent Store + +The system MUST retain the exact interface evolution intent governing each revision. + +A revision therefore references: + +```text +revision → InterfaceEvolutionIntent version +``` + +This allows later audit to answer: + +> Was this change valid under the intent that existed when it was made? + +--- + +# 28. Security Architecture + +FLUID assumes that generated or adaptive behavior is untrusted until verified. + +Security is layered. + +```text +AI / Daimon suggestion + ↓ +candidate artifact + ↓ +deterministic policy + ↓ +verification + ↓ +signed revision + ↓ +revision router + ↓ +deterministic runtime enforcement +``` + +The Daimon MUST NOT possess unrestricted production credentials merely because it can generate code. + +--- + +## 28.1 Security Boundaries + +At minimum: + +### Runtime identity + +The deployed adapter receives only the credentials required for its declared backend calls. + +### Daimon identity + +The Daimon receives only the authority needed for its operational mode. + +### Builder identity + +May write candidate artifacts but SHOULD NOT imply promotion rights. + +### Experiment Controller identity + +May alter bounded routing policy only within declared limits. + +### Promotion authority + +Separate from code-generation authority where possible. + +### Evidence writer + +May append audit events but SHOULD NOT rewrite prior history. + +--- + +## 28.2 Deterministic Policy Gate + +Every candidate promotion MUST pass deterministic gates. + +Examples: + +- allowed adaptation class; +- permitted operational mode; +- complexity threshold; +- security status; +- test status; +- compatibility status; +- traffic-allocation maximum; +- economic budget; +- approval requirement. + +This gate is the architectural boundary preventing agentic reasoning from becoming security policy. + +--- + +# 29. Economic Architecture + +FLUID needs explicit cost accounting. + +The system SHOULD measure: + +```text +telemetry cost +analysis cost +LLM cost +build cost +test cost +experiment cost +parallel revision cost +human review cost +migration cost +``` + +A hypothesis may be valuable but not economically worth exploring yet. + +The Daimon SHOULD therefore support decisions such as: + +```text +observe longer +defer analysis +use cheaper model +reuse prior experiment +limit candidate count +stop low-value experiment +``` + +--- + +# 30. Adaptive Compute Governor + +A dedicated governor SHOULD enforce: + +- daily analysis budget; +- per-interface budget; +- per-hypothesis budget; +- maximum concurrent construction jobs; +- maximum concurrent experiments; +- model class restrictions; +- token / inference limits. + +Budget exhaustion pauses adaptation, not runtime service. + +--- + +# 31. Recommended Service Decomposition + +A reference implementation may begin with the following services. + +```text +fluid-gateway +fluid-revision-router +fluid-adapter-runtime + +fluid-telemetry-ingest +fluid-pressure-engine +fluid-cohort-engine + +fluid-daimon +fluid-hypothesis-engine +fluid-policy-engine +fluid-complexity-engine + +fluid-builder +fluid-verifier +fluid-experiment-controller +fluid-fitness-engine +fluid-promotion-controller +fluid-migration-controller + +fluid-backend-requirement-broker + +fluid-evidence-store +fluid-artifact-store +fluid-intent-store +fluid-event-log +``` + +This is a logical decomposition. + +The first implementation SHOULD combine components aggressively where that reduces operational complexity. + +--- + +# 32. Minimal Reference Implementation + +The first useful FLUID implementation does not require the full architecture. + +## Phase A — FLUID Core + +Implement: + +```text +Gateway +Revision Router +Adapter Runtime +Telemetry Ingest +Evidence Store +Intent Store +``` + +Capabilities: + +- deterministic revisions; +- revision identity; +- telemetry; +- auditable deployments; +- `InterfaceEvolutionIntent.md`. + +No AI is required. + +--- + +## Phase B — FLUID Insight + +Add: + +```text +Pressure Engine +Cohort Engine +Fitness Engine +``` + +Capabilities: + +- pressure detection; +- cohort analysis; +- revision fitness comparison; +- explicit feedback. + +This is the first genuinely adaptive-observation layer. + +--- + +## Phase C — FLUID Science + +Add: + +```text +Hypothesis Engine +Experiment Controller +Event Log +``` + +Capabilities: + +- explicit hypotheses; +- competing hypotheses; +- controlled experiments; +- scientific outcome evaluation. + +At this point FLUID can improve through evidence even if implementation remains human-driven. + +--- + +## Phase D — FLUID Builder + +Add: + +```text +Daimon +Builder +Verifier +Backend Requirement Broker +``` + +Capabilities: + +- AI-assisted candidate design; +- generated adapters; +- generated tests; +- structured backend requirements. + +Human approval may still control all promotion. + +--- + +## Phase E — FLUID Managed Evolution + +Add: + +```text +Promotion Controller +Migration Controller +Optimization Policy +Evolution Velocity Controller +``` + +Capabilities: + +- concurrent revisions; +- automatic recommendations; +- adoption-aware migration; +- policy-bounded rollout. + +--- + +## Phase F — FLUID Bounded Autonomy + +Add: + +```text +Autonomous promotion rules +Adaptive compute governor +Automated regime recommendation +``` + +Capabilities: + +- bounded autonomous improvement; +- automatic experiment scheduling; +- automatic optimization within intent. + +--- + +# 33. Example End-to-End Flow + +Consider a REST interface exposing invoice data. + +Current contract: + +```text +GET /customers/{id}/invoices +``` + +Consumers repeatedly: + +1. retrieve all invoices; +2. sort them; +3. select the newest one. + +The FLUID loop becomes: + +```text +1. Telemetry records repeated sequence. +2. Cohort engine finds pattern across independent consumers. +3. Pressure engine classifies INEFFICIENT_USAGE. +4. Hypothesis engine creates: + "latest invoice is a first-class consumer concept." +5. Complexity engine estimates low added complexity. +6. Candidate planner proposes: + GET /customers/{id}/invoices/latest +7. Backend capability check confirms existing data is sufficient. +8. Builder generates contract + adapter + tests. +9. Verifier confirms: + no security expansion, + no compatibility break, + latency inside guardrails. +10. Revision R-42 is created. +11. Experiment E-19 exposes R-42 to 20% of eligible consumers. +12. Fitness engine measures requests/task drop from 2.7 to 1.1. +13. No guardrail violation occurs. +14. Promotion controller recommends STABLE. +15. R-42 becomes preferred revision. +16. Adoption continues to be measured. +17. Historical evidence remains available for audit. +``` + +The runtime request path never required AI inference. + +--- + +# 34. Failure Containment + +FLUID MUST be designed so evolutionary failure does not imply runtime failure. + +--- + +## 34.1 Daimon Failure + +Effect: + +```text +no new hypotheses or adaptations +``` + +Runtime effect: + +```text +none +``` + +--- + +## 34.2 Telemetry Pipeline Failure + +Effect: + +```text +reduced learning +``` + +Runtime effect: + +```text +none, except optional observability degradation +``` + +Telemetry backpressure MUST NOT block normal API requests. + +--- + +## 34.3 Builder Failure + +Effect: + +```text +candidate not produced +``` + +Runtime effect: + +```text +none +``` + +--- + +## 34.4 Verification Failure + +Effect: + +```text +candidate rejected +``` + +Runtime effect: + +```text +none +``` + +--- + +## 34.5 Experiment Failure + +Effect: + +```text +candidate traffic removed +``` + +Runtime response: + +```text +route to known-good revision +``` + +--- + +## 34.6 Evolution Store Failure + +Runtime MUST continue using cached / published revision configuration. + +No new promotions should occur until control-plane consistency is restored. + +--- + +## 34.7 AI Budget Exhaustion + +Effect: + +```text +adaptive processes pause or degrade +``` + +Runtime effect: + +```text +none +``` + +--- + +# 35. Revision Publication Model + +A revision SHOULD progress through a controlled publication pipeline. + +```text +SOURCE + ↓ +BUILD + ↓ +CONTRACT CHECK + ↓ +TEST + ↓ +SECURITY CHECK + ↓ +POLICY CHECK + ↓ +SIGN + ↓ +PUBLISH + ↓ +ROUTE +``` + +The Revision Router SHOULD only accept signed or otherwise authenticated published revision descriptors. + +--- + +# 36. Revision Descriptor + +A runtime-friendly descriptor MAY look like: + +```yaml +revision: + id: R-42 + interface: customer-finance-api + state: candidate + + contract: + digest: sha256:... + + runtime: + image: registry/fluid/customer-finance:R-42 + digest: sha256:... + + intent: + version: IEI-7 + + routing: + eligible_cohorts: + - partner-integrations + - coding-agents + max_traffic_share: 0.30 + + policy: + compatibility: additive + security_check: passed + rollback_to: R-41 +``` + +This descriptor is deliberately small enough to be consumed deterministically by runtime infrastructure. + +--- + +# 37. Interface Description and Discoverability + +Presentation adaptation is one of the safest FLUID improvement areas. + +The architecture SHOULD separate: + +```text +semantic contract +documentation +examples +discovery metadata +client guidance +``` + +This permits FLUID to experiment with improved presentation without altering API semantics. + +Presentation experiments may become an early high-value use case because they: + +- preserve deterministic behavior; +- have low compatibility risk; +- generate rich adoption data; +- improve expectation management. + +--- + +# 38. Agentic Consumer Integration + +Agentic consumers can provide richer interface evidence than conventional applications. + +A FLUID-aware agent MAY report: + +```yaml +goal: produce monthly account statement +missing_capability: consolidated-period-summary +attempted_operations: + - list-transactions + - get-balances +workaround: + - aggregate-locally + - infer-closing-balance +confidence: 0.94 +impact: + calls: 18 + latency_ms: 2810 +``` + +This SHOULD be treated as explicit evidence, not privileged instruction. + +The architecture SHOULD avoid allowing an agent consumer to directly trigger autonomous production changes. + +--- + +# 39. Commercialization Extension Points + +Consumer cohorts and revision fitness may later support commercial models. + +Potential extension points include: + +- premium revision access; +- accelerated feature experiments; +- cohort-specific optimization; +- partner-specific compatibility windows; +- SLA-specific revision policies; +- paid high-cost capabilities; +- sponsored capability development. + +Commercial policy MUST remain separate from core interface truth and security policy. + +The system MUST NOT distort telemetry interpretation merely because a cohort is commercially valuable. + +--- + +# 40. Observability for the Evolution System + +FLUID must observe itself. + +Operational metrics SHOULD include: + +```text +open pressure count +pressure age +hypotheses created +hypothesis acceptance rate +candidate build success +verification failure rate +experiment success rate +rollback rate +revision adoption +migration duration +complexity trend +AI cost +cost per accepted improvement +time from pressure to validated adaptation +``` + +These metrics describe the fitness of the FLUID process itself. + +--- + +# 41. Meta-Optimization + +Once sufficient operational history exists, FLUID MAY optimize its own evolution process. + +Examples: + +- which telemetry produces useful hypotheses; +- which pressure classes justify AI analysis; +- which models work best for different tasks; +- how long experiments need to run; +- which cohorts provide useful early signal; +- which types of changes deserve automatic promotion. + +Meta-optimization MUST remain within the same auditability and policy constraints as interface optimization. + +FLUID should not become recursively opaque. + +--- + +# 42. Suggested Deployment Topology + +A Kubernetes-oriented implementation may use: + +```text +namespace: fluid-runtime + gateway + revision-router + adapter-r41 + adapter-r42 + +namespace: fluid-observation + telemetry-ingest + pressure-engine + cohort-engine + +namespace: fluid-control + daimon + hypothesis-engine + policy-engine + experiment-controller + promotion-controller + +namespace: fluid-build + builder-jobs + verifier-jobs + +namespace: fluid-state + evidence-db + artifact-reference-service + event-log +``` + +The exact deployment substrate is not normative. + +The architectural separation is. + +--- + +# 43. Kubernetes Control Pattern + +FLUID may map naturally to a controller/operator model. + +Potential custom resources: + +```text +FluidInterface +FluidRevision +FluidPressure +FluidHypothesis +FluidExperiment +FluidBackendRequirement +FluidOptimizationPolicy +FluidMigration +``` + +Example: + +```yaml +apiVersion: fluid.example/v1alpha1 +kind: FluidRevision +metadata: + name: customer-finance-r42 + +spec: + interfaceRef: customer-finance + parentRevision: r41 + contractRef: ... + runtimeRef: ... + intentVersion: iei-7 + state: candidate + +status: + verification: passed + trafficShare: 0.20 + fitnessState: evaluating +``` + +This is a promising implementation model because Kubernetes already offers: + +- declarative desired state; +- controllers; +- immutable artifact references; +- rollout mechanics; +- status reconciliation; +- RBAC; +- event history. + +FLUID does not require Kubernetes, but the control-loop semantics align well. + +--- + +# 44. Suggested Internal APIs + +The first implementation SHOULD establish a small set of internal control APIs. + +--- + +## 44.1 Revision API + +Operations: + +```text +create revision +verify revision +publish revision +set revision state +query revision lineage +``` + +--- + +## 44.2 Pressure API + +Operations: + +```text +record pressure +aggregate pressure +link evidence +link hypothesis +close / dismiss pressure +``` + +--- + +## 44.3 Hypothesis API + +Operations: + +```text +create hypothesis +compare hypotheses +prioritize hypothesis +attach candidate +record outcome +``` + +--- + +## 44.4 Experiment API + +Operations: + +```text +create experiment +start experiment +change bounded allocation +stop experiment +record metrics +finalize outcome +``` + +--- + +## 44.5 Intent API + +Operations: + +```text +read active intent +read historical intent +validate candidate against intent +propose intent amendment +``` + +Intent amendment SHOULD remain separately governed. + +--- + +# 45. Reference Persistence Model + +A relational starting model could use tables: + +```text +interfaces +interface_intents +revisions +pressures +cohorts +hypotheses +hypothesis_pressures +experiments +experiment_revisions +fitness_measurements +backend_requirements +decisions +events +artifact_refs +``` + +Append-only `events` SHOULD capture lifecycle changes. + +Materialized views may provide operational summaries. + +This is likely simpler for a first implementation than introducing a specialized graph database. + +--- + +# 46. Reference Event Flow + +```text +API REQUEST + ↓ +runtime event + ↓ +telemetry ingest + ↓ +normalized interaction event + ↓ +pressure detection + ↓ +pressure record + ↓ +hypothesis candidate + ↓ +policy / complexity evaluation + ↓ +revision candidate + ↓ +verification + ↓ +experiment + ↓ +fitness event + ↓ +promotion decision + ↓ +routing policy update +``` + +Every arrow SHOULD be independently observable. + +--- + +# 47. Trust Model + +FLUID assumes different components have different trust levels. + +```text +consumer request untrusted +telemetry evidence +AI interpretation advisory +generated code untrusted candidate +deterministic tests verification evidence +signed revision deployable artifact +runtime security policy authoritative +interface intent constitutional authority +human / policy approval governance authority +``` + +This distinction should remain visible in code and data models. + +--- + +# 48. Architectural Anti-Patterns + +FLUID implementations SHOULD avoid the following. + +--- + +## 48.1 LLM in the Mandatory Request Path + +```text +request → LLM decides semantics → backend +``` + +This violates the deterministic runtime principle. + +--- + +## 48.2 Self-Modifying Production Runtime + +```text +runtime observes error +→ edits own production implementation +→ continues +``` + +This destroys auditability and safe rollback. + +--- + +## 48.3 Telemetry Equals Requirement + +```text +many clients request X +→ X automatically becomes valid interface scope +``` + +Usage is evidence, not intent. + +--- + +## 48.4 Backend Authority Leakage + +```text +interface wants capability +→ Daimon modifies backend +``` + +FLUID must escalate requirements instead. + +--- + +## 48.5 Single Fitness Number Without Explanation + +A scalar may be operationally useful but MUST NOT hide the underlying dimensions and guardrails. + +--- + +## 48.6 Endless API Accretion + +Every pressure becoming a new endpoint will eventually destroy interface quality. + +Complexity governance is mandatory. + +--- + +## 48.7 Agent as Policy + +The Daimon may reason about policy. + +It MUST NOT be the sole implementation of policy. + +--- + +# 49. Initial Repository Structure + +A FLUID framework repository could begin with: + +```text +/ +├── INTENT.md +├── README.md +├── FluidAPIStandards.md +├── ArchitectureBlueprint.md +│ +├── standards/ +│ ├── InterfaceEvolutionIntent.md +│ └── FluidHypothesisRevisionSchema.md +│ +├── schemas/ +│ ├── pressure.schema.yaml +│ ├── hypothesis.schema.yaml +│ ├── revision.schema.yaml +│ ├── experiment.schema.yaml +│ └── event.schema.yaml +│ +├── runtime/ +│ ├── gateway/ +│ ├── revision-router/ +│ └── adapter-runtime/ +│ +├── observation/ +│ ├── telemetry/ +│ ├── cohorts/ +│ └── pressure/ +│ +├── control/ +│ ├── daimon/ +│ ├── hypotheses/ +│ ├── policy/ +│ ├── experiments/ +│ ├── fitness/ +│ └── migration/ +│ +├── build/ +│ ├── builder/ +│ └── verifier/ +│ +├── backend-requirements/ +│ +├── examples/ +│ └── customer-finance/ +│ +└── docs/ +``` + +This structure is illustrative and should evolve with implementation experience. + +--- + +# 50. First Vertical Slice + +The recommended first vertical slice is deliberately small. + +Build one FLUID-enabled REST interface with: + +1. two deterministic revisions; +2. explicit revision routing; +3. telemetry; +4. one consumer cohort dimension; +5. pressure detection; +6. manually created hypothesis; +7. manually created candidate revision; +8. controlled 90/10 experiment; +9. fitness comparison; +10. promotion or rollback; +11. complete audit trail. + +The first success criterion is not autonomous coding. + +It is proving that the **revision–experiment–fitness loop works cleanly and safely**. + +--- + +# 51. Second Vertical Slice + +Once the first loop is stable: + +1. add explicit consumer feedback; +2. auto-generate pressure records; +3. use the Daimon to propose hypotheses; +4. require human selection; +5. generate candidate contract changes; +6. generate tests; +7. keep promotion human-controlled. + +This establishes FLUID-2 / FLUID-3 behavior without production autonomy. + +--- + +# 52. Third Vertical Slice + +Next: + +1. automate candidate build; +2. automate verification; +3. create bounded experiment deployments; +4. let the Daimon recommend promotion; +5. implement complexity scoring; +6. implement backend requirement escalation. + +This establishes FLUID-4. + +--- + +# 53. Fourth Vertical Slice + +Only after sufficient operational evidence: + +1. define deterministic promotion policies; +2. allow low-risk presentation and implementation adaptations to promote automatically; +3. retain contract adaptations under stricter controls; +4. automate optimization-regime recommendations; +5. introduce evolution velocity control. + +This begins FLUID-5. + +--- + +# 54. Open Architectural Questions + +The following should be resolved by implementation experiments rather than prematurely standardized. + +### Pressure detection + +Which signals produce the best improvement candidates? + +### Cohorts + +How stable and expressive should cohort definitions be? + +### Hypothesis reach + +How should explanatory reach be measured? + +### Complexity + +Which metrics correlate with actual consumer cognitive burden? + +### Experiment design + +When is shadow traffic sufficient, and when is live adoption required? + +### Revision identity + +Should revision numbering be global, per interface, semantic, or content-addressed? + +### Traffic allocation + +How should long-lived consumers be consistently assigned? + +### Agent feedback + +What feedback schema is most useful without creating excessive verbosity or cost? + +### Backend requirement exchange + +Should this become a portable cross-service protocol? + +### Economic optimization + +How should expected improvement value be estimated? + +--- + +# 55. Architectural Invariants + +The first implementation SHOULD protect these invariants aggressively. + +1. Runtime behavior remains deterministic. +2. Evolution can stop without stopping the API. +3. Every published revision is identifiable. +4. Every revision has an explicit contract. +5. Every revision is governed by a specific intent version. +6. Every nontrivial change can be linked to evidence. +7. Every experiment has guardrails and stop conditions. +8. Every promotion is auditable. +9. AI-generated artifacts are untrusted until verified. +10. Security policy remains deterministic. +11. Backend authority does not leak into the interface Daimon. +12. Complexity is measured. +13. Multiple revisions may coexist. +14. Failed experiments are normal and recoverable. +15. Usage informs intent but cannot silently redefine it. +16. Adaptive cost is controlled independently from runtime availability. + +--- + +# 56. Architectural Summary + +The core FLUID architecture is not an AI gateway. + +It is a **deterministic interface platform surrounded by a scientific evolution system**. + +The minimal loop is: + +```text +deterministic revision + ↓ + telemetry + ↓ + pressure + ↓ + hypothesis + ↓ + candidate revision + ↓ + experiment + ↓ + fitness + ↓ + promote / modify / reject +``` + +The architecture becomes powerful because each part remains independently inspectable. + +The Daimon contributes interpretation, creativity, planning, and adaptation. + +Deterministic runtime infrastructure contributes reliability. + +Intent contributes direction. + +Complexity governance contributes restraint. + +Experiments contribute criticism. + +Auditability contributes trust. + +Together they allow an interface to evolve continuously without sacrificing the determinism expected from infrastructure. diff --git a/spec/FluidAPIStandards.md b/spec/FluidAPIStandards.md new file mode 100755 index 0000000..904c0c6 --- /dev/null +++ b/spec/FluidAPIStandards.md @@ -0,0 +1,1150 @@ +# FLUID API Standards + +**Document:** `FluidAPIStandards.md` +**Version:** 0.1.0 +**Status:** Working Standard +**Framework:** FLUID — Flow Utilizing Interface Daimon + +--- + +## 1. Scope + +This document defines the normative core of FLUID APIs. + +FLUID is a framework for operating deterministic service interfaces inside a governed evolutionary control loop. A FLUID API may observe usage, detect interface pressure, formulate hypotheses, construct candidate interface revisions, evaluate them, and promote or retire revisions according to explicit policy. + +FLUID does **not** require runtime AI inference for normal request processing. The active interface remains deterministic; adaptation occurs around the interface. + +This document standardizes: + +- core terminology; +- architectural boundaries; +- deterministic runtime invariants; +- interface revisions; +- telemetry and interface pressure; +- consumer cohorts; +- hypothesis-driven evolution; +- fitness and optimization; +- complexity governance; +- compatibility and migration; +- operational authority modes; +- security and auditability; +- backend capability escalation; +- conformance requirements. + +The following remain intentionally implementation-defined in v0.1: + +- telemetry transport; +- persistence technology; +- scoring algorithms; +- traffic-splitting technology; +- AI model choice; +- deployment platform; +- API protocol or style. + +A FLUID interface MAY expose REST, GraphQL, RPC, event, messaging, streaming, tool, or other machine-facing interface styles. + +--- + +## 2. Normative Language + +The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, **SHOULD NOT**, **MAY**, and **OPTIONAL** are to be interpreted as normative requirements. + +Where this standard describes an implementation pattern without using normative language, the text is informative. + +--- + +## 3. Core Principle + +The defining FLUID principle is: + +> **Deterministic execution, adaptive evolution.** + +A FLUID interface MUST expose one or more identifiable deterministic interface revisions. + +The evolutionary system MAY use probabilistic or agentic techniques to: + +- analyze telemetry; +- detect patterns; +- generate hypotheses; +- design candidate revisions; +- generate adapter code; +- generate tests; +- evaluate outcomes; +- recommend migration; +- recommend optimization preferences. + +Probabilistic mechanisms MUST NOT silently replace deterministic: + +- authentication; +- authorization; +- tenancy boundaries; +- policy enforcement; +- contractual API semantics; +- security constraints. + +--- + +## 4. FLUID Daimon + +The **FLUID Daimon** is the active caretaker of a FLUID interface. + +The Daimon is responsible for the interface evolution loop within explicitly granted authority. + +A Daimon MAY perform: + +1. observation; +2. pressure detection; +3. classification; +4. hypothesis generation; +5. candidate design; +6. implementation generation; +7. verification; +8. controlled experimentation; +9. fitness evaluation; +10. migration planning; +11. backend capability escalation; +12. promotion or retirement where authorized. + +The Daimon MUST operate within explicit interface intent and governance constraints. + +--- + +## 5. Responsibility Boundary + +A FLUID interface owns the interface and adapter layer. + +It MAY: + +- expose backend capabilities; +- compose multiple backend capabilities; +- reshape representations; +- introduce interface-level abstractions; +- improve discoverability; +- improve validation and error feedback; +- optimize adapter implementation; +- create new interface revisions; +- define requirements for unavailable backend capabilities. + +A FLUID interface MUST NOT assume authority to modify backend systems merely because the interface requires new capability. + +Where a candidate interface requires unavailable backend functionality, the FLUID implementation SHOULD emit a structured backend capability requirement. + +The backend remains responsible for accepting, rejecting, constraining, or declaring the request out of scope. + +--- + +## 6. Interface Intent + +Every FLUID interface MUST have declared evolutionary intent. + +The parent service or repository MAY use a general `INTENT.md`. FLUID MUST NOT redefine that schema. + +A FLUID interface SHOULD reference a dedicated: + +```text +InterfaceEvolutionIntent.md +``` + +This document defines the constitutional boundary of interface evolution. + +At minimum it SHOULD define: + +- mission; +- intended consumers; +- capability domain; +- non-goals; +- responsibility boundaries; +- optimization preferences; +- complexity constraints; +- compatibility policy; +- autonomy policy; +- quality requirements; +- economic constraints. + +The Daimon MAY recommend changes to interface intent. + +The Daimon MUST NOT silently redefine its own intent. + +--- + +## 7. Deterministic Runtime Invariant + +For a given: + +- interface revision; +- request; +- authenticated identity; +- authorization state; +- deterministic configuration; +- relevant backend state; + +the interface MUST behave according to its declared contract. + +Normal request handling MUST NOT depend on an LLM or other probabilistic mechanism inventing undefined semantics. + +Experimental dynamic fulfillment is outside the FLUID v0.1 conformance core. + +--- + +## 8. Interface Revision + +Every production mutation of a FLUID interface MUST result in an identifiable revision. + +A revision MUST have: + +- revision identifier; +- parent revision or genesis marker; +- contract reference; +- implementation reference; +- creation time; +- provenance; +- compatibility declaration; +- verification status. + +A revision SHOULD additionally contain: + +- originating hypotheses; +- expected fitness effects; +- measured fitness; +- deployment history; +- consumer cohort exposure; +- promotion state; +- rollback information; +- associated backend requirements; +- complexity impact. + +Published revisions SHOULD be immutable. + +Corrections SHOULD create successor revisions. + +--- + +## 9. Concurrent Revisions + +A FLUID implementation MAY expose multiple revisions concurrently. + +Example: + +```text +Revision 21 stable 62% traffic +Revision 22 candidate 28% traffic +Revision 23 experiment 10% traffic +``` + +Concurrent revisions MAY be used for: + +- controlled experiments; +- cohort-specific interfaces; +- gradual migration; +- compatibility support; +- fitness comparison; +- rollback protection. + +Traffic allocation MUST be governed deterministically. + +The basis for assigning a consumer to a revision SHOULD be auditable. + +--- + +## 10. Evolution Velocity + +FLUID SHOULD treat the rate of change as a controllable system variable. + +Signals that MAY influence evolution velocity include: + +- hypothesis success rate; +- regression rate; +- reliability trend; +- support burden; +- adoption rate; +- migration success; +- failed experiments; +- available review capacity; +- economic budget; +- operational risk. + +A FLUID implementation MAY accelerate, maintain, slow, or freeze adaptation activity according to policy. + +Evolution velocity MUST NOT override deterministic safety constraints. + +--- + +## 11. Compatibility Model + +FLUID v0.1 follows: + +> **Versioned evolution aiming toward managed migration.** + +Compatibility preservation is important but is not an absolute prohibition against redesign. + +A FLUID implementation SHOULD support a lifecycle similar to: + +```text +detect weakness +→ formulate replacement +→ introduce successor revision +→ allow coexistence +→ observe adoption +→ guide migration +→ deprecate predecessor +→ retire when justified +``` + +Breaking changes MUST be explicit. + +Breaking changes MUST NOT silently alter an already published revision. + +--- + +## 12. Interface Telemetry + +FLUID telemetry extends conventional API monitoring. + +A FLUID implementation SHOULD be capable of observing relevant signals from: + +- successful calls; +- failed calls; +- invalid requests; +- near-miss requests; +- call sequences; +- redundant round trips; +- repeated client-side transformations; +- latency; +- backend failures; +- authorization failures; +- unused capabilities; +- discoverability failures; +- explicit consumer feedback; +- agent/tool usage; +- revision adoption; +- migration behavior. + +Telemetry MUST respect: + +- privacy constraints; +- tenancy boundaries; +- retention policy; +- data minimization; +- contractual restrictions; +- security policy. + +Telemetry collection SHOULD be sufficient to support interface evolution without becoming an unrestricted surveillance layer. + +--- + +## 13. Interface Pressure + +**Interface pressure** is evidence that the interface differs materially from the needs, expectations, or natural interaction patterns of its consumers. + +Initial standard pressure classes are: + +1. successful natural usage; +2. successful but inefficient usage; +3. recoverable misunderstanding; +4. repeated expectation mismatch; +5. poor discoverability; +6. missing interface capability; +7. missing backend capability; +8. out-of-scope demand; +9. prohibited demand; +10. implementation failure. + +Pressure is evidence, not truth. + +Repeated consumer behavior MUST NOT automatically redefine interface intent. + +--- + +## 14. Consumer Cohorts + +FLUID SHOULD support consumer cohort analysis where appropriate. + +Possible cohorts include: + +- human developers; +- browser applications; +- mobile applications; +- legacy integrations; +- internal services; +- external partners; +- coding agents; +- autonomous agents; +- contract versions; +- commercial plans; +- organizational tenants. + +Cohorts SHOULD be sufficiently coarse to avoid unnecessary identification where aggregate analysis is adequate. + +Cohort analysis MAY be used to evaluate: + +- adoption; +- friction; +- fitness; +- migration; +- feature demand; +- reliability; +- cost; +- commercial product behavior. + +Commercial use MUST remain subordinate to privacy, contractual, and governance constraints. + +--- + +## 15. Explicit Consumer Feedback + +A FLUID interface SHOULD support optional structured feedback from consumers. + +Feedback MAY express: + +- intended goal; +- attempted operation; +- expected capability; +- actual outcome; +- workaround; +- desired capability; +- operational impact. + +Example: + +```json +{ + "goal": "retrieve the latest invoice", + "attempt": "GET /customers/4711/invoices/latest", + "outcome": "capability unavailable", + "workaround": "query all invoices, sort locally, take first", + "impact": "extra requests and client-side logic" +} +``` + +Explicit feedback MUST be treated as evidence. + +It MUST NOT itself authorize interface changes. + +--- + +## 16. Adaptation Classes + +FLUID defines the following initial adaptation classes. + +### 16.1 Presentation Adaptation + +Changes how existing capabilities are explained or discovered. + +Examples: + +- documentation; +- examples; +- error messages; +- schema annotations. + +### 16.2 Contract Adaptation + +Changes externally exposed API semantics or surface. + +Examples: + +- endpoint; +- field; +- operation; +- query; +- mutation; +- resource representation. + +### 16.3 Composition Adaptation + +Changes how existing backend capabilities are combined. + +### 16.4 Implementation Adaptation + +Changes adapter implementation without intended semantic change. + +Examples: + +- caching; +- batching; +- routing; +- serialization. + +### 16.5 Requirement Escalation + +Defines missing capability that belongs outside the FLUID interface responsibility boundary. + +Implementations MAY introduce additional adaptation classes. + +--- + +## 17. Scientific Adaptation Method + +A nontrivial FLUID adaptation SHOULD originate from an explicit hypothesis. + +A hypothesis SHOULD define: + +- observation; +- problem statement; +- explanatory claim; +- proposed adaptation; +- expected outcome; +- measurement method; +- success criteria; +- guardrails; +- risk; +- complexity impact; +- implementation cost; +- expected learning value. + +The adaptation lifecycle SHOULD follow: + +```text +observe +→ classify +→ hypothesize +→ prioritize +→ design +→ construct +→ verify +→ experiment +→ measure +→ criticize +→ retain / modify / reject +``` + +A hypothesis MUST be falsifiable or otherwise evaluable against explicit evidence. + +--- + +## 18. Hypothesis Reach + +FLUID SHOULD distinguish local fixes from higher-reach hypotheses. + +A high-reach hypothesis explains multiple observations through one coherent abstraction. + +Example: + +```text +Low reach: +Add six convenience endpoints. + +Higher reach: +The interface lacks a coherent customer financial context abstraction. +``` + +Candidate prioritization MAY consider: + +- expected impact; +- confidence; +- explanatory reach; +- implementation cost; +- complexity cost; +- reversibility; +- risk; +- learning value; +- number of affected cohorts. + +Reach does not imply correctness. + +It is a prioritization signal. + +--- + +## 19. Competing Hypotheses + +FLUID SHOULD support multiple competing hypotheses. + +Where practical, hypotheses MAY be compared through: + +- offline analysis; +- replay; +- simulation; +- test environments; +- shadow traffic; +- canary traffic; +- parallel revisions; +- consumer studies. + +The Daimon SHOULD preserve uncertainty where evidence is insufficient. + +--- + +## 20. Fitness + +Fitness describes how well an interface revision fulfills intended purpose. + +Standard fitness dimensions are: + +- client utility; +- correctness; +- reliability; +- availability; +- performance; +- discoverability; +- simplicity; +- compatibility; +- security; +- maintainability; +- operational cost; +- implementation cost; +- resource consumption. + +Implementations MAY add dimensions. + +The standard does not define one universal scalar fitness function. + +--- + +## 21. Optimization Preferences + +A FLUID interface MUST support explicit optimization preferences. + +Example: + +```text +client utility HIGH +reliability HIGH +simplicity MEDIUM +latency MEDIUM +cost LOW +``` + +Optimization preferences MAY change by operational phase. + +Common regimes MAY include: + +- EXPLORATION; +- ADOPTION; +- UTILITY; +- PERFORMANCE; +- RELIABILITY; +- SECURITY; +- COST; +- CONSOLIDATION; +- MIGRATION. + +Operator-selected regimes are acceptable. + +Mature FLUID implementations SHOULD support automatic optimization recommendations. + +Where sufficient evidence and governance exist, automatic optimization SHOULD be the default operational convenience model, subject to operator override. + +--- + +## 22. Complexity Governance + +Complexity is a constrained resource. + +Standard complexity dimensions are: + +- surface area; +- concept count; +- operation count; +- parameter dimensionality; +- semantic overlap; +- alternative-path count; +- dependency count; +- backend composition count; +- exception count; +- active revision count; +- consumer cognitive load. + +Implementations SHOULD measure relevant dimensions. + +Implementations MAY define their own scoring functions. + +The governing principle is: + +> **Standard dimensions, implementation-defined scoring.** + +--- + +## 23. Complexity Budget + +`InterfaceEvolutionIntent.md` SHOULD define a complexity budget. + +A candidate MAY be rejected even when it increases local utility. + +Example: + +```text +utility gain +2 +complexity cost +9 +decision reject or redesign +``` + +Repeated special-case pressure SHOULD trigger consideration of a higher-reach abstraction. + +The Daimon SHOULD prefer the smallest sufficient adaptation. + +--- + +## 24. Improvement Versus Accretion + +Continuous addition is not equivalent to improvement. + +The Daimon SHOULD detect: + +- duplicate semantics; +- overlapping operations; +- historical exceptions; +- obsolete features; +- redundant representations; +- fragmented abstractions. + +Evolution MAY remove or consolidate capability. + +The goal is fitness for intent, not maximum API surface. + +--- + +## 25. Auditability + +Auditability is a FLUID core invariant. + +A conformant system SHOULD be able to answer: + +- What changed? +- Why did it change? +- What evidence triggered it? +- Which hypotheses were considered? +- Which revision implemented it? +- What tests were performed? +- Who or what authorized it? +- Which cohorts received it? +- What happened after deployment? +- Why was it retained, modified, or rejected? +- How can the prior state be restored? + +Adaptive behavior without sufficient provenance is non-conformant with FLUID design intent. + +--- + +## 26. Operational Authority Modes + +FLUID modes describe authority, not maturity. + +### FLUID-0 — Instrumented + +Collect telemetry and maintain revision identity. + +### FLUID-1 — Analytical + +Detect and classify interface pressure. + +### FLUID-2 — Advisory + +Propose interface adaptations. + +### FLUID-3 — Constructive + +Generate contracts, adapter implementations, tests, documentation, or migration artifacts. + +### FLUID-4 — Experimental + +Deploy candidates into bounded experiment environments. + +### FLUID-5 — Bounded Autonomous + +Promote qualifying changes according to deterministic policy. + +### FLUID-6 — Evolutionary + +Manage complete revision and migration lifecycles within declared authority. + +A high-assurance system MAY deliberately remain at FLUID-2. + +A lower-risk internal environment MAY operate at FLUID-5. + +--- + +## 27. Security Invariants + +The Daimon MUST NOT autonomously bypass: + +- authentication; +- authorization; +- tenant isolation; +- network policy; +- secret policy; +- data-access policy; +- legal constraints; +- explicit responsibility boundaries. + +AI-generated changes MUST pass the same deterministic enforcement mechanisms required of human-generated changes. + +Security policy MUST NOT rely solely on probabilistic reasoning. + +--- + +## 28. Economic Governance + +Adaptive intelligence consumes resources. + +FLUID SHOULD measure cost attributable to: + +- telemetry; +- storage; +- analysis; +- model inference; +- candidate generation; +- testing; +- parallel revisions; +- deployment; +- human review; +- migration. + +Economic cost SHOULD be a fitness dimension. + +The Daimon SHOULD be able to defer low-value, high-cost exploration. + +--- + +## 29. Adaptive Compute Budget + +A FLUID deployment SHOULD support explicit budgets such as: + +- analysis spend per period; +- hypothesis-generation spend; +- candidate-generation spend; +- maximum concurrent experiments; +- maximum autonomous implementation effort. + +Exhausting the adaptive budget MUST NOT compromise deterministic runtime operation. + +The API MUST continue operating according to its active contract even when adaptive evolution is paused. + +--- + +## 30. Backend Capability Requirement Protocol + +Where required functionality is unavailable from the interface layer, FLUID SHOULD emit a structured capability requirement. + +A requirement SHOULD contain: + +- requirement identifier; +- originating interface; +- originating revision; +- originating hypothesis; +- requested capability; +- reason; +- expected consumer value; +- expected usage; +- semantic requirements; +- quality requirements; +- security constraints; +- urgency; +- candidate interface dependency. + +A backend SHOULD be able to return a disposition such as: + +- ACCEPTED; +- PLANNED; +- AVAILABLE; +- PARTIALLY_AVAILABLE; +- OUT_OF_SCOPE; +- REJECTED; +- SUPERSEDED. + +Repeated backend rejection MAY provide evidence about the appropriate interface boundary. + +--- + +## 31. Boundary Learning + +Repeated consumer demand outside declared intent MAY indicate: + +- consumer misunderstanding; +- weak documentation; +- missing neighboring service; +- wrong interface boundary; +- outdated interface intent; +- genuinely out-of-scope demand. + +The Daimon MAY recommend intent revision. + +Intent revision SHOULD itself be governed and auditable. + +--- + +## 32. Adoption as Evidence + +Where revisions coexist, adoption MAY be used as a fitness signal. + +Adoption MUST NOT be treated as proof of quality. + +Adoption may be affected by: + +- defaults; +- migration cost; +- novelty; +- lock-in; +- incentives; +- documentation; +- familiarity; +- commercial packaging. + +Adoption SHOULD therefore be combined with other fitness signals. + +--- + +## 33. Experimental Dynamic Fulfillment + +Runtime synthesis of undefined API behavior is outside the FLUID v0.1 core. + +Future experimental profiles MAY investigate: + +```text +unknown request +→ semantic interpretation +→ dynamic capability construction +→ validation +→ response +``` + +Such behavior raises unresolved questions regarding: + +- determinism; +- latency; +- reproducibility; +- cost; +- authorization; +- security; +- auditability; +- liability. + +Production-grade dynamic fulfillment SHOULD NOT be attempted until substantial operational experience exists with deterministic FLUID evolution. + +--- + +## 34. Modular Architecture + +FLUID SHOULD support incremental implementation. + +A minimal implementation MAY consist of: + +```text +deterministic API ++ interface revision identity ++ telemetry ++ interface evolution intent +``` + +Optional modules MAY provide: + +- pressure analysis; +- cohort analysis; +- explicit feedback; +- hypothesis management; +- candidate generation; +- automated testing; +- fitness evaluation; +- parallel revisions; +- migration; +- backend requirement escalation; +- autonomous promotion. + +Advanced capability MUST NOT be required for basic FLUID adoption. + +--- + +## 35. Conformance Profiles + +The following profiles are informative names for modular packaging. + +### FLUID Core + +Requires: + +- deterministic interface; +- revision identity; +- telemetry; +- interface evolution intent; +- auditability. + +### FLUID Insight + +Adds: + +- pressure detection; +- consumer cohorts; +- fitness metrics. + +### FLUID Science + +Adds: + +- explicit hypotheses; +- experiments; +- candidate comparison; +- outcome evaluation. + +### FLUID Builder + +Adds: + +- generated contracts; +- adapter implementation; +- generated tests. + +### FLUID Evolution + +Adds: + +- parallel revisions; +- candidate deployment; +- managed promotion; +- migration. + +### FLUID Autonomous Evolution + +Adds: + +- policy-bounded autonomous promotion. + +These names do not replace operational authority modes. + +--- + +## 36. Minimal FLUID v0.1 Conformance + +An implementation claiming FLUID v0.1 core conformance MUST provide: + +1. a deterministic API contract; +2. an identifiable active interface revision; +3. interface telemetry; +4. declared interface evolutionary intent; +5. an auditable link from evidence to proposed change; +6. explicit responsibility boundaries; +7. deterministic security enforcement independent of probabilistic AI decisions. + +Autonomous modification is not required. + +--- + +## 37. Recommended Implementation Sequence + +### Stage 1 — Observable Interface + +Implement: + +- deterministic contract; +- revision identity; +- telemetry; +- `InterfaceEvolutionIntent.md`. + +### Stage 2 — Interface Pressure + +Add: + +- pressure taxonomy; +- consumer cohorts; +- fitness dimensions; +- explicit feedback. + +### Stage 3 — Scientific Evolution + +Add: + +- hypothesis records; +- candidate comparison; +- experiments; +- outcome evaluation. + +### Stage 4 — Constructive Daimon + +Add: + +- AI-assisted interface design; +- adapter generation; +- test generation; +- backend requirement generation. + +### Stage 5 — Managed Evolution + +Add: + +- parallel revisions; +- traffic allocation; +- adoption analysis; +- migration lifecycle; +- optimization recommendations. + +### Stage 6 — Bounded Autonomy + +Add: + +- policy-driven autonomous experiments; +- bounded promotion; +- automatic optimization. + +--- + +## 38. Open Standardization Areas + +The following are intentionally open in v0.1: + +- telemetry schema; +- cohort identity model; +- interface-pressure scoring; +- fitness aggregation; +- complexity scoring; +- hypothesis exchange format; +- experiment protocol; +- revision-routing protocol; +- feedback protocol; +- backend requirement protocol; +- adaptation-risk classification; +- migration mechanics; +- AI cost accounting; +- cross-interface coordination. + +FLUID v0.1 standardizes the conceptual and governance core before freezing implementation detail prematurely. + +--- + +## 39. Canonical Design Principles + +1. **Deterministic execution, adaptive evolution.** +2. **Usage is evidence, not truth.** +3. **Errors can be product signals.** +4. **Evolution proceeds through explicit hypotheses.** +5. **Criticism is part of improvement.** +6. **Prefer hypotheses with useful explanatory reach.** +7. **Competing hypotheses are legitimate.** +8. **Complexity is a budget.** +9. **Improvement may require subtraction.** +10. **Adaptation does not imply authority propagation.** +11. **Multiple live revisions may represent legitimate uncertainty.** +12. **Adoption is evidence, not proof.** +13. **Convenience is an adoption requirement.** +14. **Adaptive intelligence has an economic cost.** +15. **Auditability is essential.** +16. **Intent constrains evolution.** +17. **The smallest sufficient adaptation is preferred.** +18. **Autonomy is a setting, not a maturity score.** + +--- + +## 40. Vision + +A conventional API is designed, deployed, monitored, and periodically redesigned. + +A FLUID API participates in its own continuous improvement. + +Its runtime behavior remains deterministic. + +Its understanding of consumer needs becomes empirical. + +Its changes become hypotheses. + +Its revisions become experiments. + +Its telemetry becomes criticism. + +Its production history becomes evidence. + +Its intent constrains its growth. + +Its Daimon continuously cares for its fitness. + +The goal is not an API that changes constantly. + +The goal is an API that can learn **when it should change, why it should change, how to test the change, and whether the result deserves to become part of its evolving contract**. diff --git a/spec/FluidHypothesisRevisionSchema.md b/spec/FluidHypothesisRevisionSchema.md new file mode 100755 index 0000000..748289e --- /dev/null +++ b/spec/FluidHypothesisRevisionSchema.md @@ -0,0 +1,773 @@ +# 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: + - "" + notes: "" +``` + +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:" + + implementation: + artifact_ref: "artifact:adapter/customer-finance-api/r22" + source_ref: "git:" + build_ref: "build:" + digest: "sha256:" + + 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. diff --git a/spec/InterfaceEvolutionIntent.md b/spec/InterfaceEvolutionIntent.md new file mode 100755 index 0000000..a17b025 --- /dev/null +++ b/spec/InterfaceEvolutionIntent.md @@ -0,0 +1,505 @@ +# Interface Evolution Intent + +**Document:** `InterfaceEvolutionIntent.md` +**Version:** 0.1.0 +**Status:** Template / Normative Companion to FLUID API Standards + +--- + +## 1. Purpose + +This document defines the evolutionary intent and governance boundary of a FLUID interface. + +It is subordinate to the parent repository or service `INTENT.md` and MUST NOT redefine the overall mission of that service. + +Its purpose is to answer: + +> **How may this interface evolve while remaining faithful to the service it represents?** + +The FLUID Daimon MUST treat this document as a constitutional constraint. + +--- + +## 2. Parent Intent + +**Parent service/repository:** +`` + +**Parent intent document:** +`INTENT.md` + +**Relevant parent mission excerpt or reference:** +`` + +--- + +## 3. Interface Identity + +**Interface name:** +`` + +**Interface identifier:** +`` + +**Current operational authority mode:** +`FLUID-0 | FLUID-1 | FLUID-2 | FLUID-3 | FLUID-4 | FLUID-5 | FLUID-6` + +**Protocols / interface styles:** + +- `` +- `` +- `` +- `` +- `` + +--- + +## 4. Mission + +Describe the outcome the interface exists to enable. + +The mission SHOULD focus on consumer outcomes rather than protocol details. + +### Mission statement + +> `` + +### Success looks like + +- `` +- `` +- `` + +--- + +## 5. Intended Consumers + +Define the consumers the interface is designed to serve. + +### Primary consumer cohorts + +| Cohort | Description | Importance | Notes | +|---|---|---:|---| +| `` | `` | `` | `` | + +### Secondary cohorts + +| Cohort | Description | Importance | Notes | +|---|---|---:|---| +| `` | `` | `` | `` | + +### Explicitly unsupported cohorts + +- `` +- `` + +--- + +## 6. Capability Domain + +Define which capabilities properly belong inside this interface. + +### In scope + +- `` +- `` +- `` + +### Conditionally in scope + +Capabilities that MAY be introduced if evidence justifies them: + +- `` +- `` + +### Out of scope + +- `` +- `` + +--- + +## 7. Responsibility Boundaries + +The FLUID interface owns interface and adapter behavior only. + +### Responsibilities owned by this interface + +- `` +- `` +- `` +- `` +- `` + +### Responsibilities owned by backend systems + +| Backend | Responsibility | Boundary | +|---|---|---| +| `` | `` | `` | + +### Explicit non-authority + +The Daimon MUST NOT autonomously: + +- `` +- `` +- `` +- `` + +--- + +## 8. Consumer Expectation Model + +Describe the expectations the interface SHOULD cultivate. + +### Concepts consumers should naturally understand + +- `` +- `` + +### Interaction patterns considered natural + +- `` +- `` + +### Expectations that should be discouraged + +- `` +- `` + +This section provides context when interpreting interface pressure. + +--- + +## 9. Optimization Preferences + +The Daimon MUST optimize within declared priorities. + +### Active optimization regime + +`` + +### Fitness priorities + +| Dimension | Priority | Target / Constraint | Notes | +|---|---:|---|---| +| Client utility | High | `` | | +| Correctness | High | `` | | +| Reliability | High | `` | | +| Availability | `<...>` | `` | | +| Performance | `<...>` | `` | | +| Discoverability | `<...>` | `` | | +| Simplicity | `<...>` | `` | | +| Compatibility | `<...>` | `` | | +| Security | `<...>` | `` | | +| Maintainability | `<...>` | `` | | +| Operational cost | `<...>` | `` | | +| Implementation cost | `<...>` | `` | | +| Resource consumption | `<...>` | `` | | + +### Automatic recommendation policy + +`` + +--- + +## 10. Complexity Budget + +Complexity is a constrained resource. + +### Complexity dimensions + +| Dimension | Current | Preferred | Maximum | Scoring method | +|---|---:|---:|---:|---| +| Surface area | | | | | +| Concept count | | | | | +| Operation count | | | | | +| Parameter dimensionality | | | | | +| Semantic overlap | | | | | +| Alternative-path count | | | | | +| Dependency count | | | | | +| Backend composition count | | | | | +| Exception count | | | | | +| Active revision count | | | | | +| Cognitive load | | | | | + +### Complexity policy + +- New capability SHOULD replace or generalize existing capability where reasonable. +- Semantic duplication SHOULD be rejected unless justified. +- Repeated special-case pressure SHOULD trigger abstraction review. +- Candidates exceeding a hard complexity limit MUST NOT be autonomously promoted. +- Complexity-reducing adaptations MAY be prioritized during consolidation regimes. + +--- + +## 11. Compatibility Policy + +### Compatibility posture + +`` + +### Rules + +- Published revision semantics MUST NOT change silently. +- Breaking changes REQUIRE a successor revision. +- `` +- `` + +### Coexistence expectations + +**Default maximum concurrent major revisions:** +`` + +**Default deprecation period:** +`` + +**Migration assistance required:** +`` + +--- + +## 12. Revision and Experiment Policy + +### Revision classes + +- stable; +- candidate; +- experiment; +- deprecated; +- retired. + +### Allowed concurrent exposure + +| Revision class | Production traffic allowed? | Max share | Approval required? | +|---|---|---:|---| +| stable | yes | 100% | no | +| candidate | `` | `<%>` | `` | +| experiment | `` | `<%>` | `` | +| deprecated | yes | `<%>` | no | +| retired | no | 0% | n/a | + +### Evolution velocity controls + +The Daimon SHOULD slow or freeze promotion when: + +- `` +- `` +- `` +- `` + +The Daimon MAY accelerate experimentation when: + +- `` +- `` +- `` + +--- + +## 13. Hypothesis Policy + +Nontrivial adaptations SHOULD have explicit hypotheses. + +### Minimum evidence for hypothesis creation + +- `` +- `` +- `` +- `` + +### Required hypothesis fields + +- observation; +- explanation; +- proposed adaptation; +- expected outcome; +- measurement; +- success criteria; +- guardrails; +- complexity impact; +- risk; +- expected learning value. + +### Competing hypotheses + +`` + +### Reach preference + +Describe whether broad explanatory hypotheses should be favored over local fixes. + +`` + +--- + +## 14. Adaptation Authority + +Define what the Daimon may do automatically. + +| Adaptation class | Observe | Propose | Generate | Experiment | Promote | +|---|---:|---:|---:|---:|---:| +| Presentation | yes | yes | `` | `` | `` | +| Contract | yes | yes | `` | `` | `` | +| Composition | yes | yes | `` | `` | `` | +| Implementation | yes | yes | `` | `` | `` | +| Requirement escalation | yes | yes | yes | n/a | n/a | + +### Absolute prohibitions + +The Daimon MUST NOT autonomously: + +- expand authorization scope; +- weaken tenant isolation; +- bypass deterministic security controls; +- reinterpret legal constraints; +- create backend authority it does not possess; +- ``. + +--- + +## 15. Security Requirements + +### Authentication + +`` + +### Authorization + +`` + +### Tenant isolation + +`` + +### Data handling + +`` + +### Logging and provenance + +`` + +### AI boundary + +AI-generated changes MUST pass deterministic: + +- security policy; +- tests; +- authorization validation; +- tenant-boundary checks; +- release controls. + +--- + +## 16. Quality Requirements + +| Quality attribute | Requirement | Hard guardrail? | +|---|---|---:| +| Correctness | `` | yes | +| Availability | `` | `` | +| Reliability | `` | `` | +| p95 latency | `` | `` | +| Error rate | `` | `` | +| Security | `` | yes | +| Auditability | `` | yes | +| Rollback | `` | yes | + +--- + +## 17. Economic Constraints + +### Adaptive compute budget + +| Budget | Limit | +|---|---:| +| analysis per day | `` | +| hypothesis generation | `` | +| candidate generation | `` | +| concurrent experiments | `` | +| autonomous implementation effort | `` | + +### Cost policy + +- Adaptive budget exhaustion MUST NOT affect deterministic runtime availability. +- High-cost / low-value hypotheses SHOULD be deferred. +- `` + +--- + +## 18. Backend Capability Escalation + +When a candidate requires backend functionality that is unavailable, the Daimon SHOULD issue a structured capability requirement. + +### Preferred requirement destination + +`` + +### Required response states + +- ACCEPTED; +- PLANNED; +- AVAILABLE; +- PARTIALLY_AVAILABLE; +- OUT_OF_SCOPE; +- REJECTED; +- SUPERSEDED. + +### Boundary-learning policy + +Repeated `OUT_OF_SCOPE` or `REJECTED` responses SHOULD trigger: + +`` + +--- + +## 19. Audit and Provenance Policy + +For every promoted change the system MUST retain enough evidence to reconstruct: + +- originating pressure; +- hypothesis; +- candidate; +- verification; +- approval; +- deployment; +- affected cohorts; +- measured outcome; +- final disposition. + +### Retention period + +`` + +### Immutable evidence store + +`` + +--- + +## 20. Review and Amendment + +This document SHOULD be versioned. + +Changes to this document SHOULD be treated as governance changes rather than ordinary interface changes. + +### Amendment authority + +`` + +### Review cadence + +`` + +### Last reviewed + +`` + +--- + +## 21. Summary + +The FLUID Daimon SHOULD optimize aggressively **inside** this document and remain conservative **at** its boundaries. + +The interface may evolve. + +Its intent must remain explicit. diff --git a/workplans/FC-WP-0001-foundations-and-wire-contract.md b/workplans/FC-WP-0001-foundations-and-wire-contract.md new file mode 100644 index 0000000..fe1fb06 --- /dev/null +++ b/workplans/FC-WP-0001-foundations-and-wire-contract.md @@ -0,0 +1,109 @@ +--- +id: FC-WP-0001 +type: workplan +title: "FLUID foundations and the wire contract" +domain: infotech +repo: fluid-core +status: active +owner: worsch +topic_slug: fluid +created: "2026-09-04" +updated: "2026-09-04" +planning_priority: high +planning_order: 1 +related_repos: + - fluid-telegram + - fluid-x + - fluid-substack +--- + +# FC-WP-0001 - Foundations and the wire contract + +Establish the boundary before any code depends on it. fluid-core integrates +out of process, so its contract is a set of on-the-wire artifacts, not a Go +API. Everything downstream assumes these schemas are stable. + +Reference: `spec/FluidHypothesisRevisionSchema.md`, `spec/ArchitectureBlueprint.md` +§36 (revision descriptor), §17 (routing policy), §44 (control APIs). + +## T01 - Repository scaffold and INTENT + +```task +id: FC-WP-0001-T01 +status: done +priority: high +``` + +Go module, directory tree per the plan, `INTENT.md` declaring the wire-contract +boundary and the four invariants this repo defends hardest. + +## T02 - Record schemas + +```task +id: FC-WP-0001-T02 +status: todo +priority: high +``` + +JSON Schema for `fluid_pressure`, `fluid_hypothesis`, `fluid_revision`, +`fluid_experiment`, `fluid_event`, `fluid_backend_requirement` and the feedback +record. Transcribe field names faithfully from the schema document — they are +the interop surface, per its §1. + +## T03 - Descriptor and policy schemas + +```task +id: FC-WP-0001-T03 +status: todo +priority: high +``` + +JSON Schema for the revision descriptor (Blueprint §36) and the routing policy +(Blueprint §17). These two are what the gateway consumes at runtime and must be +readable without any fluid-core code. + +## T04 - Type generation + +```task +id: FC-WP-0001-T04 +status: todo +priority: high +``` + +Generate Go types into `internal/contract/` from `schemas/`. Hand-written record +types are prohibited — drift between spec and implementation must fail CI. + +## T05 - Spec examples as fixtures + +```task +id: FC-WP-0001-T05 +status: todo +priority: high +``` + +Extract the YAML examples embedded in the spec documents and validate them +against the schemas in CI. If the spec changes and the schema does not, the +build breaks. + +## T06 - Build, CI and identifier conventions + +```task +id: FC-WP-0001-T06 +status: todo +priority: medium +``` + +Makefile, GitHub Actions (build, vet, test, schema validation), and the +identifier prefix helpers from schema doc §16: `H- R- E- P- BR- D- EV- F- C-`. + +## T07 - Architecture decision records + +```task +id: FC-WP-0001-T07 +status: todo +priority: medium +``` + +ADRs for: Go as the implementation language; out-of-process attachment; the +wire contract as boundary; SQLite to Postgres evidence store; and the revision +identity scheme, which Blueprint §54 leaves deliberately open. diff --git a/workplans/FC-WP-0002-deterministic-data-plane.md b/workplans/FC-WP-0002-deterministic-data-plane.md new file mode 100644 index 0000000..bb3b2ee --- /dev/null +++ b/workplans/FC-WP-0002-deterministic-data-plane.md @@ -0,0 +1,135 @@ +--- +id: FC-WP-0002 +type: workplan +title: "Deterministic data plane (Blueprint Phase A)" +domain: infotech +repo: fluid-core +status: active +owner: worsch +topic_slug: fluid +created: "2026-09-04" +updated: "2026-09-04" +planning_priority: high +planning_order: 2 +depends_on: + - FC-WP-0001 +--- + +# FC-WP-0002 - Deterministic data plane + +The production request path. No AI, no analysis, no dependency on the control +plane. Blueprint §5 and §34: the gateway must keep serving when everything +above it is dead. + +## T01 - Edge gateway + +```task +id: FC-WP-0002-T01 +status: todo +priority: high +``` + +Transport termination, correlation IDs, coarse rate limiting, request size and +shape limits. Blueprint §5.1 — the gateway must not invent interface semantics. + +## T02 - Revision resolver + +```task +id: FC-WP-0002-T02 +status: todo +priority: high +``` + +The §5.2 precedence chain: explicit revision, bound client contract, experiment +assignment, stable default. Every resolution records its reason; resolution +without an auditable reason is a defect. + +## T03 - Revision router + +```task +id: FC-WP-0002-T03 +status: todo +priority: high +``` + +Map a resolved revision to an adapter upstream. Reject unpublished, failed, +ineligible and retired revisions (§5.3). Allocation rules are deterministic and +read from routing policy the router does not author. + +## T04 - Contract validator + +```task +id: FC-WP-0002-T04 +status: todo +priority: high +``` + +OpenAPI 3.1 request and response validation (§5.4). The contract digest is part +of the revision artifact and is content-addressed. + +## T05 - Backend connector layer + +```task +id: FC-WP-0002-T05 +status: todo +priority: high +``` + +Timeout, retry, circuit breaker, error mapping, tenant propagation (§5.6). The +adapter is an upstream process reached over HTTP — this is where the +language-agnostic promise is kept. + +## T06 - Response policy + +```task +id: FC-WP-0002-T06 +status: todo +priority: medium +``` + +Structured errors carrying a FLUID correlation reference, leaking no backend +detail (§5.7). + +## T07 - Telemetry emitter + +```task +id: FC-WP-0002-T07 +status: todo +priority: high +``` + +Fire-and-forget emission. Blueprint §34.2 is a hard invariant: telemetry +backpressure must never block or slow a request. Test it under a stalled sink. + +## T08 - Evidence store + +```task +id: FC-WP-0002-T08 +status: todo +priority: high +``` + +Append-only event storage, SQLite for development and Postgres-ready. Mutable +summaries exist only as derived views (§26). + +## T09 - Intent store + +```task +id: FC-WP-0002-T09 +status: todo +priority: high +``` + +Bind every revision to an `InterfaceEvolutionIntent` version (§27), so audit can +later answer whether a change was valid under the intent that existed when it +was made. + +## T10 - Operator CLI, first commands + +```task +id: FC-WP-0002-T10 +status: todo +priority: medium +``` + +`fluid revision create|publish|list`, `fluid intent show`, `fluid events tail`. diff --git a/workplans/FC-WP-0003-publication-and-control-apis.md b/workplans/FC-WP-0003-publication-and-control-apis.md new file mode 100644 index 0000000..fe95bab --- /dev/null +++ b/workplans/FC-WP-0003-publication-and-control-apis.md @@ -0,0 +1,93 @@ +--- +id: FC-WP-0003 +type: workplan +title: "Revision publication pipeline and control APIs" +domain: infotech +repo: fluid-core +status: active +owner: worsch +topic_slug: fluid +created: "2026-09-04" +updated: "2026-09-04" +planning_priority: high +planning_order: 3 +depends_on: + - FC-WP-0002 +--- + +# FC-WP-0003 - Publication and control APIs + +Nothing reaches the router unsigned. The deterministic policy gate is built now, +before anything can generate candidates, so a future Daimon has nowhere to +bypass. + +## T01 - Publication pipeline + +```task +id: FC-WP-0003-T01 +status: todo +priority: high +``` + +Blueprint §35: SOURCE, BUILD, CONTRACT CHECK, TEST, SECURITY CHECK, POLICY +CHECK, SIGN, PUBLISH, ROUTE. Each stage emits an audit event. + +## T02 - Descriptor signing and verification + +```task +id: FC-WP-0003-T02 +status: todo +priority: high +``` + +The router accepts only signed or otherwise authenticated published revision +descriptors (§35). An unsigned descriptor must be refused, and that refusal +tested. + +## T03 - Revision API + +```task +id: FC-WP-0003-T03 +status: todo +priority: high +``` + +Blueprint §44.1: create, verify, publish, set state, query lineage. + +## T04 - Intent API + +```task +id: FC-WP-0003-T04 +status: todo +priority: medium +``` + +Blueprint §44.5: read active intent, read historical intent, validate a +candidate against intent, propose an amendment. Amendment stays separately +governed — the API records a proposal, it does not enact one. + +## T05 - Deterministic policy gate + +```task +id: FC-WP-0003-T05 +status: todo +priority: high +``` + +Blueprint §28.2. Allowed adaptation class, permitted operational mode, +complexity threshold, security status, test status, compatibility status, +traffic-allocation maximum, budget, approval requirement. This gate is the +architectural boundary that stops agentic reasoning from becoming security +policy. + +## T06 - Trust model in the type system + +```task +id: FC-WP-0003-T06 +status: todo +priority: medium +``` + +Blueprint §47 made mechanical: generated artifacts are an untrusted candidate +type until verification produces a signed revision. The compiler should make the +unsafe path awkward to write. diff --git a/workplans/FC-WP-0004-fluid-insight.md b/workplans/FC-WP-0004-fluid-insight.md new file mode 100644 index 0000000..0352db1 --- /dev/null +++ b/workplans/FC-WP-0004-fluid-insight.md @@ -0,0 +1,122 @@ +--- +id: FC-WP-0004 +type: workplan +title: "FLUID Insight - observation plane (Blueprint Phase B)" +domain: infotech +repo: fluid-core +status: active +owner: worsch +topic_slug: fluid +created: "2026-09-04" +updated: "2026-09-04" +planning_priority: high +planning_order: 4 +depends_on: + - FC-WP-0003 +--- + +# FC-WP-0004 - FLUID Insight + +Turn traffic into evidence. Deterministic heuristics only at this stage — no +model inference anywhere in this workplan. + +## T01 - Telemetry ingest and normalizer + +```task +id: FC-WP-0004-T01 +status: todo +priority: high +``` + +Request, error, sequence, adoption and explicit-feedback events into one +normalized interaction event (Blueprint §6.1). + +## T02 - Redaction and privacy filter + +```task +id: FC-WP-0004-T02 +status: todo +priority: high +``` + +Field exclusion, pseudonymization, tenant isolation, retention, cohort minimum +sizes (§6.2). Raw payload capture is off by default and must stay that way — +FLUID learns about the interface, not about people. + +## T03 - Cohort engine + +```task +id: FC-WP-0004-T03 +status: todo +priority: medium +``` + +Coarse, stable, comparable over time (§6.3). Resist granularity: cohorts should +not be more specific than the analysis requires. + +## T04 - Interaction topology analyzer + +```task +id: FC-WP-0004-T04 +status: todo +priority: high +``` + +Recurring call-sequence detection (§6.4) — the signal that makes FLUID more than +error counting. + +## T05 - Pressure classifier + +```task +id: FC-WP-0004-T05 +status: todo +priority: high +``` + +The ten pressure classes from §6.5. Classification retains evidence references +in every case. + +## T06 - Pressure registry + +```task +id: FC-WP-0004-T06 +status: todo +priority: high +``` + +Deduplication, aggregation, frequency, severity, confidence, and the §9 +lifecycle. Pressure may remain unresolved on purpose — not every mismatch +deserves adaptation. + +## T07 - Fitness engine + +```task +id: FC-WP-0004-T07 +status: todo +priority: high +``` + +Blueprint §18: primary metrics, guardrails, secondary and learning metrics kept +distinct. Baseline and measurement window are retained, never recomputed. + +## T08 - Explicit feedback collector + +```task +id: FC-WP-0004-T08 +status: todo +priority: medium +``` + +API Standards §15. Accepted over the wire, stored as evidence, and never +treated as authority to change anything. + +## T09 - CLI and pressure API + +```task +id: FC-WP-0004-T09 +status: todo +priority: medium +``` + +Blueprint §44.2 plus `fluid pressure list|show|dismiss`, `fluid cohort list`, +`fluid fitness compare`. diff --git a/workplans/FC-WP-0005-fluid-science.md b/workplans/FC-WP-0005-fluid-science.md new file mode 100644 index 0000000..c77259e --- /dev/null +++ b/workplans/FC-WP-0005-fluid-science.md @@ -0,0 +1,125 @@ +--- +id: FC-WP-0005 +type: workplan +title: "FLUID Science - the adaptation loop closes (Blueprint Phase C)" +domain: infotech +repo: fluid-core +status: active +owner: worsch +topic_slug: fluid +created: "2026-09-04" +updated: "2026-09-04" +planning_priority: high +planning_order: 5 +depends_on: + - FC-WP-0004 +--- + +# FC-WP-0005 - FLUID Science + +Hypotheses, experiments, fitness and promotion. Entirely human-driven — the +Daimon is deliberately absent. Blueprint §50 says the success criterion is +proving this loop works cleanly and safely, not autonomous coding. + +## T01 - Hypothesis records and lifecycle + +```task +id: FC-WP-0005-T01 +status: todo +priority: high +``` + +Schema doc §2: DRAFT, READY, PRIORITIZED, DESIGNING, EXPERIMENTING, EVALUATING, +then ACCEPTED, REJECTED, SUPERSEDED or DEFERRED. Keep observation, explanation, +prediction, intervention and result separate — schema doc §18 warns that +collapsing them into one narrative destroys criticism and auditability. + +## T02 - Competition groups + +```task +id: FC-WP-0005-T02 +status: todo +priority: medium +``` + +Rival explanations of one pressure coexist (schema doc §6). Preserving +uncertainty is a feature. + +## T03 - Hypothesis API + +```task +id: FC-WP-0005-T03 +status: todo +priority: medium +``` + +Blueprint §44.3: create, compare, prioritize, attach candidate, record outcome. + +## T04 - Experiment controller + +```task +id: FC-WP-0005-T04 +status: todo +priority: high +``` + +Blueprint §16. Declares hypothesis, control, candidate, cohorts, allocation, +metrics, guardrails, start and stop conditions, maximum duration. Per §17 it +must not touch traffic directly: it writes routing policy the router consumes. +Experiments are interruptible. + +## T05 - Experiment API + +```task +id: FC-WP-0005-T05 +status: todo +priority: medium +``` + +Blueprint §44.4: create, start, change bounded allocation, stop, record metrics, +finalize. + +## T06 - Fitness evaluation against hypotheses + +```task +id: FC-WP-0005-T06 +status: todo +priority: high +``` + +Wire the fitness engine to experiments. Success criteria may not be changed +after results are visible without recording the amendment (§18). + +## T07 - Promotion controller + +```task +id: FC-WP-0005-T07 +status: todo +priority: high +``` + +PROMOTE, EXPAND_EXPERIMENT, RETAIN_AS_OPTION, MODIFY, REVERT, ABANDON, DEFER +recorded as decisions with an authorizing actor (§19). Human authority only. + +## T08 - Append-only event log + +```task +id: FC-WP-0005-T08 +status: todo +priority: high +``` + +Every transition above as a `fluid_event` (schema doc §15). FLUID evolution is +itself a system behavior that must remain reconstructable. + +## T09 - Audit trace command + +```task +id: FC-WP-0005-T09 +status: todo +priority: high +``` + +`fluid audit trace ` reconstructs pressure, hypothesis, revision, +experiment, fitness and decision, answering all eleven questions in API +Standards §25. diff --git a/workplans/FC-WP-0006-conformance-and-self-validation.md b/workplans/FC-WP-0006-conformance-and-self-validation.md new file mode 100644 index 0000000..93cbf42 --- /dev/null +++ b/workplans/FC-WP-0006-conformance-and-self-validation.md @@ -0,0 +1,90 @@ +--- +id: FC-WP-0006 +type: workplan +title: "Conformance suite and self-validation" +domain: infotech +repo: fluid-core +status: active +owner: worsch +topic_slug: fluid +created: "2026-09-04" +updated: "2026-09-04" +planning_priority: high +planning_order: 6 +depends_on: + - FC-WP-0005 +--- + +# FC-WP-0006 - Conformance and self-validation + +Prove the loop mechanically before a real workload depends on it. Everything +here runs in CI with no human steps and no external services. + +## T01 - Echo interface fixture + +```task +id: FC-WP-0006-T01 +status: todo +priority: high +``` + +`examples/echo-interface` — two revisions, R-1 deliberately inefficient +(list then filter), R-2 the convenience form. This is the smallest honest +reproduction of the Blueprint §33 worked example. + +## T02 - Minimal conformance assertions + +```task +id: FC-WP-0006-T02 +status: todo +priority: high +``` + +The seven requirements of API Standards §36, asserted as tests rather than +claimed in a README. + +## T03 - Architectural invariant checks + +```task +id: FC-WP-0006-T03 +status: todo +priority: high +``` + +The mechanically checkable subset of Blueprint §55. Invariant 2 (evolution can +stop without stopping the API) and invariant 9 (AI-generated artifacts untrusted +until verified) matter most and get dedicated tests. + +## T04 - Failure containment matrix + +```task +id: FC-WP-0006-T04 +status: todo +priority: high +``` + +Blueprint §34. Kill the control plane, the evidence store and the telemetry +pipeline in turn; assert the data plane keeps serving from cached published +configuration each time. + +## T05 - End-to-end loop in CI + +```task +id: FC-WP-0006-T05 +status: todo +priority: high +``` + +The full §50 vertical slice automated: two revisions, a 90/10 experiment, +fitness comparison, promotion, complete audit trail. + +## T06 - Integration guide + +```task +id: FC-WP-0006-T06 +status: todo +priority: medium +``` + +`docs/integration-guide.md` — how to put an existing API of any stack behind +fluid-core without modifying it. diff --git a/workplans/FC-WP-0007-fluid-telegram-handover.md b/workplans/FC-WP-0007-fluid-telegram-handover.md new file mode 100644 index 0000000..f52545c --- /dev/null +++ b/workplans/FC-WP-0007-fluid-telegram-handover.md @@ -0,0 +1,142 @@ +--- +id: FC-WP-0007 +type: workplan +title: "Handover: HelixForge Telegram identity and hall-of-helix channel" +domain: infotech +repo: fluid-core +status: active +owner: worsch +topic_slug: fluid +created: "2026-09-04" +updated: "2026-09-04" +planning_priority: high +planning_order: 7 +depends_on: + - FC-WP-0006 +related_repos: + - fluid-telegram + - helix-forge + - hall-of-helix +--- + +# FC-WP-0007 - Handover to fluid-telegram + +The point of the whole sequence. Establish a Telegram identity for HelixForge +and a channel publishing hall-of-helix entries, as the first real FLUID +interface. Outbound-first: agents and publishing jobs are the consumers, +Telegram is the backend. + +Deliverables land in `docs/handover/fluid-telegram.md` here and as `FT-WP-0001` +in the `fluid-telegram` repository. + +## T01 - Interface evolution intent + +```task +id: FC-WP-0007-T01 +status: todo +priority: high +``` + +Fill the template for `helix-forge-telegram-publishing`. Parent intent is +`helix-forge/INTENT.md`. Initial authority mode FLUID-2 (advisory): the Daimon +may propose and never generate or promote. Out of scope for now: inbound +commands, payments, Mini Apps, moderation. Non-authority: never create Telegram +entities, change membership, or touch credentials. + +## T02 - Bot identity + +```task +id: FC-WP-0007-T02 +status: todo +priority: high +``` + +**Human step.** Register the HelixForge bot via BotFather (Canon BOT-01). Store +the token in OpenBao per Canon SEC-04, consistent with HF-WP-0002. The token +never enters the repository; the adapter receives only that credential, per +Blueprint §28.1 runtime identity. + +## T03 - Channels + +```task +id: FC-WP-0007-T03 +status: todo +priority: high +``` + +**Human step.** Create a private test channel first, then the public +hall-of-helix channel (Canon PUB-01). Bot is administrator with post rights +only. All verification runs against the private channel before anything is +published publicly. + +## T04 - Revision R-1 contract + +```task +id: FC-WP-0007-T04 +status: todo +priority: high +``` + +`POST /v1/hall-entries` (idempotent on entry id) and +`GET /v1/hall-entries/{id}`. OpenAPI plus signed revision descriptor. + +## T05 - Telegram adapter and connector contract + +```task +id: FC-WP-0007-T05 +status: todo +priority: high +``` + +Map a `hall-of-helix/entries/*.md` file to a Telegram post. The adapter is a +separate process and may be written in whatever suits the platform. Declare the +connector capability contract: identity, auth, timeouts, retry, rate limits, +error mapping. + +## T06 - Cohorts, telemetry and redaction + +```task +id: FC-WP-0007-T06 +status: todo +priority: high +``` + +Subscriber classes and agent consumers as cohorts. Redaction rules that keep +Telegram user identity (Canon ID-01) out of the evidence store entirely. + +## T07 - First competing hypotheses + +```task +id: FC-WP-0007-T07 +status: todo +priority: high +``` + +Telegram's 4096-character message limit against long-form entries is the first +genuine pressure. Two presentation adaptations compete: H-A, teaser plus link +back to the hall; H-B, full entry serialized as a multi-part rich post +(Canon PUB-02/MED-02). Blueprint §37 argues presentation is the safest and +highest-value place to start. + +## T08 - Live experiment and audit + +```task +id: FC-WP-0007-T08 +status: todo +priority: high +``` + +R-2 and R-3 implement H-A and H-B. Run the experiment on real subscriber +traffic, measure read-through and reaction, and confirm `fluid audit trace` +reconstructs the whole chain. This is the §50 slice on a real workload. + +## T09 - Runbook and handover package + +```task +id: FC-WP-0007-T09 +status: todo +priority: medium +``` + +Token rotation, channel admin recovery, rollback to R-1, and the assembled +handover document.