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

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 };
+}

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

@@ -14,27 +14,54 @@ pre-remote library sweep.
 
 ## Verbs
 
-- `library put <path> [--kind <kind>] [--tier auto|<tier>]`
+- `library put <path> [--kind <kind>] [--tier auto|<tier>] [--verbatim-path]`
   Streams a single event to `POST /events`.
   **`--kind` is required** for any path outside `agents/*/staging/`; those
   staging paths default to `knowledge.observation.staged` via path inference.
-  A canonical doc write is `library put <absolute path> --kind knowledge.doc.upsert`.
+  A canonical doc write is `library put <path> --kind knowledge.doc.upsert`.
   Known kinds (ingest will 422 anything else): `knowledge.observation.staged`,
   `knowledge.doc.upsert`, `knowledge.doc.delete`, `profile.upsert`,
   `profile.slice.upsert`, `preferences.upsert`, `role.output`,
   `system.correction`, `synthesis.upsert`, `synthesis.merge`,
   `synthesis.retire`, `system.seed`.
-  **Path resolution.** The `<path>` argument is read as given (cwd-relative or
-  absolute); the repo-relative payload path is derived only when the input is
-  absolute. A relative path run from `agents/dave/` therefore encodes a
-  payload path relative to `agents/dave/`, which also misses the
-  `agents/*/staging/` kind-inference regex. Safe form: pass an absolute path,
-  or run from the repo root.
+  **Path resolution.** `<path>` is resolved against the current directory, so
+  a relative path from any cwd and an absolute path encode the same
+  repo-relative path. From the repo root this is byte-identical to the old
+  "as given" encoding.
+  **Knowledge docs go to the tier path a mount reads.** For
+  `knowledge.doc.upsert` and `knowledge.doc.delete` the workspace path
+  (`operator/knowledge/...`) is mapped through the registry knowledge mounts
+  (`repos.<repo>.mounts[]` with `to` under `operator/knowledge/`) by the
+  shared mount map vendored from remote-library
+  (`packages/core/src/knowledge/retrieval/mount-map.mjs`). The longest
+  matching mount `to` wins:
+  | Workspace path | Sent as | Tier |
+  |---|---|---|
+  | `operator/knowledge/engineering/x.md` | `knowledge/engineering/x.md` | `auto` (hq and company agree) |
+  | `operator/knowledge/wsd/memory/y.md` | `knowledge/memory/y.md` | `stravica-library-wsd` |
+  | `operator/knowledge/writing/z.md` | `voice/z.md` | `stravica-operator-barry` |
+  A unique tier is stamped exactly as an explicit `--tier` is (envelope `tier`
+  and `payload.source`); `provenance.sourcePath` keeps the workspace path.
+  With an explicit `--tier` (registry key or short name such as `hq`), only
+  that tier's mounts are tried, and the registry key is stamped. Put refuses
+  with exit 2 and one line naming the mounts tried when no knowledge mount
+  reads the path, when the candidate tiers disagree, when `--tier` names an
+  unknown tier or one that cannot read the path, or when no registry is found.
+  The ingest refuses the same shape with 422 `unmapped-path`.
+  Paths the profile tier map owns (`operator/profile/**`) keep their profile
+  routing and are sent unmapped.
+  **Registry source.** The company clone among `LIBRARY_KNOWLEDGE_EXTRA_ROOTS`
+  (the clone whose own registry entry mounts `registry/`), else the workspace
+  copy `<repoRoot>/operator/registry/repos.json`, else none (refuse).
   `--tier auto` sends the spec §2.3 sentinel; the server's routing engine
   resolves the actual tier. An explicit `--tier <repo>` also stamps
   `payload.source = <repo>` on the kinds whose ingest schema accepts it
   (`knowledge.doc.upsert`, `knowledge.doc.delete`, `profile.upsert`,
   `profile.slice.upsert`).
+  `--verbatim-path` (slice 3 removes) sends a `knowledge.doc.delete` at the
+  workspace path unmapped, to delete the legacy `operator/knowledge/...`
+  copies. It needs `--kind knowledge.doc.delete` and an explicit `--tier`;
+  any other use is a usage error (exit 1).
 
 - `library flush`
   Sweeps `<repoRoot>/agents/<paName>/staging/*` and streams one event per file.

package/dist/engineering-pa-library-cli/src/cli.mjs

@@ -78,7 +78,7 @@ help ('library put --help' etc.) is served the same way.
  * useful at the point of friction, not a prose essay.
  */
 const VERB_USAGE = {
-  put: `library put <path> [--kind <kind>] [--tier auto|<tier>]
+  put: `library put <path> [--kind <kind>] [--tier auto|<tier>] [--verbatim-path]
 
   Streams a single event to POST /events (REMOTE mode only).
 
@@ -91,12 +91,23 @@ const VERB_USAGE = {
                   synthesis.upsert, synthesis.merge, synthesis.retire,
                   system.seed.
   --tier <name>   'auto' (default) lets the server route; an explicit tier
-                  (repo name) stamps payload.source for routing-rule kinds.
+                  (repo name, or a short name such as 'hq') stamps
+                  payload.source for routing-rule kinds.
+  --verbatim-path With --kind knowledge.doc.delete and an explicit --tier
+                  only: send the workspace path unmapped, to delete a legacy
+                  operator/knowledge/... copy (slice 3 removes).
 
-  Path resolution: the argument is read as given (cwd-relative or absolute);
-  the repo-relative payload path is derived only when the input is absolute.
-  Run from the repo root with a relative path, or always pass an absolute
-  path, to keep the staging-inference and payload path in agreement.
+  Path resolution: <path> is resolved against the current directory, so the
+  payload path is repo-relative from any cwd.
+
+  Knowledge docs (knowledge.doc.upsert, knowledge.doc.delete) are sent at the
+  tier path a registry knowledge mount reads, for example
+  operator/knowledge/x.md -> knowledge/x.md (tier auto),
+  operator/knowledge/wsd/x.md -> knowledge/x.md (stravica-library-wsd),
+  operator/knowledge/writing/x.md -> voice/x.md (stravica-operator-barry).
+  No mount reads the path, the tiers disagree, or no registry: exit 2 with
+  the mounts tried. Registry: the company clone among
+  LIBRARY_KNOWLEDGE_EXTRA_ROOTS, else operator/registry/repos.json.
 `,
   flush: `library flush
 
@@ -276,9 +287,16 @@ function parsePut(argv) {
     options: {
       kind: { type: 'string' },
       tier: { type: 'string', default: 'auto' },
+      // slice 3 removes: deletes the legacy operator/knowledge/... copies.
+      'verbatim-path': { type: 'boolean', default: false },
     },
   });
-  return { path: positionals[0], kind: values.kind, tier: values.tier };
+  return {
+    path: positionals[0],
+    kind: values.kind,
+    tier: values.tier,
+    verbatimPath: values['verbatim-path'],
+  };
 }
 function parseFlush(argv) {
   parseArgs({ args: argv, strict: true, allowPositionals: true, options: {} });

package/dist/engineering-pa-library-cli/src/envelope.mjs

@@ -143,6 +143,12 @@ export function guessKindFromPath(sourcePath) {
  *   `--tier` is asserted explicitly (not the `auto` sentinel), the tier
  *   value is used as the source stamp for these kinds automatically, so
  *   callers rarely pass this directly.
+ * @param {string} [args.payloadPath]  the tier path to send as
+ *   `payload.path` when it differs from the repo-relative source path
+ *   (`library put` maps knowledge docs through the registry mounts,
+ *   w-2026-10-16-dave-019 slice 2). `provenance.sourcePath` keeps the
+ *   repo-relative source path. Absent: `payload.path` is the source path,
+ *   unchanged.
  * @param {() => Date} [args.clock]  test seam
  * @returns {object} EventInput ready for POST /events
  */
@@ -155,6 +161,7 @@ export function buildEnvelope({
   tier = 'auto',
   sourceKind = 'manual',
   source,
+  payloadPath,
   clock = () => new Date(),
 }) {
   // Repo-relative resolution + refusal for anything that would encode as
@@ -173,6 +180,10 @@ export function buildEnvelope({
   if (relPath !== undefined) {
     assertRepoRelativeSafe(relPath, sourcePath, repoRoot);
   }
+  if (payloadPath !== undefined) {
+    assertRepoRelativeSafe(payloadPath, sourcePath, repoRoot);
+  }
+  const wirePath = payloadPath ?? relPath;
 
   const resolvedKind = kind ?? guessKindFromPath(relPath ?? sourcePath ?? '') ?? null;
   if (!resolvedKind) {
@@ -218,7 +229,7 @@ export function buildEnvelope({
   let payload;
   if (resolvedKind === 'knowledge.doc.delete') {
     payload = {
-      path: relPath ?? null,
+      path: wirePath ?? null,
       ...(stampSource ? { source: effectiveSource } : {}),
     };
   } else if (resolvedKind === 'profile.slice.upsert') {
@@ -249,7 +260,7 @@ export function buildEnvelope({
   } else if (KINDS_ACCEPTING_SOURCE.has(resolvedKind)) {
     // knowledge.doc.upsert, profile.upsert.
     payload = {
-      path: relPath ?? null,
+      path: wirePath ?? null,
       content,
       ...(stampSource ? { source: effectiveSource } : {}),
     };
@@ -257,7 +268,7 @@ export function buildEnvelope({
     // Every other kind keeps the pre-cure {path, content} shape
     // byte-identical.
     payload = {
-      path: relPath ?? null,
+      path: wirePath ?? null,
       content,
     };
   }

package/dist/engineering-pa-library-cli/src/verbs/put.mjs

@@ -1,40 +1,72 @@
-// verbs/put.mjs — `library put <path> [--kind ...] [--tier auto|<tier>]`
+// verbs/put.mjs: `library put <path> [--kind ...] [--tier auto|<tier>] [--verbatim-path]`
 //
 // Streams a single event to POST /events. Reads the file's UTF-8 contents,
 // builds an envelope (spec §3.1), and posts with retries via http.mjs.
 // A `deduped` server response counts as SUCCESS (spec §4.2: retrying a
 // timed-out send must see success).
+//
+// Knowledge docs (`knowledge.doc.upsert`, `knowledge.doc.delete`) are sent at
+// the TIER path a registry mount reads, never at the workspace path
+// (w-2026-10-16-dave-019, slice 2). The input resolves against cwd to a
+// repo-relative workspace path, the shared mount map (vendored from
+// remote-library) maps it, and put refuses with exit 2 when no knowledge
+// mount reads it. The ingest refuses the same shape with 422 `unmapped-path`.
 
 import { readFile } from 'node:fs/promises';
-import { basename } from 'node:path';
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { resolveExtraScanRoots } from '../../../engineering-pa-core/src/knowledge/retrieval/links.mjs';
+import { loadWriteRegistry } from '../../../engineering-pa-core/src/knowledge/retrieval/mounts.mjs';
+import { createMountMap, resolveWrite } from '../../../engineering-pa-core/src/knowledge/retrieval/mount-map.mjs';
 
-import { buildEnvelope, subkeyIdFromRemoteKey } from '../envelope.mjs';
+import { buildEnvelope, guessKindFromPath, subkeyIdFromRemoteKey } from '../envelope.mjs';
 import { postEvents } from '../http.mjs';
 import { parseIngestAck } from '../ack.mjs';
 import { assertTierMatchesPath, deriveTierFromPath } from '../tier-map.mjs';
 
+/** Kinds whose payload path must be one a registry knowledge mount reads. */
+export const MAPPED_KINDS = new Set(['knowledge.doc.upsert', 'knowledge.doc.delete']);
+
 /**
  * @param {object} ctx
  * @param {object} ctx.config   from loadLibraryConfig (mode/remoteEndpoint/remoteKey/preferences)
- * @param {object} ctx.args     { path, kind?, tier? }
+ * @param {object} ctx.args     { path, kind?, tier?, verbatimPath? }
  * @param {typeof fetch} [ctx.fetchImpl]
  * @param {(...m:unknown[])=>void} [ctx.log]
+ * @param {string} [ctx.cwd]    test seam; defaults to process.cwd()
+ * @param {() => { registry: object|null, looked: string[] }} [ctx.loadRegistry]
+ *   test seam for the mount registry; defaults to loadWriteRegistry over
+ *   LIBRARY_KNOWLEDGE_EXTRA_ROOTS and the workspace copy
  * @returns {Promise<number>}   exit code
  */
-export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
-  const { path, kind, tier = 'auto' } = args;
+export async function runPut({ config, args, fetchImpl, log = defaultLog, cwd = process.cwd(), loadRegistry }) {
+  const { path, kind, tier = 'auto', verbatimPath = false } = args;
   if (!path) {
-    log('usage: library put <path> [--kind <kind>] [--tier auto|<tier>]');
+    log('usage: library put <path> [--kind <kind>] [--tier auto|<tier>] [--verbatim-path]');
+    return 1;
+  }
+
+  // `--verbatim-path` (slice 3 removes): send a delete at the workspace path
+  // unmapped, so slice 3 can delete the legacy `operator/knowledge/...`
+  // copies. Deletes only, and only with an explicit tier.
+  if (verbatimPath && (kind !== 'knowledge.doc.delete' || tier === 'auto')) {
+    log('usage: --verbatim-path is valid only with --kind knowledge.doc.delete and an explicit --tier <tier>');
     return 1;
   }
 
+  // Every kind resolves the input against cwd, so the payload path is
+  // repo-relative whether the caller passed a repo-root-relative path, a
+  // path relative to some other cwd, or an absolute path. From the repo
+  // root this encodes byte-identically to the old "as given" behaviour.
+  const absPath = resolve(cwd, path);
+
   // Refuse a caller-forced tier that disagrees with the path-derived
   // default (w-2026-09-03-dave-017). `auto` never triggers the refusal
   // (auto means "let derivation choose"); an explicit tier does. The
   // refusal is a clean exit 2 with a single-line reason so an operator
   // sees why the CLI declined to encode the event rather than silently
   // stamping the wrong tier.
-  const tierRefusal = assertTierMatchesPath(path, config.repoRoot, tier);
+  const tierRefusal = assertTierMatchesPath(absPath, config.repoRoot, tier);
   if (tierRefusal) {
     log(`[library put] refused: ${tierRefusal}`);
     return 2;
@@ -43,9 +75,37 @@ export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
   // When `--tier` is absent the CLI derives it from the path map. Paths
   // outside the map keep today's `auto` sentinel so unrelated payload
   // kinds still content-route the way they always did.
-  const derivedTier = tier === 'auto'
-    ? (deriveTierFromPath(path, config.repoRoot) ?? 'auto')
-    : tier;
+  const mapTier = deriveTierFromPath(absPath, config.repoRoot);
+  let derivedTier = tier === 'auto' ? (mapTier ?? 'auto') : tier;
+
+  // Knowledge docs go to the tier path a registry mount reads. Paths the
+  // profile tier map owns (operator/profile/**) keep their profile routing
+  // and path unchanged; profile routing is out of scope for slice 2. A path
+  // outside the repo skips mapping so buildEnvelope refuses it as before.
+  const workspacePath = relative(config.repoRoot, absPath).split(sep).join('/');
+  const insideRepo = workspacePath !== '' && !workspacePath.startsWith('../') && !isAbsolute(workspacePath);
+  const effectiveKind = kind ?? guessKindFromPath(workspacePath);
+  let payloadPath;
+  if (MAPPED_KINDS.has(effectiveKind) && insideRepo && !mapTier && !verbatimPath) {
+    const loaded = (loadRegistry ?? (() => loadWriteRegistry({
+      extraRoots: resolveExtraScanRoots(process.env),
+      repoRoot: config.repoRoot,
+    })))();
+    if (!loaded?.registry) {
+      log(`[library put] refused: no mount registry (looked in: ${(loaded?.looked ?? []).join(', ')})`);
+      return 2;
+    }
+    const asserted = tier === 'auto' ? undefined : tier;
+    const res = resolveWrite(createMountMap(loaded.registry), workspacePath, asserted);
+    if (!res.ok) {
+      log(`[library put] refused: ${describeRefusal(res, workspacePath, asserted)}`);
+      return 2;
+    }
+    payloadPath = res.libraryPath;
+    // A unique tier stamps itself exactly as an explicit --tier does; agreeing
+    // tiers (hq and company both read `knowledge/`) leave the server to route.
+    derivedTier = res.repo ?? 'auto';
+  }
 
   // Delete events carry no content by spec (§3.1 payload schema); the
   // operator can and typically will have removed the file locally before
@@ -54,17 +114,18 @@ export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
   // delete. Every other kind still reads the file to populate
   // payload.content. Fix Wave E (w-2026-08-24-dave-029) partner cure to
   // the envelope kind-aware branch.
-  const content = kind === 'knowledge.doc.delete' ? undefined : await readFile(path, 'utf8');
+  const content = kind === 'knowledge.doc.delete' ? undefined : await readFile(absPath, 'utf8');
 
   const producer = producerFromPreferences(config);
   const envelope = buildEnvelope({
     repoRoot: config.repoRoot,
-    sourcePath: path,
+    sourcePath: absPath,
     content,
     producer,
     kind,
     tier: derivedTier,
     sourceKind: 'manual',
+    ...(payloadPath !== undefined ? { payloadPath } : {}),
   });
 
   const res = await postEvents({
@@ -77,13 +138,35 @@ export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
   // RB-5 fix (2026-08-20 rehearsal). See ack.mjs for the wire contract.
   const ack = parseIngestAck(res);
   if (ack.kind === 'accepted' || ack.kind === 'deduped') {
-    log(`[library put] ${ack.kind} ${basename(path)} -> ${ack.eventId} (tier: ${derivedTier})`);
+    const pathNote = payloadPath !== undefined ? `, path: ${payloadPath}` : '';
+    log(`[library put] ${ack.kind} ${basename(path)} -> ${ack.eventId} (tier: ${derivedTier}${pathNote})`);
     return 0;
   }
   log(`[library put] rejected ${basename(path)}: ${ack.reason}`);
   return 2;
 }
 
+/**
+ * One-line reason for a failed resolveWrite, naming the mounts tried.
+ *
+ * @param {{ reason: string, tried: { repo: string, from: string, to: string }[] }} res
+ * @param {string} workspacePath
+ * @param {string|undefined} asserted
+ */
+export function describeRefusal(res, workspacePath, asserted) {
+  const tried = res.tried.length
+    ? res.tried.map((t) => `${t.repo} ${t.to} -> ${t.from}`).join(', ')
+    : 'no knowledge mounts';
+  if (res.reason === 'unknown-tier') {
+    return `${workspacePath}: tier ${asserted} is not in the mount registry`;
+  }
+  if (res.reason === 'ambiguous') {
+    return `${workspacePath} is read by knowledge mounts of several tiers that disagree on the tier path; ` +
+      `pass --tier to choose; tried: ${tried}`;
+  }
+  return `${workspacePath} is read by no knowledge mount of ${asserted ?? 'any tier'}; tried: ${tried}`;
+}
+
 export function producerFromPreferences(config) {
   const paName = config.preferences?.paName;
   const operator = (config.preferences?.operator?.name ?? '').toString().toLowerCase() || 'unknown';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.63",
+  "version": "0.1.64",
   "description": "Digital Operator PA: single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",