@stravica-ai/digital-operator-pa 0.1.63 → 0.1.65

package/dist/engineering-pa-cli/README.md

@@ -137,11 +137,13 @@ roots, else the clone's own. For every mount whose `to` lies under
 `operator/knowledge/writing/`. The legacy `<clone>/operator/knowledge/`
 form is still read during the path migration. On a colliding id the home
 copy wins, then the mapped copy (higher registry `precedence` first), then
-the legacy copy. Within one clone that holds both forms of an id, the
-legacy copy wins over the mapped one until the migration removes it: every
-writer has written the legacy form since the 2026-08-21 cutover, so it is
-the newer copy. A clone with no registry entry is read in the legacy form
-only.
+the legacy copy. Within one clone that holds both forms of an id, the copy
+whose last commit in that clone is newer wins (`git log -1 --format=%ct`,
+read only on such a collision), until the migration removes the legacy
+copies. On a tie, or when either time is unavailable (the clone is not a
+git repo, the file is untracked, git fails), the legacy copy wins. Commit
+times, not file mtimes, because a clone's mtimes are checkout times. A
+clone with no registry entry is read in the legacy form only.
 
 Global flag: `--format <table|json|mermaid>` (default: `table`). The
 `json` shape is stable-by-convention — `{ "verb": "<name>", ... }` —

package/dist/engineering-pa-core/src/knowledge/retrieval/links.mjs

@@ -33,6 +33,7 @@
 // nowhere does not describe the estate — it inflates it, and every orphan
 // statistic computed over it is wrong in both directions.
 
+import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { join, normalize, posix, relative } from 'node:path';
@@ -66,8 +67,9 @@ export const KNOWLEDGE_SCAN_DIRS = ['operator/knowledge', 'core/knowledge'];
 // composes at `operator/knowledge/` (or `operator/knowledge/wsd/`, and
 // `<clone>/voice/` at `operator/knowledge/writing/`) exactly as the registry
 // says. Across clones a mapped copy beats a legacy one; within one clone the
-// legacy `<clone>/operator/knowledge/` copy beats the mapped copy during the
-// migration bridge (`legacySupersedes`); home still beats both. See
+// copy with the newer last commit wins during the migration bridge, the
+// legacy `<clone>/operator/knowledge/` copy on a tie or when a commit time is
+// unavailable (`legacySupersedes`); home still beats both. See
 // `scanSourcesFor` and mounts.mjs.
 export const EXTRA_SCAN_ROOTS_ENV = 'LIBRARY_KNOWLEDGE_EXTRA_ROOTS';
 
@@ -193,9 +195,10 @@ export function scanDirsFor(root) {
  *      exactly the ids this function produced before mounts were read.
  *
  * So the home copy beats both forms, and a mapped copy beats another clone's
- * legacy copy of the same id. Within ONE clone the legacy copy beats the
- * mapped one; the order cannot say that, so the collision step applies it
- * (`legacySupersedes`, `collectScannedFiles`). A clone with no registry entry
+ * legacy copy of the same id. Within ONE clone the copy whose last commit
+ * is newer wins (legacy on a tie or an unavailable time); the order cannot
+ * say that, so the collision step applies it (`legacySupersedes`,
+ * `collectScannedFiles`). A clone with no registry entry
  * contributes its legacy form only.
  *
  * @param {string} root the home workspace root
@@ -258,35 +261,92 @@ export function scanIdFor(scan, abs) {
 }
 
 // slice 3 removes: the within-tier bridge rule. The scan order cannot carry
-// it, because "legacy first within a clone" and "mapped first across clones"
-// are not one order: with copies in A legacy, A mapped and B mapped (A of
-// higher precedence) the two rules cycle. So the order picks the winning
-// TIER (first occurrence: home, mapped by precedence, legacy), and this rule
-// then swaps a mapped winner for the same clone's legacy copy. Every writer
-// wrote the legacy form after the 2026-08-21 cutover, so where one clone
-// holds both, the legacy copy is the newer (all 25 hq merge rows).
+// it, because "one form first within a clone" and "mapped first across
+// clones" are not one order: with copies in A legacy, A mapped and B mapped
+// (A of higher precedence) the two rules cycle. So the order picks the
+// winning TIER (first occurrence: home, mapped by precedence, legacy), and
+// this rule then decides between that clone's own two copies: the copy whose
+// last commit in the clone is newer wins. On a tie, or when either commit
+// time is unavailable (not a git clone, untracked file, git error), the
+// legacy copy wins, which was the slice 1 rule: every writer took the legacy
+// form between the 2026-08-21 cutover and slice 2, which moved the writers
+// to the mounted form. Commit times, not mtimes: a clone's mtimes are
+// checkout times, while commit times are the same on every host.
+
+/**
+ * Unix seconds of the last commit that touched `abs` in the clone at
+ * `root`, or null when there is none to read: `root` is not a git clone,
+ * the file is untracked, or git fails.
+ *
+ * @param {string} root clone root
+ * @param {string} abs absolute path of a file under `root`
+ * @returns {number|null}
+ */
+export function lastCommitTime(root, abs) {
+  // `git -C` would climb into an enclosing repo; only the clone's own
+  // history counts.
+  if (!existsSync(join(root, '.git'))) return null;
+  try {
+    const out = execFileSync(
+      'git',
+      ['-C', root, 'log', '-1', '--format=%ct', '--', toPosix(relative(root, abs))],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    return /^\d+$/.test(out) ? Number(out) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `lastCommitTime` memoised per path, for the life of one scan.
+ *
+ * @returns {(root: string, abs: string) => number|null}
+ */
+export function memoCommitTime(lookup = lastCommitTime) {
+  const memo = new Map();
+  return (root, abs) => {
+    if (!memo.has(abs)) memo.set(abs, lookup(root, abs));
+    return memo.get(abs);
+  };
+}
+
 /**
  * True when `candidate` (met later in scan order) should replace `winner`,
- * the scan that first claimed the same id.
+ * the scan that first claimed the same id. Only a clone's legacy copy can
+ * replace that same clone's mapped copy, and it does unless the mapped copy's
+ * last commit is strictly newer. Commit times are read only here, so only on
+ * a within-clone collision.
  *
  * @param {ReturnType<typeof scanSourcesFor>[number]} winner
+ * @param {string} winnerAbs the file `winner` holds for the id
  * @param {ReturnType<typeof scanSourcesFor>[number]} candidate
+ * @param {string} candidateAbs the file `candidate` holds for the id
+ * @param {(root: string, abs: string) => number|null} commitTime
  */
-export function legacySupersedes(winner, candidate) {
-  return winner.form === 'mapped' && candidate.form === 'legacy'
-    && winner.sourceRoot === candidate.sourceRoot;
+export function legacySupersedes(winner, winnerAbs, candidate, candidateAbs, commitTime) {
+  if (winner.form !== 'mapped' || candidate.form !== 'legacy'
+    || winner.sourceRoot !== candidate.sourceRoot) return false;
+  const mappedAt = commitTime(winner.sourceRoot, winnerAbs);
+  const legacyAt = commitTime(candidate.sourceRoot, candidateAbs);
+  if (mappedAt === null || legacyAt === null) return true;
+  return legacyAt >= mappedAt;
 }
 
 /**
  * Walk every scan and keep one file per workspace id: the first occurrence,
- * except that a clone's legacy copy replaces that clone's mapped copy
+ * except that within one clone the copy with the newer last commit wins
  * (`legacySupersedes`). A replaced entry keeps its position, so the entry
  * order is still scan order of first occurrence.
  *
  * @param {ReturnType<typeof scanSourcesFor>} scans
+ * @param {object} [opts]
+ * @param {(root: string, abs: string) => number|null} [opts.commitTime]
+ *   override the memoised git lookup (tests, timing)
  * @returns {Promise<{ abs: string, id: string, scan: object }[]>}
  */
-export async function collectScannedFiles(scans) {
+export async function collectScannedFiles(scans, opts = {}) {
+  const commitTime = opts.commitTime ?? memoCommitTime();
   const entries = [];
   const byId = new Map();
   for (const scan of scans) {
@@ -297,7 +357,7 @@ export async function collectScannedFiles(scans) {
         const entry = { abs, id, scan };
         byId.set(id, entry);
         entries.push(entry);
-      } else if (legacySupersedes(existing.scan, scan)) {
+      } else if (legacySupersedes(existing.scan, existing.abs, scan, abs, commitTime)) {
         existing.abs = abs;
         existing.scan = scan;
       }
@@ -308,14 +368,18 @@ export async function collectScannedFiles(scans) {
 
 /**
  * The on-disk file that backs a workspace id, under the same precedence the
- * builders apply (including `legacySupersedes`), or null. Lets body readers (`pa knowledge search --full`)
- * open the copy the graph actually indexed.
+ * builders apply (including `legacySupersedes`), or null. Lets body readers
+ * (`pa knowledge search --full`) open the copy the graph actually indexed.
  *
  * @param {ReturnType<typeof scanSourcesFor>} scans
  * @param {string} id
+ * @param {object} [opts]
+ * @param {(root: string, abs: string) => number|null} [opts.commitTime]
+ *   override the memoised git lookup (tests, timing)
  * @returns {string|null}
  */
-export function locateScannedFile(scans, id) {
+export function locateScannedFile(scans, id, opts = {}) {
+  const commitTime = opts.commitTime ?? memoCommitTime();
   const posixId = toPosix(id);
   const fileIn = (scan) => {
     if (!posixId.startsWith(scan.idPrefix)) return null;
@@ -328,9 +392,9 @@ export function locateScannedFile(scans, id) {
     const found = fileIn(scan);
     if (!found) continue;
     for (const later of scans.slice(i + 1)) {
-      if (!legacySupersedes(scan, later)) continue;
+      if (later.form !== 'legacy' || later.sourceRoot !== scan.sourceRoot) continue;
       const legacy = fileIn(later);
-      if (legacy) return legacy;
+      if (legacy && legacySupersedes(scan, found, later, legacy, commitTime)) return legacy;
     }
     return found;
   }

package/dist/engineering-pa-core/src/knowledge/retrieval/mount-map.mjs

@@ -0,0 +1,169 @@
+// Vendored from Stravica/remote-library, src/mounts/mount-map.ts, compiled at 2add6c77a58664981771e71e0cdf0db8def64f66.
+// Do not edit here; change the source and re-vendor.
+// Same fixture in both repos (test/knowledge/fixtures/mount-map-cases.json) proves it is one map.
+// Shared mount map (w-2026-10-16-dave-019, library-sync slice 2).
+//
+// One answer, used by every writer and gate, to "which tier path does a
+// registry mount read for this workspace path, and back". The registry is
+// `registry/repos.json` from the company tier: `repos.<repoKey>.mounts[]`,
+// each `{ from, to }` where `from` is the path inside the tier repo and `to`
+// is the workspace path it composes at.
+//
+// PURE by contract: this file has no imports at all (not even node:path) and
+// works on POSIX path strings only, so its compiled `dist/mounts/mount-map.js`
+// can be vendored unchanged into other repos. Keep it that way.
+export const KNOWLEDGE_TO_PREFIX = "operator/knowledge/";
+function stripDotSlash(p) {
+    let out = p;
+    while (out.startsWith("./"))
+        out = out.slice(2);
+    return out;
+}
+function hasUnsafeSegment(p) {
+    return p.split("/").some((seg) => seg === "..");
+}
+// Normalise a mount side to `a/b/` form. Null when it cannot be a safe
+// relative directory (empty, absolute, or holding a `..` segment).
+function normaliseMountSide(raw) {
+    if (typeof raw !== "string")
+        return null;
+    let p = stripDotSlash(raw.trim());
+    if (p === "" || p.startsWith("/") || p.includes("\\"))
+        return null;
+    if (hasUnsafeSegment(p))
+        return null;
+    if (!p.endsWith("/"))
+        p += "/";
+    return p;
+}
+// Normalise an input file path. Null when it is not a safe relative file
+// path: empty, absolute, a directory (trailing `/`), or holding an empty,
+// `.` or `..` segment.
+function normaliseFilePath(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const p = stripDotSlash(raw);
+    if (p === "" || p.startsWith("/") || p.endsWith("/") || p.includes("\\"))
+        return null;
+    if (p.includes("\0"))
+        return null;
+    for (const seg of p.split("/")) {
+        if (seg === "" || seg === "." || seg === "..")
+            return null;
+    }
+    return p;
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+// Longest-prefix mount for `path` on the given side, with the remainder.
+function longestMatch(mounts, path, side) {
+    let best = null;
+    for (const m of mounts) {
+        if (!path.startsWith(m[side]))
+            continue;
+        if (best === null || m[side].length > best[side].length)
+            best = m;
+    }
+    if (best === null)
+        return null;
+    const rest = path.slice(best[side].length);
+    if (rest === "")
+        return null;
+    return { mount: best, rest };
+}
+export function createMountMap(registry, opts) {
+    const toPrefix = opts?.toPrefix ?? KNOWLEDGE_TO_PREFIX;
+    const byRepo = new Map();
+    const repoEntries = isObject(registry) && isObject(registry.repos) ? registry.repos : {};
+    for (const [repoKey, entry] of Object.entries(repoEntries)) {
+        const kept = [];
+        const rawMounts = isObject(entry) && Array.isArray(entry.mounts) ? entry.mounts : [];
+        for (const raw of rawMounts) {
+            if (!isObject(raw))
+                continue;
+            const from = normaliseMountSide(raw.from);
+            const to = normaliseMountSide(raw.to);
+            if (from === null || to === null)
+                continue;
+            if (!to.startsWith(toPrefix))
+                continue;
+            kept.push({ from, to });
+        }
+        byRepo.set(repoKey, kept);
+    }
+    const mountsFor = (repo) => (byRepo.get(repo) ?? []).map((m) => ({ from: m.from, to: m.to }));
+    const toLibraryPath = (repo, workspacePath) => {
+        const p = normaliseFilePath(workspacePath);
+        if (p === null)
+            return null;
+        const hit = longestMatch(byRepo.get(repo) ?? [], p, "to");
+        return hit === null ? null : hit.mount.from + hit.rest;
+    };
+    const toWorkspacePath = (repo, libraryPath) => {
+        const p = normaliseFilePath(libraryPath);
+        if (p === null)
+            return null;
+        const hit = longestMatch(byRepo.get(repo) ?? [], p, "from");
+        return hit === null ? null : hit.mount.to + hit.rest;
+    };
+    const resolveRepoKey = (tier) => {
+        if (typeof tier !== "string" || tier === "")
+            return null;
+        if (byRepo.has(tier))
+            return tier;
+        const suffix = `-${tier}`;
+        const hits = [...byRepo.keys()].filter((k) => k.endsWith(suffix));
+        return hits.length === 1 ? hits[0] : null;
+    };
+    return {
+        repos: () => [...byRepo.keys()],
+        mountsFor,
+        toLibraryPath,
+        toWorkspacePath,
+        isReadable: (repo, libraryPath) => toWorkspacePath(repo, libraryPath) !== null,
+        resolveRepoKey,
+    };
+}
+export function resolveWrite(map, workspacePath, assertedTier) {
+    const triedFor = (repo) => map.mountsFor(repo).map((m) => ({ repo, from: m.from, to: m.to }));
+    if (assertedTier !== undefined && assertedTier !== "") {
+        const repo = map.resolveRepoKey(assertedTier);
+        if (repo === null)
+            return { ok: false, reason: "unknown-tier", tried: [] };
+        const libraryPath = map.toLibraryPath(repo, workspacePath);
+        if (libraryPath === null)
+            return { ok: false, reason: "unmapped", tried: triedFor(repo) };
+        return { ok: true, repo, libraryPath };
+    }
+    const p = normaliseFilePath(workspacePath);
+    const candidates = [];
+    const tried = [];
+    for (const repo of map.repos()) {
+        tried.push(...triedFor(repo));
+        if (p === null)
+            continue;
+        const libraryPath = map.toLibraryPath(repo, p);
+        if (libraryPath === null)
+            continue;
+        const mount = map
+            .mountsFor(repo)
+            .filter((m) => p.startsWith(m.to))
+            .reduce((a, b) => (b.to.length > a.to.length ? b : a));
+        candidates.push({ repo, mount, libraryPath });
+    }
+    if (candidates.length === 0)
+        return { ok: false, reason: "unmapped", tried };
+    const longest = Math.max(...candidates.map((c) => c.mount.to.length));
+    const best = candidates.filter((c) => c.mount.to.length === longest);
+    if (best.length === 1)
+        return { ok: true, repo: best[0].repo, libraryPath: best[0].libraryPath };
+    const paths = new Set(best.map((c) => c.libraryPath));
+    if (paths.size === 1)
+        return { ok: true, repo: null, libraryPath: best[0].libraryPath };
+    return {
+        ok: false,
+        reason: "ambiguous",
+        tried: best.map((c) => ({ repo: c.repo, from: c.mount.from, to: c.mount.to })),
+    };
+}

package/dist/engineering-pa-core/src/knowledge/retrieval/mounts.mjs

@@ -22,6 +22,9 @@
 //      `registry/`, the registry source of truth);
 //   2. else the clone's own `registry/repos.json`;
 //   3. else no registry: the clone is scanned in the legacy form only.
+//
+// `loadWriteRegistry` gives `library put` its registry by the same company
+// rule, falling back to the workspace copy (slice 2).
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
@@ -147,15 +150,7 @@ function mountsRegistry(entry) {
 export function resolveTierMounts(extraRoots, { remoteOf = gitRemoteOf } = {}) {
   const own = new Map();
   for (const root of extraRoots) own.set(root, readRegistry(root));
-
-  // The company clone is the registry's own source: its entry mounts
-  // `registry/`. Prefer its copy over each clone's (possibly drifted) one.
-  let company = null;
-  for (const root of extraRoots) {
-    const registry = own.get(root);
-    const self = resolveRepoEntry(registry, root, { remoteOf });
-    if (self && mountsRegistry(self.entry)) { company = registry; break; }
-  }
+  const company = findCompanyRegistry(extraRoots, { remoteOf, read: (root) => own.get(root) })?.registry ?? null;
 
   return extraRoots.map((root) => {
     let hit = null;
@@ -182,3 +177,61 @@ export function resolveTierMounts(extraRoots, { remoteOf = gitRemoteOf } = {}) {
     };
   });
 }
+
+/**
+ * The company clone among `roots`: the clone whose own registry entry mounts
+ * `registry/`, the registry's source of truth. Its copy is preferred over
+ * every other (possibly drifted) one.
+ *
+ * @param {string[]} roots
+ * @param {object} [opts]
+ * @param {(root: string) => string|null} [opts.remoteOf]
+ * @param {(root: string) => object|null} [opts.read] registry reader seam
+ * @returns {{ root: string, registry: object } | null}
+ */
+export function findCompanyRegistry(roots, { remoteOf = gitRemoteOf, read = readRegistry } = {}) {
+  for (const root of roots) {
+    const registry = read(root);
+    const self = resolveRepoEntry(registry, root, { remoteOf });
+    if (self && mountsRegistry(self.entry)) return { root, registry };
+  }
+  return null;
+}
+
+/**
+ * The registry `library put` maps knowledge paths through
+ * (w-2026-10-16-dave-019, slice 2). Source order:
+ *   1. the company clone among the extra roots (LIBRARY_KNOWLEDGE_EXTRA_ROOTS);
+ *   2. else the workspace copy, `<repoRoot>/operator/registry/repos.json`;
+ *   3. else none.
+ * `looked` names every place tried, so a refusal can print it.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.extraRoots
+ * @param {string} opts.repoRoot
+ * @param {(root: string) => string|null} [opts.remoteOf]
+ * @returns {{ registry: object|null, source: 'company'|'workspace'|null, path: string|null, looked: string[] }}
+ */
+export function loadWriteRegistry({ extraRoots, repoRoot, remoteOf = gitRemoteOf }) {
+  const looked = [];
+  if (extraRoots.length) {
+    looked.push(`company clone among ${extraRoots.length} extra root(s) (${extraRoots.join(':')})`);
+    const company = findCompanyRegistry(extraRoots, { remoteOf });
+    if (company) {
+      return {
+        registry: company.registry,
+        source: 'company',
+        path: join(company.root, ...REGISTRY_RELATIVE_PATH.split('/')),
+        looked,
+      };
+    }
+  } else {
+    looked.push('company clone (LIBRARY_KNOWLEDGE_EXTRA_ROOTS unset)');
+  }
+  const operatorDir = join(repoRoot, 'operator');
+  const workspacePath = join(operatorDir, ...REGISTRY_RELATIVE_PATH.split('/'));
+  looked.push(workspacePath);
+  const workspace = readRegistry(operatorDir);
+  if (workspace) return { registry: workspace, source: 'workspace', path: workspacePath, looked };
+  return { registry: null, source: null, path: null, looked };
+}