Working logic — VFE / EFE / OODA, Document-Driven, Test-Driven (binding)

The Colony & the Method · docs/WORKING_LOGIC.md @ 44baf03d5041 (gen2-runtime) — opens the published snapshot ac338733bbba

2 values were removed from this page. Each one is marked in place as [redacted: category] — 1 private address, 1 internal hostname. Nothing else was altered. The document is otherwise exactly as it is written in the repository, and the sha256 below is of the original, so what was ingested stays checkable.

Three ways to read this page. Precise is the document itself, exactly as it is written in the repository. Plain and Clear were written for this website to help you meet that document — they are about it. They are not it, and they are not evidence.

Eighty-four pages about the colony. Each agent is an Elixir process holding a generative model and doing inference, attached to a body that logs into a Minecraft world as an ordinary player. Around that sit the broadcast suite that films them and the runbooks that keep the whole thing running. There are typed specifications for each organ of the model, plus the world and genome specs. There are also the adversarial review personas used to attack a proposed change before it ships.

It is for the reader curious how a running system is put together and how it is held to account. The accountability half is the more distinctive. There is a lab protocol governing evidence and attribution, and a claim fence that restricts the vocabulary a claim is allowed to use. There is a public gate log. And there is a standing invitation to reproduce any verdict from the commit and the seed named in its receipt.

Start with the public read, then the lab protocol, then the falsification invitation. If you want the mathematics rather than the operations, go straight to the typed organ specs.

What it is not: a description of a mind, and not all one kind of document. A large part of this corpus is design and planning — specs marked as proposed rather than applied, organs designed but not built, plans that were later superseded — and each page states which it is. A specification is not a running system, and these pages are careful about the difference; the reader should be too. Eight documents were withheld from publication because they describe private infrastructure.

PlainClearPrecise

Your browser cannot switch reading levels, so the document itself is shown.

This is the document. Rendered from the repository at the commit above, with nothing rewritten for the web. A gate re-renders it on every deploy and fails the build if a single byte differs.

Loaded-by-reference from CLAUDE.md. This is the fuller version of the tight "how this agent works" section there. The rules here are binding. They govern the studio track; the science track has its own binding protocol (docs/LAB_PROTOCOL.md).

Two tracks, two agents — never conflate them (like the three boxes)

This repo runs two parallel tracks with separate owners. Conflating them is the same class of failure as conflating the three boxes (chip / studio / relay) — it is how work gets un-attributable and claims get over-stated.

	Studio track	Science track
Owns	The broadcast platform: production paths, runtimes, UIs/UX, DNS, end-to-end process, and their docs	The colony's mind: the FE engine + the gated lineages
Code	`viewer/`, `production/`, `deploy/uni-os/`, `ui/` (web/broadcast surface), `CLAUDE.md`/`docs/*` studio docs	`lib/sp/brain/`, `lib/sp/runtime/`, `test/sp/brain/`, `docs/specs/`, `docs/receipts/*`
Plan	`docs/STUDIO_HARDENING_DD_TDD_PLAN.md`	`docs/DEEPENING_PLAN.md` + the pre-registered REDs
Gate style	Operational gates (`verify_*`, `restream.ps1 -Status`, the broadcast sweep)	Pre-registered RED gates (named PASS + FALSIFIES)
Touches FE code?	Never	Always (that's the point)

The one shared, read-only seam: the colony world-view is a camera the studio may show. But the colony-scene-on-program cut and any on-air life/awareness claim stay fenced to the science verdict — forage-pureworld-graduation must PASS (encoded in viewer/infra_registry.json.goLiveGate + viewer/verify_colony.cjs). The studio agent reads that gate; it never sets it.

Rule: state which track you are on at the top of any substantive change. A studio-track change that finds itself editing lib/sp/brain/* has crossed the fence — stop and hand off to the science agent.

Work the studio the way the colony thinks — an active-inference OODA loop

The point of this project is a colony that runs an active-inference loop. The operator-agent should run the same loop over the studio, so the method and the subject are one thing, not two. The metaphor is only allowed because it is tied to real code on both sides.

The colony's loop (the real code, so the metaphor never floats free)

The live tick is SP.Runtime.Agent (lib/sp/runtime/agent.ex) driving SP.Brain.MC.step/2 (lib/sp/brain/mc.ex). (Note: the live driver is SP.Runtime.Agent, not SP.Brain.Bridge, which is a Sim/Eval path — do not confuse them.)

Observe — the Minecraft body's sense line arrives over the OS Port (agent.ex).
Orient — infer_states minimises Variational Free Energy: q(s) = softmax(forward_prior + Σ γ_m · lnA) (lib/sp/brain/infer.ex). The (lnB)·s convention is bound-critical — it is not ln(B·s). Then Hebbian-Dirichlet learn (lib/sp/brain/learn.ex) updates the counts and organs grow. The slow L2 context OODA runs every @l2_period ticks (a control/preference hierarchy: situation observed up, a large-magnitude interoceptive C overridden down — NOT a predictive-coding errors-up/predictions-down stack).
Decide — action minimises Expected Free Energy over a depth-5 plan (lib/sp/brain/plan.ex, lib/sp/brain/efe.ex): epistemic H(qo) − E[H(o|s)] + pragmatic qo·C + gated parameter-novelty W. Nothing else enters the logits (the math fence; guarded by test/sp/brain/*).
Act — the chosen action goes back out the Port as a body command.

The operator-agent's loop (how to work the studio, every turn)

Observe — run the GATES, never trust process existence. node viewer/verify_overlays.cjs, node viewer/verify_colony.cjs [redacted: private-address], a fresh /producer/health probe, restream.ps1 -Status, tailscale status, grep for surviving IP literals. A running process / open port / exit 0 launcher is not a claim. Measured insight is the sense line. Gaia (viewer/gaia/, docs/GAIA.md) is a concrete, running instantiation of this step — a read-only, signal-only mirror the operator can query directly instead of trusting process existence (gate gaia-slice1-live, PASS).
Orient (VFE) — diff the measured state against the documented true state. The gap is the prediction error. Reducing that surprise — making the docs and the box agree — is the work. If a doc claims something the gate does not show, the doc is wrong (or the box is); resolve it, don't paper over it.
Decide (EFE) — pick the one next item that most reduces uncertainty and risk:
- epistemic value = it closes a NOT-VERIFIED / an unknown (measure the thing you cannot yet see).
- pragmatic value = it moves the studio toward the preferred state C: durable, DNS-only, operator-easy, on-air-honest.
- One cure at a time. Never stack changes such that you cannot attribute the winning outcome.
Act — make the change as code (never an ephemeral runtime patch), update the doc in the same breath (DD), and record the gate (TDD). Then loop.

Document-Driven (DD) = the change-management / CI

Docs are not documentation-after-the-fact; they are the change-management system. A work-item is done only when all three hold:

Code committed and pushed (production ships via git archive of a pushed, sha-verified tag — never the working tree).
Doc is true — the canonical doc or ADR that describes the surface is updated, or carries a correct superseded/stale banner. ADRs (production/docs/adr/) are the decision backbone; 011–014 are Accepted and are current truth; 001/003 are superseded-in-part; 002/004–010 are still Proposed (design-stage).
Gate recorded — its row is appended to evidence/gates.ndjson (schema production/schemas/gate_row.schema.json), which renders to docs/GATES.md and the /infra gate-ladder.

The claim fence (production/schemas/claim_fence.json) governs wording. Operational/behavioural passes demonstrate the named behaviour, never experience or life. Keep warranted claims and over-claims visibly separated — that separation is the product. Receipts beat rhetoric.

Test-Driven (TDD) = gates first

Name the PASS gate before writing the change. For a science-adjacent change also name the FALSIFIES condition. The gate is the test; the change is judged only against its pre-named gate.
The studio's integration test is the full PUBLIC broadcast sweep (POST /api/broadcast_test on command_center.cjs, extended to sweep every scene/camera/music-feed + SMPTE bars). Public is the only acceptance path.
This plan touches no FE-engine code, so the invariant guards in test/sp/brain/* are a regression fence that must stay green — they are not modified here.

The invariants that never move (studio-relevant subset)

NO IP literals in code. Ever. Every host is a <name>.uni-lab.local DNS name derived from the single declared map viewer/infra_registry.json via viewer/fqdn.cjs (fqdn(name) / url(name)). IPs live ONLY in that registry, the DNS-bootstrap resolver (viewer/infra.cjs:272), and the drift-checker's own SSH read (viewer/infra.cjs:21). viewer/hub.html is the DNS-native reference implementation.
GO LIVE is human-typed, always (gate G-PA). No agent self-approves it, widens its own autoapprove, or holds a stream key. Keys live only in the operator shell env / /etc/uni/runtime.env — never git, never an agent.
One --sname uni Phoenix node, ever — on the chip. THINKER never starts a competing colony.
Single-encode → copy fan-out. One encoder makes the program; the relay copies it to each destination.

Remote-source security model (the camera gateway) — RETRACTED 2026-07-16

HONEST CURRENT STATE. viewer/publisher.cjs and viewer/pub.html implement no PIN check and no off-LAN approval flow. grep for PIN|UNI_PUBLISH_PIN|Authorization|approval|off-LAN in either file returns zero hits. The prior text in this section (default PIN 2077, LAN-immediate, off-LAN per-stream operator approval, APPROVE/DENY banner) described a design that was never enforced by the code. The 2026-07-15 sweep found the gap; the operator picked retract, don't ship a security claim no code enforces.

The publisher is unauthenticated, LAN/tailnet only. pub.html banners this in place.
MediaMTX WebRTC (:8889) is bound loopback-only in viewer/mediamtx_local.yml so the WHIP is reachable only via the local publisher proxy, not directly from the LAN. This is the only posture defense that survives retraction.
Do not re-add a PIN or approval claim to CLAUDE.md, this file, or pub.html unless the code in publisher.cjs enforces it. Enforcement is filed for a later pass.
The [redacted: internal-hostname] name and :8443 HTTPS endpoint are unchanged; what changed is the claim about protection, not the topology.

sha256 17f6de41610fdd76 — of the original file, so what was ingested stays checkable.

Written for this website — not the document. This is a plain-language retelling, written to help you meet the document. It is not the source, and it is not evidence. It has not yet been checked by a person. Read the document itself → (or choose Precise in the reading-level control above)

This page is the binding method for how one of the two tracks of work is done. It is longer than the summary that lives in the project contract, and its rules are stated as binding rather than advisory.

It starts by separating two tracks with separate owners, and says conflating them is how work becomes unattributable and claims get overstated. A table gives what each owns, which code it may touch, and which kind of gate it uses. One track never touches the model's own code, and a rule says to state which track you are on before any substantive change.

The middle is a deliberate parallel: work the studio using the same loop the colony runs. Observe by running gates rather than trusting that a process exists. Orient by measuring the gap between the box and the documents. Decide the one next thing. Act as code, document and gate together.

One section is a retraction: a security claim no code enforced was withdrawn rather than shipped.

Plain · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 17f6de41610fdd76

Written for this website — not the document. This is a clearer retelling, written to help you meet the document. It is not the source, and it is not evidence. It has not yet been checked by a person. Read the document itself → (or choose Precise in the reading-level control above)

This document sets out a binding working method for one track of the project. It is loaded by reference from the project contract and is the fuller version of the short section there.

It opens by separating two tracks with separate owners, and names the failure it is preventing: conflating them makes work unattributable and claims overstated, in the same way that conflating the three machines does. A table gives, for each track, what it owns, which code it touches, which plan governs it, what style of gate it uses, and whether it may touch the model's own code, which for one track is never. A single shared seam is named as read-only: a camera view may be shown, but a particular cut and any on-air claim about life or awareness stay fenced behind a science verdict that this track reads and never sets. A rule follows: state which track you are on, and if a change finds itself editing the model's code, stop and hand it over.

The middle is a deliberate parallel and the page is careful to justify it: the method and the subject should be one thing, and the metaphor is only allowed because both sides are tied to real code. It first describes the colony's own loop, with the modules that implement each step. That includes a note about which component is the live driver and which is a different path easy to confuse with it. It also gives a convention in the mathematics critical to a bound, and a statement that nothing but the named terms enters the decision.

It then describes the operator's loop in the same four steps. Observe means running the gates rather than trusting that a process exists, and the page says plainly that a running process, an open port or a successful launcher is not a claim. Orient means diffing measured state against the documented state, where the gap is the prediction error. If a document claims something a gate does not show, one of the two is wrong, and must be resolved rather than papered over. Decide means picking the single next item that most reduces uncertainty and risk, with one cure at a time. Act means making the change as code, updating the document in the same breath, and recording the gate.

Two sections then define what done means. A work item is done only when the code is committed and pushed, the document that counts is true or carries a correct stale banner, and a gate row has been appended to the list that is never edited. The vocabulary is governed by a fixed list, and operational passes show a named behaviour and never experience.

A gates-first section requires the passing condition to be named before the change is written, and near the science track the refuting condition too. The integration test is the full public sweep, and the page states that public is the only acceptance path.

A list of invariants follows, including no address literals in code, a human-typed go-live that no agent may perform or widen, one node of a kind ever, and a single encode copied outward.

The last section is a retraction, and it is the most instructive part. A described security posture involving a code and an approval flow was found never to have been enforced by any code. Rather than ship a claim no code backs, the operator retracted it. The page now states the honest posture, names the one defence that survives, and instructs that the claim not be re-added anywhere until the code enforces it.

Clear · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 17f6de41610fdd76

Working logic — VFE / EFE / OODA, Document-Driven, Test-Driven (binding)

How to read this page

Precise — the source document