Skip to content
← Documentation

docs/repository-in-the-app.md


The engine gets a body

The standalone artifact proved the engine. This connects it to the running application.

repo adapter → facts → worldFromFacts → /api/world?repo=<name> → WorldScene

src/lib/world/repository.ts, tests/repository-acquire.test.ts.


Measured through the app's own path

registry: enterprise
enterprise → 44 districts · 117 buildings · 2 actors · 1405 links
refused 38× import dependency · 2 unplaced
warrants: 476 evidence / 209 convention
agents located: 0

Nothing in that chain consults PRODUCTS or AGENTS — asserted by a test that checks the module's imports, not its prose, since the module's own comment says it consults neither and a text scan would match that sentence.

The counts differ slightly from the standalone artifact (43/113) because this path also reads .js, .jsx and .mjs. Declared in one place as SOURCE, so the difference is visible rather than mysterious.

The parameter is a name, not a path

The obvious shape is ?repo=/some/path, and it is wrong. git -C <anything> reads whatever the process can reach; execFile prevents shell injection and does nothing about being pointed at the wrong directory.

So the parameter selects a name from an operator-declared registry (COGNITHAMUS_REPOS="name=/abs/path"), and there is no code path from a request to an arbitrary path. The negative tests are the load-bearing ones:

/etc/passwd          → null
../../etc            → null
/tmp/demo            → null   (the right path, by path — still not a name)
demo/../../../etc    → null
(no declaration)     → nothing offered
rel=./somewhere      → rejected; relative resolves against a cwd that varies

A missing declaration is not permission to read the disk.

An unknown name 404s rather than falling back

Returning the estate for a repository asked for by name would be a silent substitution — a different world than the one requested, which is the failure class this whole system exists to prevent. Asserted.

server-only is earned here

The rule from metric.ts is that the marker means privilege, not residence. This module executes git against the filesystem, which is the case that earns it — and a test checks both the marker and the execFile that justifies it, so the claim cannot outlive the privilege.


Standing

Generated world reaches the app? yes — through /api/world?repo=<name>
Estate removed? no — it remains the default and the calibration fixture
Path reachable from a request? no — asserted against six hostile shapes
Ontology expanded? no

What is still not established

  • Nobody has seen it render. The app is passkey-gated and signing in is the user's action, so the 3-D city built from a repository is wired, typechecked and tested at every seam — and unverified visually. To try it: COGNITHAMUS_REPOS="demo=/abs/path" npm run dev, then /?view=world&repo=demo.
  • No repository picker. The name must be typed into the URL. That is the first interaction gap, not an architectural one.
  • Acquisition is uncached and unstreamed. It shells out to git log and git show per file on every poll — fine for 117 files, and it will not hold at 10⁴. The estate path caches telemetry for 60s; this does not.
  • The 54.5% position result is unchanged and now reaches the product. The city will show an arrangement that carries no information about coupling, and the inspector is what says so.

301 → 309 tests, 26 DOM, 40 mutations, tsc clean.