@stravica-ai/digital-operator-pa 0.1.29 → 0.1.31

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

@@ -13,7 +13,7 @@
 
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
-import { relative, isAbsolute } from 'node:path';
+import { isAbsolute, normalize, relative, sep } from 'node:path';
 
 import { EVENT_KINDS, canonicalJson } from '@stravica-ai/remote-library';
 
@@ -31,6 +31,47 @@ export function contentShaOf(payload) {
   return `sha256:${createHash('sha256').update(canonical).digest('hex')}`;
 }
 
+/**
+ * Refuse a source path that would encode as an escape from the repo root.
+ * Root-cause cure for the poison-event wedge Stream 5 re-verify Scope C
+ * surfaced (w-2026-08-24-dave-025, SA14). Called by buildEnvelope after
+ * relPath is computed. Semantics match the server's assertPathSafe
+ * (spec §4 apply gate): reject empty, absolute, NUL, drive-letter,
+ * root-backslash, `..`-segments, and any string that normalises to a
+ * path starting with `..`. The error names the input sourcePath and
+ * repoRoot so an operator can see immediately why the encoding refused.
+ *
+ * @param {string} relPath      candidate repo-relative path
+ * @param {string} sourcePath   original input (for the error message)
+ * @param {string} repoRoot     resolved repo root (for the error message)
+ * @throws {Error} with exitCode=1 if the path is unsafe
+ */
+export function assertRepoRelativeSafe(relPath, sourcePath, repoRoot) {
+  const fail = (reason) => {
+    const err = new Error(
+      `refusing to encode source path outside repo root (${reason}): ` +
+        `sourcePath=${JSON.stringify(sourcePath)}, repoRoot=${JSON.stringify(repoRoot)}, ` +
+        `resolvedRelative=${JSON.stringify(relPath)}. ` +
+        `Move the file into the repo or stage it under a repo-resident path before calling library put.`,
+    );
+    err.exitCode = 1;
+    throw err;
+  };
+  if (typeof relPath !== 'string') fail('path must be a string');
+  if (relPath.length === 0) fail('path resolves empty');
+  if (relPath.includes('\0')) fail('path contains NUL byte');
+  if (isAbsolute(relPath)) fail('resolved path is absolute');
+  if (/^[A-Za-z]:[\\/]/.test(relPath) || relPath.startsWith('\\')) {
+    fail('drive-letter or root-backslash path');
+  }
+  const parts = relPath.split(/[/\\]/);
+  if (parts.some((seg) => seg === '..')) fail("'..' segments not permitted");
+  const normalised = normalize(relPath);
+  if (normalised === '..' || normalised.startsWith('..' + sep) || normalised.startsWith('../')) {
+    fail('path normalises outside repo root');
+  }
+}
+
 /**
  * Guess the event kind from a staging file path when the operator did
  * not supply one via `--kind`. Falls back to
@@ -49,21 +90,37 @@ export function guessKindFromPath(sourcePath) {
 }
 
 /**
- * Build a `knowledge.observation.staged` envelope for a staging file.
- * The payload carries `path` (destination hint — the worker's apply
- * function decides the actual write path) and the raw markdown body.
- * `frontmatter` is left absent; the worker parses it if present in the
- * body.
+ * Build an EventInput envelope for one file.
+ *
+ * The envelope construction is uniform across every kind (clientEventId,
+ * occurredAt, producer, tier, provenance, contentSha). Only the
+ * `payload` sub-object is per-kind: `knowledge.doc.delete` carries
+ * `{path, source?}` (deletion — no content field; the ingest schema
+ * refuses `content` as an additionalProperty for this kind, spec §3.1 +
+ * `remote-library` `src/schema/payloads.ts`), while every other kind
+ * currently ships as `{path, content}` (content-bearing). This mapping
+ * is intentionally narrow: only the delete branch differs. Every
+ * non-delete kind's payload shape is preserved byte-for-byte from the
+ * pre-cure encoding, so nothing else can regress (asserted by the
+ * envelope regression test).
+ *
+ * For the `knowledge.observation.staged` default the payload carries
+ * `path` (destination hint — the worker's apply function decides the
+ * actual write path) and the raw markdown body. `frontmatter` is left
+ * absent; the worker parses it if present in the body.
  *
  * @param {object} args
  * @param {string} args.repoRoot
  * @param {string} args.sourcePath   absolute or repo-relative
- * @param {string} args.content
+ * @param {string} [args.content]    ignored for `knowledge.doc.delete`
  * @param {object} args.producer     { operator, agent, host?, session?, subkeyId }
  * @param {string} [args.kind]       overrides guess; must be in KNOWN_KINDS
  * @param {string} [args.tier]       default "auto" sentinel (spec §2.3)
  * @param {'staging'|'flush'|'role-output'|'manual'|'synthesis'} [args.sourceKind]
  *   default "manual"; `library flush` passes "flush"
+ * @param {string} [args.source]     optional routing hint; only encoded
+ *   into the payload for `knowledge.doc.delete` (mirrors the schema's
+ *   optional `source` field for the delete kind — spec §3.1 shape).
  * @param {() => Date} [args.clock]  test seam
  * @returns {object} EventInput ready for POST /events
  */
@@ -75,11 +132,25 @@ export function buildEnvelope({
   kind,
   tier = 'auto',
   sourceKind = 'manual',
+  source,
   clock = () => new Date(),
 }) {
+  // Repo-relative resolution + refusal for anything that would encode as
+  // a `..`-segment or otherwise escape the repo root. This is the root
+  // cause cure for the Stream 5 re-verify Scope C poison-event wedge
+  // (w-2026-08-24-dave-025). Before this cure `relative(repoRoot, abs)`
+  // silently produced `../../etc/...` for files sitting outside the
+  // repo and the envelope was posted with a payload path the worker's
+  // apply gate would later refuse — halting single-writer propagation
+  // for the whole estate. Refusing here (client-side, at encoding time)
+  // stops the poison at source; SA14's ingest-side check is the second
+  // line; the worker's apply gate remains the third.
   const relPath = sourcePath
     ? isAbsolute(sourcePath) ? relative(repoRoot, sourcePath) : sourcePath
     : undefined;
+  if (relPath !== undefined) {
+    assertRepoRelativeSafe(relPath, sourcePath, repoRoot);
+  }
 
   const resolvedKind = kind ?? guessKindFromPath(relPath ?? sourcePath ?? '') ?? null;
   if (!resolvedKind) {
@@ -98,10 +169,27 @@ export function buildEnvelope({
   }
 
   const now = clock();
-  const payload = {
-    path: relPath ?? null,
-    content,
-  };
+  // Per-kind payload construction (spec §3.1 + `remote-library` payload
+  // schema). Fix Wave E (w-2026-08-24-dave-029): before this branch the
+  // envelope encoded `{path, content}` for every kind, and the ingest
+  // schema for `knowledge.doc.delete` refused the `content` key with
+  // 422 (additionalProperties:false, required=["path"]). Result: the
+  // delete verb structurally could not succeed via the CLI — the same
+  // deferred-defect class the retirement programme is here to close.
+  // The delete branch omits `content` and (optionally) attaches
+  // `source`. Every other kind keeps the pre-cure `{path, content}`
+  // shape byte-for-byte; the regression test in envelope.test.mjs
+  // asserts that determinism against a frozen contentSha.
+  const payload =
+    resolvedKind === 'knowledge.doc.delete'
+      ? {
+          path: relPath ?? null,
+          ...(source !== undefined ? { source } : {}),
+        }
+      : {
+          path: relPath ?? null,
+          content,
+        };
 
   const envelope = {
     clientEventId: randomUUID(),

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

@@ -26,7 +26,14 @@ export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
     log('usage: library put <path> [--kind <kind>] [--tier auto|<tier>]');
     return 1;
   }
-  const content = await readFile(path, 'utf8');
+  // Delete events carry no content by spec (§3.1 payload schema); the
+  // operator can and typically will have removed the file locally before
+  // asking the tier remote to catch up. Reading a file that does not
+  // exist would be a spurious ENOENT — so we skip the read entirely for
+  // 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 producer = producerFromPreferences(config);
   const envelope = buildEnvelope({

package/package.json

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