amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/registry/index.js

@@ -0,0 +1,666 @@
+'use strict';
+
+/**
+ * The entity registry: the canonical owner of the six-field universal
+ * records (docs/entity-model.md). Adapters observe and PROPOSE; only this
+ * module validates, versions, and commits — and only its lifecycle verbs
+ * ever write `status`. The evidence path has no status parameter at all,
+ * so detection cannot write lifecycle by construction.
+ *
+ * The rules it enforces are exactly the ratified axioms, nothing more:
+ *  - ONE identity database holds every registered tree: each tree is one
+ *    active parentless record — a workspace, a repo.git, or, a tree of
+ *    one, a single registered file or explicitly registered link
+ *    (`amalgm register <path>` names an address, and a pointer at that
+ *    address is an entity of its own; docs/realtime-rails.md). A tree
+ *    boundary is never an identity boundary: an entity moves between
+ *    trees as a parent update in one transaction, and a whole tree
+ *    joining another (ADOPTION) is the same lawful move performed on a
+ *    parentless record — the UUID and every descendant ride along;
+ *  - one active owner per (parentUUID, name) slot (the schema convicts
+ *    too); parentless records are exempt — a top-level tree is placed by
+ *    its machine binding, never by name;
+ *  - only containers — workspace, folder, repo.git — hold active children;
+ *  - the parent graph is acyclic;
+ *  - valid type transitions preserve the UUID; a folder with stored-active
+ *    children never becomes a file (that flip would canonicalize subtree
+ *    destruction);
+ *  - lifecycle is explicit: trash (active → trashed), restore
+ *    (trashed → active, refused while another active entity owns the slot),
+ *    and empty-trash (trashed → deleted, owner-only via the injected
+ *    `authorizeDelete`; unwired means unavailable, never fail-open);
+ *  - lifecycle inherits DOWN the chain as derived effective status — one
+ *    flip on a folder, no descendant record rewritten.
+ *
+ * The canonical version is DERIVED, never stored: a column could drift
+ * from its inputs, a pure function cannot. Container payloads (workspace,
+ * folder) are their sorted active direct membership; other types attest
+ * their payload version through the evidence path.
+ *
+ * First initialization is distinguished from loss: an empty database on a
+ * fresh machine enrolls; a database missing tables where the sentinel says
+ * a registry existed fails loudly and never silently mints replacement
+ * UUIDs. A DURABLE REGISTRY REQUIRES A SENTINEL — only a real in-memory
+ * database may declare `ephemeral: true` instead. Losing both the database
+ * and the sentinel stays honestly unsolvable until remote identity storage
+ * exists.
+ *
+ * Registry state is truth; notifications are doorbells. `entity.committed`
+ * payloads are an optimization, never authoritative mutations — every
+ * consumer rereads and compares registry versions, and startup attachment
+ * always compares (a restart loses the pending flag). A failed ring leaves
+ * one pending bell, cleared only by a successful `registry.changed`;
+ * `flush()` always requests comparison regardless of the flag.
+ *
+ * NOTHING RINGS UNTIL ITS TRUTH COMMITS: an event born inside an open
+ * transaction waits for the outermost commit and a rollback silences it,
+ * so a consumer can never hear a record the database never held. The
+ * registry owns the identity database's one transition primitive
+ * (`transaction`) for exactly this reason — the ringer must own the
+ * commit boundary its bells wait on.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+
+const { createStore, inspect, isMigratableGenerationShape } = require('./store');
+
+// `link` is a filesystem symlink as ratified: payload = the literal
+// target text, resolution derived, death honest. `reference` is the
+// OTHER link kind, never conflated: Amalgm-created by a deliberate act,
+// its payload is the TARGET ENTITY'S UUID — identity, not an address —
+// and its local rendering as an ordinary symlink is derived state the
+// registration boundary maintains.
+// The alphabet is PHYSICAL kinds only. Constructs — agents, apps,
+// automations, tools, skills — are organized filesystem ground with a
+// known structure: physically folders and files, with their construct
+// meaning layered ABOVE the physical type, never encoded as one.
+// (The former `automation`/`agent` placeholder types contradicted
+// themselves: declared as folder-shaped ground yet barred from holding
+// children. Removed by ratification 2026-08-02; promoting a construct
+// to a physical type would take proof that it truly travels or applies
+// differently — a deliberate future decision, never a default.)
+const TYPES = new Set([
+  'workspace', 'folder', 'repo.git', 'file.text', 'file.binary',
+  'link', 'reference',
+]);
+const CONTAINERS = new Set(['workspace', 'folder', 'repo.git']);
+const ROOT_TYPES = new Set(['workspace', 'repo.git', 'file.text', 'file.binary', 'link']);
+// Types whose payload IS their membership: derived from the records
+// beneath them, so no observation may attest one.
+const DERIVED_PAYLOAD = new Set(['workspace', 'folder']);
+
+// The one entity alphabet, published for the layers that map onto it
+// (adapters/ serves every member) — read from here, never restated,
+// so the alphabet cannot drift from the registry that enforces it.
+const ENTITY_TYPES = Object.freeze([...TYPES].sort());
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+/**
+ * What an attestation may say — asked of both the type a record wears
+ * now and the type its new bytes claim, because an attestation may
+ * carry a record across leaf kinds (a pointer replaced by bytes) and
+ * both ends must be ground an observation can speak for.
+ */
+function attestable(type) {
+  if (DERIVED_PAYLOAD.has(type)) {
+    throw new Error(`${type} payload is derived membership, never attested`);
+  }
+  if (type === 'reference') {
+    throw new Error('a reference\'s payload is the target\'s identity, set by the deliberate act that created it — never an attestation; the rendered symlink is derived state, not evidence');
+  }
+  if (!TYPES.has(type)) throw new Error(`unknown entity type ${JSON.stringify(type)}`);
+}
+
+/** The ratified formula: version = hash(type, parentUUID, name, status, payloadVersion). */
+function canonicalVersion({ type, parentUUID = null, name, status, payloadVersion = null }) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify([type, parentUUID, name, status, payloadVersion]))
+    .digest('hex');
+}
+
+function createRegistry(options) {
+  const {
+    db,
+    emit,
+    sentinelPath = null,
+    ephemeral = false,
+    authorizeDelete = null,
+    journal = null,
+  } = options;
+  if (!db) throw new Error('createRegistry requires { db }');
+  if (typeof emit !== 'function') throw new Error('createRegistry requires { emit }');
+  if (journal !== null && typeof journal !== 'function') {
+    throw new Error('createRegistry journal must be a function when supplied');
+  }
+  if (ephemeral) {
+    if (sentinelPath) throw new Error('ephemeral and sentinelPath are contradictory: pick one');
+    if (!db.memory) throw new Error(`ephemeral is for a real in-memory database; this one lives at ${db.name}`);
+  } else if (!sentinelPath) {
+    throw new Error('a durable registry requires a sentinel: pass sentinelPath, or ephemeral: true for a real in-memory database');
+  }
+
+  // ---- Sentinel: first init vs loss, decided before any schema exists ----
+  // The registry tables — records, evidence memory, and repo state — are
+  // born together, so
+  // any missing one in an established database is loss, never first init:
+  // silently recreating a table would be forgetting that resolves identity.
+  const inspection = inspect(db);
+  const { fresh, missing } = inspection;
+  if (!fresh && missing.length > 0 && !isMigratableGenerationShape(db, inspection)) {
+    throw new Error(`registry corrupt: ${missing.join(', ')} gone from a database where a registry lived — refusing to touch it`);
+  }
+  const marker = sentinelPath && fs.existsSync(sentinelPath)
+    ? fs.readFileSync(sentinelPath, 'utf8').trim()
+    : null;
+  if (fresh && marker !== null) {
+    throw new Error(`registry lost: sentinel ${sentinelPath} says epoch ${marker} lived here, but this database holds no registry — refusing to mint replacement identities`);
+  }
+  const store = createStore(db);
+  if (fresh) store.initMeta({ epochUuid: crypto.randomUUID(), createdAtMs: Date.now() });
+  const meta = store.meta();
+  if (!meta) {
+    throw new Error('registry corrupt: registry_meta exists but holds no epoch row — refusing to re-initialize over it');
+  }
+  if (sentinelPath) {
+    if (marker === null) {
+      fs.writeFileSync(sentinelPath, `${meta.epochUuid}\n`);
+      if (!fresh) console.warn(`[Registry] sentinel marker was missing at ${sentinelPath}; rewrote epoch ${meta.epochUuid}`);
+    } else if (marker !== meta.epochUuid) {
+      throw new Error(`registry mismatch: sentinel epoch ${marker} is not this database's epoch ${meta.epochUuid} — this is not the registry that lived here`);
+    }
+  }
+
+  // ---- Internals ----
+
+  // Registry state is truth; notifications are DOORBELLS. `entity.committed`
+  // payloads are an optimization, never authoritative mutations — every
+  // consumer rereads and compares registry versions. A failed ring leaves
+  // the bell pending: multiple misses collapse into the one comparison the
+  // consumer owes anyway, so no event content is ever stored for replay.
+  // The flag is in-memory only — a restart loses it — which is why startup
+  // attachment must always compare, pending bell or not.
+  let bellPending = false;
+  const deferred = []; // bells born inside an open transaction: they ring at commit, or a rollback silences them
+
+  function ring(event) {
+    try {
+      emit(event);
+      return true;
+    } catch (error) {
+      console.warn('[Registry] ring failed:', error?.message || error);
+      return false;
+    }
+  }
+
+  function publish(event) {
+    // Nothing rings until its truth commits: inside a transaction the
+    // bell waits — transaction() flushes it after the outermost commit,
+    // and a rollback discards exactly what it rolled back.
+    if (db.inTransaction) {
+      deferred.push(event);
+      return;
+    }
+    if (bellPending) {
+      if (!ring({ type: 'registry.changed' })) return; // still down; truth waits in the registry
+      bellPending = false;
+    }
+    if (!ring(event)) bellPending = true;
+  }
+
+  function transaction(fn) {
+    const outermost = !db.inTransaction;
+    const mark = deferred.length;
+    try {
+      const result = db.transaction(fn)();
+      if (outermost) {
+        while (deferred.length > 0) publish(deferred.shift());
+      }
+      return result;
+    } catch (error) {
+      deferred.length = mark;
+      throw error;
+    }
+  }
+
+  function mustGet(uuid) {
+    const row = store.byUuid(uuid);
+    if (!row) throw new Error(`no entity ${uuid}`);
+    return row;
+  }
+
+  function validName(name) {
+    if (typeof name !== 'string' || name === '' || name === '.' || name === '..'
+      || name.includes('/') || name.includes('\0')) {
+      throw new Error(`invalid entity name ${JSON.stringify(name)}: a name is one non-empty path segment`);
+    }
+  }
+
+  /** A UUID may arrive only through a trusted identity binding (for example
+   * a cloud user-home bootstrap). The registry still owns the actual insert:
+   * accepting a caller-supplied UUID is not accepting a caller-supplied
+   * record, parent, status, or version. */
+  function mintOrValidateUuid(uuid) {
+    if (uuid === undefined || uuid === null) return crypto.randomUUID();
+    if (typeof uuid !== 'string' || !UUID.test(uuid)) {
+      throw new Error(`entity identity must be a UUID, got ${JSON.stringify(uuid)}`);
+    }
+    if (store.byUuid(uuid)) throw new Error(`entity identity ${uuid} is already registered`);
+    return uuid.toLowerCase();
+  }
+
+  /** Ancestor uuids from the given parent up to the root. */
+  function ancestorsOf(parentUuid) {
+    const chain = [];
+    const seen = new Set();
+    let cursor = parentUuid;
+    while (cursor !== null) {
+      if (seen.has(cursor)) throw new Error(`registry corrupt: parent cycle at ${cursor}`);
+      seen.add(cursor);
+      chain.push(cursor);
+      cursor = mustGet(cursor).parentUuid;
+    }
+    return chain;
+  }
+
+  function effectiveStatusOf(row) {
+    const statuses = [row.status, ...ancestorsOf(row.parentUuid).map((uuid) => mustGet(uuid).status)];
+    if (statuses.includes('deleted')) return 'deleted';
+    if (statuses.includes('trashed')) return 'trashed';
+    return row.status;
+  }
+
+  /** Container payload: the sorted active direct membership (childUUID, name). */
+  function membershipHash(uuid) {
+    const pairs = store.activeChildrenOf(uuid).map((child) => [child.uuid, child.name]);
+    return crypto.createHash('sha256').update(JSON.stringify(pairs)).digest('hex');
+  }
+
+  function payloadFor(row) {
+    return DERIVED_PAYLOAD.has(row.type) ? membershipHash(row.uuid) : row.payloadVersion;
+  }
+
+  function record(row) {
+    return {
+      uuid: row.uuid,
+      type: row.type,
+      parentUUID: row.parentUuid,
+      name: row.name,
+      version: canonicalVersion({
+        type: row.type, parentUUID: row.parentUuid, name: row.name,
+        status: row.status, payloadVersion: payloadFor(row),
+      }),
+      status: row.status,
+    };
+  }
+
+  /** The cloud form contains identity and the content/head token, never an
+   * address, watcher, inode, or SQLite bytes. `payloadVersion` is the
+   * unambiguous current head for leaf types; containers derive theirs from
+   * membership and retain null here; a repo.git retains its immutable
+   * Card/Checkpoint head. */
+  function syncRecord(row) {
+    return {
+      ...record(row),
+      payloadVersion: row.payloadVersion,
+    };
+  }
+
+  function journalRecord(next, previous) {
+    // This call intentionally happens inside the identity transaction and
+    // before notification. A failed journal write rolls the entity mutation
+    // back; a later process can never observe local truth without its cloud
+    // delivery intent.
+    if (journal) journal({ record: syncRecord(next), previous: previous ? syncRecord(previous) : null });
+  }
+
+  function normalizeCloudRecord(value) {
+    if (!value || typeof value !== 'object'
+      || typeof value.uuid !== 'string' || !UUID.test(value.uuid)
+      || typeof value.type !== 'string' || !TYPES.has(value.type)
+      || (value.parentUUID !== null && (typeof value.parentUUID !== 'string' || !UUID.test(value.parentUUID)))
+      || typeof value.name !== 'string'
+      || !['active', 'trashed', 'deleted'].includes(value.status)
+      || (value.payloadVersion !== null && typeof value.payloadVersion !== 'string')
+      || typeof value.version !== 'string' || !/^[0-9a-f]{64}$/i.test(value.version)) {
+      throw new Error('cloud entity operation has an invalid record');
+    }
+    validName(value.name);
+    if (value.parentUUID === null && !ROOT_TYPES.has(value.type)) {
+      throw new Error(`cloud entity ${value.uuid} is not a valid tree root`);
+    }
+    if (value.parentUUID !== null && value.type === 'workspace') {
+      throw new Error('cloud entity workspace is the root type only');
+    }
+    return {
+      uuid: value.uuid.toLowerCase(),
+      type: value.type,
+      parentUuid: value.parentUUID === null ? null : value.parentUUID.toLowerCase(),
+      name: value.name,
+      status: value.status,
+      payloadVersion: value.payloadVersion,
+      expectedVersion: value.version.toLowerCase(),
+    };
+  }
+
+  function sameLogicalRecord(left, right) {
+    return left.uuid === right.uuid
+      && left.type === right.type
+      && left.parentUuid === right.parentUuid
+      && left.name === right.name
+      && left.status === right.status
+      && left.payloadVersion === right.payloadVersion;
+  }
+
+  /** Every write funnels through here: previous captured, change applied, one event. */
+  function commit(row, changes) {
+    if (!db.inTransaction) return transaction(() => commit(row, changes));
+    const previous = record(row);
+    store.update(row.uuid, { ...row, ...changes });
+    const nextRow = mustGet(row.uuid);
+    const next = record(nextRow);
+    journalRecord(nextRow, row);
+    publish({ type: 'entity.committed', record: next, previous });
+    return next;
+  }
+
+  function requireActiveContainerParent(parentUuid) {
+    const parent = mustGet(parentUuid);
+    if (!CONTAINERS.has(parent.type)) {
+      throw new Error(`only containers hold active children: ${parentUuid} is ${parent.type}, not workspace/folder/repo.git`);
+    }
+    if (effectiveStatusOf(parent) !== 'active') {
+      throw new Error(`parent ${parentUuid} is not effectively active — restore it before putting entities under it`);
+    }
+    return parent;
+  }
+
+  function requireFreeSlot(parentUuid, name, forUuid = null) {
+    if (parentUuid === null) return; // top level: address places a tree, never its name
+    const occupant = store.activeAtSlot(parentUuid, name);
+    if (occupant && occupant.uuid !== forUuid) {
+      throw new Error(`slot taken: active entity ${occupant.uuid} already owns (${parentUuid}, ${name}) — move or trash it first`);
+    }
+  }
+
+  /**
+   * One batch of moves, one transition. The slot law and acyclicity are
+   * STATE invariants: they constrain the graph after the batch, never the
+   * order inside it — so movers may hold each other's slots (directories
+   * exchange addresses on disk, and detection reports the endpoints). A
+   * single move is a batch of one. A PARENTLESS mover is ADOPTION: the
+   * whole tree joins another under one parent update — a tree boundary
+   * is never an identity boundary, so this is the same lawful move, not
+   * a special ceremony.
+   */
+  function moveMany(moves) {
+    if (!db.inTransaction) return transaction(() => moveMany(moves));
+    const rows = new Map(); // uuid -> current row
+    const post = new Map(); // uuid -> its move
+    for (const move of moves) {
+      const { uuid, name } = move;
+      if (post.has(uuid)) throw new Error(`one batch moves ${uuid} once, not twice`);
+      const row = mustGet(uuid);
+      if (row.status !== 'active') {
+        throw new Error(`only an active entity moves: ${uuid} is ${row.status}`);
+      }
+      validName(name);
+      rows.set(uuid, row);
+      post.set(uuid, move);
+    }
+    const postParentOf = (uuid) => post.get(uuid)?.parentUUID ?? mustGet(uuid).parentUuid;
+    const targets = new Set();
+    for (const { uuid, parentUUID, name } of moves) {
+      const parent = mustGet(parentUUID);
+      if (!CONTAINERS.has(parent.type)) {
+        throw new Error(`only containers hold active children: ${parentUUID} is ${parent.type}, not workspace/folder/repo.git`);
+      }
+      const slot = `${parentUUID}\0${name}`;
+      if (targets.has(slot)) throw new Error(`slot taken: two movers claim (${parentUUID}, ${name}) in one batch`);
+      targets.add(slot);
+      const occupant = store.activeAtSlot(parentUUID, name);
+      if (occupant && occupant.uuid !== uuid && !post.has(occupant.uuid)) {
+        throw new Error(`slot taken: active entity ${occupant.uuid} already owns (${parentUUID ?? 'root'}, ${name}) — move or trash it first`);
+      }
+      // The target parent's whole post-state chain: acyclic and effectively
+      // active, walked once.
+      const seen = new Set();
+      let cursor = parentUUID;
+      while (cursor !== null) {
+        if (cursor === uuid) {
+          throw new Error(`the parent graph is acyclic: ${uuid} cannot live under itself`);
+        }
+        if (seen.has(cursor)) throw new Error(`registry corrupt: parent cycle at ${cursor}`);
+        seen.add(cursor);
+        if (mustGet(cursor).status !== 'active') {
+          throw new Error(`parent ${parentUUID} is not effectively active — restore it before putting entities under it`);
+        }
+        cursor = postParentOf(cursor);
+      }
+    }
+    const previous = moves.map(({ uuid }) => record(rows.get(uuid)));
+    // Adoption sheds the root shape in the SAME transition: workspace is
+    // the root type only, so a parentless workspace landing under a
+    // parent lands as a folder — one write, never a two-step that could
+    // tear into a nested workspace.
+    store.applyMoves(moves.map(({ uuid, parentUUID, name }) => {
+      const row = rows.get(uuid);
+      const adoptedWorkspace = row.parentUuid === null && row.type === 'workspace';
+      return { uuid, parentUuid: parentUUID, name, ...(adoptedWorkspace ? { type: 'folder' } : {}) };
+    }));
+    return moves.map(({ uuid }, index) => {
+      const nextRow = mustGet(uuid);
+      const next = record(nextRow);
+      journalRecord(nextRow, rows.get(uuid));
+      publish({ type: 'entity.committed', record: next, previous: previous[index] });
+      return next;
+    });
+  }
+
+  // ---- The registry ----
+
+  return {
+    epoch: () => meta.epochUuid,
+    canonicalVersion,
+
+    /**
+     * The identity database's one transition primitive: everything the
+     * callback writes — records and evidence bindings alike, they share
+     * this database — lands or none of it does, and every bell those
+     * writes rang waits here: bells ring only after the OUTERMOST
+     * commit, and a rollback silences exactly what it rolled back
+     * (a nested savepoint truncates to its own mark). A tree's birth
+     * uses it so a minted record and its witness binding never tear
+     * apart — and never announce a record that rolled back.
+     */
+    transaction,
+
+    /** Always requests comparison — it never trusts the in-memory flag,
+     * because a restart loses that memory. Returns whether the bell rang. */
+    flush() {
+      if (ring({ type: 'registry.changed' })) {
+        bellPending = false;
+        return true;
+      }
+      bellPending = true;
+      return false;
+    },
+
+    /** Births one registered tree's top record. The one registry holds
+     * every tree, so enrolling another root is ordinary — each is one
+     * active parentless record, placed by its machine binding. */
+    enrollRoot({ type, name, payloadVersion = null, uuid = undefined }) {
+      if (!db.inTransaction) {
+        return transaction(() => this.enrollRoot({ type, name, payloadVersion, uuid }));
+      }
+      if (!ROOT_TYPES.has(type)) {
+        throw new Error(`the root is workspace, repo.git, a registered file, or a registered link, never ${JSON.stringify(type)}`);
+      }
+      validName(name);
+      const row = {
+        uuid: mintOrValidateUuid(uuid), type, parentUuid: null, name, status: 'active', payloadVersion,
+      };
+      store.insert(row);
+      const next = record(row);
+      journalRecord(row, null);
+      publish({ type: 'entity.committed', record: next, previous: null });
+      return next;
+    },
+
+    create({ type, parentUUID, name, payloadVersion = null, uuid = undefined }) {
+      if (!db.inTransaction) {
+        return transaction(() => this.create({ type, parentUUID, name, payloadVersion, uuid }));
+      }
+      if (!TYPES.has(type)) throw new Error(`unknown entity type ${JSON.stringify(type)}`);
+      if (type === 'workspace') throw new Error('workspace is the root type only; a nested container is a folder');
+      validName(name);
+      requireActiveContainerParent(parentUUID);
+      requireFreeSlot(parentUUID, name);
+      const row = {
+        uuid: mintOrValidateUuid(uuid), type, parentUuid: parentUUID, name,
+        status: 'active', payloadVersion,
+      };
+      store.insert(row);
+      const next = record(row);
+      journalRecord(row, null);
+      publish({ type: 'entity.committed', record: next, previous: null });
+      return next;
+    },
+
+    move(uuid, { parentUUID, name }) {
+      return moveMany([{ uuid, parentUUID, name }])[0];
+    },
+    moveMany,
+
+    /**
+     * The evidence path, and ONE OBSERVATION IS ONE TRANSITION: the
+     * payload a look found and the type that same look implies land in
+     * a single commit, or neither does. Two writes could tear — new
+     * bytes wearing an old type — and the equal-payload silence on the
+     * next pass would never heal it, because the payload it compares
+     * already matches. One write, one bell: what a consumer hears is a
+     * state disk actually held.
+     *
+     * Equal attestations are silence.
+     */
+    attest(uuid, { payloadVersion, type }) {
+      const row = mustGet(uuid);
+      if (row.status !== 'active') {
+        throw new Error(`only an active entity attests payload: ${uuid} is ${row.status}`);
+      }
+      attestable(row.type);
+      attestable(type);
+      if (row.parentUuid === null && !ROOT_TYPES.has(type)) {
+        throw new Error(`the root is workspace, repo.git, a registered file, or a registered link, never ${JSON.stringify(type)}`);
+      }
+      if (row.type === type && row.payloadVersion === payloadVersion) return record(row);
+      return commit(row, { type, payloadVersion });
+    },
+
+    changeType(uuid, type, { payloadVersion = null } = {}) {
+      const row = mustGet(uuid);
+      if (row.status !== 'active') {
+        throw new Error(`only an active entity changes type: ${uuid} is ${row.status}`);
+      }
+      if (!TYPES.has(type)) throw new Error(`unknown entity type ${JSON.stringify(type)}`);
+      if (row.parentUuid === null) {
+        if (!ROOT_TYPES.has(type)) throw new Error(`the root is workspace, repo.git, a registered file, or a registered link, never ${JSON.stringify(type)}`);
+      } else if (type === 'workspace') {
+        throw new Error('workspace is the root type only; a nested container is a folder');
+      }
+      if (!CONTAINERS.has(type)) {
+        const children = store.activeChildrenOf(uuid);
+        if (children.length > 0) {
+          throw new Error(`refusing ${row.type} → ${type} on ${uuid}: ${children.length} stored-active child(ren) would be stranded — only containers hold active children`);
+        }
+      }
+      if (type === row.type) return record(row);
+      return commit(row, {
+        type, payloadVersion: DERIVED_PAYLOAD.has(type) ? null : payloadVersion,
+      });
+    },
+
+    trash(uuid) {
+      const row = mustGet(uuid);
+      if (row.status !== 'active') throw new Error(`trash is active → trashed: ${uuid} is ${row.status}`);
+      if (row.parentUuid === null) {
+        throw new Error('a tree\'s top record is never trashed: removing a whole tree is an explicit future operation, never a lifecycle flip');
+      }
+      return commit(row, { status: 'trashed' });
+    },
+
+    restore(uuid) {
+      const row = mustGet(uuid);
+      if (row.status === 'deleted') throw new Error(`deleted is permanent: ${uuid} cannot be restored`);
+      if (row.status !== 'trashed') throw new Error(`restore is trashed → active: ${uuid} is ${row.status}`);
+      requireFreeSlot(row.parentUuid, row.name);
+      return commit(row, { status: 'active' });
+    },
+
+    deletePermanently(uuid) {
+      if (typeof authorizeDelete !== 'function') {
+        throw new Error('permanent deletion is unavailable: no ownership authorization is wired (authorizeDelete)');
+      }
+      const row = mustGet(uuid);
+      if (row.status === 'deleted') throw new Error(`${uuid} is already deleted`);
+      if (row.status !== 'trashed') {
+        throw new Error(`empty-trash deletes from Trash only: ${uuid} is ${row.status} — trash it first`);
+      }
+      if (!authorizeDelete(record(row))) {
+        throw new Error(`permanent deletion is owner-only: not authorized for ${uuid}`);
+      }
+      return commit(row, { status: 'deleted' });
+    },
+
+    /**
+     * Apply one already-authorized cloud operation without creating a new
+     * local outbox row. This is intentionally a graph operation only: no
+     * observer root, path, inode, or watcher is created by an inbound UUID.
+     */
+    applyCloudRecord(value) {
+      const incoming = normalizeCloudRecord(value);
+      return transaction(() => {
+        const previous = store.byUuid(incoming.uuid);
+        if (!previous && incoming.parentUuid !== null && !store.byUuid(incoming.parentUuid)) {
+          throw new Error(`cloud entity ${incoming.uuid} names missing parent ${incoming.parentUuid}`);
+        }
+        if (previous) {
+          store.update(incoming.uuid, incoming);
+        } else {
+          store.insert(incoming);
+        }
+        const current = mustGet(incoming.uuid);
+        const synced = syncRecord(current);
+        if (synced.version !== incoming.expectedVersion) {
+          throw new Error(`cloud entity ${incoming.uuid} version does not match its logical record`);
+        }
+        const previousRecord = previous ? record(previous) : null;
+        if (!previous || !sameLogicalRecord(previous, current)) {
+          publish({ type: 'entity.committed', record: record(current), previous: previousRecord });
+        }
+        return synced;
+      });
+    },
+
+    record: (uuid) => record(mustGet(uuid)),
+    syncRecord: (uuid) => syncRecord(mustGet(uuid)),
+    /** Full logical graph for cloud snapshots. Machine bindings and evidence
+     * are intentionally absent. */
+    syncRecords: () => store.allEntities().map(syncRecord),
+    /** Every registered tree's top record. */
+    roots: () => store.activeRoots().map(record),
+    /** Every active managed reference with the identity it targets. The
+     * six-field record law holds: the target UUID is the payload, and it
+     * travels beside the record here, never as a seventh field. */
+    references: () => store.activeByType('reference')
+      .map((row) => ({ record: record(row), targetUUID: row.payloadVersion })),
+    activeAt: (parentUUID, name) => {
+      const row = store.activeAtSlot(parentUUID, name);
+      return row ? record(row) : null;
+    },
+    children: (uuid) => store.childrenOf(uuid).map(record),
+    effectiveStatus: (uuid) => effectiveStatusOf(mustGet(uuid)),
+  };
+}
+
+module.exports = { createRegistry, canonicalVersion, ENTITY_TYPES };