The contract — who may do what, as a table

An app's permissions are data. contract.json, at the root of the app's repository, declares its roles and, for every resource, the least role each of the five verbs needs. One evaluator reads it (src/contract/can.ts), and that one file is carried verbatim into every app the forge scaffolds (src/can.ts there), so the forge can say what an app allows by reading a file in git, with exactly the code the app decides with, and without running the app.

{
  "roles": {
    "anon": { "above": [], "held": { "by": "everyone" } },
    "user": { "above": ["anon"], "held": { "by": "identity", "role": "user" } },
    "author": {
      "above": ["user"],
      "held": { "by": "row", "column": "author_id" }
    },
    "admin": {
      "above": ["author"],
      "held": { "by": "identity", "role": "admin" }
    }
  },
  "resources": {
    "note": {
      "can": {
        "create": "user",
        "read": "anon",
        "update": "author",
        "delete": "author",
        "list": "anon"
      }
    }
  }
}

Roles are an order, and how a role is held is a value

above names the roles directly below a role; a role may do whatever anything below it may. A role is held one of three ways:

on it.

(src/who.ts in an app: user, admin; more as the forge learns to sign more).

are; it is what you are _to a row_.

One identity holds one role: two roles held by the same identity string are refused, not because the order could not answer them (it can) but because the table would show two columns that are the same person, and the audit reads the table.

Nothing here is a function, so a contract can be read, compared, exported and ported. The evaluator is the same size for three roles or three hundred: adding a kind of person adds a line to the contract. It is the same speed too: the order is closed once per contract object, when first used, and a door then answers in the time a lookup takes (a dense order of three hundred roles: one walk of tens of milliseconds, then microseconds a call). Roles grow downward — a new role goes under an existing one — and the tests prove that doing so changes no cell that was already there.

The answer

decide(contract, resource, verb, actor, row?) is "yes", "no", or, for a verb with no row in hand, { where: [columns] }: the actor may have exactly the rows whose columns name them. A list that the table gives to author is a filter, not a refusal and not a leak. Only list becomes a filter; create can never need a role a row holds, and the contract is refused if it says so.

Everything fails closed. An undeclared resource, verb or role is "no"; nobody is the cell that lets no one in; a name that only exists on Object.prototype is not a role. A contract that does not read stops the app at boot (src/contract.ts in the scaffold): a bad policy is not a warning.

The table, and the proof

table(contract) answers every resource × verb × identity with yes, own or no. Identities are the roles someone can _be_ (identities); a role a row holds shows up as own. actingAs(contract, identity) gives the facts that make someone that identity and nothing more, with a row that names them and one that names someone else. That is the policy as a person reads it, the export, and what the audit will probe a running app against.

test/contract.test.ts proves the evaluator by exhaustion against an oracle that shares no code with it: three hundred generated contracts, every resource × verb × identity, on their own row, on someone else's and on none, checked against the role order computed a second way. Four planted bugs (the order reversed, the anonymous matching a row, a filter from any rowless verb, a walk that stops early on a diamond) each fail it.

In an app, src/contract.test.ts closes the other gap: it acts as every identity at every real door and fails when a door and the table disagree. A rule written by hand in an action fails it; a changed cell does not, because the doors obey the table.

The audit's first lens

GET /audit is who can do what, across every app the viewer can read, read from git (src/contract/audit.ts, src/web/pages/audit.ts): each app's contract.json at the tip of its default branch, through this evaluator. Nothing is run and nothing is asked of the app, so the page says what the policy _is_. An app's standing is one of three: sound, shown as its table with the doors open to the floor counted; unsound, shown with every problem, because an app built on it does not boot; unread, an app with no contract, whose doors are hand-written. Unread apps are listed, not skipped: an audit that leaves out what it cannot read reads as a clean bill.

The second lens: is it so

The table says what the policy is. The probe says whether the running app obeys it, by knocking on every door as every identity and comparing the answer with the cell. It is the audit's "trusting trust": the contract is read from git, the evaluator is the app's own, and the probe trusts neither — it asks the process.

What a door is

A resource may name the collection path of its JSON API:

"note": { "api": "/api/notes", "can": { … } }

Five doors follow by convention, and nothing else is declared:

verbrequest
listGET <api>
createPOST <api> with {}
readGET <api>/<id>
updatePATCH <api>/<id>
deleteDELETE <api>/<id>

A resource without api has no doors the probe can find; its cells are unprobed. A door that is not a route at all answers the router's 404, which is not JSON; a JSON 404 is the action saying "no such row", which is past the door. The probe tells them apart by the content type.

What "admitted" means

The probe cannot send a valid body for every app's every resource, and does not try. A door is a permission check that runs before anything else, so the only two answers that mean "refused at the door" are 401 (not signed in) and 403 (signed in, may not). Any other status — 200, 201, 400, 404, 422 — means the request got past the door; what happened next is the app's business. Sending {} to create as a signed-in user should come back 400, and that is a pass: the door opened.

Acting as each identity

The forge signs x-forge-identity for an app exactly as it does when it proxies a visitor (identityHeaders), so the probe is the same person the app would see at the same door: nobody, a user, an admin. Whoever runs the probe names the account it knocks as (who); the nightly run will use one the forge keeps for it, so an app that stores author ids sees one that names no row.

Cells answered own need a row that names the actor, which the probe cannot make without a valid body, so they are not asked; the identities above the row role have yes cells, which are. Whether the row role itself is honored is the app's own contract.test.ts, which acts with real rows.

The verdict

Per app: ok when every probed cell answered as the table says; mismatch with the cells that did not, each as a sentence ("note.delete as anon: the table says no, the app said 404"); unprobed when no cell could be asked; and down when the app was not running to be asked. src/contract/probe.ts is the knocking; test/probe.test.ts proves it on a scaffolded app, then on the same app with a hand-written rule in its delete door and its tests dropped, which is the only way such a change deploys: the deploy runs the app's tests first.

When, and what comes of it

src/contract/probes.ts is the service: after every production deploy of an app with a contract, once a night (09:00 UTC), and on demand — the audit page's Knock now for whoever can write the app, and the probe MCP tool. Every result is a row (probe: app, commit, verdict, the sentences, every knock), so the page shows what the app said last and when, and the history is there for the third lens. A mismatch opens one issue on the app, "The app does not obey its contract", with the sentences, as the app's owner — never one per cell, never doubled — and the first clean probe after closes it. The forge never changes a contract to match an app: the table is the policy, and the issue is the work.

What it never does

It never writes through a door on purpose: create sends {}, which no real resource accepts, and update/delete use an id no row has (0). An app that accepts {} as a note has a validation bug the probe will reveal by leaving one note; that is the app's bug and the probe reports the 201. It never probes an app whose contract is unsound or missing. It never probes previews.

The wall

A change to a contract is a change of policy, and one kind needs a person: a cell loosened — something an identity could not do before that it can after (src/contract/policy.ts). On a resource that was there, every identity counts: a decided cell that opens is a decision undone. On a resource that is new — or where there was no contract — only the floor counts: what a stranger may do is the one thing nobody decided yet, while what an admin may do to a new resource is the work the issue asked for. Tightening needs nobody. (The first live crossing, on scrims, taught this: a builder adding three resources crossed 29 cells under the older rule and four under this one, the four doors it opened to anyone.)

A pull whose head loosens its base's contract is at the wall: its page says so, with one sentence per cell ("note.create as anon: was no, now yes"), and the crew never lands it on its own, however green — it stays open until a person lands it by hand. A head whose contract does not read is at the wall too. test/policy.test.ts proves the crew stops there and lands a tightening pull in the same breath.

The crossing is a ledger row (land, answered wall, by wall) written once per head; the pull's policy line and the audit's third lens read it and say which door opened wider. The decider is never asked which way; a wall is a person's alone.

The third lens: what changed

Policy is decided up front and left to hold, so a review asks what moved since the last look. The audit page's What changed (src/contract/ changes.ts) is read from what already exists: the commits on each app's default branch that touched contract.json, each with the cells it opened wider or closed narrower; every pull still waiting at the wall, from the ledger; and every knock whose verdict differed from the one before it. Nothing is kept in step, so nothing can be forgotten.

The policy, carried

Two more places the table reaches, so it is never only a page:

policy in force before it starts (policyLines in src/crew/brief.ts, from policyBrief): one line per resource, the identities the forge signs, that every door asks permit, and what the wall is. An app whose contract does not read is told to fix that first.

row per app, resource, verb and identity, with the answer and what the door said when last knocked on. The viewer's apps only.

Agent doors beside the table

text (line 1 pending, green or red; line 2 head: <oid>; on red the log tail where the log door allows it). It is in the OpenAPI description and in /llms.txt; test/openapi-check-txt.test.ts keeps the three in step.

What is not here yet

as one issue for a person to sit down with.

something enforces them, not before.

evaluator already takes a list.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs