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

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

@@ -115,6 +115,19 @@ pre-remote library sweep.
   Runs the same in SIMPLE and REMOTE mode (GitHub-side maintenance verb,
   no ingest touch). Config in the `library.upMerge` stanza; see below.
 
+- `library migrate-mounts --dry-run|--check [--tier <name>]... [--clone <path>]... [--ref <ref>] [--no-fetch] [--out <dir>] [--baseline <csv>] [--repo-root <dir>] [--json]`
+  Plans the legacy-path migration: lists every knowledge doc a tier clone
+  holds at the workspace path (`operator/knowledge/...`), where no registry
+  mount reads it, and says what moving it to the mounted path takes.
+  Read-only (no vault, no ingest, no network beyond `git fetch` of the
+  clones), so it runs in SIMPLE and REMOTE mode. See
+  [Legacy-path migration](#legacy-path-migration-library-migrate-mounts).
+
+- `library migrate-mounts --apply --tier <name> --out <dir> [--clone <path>]... [--batch-size <n>] [--batches 1|all] [--merged-dir <dir>] [--wait-ms <n>] [--poll-ms <n>]`
+  Moves one tier's legacy rows to the mounted path in verified batches
+  through the ingest, and stops on the first divergence. REMOTE mode only.
+  See [Apply](#apply---apply).
+
 ### Scope rule (verbatim)
 
 ```
@@ -136,6 +149,172 @@ Every verb accepts `--help` and `-h` and prints that verb's usage before any
 config or vault resolution runs, so verb-level help has the same vault-free
 guarantee as the top-level `library --help`.
 
+## Legacy-path migration (`library migrate-mounts`)
+
+Writers before 0.1.64 sent knowledge docs to the tier repos at the workspace
+path, so a tier can hold `operator/knowledge/R` (the legacy form, read only
+through the reader's bridge) beside or instead of the mounted form
+(w-2026-10-16-dave-019). `library migrate-mounts` plans the move back.
+
+**Clones and registry.** Every clone under the pull-clones root, or the
+`--clone` list, each resolved to its registry key (origin remote, else
+directory name); `--tier` limits the run (a registry key or short name such
+as `hq`). The registry is the company clone among the planned clones, else
+the one `library put` uses (the company clone among
+`LIBRARY_KNOWLEDGE_EXTRA_ROOTS`, else `operator/registry/repos.json`); none
+exits 2 naming every place looked. Each clone is planned at `origin/main`
+(else `HEAD`, or `--ref`) after a `git fetch origin` unless `--no-fetch`;
+the sha is recorded.
+
+**Target (tier-preserving).** With R the path after `operator/knowledge/`,
+the tier's one knowledge mount gives the target `<from>R` and the workspace
+id `<to>R`, which the shared mount map's `resolveWrite` must confirm:
+
+| Tier | Legacy row | Target | Workspace id |
+|---|---|---|---|
+| hq | `operator/knowledge/x.md` | `knowledge/x.md` | `operator/knowledge/x.md` |
+| hq | `operator/knowledge/writing/x.md` | `knowledge/writing/x.md` (stays in hq) | `operator/knowledge/writing/x.md` |
+| wsd | `operator/knowledge/x.md` | `knowledge/x.md` | `operator/knowledge/wsd/x.md` (the id moves) |
+| operator-barry-private | any | none: no knowledge mount | `owner-decision` |
+| wsd | `operator/knowledge/wsd/R` | `knowledge/R` (same tier, ordinary actions) | `operator/knowledge/wsd/R` (the id stays) |
+| any other | `operator/knowledge/wsd/R` | wsd `knowledge/R` (`cross-tier`) | `operator/knowledge/wsd/R` |
+
+A tier with more than one knowledge mount, or a `resolveWrite`
+disagreement, gives `unmappable`.
+
+**Cross-tier rows (Dave ruling 2026-10-19).** A legacy row under
+`operator/knowledge/wsd/` is a wsd workspace path, so its target is the one
+`resolveWrite` gives in `stravica-library-wsd` (`knowledge/R`), never the
+tier-preserving nest at `knowledge/wsd/R` (workspace id
+`operator/knowledge/wsd/wsd/R`). Whether it is cross-tier is decided by tier
+identity, not by the prefix: a row is `cross-tier` only when its own tier
+differs from the tier its target belongs to. In the wsd tier such a row is an
+ordinary same-tier row (`re-put`, `delete`, `take-legacy`, `take-mounted`
+or `merge`) with the legacy path as its workspace id. In any other tier it
+gets the action `cross-tier`, and `--apply` never writes it (the planned
+tier's writer may hold no wsd subkey, and the move is the wsd owner's from a
+wsd host). `<dir>/cross-tier.csv` lists every one with
+`sourceTier,legacyPath,legacyBlob,targetTier,targetPath,targetBlob,workspaceId,crossKind,targetSha,reason`;
+`crossKind` is `move` (no wsd copy), `identical`, `merge` (a wsd copy that
+differs; the merge rule applies) or `unknown` (no wsd clone among the
+clones). They still count as legacy rows for `--check`, and a baseline
+`correct` that differs on one is printed as resolved by the ruling, not as
+a disagreement.
+
+Open step (not built): once a cross-tier row lands in its target tier (the
+wsd owner applies the move or merge from a wsd host), the source tier's
+legacy copy still needs a `knowledge.doc.delete` in the source tier.
+`--apply` does not do it yet, so `--check` keeps naming the row until that
+delete lands.
+
+**Actions**, from the blob shas at the planned sha, never from commit time:
+
+| Action | When | Body the apply posts |
+|---|---|---|
+| `re-put` | the mounted path is absent | the legacy body |
+| `delete` | both paths hold the same blob | none (legacy copy deleted) |
+| `take-legacy` | the mounted blob is in the legacy path's history | the legacy body |
+| `take-mounted` | the legacy blob is in the mounted path's history | none (legacy copy deleted) |
+| `merge` | anything else | a merged body, written first |
+| `cross-tier` | the path is under `operator/knowledge/wsd/` in a tier other than wsd | none: never applied, listed in `cross-tier.csv` |
+
+**Plan CSV.** `--dry-run --out <dir>` writes `<dir>/plan-<tier>.csv`
+(`<tier>` is the registry key without `stravica-`, for example
+`library-hq`) with the columns
+`tier,current,correct,action,writer,indexed,home,reason,bothExist,legacyBlob,mountedBlob,workspaceId,body,baseline`.
+`writer` is `librarian` when the legacy body's frontmatter has
+`distilledBy:`, else `put`. `indexed` (the legacy id is a node in
+`operator/knowledge/.graph.json`) and `home` (`absent`, `same-as-mounted`,
+`same-as-mispathed` or `differs`, for the home copy at the workspace id)
+need `--repo-root`; otherwise they read `unknown`. With `--baseline <csv>`
+each row is `in-baseline` or `new-since-baseline`, baseline rows no longer
+present count as gone, and a common row whose `correct` differs is printed
+on stderr. One summary line per tier:
+
+```
+library-hq @f3f313e: 548 legacy rows: re-put 520, delete 1, take-legacy 0, take-mounted 0, merge 27, owner-decision 0, unmappable 0; new since baseline 32, gone 0
+```
+
+Without `--out` the CSV (one header for every tier) goes to stdout and the
+summary lines to stderr.
+
+**Merge kit.** For every `merge`, `take-legacy` and `take-mounted` row,
+`<dir>/merge/<tier>/<R>.legacy`, `.mounted`, `.diff` (unified, mounted copy
+a/ to legacy copy b/) and `.home` when the home copy matches neither, plus
+`<dir>/merge/README.md`. Merged bodies go to `<merged-dir>/<tier>/<R>`:
+keep the Librarian additions from the legacy copy and the newer operator
+edits from the mounted copy, and resolve conflicts on purpose. Nothing is
+written outside `--out`.
+
+**Check.** `--check` exits 0 when every selected tier holds no legacy row
+other than `owner-decision` rows (each named on stderr) and 2 otherwise.
+`--json` prints `{ tiers: [{ repo, ref, sha, legacyCount, byAction,
+ownerDecision: [path], crossTier: [...] }] }`.
+
+### Apply (`--apply`)
+
+`library migrate-mounts --apply --tier <name> --out <dir>` moves ONE tier's
+rows to the mounted path through the ingest, as ordinary events. REMOTE mode
+only (SIMPLE exits 1, like every write verb). It needs the company clone
+among the clones (the reader check reads its registry), refuses a tier with
+no knowledge mount (exit 2) and a clone with uncommitted changes, and always
+fetches (`--no-fetch` is refused).
+
+Each invocation re-plans the tier live and takes the eligible rows in plan
+order: `re-put`, `delete`, `take-legacy`, `take-mounted`, and `merge` rows
+whose merged body exists at `<merged-dir>/<tier>/<R>`. Every other row
+(`owner-decision`, `unmappable`, `cross-tier`, a `merge` with no merged
+body) is skipped and listed. The first 25 (`--batch-size`, 1 to 100) form
+the batch; `--batches all` repeats until nothing is eligible or a divergence
+stops it. Then, per batch:
+
+1. **Compare-and-swap.** Fetch and re-read both blobs of every batch row;
+   any change since the plan is `state-changed`.
+2. **Upserts.** `knowledge.doc.upsert` with `payload.path` the target,
+   `tier` the registry key, `provenance.sourcePath` the workspace id, and
+   the legacy body (`re-put`, `take-legacy`) or the merged body (`merge`).
+   An ack other than accepted or deduped is `rejected:<reason>`.
+3. **Wait** until each target blob equals the posted body's blob
+   (`--wait-ms`, default 300000; `--poll-ms`, default 10000): a timeout is
+   `not-applied`, another blob is `content-mismatch`.
+4. **Deletes.** `knowledge.doc.delete` of the legacy path verbatim, only for
+   rows whose mounted copy verified (phase 3, or phase 1 for `delete` and
+   `take-mounted`).
+5. **Wait** until each legacy path is absent (same bound).
+6. **Reader check.** Fast-forward the clone, then the reader over an empty
+   home (`scanSourcesFor`, `locateScannedFile`) must resolve each workspace
+   id to `<clone>/<target>` with the posted (or planned mounted) body's
+   sha256; otherwise `reader-mismatch`.
+
+The first divergence stops the invocation: no further post of any kind, and
+a legacy copy is never deleted unless its mounted copy verified. Upserted
+docs whose legacy copy is still there are safe (the reader's bridge serves
+the newer mounted copy) and the next run re-plans them. A divergence writes
+`<out>/divergence-<batchId>.json` and exits 2.
+
+Event ids are deterministic: a uuid v5 over `migrate-mounts`, the repo key,
+the event action (`upsert` or `delete`), the path, the body's blob sha and
+the last commit that touched the path at the planned sha. A rerun after a
+crash, with the path untouched since, dedups at the ingest, and a second
+full run posts nothing; once the path has changed (the worker wrote another
+body, or a stale writer brought a legacy copy back) the corrective post
+gets a new id rather than being deduped forever.
+
+Each batch writes `<out>/batches/<repoKey>-<UTC stamp>.json`: `batchId`,
+`tier`, `ref`, `tierShaBefore`, `tierShaAfter`, `startedAt`, `finishedAt`,
+`rows[]` (`action`, `legacyPath`, `mountedPath`, `workspaceId`,
+`preLegacyBlob`, `preMountedBlob`, `postedBlob`, `mergedBodySha256`,
+`upsertEventId`, `deleteEventId`, `verified: { mounted, legacyGone,
+reader }`, `divergence`), `skipped[]`, `crossTier[]` and `rollback`. There
+is no rollback mode: every pre-state copy is `git show <tierShaBefore>:<path>`
+in the tier; to restore a mounted copy, put that body at its workspace path
+with `library put`; legacy copies are not restored. One line per batch on
+stdout:
+
+```
+library-hq batch stravica-library-hq-20261019T120000000Z: posted 22 upserts, 25 deletes; verified 25 of 25; skipped 30; divergence none
+```
+
 ## Configuration
 
 - `operator/config/preferences.json` (base) and `preferences.local.json`

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

@@ -15,7 +15,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { loadLibraryConfig, LibraryConfigError } from './config.mjs';
+import { loadLibraryConfig, LibraryConfigError, readMergedPreferences, resolveDefaultRepoRoot } from './config.mjs';
 import { runPut } from './verbs/put.mjs';
 import { runFlush } from './verbs/flush.mjs';
 import { runGet } from './verbs/get.mjs';
@@ -23,6 +23,7 @@ import { runSearch } from './verbs/search.mjs';
 import { runStatus } from './verbs/status.mjs';
 import { runRefreshClones } from './verbs/refresh-clones.mjs';
 import { runUpMerge } from './verbs/up-merge.mjs';
+import { runMigrateMounts } from './migrate/verb.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -54,6 +55,10 @@ Usage:
   library status [--json]
   library refresh-clones [--json] [--timeout-ms <n>] [--tier <name>]...
   library up-merge [--repo <owner/name>]... [--pr <number>] [--dry-run] [--once] [--verbose] [--json]
+  library migrate-mounts --dry-run|--check [--tier <name>]... [--clone <path>]... [--ref <ref>]
+                         [--no-fetch] [--out <dir>] [--baseline <csv>] [--repo-root <dir>] [--json]
+  library migrate-mounts --apply --tier <name> --out <dir> [--clone <path>]... [--batch-size <n>]
+                         [--batches 1|all] [--merged-dir <dir>] [--wait-ms <n>] [--poll-ms <n>]
   library <verb> -h | --help
   library -h | --help
   library -v | --version
@@ -61,8 +66,10 @@ Usage:
 Reads config from operator/config/preferences.json (+ preferences.local.json overlay).
 Verbs are only active in REMOTE mode. SIMPLE mode 'library status' prints a
 one-line mode summary and exits 0; 'library up-merge' is a GitHub-side
-maintenance verb and runs in both SIMPLE and REMOTE mode; every other verb
-exits 1 in SIMPLE mode with a clean not-applicable message.
+maintenance verb and runs in both SIMPLE and REMOTE mode; 'library
+migrate-mounts --dry-run|--check' is read-only (no vault, no ingest) and runs
+in both modes ('--apply' is REMOTE only); every other verb exits 1 in SIMPLE mode with a clean
+not-applicable message.
 
 --help and --version never touch config or the vault, so they always work
 from a directory with no operator config and no vault installed. Per-verb
@@ -166,6 +173,70 @@ const VERB_USAGE = {
   left open with a one-time comment (idempotent via an HTML marker) and no
   merge is ever attempted. Runs in both SIMPLE and REMOTE mode (GitHub-side
   maintenance verb, no ingest touch). Config in the 'library.upMerge' stanza.
+`,
+  'migrate-mounts': `library migrate-mounts --dry-run|--check [--tier <name>]... [--clone <path>]...
+                       [--ref <ref>] [--no-fetch] [--out <dir>] [--baseline <csv>]
+                       [--repo-root <dir>] [--json]
+       library migrate-mounts --apply --tier <name> --out <dir> [--clone <path>]...
+                       [--batch-size <n>] [--batches 1|all] [--merged-dir <dir>]
+                       [--wait-ms <n>] [--poll-ms <n>] [--ref <ref>]
+
+  Plans the legacy-path migration (w-2026-10-16-dave-019): every file under
+  operator/knowledge/ in a tier clone is a legacy row that no registry mount
+  reads. Read-only: no vault, no ingest, no network beyond 'git fetch' of the
+  clones; runs in SIMPLE and REMOTE mode.
+
+  Cross-tier (Dave ruling 2026-10-19): a row under operator/knowledge/wsd/
+  is a wsd workspace path, target wsd knowledge/R. Outside the wsd tier it
+  is cross-tier: never applied, listed with both blobs in
+  <out>/cross-tier.csv. In the wsd tier it takes the ordinary actions, with
+  the legacy path as its workspace id.
+
+  Target (tier-preserving): R is the path after operator/knowledge/; the
+  tier's one knowledge mount gives the target <from>R and the workspace id
+  <to>R (hq knowledge/R; wsd knowledge/R with id operator/knowledge/wsd/R).
+  No knowledge mount: owner-decision. More than one: unmappable.
+  Actions, by blob: mounted path absent re-put; same blob delete; mounted
+  blob in the legacy path's history take-legacy; legacy blob in the mounted
+  path's history take-mounted; anything else merge. Never by commit time.
+
+  --dry-run         Write <out>/plan-<tier>.csv and the merge kit
+                    (<out>/merge/), and print one summary line per tier.
+                    Without --out the CSV goes to stdout, summaries to stderr.
+  --check           Exit 0 when every selected tier holds no legacy row other
+                    than owner-decision rows (each named on stderr), else 2.
+  --tier <name>     Repeatable; a registry key or short name (hq, library-wsd).
+  --clone <path>    Repeatable; the clones to plan. Default: every clone under
+                    the pull-clones root.
+  --ref <ref>       Default origin/main when it resolves, else HEAD.
+  --no-fetch        Skip 'git fetch origin' in each clone.
+  --baseline <csv>  Mark rows in-baseline or new-since-baseline; count rows
+                    gone and print any 'correct' disagreement on stderr.
+  --repo-root <dir> Fill 'indexed' (operator/knowledge/.graph.json) and 'home'
+                    (the home copy at the workspace id); else 'unknown'.
+  --json            Print { tiers: [{ repo, ref, sha, legacyCount, byAction,
+                    ownerDecision, crossTier }] } instead of the summary lines.
+
+  --apply           REMOTE mode only. Re-plans ONE tier live (with fetch) and
+                    moves one batch of its eligible rows (re-put, delete,
+                    take-legacy, take-mounted, merge with a merged body) to
+                    the mounted path through the ingest: compare-and-swap,
+                    upserts, wait for each target blob, delete the legacy
+                    path only behind a verified mounted copy, wait for it to
+                    go, then the reader must resolve each workspace id to the
+                    mounted file with the posted body's sha256. The first
+                    divergence stops the run (exit 2, <out>/divergence-<id>.json).
+                    Event ids are deterministic (uuid v5), so a rerun dedups.
+                    Writes <out>/batches/<repo>-<UTC stamp>.json (rows, skipped,
+                    rollback note) and <out>/cross-tier.csv. Needs the company
+                    clone among the clones; refuses a tier with no knowledge
+                    mount (exit 2) and a dirty clone.
+  --batch-size <n>  Rows per batch, 1 to 100. Default 25.
+  --batches 1|all   One batch (default) or repeat until nothing is eligible.
+  --merged-dir <d>  Merged bodies at <d>/<tier>/<R>; a merge row without one
+                    is skipped.
+  --wait-ms <n>     Bound per wait phase. Default 300000.
+  --poll-ms <n>     Poll interval in a wait phase. Default 10000.
 `,
 };
 
@@ -204,6 +275,57 @@ export async function main(argv, seams = {}) {
     return 0;
   }
 
+  // `library migrate-mounts --dry-run|--check` is read-only: it needs the
+  // preferences (pull-clone root) and the repo root (registry fallback) but
+  // never the vault or the ingest, so it is routed before loadLibraryConfig
+  // (which resolves a vault-ref remoteKey in REMOTE mode) and therefore
+  // before the SIMPLE-mode refusal, as up-merge is.
+  if (verb === 'migrate-mounts') {
+    let args;
+    try {
+      args = parseMigrateMounts(rest);
+    } catch (e) {
+      err(`[library migrate-mounts] ${e.message ?? e}`);
+      return 1;
+    }
+    try {
+      const repoRoot = seams.repoRoot ?? resolveDefaultRepoRoot();
+      const preferences = readMergedPreferences({
+        base: join(repoRoot, 'operator', 'config', 'preferences.json'),
+        local: join(repoRoot, 'operator', 'config', 'preferences.local.json'),
+      });
+      // --apply writes through the ingest: REMOTE mode only, like every
+      // other write verb, with the same SIMPLE-mode refusal.
+      let config;
+      if (args.mode === 'apply') {
+        config = loadLibraryConfig({ repoRoot: seams.repoRoot });
+        if (config.mode === 'simple') {
+          err('[library migrate-mounts] --apply is not applicable in simple mode (library.mode="simple"); '
+            + 'it writes through the ingest. --dry-run and --check run in both modes.');
+          return 1;
+        }
+      }
+      return await runMigrateMounts({
+        args,
+        repoRoot,
+        preferences,
+        env: seams.env ?? process.env,
+        log,
+        err,
+        git: seams.migrateGit,
+        remoteOf: seams.remoteOf,
+        config,
+        fetchImpl: seams.fetchImpl,
+        clock: seams.migrateClock,
+        sleep: seams.migrateSleep,
+        hooks: seams.migrateHooks,
+      });
+    } catch (e) {
+      err(`[library migrate-mounts] ${e.message ?? e}`);
+      return typeof e.exitCode === 'number' ? e.exitCode : 2;
+    }
+  }
+
   let config;
   try {
     config = loadLibraryConfig({ repoRoot: seams.repoRoot });
@@ -298,6 +420,66 @@ function parsePut(argv) {
     verbatimPath: values['verbatim-path'],
   };
 }
+function parseMigrateMounts(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: false,
+    options: {
+      'dry-run':   { type: 'boolean', default: false },
+      check:       { type: 'boolean', default: false },
+      apply:       { type: 'boolean', default: false },
+      tier:        { type: 'string', multiple: true },
+      clone:       { type: 'string', multiple: true },
+      ref:         { type: 'string' },
+      'no-fetch':  { type: 'boolean', default: false },
+      out:         { type: 'string' },
+      baseline:    { type: 'string' },
+      'repo-root': { type: 'string' },
+      json:        { type: 'boolean', default: false },
+      'batch-size': { type: 'string' },
+      batches:     { type: 'string' },
+      'merged-dir': { type: 'string' },
+      'wait-ms':   { type: 'string' },
+      'poll-ms':   { type: 'string' },
+    },
+  });
+  const modes = ['dry-run', 'check', 'apply'].filter((m) => values[m]);
+  if (modes.length !== 1) {
+    throw new Error('exactly one of --dry-run, --check or --apply is required');
+  }
+  const intFlag = (name, min, max) => {
+    const raw = values[name];
+    if (raw === undefined) return undefined;
+    const n = Number(raw);
+    if (!/^\d+$/.test(raw) || n < min || n > max) throw new Error(`--${name} must be an integer from ${min} to ${max}`);
+    return n;
+  };
+  const applyOnly = ['batch-size', 'batches', 'merged-dir', 'wait-ms', 'poll-ms'].filter((k) => values[k] !== undefined);
+  if (modes[0] !== 'apply' && applyOnly.length) throw new Error(`--${applyOnly[0]} is for --apply only`);
+  if (modes[0] === 'apply') {
+    if ((values.tier ?? []).length !== 1) throw new Error('--apply needs exactly one --tier');
+    if (!values.out) throw new Error('--apply needs --out <dir>');
+    if (values['no-fetch']) throw new Error('--apply always fetches; --no-fetch is for --dry-run and --check');
+    if (values.batches !== undefined && !['1', 'all'].includes(values.batches)) throw new Error('--batches must be 1 or all');
+  }
+  return {
+    mode: modes[0],
+    tiers: values.tier ?? [],
+    clones: values.clone ?? [],
+    ref: values.ref,
+    fetch: !values['no-fetch'],
+    out: values.out,
+    baseline: values.baseline,
+    repoRoot: values['repo-root'],
+    json: values.json,
+    batchSize: intFlag('batch-size', 1, 100),
+    batches: values.batches ?? '1',
+    mergedDir: values['merged-dir'],
+    waitMs: intFlag('wait-ms', 1, 3600000),
+    pollMs: intFlag('poll-ms', 1, 600000),
+  };
+}
 function parseFlush(argv) {
   parseArgs({ args: argv, strict: true, allowPositionals: true, options: {} });
   return {};

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

@@ -149,6 +149,10 @@ export function guessKindFromPath(sourcePath) {
  *   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 {string} [args.clientEventId]  a caller-chosen event id (a uuid)
+ *   for an idempotent rerun: `library migrate-mounts --apply` derives one
+ *   per row so the ingest dedups a repeat post (w-2026-10-16-dave-019 slice
+ *   3). Absent: a fresh `randomUUID()`, unchanged.
  * @param {() => Date} [args.clock]  test seam
  * @returns {object} EventInput ready for POST /events
  */
@@ -162,6 +166,7 @@ export function buildEnvelope({
   sourceKind = 'manual',
   source,
   payloadPath,
+  clientEventId,
   clock = () => new Date(),
 }) {
   // Repo-relative resolution + refusal for anything that would encode as
@@ -274,7 +279,7 @@ export function buildEnvelope({
   }
 
   const envelope = {
-    clientEventId: randomUUID(),
+    clientEventId: clientEventId ?? randomUUID(),
     occurredAt: now.toISOString(),
     producer: {
       operator: producer.operator,