fluid-core/SCOPE.md

SCOPE

One-liner

The reference implementation of FLUID: the deterministic data plane, the observation plane, and the evolution control plane through Blueprint Phase C — attached to any API out of process, through a wire contract.

Core Idea

Deterministic execution, adaptive evolution (spec/FluidAPIStandards.md §3).

The production request path stays deterministic and auditable. Observation, analysis, hypothesis formation, experimentation and promotion happen around the interface, never inside the request path. fluid-core is what makes that separation real rather than aspirational: the control plane can be killed in production and the API keeps serving.

The framework is attached, not imported. A target API contributes no code, links no library, and may be written in any stack.

In Scope

The deterministic data plane — gateway, revision resolver, revision router, contract validation, backend connectors, response policy, telemetry emission. internal/runtime (the gateway is a library; cmd/fluid-gateway is reserved and empty), internal/contract, internal/validate, internal/policy.

The observation plane — telemetry ingest, redaction, cohorts, interaction topology, pressure classification. internal/observation.

The evolution control plane through Phase C — pressure registry, hypothesis records, experiment control, fitness evaluation, promotion decisions. internal/experiment, internal/fitness, internal/promotion, internal/science.

The stores — evidence, artifact and intent. internal/evidence, internal/intent.

The wire contract by which any interface, in any language, becomes FLUID: the revision descriptor (Blueprint §36), the routing policy (§17), the telemetry envelope, and the control APIs (§44). The JSON Schemas in schemas/ are the normative form; Go types are generated from them, never the reverse.

The specification — spec/ArchitectureBlueprint.md, spec/FluidAPIStandards.md, spec/FluidHypothesisRevisionSchema.md, spec/InterfaceEvolutionIntent.md. The sixteen invariants in Blueprint §55 are constitutional here.

Operator surfaces — cmd/fluid (reads and writes the evidence store directly, so an audit still works when the control plane is down) and cmd/fluid-control (publishes revisions, records governance decisions; not on the request path).

Conformance — conformance/, asserting every conformance requirement and architectural invariant, including the deliberate cross-repository handover test.

Integration documentation — docs/integration-guide.md, docs/adr/, docs/handover/, and examples/echo-interface as the general worked example.

Out of Scope

• The interfaces themselves. Those live in consumer repositories: fluid-telegram, and the planned fluid-x and fluid-substack. fluid-core never contains an adapter for a particular platform.
• Campaigns. What to say, to whom, and when belongs in pr- repositories (pr-hall-of-helix). A campaign is a consumer of an interface, and the framework must not know about one.
• Backend systems reached through connectors, and their authority. Missing backend capability is escalated as a structured requirement, never taken — Blueprint invariant on backend authority.
• The Daimon's generative capability (Phase D). Deliberately deferred until real telemetry exists for it to learn from. Deferred, not abandoned; building it early would mean training a generator on nothing.
• Any LLM in the mandatory request path. Not a performance decision — a determinism invariant, and the one most often eroded by convenience.
• Go types across the boundary. Any change that leaks them is a design failure (INTENT.md §4). It is what allows adapters, Daimons and future gateways to be written in whatever language suits them.

Boundary Tests

Three questions that settle most "does this belong here?" arguments:

1. Could the control plane be killed in production, right now, with no runtime effect? If a change makes the answer no, it is in the wrong plane.
2. Does this require the target API to change, link, or import anything? If yes, it violates out-of-process attachment (ADR-0002, ADR-0003).
3. Would this be here if the Hall of Helix did not exist? If no, it is a campaign concern wearing framework clothes. FLUID-WP-0009 T03 audits exactly this, on the grounds that the couplings are easier to find deliberately than to argue about in advance.

Current State

Active. The data plane, publication and control APIs, insight, science and the conformance suite have their own workplans (FLUID-WP-0002 … FLUID-WP-0007). FLUID-WP-0008 hands the first real interface over to fluid-telegram; FLUID-WP-0009 establishes the pr- campaign pattern and audits what the framework accidentally assumes about its first consumer.

The honest limitation: there is still only one worked consumer. Until a second interface goes from empty capability canon to a published R-1 (FLUID-WP-0009 T05), claims of generality are untested. That test is the point of the workplan, and its findings are expected to be uncomfortable.

Registered with the Custodian State Hub: domain infotech, repo topic helix-forge, workplan prefix FLUID-WP-. Workplan records currently index under the custodian topic; query by repo (0f681685-7bc0-41b9-97fb-50073ebf6cf4) rather than by helix-forge.

Getting Oriented

• Why it exists, and the invariants it defends: INTENT.md
• The architecture: spec/ArchitectureBlueprint.md (§55 for the invariants)
• The standard: spec/FluidAPIStandards.md (§3 determinism, §25 auditability)
• Attaching an API: docs/integration-guide.md, then examples/echo-interface
• Decisions and their reasons: docs/adr/
• A real interface, end to end: docs/handover/fluid-telegram.md
• Agent instructions: AGENTS.md
• Workplans: workplans/