Sense 59: The Double Circle

Sense 59 · In bloom · Last touched 2026-08-20

• last_verified: 2026-07-27

Synced from docs/design/sense_59_the_double_circle.md in the engine repo — that’s the source; this page is a build-time mirror.

Status: proposed Date: 2026-07-15 Origin: a terminology argument that turned architectural. Untangling why the River view felt hollow led to the realisation that the word named two different substances — a stream of data and a stream of telemetry — and that separating them exposes a deeper truth: make is not one cycle but two, and they meet at exactly one place. Companion Sense docs: Sense 42 The Landscape (Garden + River — this gives them their cycle meaning) · Sense 57 The Rooms (Analysis = the Garden, Flow = the River) · Sense 5 No Silent Filtering (extended here past Gold) · Sense 53 The Codex + Sense 54 The Typology (they make Gold a versioned contract — which is what this Sense needs) · Sense 7 Make / Explore Split (the cycle this one bisects) Reframes: the River. Sense 42/57 read the River as time (the flow of events). The Double Circle reads it as data (the flow toward Gold). The event/telemetry stream that the River page used to show is not the River — it is the Heartbeat, the pulse of the Cycle. Spec: The Membrane — settles the rejection surface and the contract version, and specifies the staleness protocol that crosses the seam. Read it before building the Garden-only rebuild.

Claim

The build is not one circle. It is two circles that touch at a single point.

• The River is the circle of data: ingestion rising through the medallion until it sets into the Gold contract. Source → Bronze → Silver → Gold. How raw delivery becomes trustworthy.
• The Garden is the circle of analysis: everything rooted in the Gold contract — the diamond of Signals → Perspectives → Theses → Verdicts, and the Subject Matter and Observations that stand beside it. What we cultivate on that trust.
• The Gold contract is the only place they touch. It is the river’s mouth and the garden’s soil — the estuary where the flow deposits what is solid and the garden grows in it.

Today make runs both circles as one DAG. This Sense says: let them turn independently. Two processes that never talk to each other except across one membrane — the contract changed and new data arrived. From that one move we gain speed, topology, and honesty.

The two circles

	The River	The Garden
Substance	data	analysis
Span	source → Bronze → Silver → Gold	Gold → signals → perspectives → theses → verdicts
Answers	how does data become trustworthy?	what do we conclude from it?
Inputs	source deliveries + AFS-river (medallion models, contracts)	Gold + AFS-garden (signals, theses, verdicts, …)
Output	the Gold contract + Gold data	findings + verdicts
Character	flowing, watched, dynamic	arranged, contemplated, structural
Triggered by	new source data arrives	the contract changes, Gold refreshes, or a signal is authored
Belongs to	the Flow room (Sense 57)	the Analysis room (Sense 57)

Both are still deterministic from their inputs — source + AFS-river → Gold, and Gold + AFS-garden → findings. Splitting the DAG at Gold does not weaken reproducibility; it gives you two clean checkpoints instead of one. The self-contained KLS survives as one file with two independently-refreshable strata (a Gold stratum River owns, a findings stratum Garden owns) joined by a version link.

The membrane: the Gold contract, and nothing else

The circles share exactly one interface — the Gold contract — carrying exactly two signals across it:

1. The contract changed. River reshaped Gold (a new column, a new entity, a changed type). This is a versioned, breaking event: Garden must recompile against the new contract version.
2. New data arrived. River refreshed Gold’s data without changing its shape. Garden’s findings are now stale against fresh Gold and should recompute — but nothing structural moved.

That is the whole conversation. No other coupling is permitted.

The load-bearing constraint: instruments read Gold only

For the membrane to hold, an instrument (signal) may read Gold and only Gold — never Silver, never Bronze. This is almost true today. The one exception is the honest one: data-quality signals reach into Silver to see what Gold filtered out.

We do not forbid the need — we relocate it. River must publish its own rejection record into Gold. The invalid rows, and why, become a Gold surface (widening the existing gold_quality_metrics from a loss count to the actual rejected set). Then the data-quality signal reads that, through the contract, like every other signal.

This is just Sense 5 — No Silent Filtering taken one step further:

Invalid rows are flagged, not dropped, until Gold. → Not dropped at Gold either — surfaced as part of the contract.

Gold becomes the clean product and the honest record of what did not make it. The membrane is complete; the Garden never needs to peek beneath it. The constraint is not a cost — it is the River made more honest.

Why turn them independently — the payoffs

Authoring is cheap again. Today, publishing one signal (Sense — cloud authoring loop) triggers a full make: re-ingest, re-medallion, re-Gold — all to test one analytical edit where Gold did not change. Split the circles and publishing a signal runs the Garden only — seconds, on frozen Gold, no data re-touch. The stage buffer, the worker /publish, evolve’s proposals — all become fast. This is the payoff that pays for the whole idea.

Topology falls out for free. The River is heavy and often sensitive (raw source data); the Garden runs on Gold, which is the shareable product. So: River on-site, Garden in the cloud, with the Gold contract as the export boundary. Semi-cloud (Sense 16 / operating modes) stops being a special case and becomes the natural shape — you were always meant to ship Gold, not Bronze.

Cadence decouples. A sensor fleet delivers every few minutes; the analytical framework changes when an author edits a signal. These are different clocks. One DAG forces them to tick together. Two circles let the River beat on the data’s clock and the Garden turn on the author’s.

One River, many Gardens

Because a Garden’s only input is Gold, one River can nurture many Gardens. The constraint that looked like a limit — read Gold and only Gold — is precisely what turns Gold into a shared foundation: any number of independent analytical frameworks can root in the same trustworthy data, each on its own clock, none aware of the others.

Picture it not as two circles but as a flower: the Gold contract at the centre, the River feeding it from below, and around it garden after garden — a compliance garden for the auditors, an operations garden for the fleet team, a clinical-quality garden for the ward — each a coherent set of Signals → Verdicts cultivated for a different purpose, all drinking from the same water. The “double” in the name is the two kinds of circle (data vs analysis); the gardens themselves multiply freely.

This quietly reframes what a tenant is. Today: one pack, one framework, one instance. The Double Circle says the River is the tenant’s (their data, their Gold) and a Garden is a framework grown on it — so a tenant is not “an instance of a pack” but one river that can grow several gardens, possibly from different packs, possibly bespoke. The pack stops being the unit of a tenant and becomes a garden you can plant.

The topology multiplies with it: one on-site River → Gold → many cloud Gardens, each shippable to its own audience, each independently rebuildable, all sharing one Gold lineage. And it is safe only because of the membrane — gardens can proliferate without ever colliding, since none of them can reach past Gold into each other’s or the river’s business.

Open: where is the boundary of a garden — a pack, a perspective-set, a labelled sub-framework in the AFS? Does Gold stay single while gardens multiply (one contract, the commons — our current bet), or can one River feed differently-shaped Golds for differently-shaped gardens? New ground; named here, not settled.

Coherence across the seam

Independence needs a coherence story, or the two circles drift into lying to each other:

• Findings are stamped with the Gold version they ran against. Garden output carries computed against Gold@<version>.
• A River refresh marks the Garden stale — it does not silently invalidate it. You always know whether the findings you are reading were computed on the current Gold or a prior one.
• A contract reshape is a version bump the Garden must clear. This is where the Typology + Codex earn their keep: every Gold column already declares its type, so “did the contract change in a way that breaks a signal?” becomes a checkable question, not a guess. The Double Circle is the reason that work matters.

The KLS snapshot mechanism already carries git provenance and a self-describing AFS archive; the Gold-version link rides the same rails.

Physical topology — how the circles are packaged (a new operating-mode axis)

The two circles are a logical split. How they are physically materialised is a separate, lower question — and a genuinely new one, because it adds an axis to the operating modes (Sense 16). Today’s five modes answer where the KLS lives and who runs make. This axis answers how the two circles are packaged, and it turns two dials.

The invariant, first — so the axis stays safe. Whatever the packaging, the membrane is unchanged: the Garden reads Gold + the contract version, and nothing else. Packaging is a choice below the membrane; the logical model never notices it. That is the reassurance that lets us treat this as a mode, not a redesign — you can change the physical shape without touching a single instrument.

Dial 1 — Depth: keep the ladder, or purge it

Bronze and Silver are the ladder the River climbs to reach Gold. The Garden never reads them. So once the River has set Gold, they can be purged — leaving a KLS that carries only the product (Gold + findings + the rejection ledger).

• Benefit: a dramatically leaner artifact. Bronze is usually the heaviest stratum (raw ingestion — millions of rows); dropping it shrinks what you snapshot, sync to R2, and load in JinDesk. Ship the product, not the scaffolding.
• Cost: you lose interactive drill-back — the medallion Stream / lineage view that walks a Gold row back to its Bronze source. That view would need baked summary stats to survive a purge.
• Precondition — ties straight to the membrane: purging Silver is only safe once gold_rejections is materialised as a Gold table, not a view over Silver (membrane §I). Once the rejection record is in Gold, Silver has no remaining reader and can go.
• Recoverability ≠ drill-back. Bronze/Silver are Built (Sense 61) — derived from source + AFS-river. Purging them loses the interactive walk-back, not the ability to rebuild them from source. Caveat: a purged artifact shipped without its source is a leaf — it cannot re-derive its own Gold; it depends on the River that made it. Which is exactly a Garden’s contract anyway.

Dial 2 — Split: one file, or two

Sense 59 assumed one file, two strata. The alternative: two files — a River-KLS (Bronze → Gold) and a Garden-KLS (findings), joined by the same contract_version link, the Garden-KLS ATTACHing the River’s Gold read-only.

• Benefit — the flower, made physical. River-KLS stays on-site (heavy, sensitive raw data); Garden-KLS ships to the cloud (Gold + findings, shareable). One River, many Gardens becomes one River-KLS, many Garden-KLS files, each rooted in the same Gold, each independently snapshot-able and refreshable. Semi-cloud (Sense 16) stops being a special case.
• Cost — the topology complexity, named honestly. Two files to version, snapshot, and reason about; the single-contained-file value (the KLS crown jewel) splits in two. The membrane’s version link becomes an inter-file reference, and the staleness protocol (membrane §III) now spans files rather than strata.

The dials compose — and pair naturally

	Unified (one KLS)	Split (River-KLS + Garden-KLS)
Full depth	today’s KLS — everything in one file	River-KLS holds the full ladder; Garden-KLS holds findings
Slim (purged)	one lean file: Gold + findings + rejects	inherent — the Garden-KLS is slim by construction (Bronze/Silver never leave the River-KLS)

The bottom-right cell is the quiet insight: splitting gives you Dial-1’s lean shippable artifact for free, without ever purging. Bronze/Silver simply stay behind in the River-KLS — fully intact for drill-back — while the Garden-KLS that ships is naturally slim. Purge-in-a-unified-file is for those who want one file but lean; split-file is for those who accept two files to keep the ladder and ship slim.

It is an axis, not a mode

This composes with — does not replace — the five deployment modes. Deployment answers where + who; packaging answers how materialised. A future revision of operating_modes.md gains this second dimension. And the Operational stratum (the Reservoir, Sense 61) is untouched by either dial — identity and roster don’t care how deep the medallion is baked or across how many files. More evidence the strata are genuinely separate.

Stance: an idea worth naming, not settling. Both dials carry real benefit and real topology cost. The trigger to reach for them is concrete: a Bronze too heavy to ship (→ purge or split), or a River too sensitive to leave the site (→ split). Absent that, one full file stays the simple default — the contained KLS we already love.

The Heartbeat, and a possible third circle

The Heartbeat (Sense 21 — the system’s rhythm: regular, observable, one-way beats) is not the River. The extraction/build cadence the old River page showed — channel freshness, last build, last verdict — is one beat of the Heartbeat, not the River itself. A different axis entirely: the River is about shape (how data ascends to the contract); the Heartbeat is about rhythm (is the system beating, how fresh). That beat was homed on the River page for want of a better place; it wants to live near where the Cycle turns (the Bench, with make and the CLI), not in Flow.

And the main beat belongs to the River circle — extraction and the medallion build are what pulse on the data’s clock.

Open — and deliberately unhurried: if the River has its heartbeat, does the Garden have its own pulse (findings recomputation on the author’s clock)? And do the artefacts the Garden creates — Observations, Interventions, Scenarios, evolve proposals — form a third circle turning on Gold-plus-findings? The Double Circle may yet be a triple. We are not deciding that here.

Open design questions

• Materialised views in the Garden. If the Garden runs independently on frozen Gold, what does it materialise, and where does that live relative to the findings stratum? Are perspective/thesis roll-ups River-adjacent (contract-shaped) or Garden-internal?
• One KLS or two, and purge-or-keep the ladder. Now framed as the packaging axis above (“Physical topology”): Depth (full vs slim) × Split (unified vs River-KLS + Garden-KLS). Default stays one full file; the dials are opt-in modes with a concrete trigger. Physical layout still to be pinned when a driver appears.
• What exactly is “the contract version”? Settled in The Membrane §II: a canonical hash of the typed Gold schema (whole-Gold + per-entity), separate from a deterministic data_version; display: config never bumps it.
• Where the seam lives in make. make is already decomposed into phases; the River phases (extract → bronze → silver → gold) and Garden phases (signals → … → verdicts) are already adjacent. The split is a grouping and a trigger, not a rewrite — but the orchestration (two entry points, staleness propagation) is new. The protocol it obeys is fixed in The Membrane §III; the wiring is the rebuild slice.
• Rejection surface shape. Settled in The Membrane §I: a single unified Gold ledger, gold_rejections, projected from Silver’s is_valid flags; gold_quality_metrics stays as the aggregate beside it.

Vocabulary this Sense fixes

• River — the circle of data: ingestion → the Gold contract (Bronze → Silver → Gold). Platform term.
• Garden — the circle of analysis: everything rooted in the Gold contract (the Signal → Verdict diamond and its neighbours). Platform term.
• The Gold contract — the single membrane where River and Garden touch; the river’s mouth and the garden’s soil.
• The Heartbeat — the pulse of the Cycle (extraction/build cadence), belonging chiefly to the River. Not the River itself.

Non-goals (for now)

• Not a rewrite of make — this Sense specs the shape; the implementation is deliberately deferred.
• Not deciding the third circle. Named, not resolved.
• Not removing the single-commit reproducibility guarantee — it is preserved as two checkpoints, not abandoned.

---

Numerical neighbors: ← Sense 58: The Broker · Sense 60: The Doctor →