diff --git a/SCOPE.md b/SCOPE.md index d720a7b..e8e234f 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,32 +1,118 @@ # SCOPE -> This file was generated by `statehub register`. Refine it as the repository -> boundaries become clearer. - ## One-liner -Core framework for fluid interfaces to provide adaptive robust systems capability integration. +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 -fluid-core exists to provide the capability described in INTENT.md. +**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 -- Maintain the repository's primary implementation. -- Keep docs, tests, and operational metadata current. +**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 -- Own unrelated adjacent systems. -- Make irreversible operational decisions without human approval. +- **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 -- Status: active; implementation and stability should be verified by the repo agent. +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 -- Start with: INTENT.md -- Agent instructions: AGENTS.md -- Workplans: workplans/ +- 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/` diff --git a/workplans/FLUID-WP-0009-campaign-repos-and-example-separation.md b/workplans/FLUID-WP-0009-campaign-repos-and-example-separation.md index 0f5dc3a..037bb7a 100644 --- a/workplans/FLUID-WP-0009-campaign-repos-and-example-separation.md +++ b/workplans/FLUID-WP-0009-campaign-repos-and-example-separation.md @@ -67,7 +67,7 @@ consumes one or more `fluid-*` interfaces and owns none of them. ```task id: FLUID-WP-0009-T02 -status: todo +status: progress priority: medium state_hub_task_id: "7d40da89-9a4d-5358-ae2b-7a1a1339efff" ``` @@ -76,6 +76,20 @@ Create the repository and move the campaign into it, per `FT-WP-0001` T13. The split is already written there; this task is the execution and the registration with the State Hub under the `infotech` domain. +**Partly done, ahead of the sequencing above (2026-09-04).** The repository +exists, is registered (domain `infotech`, topic `helix-forge`, prefix +`PRHOH-WP-`), and carries a grounded `INTENT.md` and `SCOPE.md` plus the declared +Telegram presence at `presence/telegram.yaml`. + +It was created early because provisioning needed somewhere to put the presence +spec — a bot's name and a channel's title are editorial, and putting them in the +delivery interface would have cut the seam in the wrong place immediately. + +What remains is the part the sequencing was actually protecting: **the campaign +itself has not moved.** Composition and the review queue still live in +`fluid-telegram` under `FT-WP-0001` T06/T07, and should stay there until the loop +has closed once (T12), as `FT-WP-0001` T13 says. + The campaign becomes a consumer of `fluid-telegram` in cohort `hall-publishing-jobs`, and runs its own FLUID loop over its own artifacts — which composition variant travels — using the per-variant engagement the