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.
`cmd/fluid-gateway`, `internal/runtime`, `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`, topic `helix-forge`,
workplan prefix `FLUID-WP-`.

## 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/`