amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/registration/tree.js

@@ -0,0 +1,178 @@
+'use strict';
+
+/**
+ * Structural registration for `amalgm register`.
+ *
+ * Purpose: give every enrolled thing a durable UUID before realtime work
+ * begins. This is deliberately a filesystem-shape walk: names, nesting,
+ * directories, links, ordinary files, and repository boundaries. It never
+ * reads a file's bytes or a link's target. A repository boundary adds one
+ * required semantic fact: its initial Card + Checkpoint baseline. Detect
+ * owns all later changing facts after Watch has started.
+ *
+ * Axioms:
+ *   1. Registration records the complete enrolled shape, never content.
+ *   2. One registration walk commits the tree and its root witness together.
+ *   3. A repository is a boundary for realtime semantics, never a hole in
+ *      the entity tree: `.git` is excluded, its allowed worktree children
+ *      are registered beneath the repo.git entity.
+ *   4. Every repo.git record is born with a persisted Card + Checkpoint;
+ *      Watch resumes from that baseline rather than inventing one later.
+ *
+ * The existing public alphabet still distinguishes file.text/file.binary,
+ * although they have identical behavior today. A structural walk therefore
+ * uses file.text as the content-free ordinary-file placeholder. The first
+ * Detect pass immediately attests the actual bytes and corrects that
+ * representation through the normal one-observation transition.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function rootType(rootPath, kind) {
+  if (kind === 'repo') return 'repo.git';
+  if (kind !== 'file') return 'workspace';
+  return fs.lstatSync(rootPath).isSymbolicLink() ? 'link' : 'file.text';
+}
+
+function isRepository(dirPath) {
+  try {
+    fs.lstatSync(path.join(dirPath, '.git'));
+    return true;
+  } catch (error) {
+    // A failed look cannot prove a repo boundary. Register the readable
+    // shape below it; observer territory detection retries the boundary
+    // look and performs the UUID-preserving folder → repo.git transition
+    // once Git becomes knowable.
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR'
+      || error.code === 'EACCES' || error.code === 'EPERM') return false;
+    throw error;
+  }
+}
+
+/**
+ * Create the root record, its witness, and every entity below ordinary
+ * directory ground. The caller supplies a root that is already known to the
+ * observer but is not yet watched or scanned.
+ */
+function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoStates, identityAt = null }) {
+  if (!root || !registry || !memory || typeof shouldEnroll !== 'function'
+    || typeof captureRepo !== 'function' || !repoStates) {
+    throw new Error('registerTree requires { root, registry, memory, shouldEnroll, captureRepo, repoStates }');
+  }
+
+  if (identityAt !== null && typeof identityAt !== 'function') {
+    throw new Error('registerTree identityAt must be a function when supplied');
+  }
+
+  function seeded(relativePath, { type, parentUUID, name, root: isRoot }) {
+    const identity = identityAt?.(relativePath) || null;
+    if (!identity) return { type, uuid: undefined };
+    if (identity.name !== name || identity.parentUUID !== parentUUID || identity.status !== 'active') {
+      throw new Error(`cloud identity at ${relativePath || '.'} does not match the local declared tree`);
+    }
+    // The structural walk intentionally does not read file bytes. A seeded
+    // file may therefore retain either physical file subtype until Detect
+    // observes its local bytes; directories and links must already agree.
+    const compatibleFile = type === 'file.text'
+      && (identity.type === 'file.text' || identity.type === 'file.binary');
+    if (identity.type !== type && !compatibleFile) {
+      throw new Error(`cloud identity at ${relativePath || '.'} is ${identity.type}, local declared tree is ${type}`);
+    }
+    if (isRoot && !['workspace', 'repo.git', 'file.text', 'file.binary', 'link'].includes(identity.type)) {
+      throw new Error(`cloud identity at ${relativePath || '.'} is not a valid tree root`);
+    }
+    return { type: identity.type, uuid: identity.uuid };
+  }
+
+  return registry.transaction(() => {
+    const initialState = root.kind === 'repo' ? captureInitialRepo(root.path, captureRepo) : null;
+    const rootIdentity = seeded('', {
+      type: rootType(root.path, root.kind), parentUUID: null, name: path.basename(root.path), root: true,
+    });
+    const record = registry.enrollRoot({
+      type: rootIdentity.type,
+      name: path.basename(root.path),
+      payloadVersion: initialState?.stateId ?? null,
+      uuid: rootIdentity.uuid,
+    });
+    memory.bind(root.rootId, root.rootId, record.uuid);
+    if (initialState) repoStates.put(record.uuid, initialState);
+
+    if (root.kind === 'files' || root.kind === 'repo') {
+      registerDirectory(root.path, record.uuid, {
+        registry, shouldEnroll, captureRepo, repoStates, identityAt, seeded, relativePath: '',
+      });
+    }
+    return record;
+  });
+}
+
+function captureInitialRepo(repoPath, captureRepo) {
+  const state = captureRepo(repoPath);
+  if (state?.busy) {
+    throw new Error(`cannot register ${repoPath}: Git is unsettled (${state.busy})`);
+  }
+  if (!state?.stateId || !state.cardId || !state.checkpointId) {
+    throw new Error(`cannot register ${repoPath}: Git did not produce a Card + Checkpoint state`);
+  }
+  return state;
+}
+
+function registerDirectory(dirPath, parentUUID, {
+  registry, shouldEnroll, captureRepo, repoStates, identityAt, seeded, relativePath,
+}) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name));
+  } catch (error) {
+    // Structural registration names every readable child. An unreadable
+    // directory is not proof that it is empty; leave its already-created
+    // folder record childless and let Detect retry when ground settles.
+    if (error.code === 'EACCES' || error.code === 'EPERM') return;
+    throw error;
+  }
+
+  for (const entry of entries) {
+    const entryPath = path.join(dirPath, entry.name);
+    const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+    if (!shouldEnroll(entryPath)) continue;
+    const stat = fs.lstatSync(entryPath);
+
+    if (stat.isSymbolicLink()) {
+      const identity = seeded(entryRelativePath, {
+        type: 'link', parentUUID, name: entry.name, root: false,
+      });
+      registry.create({ type: identity.type, parentUUID, name: entry.name, uuid: identity.uuid });
+      continue;
+    }
+    if (stat.isDirectory()) {
+      const type = isRepository(entryPath) ? 'repo.git' : 'folder';
+      const state = type === 'repo.git' ? captureInitialRepo(entryPath, captureRepo) : null;
+      const identity = seeded(entryRelativePath, {
+        type, parentUUID, name: entry.name, root: false,
+      });
+      const record = registry.create({
+        type: identity.type,
+        parentUUID,
+        name: entry.name,
+        payloadVersion: state?.stateId ?? null,
+        uuid: identity.uuid,
+      });
+      if (state) repoStates.put(record.uuid, state);
+      registerDirectory(entryPath, record.uuid, {
+        registry, shouldEnroll, captureRepo, repoStates, identityAt, seeded, relativePath: entryRelativePath,
+      });
+      continue;
+    }
+    if (stat.isFile()) {
+      const identity = seeded(entryRelativePath, {
+        type: 'file.text', parentUUID, name: entry.name, root: false,
+      });
+      registry.create({ type: identity.type, parentUUID, name: entry.name, uuid: identity.uuid });
+    }
+  }
+}
+
+module.exports = { registerTree };