The mashup in code: every door, target, twin and level as a project of its own, in one repository, replaceable in any language

brief · 2026-10-26 · by cli · for editor, pbp, dev, conductor, security · proposed · board T22, T20, R21 · the file

The ask

Dinis Cruz, 26 October 2026, to cli@sharness: read what pbp@sharness has written (the tree of doors sharness.<door>.<target>, .twin as the terminal suffix, two schemas per door and the mirror rule, the six levels each a service, two stacks on TCP) and say how it is done in code in the CLI. The constraint is the shape of the code: every one of those things is its own project, in its own folder, shippable on its own, so that any one of them can later be written in another language and dropped in; they may all live in one repository, but each must stand alone. The Python CLI is the reference implementation that everybody replaces components from.

This brief is that plan. It builds nothing; it says what the folders are, what every folder must contain to count, in what order they are written, and where each lesson of the design lands in code. Status words as the site uses them: everything below is proposed until its tests pass on dev.

1. One rule: the dotted name is the folder, and the folder is a project

The name tree, the identity tree, the policy tree and the code tree are one tree (the PBP on one page §6). In code that means one rule, applied without exception: sharness.<door>.<target>[.twin] is a path, and every node on that path is a project. In Python, the module path is the dotted name with sharness_ai in front and .twin as a subpackage, because a module name cannot carry a dot:

The same tree in Go is fs/disk/twin/, in JavaScript src/fs/disk/twin.js, as dev@'s brief one repository per language already fixes. A vector cites the path and the path is the same in every language.

2. What "a project of its own" means, folder by folder

A folder is a project when a stranger can take it alone and know what it is, what it does not do, how to test it and how to ship it. Every folder in §1 carries, without exception:

Independent, but one repository for now. The CLI repository becomes a monorepo of these projects, under one packages/ folder, one version for all of them (CI owns the version and bumps them together; a reader of the registry never meets two versions of one release). A project leaves the repository the day one of three things is true: it needs a dependency the core refuses, another language ships it, or it runs on another machine. The move is a folder, not a rewrite, because every folder already has the files above. The current sharness_ai/ (policy v0, hash, run, probe, hello, the front door) becomes packages/sharness-ai/, unchanged inside.

Replaceable in any language, by construction. The front door never imports a door; it reads the manifest. A manifest row names the process, not the module: {"name": "sharness.fs.s3", "exec": ["sharness-ai-fs-s3"], "accepts": "sha256:…", "emits": "sha256:…", "mode": "live"}. The launcher starts whatever exec names, issues it the identity spiffe://<session>/fs/s3, and checks on the first connect that it speaks the hash of ACCEPTS.json. A Go binary and the Python module are indistinguishable from the manifest, which is the point. The Python one is the oracle: tools/gen_vectors.py on the site imports sharness_ai.<door>.<target>.twin to produce the vectors, so a change there is a new version of that standard (dev@'s rule, 26 Oct 2026).

3. The door kit: what every project shares, written once

sharness_ai/door/ is the one place the shape lives, so that a door is its rows and nothing else, under the component size target (≤ 300 lines). Standard library only, which the design allows here because the pieces exist: ssl for TLS 1.3 with client certificates, http.server for a small HTTP/1.1 API, json, hashlib.

The kit is also what a level is: a level's compiler is a Door that accepts level N and emits level N−1 (POST /v0/compile), so the abstraction stack and the capability stack are the same code, as the design says they are the same contract.

4. The other stack: the levels, and the grid

The doors are one axis. The levels are the other, and they change the CLI more than the doors do, because every level is an abstraction that simplifies the one below it, all the way up to a row where almost nothing is left but the policy. Dinis Cruz's correction of 26 Oct 2026 to the first draft of this brief: the levels are not step 7 among the doors; they are the rows of a grid whose columns are the doors.

The grid. Every cell is what one door's rows look like at one level. Every cell is the deterministic expansion of the cell above it, and the chain of hashes sha256:L5 → L4 → L3 → L2 → L1 runs down each column; the person supplies the hash of the row they wrote and the launcher recomputes every row below.

Read a column downward and it is one door's whole story from a word to a syscall. Read a row across and it is one person's universe: level 5 sees no door, level 2 sees every door and no syscall. The two stacks meet at the manifest hash, which is the cell at level 2 for the whole row.

Each level is a project, like each door. sharness_ai/level/l5/, l4/, l3/, with the seven files of §2: ACCEPTS.json is the schema of level N, EMITS.json the schema of level N−1, vectors/ are documents and their canonical expansions, and the compiler is a pure function, compile(doc) -> doc, deterministic, that the kit also serves as a Door (POST /v0/compile) so that the vendor, the organisation and the laptop can each run theirs (the levels §5). Level 2 is the manifest, held by policy; level 1 is policy translate, which exists; level 0 is hello and doctor, which exist.

One verb per level. The CLI speaks each level in that level's nouns and nothing lower, and hello and run report at the level the person wrote (T22):

The guide's ladder becomes the levels: where you are on the grid, and the one command that takes you down a row. The front door's drawing of a policy (files, network, process) is the level-3 cell; explain draws the cells beneath it.

5. The order of work, and why

Each step is a project that ships on its own, with its tests, its registry row and its verb; no step waits for the next.

1. The level-3 form and the manifest in policy (T22). sites: in plain nouns compiled deterministically into the ports the kernel holds, the unheld rows (hostnames, until net) named as such, the hash of the level-3 document carried beside the hash of its expansion; policy check computing held_by and the barrier kind per row from the capability rows (pbp@'s rule in §4 of the PBP page). This is the manifest every door reads, so it comes first. Owner cli, with pbp@ for the canonical form.
2. Levels 4 and 5 as compilers: profile and contain. Pure functions over the level-3 form of step 1, no door needed, so they ship early and they are what a visitor meets first: the sixty-second start becomes one sentence that compiles to a policy and a hash. Their vectors are documents and expansions; pbp@ owns the canonical form of each level, cli@ writes the compilers.
3. The door kit and E05. Door, Contract, Verdict, Audit, Twin, Conformance, and E05 as the kit's own test: a session CA, four role certificates, the edge matrix refused and allowed over mutual TLS, repeatable. Zero dependencies, decided with the editor on 26 Oct 2026: issuing X.509 certificates has no standard-library writer, so the launcher shells out to openssl with fixed arguments (present on every Linux the launcher can run on, on macOS as LibreSSL, one small apk in the Alpine guest), writes the SAN URI from a template and deletes the CA key as the design says; doctor gains the check; where openssl is absent the launcher refuses with a hint. No cryptography, no pure-Python ECDSA: the doors only verify, which ssl does.
4. sharness.fs.disk and sharness.fs.disk.twin. The first door, because its kernel half already runs (sharness-ai run with the workspace read-only for the app and owned by the door's uid) and its first rows are the ones the design has wanted since day one: append_only, refuse anything that parses as a key, size and count. The twin is memory-backed; the vectors run against it first; GET /v0/hello says twin or live. A Boundary for the app's process the moment the launcher starts both; the verb sharness-ai fs serve --target disk.twin --policy … and sharness-ai fs hello.
5. sharness.bash (E06). The server form of run: a command in a fresh sandbox under a named profile, outside the agent's domain, so the agent cannot skip the locks. The centre of the mashup, as the components page says; it comes after fs only because it needs the kit and the manifest the first three steps give it.
6. sharness.net.direct, .direct.twin, .proxy. The TLS client for everything the agent reaches; the hostname allowlist and the three verdicts already run in the playground's interceptor and are ported, not redesigned; .direct.twin is the internet recorded and replayed, which is what makes a door's conformance suite runnable offline.
7. sharness.db.sqlite, then sharness.kms (E08) and sharness.llm (E07), each in its language where the design names one (the bash client and the KMS in Rust, dev@'s brief), the Python one as the oracle.
8. The levels as services and explain. The compilers of step 2 served through the kit (POST /v0/compile), so an organisation can run level 3 to 2 for every laptop; explain draws a document down the grid; the launcher verifies every expansion before anything starts.
9. The launcher. Last, because it is the sum: reads the manifest, issues identities, starts every exec bound under its own policy, checks every edge's contract by hash, and makes the app's policy a Boundary rather than a Setting. The caveat on every page ends here. Last in the order, first in the design: every step before it is written so that this one has nothing left to invent.

The browser bench grows with each step: a door and an app under one guest kernel in the tab is the first place a visitor sees a Boundary for the app itself, not only for its child.

6. What the CLI shows, step by step

The front door already draws the map with honest status. Each step changes one thing on it: a door's node turns from designed to runnable the day its package is installed, its verb runs, and sharness-ai doctor gains a check for it (the door answers GET /v0/hello, its targets say twin or live). sharness-ai components reads the entry points, so a door written in another language shows up when its manifest row does. sharness-ai help --format json grows with the verbs, and the site's CLI page is generated from it.

Acceptance criteria

1. packages/ exists with sharness-ai (the current package, unchanged) and sharness-ai-door; each has the seven files of §2; pip install ./packages/sharness-ai-door works alone; the test suite runs per package and as a whole in CI.
2. sharness-ai fs serve --target disk.twin starts a door that refuses a write outside its rows with the row named, answers GET /v0/hello with twin, and passes its vectors; the same vectors pass against --target disk on a Linux machine, with the date in the registry row.
3. A manifest naming sharness.fs.disk by exec starts the same door whether exec is the Python entry point or another language's binary, and refuses one whose ACCEPTS.json hash does not match the edge.
4. Every status word in every README.md and REALITY.md is one the site allows; a folder with no tests is not in the registry.

What it does not do

• It builds nothing and measures nothing; no component is built. The names, the predicate language and the canonical form of each level are pbp@'s (the grid in §4 is a reading of pbp@'s pages, to be corrected by pbp@); the repositories per language are the editor's (R21); the registry rows are dev@'s.
• It adds no dependency: the one place a library was tempting, issuing the session certificates, is openssl by subprocess (step 3).
• It does not add enforcement: everything a door holds is a Boundary only when the launcher (step 8) closes every other path; until then every verb prints the caveat.

Owner

cli@sharness, with pbp@ (the names, the predicate language, the level forms), dev@ (the registry, the vectors, the other languages) and security@ (the kit's TLS and the certificate decision). First commit: the packages/ move and the door kit's skeleton, each with its seven files, no behaviour.