amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/state/promotions.js

@@ -233,26 +233,6 @@ function acknowledgePromotion(promotionIdInput, acknowledgement, options = {}) {
     // the shared channel — their base is the promoted snapshot — so the
     // normal outbox claim delivers them. Their journal identity, order, and
     // already-projected local events are untouched.
-    const pendingRehomes = cachedStatement(database, `
-      SELECT channel_id, mutation_id
-      FROM mutation_journal
-      WHERE local_resource = ?
-        AND shared_resource_id IS NULL
-        AND mutation_origin = 'local'
-        AND journal_id > ?
-      ORDER BY journal_id ASC
-    `).all(promotion.localResource, promotion.journalCursor);
-    const sharedChannelId = `resource:${replica.resourceId}`;
-    for (const mutation of pendingRehomes) {
-      // The permanent mutation ID joins semantic and physical durability.
-      // Rekey both halves in this transaction; otherwise restart can see the
-      // shared journal row and strand its still-local native file receipt.
-      require('./doc-disk').rehomeMutation(database, {
-        mutationId: mutation.mutation_id,
-        oldChannelId: mutation.channel_id,
-        newChannelId: sharedChannelId,
-      });
-    }
     const rehomed = cachedStatement(database, `
       UPDATE mutation_journal
       SET channel_id = ?,
@@ -266,7 +246,7 @@ function acknowledgePromotion(promotionIdInput, acknowledgement, options = {}) {
         AND mutation_origin = 'local'
         AND journal_id > ?
     `).run(
-      sharedChannelId,
+      `resource:${replica.resourceId}`,
       replica.resourceId,
       require('../workspace/identity').machineId(),
       replica.authorityEpoch,

package/runtime/scripts/amalgm-mcp/state/replicas.js

@@ -35,41 +35,6 @@ function integer(value, name, minimum) {
   return number;
 }
 
-/**
- * A snapshot is an official prefix, never an independently numbered value.
- * Validate the complete authority envelope before any caller touches disk,
- * memory, or SQLite so every snapshot contract shares one ordering boundary.
- */
-function validateSnapshotEnvelope(input, expected = {}) {
-  const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
-  if (!isCloudResourceId(resourceId)) {
-    throw invalid('resourceId must be a node UUID or legacy cloud id');
-  }
-  const contract = requiredText(input?.contract, 'contract', 128);
-  if (!CONTRACT.test(contract)) throw invalid('contract has an invalid format');
-  const schemaVersion = integer(input?.schemaVersion, 'schemaVersion', 1);
-  const authorityEpoch = integer(input?.authorityEpoch, 'authorityEpoch', 1);
-  const snapshotVersion = integer(input?.snapshotVersion, 'snapshotVersion', 0);
-  const headVersion = integer(input?.headVersion, 'headVersion', 0);
-  if (expected.contract && contract !== expected.contract) {
-    throw invalid(`snapshot contract must be ${expected.contract}`, 409);
-  }
-  if (expected.schemaVersion && schemaVersion !== expected.schemaVersion) {
-    throw invalid(`snapshot schemaVersion must be ${expected.schemaVersion}`, 409);
-  }
-  if (snapshotVersion > headVersion) {
-    throw invalid('snapshotVersion cannot exceed headVersion', 409);
-  }
-  return {
-    resourceId,
-    contract,
-    schemaVersion,
-    authorityEpoch,
-    snapshotVersion,
-    headVersion,
-  };
-}
-
 function normalizeReplica(row) {
   if (!row) return null;
   return {
@@ -254,17 +219,11 @@ function markReplicaRevoked(input, options = {}) {
 }
 
 /**
- * Decide what an already-bound replica may do with a snapshot before the
- * caller touches its materialization.
- *
- * Rail version and authority epoch are independent coordinates. Most
- * contracts have one canonical value at a rail version, while an
- * authority-projected contract (the workspace tree) may legitimately have
- * different visible bytes at the same rail version after an access change.
- * Older authority is never allowed to install, even when it carries a larger
- * rail number.
+ * A freshly attached official snapshot subsumes every version at or before
+ * it, so the replica's cursors jump forward to the snapshot — never backward:
+ * a replica that already applied past the snapshot keeps its position.
  */
-function inspectReplicaSnapshot(input, options = {}) {
+function advanceReplicaSnapshot(input, options = {}) {
   const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
   const snapshotVersion = integer(input?.snapshotVersion, 'snapshotVersion', 0);
   const snapshotChecksum = requiredText(input?.snapshotChecksum, 'snapshotChecksum', 64);
@@ -273,101 +232,23 @@ function inspectReplicaSnapshot(input, options = {}) {
   }
   const authorityEpoch = integer(input?.authorityEpoch, 'authorityEpoch', 1);
   const database = options.database || openLocalDb();
-  const current = getReplicaByResourceId(resourceId, { database });
-  if (!current) throw invalid(`unknown shared replica ${resourceId}`, 404);
-  const projectedAuthorityEpoch = options.projectedAuthorityEpoch == null
-    ? current.authorityEpoch
-    : integer(options.projectedAuthorityEpoch, 'projectedAuthorityEpoch', 1);
-  if (
-    authorityEpoch < current.authorityEpoch
-    || authorityEpoch < projectedAuthorityEpoch
-  ) {
-    throw invalid(
-      `shared resource ${resourceId} snapshot has stale authority epoch ${authorityEpoch}`,
-      409,
-    );
-  }
-  // `authorityEpoch` on the replica is the newest authority advertised by
-  // the tunnel. `projectedAuthorityEpoch` is the authority whose bytes and
-  // permissions are physically installed. A reconnect may advance the first
-  // coordinate before the same-version projection arrives, so projection
-  // eligibility must compare with the second.
-  const authorityChanged = authorityEpoch > projectedAuthorityEpoch;
-  const authorityProjection = options.allowAuthorityProjection === true && authorityChanged;
-  if (
-    current.snapshotVersion === snapshotVersion
-    && current.snapshotChecksum !== null
-    && current.snapshotChecksum !== snapshotChecksum
-    && !authorityProjection
-  ) {
-    throw invalid(
-      `shared resource ${resourceId} has unequal state at version ${snapshotVersion}`,
-      409,
-    );
-  }
-  if (snapshotVersion < current.appliedVersion) {
-    return { action: 'stale', authorityChanged, replica: current };
-  }
-  if (authorityProjection) {
-    return { action: 'install', authorityChanged, replica: current };
-  }
-  if (snapshotVersion === current.appliedVersion) {
-    if (
-      current.snapshotVersion === snapshotVersion
-      && current.snapshotChecksum === null
-    ) {
-      return { action: 'metadata', authorityChanged, replica: current };
-    }
-    if (
-      current.snapshotVersion === snapshotVersion
-      && current.snapshotChecksum === snapshotChecksum
-    ) {
-      return { action: authorityChanged ? 'metadata' : 'duplicate', authorityChanged, replica: current };
-    }
-    if (current.snapshotVersion < snapshotVersion) {
-      return { action: 'metadata', authorityChanged, replica: current };
-    }
-    throw invalid(
-      `shared resource ${resourceId} has unequal state at version ${snapshotVersion}`,
-      409,
-    );
-  }
-  return { action: 'install', authorityChanged, replica: current };
-}
-
-/**
- * A freshly attached official snapshot subsumes every version at or before
- * it, so the replica's cursors jump forward to the snapshot — never backward:
- * a replica that already applied past the snapshot keeps its position.
- */
-function advanceReplicaSnapshot(input, options = {}) {
-  const database = options.database || openLocalDb();
-  const disposition = inspectReplicaSnapshot(input, options);
-  const {
-    resourceId,
-    snapshotVersion,
-    snapshotChecksum,
-    authorityEpoch,
-  } = {
-    resourceId: disposition.replica.resourceId,
-    snapshotVersion: integer(input?.snapshotVersion, 'snapshotVersion', 0),
-    snapshotChecksum: requiredText(input?.snapshotChecksum, 'snapshotChecksum', 64),
-    authorityEpoch: integer(input?.authorityEpoch, 'authorityEpoch', 1),
-  };
-  if (disposition.action === 'stale' || disposition.action === 'duplicate') {
-    return disposition.replica;
-  }
+  const row = cachedStatement(
+    database,
+    'SELECT * FROM shared_resource_replicas WHERE resource_id = ?',
+  ).get(resourceId);
+  if (!row) throw invalid(`unknown shared replica ${resourceId}`, 404);
   cachedStatement(database, `
     UPDATE shared_resource_replicas
-    SET applied_version = ?,
-        snapshot_version = ?,
-        snapshot_checksum = ?,
+    SET applied_version = MAX(applied_version, ?),
+        snapshot_version = MAX(snapshot_version, ?),
+        snapshot_checksum = CASE WHEN snapshot_version <= ? THEN ? ELSE snapshot_checksum END,
         authority_epoch = MAX(authority_epoch, ?),
         sync_status = 'synced',
         last_error = NULL,
         updated_at = ?
     WHERE resource_id = ?
   `).run(
+    snapshotVersion,
     snapshotVersion,
     snapshotVersion,
     snapshotChecksum,
@@ -387,6 +268,4 @@ module.exports = {
   markReplicaRevoked,
   refreshReplicaAuthority,
   registerReplica,
-  inspectReplicaSnapshot,
-  validateSnapshotEnvelope,
 };

package/runtime/scripts/amalgm-mcp/state/shared-rest.js

@@ -118,35 +118,9 @@ async function handleWorkspaceContentDiscover(body, sendJson) {
 
 async function handlePromotionStart(body, sendJson) {
   try {
-    const codeProject = body?.contract === 'code-project-stream@2';
     const requestedResourceId = typeof body?.resourceId === 'string' && body.resourceId.trim()
       ? body.resourceId.trim()
       : null;
-    if (codeProject) {
-      if (!requestedResourceId) {
-        const error = new Error('code project promotion requires a resourceId');
-        error.statusCode = 409;
-        throw error;
-      }
-      const projectStream = require('../workspace/project-stream');
-      const localPath = require('path').resolve(body?.path || '');
-      const snapshot = projectStream.readSnapshot(localPath, requestedResourceId);
-      const bytes = Buffer.from(`${JSON.stringify(snapshot)}\n`, 'utf8');
-      const result = require('./promotions').enqueuePromotion({
-        promotionId: body?.promotionId || `prm_${crypto.randomBytes(16).toString('base64url')}`,
-        resourceId: requestedResourceId,
-        localResource: `${projectStream.LOCAL_RESOURCE_PREFIX}${requestedResourceId}`,
-        localPath,
-        contract: projectStream.STREAM_CONTRACT,
-        schemaVersion: 2,
-        snapshotBase64: bytes.toString('base64'),
-        contentBytes: bytes.length,
-        name: body?.name,
-        mediaType: 'application/vnd.amalgm.code-project+json',
-      });
-      sendJson(result.duplicate ? 200 : 202, result);
-      return;
-    }
     const requestedNodeId = requestedResourceId
       && require('../workspace/tree/identity').isUuid(requestedResourceId)
       ? requestedResourceId.toLowerCase()
@@ -240,23 +214,13 @@ async function handlePromotionFail(body, sendJson) {
 async function handleAttachmentStart(body, sendJson) {
   try {
     const tree = body?.contract === 'workspace-tree@1';
-    const codeProject = body?.contract === 'code-project-stream@2';
-    const localPath = tree || codeProject
-      ? require('path').resolve(body?.path || '')
-      : require('./docs').openDoc(body?.path).path;
+    const localPath = tree ? require('path').resolve(body?.path || '') : require('./docs').openDoc(body?.path).path;
     if (tree) {
       const stats = fs.statSync(localPath);
       if (!stats.isDirectory() || fs.readdirSync(localPath).length > 0) {
         sendJson(409, { error: 'cloud workspace attachment requires an empty folder' });
         return;
       }
-    } else if (codeProject) {
-      const stream = require('../workspace/project-stream');
-      const snapshot = stream.readSnapshot(localPath, body?.resourceId);
-      if (snapshot.version !== 0 || snapshot.card !== null || snapshot.checkpoint !== null) {
-        sendJson(409, { error: 'code project attachment requires an empty local projection' });
-        return;
-      }
     } else if (require('./docs').getDocText(localPath).length > 0) {
       sendJson(409, { error: 'cloud attachment requires an empty local text file' });
       return;
@@ -353,12 +317,7 @@ async function handleMutationFail(body, sendJson) {
     sendJson(200, require('./mutations').failCloudMutation(
       body?.resourceId,
       body?.mutationId,
-      {
-        code: body?.code,
-        message: body?.message,
-        retryable: body?.retryable,
-        retryAt: body?.retryAt,
-      },
+      { message: body?.message, retryable: body?.retryable, retryAt: body?.retryAt },
     ));
   } catch (error) {
     sendHandlerError(error, sendJson);
@@ -372,9 +331,7 @@ async function handleMutationIngest(body, sendJson) {
       ? require('../browser/cookie-jar').applyCloudCookieMutation(body)
       : contract === 'workspace-tree@1'
         ? require('../workspace/tree-store').applyCloudTreeMutation(body)
-        : contract === 'code-project-stream@2'
-          ? require('../workspace/project-stream').applyCloudMutation(body)
-          : require('./docs').applyCloudDocMutation(body);
+        : require('./docs').applyCloudDocMutation(body);
     sendJson(200, result);
   } catch (error) {
     sendHandlerError(error, sendJson);

package/runtime/scripts/amalgm-mcp/tests/adapters.test.js

@@ -0,0 +1,379 @@
+'use strict';
+
+/**
+ * The adapter contract exams (adapters/): the ratified three-adapter
+ * map over the registry's physical alphabet, the socket law proven the
+ * only way that counts — ONE GENERIC CALLER reading, applying, and
+ * verifying real ground of every kind through identical calls, zero
+ * type branching — and the contract's convictions: each stated law
+ * shown to refuse its violation, not just to accept lawful shape.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { ENTITY_TYPES } = require('../registry');
+const { ADAPTERS, RAILS, SOCKETS, adapterFor, assertAdapter, buildTypeMap } = require('../adapters');
+const filesystem = require('../adapters/filesystem');
+const git = require('../adapters/git');
+const reference = require('../adapters/reference');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-adapters-'));
+
+test.after(() => {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+function ground(name) {
+  const dir = path.join(tempRoot, name);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function makeRepo(name) {
+  const dir = fs.realpathSync(ground(name));
+  const run = (...args) => execFileSync('git', args, { cwd: dir, stdio: 'pipe' });
+  run('init', '--quiet');
+  run('config', 'user.email', 'adapters@amalgm.test');
+  run('config', 'user.name', 'Adapters');
+  run('config', 'commit.gpgsign', 'false');
+  fs.writeFileSync(path.join(dir, 'seed.txt'), 'seed\n');
+  run('add', '-A');
+  run('commit', '--quiet', '-m', 'seed');
+  return dir;
+}
+
+/** A minimal lawful descriptor; each conviction exam breaks exactly one law. */
+function lawfulAdapter(overrides = {}) {
+  return Object.freeze({
+    name: 'exam',
+    types: Object.freeze({ 'file.text': 'its bytes' }),
+    rails: Object.freeze({ detect: Object.freeze({ truth: () => null }) }),
+    ...overrides,
+  });
+}
+
+// ---- The physical alphabet and the ratified map ----------------------
+
+test('the physical alphabet is exactly the ratified seven', () => {
+  assert.deepEqual([...ENTITY_TYPES],
+    ['file.binary', 'file.text', 'folder', 'link', 'reference', 'repo.git', 'workspace']);
+  assert.ok(Object.isFrozen(ENTITY_TYPES));
+});
+
+test('constructs are not physical types: meaning is layered above, never encoded as a kind', () => {
+  for (const construct of ['automation', 'agent', 'app', 'tool', 'skill']) {
+    assert.ok(!ENTITY_TYPES.includes(construct), `${construct} is not in the physical alphabet`);
+    assert.throws(() => adapterFor(construct), /no adapter serves entity type/);
+  }
+});
+
+test('the seven rails are declared once, frozen, in journey order', () => {
+  assert.deepEqual([...RAILS], ['watch', 'detect', 'record', 'send', 'receive', 'apply', 'verify']);
+  assert.ok(Object.isFrozen(RAILS));
+});
+
+test('every type in the registry alphabet is assigned exactly one adapter', () => {
+  for (const type of ENTITY_TYPES) {
+    const claimants = ADAPTERS.filter((adapter) => type in adapter.types);
+    assert.equal(claimants.length, 1, `${type} must have exactly one adapter`);
+    assert.equal(adapterFor(type), claimants[0]);
+  }
+});
+
+test('the adapter set is exactly the ratified three', () => {
+  assert.deepEqual(ADAPTERS.map((adapter) => adapter.name).sort(), ['filesystem', 'git', 'reference']);
+});
+
+test('same-ground transition kinds share ONE adapter, so a transition never changes hands', () => {
+  // file ↔ link on one slot, text ↔ binary, workspace shedding to
+  // folder on adoption: all inside the filesystem adapter by design.
+  for (const type of ['workspace', 'folder', 'file.text', 'file.binary', 'link']) {
+    assert.equal(adapterFor(type), filesystem, `${type} rides the filesystem adapter`);
+  }
+});
+
+test('a transition may cross adapters as a handoff: folder and repo.git are served apart', () => {
+  // becomeRepo/becomeFiles moves a container between these two on the
+  // SAME UUID — identity is the registry's, never the adapter's.
+  assert.equal(adapterFor('repo.git'), git);
+  assert.notEqual(adapterFor('folder'), adapterFor('repo.git'));
+});
+
+test('an unknown type convicts and names the alphabet', () => {
+  assert.throws(() => adapterFor('hologram'), /no adapter serves entity type "hologram"/);
+  assert.throws(() => adapterFor('hologram'), new RegExp(ENTITY_TYPES.join(', ')));
+});
+
+test('every adapter descriptor satisfies the contract it shipped under', () => {
+  for (const adapter of ADAPTERS) assert.equal(assertAdapter(adapter), adapter);
+});
+
+test('the reference adapter is assigned, not yet operational — absence is honest, a stub is not', () => {
+  assert.deepEqual(Object.keys(reference.rails), []);
+  assert.ok(Object.isFrozen(reference.rails));
+});
+
+test('every declared truth is one non-empty sentence', () => {
+  for (const adapter of ADAPTERS) {
+    for (const [type, truth] of Object.entries(adapter.types)) {
+      assert.ok(typeof truth === 'string' && truth.length > 0, `${adapter.name}/${type} declares truth`);
+    }
+  }
+});
+
+// ---- The socket law, proven by a generic caller ----------------------
+
+test('PROOF: one generic caller reads truth for every kind through one socket — zero type branching', () => {
+  const folderPath = ground('proof-folder');
+  fs.writeFileSync(path.join(folderPath, 'member.txt'), 'hello');
+  const filePath = path.join(ground('proof-file'), 'notes.md');
+  fs.writeFileSync(filePath, 'first line\n');
+  const linkPath = path.join(ground('proof-link'), 'pointer');
+  fs.symlinkSync('../somewhere', linkPath);
+  const repoPath = makeRepo('proof-repo');
+
+  // The fixtures know their ground; the CALLER below is one loop with
+  // one call shape — it never asks "which kind is this?".
+  const fixtures = [
+    { type: 'folder', path: folderPath, change: () => fs.writeFileSync(path.join(folderPath, 'newcomer.txt'), 'x') },
+    { type: 'file.text', path: filePath, change: () => fs.appendFileSync(filePath, 'second line\n') },
+    { type: 'link', path: linkPath, change: () => { fs.unlinkSync(linkPath); fs.symlinkSync('../elsewhere', linkPath); } },
+    { type: 'repo.git', path: repoPath, change: () => fs.writeFileSync(path.join(repoPath, 'untracked.txt'), 'new work') },
+  ];
+
+  for (const fixture of fixtures) {
+    const read = adapterFor(fixture.type).rails.detect.truth(fixture.path);
+    assert.equal(read.truth, 'present', `${fixture.type} truth is present`);
+    assert.ok(typeof read.version === 'string' && read.version.length > 0, `${fixture.type} truth carries a version`);
+
+    const again = adapterFor(fixture.type).rails.detect.truth(fixture.path);
+    assert.equal(again.version, read.version, `${fixture.type}: equal truth is silence`);
+
+    fixture.change();
+    const changed = adapterFor(fixture.type).rails.detect.truth(fixture.path);
+    assert.equal(changed.truth, 'present');
+    assert.notEqual(changed.version, read.version, `${fixture.type}: changed truth changes the version`);
+
+    fs.rmSync(fixture.path, { recursive: true, force: true });
+    const gone = adapterFor(fixture.type).rails.detect.truth(fixture.path);
+    assert.equal(gone.truth, 'absent', `${fixture.type}: vanished ground is honest absence, never an error`);
+    assert.ok(!('version' in gone), `${fixture.type}: absence claims no version`);
+  }
+});
+
+test('a repo mid-operation is honestly unsettled — truth unreadable is a state, never an error', () => {
+  const repoPath = makeRepo('busy-repo');
+  fs.writeFileSync(path.join(repoPath, '.git', 'MERGE_HEAD'), '0'.repeat(40));
+  const read = adapterFor('repo.git').rails.detect.truth(repoPath);
+  assert.equal(read.truth, 'unsettled');
+  assert.equal(read.reason, 'MERGE_HEAD');
+  assert.ok(!('version' in read), 'unsettled truth claims no version');
+});
+
+test('ground without a repository is an absent repo.git, whatever else stands there', () => {
+  const plain = ground('no-repo');
+  fs.writeFileSync(path.join(plain, 'just-a-file.txt'), 'not a repo');
+  assert.equal(adapterFor('repo.git').rails.detect.truth(plain).truth, 'absent');
+});
+
+test('a repository that cannot be inspected is unsettled — unreadable is never absent', () => {
+  // Absence withdraws territory; unsettledness preserves the last known
+  // truth and reads again. Mistaking one for the other is the lie the
+  // axiom forbids.
+  const repoPath = makeRepo('sealed-repo');
+  fs.chmodSync(repoPath, 0o000);
+  try {
+    const read = adapterFor('repo.git').rails.detect.truth(repoPath);
+    assert.equal(read.truth, 'unsettled');
+    assert.equal(read.reason, 'EACCES');
+    assert.ok(!('version' in read), 'unsettled truth claims no version');
+  } finally {
+    fs.chmodSync(repoPath, 0o755);
+  }
+  assert.equal(adapterFor('repo.git').rails.detect.truth(repoPath).truth, 'present',
+    'the same ground, readable again, settles to presence');
+});
+
+test('a git command failing mid-capture is unsettled — never a fourth answer', () => {
+  // The repo and its .git are visible, but git itself cannot read HEAD:
+  // capture fails AFTER the .git look succeeded. The contract promises
+  // exactly three answers — a throw is not one of them.
+  const repoPath = makeRepo('headless-repo');
+  fs.chmodSync(path.join(repoPath, '.git', 'HEAD'), 0o000);
+  try {
+    const read = adapterFor('repo.git').rails.detect.truth(repoPath);
+    assert.equal(read.truth, 'unsettled');
+    assert.match(read.reason, /^git /, 'the reason names the git command that failed');
+  } finally {
+    fs.chmodSync(path.join(repoPath, '.git', 'HEAD'), 0o644);
+  }
+  assert.equal(adapterFor('repo.git').rails.detect.truth(repoPath).truth, 'present',
+    'the same repository, readable again, settles to presence');
+});
+
+test('a membership that cannot be read completely is unsettled — never quietly partial', () => {
+  const dir = ground('sealed');
+  fs.writeFileSync(path.join(dir, 'inside.txt'), 'x');
+  fs.chmodSync(dir, 0o000);
+  try {
+    const read = adapterFor('folder').rails.detect.truth(dir);
+    assert.equal(read.truth, 'unsettled');
+    assert.equal(read.reason, 'EACCES');
+    assert.ok(!('state' in read), 'unsettled truth claims no state');
+  } finally {
+    fs.chmodSync(dir, 0o755);
+  }
+});
+
+test('STITCH: production detection and the adapter speak one truth — no parallel detector', () => {
+  // The observer's content decision (safeHash) now reads through the
+  // adapter socket. Prove agreement on real ground: the hash the
+  // production observer records for a file is byte-identical to the
+  // truth the adapter answers for the same ground.
+  const Database = require('better-sqlite3');
+  const { createObserver } = require('../observer');
+  const dir = fs.realpathSync(ground('stitch'));
+  fs.writeFileSync(path.join(dir, 'watched.txt'), 'one truth\n');
+  const events = [];
+  const observer = createObserver({ db: new Database(':memory:'), emit: (event) => events.push(event) });
+  try {
+    const root = observer.enrollRoot(dir);
+    observer.scanNow(root.rootId);
+    const born = events.find((event) => event.type === 'file.created' && event.path === 'watched.txt');
+    assert.ok(born, 'the observer detected the file');
+    const read = adapterFor('file.text').rails.detect.truth(path.join(dir, 'watched.txt'));
+    assert.equal(read.truth, 'present');
+    assert.equal(born.hash, read.state.sha256, 'observer-recorded content IS adapter truth');
+  } finally {
+    observer.stop?.();
+  }
+});
+
+test('filesystem truth follows the ground, not the label: a slot swapping file for link swaps kinds', () => {
+  const slot = path.join(ground('swap'), 'occupant');
+  fs.writeFileSync(slot, 'bytes');
+  const asFile = adapterFor('file.text').rails.detect.truth(slot);
+  assert.equal(asFile.state.kind, 'file');
+  fs.unlinkSync(slot);
+  fs.symlinkSync('over-there', slot);
+  const asLink = adapterFor('link').rails.detect.truth(slot);
+  assert.equal(asLink.state.kind, 'link');
+  assert.equal(asLink.state.target, 'over-there');
+  assert.notEqual(asLink.version, asFile.version);
+});
+
+test('folder truth is direct membership, never member content', () => {
+  const dir = ground('membership');
+  fs.writeFileSync(path.join(dir, 'a.txt'), 'one');
+  const before = adapterFor('folder').rails.detect.truth(dir);
+  assert.deepEqual(before.state.members, [{ name: 'a.txt', kind: 'file' }]);
+  fs.writeFileSync(path.join(dir, 'a.txt'), 'rewritten entirely');
+  const after = adapterFor('folder').rails.detect.truth(dir);
+  assert.equal(after.version, before.version, "a member's content is the member's truth, not the folder's");
+});
+
+// ---- The contract convicts -------------------------------------------
+
+test('an unfrozen descriptor convicts: the contract is frozen ground', () => {
+  const thawed = { name: 'exam', types: Object.freeze({ link: 'its written target text' }), rails: Object.freeze({}) };
+  assert.throws(() => assertAdapter(thawed), /frozen object/);
+});
+
+test('a nameless adapter convicts', () => {
+  assert.throws(() => assertAdapter(lawfulAdapter({ name: '' })), /name is a non-empty string/);
+});
+
+test('an adapter serving no types convicts', () => {
+  assert.throws(() => assertAdapter(lawfulAdapter({ types: Object.freeze({}) })), /non-empty map of entity type/);
+});
+
+test('an undeclared truth convicts: every type names its source of truth', () => {
+  assert.throws(
+    () => assertAdapter(lawfulAdapter({ types: Object.freeze({ 'file.text': '' }) })),
+    /must declare its source of truth/,
+  );
+});
+
+test('an invented rail convicts and names the seven', () => {
+  assert.throws(
+    () => assertAdapter(lawfulAdapter({ rails: Object.freeze({ teleport: Object.freeze({ go: () => null }) }) })),
+    /"teleport" is not a rail/,
+  );
+});
+
+test('binding a rail with no ratified socket convicts: the socket comes first', () => {
+  // apply and verify are real rails with real repocard implementations —
+  // and STILL unbindable, because no multi-type consumer has ratified
+  // their socket. Deferral is enforced, not just documented.
+  for (const rail of ['watch', 'record', 'send', 'receive', 'apply', 'verify']) {
+    assert.throws(
+      () => assertAdapter(lawfulAdapter({ rails: Object.freeze({ [rail]: Object.freeze({ go: () => null }) }) })),
+      /no ratified socket yet/,
+      `${rail} has no socket to bind`,
+    );
+  }
+});
+
+test('an adapter-specific surface name convicts: the socket is the same for everyone', () => {
+  assert.throws(
+    () => assertAdapter(lawfulAdapter({ rails: Object.freeze({ detect: Object.freeze({ walkRoot: () => null }) }) })),
+    /whole socket or binds the rail not at all/,
+  );
+});
+
+test('a partial or padded socket convicts: whole socket or nothing', () => {
+  assert.throws(
+    () => assertAdapter(lawfulAdapter({ rails: Object.freeze({ detect: Object.freeze({}) }) })),
+    /whole socket or binds the rail not at all/,
+  );
+  assert.throws(
+    () => assertAdapter(lawfulAdapter({ rails: Object.freeze({ detect: Object.freeze({ truth: () => null, extra: () => null }) }) })),
+    /whole socket or binds the rail not at all/,
+  );
+});
+
+test('a stubbed surface convicts: unbuilt means absent, never a placeholder', () => {
+  assert.throws(
+    () => assertAdapter(lawfulAdapter({ rails: Object.freeze({ detect: Object.freeze({ truth: null }) }) })),
+    /never stubbed/,
+  );
+});
+
+test('thawed rails or surfaces convict: freezing is per level, not just the top', () => {
+  assert.throws(
+    () => assertAdapter(lawfulAdapter({ rails: { detect: Object.freeze({ truth: () => null }) } })),
+    /rails is a frozen map/,
+  );
+  assert.throws(
+    () => assertAdapter(lawfulAdapter({ rails: Object.freeze({ detect: { truth: () => null } }) })),
+    /frozen map of its socket's surfaces/,
+  );
+});
+
+// ---- The map builder convicts ----------------------------------------
+
+test('two adapters claiming one type convicts and names both claimants', () => {
+  const a = lawfulAdapter({ name: 'first' });
+  const b = lawfulAdapter({ name: 'second' });
+  assert.throws(() => buildTypeMap([a, b], ['file.text']), /claimed by both first and second/);
+});
+
+test('claiming a type outside the alphabet convicts', () => {
+  const a = lawfulAdapter({ types: Object.freeze({ hologram: 'projected light' }) });
+  assert.throws(() => buildTypeMap([a], ['file.text']), /not in the registry's alphabet/);
+});
+
+test('an unassigned alphabet type convicts: every type is assigned', () => {
+  assert.throws(() => buildTypeMap([lawfulAdapter()], ['file.text', 'file.binary']), /"file.binary" has no adapter/);
+});
+
+test('detect is the ONLY ratified socket: a socket is derived from a real consumer or not ratified at all', () => {
+  assert.ok(Object.isFrozen(SOCKETS));
+  assert.deepEqual(Object.keys(SOCKETS), ['detect']);
+  assert.deepEqual([...SOCKETS.detect], ['truth']);
+});