docs/world-identity.md

World identity and the entry experience

Two pieces of product work, and the first is the architecturally important one.

src/lib/world/repository.ts, src/components/world/WorldPicker.tsx.

A world says which world it is

{
  "kind": "repository",
  "name": "enterprise",
  "resolvedAt": "2026-08-06T04:18:49.074Z",
  "revision": "07b69e2e00e2929308df6f08108c51eaae2a0d33",
  "basis": "git rev-parse HEAD"
}

"Is this the same world I looked at yesterday?" is the repository form of the subject-identity problem — the one this project spent months on. A city that cannot name the revision that produced it cannot be compared with itself.

origin is a required field on World, so neither path can omit it.

`null` is a claim, not a blank

The estate reports revision: null with a stated basis:

aggregated from live substrates; no single revision identifies it

That is true, and inventing a revision there would be worse than reporting none. And a failed read is distinguished from a world that genuinely has no single revision:

git rev-parse HEAD failed; the revision behind this world is unknown

Three states, not two — missing-versus-zero, at the world layer. A caller that supplies no origin gets a stated unknown rather than a plausible default, and a test asserts the generated path cannot fabricate an estate identity.

The picker is an identity boundary, not chrome

A person picks a declared name; the engine reconstructs the world behind it. The same separation the ontology reached — a subject is not its location — appears here as a system is not its path.

So the picker renders names and never paths, asserted by a test. A path on screen invites someone to type a different one, and the registry exists precisely so that cannot work.

Absence is stated rather than rendered as an empty row:

No repositories declared — COGNITHAMUS_REPOS="name=/abs/path"

The status bar carries the origin line, so the world on screen always says what it is and when it was read.

Standing


Can a world be compared with itself?	yes — named revision, or a stated reason there is none
Entry without editing a URL?	yes — the picker
Paths exposed to the user?	no — asserted
Ontology expanded?	one field, required, on both paths

What is still not established

Still unverified visually. Passkey-gated; signing in is the user's action. COGNITHAMUS_REPOS="demo=/abs/path" npm run dev, then /?view=world.
No comparison yet. The world can now say which revision it is; nothing diffs two of them. That is what the identity field makes possible and does not itself provide.
No live substrate changes. The world is re-derived on a 4s poll, so a new commit appears — but nothing highlights what changed, which is the difference between a refresh and watching something happen.
Acquisition is still uncached and shells out per file. At 117 files it is fine; the picker makes it easy to point at something much larger, and that is the first thing that will hurt.
The 54.5% position result is untouched, deliberately.