amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * A REFUSAL: the boundary understood the request and declined it.
+ *
+ * Two things can go wrong when a caller asks for something, and they
+ * mean opposite things:
+ *
+ *   a refusal   the request named ground amalgm will not take — excluded
+ *               by enrollment policy, already owned by another tree, not
+ *               there at all. Nothing is broken. The message IS the
+ *               reason and is meant to be shown to whoever asked.
+ *   a fault     the boundary could not do its job — a torn identity
+ *               store, an unusable database, a bug. The request was
+ *               fine; the installation is not.
+ *
+ * A refusal is NAMED WHERE IT IS RAISED, by the code that decided to
+ * refuse. It is never guessed later from an error's wording: matching on
+ * message text would quietly reclassify every fault as the caller's
+ * mistake the moment a message changed, and "your path is bad" is the
+ * worst possible thing to say on the day the identity store tears.
+ *
+ * Callers that must answer differently — an HTTP status, an exit code —
+ * ask `isRefusal`. Everything else stays an ordinary Error and travels
+ * to whatever handles faults.
+ */
+
+const REFUSAL = Symbol.for('amalgm.registration.refusal');
+
+/** Decline a request, with the reason the caller should be shown. */
+function refusal(message) {
+  const error = new Error(message);
+  error[REFUSAL] = true;
+  return error;
+}
+
+/** True only for an error this boundary deliberately raised as a refusal. */
+function isRefusal(error) {
+  return Boolean(error && error[REFUSAL]);
+}
+
+module.exports = { refusal, isRefusal };

package/runtime/scripts/amalgm-mcp/registration/repo-followers.js

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * The repository half of the registration boundary.
+ *
+ * Purpose: one `repo.git` entity travels as one Repocard state. The
+ * filesystem observer supplies noisy "something changed" doorbells; the
+ * Repocard follower turns them into settled Card + Checkpoint facts, and the
+ * registry records their stateId on the repo's existing UUID, then the
+ * settled state authorizes one child-tree reconciliation.
+ *
+ * Axioms:
+ *   1. One live repository observer root owns one follower.
+ *   2. Only a follower may turn `repo.changed` into a repo state update.
+ *   3. A settled state updates the existing repo UUID and is the only
+ *      authority that may reconcile its registered worktree children.
+ *   4. A follower resumes from registration's persisted Card + Checkpoint;
+ *      a restart never invents a second initial state.
+ *
+ * Card and checkpoint documents are the future Send rail's cargo. Local
+ * Record persists the complete bundle-free document now; the entity row
+ * carries its stateId, exactly as every other entity records its payload
+ * fingerprint.
+ */
+
+const { createFollower, createCaptureWorker } = require('../repocard');
+
+function createRepoFollowers({ observer, registry, repoStates, recordForRoot, onSettled }) {
+  if (!observer || !registry || !repoStates || typeof recordForRoot !== 'function'
+    || typeof onSettled !== 'function') {
+    throw new Error('createRepoFollowers requires { observer, registry, repoStates, recordForRoot, onSettled }');
+  }
+
+  const worker = createCaptureWorker();
+  const followers = new Map(); // observer rootId -> { path, uuid, follower }
+  let stopped = false;
+
+  function close(rootId) {
+    const entry = followers.get(rootId);
+    if (!entry) return;
+    entry.follower.close();
+    followers.delete(rootId);
+  }
+
+  /**
+   * Align followers with the observer's currently live repo roots. A root can
+   * move, be adopted, or cease being a repository; in every case the old
+   * follower is closed before a replacement can speak.
+   */
+  function sync() {
+    if (stopped) return;
+    const roots = observer.listRoots().filter((root) => root.kind === 'repo');
+    const live = new Set(roots.map((root) => root.rootId));
+    for (const rootId of [...followers.keys()]) {
+      if (!live.has(rootId)) close(rootId);
+    }
+
+    for (const root of roots) {
+      const record = recordForRoot(root);
+      if (!record || record.type !== 'repo.git') {
+        // A territory can appear before its enclosing lens has registered the
+        // boundary. `sync()` runs again after that lens reconciles.
+        close(root.rootId);
+        continue;
+      }
+      const existing = followers.get(root.rootId);
+      if (existing && existing.path === root.path && existing.uuid === record.uuid) continue;
+      close(root.rootId);
+      const baseline = repoStates.get(record.uuid);
+
+      const follower = createFollower({
+        repoPath: root.path,
+        last: baseline && { cardId: baseline.cardId, checkpointId: baseline.checkpointId },
+        captureFn: (repoPath) => worker.capture(repoPath, { withBundle: false }),
+        emit: (next) => {
+          // ONE settled Card + Checkpoint state is ONE registry transition on
+          // the repo entity. Raw filesystem events never write Git state.
+          const previous = repoStates.get(record.uuid);
+          registry.transaction(() => {
+            repoStates.put(record.uuid, next);
+            registry.attest(record.uuid, { type: 'repo.git', payloadVersion: next.stateId });
+          });
+          // The normal structural comparer may now inspect the worktree.
+          // It never runs from a raw doorbell, only this settled state.
+          onSettled({ root, record, previous, state: next });
+        },
+      });
+      followers.set(root.rootId, { path: root.path, uuid: record.uuid, follower });
+      // Birth captures the initial Card + Checkpoint. The follower owns its
+      // retry policy; registration must not invent an alternate Git scanner.
+      void follower.start();
+    }
+  }
+
+  /** Route exactly the observer's repo lifecycle signals into its follower. */
+  function onObserverEvent(event) {
+    if (stopped) return;
+    if (event.type === 'repo.removed') {
+      // A territory that ceased to be Git cannot keep a capture loop alive
+      // over an ordinary folder (or a vanished address).
+      close(event.rootId);
+      return;
+    }
+    if (event.type === 'root.moved') {
+      // The follower's capture path is its repo root's address. Rebind it
+      // before an old in-flight capture can mistake a normal move for a Git
+      // failure; `sync()` closes the old follower and starts one at the new
+      // address on the same repo UUID.
+      sync();
+      return;
+    }
+    if (event.type === 'repo.changed') followers.get(event.rootId)?.follower.ring();
+  }
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    for (const rootId of [...followers.keys()]) close(rootId);
+    // `close()` rejects any in-flight worker capture. Followers are closed
+    // first, so no rejected capture can schedule another retry.
+    void worker.close();
+  }
+
+  return { sync, onObserverEvent, stop };
+}
+
+module.exports = { createRepoFollowers };

package/runtime/scripts/amalgm-mcp/registration/repo-states.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * The durable current state of each registered Git repository.
+ *
+ * Purpose: a `repo.git` entity needs a complete Card + Checkpoint baseline
+ * before Watch begins. The identity registry owns the UUID and stateId;
+ * this module keeps the exact bundle-free documents that stateId names so a
+ * follower can resume after a restart and reconciliation can compare a new
+ * settled state with the state registration actually recorded.
+ *
+ * Axioms:
+ *   1. One active repo UUID has at most one current Card + Checkpoint state.
+ *   2. The state document and the entity's stateId commit in the same
+ *      identity-database transaction.
+ *   3. Detect stores bundle-free state. Send constructs a transport bundle
+ *      later; Detect never pays transport's cost.
+ */
+
+function encodeBytes(bytes) {
+  return Buffer.from(bytes || []).toString('base64');
+}
+
+function decodeBytes(encoded) {
+  return Buffer.from(encoded || '', 'base64');
+}
+
+function pack(state) {
+  return JSON.stringify({
+    stateId: state.stateId,
+    cardId: state.cardId,
+    checkpointId: state.checkpointId,
+    card: {
+      ...state.card,
+      bundle: state.card.bundle && {
+        ...state.card.bundle,
+        bytes: encodeBytes(state.card.bundle.bytes),
+      },
+    },
+    checkpoint: {
+      ...state.checkpoint,
+      stagedPatch: encodeBytes(state.checkpoint.stagedPatch),
+      unstagedPatch: encodeBytes(state.checkpoint.unstagedPatch),
+      untracked: state.checkpoint.untracked.map((file) => ({
+        ...file,
+        content: encodeBytes(file.content),
+      })),
+    },
+  });
+}
+
+function unpack(text) {
+  const state = JSON.parse(text);
+  return {
+    ...state,
+    card: {
+      ...state.card,
+      bundle: state.card.bundle && {
+        ...state.card.bundle,
+        bytes: decodeBytes(state.card.bundle.bytes),
+      },
+    },
+    checkpoint: {
+      ...state.checkpoint,
+      stagedPatch: decodeBytes(state.checkpoint.stagedPatch),
+      unstagedPatch: decodeBytes(state.checkpoint.unstagedPatch),
+      untracked: state.checkpoint.untracked.map((file) => ({
+        ...file,
+        content: decodeBytes(file.content),
+      })),
+    },
+  };
+}
+
+function createRepoStates(db) {
+  if (!db) throw new Error('createRepoStates requires the identity database');
+  const read = db.prepare('SELECT state_json FROM repo_states WHERE entity_uuid = ?');
+  const write = db.prepare(`
+    INSERT INTO repo_states (entity_uuid, state_id, card_id, checkpoint_id, state_json)
+    VALUES (@entityUuid, @stateId, @cardId, @checkpointId, @stateJson)
+    ON CONFLICT(entity_uuid) DO UPDATE SET
+      state_id = excluded.state_id,
+      card_id = excluded.card_id,
+      checkpoint_id = excluded.checkpoint_id,
+      state_json = excluded.state_json
+  `);
+
+  return {
+    get(entityUuid) {
+      const row = read.get(entityUuid);
+      return row ? unpack(row.state_json) : null;
+    },
+    put(entityUuid, state) {
+      if (!entityUuid || !state?.stateId || !state?.cardId || !state?.checkpointId) {
+        throw new Error('a repo state needs entityUuid, stateId, cardId, and checkpointId');
+      }
+      write.run({
+        entityUuid,
+        stateId: state.stateId,
+        cardId: state.cardId,
+        checkpointId: state.checkpointId,
+        stateJson: pack(state),
+      });
+      return state;
+    },
+  };
+}
+
+module.exports = { createRepoStates };

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

@@ -0,0 +1,310 @@
+'use strict';
+
+/**
+ * The installation's ONE live registration boundary — the production
+ * composition root for the realtime rails that exist today:
+ *
+ *   Watch    the observer's doorbells, armed by start()
+ *   Detect   the observer's scans, published as events
+ *   Record   registration.onEvent → the evidence lenses → the registry
+ *
+ * This file's only job is COMPOSITION AND LIFETIME: which policies are
+ * injected, where the two databases live, how the observer's events
+ * reach the boundary, and how all of it is given back. It contains no
+ * detection logic and no laws — those are `observer/`, `registry/`, and
+ * `registration/index.js`. Nothing is built until something asks: the
+ * runtime pays nothing for this until a caller registers ground, which
+ * is what keeps the cutover shadow-only.
+ *
+ * Because this root OPENS the handles, this root CLOSES them: `close()`
+ * is the exact inverse of construction, and it is complete or it is a
+ * leak wearing a shutdown's name.
+ *
+ * TWO DATABASES, one directory, because they answer different questions
+ * and fail independently: `observer.db` holds EVIDENCE (what disk looks
+ * like right now, rebuildable by rescanning), `identity.db` holds
+ * IDENTITY (permanent UUIDs, never rebuildable) guarded by its epoch
+ * sentinel — if identity is lost while the sentinel survives, the
+ * registry refuses to mint replacement identities rather than quietly
+ * re-inventing everyone.
+ *
+ * The event wire is the Detect → Record rail and is NOT optional: the
+ * observer publishes into the boundary, which reconciles its lenses.
+ * The boundary's OWN events (`entity.committed` and kin) are discarded
+ * here on purpose — fanning them out to the app, the cloud, or the
+ * legacy consumers is the next cutover slice, and a shadow that
+ * publishes is not a shadow. User-home bootstrap is intentionally not
+ * another registrar: it calls this boundary's registration operation once for
+ * every declared safe root (docs/user-cloud-bootstrap.md).
+ */
+
+const path = require('path');
+
+const Database = require('better-sqlite3');
+
+const { STORAGE_DIR } = require('../config');
+const { ensureDir } = require('../lib/storage');
+const { ensureUserHome } = require('../lib/layout');
+const { createObserver } = require('../observer');
+const { shouldEnroll } = require('../workspace/tree/inclusion');
+const { classifyFile } = require('./classify');
+const { createEntityCloud } = require('./entity-cloud');
+const { createEntityContent } = require('./entity-content');
+const { createRegistration } = require('./index');
+const { machineId, userId } = require('../workspace/identity');
+
+const ENTITIES_DIR = path.join(STORAGE_DIR, 'entities');
+const USER_HOME_CLOUD_CONTRACT = 'amalgm-user-home@1';
+const USER_HOME_CLOUD_SCHEMA_VERSION = 1;
+
+let live = null;
+
+/**
+ * Build the whole stack over one directory. Exported for tests, which
+ * pass a temporary directory; production always uses the singleton
+ * below, so an installation can never hold two boundaries over one
+ * identity database.
+ */
+function createRegistrationService({
+  dir = ENTITIES_DIR,
+  homeDir = STORAGE_DIR,
+  // Tests may supply a signed-in identity without mutating process-global
+  // runtime configuration. Production uses the enrolled computer record.
+  cloudUserId = userId(),
+  cloudDeviceId = machineId(),
+} = {}) {
+  ensureDir(dir);
+
+  const evidenceDb = new Database(path.join(dir, 'observer.db'));
+  const identityDb = new Database(path.join(dir, 'identity.db'));
+  const entityContent = createEntityContent({ dir });
+  const entityCloud = createEntityCloud({
+    db: identityDb,
+    userId: cloudUserId,
+    deviceId: cloudDeviceId,
+    content: entityContent,
+  });
+
+  // The observer emits before the boundary exists (its constructor
+  // scans), so the wire reads through a box that the boundary fills.
+  const boundary = { current: null };
+  const observer = createObserver({
+    db: evidenceDb,
+    emit: (event) => boundary.current?.onEvent(event),
+    shouldEnroll,
+    captureContent: entityContent.captureFile,
+  });
+
+  boundary.current = createRegistration({
+    observer,
+    openIdentity: () => ({
+      db: identityDb,
+      sentinelPath: path.join(dir, 'identity.epoch'),
+      journal: entityCloud.journal,
+    }),
+    classify: classifyFile,
+  });
+
+  let closed = false;
+
+  const publicRecord = (record) => ({
+    uuid: record.uuid,
+    type: record.type,
+    parentUUID: record.parentUUID,
+    name: record.name,
+    version: record.version,
+    status: record.status,
+  });
+
+  function identitySeeds(snapshot, declaration) {
+    if (snapshot === null || snapshot === undefined) return null;
+    if (!snapshot || snapshot.schemaVersion !== USER_HOME_CLOUD_SCHEMA_VERSION
+      || snapshot.kind !== 'amalgm-user-home'
+      || !Array.isArray(snapshot.roots) || !Array.isArray(snapshot.exactManaged)) {
+      throw new Error('cloud user-home snapshot has an unsupported shape');
+    }
+
+    const rootEntries = new Map(snapshot.roots.map((entry) => [entry?.key, entry]));
+    const exactEntries = new Map(snapshot.exactManaged.map((entry) => [entry?.key, entry]));
+    if (rootEntries.size !== declaration.roots.length || exactEntries.size !== declaration.exactManaged.length) {
+      throw new Error('cloud user-home snapshot does not declare this user-home schema');
+    }
+
+    const roots = new Map();
+    for (const root of declaration.roots) {
+      const entry = rootEntries.get(root.key);
+      const record = entry?.record;
+      if (!entry || !record || record.parentUUID !== null || record.name !== path.basename(root.path)
+        || record.status !== 'active') {
+        throw new Error(`cloud user-home root ${root.key} is invalid`);
+      }
+      roots.set(root.key, record);
+    }
+
+    const managed = new Map();
+    for (const target of declaration.exactManaged) {
+      const entry = exactEntries.get(target.key);
+      const record = entry?.record;
+      const root = roots.get(target.rootKey);
+      const isRoot = target.relativePath === target.rootKey;
+      const parentUUID = isRoot ? null : root?.uuid;
+      if (!entry || entry.scope !== 'exact' || entry.relativePath !== target.relativePath
+        || !record || !root || record.parentUUID !== parentUUID
+        || record.name !== path.basename(target.relativePath)
+        || record.status !== 'active'
+        || (isRoot && record.uuid !== root.uuid)) {
+        throw new Error(`cloud user-home managed target ${target.key} is invalid`);
+      }
+      managed.set(target.key, record);
+    }
+
+    return {
+      forRoot(key) {
+        return (relativePath) => {
+          if (relativePath === '') return roots.get(key) || null;
+          const target = declaration.exactManaged.find((entry) => (
+            entry.rootKey === key
+            && entry.relativePath.startsWith(`${key}/`)
+            && entry.relativePath.slice(key.length + 1) === relativePath
+          ));
+          return target ? managed.get(target.key) || null : null;
+        };
+      },
+      root: (key) => roots.get(key),
+      managed: (key) => managed.get(key),
+    };
+  }
+
+  /**
+   * Bootstrap a logged-in person's declared Amalgm home through the SAME
+   * operation as `amalgm register`. `ensureUserHome` only creates the safe shape;
+   * this function is the sole point that assigns UUIDs and begins Watch.
+   *
+   * The result deliberately exposes the exact platform-managed UUIDs rather
+   * than inferring authority from `system/`. The gateway will persist those
+   * exact facts beside ordinary inheriting human permissions in the Send
+   * slice. Until then this operation is local identity + watch only.
+   */
+  async function bootstrapUserHome({ identitySnapshot = null } = {}) {
+    const declaration = ensureUserHome(homeDir);
+    const seeds = identitySeeds(identitySnapshot, declaration);
+    const roots = [];
+    const addedRoots = boundary.current.addMany(declaration.roots.map((entry) => ({
+      targetPath: entry.path,
+      identityAt: seeds?.forRoot(entry.key) ?? null,
+    })));
+    for (let index = 0; index < declaration.roots.length; index += 1) {
+      const entry = declaration.roots[index];
+      const added = addedRoots[index];
+      if (seeds && added.record.uuid !== seeds.root(entry.key).uuid) {
+        throw new Error(`local user-home root ${entry.key} does not match its cloud UUID`);
+      }
+      roots.push({
+        key: entry.key,
+        path: added.rootPath,
+        record: added.record,
+      });
+    }
+
+    const system = roots.find((entry) => entry.key === 'system');
+    if (!system) throw new Error('declared user home has no system root');
+    const tree = boundary.current.tree(system.path);
+    if (!tree?.root()) throw new Error(`declared system root was not registered: ${system.path}`);
+
+    const recordAt = (relativePath) => {
+      let record = tree.root();
+      for (const name of relativePath.split('/')) {
+        record = tree.registry.activeAt(record.uuid, name);
+        if (!record) throw new Error(`declared user-home target was not registered: ${relativePath}`);
+      }
+      return record;
+    };
+
+    const exactManaged = declaration.exactManaged.map((entry) => {
+      const root = roots.find((candidate) => candidate.key === entry.rootKey);
+      const isRoot = entry.relativePath === entry.rootKey;
+      const relativePath = isRoot ? '' : entry.relativePath.slice(entry.rootKey.length + 1);
+      const record = isRoot ? root?.record : recordAt(relativePath);
+      if (!record) throw new Error(`declared user-home managed target was not registered: ${entry.relativePath}`);
+      if (seeds && record.uuid !== seeds.managed(entry.key).uuid) {
+        throw new Error(`local user-home managed target ${entry.key} does not match its cloud UUID`);
+      }
+      return {
+        key: entry.key,
+        rootKey: entry.rootKey,
+        relativePath: entry.relativePath,
+        path: entry.path,
+        scope: entry.scope,
+        record,
+      };
+    });
+
+    const cloudSnapshot = {
+      schemaVersion: USER_HOME_CLOUD_SCHEMA_VERSION,
+      kind: 'amalgm-user-home',
+      roots: roots.map(({ key, record }) => ({ key, record: publicRecord(record) })),
+      exactManaged: exactManaged.map(({ key, relativePath, scope, record }) => ({
+        key, relativePath, scope, record: publicRecord(record),
+      })),
+    };
+
+    return {
+      schemaVersion: declaration.schemaVersion,
+      homeDir: declaration.userDir,
+      roots,
+      exactManaged,
+      cloudSnapshot,
+    };
+  }
+
+  return {
+    dir,
+    homeDir,
+    observer,
+    registration: boundary.current,
+    /** `amalgm register <path>` — register, then begin Watch + Detect. */
+    register: async (targetPath) => {
+      entityCloud.assertRegistrationReady();
+      return boundary.current.add(targetPath);
+    },
+    /** `amalgm register <path>...` — the same primitive for each selected root. */
+    registerMany: async (targetPaths) => {
+      entityCloud.assertRegistrationReady();
+      return boundary.current.addMany(targetPaths);
+    },
+    bootstrapUserHome,
+    entityCloud,
+    entityContent,
+    /**
+     * Give back everything this root took, in the order it took it:
+     * watchers and their timers first (the observer's own `stop`), then
+     * the two databases. Whoever opens a handle closes it — a stack that
+     * only stops watching is still holding the files it opened, which is
+     * why a "restart" over a half-closed service is two live stacks over
+     * one database rather than the fresh process it claims to be.
+     * Idempotent: shutdown is often reached from more than one direction.
+     */
+    close() {
+      if (closed) return;
+      closed = true;
+      observer.stop();       // doorbells and their timers
+      boundary.current.stop(); // and the pass they may already have scheduled
+      evidenceDb.close();
+      identityDb.close();
+    },
+  };
+}
+
+/** The installation's one boundary, built on first use. */
+function registrationService() {
+  if (!live) live = createRegistrationService();
+  return live;
+}
+
+module.exports = {
+  ENTITIES_DIR,
+  USER_HOME_CLOUD_CONTRACT,
+  USER_HOME_CLOUD_SCHEMA_VERSION,
+  createRegistrationService,
+  registrationService,
+};