amalgm 0.1.246 → 0.1.247

package/runtime/scripts/amalgm-mcp/tests/registration.service.test.js

@@ -3,38 +3,72 @@
 /**
  * The production-owned vertical slice:
  *
- *   amalgm add [path] → POST /entities/add → registration.add(path)
+ *   amalgm register [path] → POST /entities/register → registration.register(path)
  *                     → Watch + Detect + Record
  *
  * The wall already proves detection. What is unproven here is the
  * WIRING — the parts that only exist because production owns the stack:
- * which policies are actually injected, where state lands, that the
- * observer's events genuinely reach the boundary, that identity
- * survives a process restart over the same directory, and that the
- * endpoint reports refusal as refusal.
+ * which policies are actually injected, where state lands, that a real
+ * doorbell reaches the registry with nobody poking the machinery, that
+ * identity survives a genuine close-and-reopen, that the composition
+ * root gives back everything it took, and that the endpoint tells a
+ * refusal from a fault over a real authenticated socket.
+ *
+ * Two rules this file holds itself to:
+ *
+ *   NO ASSISTED PASSES. Nothing here calls `scanNow` or `flushIfDirty`
+ *   to make a rail appear to work. A rail is proven through its own
+ *   front door or it is not proven — so the timings are production's
+ *   own (a 200ms settle), and the exams wait for them.
+ *
+ *   NO FAKE TRANSPORT. The endpoint exams go over real HTTP through the
+ *   real authorizing handler and the real dispatcher. A route proven
+ *   against a hand-made context object proves the function, not the
+ *   journey.
  *
  * Everything runs over a temporary AMALGM_DIR, set before config loads,
  * so the singleton this route uses can never touch a real installation.
  */
 
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
 const fs = require('fs');
+const http = require('http');
 const os = require('os');
 const path = require('path');
 const test = require('node:test');
 const assert = require('node:assert');
 
-const tempRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-add-')));
+const tempRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-register-')));
 process.env.AMALGM_DIR = path.join(tempRoot, 'home');
+// The runtime reads its token from the environment; the CLI reads the
+// same secret from disk and sends it. Setting it here makes the server
+// below demand authorization exactly as production does.
+process.env.AMALGM_RUNTIME_TOKEN = crypto.randomUUID();
+
+const Database = require('better-sqlite3');
 
 const { classifyFile } = require('../registration/classify');
+const { isRefusal } = require('../registration/refusal');
 const { ENTITIES_DIR, createRegistrationService, registrationService } = require('../registration/service');
-const { handleEntityRoutes } = require('../server/routes/entities');
+const { adapterFor } = require('../adapters');
+const { createRuntimeHttpServer } = require('../server/http-service');
 const { createLocalServiceRouter } = require('../server/local-service-router');
 
 const services = [];
+let server;
+let port;
+
+test.before(async () => {
+  const router = createLocalServiceRouter();
+  server = createRuntimeHttpServer((ctx) => router.handle(ctx), { serviceName: 'AmalgmMCP-test' });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  port = server.address().port;
+});
 
-test.after(() => {
-  for (const service of services) service.stop();
+test.after(async () => {
+  for (const service of services) service.close();
+  if (server) await new Promise((resolve) => server.close(resolve));
   fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
@@ -51,32 +85,83 @@ function makeGround(name) {
   return fs.realpathSync(dir);
 }
 
-// --- the injected type policy ---------------------------------------------
+/** Exactly the request the CLI makes: JSON body, token in its header. */
+function post(requestPath, body, { token = process.env.AMALGM_RUNTIME_TOKEN } = {}) {
+  const payload = JSON.stringify(body);
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      host: '127.0.0.1',
+      port,
+      path: requestPath,
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(payload),
+        ...(token ? { 'x-amalgm-runtime-token': token } : {}),
+      },
+    }, (res) => {
+      let text = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { text += chunk; });
+      res.on('end', () => {
+        let parsed = null;
+        try { parsed = JSON.parse(text); } catch { parsed = null; }
+        resolve({ status: res.statusCode, payload: parsed });
+      });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
 
-test('classify: ordinary bytes are text', () => {
-  const file = path.join(makeGround('classify-text'), 'notes.md');
-  fs.writeFileSync(file, '# hello\nplain words\n');
-  assert.equal(classifyFile(file), 'file.text');
-});
+/**
+ * Make ONE change through the front door and wait for the registry to
+ * show it on its own.
+ *
+ * One change, never repeated, because that is the user: they save once.
+ * Nothing here scans, flushes, or repairs; a rail that needs help fails,
+ * loudly, at the deadline, which is generous only because the whole wall
+ * shares one machine. A converging rail returns the moment it converges.
+ */
+async function arrives(act, seen, what, timeoutMs = 30_000) {
+  act();
+  const deadline = Date.now() + timeoutMs;
+  while (!seen()) {
+    if (Date.now() > deadline) assert.fail(`timed out waiting for ${what}`);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+}
+
+// --- one read, one answer ---------------------------------------------------
+
+const fileTruth = adapterFor('file.text').rails.detect.truth;
 
-test('classify: a NUL in the opening bytes means bytes, never text', () => {
-  const file = path.join(makeGround('classify-binary'), 'blob.bin');
-  fs.writeFileSync(file, Buffer.from([0x89, 0x50, 0x00, 0x4e, 0x47]));
-  assert.equal(classifyFile(file), 'file.binary');
+test('Detect reports a file\'s type from the same read that fingerprints it', () => {
+  const dir = makeGround('one-read');
+  const text = path.join(dir, 'notes.md');
+  const bytes = path.join(dir, 'blob.bin');
+  fs.writeFileSync(text, '# hello\nplain words\n');
+  fs.writeFileSync(bytes, Buffer.from([0x89, 0x50, 0x00, 0x4e, 0x47]));
+
+  const read = fileTruth(text);
+  assert.equal(read.truth, 'present');
+  assert.ok(read.state.sha256, 'the fingerprint');
+  assert.equal(read.state.binary, false, 'and the kind, from the same bytes');
+  assert.equal(fileTruth(bytes).state.binary, true);
 });
 
-test('classify: ground that cannot be read supports no structural claim', () => {
-  // The weaker of the two answers, never a throw: the caller is
-  // mid-transaction over a hash it already holds.
-  assert.equal(classifyFile(path.join(tempRoot, 'never-existed')), 'file.binary');
+test('a NUL anywhere is seen, not only in an opening window', () => {
+  // The whole file is streamed for the hash, so the kind is decided over
+  // the whole file too. A sniff window would have called this text and
+  // disagreed with the referee, which reads every byte.
+  const file = path.join(makeGround('late-nul'), 'long.bin');
+  fs.writeFileSync(file, Buffer.concat([Buffer.alloc(200_000, 0x61), Buffer.from([0])]));
+  assert.equal(fileTruth(file).state.binary, true);
 });
 
-test('classify: a NUL past the sniff window does not retroactively unmake text', () => {
-  // The law is about the OPENING bytes, stated exactly so a huge text
-  // file is never re-read whole to answer a hint.
-  const file = path.join(makeGround('classify-late'), 'long.txt');
-  fs.writeFileSync(file, Buffer.concat([Buffer.alloc(9000, 0x61), Buffer.from([0])]));
-  assert.equal(classifyFile(file), 'file.text');
+test('the type policy is total: it names a type for either report, and cannot fail', () => {
+  assert.equal(classifyFile({ binary: false }), 'file.text');
+  assert.equal(classifyFile({ binary: true }), 'file.binary');
 });
 
 // --- composition: what production actually builds --------------------------
@@ -94,14 +179,130 @@ test('the singleton lives under the Amalgm home, and is one', () => {
   services.push(registrationService());
 });
 
-test('add registers the named ground and every file beneath it', () => {
+test('user-home bootstrap creates only declared roots and registers them through the shared registration boundary', async () => {
+  const home = path.join(tempRoot, 'user-home');
+  const service = createRegistrationService({
+    dir: path.join(tempRoot, 'state-user-home'),
+    homeDir: home,
+  });
+  services.push(service);
+
+  const bootstrapped = await service.bootstrapUserHome();
+  assert.equal(bootstrapped.homeDir, home);
+  assert.deepEqual(bootstrapped.roots.map((entry) => entry.key), [
+    'agents', 'apps', 'automations', 'toolbox', 'workspaces', 'system',
+  ]);
+  for (const entry of bootstrapped.roots) {
+    assert.equal(entry.record.parentUUID, null, `${entry.key} is its own registered tree`);
+    assert.ok(entry.record.uuid, `${entry.key} received a UUID through registration`);
+    assert.equal(service.registration.tree(entry.path).root().uuid, entry.record.uuid);
+  }
+  assert.deepEqual(
+    bootstrapped.exactManaged.map((entry) => [entry.key, entry.scope]),
+    [
+      ['agents-root', 'exact'], ['apps-root', 'exact'], ['automations-root', 'exact'],
+      ['toolbox-root', 'exact'], ['workspaces-root', 'exact'], ['system-root', 'exact'],
+      ['home-manifest', 'exact'], ['defaults', 'exact'], ['policy', 'exact'],
+    ],
+  );
+  for (const entry of bootstrapped.exactManaged) {
+    assert.ok(entry.record.uuid, `${entry.key} is registered before cloud governance`);
+    const root = bootstrapped.roots.find((candidate) => candidate.key === entry.rootKey);
+    if (entry.relativePath === entry.rootKey) {
+      assert.equal(entry.record.uuid, root.record.uuid,
+        'a managed root is marked by its own exact entity identity');
+    } else {
+      assert.notEqual(entry.record.uuid, root.record.uuid,
+        'a managed child has its own exact entity identity, never inherited management');
+    }
+  }
+
+  const repeat = await service.bootstrapUserHome();
+  assert.deepEqual(
+    repeat.roots.map((entry) => entry.record.uuid),
+    bootstrapped.roots.map((entry) => entry.record.uuid),
+    'bootstrap is idempotent: existing declared ground is covered by the same trees',
+  );
+});
+
+test('a fresh machine binds existing user-home UUIDs before it starts watching', async () => {
+  const first = createRegistrationService({
+    dir: path.join(tempRoot, 'state-user-home-origin'),
+    homeDir: path.join(tempRoot, 'user-home-origin'),
+  });
+  services.push(first);
+  const origin = await first.bootstrapUserHome();
+
+  const recipient = createRegistrationService({
+    dir: path.join(tempRoot, 'state-user-home-recipient'),
+    homeDir: path.join(tempRoot, 'user-home-recipient'),
+  });
+  services.push(recipient);
+  const restored = await recipient.bootstrapUserHome({ identitySnapshot: origin.cloudSnapshot });
+
+  assert.deepEqual(
+    restored.roots.map((entry) => entry.record.uuid),
+    origin.roots.map((entry) => entry.record.uuid),
+    'the cloud graph supplies root UUIDs instead of a new machine minting replacements',
+  );
+  assert.deepEqual(
+    restored.exactManaged.map((entry) => entry.record.uuid),
+    origin.exactManaged.map((entry) => entry.record.uuid),
+    'exact platform-managed targets retain their own identities too',
+  );
+  assert.equal(recipient.observer.status().every((root) => root.watching && !root.degraded), true,
+    'only the bound identities enter Watch');
+});
+
+test('a signed-in register call writes every entity delivery intent in identity.db before Watch begins', async () => {
+  const service = createRegistrationService({
+    dir: path.join(tempRoot, 'state-cloud-register'),
+    homeDir: path.join(tempRoot, 'cloud-user-home'),
+    cloudUserId: 'user-cloud-register',
+    cloudDeviceId: 'computer-cloud-register',
+  });
+  const home = await service.bootstrapUserHome();
+  const bootstrap = service.entityCloud.bootstrap(service.registration.registry);
+  service.entityCloud.install({
+    registry: service.registration.registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  const ground = makeGround('cloud-register');
+  fs.writeFileSync(path.join(ground, 'one.md'), 'one');
+
+  try {
+    const registered = await service.register(ground);
+    const db = new Database(path.join(service.dir, 'identity.db'), { readonly: true });
+    const rows = db.prepare('SELECT operation_json, mutation_state FROM entity_cloud_mutations ORDER BY sequence').all();
+    db.close();
+    const emitted = rows.map((row) => JSON.parse(row.operation_json).record.uuid);
+    const childUuid = service.registration.tree(ground).registry.activeAt(registered.record.uuid, 'one.md').uuid;
+    assert.ok(rows.length >= 2, 'the root and its child each have a durable cloud operation');
+    assert.ok(emitted.includes(registered.record.uuid));
+    assert.ok(emitted.includes(childUuid));
+    assert.equal(rows.every((row) => row.mutation_state === 'pending'), true);
+    const childHead = service.registration.tree(ground).registry.syncRecord(childUuid).payloadVersion;
+    const captured = JSON.parse(fs.readFileSync(path.join(service.dir, 'content', 'manifests', `${childHead}.json`), 'utf8'));
+    assert.equal(captured.bytes, 3, 'Register captures the child bytes before it emits their cloud head');
+    assert.equal(captured.chunks.length, 1);
+    assert.ok(home.roots.length, 'the bootstrap graph existed only in the initial entity snapshot');
+  } finally {
+    service.close();
+  }
+});
+
+test('register registers the named ground and every file beneath it', async () => {
   const service = makeService('add');
   const ground = makeGround('add');
   fs.writeFileSync(path.join(ground, 'a.txt'), 'alpha');
   fs.mkdirSync(path.join(ground, 'nested'));
   fs.writeFileSync(path.join(ground, 'nested', 'b.bin'), Buffer.from([0, 1, 2]));
 
-  const { rootPath, record } = service.add(ground);
+  const { rootPath, record } = await service.register(ground);
   assert.equal(rootPath, ground);
   assert.ok(record.uuid, 'the tree has a permanent identity');
   assert.equal(record.parentUUID, null, 'a tree is a parentless record');
@@ -116,11 +317,25 @@ test('add registers the named ground and every file beneath it', () => {
   assert.equal(nested[0].type, 'file.binary', 'and it distinguishes bytes from text');
 });
 
-test('watching is armed: add begins the Watch rail, not just the walk', () => {
+test('registerMany registers every selected file or folder through the one registration boundary', async () => {
+  const service = makeService('add-many');
+  const folder = makeGround('add-many-folder');
+  const file = path.join(makeGround('add-many-file-parent'), 'solo.md');
+  fs.writeFileSync(path.join(folder, 'inside.md'), 'inside');
+  fs.writeFileSync(file, 'solo');
+
+  const results = await service.registerMany([folder, file]);
+  assert.deepEqual(results.map((entry) => entry.rootPath), [folder, file]);
+  assert.deepEqual(results.map((entry) => entry.record.parentUUID), [null, null]);
+  assert.equal(service.observer.status().filter((root) => root.watching && !root.degraded).length >= 2, true,
+    'each selected root passed through Register → Watch');
+});
+
+test('watching is armed: register begins the Watch rail, not just the walk', async () => {
   const service = makeService('watching');
   const ground = makeGround('watching');
   fs.writeFileSync(path.join(ground, 'a.txt'), 'alpha');
-  service.add(ground);
+  await service.register(ground);
 
   const [root] = service.observer.status();
   assert.equal(root.path, ground);
@@ -128,31 +343,322 @@ test('watching is armed: add begins the Watch rail, not just the walk', () => {
   assert.equal(root.degraded, false);
 });
 
-test('the Detect → Record wire is live: a later change reaches the registry', () => {
-  const service = makeService('wire');
-  const ground = makeGround('wire');
+test('adding a repository registers its allowed tree and saves its initial Repocard baseline', async () => {
+  const service = makeService('repo-card');
+  const repo = makeGround('repo-card');
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  fs.writeFileSync(path.join(repo, 'readme.md'), '# initial checkpoint\n');
+  fs.mkdirSync(path.join(repo, 'src'));
+  fs.writeFileSync(path.join(repo, 'src', 'blob.bin'), Buffer.from([0, 1, 2]));
+  fs.mkdirSync(path.join(repo, 'node_modules'));
+  fs.writeFileSync(path.join(repo, 'node_modules', 'ignored.js'), 'never register me');
+
+  const { record: registered } = await service.register(repo);
+  const tree = service.registration.tree(repo);
+  assert.equal(registered.type, 'repo.git');
+  const initialState = service.registration.repoState(registered.uuid);
+  assert.ok(initialState?.stateId, 'registration saved the initial Card + Checkpoint');
+  assert.ok(initialState.checkpoint.untracked.some((file) => file.path === 'readme.md'),
+    'the persisted baseline contains the actual working checkpoint, not only its hash');
+  assert.equal(tree.root().version, registered.version,
+    'add returned only after the repo entity pointed at its saved baseline');
+  const readme = tree.registry.activeAt(registered.uuid, 'readme.md');
+  const src = tree.registry.activeAt(registered.uuid, 'src');
+  assert.equal(readme.type, 'file.text');
+  assert.equal(src.type, 'folder');
+  assert.equal(tree.registry.activeAt(src.uuid, 'blob.bin').type, 'file.binary');
+  assert.equal(tree.registry.activeAt(registered.uuid, 'node_modules'), null,
+    'the same enrollment policy excludes dependency trees inside repos');
+  const initial = tree.root();
+
+  // Only a settled new checkpoint may reconcile child ground. The raw
+  // filesystem event itself never writes a repo or child record.
+  await arrives(
+    () => fs.writeFileSync(path.join(repo, 'later.md'), 'untracked checkpoint change\n'),
+    () => tree.root().version !== initial.version
+      && Boolean(tree.registry.activeAt(registered.uuid, 'later.md')),
+    'the worktree change to become one new repo state and child entity',
+  );
+  const after = tree.root();
+  assert.equal(after.uuid, initial.uuid, 'the codebase remains one entity');
+  assert.equal(after.type, 'repo.git');
+  const later = tree.registry.activeAt(registered.uuid, 'later.md');
+  assert.equal(later.type, 'file.text');
+
+  await arrives(
+    () => fs.renameSync(path.join(repo, 'later.md'), path.join(repo, 'moved.md')),
+    () => tree.registry.activeAt(registered.uuid, 'moved.md')?.uuid === later.uuid,
+    'the settled repo diff to preserve a moved child UUID',
+  );
+
+  // Repocard's own wall proves that this is `card.changed`; this composition
+  // exam proves the semantic result reaches the repo UUID through the real
+  // watcher after Git turns the checkpoint into committed history.
+  await arrives(
+    () => {
+      execFileSync('git', ['add', 'moved.md'], { cwd: repo });
+      execFileSync('git', [
+        '-c', 'user.name=Amalgm Test',
+        '-c', 'user.email=amalgm-test@example.invalid',
+        'commit', '-qm', 'record checkpoint',
+      ], { cwd: repo });
+    },
+    () => tree.root().version !== after.version,
+    'the committed Card state to be recorded on the same repo entity',
+  );
+  assert.equal(tree.root().uuid, after.uuid);
+});
+
+test('an edge-reached repository gets the same complete registration as a directly added repo', async () => {
+  const service = makeService('edge-repo-card');
+  const holder = makeGround('edge-repo-holder');
+  const target = makeGround('edge-repo-target');
+  execFileSync('git', ['init', '-q'], { cwd: holder });
+  execFileSync('git', ['init', '-q'], { cwd: target });
+  fs.mkdirSync(path.join(target, 'src'));
+  fs.writeFileSync(path.join(target, 'src', 'entry.js'), 'export const ready = true;\n');
+  fs.symlinkSync(target, path.join(holder, 'linked-repo'));
+
+  await service.register(holder);
+
+  const targetTree = service.registration.tree(target);
+  assert.ok(targetTree, 'the reachable repo is a registered tree, not merely an observer root');
+  const targetRoot = targetTree.root();
+  assert.equal(targetRoot.type, 'repo.git');
+  assert.ok(service.registration.repoState(targetRoot.uuid)?.stateId,
+    'the repo has its Card + Checkpoint baseline before add returns');
+
+  const src = targetTree.registry.activeAt(targetRoot.uuid, 'src');
+  assert.equal(src?.type, 'folder', 'the repo worktree shape was structurally registered');
+  assert.equal(targetTree.registry.activeAt(src.uuid, 'entry.js')?.type, 'file.text');
+
+  const observerRoot = service.observer.status().find((row) => row.path === target);
+  assert.equal(observerRoot?.watching, true, 'its Watch rail is live too');
+  assert.equal(observerRoot?.degraded, false);
+});
+
+test('a nested repository has its own baseline and watcher, while its tree remains registered', async () => {
+  const service = makeService('nested-repo-card');
+  const repo = makeGround('nested-repo-card');
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  const nested = path.join(repo, 'vendor', 'library');
+  fs.mkdirSync(path.join(nested, 'src'), { recursive: true });
+  execFileSync('git', ['init', '-q'], { cwd: nested });
+  fs.writeFileSync(path.join(nested, 'src', 'entry.js'), 'export const answer = 42;\n');
+
+  const { record: root } = await service.register(repo);
+  const tree = service.registration.tree(repo);
+  const vendor = tree.registry.activeAt(root.uuid, 'vendor');
+  const library = tree.registry.activeAt(vendor.uuid, 'library');
+  assert.equal(library.type, 'repo.git');
+  const baseline = service.registration.repoState(library.uuid);
+  assert.ok(baseline?.stateId,
+    'nested repo registration captured its own Card + Checkpoint');
+  const src = tree.registry.activeAt(library.uuid, 'src');
+  assert.equal(tree.registry.activeAt(src.uuid, 'entry.js').type, 'file.text');
+  const identity = new Database(path.join(service.dir, 'identity.db'), { readonly: true });
+  const nestedRow = identity.prepare('SELECT payload_version FROM entities WHERE uuid = ?').get(library.uuid);
+  identity.close();
+  assert.equal(nestedRow.payload_version, baseline.stateId,
+    'the nested repo entity points at the baseline it just saved');
+  assert.equal(
+    service.observer.status().some((row) => row.path === nested && row.watching && !row.degraded),
+    true,
+    'the nested repo has a live semantic watcher of its own',
+  );
+
+  await arrives(
+    () => fs.writeFileSync(path.join(nested, 'src', 'live.js'), 'export const live = true;\n'),
+    () => Boolean(tree.registry.activeAt(src.uuid, 'live.js'))
+      && service.registration.repoState(library.uuid).stateId !== baseline.stateId,
+    'a nested repo change to record the new child under its own repo boundary',
+  );
+  assert.equal(tree.registry.activeAt(src.uuid, 'live.js').type, 'file.text');
+});
+
+test('a reopened repo watcher resumes from the saved Card + Checkpoint baseline', async () => {
+  const service = makeService('repo-reopen');
+  const repo = makeGround('repo-reopen');
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  fs.writeFileSync(path.join(repo, 'readme.md'), '# stable\n');
+
+  const { record: first } = await service.register(repo);
+  const before = service.registration.repoState(first.uuid);
+  service.close();
+
+  const reopened = createRegistrationService({ dir: service.dir });
+  services.push(reopened);
+  const { record: again } = await reopened.register(repo);
+  assert.equal(again.uuid, first.uuid, 'the repo identity is durable');
+  assert.equal(reopened.registration.repoState(again.uuid).stateId, before.stateId,
+    'Watch resumed from the registered Card + Checkpoint, not a new birth capture');
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  assert.equal(reopened.registration.tree(repo).root().version, again.version,
+    'an unchanged repo remains silent after reopen');
+});
+
+test('register registers every entity before it starts Watch', async () => {
+  const service = makeService('ordered');
+  const ground = makeGround('ordered');
+  fs.mkdirSync(path.join(ground, 'nested'));
+  fs.writeFileSync(path.join(ground, 'nested', 'entry.txt'), 'alpha');
+
+  const start = service.observer.start.bind(service.observer);
+  let checked = false;
+  service.observer.start = (rootId) => {
+    // Register is durable identity, not the later-created Record lens.
+    // The observer's first census now happens before evidence reconciliation
+    // so a pre-registered nested repo is never mistaken for absent ground.
+    const identity = new Database(path.join(service.dir, 'identity.db'), { readonly: true });
+    const root = identity.prepare(
+      "SELECT uuid FROM entities WHERE parent_uuid IS NULL AND status = 'active'",
+    ).get();
+    const nested = identity.prepare(
+      "SELECT uuid FROM entities WHERE parent_uuid = ? AND name = 'nested' AND status = 'active'",
+    ).get(root.uuid);
+    const file = identity.prepare(
+      "SELECT uuid FROM entities WHERE parent_uuid = ? AND name = 'entry.txt' AND status = 'active'",
+    ).get(nested.uuid);
+    identity.close();
+    assert.ok(nested, 'the folder already has a durable identity');
+    assert.ok(file, 'so does the file within it');
+    assert.equal(service.observer.status()[0].watching, false,
+      'the observer has not begun watching while registration is in progress');
+    checked = true;
+    return start(rootId);
+  };
+
+  const { rootPath } = await service.register(ground);
+  assert.equal(rootPath, ground);
+  assert.equal(checked, true, 'Watch begins only after the structural walk commits');
+});
+
+test('register never reserves or mutates a user filename for watching', async () => {
+  const service = makeService('ordinary-name');
+  const ground = makeGround('ordinary-name');
+  const name = '.amalgm-doorbell';
+  const file = path.join(ground, name);
+  fs.writeFileSync(file, 'this is user ground');
+
+  const { record } = await service.register(ground);
+  const tree = service.registration.tree(ground);
+  assert.equal(fs.readFileSync(file, 'utf8'), 'this is user ground');
+  assert.ok(tree.registry.activeAt(record.uuid, name),
+    'it remains an ordinary enrolled file, not Amalgm control state');
+});
+
+// --- the rail, through its own front door ----------------------------------
+
+test('a real doorbell reaches the registry with nobody poking the machinery', async () => {
+  const service = makeService('doorbell');
+  const ground = makeGround('doorbell');
   fs.writeFileSync(path.join(ground, 'a.txt'), 'alpha');
-  const { record } = service.add(ground);
+  const { record } = await service.register(ground);
+  const tree = service.registration.tree(ground);
+
+  // Ground that appears after registration. From here on NOTHING in this
+  // test touches the observer or the boundary: the watcher notices, the
+  // scan concludes, the boundary records. Cut the emit wire in
+  // service.js, or never start the observer, and this never converges.
+  await arrives(
+    () => fs.writeFileSync(path.join(ground, 'later.md'), 'arrived after'),
+    () => tree.registry.children(record.uuid).some((row) => row.name === 'later.md'),
+    'the new file to reach the registry on its own',
+  );
+
+  const arrived = tree.registry.children(record.uuid).find((row) => row.name === 'later.md');
+  assert.equal(arrived.type, 'file.text', 'typed by the read that detected it');
+});
+
+test('a later change reaches the registry as a new version on the same UUID', async () => {
+  const service = makeService('change');
+  const ground = makeGround('change');
+  const file = path.join(ground, 'a.txt');
+  fs.writeFileSync(file, 'alpha');
+  const { record } = await service.register(ground);
   const tree = service.registration.tree(ground);
+  const before = tree.registry.children(record.uuid).find((row) => row.name === 'a.txt');
 
-  // Ground that appeared after registration. The scan publishes, the
-  // boundary records — cut the emit wire in service.js and this fails.
-  fs.writeFileSync(path.join(ground, 'later.txt'), 'arrived after');
-  service.observer.scanNow(service.observer.listRoots()[0].rootId);
-  service.registration.flushIfDirty();
+  await arrives(
+    () => fs.writeFileSync(file, 'beta — different bytes entirely'),
+    () => tree.registry.children(record.uuid)
+      .find((row) => row.name === 'a.txt').version !== before.version,
+    'the edit to reach the registry on its own',
+  );
 
-  const names = tree.registry.children(record.uuid).map((row) => row.name).sort();
-  assert.deepEqual(names, ['a.txt', 'later.txt']);
+  const after = tree.registry.children(record.uuid).find((row) => row.name === 'a.txt');
+  assert.equal(after.uuid, before.uuid, 'the same thing, changed — never a new identity');
 });
 
-test('identity survives a restart over the same directory', () => {
+test('bytes replacing text re-type the same UUID, through the same one doorbell', async () => {
+  const service = makeService('retype');
+  const ground = makeGround('retype');
+  const file = path.join(ground, 'a.txt');
+  fs.writeFileSync(file, 'plain words');
+  const { record } = await service.register(ground);
+  const tree = service.registration.tree(ground);
+  const born = tree.registry.children(record.uuid).find((row) => row.name === 'a.txt');
+  assert.equal(born.type, 'file.text');
+
+  await arrives(
+    () => fs.writeFileSync(file, Buffer.from([0x89, 0x50, 0x00, 0x4e, 0x47])),
+    () => tree.registry.children(record.uuid)
+      .find((row) => row.name === 'a.txt').type === 'file.binary',
+    'the new bytes to re-type the record on their own',
+  );
+  const after = tree.registry.children(record.uuid).find((row) => row.name === 'a.txt');
+  assert.equal(after.uuid, born.uuid, 'the same thing, now bytes — never a new identity');
+});
+
+// --- lifetime ---------------------------------------------------------------
+
+test('close() is silent: no queued pass runs after the databases shut', async () => {
+  // A shutdown signal can land between a doorbell and the pass it
+  // scheduled. Every stage that owns a pending pass — the boundary AND
+  // each of its lenses — must be stopped before the handles close, or a
+  // shutdown that went exactly right complains about itself.
+  const service = createRegistrationService({ dir: path.join(tempRoot, 'state-quiet') });
+  const ground = makeGround('quiet');
+  fs.writeFileSync(path.join(ground, 'a.txt'), 'alpha');
+  await service.register(ground);
+
+  const warnings = [];
+  const realWarn = console.warn;
+  console.warn = (...args) => warnings.push(args.join(' '));
+  try {
+    const [root] = service.observer.listRoots();
+    service.registration.onEvent({ type: 'file.changed', rootId: root.rootId, path: ground });
+    service.close();
+    // Drain the immediates the doorbell scheduled, and then some.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  } finally {
+    console.warn = realWarn;
+  }
+  assert.deepEqual(warnings, [], 'a clean shutdown says nothing');
+});
+
+test('close() gives back everything the root took, and twice is not an error', async () => {
+  const service = createRegistrationService({ dir: path.join(tempRoot, 'state-close') });
+  const ground = makeGround('close');
+  fs.writeFileSync(path.join(ground, 'a.txt'), 'alpha');
+  await service.register(ground);
+
+  service.close();
+  service.close(); // shutdown is reached from more than one direction
+
+  // A closed handle refuses to answer — the honest proof that the
+  // databases are shut, not merely unwatched.
+  assert.throws(() => service.observer.listRoots(), /database connection is not open/i);
+});
+
+test('identity survives a real close-and-reopen over the same directory', async () => {
   const dir = path.join(tempRoot, 'state-restart');
   const ground = makeGround('restart');
   fs.writeFileSync(path.join(ground, 'a.txt'), 'alpha');
 
   const first = createRegistrationService({ dir });
-  const before = first.add(ground).record.uuid;
-  first.stop();
+  const before = (await first.register(ground)).record.uuid;
+  first.close(); // every handle released: the next stack is genuinely alone
 
   const second = createRegistrationService({ dir });
   services.push(second);
@@ -162,95 +668,117 @@ test('identity survives a restart over the same directory', () => {
 
 // --- the policies are the real ones ---------------------------------------
 
-test("amalgm's enrollment policy is in force, and refuses loudly", () => {
+test("amalgm's enrollment policy is in force, and refuses loudly", async () => {
   const service = makeService('policy');
   const excluded = path.join(makeGround('policy'), 'node_modules');
   fs.mkdirSync(excluded);
-  assert.throws(() => service.add(excluded), /enrollment policy excludes it/);
+  await assert.rejects(
+    () => service.register(excluded),
+    (error) => isRefusal(error) && /enrollment policy excludes it/.test(error.message),
+    'a refusal, named as one',
+  );
+});
+
+test('ground that is not there is a refusal, not a fault', async () => {
+  const service = makeService('missing');
+  await assert.rejects(
+    () => service.register(path.join(tempRoot, 'no-such-ground')),
+    (error) => isRefusal(error) && /no ground at that address/.test(error.message),
+  );
 });
 
-test('adding ground already inside a registered tree returns that tree', () => {
+test('a refusal is what the boundary RAISED, never what an error says', () => {
+  // The whole point of naming refusals: an unlucky message must not
+  // promote a fault into "your path is bad".
+  assert.equal(isRefusal(new Error('refusing to add /x: enrollment policy excludes it')), false);
+  assert.equal(isRefusal(null), false);
+});
+
+test('adding ground already inside a registered tree returns that tree', async () => {
   const service = makeService('covered');
   const ground = makeGround('covered');
   fs.mkdirSync(path.join(ground, 'inner'));
   fs.writeFileSync(path.join(ground, 'inner', 'a.txt'), 'alpha');
 
-  const tree = service.add(ground);
-  const inner = service.add(path.join(ground, 'inner'));
+  const tree = await service.register(ground);
+  const inner = await service.register(path.join(ground, 'inner'));
   assert.equal(inner.rootPath, ground, 'one owner per path — no second tree is born');
   assert.equal(inner.record.uuid, tree.record.uuid);
 });
 
-// --- the endpoint ----------------------------------------------------------
+// --- the endpoint, over real authenticated HTTP ----------------------------
 
-function fakeCtx(pathname, method, body) {
-  const sent = {};
-  return {
-    ctx: {
-      pathname,
-      method,
-      readJsonBody: async () => body,
-      sendJson: (status, payload) => Object.assign(sent, { status, payload }),
-    },
-    sent,
-  };
-}
+test('an unauthorized request never reaches the boundary', async () => {
+  const ground = makeGround('unauthorized');
+  const answer = await post('/entities/register', { path: ground }, { token: null });
+  assert.equal(answer.status, 401);
+});
 
-test('POST /entities/add registers and answers with the tree', async () => {
+test('POST /entities/register registers and answers with the tree', async () => {
   const ground = makeGround('route');
   fs.writeFileSync(path.join(ground, 'a.txt'), 'alpha');
 
-  const { ctx, sent } = fakeCtx('/entities/add', 'POST', { path: ground });
-  assert.equal(await handleEntityRoutes(ctx), true);
-  assert.equal(sent.status, 200);
-  assert.equal(sent.payload.rootPath, ground);
-  assert.ok(sent.payload.record.uuid);
+  const answer = await post('/entities/register', { path: ground });
+  assert.equal(answer.status, 200);
+  assert.equal(answer.payload.rootPath, ground);
+  assert.ok(answer.payload.record.uuid);
+});
+
+test('POST /entities/register accepts paths for one batch of selected ground', async () => {
+  const first = makeGround('route-many-first');
+  const second = path.join(makeGround('route-many-second-parent'), 'second.txt');
+  fs.writeFileSync(second, 'second');
+
+  const answer = await post('/entities/register', { paths: [first, second] });
+  assert.equal(answer.status, 200);
+  assert.deepEqual(answer.payload.results.map((entry) => entry.rootPath), [first, second]);
+  assert.deepEqual(answer.payload.results.map((entry) => entry.record.parentUUID), [null, null]);
 });
 
 test('the endpoint reports a refusal as a refusal, with the reason', async () => {
   const excluded = path.join(makeGround('route-refused'), '.ssh');
   fs.mkdirSync(excluded);
 
-  const { ctx, sent } = fakeCtx('/entities/add', 'POST', { path: excluded });
-  assert.equal(await handleEntityRoutes(ctx), true);
-  assert.equal(sent.status, 400, 'the request named ground the boundary refuses');
-  assert.match(sent.payload.error, /enrollment policy excludes it/);
+  const answer = await post('/entities/register', { path: excluded });
+  assert.equal(answer.status, 400, 'the request named ground the boundary refuses');
+  assert.match(answer.payload.error, /enrollment policy excludes it/);
 });
 
 test('a missing path is answered, not registered', async () => {
-  const { ctx, sent } = fakeCtx('/entities/add', 'POST', {});
-  assert.equal(await handleEntityRoutes(ctx), true);
-  assert.equal(sent.status, 400);
-  assert.match(sent.payload.error, /path is required/);
+  const answer = await post('/entities/register', {});
+  assert.equal(answer.status, 400);
+  assert.match(answer.payload.error, /path.*required/);
 });
 
 test('ground that is not there is a refusal, never a crash', async () => {
-  const { ctx, sent } = fakeCtx('/entities/add', 'POST', { path: path.join(tempRoot, 'no-such-ground') });
-  assert.equal(await handleEntityRoutes(ctx), true);
-  assert.equal(sent.status, 400);
-  assert.ok(sent.payload.error);
+  const answer = await post('/entities/register', { path: path.join(tempRoot, 'no-such-ground') });
+  assert.equal(answer.status, 400);
+  assert.match(answer.payload.error, /no ground at that address/);
+});
+
+test('the route group claims only its own request', async () => {
+  assert.equal((await post('/entities', {})).status, 404);
 });
 
-test('the route is MOUNTED: the runtime dispatcher reaches it', async () => {
-  // A handler nothing routes to is a handler that does not exist. This
-  // is the local dispatcher production actually serves, unmodified.
-  const ground = makeGround('mounted');
+// --- the fault, last: it convicts the installation's singleton -------------
+
+test('a torn identity store is a FAULT, never the caller\'s bad path', async () => {
+  // The sharpest case the split exists for. The tree is registered and
+  // its identity is intact; the EVIDENCE that witnesses it is destroyed
+  // underneath the runtime. The loss law convicts — loudly, by design —
+  // and that conviction must never reach the user as "your path is bad".
+  //
+  // (The server's fault handler logs the error; the noise below is that
+  // handler doing its job.)
+  const ground = makeGround('torn');
   fs.writeFileSync(path.join(ground, 'a.txt'), 'alpha');
+  assert.equal((await post('/entities/register', { path: ground })).status, 200);
 
-  const { ctx, sent } = fakeCtx('/entities/add', 'POST', { path: ground });
-  assert.equal(await createLocalServiceRouter().handle(ctx), true);
-  assert.equal(sent.status, 200);
-  assert.equal(sent.payload.rootPath, ground);
-});
+  const evidence = new Database(path.join(ENTITIES_DIR, 'observer.db'));
+  evidence.prepare('DELETE FROM observer_roots').run();
+  evidence.close();
 
-test('the route group claims only its own request', async () => {
-  const others = [
-    fakeCtx('/entities/add', 'GET', {}),
-    fakeCtx('/workspace/projects', 'POST', {}),
-    fakeCtx('/entities', 'POST', {}),
-  ];
-  for (const { ctx, sent } of others) {
-    assert.equal(await handleEntityRoutes(ctx), false);
-    assert.equal(sent.status, undefined, 'an unclaimed request is never answered');
-  }
+  const answer = await post('/entities/register', { path: makeGround('torn-next') });
+  assert.equal(answer.status, 500, 'an installation fault, reported as one');
+  assert.doesNotMatch(String(answer.payload?.error), /refusing to add/);
 });