Add O Observatory with scalable FACTORY navigation and instruments

docs/OBSERVATORY_INSIGHTS.md

@@ -0,0 +1,25 @@
+# Observatory instruments
+
+The expanded instruments below the spatial field provide analytics, a timestamped timeline, FLUJO worker nodes, conversations with tool calls/results, and separate Modal/Fly inventory. The sticky navigation jumps between sections; the scope picker filters them by registered authority. Section navigation preserves the authority URL fragment. Conversations open at the newest message; refresh preserves a reader's position and expanded tool calls when the transcript is unchanged.
+
+The two-second expiry tick refreshes time-sensitive analytics and worker/provider freshness when their effective evidence changes, even without a new transport frame or changed data object. One captured clock drives the panels. Lease expiry and the 15-second freshness boundary invalidate these panels without rebuilding the timeline or transcript, preserving scroll and tool expansion. Repeated ticks with unchanged evidence do not repaint.
+
+The existing `brain-swarm/1` exact-origin/frame/channel transport carries an optional `model.observatory` detail envelope. `insights-model.ts` is the positive allowlist shared verbatim with Brain Online's `factory-observatory.ts`. It requires `schemaVersion: 1`, `scope: factory-observatory`, `commands: false`, and sources matching the controller registry's exact `(sourceId, factoryId)`. Unknown extensions are stripped. Malformed/unregistered detail is erased without fabricating worker facts. A standalone same-origin swarm bridge can include this same field. `?preview=1` supplies explicitly labeled sample detail; failed live reads never load samples.
+
+Machine identities include provider, nullable account, app, run and resource under their registered source/factory. Retained receipts are historical; a refreshed local journal cannot establish fresh cloud health. Paid reservations are displayed separately and never converted into machine identities. Unknown paid spend remains unknown, and logical cell allocation is separate from the paid ledger. Reported conversation token totals can overlap across nested runs.
+
+Worker registration is a grouping mechanism. Null cell/machine bindings remain visibly unbound. Flow definitions display node labels, types and edges only. The current position comes from the conversation's `currentNodeId`; it is labeled reported running only when the conversation reports `running` and the worker observation is recent. Definitions do not imply node execution or completion. A completed conversation's position stays historical. This view has no execution controls.
+
+Detail bounds are 32 sources, 128 resources/source, 16 workers/source, 12 conversations/worker, 100 display messages/conversation, 512 nodes/flow, and 2,048 edges/flow. Message/tool-argument shortening is explicitly marked. Private conversation access failures erase transcripts and topology. Controller history starts with the current connection's cursor; snapshots do not reconstruct earlier controller events.
+
+Validation: `npm run build` and `npm run test:swarm` include namespace, graph-binding, private-field, transcript-denial, byte/window and unknown-spend checks, alongside the existing 10,000-cell and renderer evidence qualification. A JSDOM regression runs the actual instrument module through lease expiry with the same observation objects, then worker/provider freshness expiry on an idle tick; it verifies transcript/timeline identity, scroll and tool expansion are preserved.
+
+## O visual redesign
+
+The O is a mouth. Its SVG mark shares the field's deterministic authority palette. The visual language combines serif readings, monospace identities, glass surfaces, measured rules and a numbered section spine. All five observation sections remain expanded. Tool calls, operation receipts and evidence digests start expanded; longer interpretation notes live in Evidence drawers.
+
+The dial and field's `recent leased` figure show cells with an unexpired running lease and recent heartbeat/source evidence. Uncertain, unknown-outcome and retained records are excluded; the figure and mouth mark do not report a full lease census. The budget rule shows recorded paid holds, the timeline ribbon shows record density in three separate provenance lanes, and flow diagrams show recorded nodes and edges. These marks do not introduce health, inferred execution, reconstructed history or new controls. Node tooltips and the accessible graph description preserve full labels, types and identities. Cyclic or disconnected definitions retain every node within the SVG bounds. Completed operations remain separate from delivered software in the task reading.
+
+The requested FLUJO flow `6b0b98fd-aa5a-4d8a-bdf5-510bb70a7e03` (`Claude_Opus_Agent`) authored the presentation candidate in conversation `c46dc824-9cc3-45a8-9c19-eabab529f9d8`. Parent review repaired section navigation, task-status labels, graph bounds, receipt expansion and responsive readings before acceptance. The flow definition was not changed.
+
+The redesign builds successfully and passes 20 viewer checks. Browser qualification covers source-preserving navigation, the actual two registered FLUJO conversations (including the design run's six-node graph and 100/135-message window), the recorded $100 held/$0 available/incomplete paid ledger, expanded historical Modal/Fly receipts, and a 390px viewport without page overflow. The private local qualification harness is separate from shipped source; release and runtime adoption remain the host owner's responsibility. The shared observation schema, transport, source parsing, server redaction and read budgets are unchanged.

docs/SWARM.md

@@ -0,0 +1,110 @@
+# Brain Observatory
+
+`swarm.html` is the multipage FACTORY viewer built with the normal Vite build.
+Brain Online embeds it under `/viewer/` from the upstream Brain image and supplies
+authenticated observations. Its normal Brain viewer links to `/factory/swarm`
+when hosted at `/viewer/`; standalone hosts link to `./swarm.html`.
+
+The component accepts public v1 snapshots from an explicit operator source
+registry. It does not discover factories, receive credentials, execute work,
+or infer authority links between sources. All identities include the registry
+source and factory. The read-only index preserves every recorded cell, task,
+effect, evidence digest and local parent relationship while rendering a bounded
+subset. Search, breadcrumbs and 128-child pages navigate the complete index.
+
+## Hosting
+
+Embedded hosts pass `?embed=1&channel=<16..128 character channel>` and exchange
+same-origin `brain-swarm/1` messages with the exact parent/frame:
+
+- viewer → parent: `ready` or `select` with the channel and a selection naming
+  sourceId, factoryId, kind and id;
+- parent → viewer: `observe` with channel, increasing integer sequence and model;
+- parent → viewer: `ping`; viewer repeats `ready`.
+
+The model has schemaVersion 1, scope `operator-source-registry`, commands false,
+observedAt and at most 32 sources. Each source has id, label, factoryId,
+observed/stale/unavailable status, a public canonical FACTORY snapshot or null,
+and optional metadata events. Hash links also name the exact factory; changing
+the authority behind a registry alias clears its former selection.
+`model.ts` positively allowlists these facts; private extensions are dropped
+and unsupported execution capability is rejected.
+Never put a bearer credential in a URL, iframe message or client environment.
+
+A standalone deployment must supply its own authenticated same-origin JSON bridge
+at `/api/factory/swarm` (or the `source` parameter's same-origin absolute path).
+The Brain manager does not automatically expose credentialed FACTORY reads.
+Standalone polling uses same-origin credentials, no-store reads and a five-second
+delay after each observation. An unavailable bridge shows an empty/unavailable
+world; there is no real-data-to-fixture fallback.
+
+`swarm.html?preview=1&cells=10000` explicitly generates a 10,000-cell design
+fixture. Normal preview defaults to 54 cells across three independent sources.
+The fixture label remains visible. Brain Online has its own explicit preview
+host and uses the same upstream renderer.
+
+## Scale and rendering
+
+The full index uses iterative hierarchy layout, deterministic positions and
+scoped keys. It handles deep chains and wide parents without recursion or a
+force simulation. Visible nodes are capped at 600, labels at 24, and navigation
+lists/search results are bounded. Ancestor/sibling context and child pages keep
+hidden records reachable. A source overview has no cross-source authority edges.
+
+The WebGL renderer batches node points and delegation/reference lines, disposes
+replaced geometry, suspends hidden documents, renders idle views only on demand,
+and caps evidenced activity at 30 frames/second. Reduced motion disables pulse
+and animated camera flight. Context loss switches to the 2D renderer, which
+uses the same index and scoped selection. Rendering diagnostics report CPU
+submission time separately from draw-call and frame counts; they do not prove
+GPU timing or physical worker health.
+
+The Observatory design and first UI implementation were completed by Claude Opus
+through a normal local FLUJO subscription-agent conversation at Medium effort
+with Bash. The integration pass added camera fitting around visible instruments,
+responsive reframing, measured label collision bounds, live reduced-motion
+changes and a trailing diagnostics update when on-demand rendering settles.
+
+Static shapes also preserve status under reduced motion: authority plates use
+a hollow keystone, observed idle cells an open ring, recent qualifying leased
+work a bullseye, uncertain evidence an amber barred ring, and retained records
+a broken grey ring. Unconfirmed running-work evidence is distinct from an
+owned unknown external outcome in the inspector. Only an owned unknown outcome
+outranks retirement or source staleness; it remains unresolved by completion.
+
+Fresh observations do not establish worker activity. A cell needs an active
+controller, ready lifecycle, recent heartbeat, an unexpired running lease and
+no owned unknown outcome. Completed/cancelled operations do not animate as
+running work. Unknown external outcomes keep their cell's uncertainty marker
+after task completion or retirement, until an observed resolution replaces them.
+Pause, effect drain and worker quiescence remain separate facts.
+The selected inspector preserves task, candidate and review digests and states
+that quiescence is unverified.
+
+## Development and verification
+
+Run `npm ci`, `npm run build` and `npm run test:swarm`. Tests use the actual model,
+marker, transport and preview modules and cover duplicate record IDs across authorities, complete
+10,000-deep/wide navigation, stable layout, stale/lease/terminal activity gates,
+positive allowlists and missing-source behavior. Copy the built `dist` artifact
+to the consumer's ignored viewer directory for local integration; keep source
+in this repository. Qualify desktop/mobile composition and 3D/2D navigation in
+the browser against the built artifact before publishing the Brain image.
+
+The 2026-10-03 fixture qualification reached `cell-3333` in a 10,000-cell world
+in both modes and preserved its source/factory identity after actual WebGL
+context loss. The world had 10,003 indexed nodes; its overview drew 18 nodes and
+the selected neighborhood drew 10, with two GPU draw calls in 3D and no GL calls
+in 2D. Desktop, 615-pixel and 390-pixel layouts were checked. Reduced motion
+stopped an already-running renderer; 2D settled without an animation loop.
+These are fixture/navigation checks, not live FACTORY health evidence.
+
+After FACTORY's owner restored and qualified its observer, the actual Brain
+Online BFF passed a fresh read at 2026-10-03T21:06:54Z: loaded build
+`d9d87c6ebbd05b6c82bdbf0f7c537e76eb4b9a66`, paused admission at revision 92,
+five cells, three tasks and six effects. Staff reads returned 200, anonymous
+reads 401 and customer reads 404; snapshot/event responses were no-store and
+contained no server credential. The actual host component and upstream artifact
+also displayed these live records in a local qualification harness with a
+development staff principal and five-second refreshes. This does not qualify
+a production Supabase login or prove provider freshness or worker quiescence.

index.html

@@ -20,6 +20,7 @@ <h1>brain</h1>
         </div>
       </div>
       <div class="controls">
+        <a id="swarm-link" class="lobby-link" href="./swarm.html">⬡ swarm</a>
         <a id="lobby-link" class="lobby-link hidden" href="./lobby.html">⬡ brains</a>
         <div id="life">
           <button id="heartbeat" class="hidden" title="the brain's heartbeats — click for details" aria-expanded="false" aria-controls="hb-panel">