tegwick c2cfe86d88 Establish fluid-core scaffold, intent, and phased workplans

Adds the repository structure, INTENT.md declaring the wire-contract
boundary, and seven workplans covering Blueprint Phases A-C plus the
fluid-telegram handover.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014KmVxhJ35tCo7rE7UnLwWu

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 1116572@bnt-lap001
Assistant-Session: 8ba9bb93-a72a-4883-b189-2499cce5c400

2026-09-04 01:49:12 +02:00

46 KiB

Executable file

Raw Blame History

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:

                         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.

┌────────────────────────────────────────────────────────────┐
│                     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:

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:

Edge Gateway
Revision Resolver
Revision Router
Contract Validator
Deterministic Adapter Runtime
Backend Connector Layer
Response Policy
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:

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:

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:

Telemetry Ingest
Event Normalizer
Privacy / Redaction Filter
Interaction Topology Analyzer
Consumer Cohort Engine
Explicit Feedback Collector
Pressure Classifier
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:

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:

GET customer
GET invoices
GET payments
GET contracts

or:

GET invoices
sort locally
discard N-1 records

or:

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:

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:

Pressure Registry
Hypothesis Engine
Hypothesis Competition Manager
Optimization Policy
Complexity Evaluator
Candidate Planner
Builder
Verification Controller
Experiment Controller
Fitness Evaluator
Promotion Controller
Migration Controller
Backend Requirement Broker
Evolution Velocity Controller
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:

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:

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:

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:

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:

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:

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:

useful capability growth

from:

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:

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:

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:

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:

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:

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:

Pressure
Hypothesis
Revision
Experiment
Event

Later additions MAY include:

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:

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.

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:

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:

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.

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:

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:

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:

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:

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:

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:

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:

GET /customers/{id}/invoices

Consumers repeatedly:

retrieve all invoices;
sort them;
select the newest one.

The FLUID loop becomes:

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:

no new hypotheses or adaptations

Runtime effect:

none

34.2 Telemetry Pipeline Failure

Effect:

reduced learning

Runtime effect:

none, except optional observability degradation

Telemetry backpressure MUST NOT block normal API requests.

34.3 Builder Failure

Effect:

candidate not produced

Runtime effect:

none

34.4 Verification Failure

Effect:

candidate rejected

Runtime effect:

none

34.5 Experiment Failure

Effect:

candidate traffic removed

Runtime response:

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:

adaptive processes pause or degrade

Runtime effect:

none

35. Revision Publication Model

A revision SHOULD progress through a controlled publication pipeline.

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:

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:

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:

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:

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:

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:

FluidInterface
FluidRevision
FluidPressure
FluidHypothesis
FluidExperiment
FluidBackendRequirement
FluidOptimizationPolicy
FluidMigration

Example:

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:

create revision
verify revision
publish revision
set revision state
query revision lineage

44.2 Pressure API

Operations:

record pressure
aggregate pressure
link evidence
link hypothesis
close / dismiss pressure

44.3 Hypothesis API

Operations:

create hypothesis
compare hypotheses
prioritize hypothesis
attach candidate
record outcome

44.4 Experiment API

Operations:

create experiment
start experiment
change bounded allocation
stop experiment
record metrics
finalize outcome

44.5 Intent API

Operations:

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:

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

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.

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

request → LLM decides semantics → backend

This violates the deterministic runtime principle.

48.2 Self-Modifying Production Runtime

runtime observes error
→ edits own production implementation
→ continues

This destroys auditability and safe rollback.

48.3 Telemetry Equals Requirement

many clients request X
→ X automatically becomes valid interface scope

Usage is evidence, not intent.

48.4 Backend Authority Leakage

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:

/
├── 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:

two deterministic revisions;
explicit revision routing;
telemetry;
one consumer cohort dimension;
pressure detection;
manually created hypothesis;
manually created candidate revision;
controlled 90/10 experiment;
fitness comparison;
promotion or rollback;
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:

add explicit consumer feedback;
auto-generate pressure records;
use the Daimon to propose hypotheses;
require human selection;
generate candidate contract changes;
generate tests;
keep promotion human-controlled.

This establishes FLUID-2 / FLUID-3 behavior without production autonomy.

52. Third Vertical Slice

automate candidate build;
automate verification;
create bounded experiment deployments;
let the Daimon recommend promotion;
implement complexity scoring;
implement backend requirement escalation.

This establishes FLUID-4.

53. Fourth Vertical Slice

Only after sufficient operational evidence:

define deterministic promotion policies;
allow low-risk presentation and implementation adaptations to promote automatically;
retain contract adaptations under stricter controls;
automate optimization-regime recommendations;
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.

Runtime behavior remains deterministic.
Evolution can stop without stopping the API.
Every published revision is identifiable.
Every revision has an explicit contract.
Every revision is governed by a specific intent version.
Every nontrivial change can be linked to evidence.
Every experiment has guardrails and stop conditions.
Every promotion is auditable.
AI-generated artifacts are untrusted until verified.
Security policy remains deterministic.
Backend authority does not leak into the interface Daimon.
Complexity is measured.
Multiple revisions may coexist.
Failed experiments are normal and recoverable.
Usage informs intent but cannot silently redefine it.
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:

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.

46 KiB Executable file Raw Blame History Unescape Escape

FLUID Architecture Blueprint

1. Purpose

2. Architectural Thesis

3. Architectural Planes

4. Consumer Plane

5. Interface Data Plane

5.1 Edge Gateway

5.2 Revision Resolver

5.3 Revision Router

5.4 Contract Validator

5.5 Deterministic Adapter Runtime

5.6 Backend Connector Layer

5.7 Response Policy

6. Observation Plane

6.1 Telemetry Sources

Request events

Error events

Sequence events

Adoption events

Explicit feedback

6.2 Telemetry Boundary

6.3 Consumer Cohort Engine

6.4 Interaction Topology Analyzer

6.5 Pressure Classifier

7. Evolution Control Plane

8. Daimon Orchestrator

9. Pressure Registry

10. Hypothesis Engine

10.1 Hypothesis Generation

10.2 Hypothesis Reach

10.3 Competing Hypotheses

11. Optimization Policy

12. Complexity Evaluator

13. Candidate Planner

14. Builder

15. Verification Controller

Contract tests

Regression tests

Security tests

Backend contract tests

Performance tests

Complexity checks

Static policy checks

16. Experiment Controller

17. Revision Router and Experiment Controller Interaction

18. Fitness Evaluator

Primary metrics

Guardrails

Secondary metrics

Learning metrics

19. Promotion Controller

20. Migration Controller

21. Backend Requirement Broker

22. Boundary Learning

23. Evolution Velocity Controller

24. Evidence and Artifact Plane

25. Artifact Store

26. Evidence Store

27. Intent Store

28. Security Architecture

28.1 Security Boundaries

Runtime identity

Daimon identity

Builder identity

Experiment Controller identity

Promotion authority

Evidence writer

28.2 Deterministic Policy Gate

29. Economic Architecture

30. Adaptive Compute Governor

31. Recommended Service Decomposition

32. Minimal Reference Implementation

Phase A — FLUID Core

Phase B — FLUID Insight

Phase C — FLUID Science

Phase D — FLUID Builder

Phase E — FLUID Managed Evolution

Phase F — FLUID Bounded Autonomy

33. Example End-to-End Flow

46 KiB

Executable file

Raw Blame History