diff --git a/.custodian-brief.md b/.custodian-brief.md deleted file mode 100644 index 8a453ad..0000000 --- a/.custodian-brief.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Custodian Brief - fluid-core - -**Project:** fluid-core -**Domain:** infotech -**State Hub:** http://127.0.0.1:8000 -**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` - -## Open Workplans - -### Bootstrap State Hub integration - -Workplan file: `workplans/FLUID-WP-0001-statehub-bootstrap.md` - -Open tasks: -- T01 - Review generated integration files -- T02 - Verify local developer workflow -- T03 - Seed first real workplan - -## Session Start - -1. Read `INTENT.md`, `SCOPE.md`, and `AGENTS.md`. -2. Check inbox: `GET /messages/?to_agent=fluid-core&unread_only=true`. -3. Scan `workplans/`. -4. Update task statuses in workplan files as work progresses. - -Last generated: 2026-09-04 diff --git a/.gitignore b/.gitignore deleted file mode 100644 index 696d896..0000000 --- a/.gitignore +++ /dev/null @@ -1,10 +0,0 @@ -/bin/ -*.db -*.sqlite -.env - -# state-hub: track .claude/rules -# Claude Code local state (track shared rules; ignore machine-specific files) -.claude/* -!.claude/rules/ -!.claude/rules/*.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 6e7ed9d..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,205 +0,0 @@ -# fluid-core — Agent Instructions - -## Repo Identity - -**Purpose:** Core framework for fluid interfaces to provide adaptive robust systems capability integration. - -**Domain:** infotech -**Repo slug:** fluid-core -**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` -**Workplan prefix:** `FLUID-WP-` - ---- - -## State Hub Integration - -The Custodian State Hub tracks work across all domains. Codex uses HTTP REST and -the `statehub` CLI by default. MCP is opt-in because the current Codex MCP bridge -adds severe call latency; the full administrative MCP surface remains available -to clients that need it. - -| Context | URL | -|---------|-----| -| Local workstation | `http://127.0.0.1:8000` | -| Remote via tunnel | `http://127.0.0.1:18000` | -| Optional local edge relay | http://127.0.0.1:18080 | - -When an operator has enabled the edge relay, set API_BASE to the relay URL. -Queueable writes return an explicit queued receipt if the central hub is -unreachable. Treat that as pending local evidence, then ask the operator to run -statehub outbox status/replay after connectivity returns. - -Codex workspace-write sandboxes need network access enabled to reach the host's -loopback listener. Bootstrap this once with `make -C ~/state-hub configure-codex` -and restart Codex. The canonical REST health endpoint is `/state/health`, not -`/health`. If a sandboxed loopback probe fails, retry it with escalated execution -before declaring State Hub unavailable; a managed Codex permission profile may -still enforce isolated networking. Experimental MCP can be enabled explicitly -with `make -C ~/state-hub configure-codex WITH_MCP=1`. - -### Orient at session start - -```bash -# Offline brief — works without hub connection -cat .custodian-brief.md - -# Active workplans for this domain -curl -s "http://127.0.0.1:8000/workplans/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \ - | python3 -m json.tool - -# Check inbox -curl -s "http://127.0.0.1:8000/messages/?to_agent=fluid-core&unread_only=true" \ - | python3 -m json.tool -``` - -Mark a message read: -```bash -curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ - -H "Content-Type: application/json" -d '{}' -``` - -### Log progress (required at session close) - -```bash -curl -s -X POST http://127.0.0.1:8000/progress/ \ - -H "Content-Type: application/json" \ - -d '{ - "summary": "what was done", - "event_type": "note", - "author": "codex", - "workplan_id": "", - "task_id": "" - }' -``` - -Omit `workplan_id` / `task_id` when not applicable. - -### Update task status - -```bash -curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ - -H "Content-Type: application/json" \ - -d '{"status": "progress"}' -# values: wait | todo | progress | done | cancel -``` - -### Flag a task for human review - -```bash -curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ - -H "Content-Type: application/json" \ - -d '{"needs_human": true, "intervention_note": "reason"}' -``` - ---- - -## Session Protocol - -**Start:** -1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe) -2. Check inbox: `GET /messages/?to_agent=fluid-core&unread_only=true`; mark read -3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks -4. Check human-needed tasks: `GET /tasks/?needs_human=true` - -**During work:** -- Update task statuses in workplan files as tasks progress -- Record significant decisions via `POST /decisions/` - -**Close:** -1. Update workplan file task statuses to reflect progress -2. If finishing a workplan: hand off **residuals** as live work records first - (intake with `origin: residual` + `origin_ref: `, or a next workplan / - decision / engagement). Do not park leftovers only in prose or `SCOPE.md`. - Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals. -3. Log: `POST /progress/` with a summary of what changed (name handoff ids) -4. After workplan file changes, run: - ```bash - uv run --project ~/repo-manager rmgr sync --path . --push - ``` - This assigns only missing deterministic identifiers, verifies the pushed - Forgejo commit and `primary/railliance01`, then requests one central - reconciliation. A queued receipt is pending evidence; rerun after - connectivity returns. Use `statehub fix-consistency` for a separate deep audit. - ---- - -{CREDENTIAL_ROUTING} - - - - ---- - -## Workplan Convention (ADR-001) - -Work items originate as files in this repo — not in the hub. The hub is a -read/cache/index layer that rebuilds from files. - -**File location:** `workplans/FLUID-WP-NNNN-.md` - -**Archived location:** finished workplans may move to -`workplans/archived/YYMMDD-FLUID-WP-NNNN-.md`. The `YYMMDD` prefix is -the completion/archive date; the frontmatter `id` does not change. - -**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use -`workplans/ADHOC-YYYY-MM-DD.md`, workplan id -`FLUID-WP-ADHOC-YYYY-MM-DD`, and task ids -`FLUID-WP-ADHOC-YYYY-MM-DD-T01`, etc. `FLUID-WP` includes its final `-WP` -token. Unqualified historic `ADHOC-*` ids are grandfathered and must not be -copied into new records. Use this only for low-risk work completed directly; -create a normal workplan for anything needing analysis, design, approval, -dependencies, or multiple phases. - -**Frontmatter:** - -```yaml ---- -id: FLUID-WP-NNNN -type: workplan -title: "..." -domain: infotech -repo: fluid-core -status: proposed | ready | active | blocked | backlog | finished | archived -owner: codex -topic_slug: ... -created: "YYYY-MM-DD" -updated: "YYYY-MM-DD" -state_hub_workstream_id: "" # deterministic UUIDv5; managed by Repo Manager ---- -``` - -Use `proposed` for a new draft, `ready` after review against current repo -state, and `finished` after implementation. `stalled` and `needs_review` are -derived health labels, not frontmatter statuses. - -**Terminology:** workplan is the fleet term; `workstream` appears only in legacy -API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see -`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. - -**Task block format** (one per `##` section): - -``` -## Task Title - -` ` `task -id: FLUID-WP-NNNN-T01 -status: wait | todo | progress | done | cancel -priority: high | medium | low -state_hub_task_id: "" # deterministic UUIDv5; managed by Repo Manager -` ` ` - -Task description text. -``` - -Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. - -**Residuals when finishing:** actionable leftovers become live work records -before `status: finished` — usually an intake (`origin: residual`, -`origin_ref: FLUID-WP-NNNN`) or a spawned workplan. Residual is a *role*, -not a kind. Fleet list lives on State Hub, not in `SCOPE.md`. - -To create a new workplan: -1. Write the file following the format above -2. Run `uv run --project ~/repo-manager rmgr sync --path . --push`. -3. Run `statehub fix-consistency` only when a separate deep audit is needed. diff --git a/INTENT.md b/INTENT.md deleted file mode 100644 index f6926ae..0000000 --- a/INTENT.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -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/SCOPE.md b/SCOPE.md deleted file mode 100644 index d720a7b..0000000 --- a/SCOPE.md +++ /dev/null @@ -1,32 +0,0 @@ -# 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. - -## Core Idea - -fluid-core exists to provide the capability described in INTENT.md. - -## In Scope - -- Maintain the repository's primary implementation. -- Keep docs, tests, and operational metadata current. - -## Out of Scope - -- Own unrelated adjacent systems. -- Make irreversible operational decisions without human approval. - -## Current State - -- Status: active; implementation and stability should be verified by the repo agent. - -## Getting Oriented - -- Start with: INTENT.md -- Agent instructions: AGENTS.md -- Workplans: workplans/ diff --git a/go.mod b/go.mod deleted file mode 100644 index c33a0cd..0000000 --- a/go.mod +++ /dev/null @@ -1,3 +0,0 @@ -module github.com/tegwick/fluid-core - -go 1.22.2 diff --git a/history/260820-ideaFluidInterfaces.md b/history/260820-ideaFluidInterfaces.md deleted file mode 100644 index d83dd6d..0000000 --- a/history/260820-ideaFluidInterfaces.md +++ /dev/null @@ -1,14 +0,0 @@ -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 deleted file mode 100755 index 258a64b..0000000 --- a/spec/ArchitectureBlueprint.md +++ /dev/null @@ -1,2362 +0,0 @@ -# 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 deleted file mode 100755 index 904c0c6..0000000 --- a/spec/FluidAPIStandards.md +++ /dev/null @@ -1,1150 +0,0 @@ -# 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 deleted file mode 100755 index 748289e..0000000 --- a/spec/FluidHypothesisRevisionSchema.md +++ /dev/null @@ -1,773 +0,0 @@ -# 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 deleted file mode 100755 index a17b025..0000000 --- a/spec/InterfaceEvolutionIntent.md +++ /dev/null @@ -1,505 +0,0 @@ -# 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/FLUID-WP-0001-statehub-bootstrap.md b/workplans/FLUID-WP-0001-statehub-bootstrap.md deleted file mode 100644 index 621ff2e..0000000 --- a/workplans/FLUID-WP-0001-statehub-bootstrap.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -id: FLUID-WP-0001 -type: workplan -title: "Bootstrap State Hub integration" -domain: infotech -repo: fluid-core -status: ready -owner: worsch -topic_slug: fluid-core -created: "2026-09-04" -updated: "2026-09-04" ---- - -# Bootstrap State Hub integration - -Core framework for fluid interfaces to provide adaptive robust systems capability integration. - -## Review Generated Integration Files - -```task -id: FLUID-WP-0001-T01 -status: todo -priority: high -``` - -Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. -Replace generated placeholders with repo-specific facts where needed. - -## Verify Local Developer Workflow - -```task -id: FLUID-WP-0001-T02 -status: todo -priority: high -``` - -Identify the repo's install, test, lint, build, and run commands. Add or refine -those commands in the agent instructions so future coding sessions can verify -changes confidently. - -## Seed First Real Workplan - -```task -id: FLUID-WP-0001-T03 -status: todo -priority: medium -``` - -Create the first implementation workplan for the repository's most important -next change. After workplan file updates, run the sync locally from this repo -checkout: - -```bash -statehub fix-consistency -``` diff --git a/workplans/FLUID-WP-0002-foundations-and-wire-contract.md b/workplans/FLUID-WP-0002-foundations-and-wire-contract.md deleted file mode 100644 index a861797..0000000 --- a/workplans/FLUID-WP-0002-foundations-and-wire-contract.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -id: FLUID-WP-0002 -type: workplan -title: "FLUID foundations and the wire contract" -domain: infotech -repo: fluid-core -status: active -owner: worsch -topic_slug: fluid-core -created: "2026-09-04" -updated: "2026-09-04" -planning_priority: high -planning_order: 1 -related_repos: - - fluid-telegram - - fluid-x - - fluid-substack ---- - -# FLUID-WP-0002 - 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: FLUID-WP-0002-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: FLUID-WP-0002-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: FLUID-WP-0002-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: FLUID-WP-0002-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: FLUID-WP-0002-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: FLUID-WP-0002-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: FLUID-WP-0002-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/FLUID-WP-0003-deterministic-data-plane.md b/workplans/FLUID-WP-0003-deterministic-data-plane.md deleted file mode 100644 index 3d2d9d9..0000000 --- a/workplans/FLUID-WP-0003-deterministic-data-plane.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -id: FLUID-WP-0003 -type: workplan -title: "Deterministic data plane (Blueprint Phase A)" -domain: infotech -repo: fluid-core -status: active -owner: worsch -topic_slug: fluid-core -created: "2026-09-04" -updated: "2026-09-04" -planning_priority: high -planning_order: 2 -depends_on: - - FLUID-WP-0002 ---- - -# FLUID-WP-0003 - 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: FLUID-WP-0003-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: FLUID-WP-0003-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: FLUID-WP-0003-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: FLUID-WP-0003-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: FLUID-WP-0003-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: FLUID-WP-0003-T06 -status: todo -priority: medium -``` - -Structured errors carrying a FLUID correlation reference, leaking no backend -detail (§5.7). - -## T07 - Telemetry emitter - -```task -id: FLUID-WP-0003-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: FLUID-WP-0003-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: FLUID-WP-0003-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: FLUID-WP-0003-T10 -status: todo -priority: medium -``` - -`fluid revision create|publish|list`, `fluid intent show`, `fluid events tail`. diff --git a/workplans/FLUID-WP-0004-publication-and-control-apis.md b/workplans/FLUID-WP-0004-publication-and-control-apis.md deleted file mode 100644 index ffe206a..0000000 --- a/workplans/FLUID-WP-0004-publication-and-control-apis.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -id: FLUID-WP-0004 -type: workplan -title: "Revision publication pipeline and control APIs" -domain: infotech -repo: fluid-core -status: active -owner: worsch -topic_slug: fluid-core -created: "2026-09-04" -updated: "2026-09-04" -planning_priority: high -planning_order: 3 -depends_on: - - FLUID-WP-0003 ---- - -# FLUID-WP-0004 - 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: FLUID-WP-0004-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: FLUID-WP-0004-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: FLUID-WP-0004-T03 -status: todo -priority: high -``` - -Blueprint §44.1: create, verify, publish, set state, query lineage. - -## T04 - Intent API - -```task -id: FLUID-WP-0004-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: FLUID-WP-0004-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: FLUID-WP-0004-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/FLUID-WP-0005-fluid-insight.md b/workplans/FLUID-WP-0005-fluid-insight.md deleted file mode 100644 index 85759a6..0000000 --- a/workplans/FLUID-WP-0005-fluid-insight.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -id: FLUID-WP-0005 -type: workplan -title: "FLUID Insight - observation plane (Blueprint Phase B)" -domain: infotech -repo: fluid-core -status: active -owner: worsch -topic_slug: fluid-core -created: "2026-09-04" -updated: "2026-09-04" -planning_priority: high -planning_order: 4 -depends_on: - - FLUID-WP-0004 ---- - -# FLUID-WP-0005 - 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: FLUID-WP-0005-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: FLUID-WP-0005-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: FLUID-WP-0005-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: FLUID-WP-0005-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: FLUID-WP-0005-T05 -status: todo -priority: high -``` - -The ten pressure classes from §6.5. Classification retains evidence references -in every case. - -## T06 - Pressure registry - -```task -id: FLUID-WP-0005-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: FLUID-WP-0005-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: FLUID-WP-0005-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: FLUID-WP-0005-T09 -status: todo -priority: medium -``` - -Blueprint §44.2 plus `fluid pressure list|show|dismiss`, `fluid cohort list`, -`fluid fitness compare`. diff --git a/workplans/FLUID-WP-0006-fluid-science.md b/workplans/FLUID-WP-0006-fluid-science.md deleted file mode 100644 index 613ef6f..0000000 --- a/workplans/FLUID-WP-0006-fluid-science.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -id: FLUID-WP-0006 -type: workplan -title: "FLUID Science - the adaptation loop closes (Blueprint Phase C)" -domain: infotech -repo: fluid-core -status: active -owner: worsch -topic_slug: fluid-core -created: "2026-09-04" -updated: "2026-09-04" -planning_priority: high -planning_order: 5 -depends_on: - - FLUID-WP-0005 ---- - -# FLUID-WP-0006 - 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: FLUID-WP-0006-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: FLUID-WP-0006-T02 -status: todo -priority: medium -``` - -Rival explanations of one pressure coexist (schema doc §6). Preserving -uncertainty is a feature. - -## T03 - Hypothesis API - -```task -id: FLUID-WP-0006-T03 -status: todo -priority: medium -``` - -Blueprint §44.3: create, compare, prioritize, attach candidate, record outcome. - -## T04 - Experiment controller - -```task -id: FLUID-WP-0006-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: FLUID-WP-0006-T05 -status: todo -priority: medium -``` - -Blueprint §44.4: create, start, change bounded allocation, stop, record metrics, -finalize. - -## T06 - Fitness evaluation against hypotheses - -```task -id: FLUID-WP-0006-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: FLUID-WP-0006-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: FLUID-WP-0006-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: FLUID-WP-0006-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/FLUID-WP-0007-conformance-and-self-validation.md b/workplans/FLUID-WP-0007-conformance-and-self-validation.md deleted file mode 100644 index 971028c..0000000 --- a/workplans/FLUID-WP-0007-conformance-and-self-validation.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -id: FLUID-WP-0007 -type: workplan -title: "Conformance suite and self-validation" -domain: infotech -repo: fluid-core -status: active -owner: worsch -topic_slug: fluid-core -created: "2026-09-04" -updated: "2026-09-04" -planning_priority: high -planning_order: 6 -depends_on: - - FLUID-WP-0006 ---- - -# FLUID-WP-0007 - 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: FLUID-WP-0007-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: FLUID-WP-0007-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: FLUID-WP-0007-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: FLUID-WP-0007-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: FLUID-WP-0007-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: FLUID-WP-0007-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/FLUID-WP-0008-fluid-telegram-handover.md b/workplans/FLUID-WP-0008-fluid-telegram-handover.md deleted file mode 100644 index 3b3cbe1..0000000 --- a/workplans/FLUID-WP-0008-fluid-telegram-handover.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -id: FLUID-WP-0008 -type: workplan -title: "Handover: HelixForge Telegram identity and hall-of-helix channel" -domain: infotech -repo: fluid-core -status: active -owner: worsch -topic_slug: fluid-core -created: "2026-09-04" -updated: "2026-09-04" -planning_priority: high -planning_order: 7 -depends_on: - - FLUID-WP-0007 -related_repos: - - fluid-telegram - - helix-forge - - hall-of-helix ---- - -# FLUID-WP-0008 - 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: FLUID-WP-0008-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: FLUID-WP-0008-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: FLUID-WP-0008-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: FLUID-WP-0008-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: FLUID-WP-0008-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: FLUID-WP-0008-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: FLUID-WP-0008-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: FLUID-WP-0008-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: FLUID-WP-0008-T09 -status: todo -priority: medium -``` - -Token rotation, channel admin recovery, rollback to R-1, and the assembled -handover document.