amalgm 0.1.238 → 0.1.240

package/runtime/scripts/amalgm-mcp/workspace/intent.js

@@ -0,0 +1,535 @@
+'use strict';
+
+/**
+ * Durable local authorship for one registered code folder.
+ *
+ * The official stream still has only two values: card and checkpoint. This
+ * file is not shared state. It records the exact local state a real file/Git
+ * observation saw, relative to the last verified official state on this
+ * machine. The reducer may preserve only this record; a physical mismatch by
+ * itself never creates authorship.
+ *
+ * Axiom 4: a reserved predecessor is immutable and later work occupies one
+ * successor pinned to its exact content. Proven by workspace-local-intent.test.js.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { AMALGM_DIR } = require('../config');
+const durable = require('./durable');
+const provenance = require('./provenance');
+
+const INTENT_CONTRACT = 'repo-local-intent@4';
+const LEGACY_INTENT_CONTRACTS = new Set([
+  'repo-local-intent@2',
+  'repo-local-intent@3',
+]);
+const SUCCESSOR_CONTRACT = 'repo-local-intent-successor@2';
+const LEGACY_SUCCESSOR_CONTRACT = 'repo-local-intent-successor@1';
+const INTENT_DIR = path.join(AMALGM_DIR, 'state', 'repo-local-intent');
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const MUTATION_ID = /^[A-Za-z0-9_-]{16,160}$/;
+
+function newMutationId() {
+  return `mut_${crypto.randomBytes(18).toString('base64url')}`;
+}
+
+function intentFile(resourceId) {
+  const digest = crypto.createHash('sha256').update(resourceId).digest('hex').slice(0, 24);
+  return path.join(INTENT_DIR, `${digest}.json`);
+}
+
+function canonicalPath(localPath) {
+  const resolved = path.resolve(localPath);
+  const tail = [];
+  let existing = resolved;
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) return resolved;
+    tail.unshift(path.basename(existing));
+    existing = parent;
+  }
+  return path.join(fs.realpathSync.native(existing), ...tail);
+}
+
+function branchState(branches) {
+  return (branches || [])
+    .map((branch) => ({ name: branch.name, oid: branch.oid ?? null }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function cardState(card) {
+  return {
+    head: {
+      branch: card?.head?.branch ?? null,
+      oid: card?.head?.oid ?? null,
+      detached: Boolean(card?.head?.detached),
+    },
+    branches: branchState(card?.branches || card?.refs),
+  };
+}
+
+function semanticState(value) {
+  return {
+    card: cardState(value?.local?.card),
+    checkpoint: {
+      baseOid: value?.local?.checkpoint?.baseOid ?? null,
+      branch: value?.local?.checkpoint?.branch ?? null,
+      revision: value?.local?.checkpoint?.value?.revision ?? null,
+    },
+  };
+}
+
+function semanticDigest(value) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify(semanticState(value)))
+    .digest('hex');
+}
+
+function validTree(value) {
+  return SHA.test(String(value || ''));
+}
+
+function validInitialBase(base) {
+  return Boolean(
+    base?.through === 0
+    && base.card === null
+    && validTree(base.indexTree)
+    && base.indexTree === base.worktreeTree
+  );
+}
+
+function validLocal(local) {
+  return Boolean(
+    validTree(local?.card?.head?.oid)
+    && Array.isArray(local?.card?.branches)
+    && validTree(local?.indexTree)
+    && validTree(local?.worktreeTree)
+    && local?.checkpoint?.baseOid === local.card.head.oid
+    && typeof local?.physicalDigest === 'string'
+  );
+}
+
+function sameCard(left, right) {
+  return JSON.stringify(cardState(left)) === JSON.stringify(cardState(right));
+}
+
+function validSuccessor(value, predecessor) {
+  const currentContract = value?.contract === SUCCESSOR_CONTRACT;
+  const legacyContract = value?.contract === LEGACY_SUCCESSOR_CONTRACT;
+  return Boolean(
+    value
+    && (currentContract || legacyContract)
+    && (!currentContract || MUTATION_ID.test(value.birthMutationId))
+    && value.predecessorSemanticDigest === predecessor.semanticDigest
+    && value.base?.semanticDigest === predecessor.semanticDigest
+    && sameCard(value.base?.card, predecessor.local.card)
+    && value.base?.indexTree === predecessor.local.indexTree
+    && value.base?.worktreeTree === predecessor.local.worktreeTree
+    && value.base?.physicalDigest === predecessor.local.physicalDigest
+    && validLocal(value.local)
+    && value.semanticDigest === semanticDigest(value)
+    && typeof value.capturedAt === 'string'
+  );
+}
+
+function validIntent(value, project) {
+  const initial = validInitialBase(value?.base);
+  const currentContract = value?.contract === INTENT_CONTRACT;
+  const legacyContract = LEGACY_INTENT_CONTRACTS.has(value?.contract)
+    && (
+      value.contract !== 'repo-local-intent@2'
+      || value.successor === undefined
+      || value.successor === null
+    );
+  return Boolean(
+    value
+    && (currentContract || legacyContract)
+    && (!currentContract || MUTATION_ID.test(value.birthMutationId))
+    && value.resourceId === project.resourceId
+    && value.ownerUserId === project.ownerUserId
+    && canonicalPath(value.path) === canonicalPath(project.path)
+    && Number.isInteger(value.base?.through)
+    && value.base.through >= 0
+    && (
+      initial
+      || (
+        validTree(value.base?.card?.head?.oid)
+        && Array.isArray(value.base?.card?.branches)
+        && validTree(value.base?.indexTree)
+        && validTree(value.base?.worktreeTree)
+      )
+    )
+    && validLocal(value.local)
+    && value.semanticDigest === semanticDigest(value)
+    && (
+      value.successor === undefined
+      || value.successor === null
+      || validSuccessor(value.successor, value)
+    )
+    && (
+      value.publication === null
+      || (
+        typeof value.publication?.mutationId === 'string'
+        && (
+          !currentContract
+          || value.publication.mutationId === value.birthMutationId
+        )
+        && value.publication.semanticDigest === value.semanticDigest
+        && value.publication.baseThrough === value.base.through
+        && (
+          (
+            value.publication.numberedVersion === null
+            && value.publication.numberedAt === null
+            && value.publication.foldedAt === null
+          )
+          || (
+            Number.isInteger(value.publication.numberedVersion)
+            && value.publication.numberedVersion > 0
+            && typeof value.publication.numberedAt === 'string'
+            && (
+              value.publication.foldedAt === null
+              || typeof value.publication.foldedAt === 'string'
+            )
+          )
+        )
+      )
+    )
+  );
+}
+
+function persistIntent(project, value) {
+  if (!validIntent(value, project)) throw new Error('local code intent is invalid');
+  durable.writeJson(intentFile(project.resourceId), value, { pretty: true });
+  return value;
+}
+
+function readIntent(project) {
+  if (!project?.resourceId || !project?.path || !project?.ownerUserId) return null;
+  const file = intentFile(project.resourceId);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw new Error(`cannot read local code intent ${file}`, { cause: error });
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`local code intent ${file} is not valid JSON`, { cause: error });
+  }
+  if (!validIntent(value, project)) {
+    throw new Error(`local code intent ${file} has an invalid or unsupported contract`);
+  }
+  return value;
+}
+
+function writeIntent(project, input) {
+  const held = readIntent(project);
+  const nextSemanticDigest = semanticDigest({ local: input.local });
+  const samePredecessor = held
+    && held.semanticDigest === nextSemanticDigest
+    && JSON.stringify(held.base) === JSON.stringify(input.base);
+  let birthMutationId = MUTATION_ID.test(String(input.birthMutationId || ''))
+    ? input.birthMutationId
+    : null;
+  if (
+    !birthMutationId
+    && (
+      input.preserveBirthMutationId === true
+      || samePredecessor
+    )
+    && MUTATION_ID.test(String(held?.birthMutationId || ''))
+  ) birthMutationId = held.birthMutationId;
+  if (
+    !birthMutationId
+    && MUTATION_ID.test(String(input.publication?.mutationId || ''))
+  ) birthMutationId = input.publication.mutationId;
+  if (!birthMutationId) birthMutationId = newMutationId();
+  const next = {
+    contract: INTENT_CONTRACT,
+    birthMutationId,
+    resourceId: project.resourceId,
+    ownerUserId: project.ownerUserId,
+    path: canonicalPath(project.path),
+    base: input.base,
+    local: input.local,
+    publication: input.publication || null,
+    terminal: input.terminal || null,
+    capturedAt: new Date().toISOString(),
+  };
+  next.semanticDigest = nextSemanticDigest;
+  next.successor = input.successor === undefined && samePredecessor
+    ? held.successor || null
+    : input.successor || null;
+  return persistIntent(project, next);
+}
+
+/**
+ * Freeze the published intent and atomically replace only its open successor.
+ *
+ * A successor is a final desk state, not an edit log. Its base is the exact
+ * content identity of the frozen predecessor, so repeated saves coalesce
+ * without ever changing the bytes or publication identity already in flight.
+ */
+function writeSuccessor(project, predecessor, input) {
+  let held = readIntent(project);
+  if (!held || held.semanticDigest !== predecessor?.semanticDigest) return null;
+  if (
+    held.contract !== INTENT_CONTRACT
+    || !MUTATION_ID.test(String(held.birthMutationId || ''))
+  ) {
+    held = writeIntent(project, {
+      base: held.base,
+      local: held.local,
+      terminal: held.terminal,
+      successor: held.successor,
+      publication: held.publication,
+    });
+  }
+  const prior = held.successor || null;
+  const successor = {
+    contract: SUCCESSOR_CONTRACT,
+    birthMutationId: null,
+    predecessorSemanticDigest: held.semanticDigest,
+    base: {
+      semanticDigest: held.semanticDigest,
+      card: held.local.card,
+      indexTree: held.local.indexTree,
+      worktreeTree: held.local.worktreeTree,
+      physicalDigest: held.local.physicalDigest,
+    },
+    local: input.local,
+    terminal: input.terminal || null,
+    capturedAt: new Date().toISOString(),
+  };
+  successor.semanticDigest = semanticDigest(successor);
+  successor.birthMutationId = (
+    prior?.semanticDigest === successor.semanticDigest
+    && MUTATION_ID.test(String(prior.birthMutationId || ''))
+  ) ? prior.birthMutationId : newMutationId();
+  persistIntent(project, { ...held, contract: INTENT_CONTRACT, successor });
+  return successor;
+}
+
+function readSuccessor(project) {
+  return readIntent(project)?.successor || null;
+}
+
+function clearSuccessor(project, predecessor = null) {
+  let held = readIntent(project);
+  if (
+    !held?.successor
+    || (
+      predecessor
+      && held.semanticDigest !== predecessor.semanticDigest
+    )
+  ) return false;
+  if (
+    held.contract !== INTENT_CONTRACT
+    || !MUTATION_ID.test(String(held.birthMutationId || ''))
+  ) {
+    held = writeIntent(project, {
+      base: held.base,
+      local: held.local,
+      terminal: held.terminal,
+      successor: held.successor,
+      publication: held.publication,
+    });
+  }
+  persistIntent(project, { ...held, contract: INTENT_CONTRACT, successor: null });
+  return true;
+}
+
+function clearIntent(project) {
+  if (!project?.resourceId) return false;
+  const file = intentFile(project.resourceId);
+  if (!fs.existsSync(file)) return false;
+  fs.rmSync(file, { force: true });
+  return true;
+}
+
+function stampPublication(project, intent, mutationId) {
+  const held = readIntent(project);
+  if (
+    !held
+    || held.semanticDigest !== intent?.semanticDigest
+    || mutationId !== held.birthMutationId
+  ) return null;
+  return writeIntent(project, {
+    birthMutationId: held.birthMutationId,
+    base: held.base,
+    local: held.local,
+    terminal: held.terminal,
+    publication: {
+      mutationId,
+      semanticDigest: held.semanticDigest,
+      baseThrough: held.base.through,
+      numberedVersion: null,
+      numberedAt: null,
+      foldedAt: null,
+    },
+  });
+}
+
+function reservePublication(project, intent) {
+  let held = readIntent(project);
+  if (!held || held.semanticDigest !== intent?.semanticDigest) return null;
+  if (!MUTATION_ID.test(String(held.birthMutationId || ''))) {
+    held = writeIntent(project, {
+      base: held.base,
+      local: held.local,
+      terminal: held.terminal,
+      successor: held.successor,
+      publication: held.publication,
+    });
+  }
+  if (
+    held.publication
+    && held.publication.semanticDigest === held.semanticDigest
+    && held.publication.baseThrough === held.base.through
+    && held.publication.numberedVersion === null
+  ) return held;
+  provenance.requireTransition(
+    provenance.publicationState(held.publication),
+    provenance.ACTION.RESERVE,
+    provenance.STATE.RESERVED,
+    ['intent-record', 'publication-id'],
+  );
+  return stampPublication(
+    project,
+    held,
+    held.birthMutationId,
+  );
+}
+
+function markPublicationNumbered(project, mutationId, version, numberedAt = null) {
+  const held = readIntent(project);
+  if (!held || held.publication?.mutationId !== mutationId) return null;
+  if (!Number.isInteger(version) || version < 1) {
+    throw new Error('numbered publication version is invalid');
+  }
+  if (
+    held.publication.numberedVersion !== null
+    && held.publication.numberedVersion !== version
+  ) throw new Error('publication received a different official number');
+  if (held.publication.numberedVersion === version) return held;
+  provenance.requireTransition(
+    provenance.publicationState(held.publication),
+    provenance.ACTION.NUMBER,
+    provenance.STATE.NUMBERED,
+    ['publication-id', 'official-version', 'server-receipt'],
+  );
+  return writeIntent(project, {
+    base: held.base,
+    local: held.local,
+    terminal: held.terminal,
+    publication: {
+      ...held.publication,
+      numberedVersion: version,
+      numberedAt: numberedAt || new Date().toISOString(),
+    },
+  });
+}
+
+function markPublicationFolded(project, mutationId, version, numberedAt = null) {
+  const numbered = markPublicationNumbered(project, mutationId, version, numberedAt);
+  if (!numbered || numbered.publication.foldedAt !== null) return numbered;
+  provenance.requireTransition(
+    provenance.publicationState(numbered.publication),
+    provenance.ACTION.FOLD,
+    provenance.STATE.FOLDED,
+    ['predecessor-folded', 'official-event', 'official-snapshot'],
+  );
+  return writeIntent(project, {
+    base: numbered.base,
+    local: numbered.local,
+    terminal: numbered.terminal,
+    publication: {
+      ...numbered.publication,
+      foldedAt: new Date().toISOString(),
+    },
+  });
+}
+
+function officialAcknowledgement(project, intent) {
+  if (!intent?.publication?.mutationId) return null;
+  if (
+    Number.isInteger(intent.publication.numberedVersion)
+    && intent.publication.numberedVersion > 0
+    && typeof intent.publication.numberedAt === 'string'
+  ) {
+    return {
+      mutationId: intent.publication.mutationId,
+      version: intent.publication.numberedVersion,
+    };
+  }
+  const row = require('../state/mutations').getMutation(
+    `resource:${project.resourceId}`,
+    intent.publication.mutationId,
+    { revealOperation: true },
+  );
+  return (
+    row
+    && row.state === 'synced'
+    && Number.isInteger(row.officialCloudVersion)
+    && row.officialCloudVersion > 0
+    && intent.publication.semanticDigest === intent.semanticDigest
+  ) ? {
+    mutationId: row.mutationId,
+    version: row.officialCloudVersion,
+  } : null;
+}
+
+function publicationMayRebase(project, intent, through) {
+  if (
+    !intent?.publication?.mutationId
+    || intent.publication.numberedVersion !== null
+    || !Number.isInteger(through)
+    || through <= intent.base.through
+  ) return false;
+  const row = require('../state/mutations').getMutation(
+    `resource:${project.resourceId}`,
+    intent.publication.mutationId,
+  );
+  return !row || (
+    row.state === 'rejected'
+    && row.failureCode === 'code_project_stale_base'
+  );
+}
+
+function readOwnedIntent(project) {
+  const intent = readIntent(project);
+  if (!intent) return null;
+  return officialAcknowledgement(project, intent) ? null : intent;
+}
+
+module.exports = {
+  INTENT_CONTRACT,
+  SUCCESSOR_CONTRACT,
+  _test: {
+    canonicalPath,
+    cardState,
+    semanticDigest,
+    validInitialBase,
+    validIntent,
+    validSuccessor,
+  },
+  clearIntent,
+  clearSuccessor,
+  intentFile,
+  markPublicationFolded,
+  markPublicationNumbered,
+  officialAcknowledgement,
+  publicationMayRebase,
+  readIntent,
+  readOwnedIntent,
+  readSuccessor,
+  reservePublication,
+  stampPublication,
+  writeIntent,
+  writeSuccessor,
+};

package/runtime/scripts/amalgm-mcp/workspace/merge.js

@@ -72,6 +72,15 @@ async function hasTree(worktreeRoot, treeOid) {
   return result.exitCode === 0;
 }
 
+/** Gitlinks are a different repository and are not a file state we can apply. */
+async function gitlinksInTree(worktreeRoot, treeOid) {
+  const { stdout } = await run(['ls-tree', '-r', '-z', treeOid], worktreeRoot);
+  return stdout.split('\0').filter(Boolean).flatMap((entry) => {
+    const match = entry.match(/^160000 commit [0-9a-f]+\t(.+)$/);
+    return match ? [match[1]] : [];
+  });
+}
+
 /**
  * The tree a captured worktree patch describes: base commit's tree with
  * the patch applied. Computed entirely in a scratch index — the worktree
@@ -135,7 +144,7 @@ async function readBlob(worktreeRoot, oid) {
 
 /** The working file as bytes: { kind: 'file'|'symlink', content, exec } or null. */
 function workFileState(worktreeRoot, relPath) {
-  const abs = path.join(worktreeRoot, relPath);
+  const abs = transition.confinedPath(worktreeRoot, relPath);
   let stat;
   try {
     stat = fs.lstatSync(abs);
@@ -145,7 +154,7 @@ function workFileState(worktreeRoot, relPath) {
   if (stat.isSymbolicLink()) {
     return { kind: 'symlink', content: Buffer.from(fs.readlinkSync(abs)), exec: false };
   }
-  if (!stat.isFile()) return null;
+  if (!stat.isFile()) return { kind: 'other' };
   return { kind: 'file', content: fs.readFileSync(abs), exec: (stat.mode & 0o100) !== 0 };
 }
 
@@ -168,7 +177,11 @@ async function reduceTree(worktreeRoot, currentTree, baseTree, targetTree) {
   const updates = [];
   for (const relPath of await changedPaths(worktreeRoot, baseTree, targetTree)) {
     if (unsafePath(relPath)) throw new Error(`unsafe path: ${relPath}`);
-    updates.push({ path: relPath, entry: await entryAt(worktreeRoot, targetTree, relPath) });
+    const entry = await entryAt(worktreeRoot, targetTree, relPath);
+    if (entry && entry.type !== 'blob') {
+      throw new Error(`unsupported gitlink/submodule at ${relPath}`);
+    }
+    updates.push({ path: relPath, entry });
   }
 
   return {
@@ -176,6 +189,66 @@ async function reduceTree(worktreeRoot, currentTree, baseTree, targetTree) {
   };
 }
 
+function sameEntry(left, right) {
+  return (
+    left === null
+    ? right === null
+    : right !== null
+      && left.mode === right.mode
+      && left.type === right.type
+      && left.oid === right.oid
+  );
+}
+
+/**
+ * Resolve a crash-time tree from an exact apply WAL.
+ *
+ * Values equal to WAL source or target are known official progress and land
+ * on target. A value equal to neither is a real write made after the WAL was
+ * sealed, so it remains on top of target.
+ */
+async function reconcileApplyingTree(
+  worktreeRoot,
+  currentTree,
+  sourceTree,
+  targetTree,
+  { sourceCrossed = false, crossedPaths = null } = {},
+) {
+  const paths = new Set([
+    ...await changedPaths(worktreeRoot, sourceTree, currentTree),
+    ...await changedPaths(worktreeRoot, targetTree, currentTree),
+  ]);
+  const local = [];
+  const updates = [];
+  for (const relPath of [...paths].sort()) {
+    if (unsafePath(relPath)) throw new Error(`unsafe path: ${relPath}`);
+    const [current, source, target] = await Promise.all([
+      entryAt(worktreeRoot, currentTree, relPath),
+      entryAt(worktreeRoot, sourceTree, relPath),
+      entryAt(worktreeRoot, targetTree, relPath),
+    ]);
+    for (const entry of [current, source, target]) {
+      if (entry && entry.type !== 'blob') {
+        throw new Error(`unsupported gitlink/submodule at ${relPath}`);
+      }
+    }
+    if (sameEntry(current, target)) continue;
+    const crossed = sourceCrossed || crossedPaths?.has(relPath) === true;
+    // Endpoint resemblance alone is not provenance. If the apply receipt
+    // proves this path crossed, returning to the source value is a later
+    // local write (including deleting an official create) and must remain.
+    if (sameEntry(current, source) && !crossed) continue;
+    local.push(relPath);
+    updates.push({ path: relPath, entry: current });
+  }
+  return {
+    tree: updates.length
+      ? await updateHeldTree(worktreeRoot, targetTree, updates)
+      : targetTree,
+    local,
+  };
+}
+
 /** heldTree with the given entries replaced/removed — via a scratch index. */
 async function updateHeldTree(worktreeRoot, heldTree, applied) {
   return withScratch(async (dir) => {
@@ -214,15 +287,22 @@ async function advance(worktreeRoot, heldTree, targetTree, { label } = {}) {
     if (unsafePath(relPath)) throw new Error(`unsafe path: ${relPath}`);
     const held = await entryAt(worktreeRoot, heldTree, relPath);
     const target = await entryAt(worktreeRoot, targetTree, relPath);
-    if ((held && held.type !== 'blob') || (target && target.type !== 'blob')) continue;
+    if ((held && held.type !== 'blob') || (target && target.type !== 'blob')) {
+      throw new Error(`unsupported gitlink/submodule at ${relPath}`);
+    }
     const heldBytes = held ? await readBlob(worktreeRoot, held.oid) : null;
     const targetBytes = target ? await readBlob(worktreeRoot, target.oid) : null;
     const work = workFileState(worktreeRoot, relPath);
 
     if (workMatches(work, held, heldBytes)) {
       writes.push(target
-        ? { path: relPath, content: targetBytes, mode: target.mode }
-        : { path: relPath, content: null });
+        ? {
+          path: relPath,
+          content: targetBytes,
+          mode: target.mode,
+          expected: work,
+        }
+        : { path: relPath, content: null, expected: work });
     }
     applied.push({ path: relPath, entry: target });
   }
@@ -238,9 +318,12 @@ async function advance(worktreeRoot, heldTree, targetTree, { label } = {}) {
 
 module.exports = {
   advance,
+  changedPaths,
   diffOfTree,
+  gitlinksInTree,
   hasTree,
   indexTree,
+  reconcileApplyingTree,
   reduceTree,
   treeOf,
   treeOfPatch,