Kontour Console

ADR 0003: Authenticated Multi-Tenant Ingestion And The Value Plane

Date: 2026-07-05

Status

Accepted (ratified by Brian Anderson, 2026-07-05)

Context

Console is the suite management plane (ADR 0001): it aggregates, correlates, displays, and routes product-owned records without becoming the authority for product semantics. It already separates the control plane (product-owned events, projections, learnings, gates, claims, decisions) from the telemetry plane (traces, metrics, usage/cost observations, delivery diagnostics), with authority owned by the producing product (see docs/specs/emitter-sink-plane-contract.md, ADR 0002). Records enter through a sink ladder — local files today, a hosted API and telemetry destinations later — carrying kontour.console.event / kontour.console.projection shapes.

Three forces now converge that this ADR must resolve as one coherent architecture rather than as separate features:

  1. Fleets. Flow Agents’ local-first coordination substrate (liveness ⋈ assignment) is being relayed to Console so multiple machines/owners see each other’s holds (flow-agents #295 shipped the emit half; console #125 is the ingest + fleet projection). This makes Console receive records from many, mutually-untrusting installations.
  2. True multi-tenancy. Tenancy is strong at the infrastructure layer (Postgres PK per tenant, per-tenant hubs/SSE) but weak at the schema layer (records do not self-identify a tenant). With many installations posting, this gap is now a correctness and isolation risk, not a nicety (flow-agents #394 / console #123).
  3. Value legibility. The hosted tier’s value proposition is not “we show your activity and cost” — it is “the scaffolding pays for itself,” most sharply “a smaller, cheaper model + the kits matches a larger model alone, at a fraction of the cost” (flow-agents #349/#350/#409, console #117). Console must be the surface where that value is legible, which requires a counterfactual, not just observation.

The risk of solving these piecemeal is a proliferation of ingest endpoints, a tenant field that is trusted from the payload (spoofable across tenants), a bespoke store per feature, and a “value” view that is circular (measuring the scaffolding by its own gates). This ADR fixes the load-bearing calls.

Decision

Six calls, each extending the existing plane/sink model rather than replacing it.

1. One authenticated ingress: the ApiSink, with versioned record kinds

All producers — local Builder/Knowledge kit installations, CI, and the eval harness (call 4) — deliver through a single authenticated ApiSink (the hosted rung of the existing sink ladder; console #73). It accepts POST /records with a small, versioned, discriminated set of record kinds: the existing kontour.console.event and kontour.console.projection (control plane), plus the telemetry-plane kinds telemetry, kontour.console.liveness (#295/#125), and kontour.console.economics (#349). New signals are additional kinds on one pipe, never new endpoints. The ApiSink is the one place that authenticates, rate-limits, validates shape, and stamps tenancy (call 2); it then routes each record to its plane and projection.

2. Tenant is bound from the verified principal, not trusted from the payload

The authoritative tenant is the tenant claim on the authenticated principal (an OIDC human user or an M2M client credential — console #98), resolved at the ApiSink. A record MAY carry a tenant_id for self-description and debugging, but ingest stamps the tenant from the principal and rejects a record whose body tenant_id disagrees with the principal’s tenant. The body tenant is never the source of truth. Every downstream projection and query is therefore tenant-scoped by construction, on top of the existing Postgres-PK-per-tenant isolation. Each local kit installation authenticates as its own M2M principal, scoped to one tenant; a human authenticates via OIDC. This closes the schema-weak multi-tenancy gap the correct way — isolation is enforced at the trust boundary from a verified identity, not asserted by a mutable field a hostile or buggy producer controls.

3. Event-sourced core per tenant; fleet, economics, and value are rebuildable projections

Extend the existing OperatingState projection model uniformly: the immutable, tenant-stamped record stream is the source of truth; the fleet view, the economics rollups, and the value comparison are derived read-models that can be dropped and rebuilt. Do not build a bespoke store per feature. Liveness is a projection-with-TTL; economics is an aggregate; “value” (call 4) is an analytical query grouped by experiment dimensions. This preserves ADR 0001’s stance — Console renders and correlates, it is not the authority — and keeps every new surface cheap and reconstructible.

4. Value is a controlled counterfactual, produced by a separate eval harness against an independent oracle

“Value” is not a telemetry projection over live usage — it is a controlled experiment, and its honesty depends entirely on an acceptance oracle that is independent of the kits. Using the kits’ own gates as the oracle is circular (kit runs pass the kit’s gates by construction). Therefore:

  • A dedicated kontourai/evals repository owns a task corpus with objectively-checkable outcomes (tests pass / known-good diff / graded rubric) and the graders. This is the keystone; it is a distinct lifecycle from any single product and MUST be its own repo, not a subtree.
  • A baseline harness (flow-agents #350) runs the matrix {small, large model} × {bare, +kit} over that corpus and, for each run, emits a kontour.console.economics record tagged with {model_tier, kit_condition, task_id, acceptance_label, iterations, defects_caught, cost} through the same ApiSink (call 1) as any other producer.
  • The value view (console #117) is a projection over those tagged records: acceptance rate, iterations-to-accept, defects caught by gates, and $ / acceptable-outcome, grouped by (model_tier, kit_condition). The headline cell is small+kit vs large-bare (flow-agents #409).

The harness measures the value; Console renders it; the independent oracle makes it honest.

5. The feedback loop is advisory, evidence-backed, and human-ratified — Console never writes back

Economics and value projections may emit proposals (“gate X fires often and catches nothing → candidate to relax”; “small+kit underperforms on task-class Y → strengthen the plan gate there”). Console surfaces them; it does not change a kit, a gate, or a claim. Per ADR 0002, a proposal that should cause a product-owned change is realized only when the owning product emits the authoritative control-plane event through its own deliver loop after a human ratifies it (flow-agents learning-review, #352/#252). Console publishes advisory data the local learning-review pulls; it never pushes a command into a local installation. This preserves both trust and tenant data sovereignty.

6. Local-first and never-authority are invariants; one binary self-hosts or runs hosted

Every capability above degrades to fully-functional-local: the console relay is opt-in and best-effort (flow-agents #295), and Console is never the authority for a gate, claim, evidence, or coordination decision — even the coordination “source of truth” mode remains a projection the owning substrate can run without. The same console binary self-hosts single-tenant or runs the hosted multi-tenant deployment (console-deploy); the owner’s dogfood is a tenant, not a fork.

Consequences

  • Multi-tenancy becomes correct, not just isolated. Cross-tenant spoofing by editing a payload field is impossible; isolation is enforced from a verified identity at one boundary. This makes #98 (auth: principals) a hard prerequisite for opening the hosted ingress to more than one owner, and reframes the epic’s “validate the body tenant_id” as “stamp from the principal, reject a mismatch.”
  • One ingress, many kinds keeps the surface small: liveness (#125), economics (#349), and future signals are additive kinds routed to projections, not new endpoints or new auth paths.
  • The value proof gets an owner. The keystone is the independent oracle + task corpus in kontourai/evals, not a dashboard. The dashboard (#117) is downstream and easy once the tagged economics records exist. This makes the kontourai/evals repo decision (flow-agents #350/#409) a prerequisite, and it makes “is small+kit ≥ large-bare, and by how much” a falsifiable number.
  • The feedback loop stays trustworthy. No silent self-modification; every kit/gate change still travels the normal evidence-backed deliver loop. Console is a lens and an advisor, not a controller.
  • Cost of change is bounded. Because fleet/economics/value are rebuildable projections over an immutable per-tenant stream, schema and rollup evolution is a re-projection, not a migration of authority.
  • Dogfood and product are the same system. The owner’s “see my value” loop (flow-agents #410) is the hosted architecture exercised as a single tenant — no throwaway path.

Supersedes nothing; extends ADR 0001 (Console as management plane) and ADR 0002 (learnings are non-authoritative control-plane records), and the emitter/sink/plane contract. Companion trackers: console #123 / flow-agents #394 (fleet + tenancy), console #117 / flow-agents #349/#350/#409 (value), flow-agents #352/#252 (feedback), flow-agents #410 (owner dogfood loop).