simt-dev 0.6.3 → 0.7.1

package/src/memory/lessons.mjs

@@ -13,20 +13,64 @@
 
 import { createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, open, readdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 
 import { postDeliveryJson } from '../agenthooks/render.mjs';
 import { lessonPaths } from '../index/govern.mjs';
+import { recordCreatedFile } from '../journal.mjs';
+import { redactText } from '../secrets.mjs';
+import { localRel, readStateFile } from '../state.mjs';
 import { splitFrontmatter } from './decide.mjs';
 
 const exec = promisify(execFile);
 
-export const LESSONS_FILE = '.simt/lessons.jsonl';
+export const LESSONS_FILE = localRel('lessons.jsonl');
+const LESSONS_FILE_LEGACY = '.simt/lessons.jsonl';
+const LEDGER_REL = localRel('ledger.jsonl');
+const LEDGER_REL_LEGACY = '.simt/ledger.jsonl';
 export const LESSONS_DIR = 'docs/lessons';
 export const LESSON_KEYS = new Set(['simt-trigger', 'simt-evidence', 'simt-expires']);
-const DEFAULT_EXPIRES = '2027-04-01';
+
+/**
+ * A stored `fixDiff` is evidence, not an archive: the diff that proved the fix,
+ * capped so one generated-file revert cannot bloat every read of the ledger.
+ * Truncation keeps the head (the hunk headers that name the files) and says so.
+ */
+const FIX_DIFF_BUDGET = 20000;
+
+/**
+ * The default expiry is relative to the promotion, not a date in the source:
+ * a fixed date rots (every lesson written today expires on someone else's
+ * schedule) and a missing one lives forever because nothing reads the field.
+ * Half a year is long enough to recur and short enough to re-earn.
+ */
+const EXPIRY_DAYS = 180;
+
+export function defaultExpires(from = new Date()) {
+  const at = new Date(from);
+  at.setUTCDate(at.getUTCDate() + EXPIRY_DAYS);
+  return at.toISOString().slice(0, 10);
+}
+
+/**
+ * Whether a `simt-expires` value has passed. Unparseable values are NOT expired:
+ * a malformed date is a data error the reader should see, and hiding the lesson
+ * would turn it into a silent one (review 0003 Q36).
+ *
+ * @param {string|null|undefined} expires
+ * @param {Date} [now]
+ * @returns {boolean}
+ */
+export function isExpired(expires, now = new Date()) {
+  if (expires === null || expires === undefined || String(expires).trim() === '') return false;
+  const at = new Date(String(expires).trim());
+  if (Number.isNaN(at.getTime())) return false;
+  const today = new Date(now);
+  today.setUTCHours(0, 0, 0, 0);
+  return at.getTime() < today.getTime();
+}
 
 const STOP_WORDS = new Set([
   'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'when', 'were',
@@ -143,13 +187,14 @@ function slugify(text) {
  * @returns {Promise<{candidates: Array<object>, errors: string[]}>}
  */
 export async function readLessonCandidates(root) {
+  // The pre-move path is a fallback for one release (review 0003 Q19).
   let text;
   try {
-    text = await readFile(join(root, LESSONS_FILE), 'utf8');
+    ({ text } = await readStateFile(root, LESSONS_FILE, [LESSONS_FILE_LEGACY]));
   } catch (error) {
-    if (error.code === 'ENOENT') return { candidates: [], errors: [] };
     throw error;
   }
+  if (text === null) return { candidates: [], errors: [] };
   const candidates = [];
   const errors = [];
   for (const [i, raw] of text.split('\n').entries()) {
@@ -175,15 +220,69 @@ async function writeLessonCandidates(root, candidates) {
   await writeFile(full, body ? `${body}\n` : '', 'utf8');
 }
 
+/**
+ * Append one record with `O_APPEND`: the ledger is written by concurrent
+ * processes (gates, hooks, the CLI), and a read-modify-write loses one of two
+ * simultaneous appends. The position is the kernel's, not a length read earlier.
+ *
+ * @param {string} root
+ * @param {object} record
+ */
+async function appendCandidateLine(root, record) {
+  const full = join(root, LESSONS_FILE);
+  await mkdir(dirname(full), { recursive: true });
+  const handle = await open(full, 'a');
+  try {
+    await handle.appendFile(`${JSON.stringify(record)}\n`, 'utf8');
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * The candidate id is a content hash, not a counter. Ids were `c-${length+1}`:
+ * two processes appending concurrently computed the same next index, and a
+ * hand-edited or truncated file renumbered everything after it. The hash covers
+ * the fields that make a candidate distinct, so the same candidate always maps
+ * to the same id and two different ones never share it (review 0003 Q36).
+ *
+ * @param {{kind: string, signature: string, evidence: string[], cmd: string|null}} parts
+ * @returns {string}
+ */
+export function lessonIdFor({ kind, signature, evidence = [], cmd = null }) {
+  const digest = createHash('sha256')
+    .update([kind, signature, ...evidence, cmd ?? ''].join('\n'), 'utf8')
+    .digest('hex');
+  return `l-${digest.slice(0, 12)}`;
+}
+
+/**
+ * Truncate an unbounded diff to the evidence budget, keeping the head: the hunk
+ * headers that name the files are the part a reader acts on.
+ *
+ * @param {string} diff
+ * @returns {string}
+ */
+function capFixDiff(diff) {
+  const text = String(diff ?? '');
+  if (text.length <= FIX_DIFF_BUDGET) return text;
+  return `${text.slice(0, FIX_DIFF_BUDGET)}\n… (truncated to ${FIX_DIFF_BUDGET} chars)`;
+}
+
 function sameEvidence(a = [], b = []) {
   if (a.length !== b.length) return false;
   return a.every((v, i) => v === b[i]);
 }
 
 /**
- * Append one deterministic candidate to `.simt/lessons.jsonl`, deduplicating by
+ * Append one deterministic candidate to the lessons ledger, deduplicating by
  * `(kind, signature, evidence)`.
  *
+ * The stored text is redacted before anything else: candidates keep the raw
+ * commands that failed, and a command can carry a token. Redaction runs before
+ * the signature is hashed so the same failure redacts to the same signature
+ * (review 0003 Q36).
+ *
  * @param {string} root
  * @param {object} candidate
  * @returns {Promise<object>}
@@ -191,15 +290,22 @@ function sameEvidence(a = [], b = []) {
 export async function appendLessonCandidate(root, candidate) {
   const { candidates } = await readLessonCandidates(root);
   const kind = String(candidate.kind ?? 'fail-then-fix');
-  const errorLine = normaliseErrorLine(candidate.errorLine ?? firstErrorLine(candidate.output ?? candidate.summary ?? ''));
+  // Redact first: the signature must be a function of the stored bytes, not of
+  // a secret nobody can reproduce (and must never be stored).
+  const errorLine = redactText(
+    normaliseErrorLine(candidate.errorLine ?? firstErrorLine(candidate.output ?? candidate.summary ?? '')),
+  );
   const signature = candidate.signature ?? errorSignature(errorLine);
-  const evidence = Array.isArray(candidate.evidence) ? candidate.evidence.map(String).filter(Boolean) : [];
+  const evidence = Array.isArray(candidate.evidence)
+    ? candidate.evidence.map((e) => redactText(String(e)).trim()).filter(Boolean)
+    : [];
+  const cmd = candidate.cmd === null || candidate.cmd === undefined ? null : redactText(String(candidate.cmd));
 
   const existing = candidates.find(
     (c) =>
       c.kind === kind &&
       c.signature === signature &&
-      (sameEvidence(c.evidence ?? [], evidence) || (c.cmd && candidate.cmd && c.cmd === candidate.cmd && c.evidence?.[0] === evidence[0])),
+      (sameEvidence(c.evidence ?? [], evidence) || (c.cmd && cmd && c.cmd === cmd && c.evidence?.[0] === evidence[0])),
   );
   if (existing) return existing;
 
@@ -208,28 +314,26 @@ export async function appendLessonCandidate(root, candidate) {
     : [];
   const keywords = Array.isArray(candidate.keywords) && candidate.keywords.length > 0
     ? [...new Set(candidate.keywords.map(String).filter(Boolean))]
-    : extractKeywords(`${errorLine} ${candidate.cmd ?? ''}`, paths);
+    : extractKeywords(`${errorLine} ${cmd ?? ''}`, paths);
 
-  const nextIndex = candidates.length + 1;
   const record = {
     v: 1,
-    id: candidate.id ?? `c-${String(nextIndex).padStart(4, '0')}`,
+    id: candidate.id ?? lessonIdFor({ kind, signature, evidence, cmd }),
     ts: candidate.ts ?? new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
     kind,
     signature,
     errorLine,
-    summary: String(candidate.summary ?? (errorLine || `${kind} candidate`)).trim(),
-    cmd: candidate.cmd ?? null,
+    summary: redactText(String(candidate.summary ?? (errorLine || `${kind} candidate`))).trim(),
+    cmd,
     paths,
     keywords,
     evidence,
-    fixDiff: String(candidate.fixDiff ?? ''),
+    fixDiff: capFixDiff(redactText(candidate.fixDiff ?? '')),
     status: candidate.status ?? 'candidate',
     promotedTo: candidate.promotedTo ?? null,
   };
 
-  candidates.push(record);
-  await writeLessonCandidates(root, candidates);
+  await appendCandidateLine(root, record);
   return record;
 }
 
@@ -306,8 +410,8 @@ export async function captureFromLedger(root, entries = null) {
   let list = entries;
   if (!Array.isArray(list)) {
     try {
-      const raw = await readFile(join(root, '.simt', 'ledger.jsonl'), 'utf8');
-      list = raw
+      const { text } = await readStateFile(root, LEDGER_REL, [LEDGER_REL_LEGACY]);
+      list = (text ?? '')
         .split('\n')
         .map((s) => s.trim())
         .filter(Boolean)
@@ -481,12 +585,13 @@ export async function recordHookDenial(root, denial) {
  * @returns {string}
  */
 export function renderLessonMarkdown(candidate, options = {}) {
+  // No `**` fallback: a trigger with no paths is a promotion the caller
+  // refused, not a lesson about everything. `promoteLesson` rejects those;
+  // this renders exactly the paths it was given (review 0003 Q36).
   const paths =
     Array.isArray(options.paths) && options.paths.length > 0
       ? options.paths
-      : Array.isArray(candidate.paths) && candidate.paths.length > 0
-        ? candidate.paths
-        : ['**'];
+      : (Array.isArray(candidate.paths) ? candidate.paths : []);
   const keywords =
     Array.isArray(options.keywords) && options.keywords.length > 0
       ? options.keywords
@@ -494,7 +599,7 @@ export function renderLessonMarkdown(candidate, options = {}) {
         ? candidate.keywords
         : extractKeywords(candidate.errorLine ?? candidate.summary ?? '', paths);
   const evidence = Array.isArray(candidate.evidence) ? candidate.evidence : [];
-  const expires = options.expires ?? DEFAULT_EXPIRES;
+  const expires = options.expires ?? defaultExpires();
   const title = String(options.title ?? candidate.summary ?? candidate.errorLine ?? 'Lesson').trim();
 
   const pathsLiteral = paths.map((p) => JSON.stringify(String(p))).join(', ');
@@ -528,7 +633,7 @@ export function renderLessonMarkdown(candidate, options = {}) {
  * @param {string} text
  * @returns {object}
  */
-export function parseLessonFile(id, text) {
+export function parseLessonFile(id, text, now = new Date()) {
   const { front: rawFront, body: rawBody } = splitFrontmatter(text);
   const front = rawFront ?? '';
   const body = rawBody.trim();
@@ -546,6 +651,7 @@ export function parseLessonFile(id, text) {
     : [];
   const expMatch = /^simt-expires:\s*(\S+)/m.exec(front);
   const expires = expMatch ? expMatch[1].trim() : null;
+  const expired = isExpired(expires, now);
 
   const titleMatch = /^#\s+(.+)$/m.exec(body);
   const title = titleMatch ? titleMatch[1].trim() : id;
@@ -566,16 +672,23 @@ export function parseLessonFile(id, text) {
     keywords,
     evidence,
     expires,
+    expired,
   };
 }
 
 /**
- * List all promoted lessons in `docs/lessons/*.md`.
+ * List the promoted lessons in `docs/lessons/*.md` that are still in force.
+ *
+ * `simt-expires` is read here, once, so every consumer — recall, `why`, the
+ * hook, the bench, `lessons list` — agrees on what has expired. Nothing was
+ * reading the field, so expired lessons kept firing indefinitely (review 0003
+ * Q36). Pass `includeExpired` to see the retired ones with `expired: true`.
  *
  * @param {string} root
+ * @param {{includeExpired?: boolean, now?: Date}} [options]
  * @returns {Promise<Array<object>>}
  */
-export async function listPromotedLessons(root) {
+export async function listPromotedLessons(root, { includeExpired = false, now = new Date() } = {}) {
   const dir = join(root, LESSONS_DIR);
   let names = [];
   try {
@@ -587,7 +700,8 @@ export async function listPromotedLessons(root) {
   for (const name of names) {
     const text = await readFile(join(dir, name), 'utf8');
     const id = name.replace(/\.md$/, '');
-    lessons.push(parseLessonFile(id, text));
+    const lesson = parseLessonFile(id, text, now);
+    if (!lesson.expired || includeExpired) lessons.push(lesson);
   }
   return lessons;
 }
@@ -612,17 +726,20 @@ async function nextLessonNumber(root) {
 }
 
 /**
- * Promote a lesson candidate from `.simt/lessons.jsonl` to `docs/lessons/NNNN-<slug>.md`.
+ * Promote a lesson candidate from the lessons ledger to `docs/lessons/NNNN-<slug>.md`.
+ *
+ * Capture is not promotion's business: `promoteLesson` used to scan the ledger
+ * first, so a preview (`review` without `--yes`) wrote to the store it was
+ * only reading. Capture is an explicit `lessons capture` now (review 0003 Q36).
  *
  * @param {string} root
- * @param {{id?: string, apply?: boolean, paths?: string[], expires?: string, title?: string}} [options]
+ * @param {{id?: string, apply?: boolean, paths?: string[], expires?: string, title?: string, journal?: object[]}} [options]
  * @returns {Promise<{ok: boolean, error?: string, candidate?: object, path?: string, markdown?: string, written?: boolean}>}
  */
 export async function promoteLesson(root, options = {}) {
-  await captureFromLedger(root);
   const { candidates } = await readLessonCandidates(root);
   if (candidates.length === 0) {
-    return { ok: false, error: 'no lesson candidates in .simt/lessons.jsonl' };
+    return { ok: false, error: `no lesson candidates in ${LESSONS_FILE}; capture some with: lessons capture` };
   }
 
   let target = null;
@@ -633,14 +750,31 @@ export async function promoteLesson(root, options = {}) {
     if (!target) {
       return { ok: false, error: `no lesson candidate matching "${options.id}"` };
     }
+    if (target.status === 'promoted') {
+      return { ok: false, error: `lesson candidate ${target.id} is already promoted to ${target.promotedTo}` };
+    }
   } else {
-    target = candidates.find((c) => c.status !== 'promoted') ?? candidates[0];
+    // A promoted candidate is done: falling back to it re-promotes the same
+    // lesson under a new number, which is how one candidate became 0001/0002/0003.
+    target = candidates.find((c) => c.status !== 'promoted') ?? null;
+    if (!target) {
+      return { ok: false, error: 'nothing to promote: every candidate is already promoted' };
+    }
+  }
+
+  // No `**` default: a trigger that watches every path fires on every failure,
+  // which is the same as firing on none. A pathless candidate needs `--paths`.
+  const paths = Array.isArray(options.paths) && options.paths.length > 0
+    ? options.paths
+    : (Array.isArray(target.paths) ? target.paths : []);
+  if (paths.length === 0) {
+    return { ok: false, error: `lesson candidate ${target.id} names no paths; pass --paths to say what it governs` };
   }
 
   const num = await nextLessonNumber(root);
   const slug = slugify(options.title ?? target.errorLine ?? target.summary ?? target.kind);
   const relPath = `${LESSONS_DIR}/${num}-${slug}.md`;
-  const markdown = renderLessonMarkdown(target, options);
+  const markdown = renderLessonMarkdown(target, { ...options, paths, expires: options.expires ?? defaultExpires() });
 
   // The `--diff` before-side, read before anything is written so the diff is true
   // in preview and in apply alike (R50). Always a creation in practice — the
@@ -657,6 +791,7 @@ export async function promoteLesson(root, options = {}) {
     const fullPath = join(root, relPath);
     await mkdir(dirname(fullPath), { recursive: true });
     await writeFile(fullPath, markdown, 'utf8');
+    if (Array.isArray(options.journal)) recordCreatedFile(root, options.journal, join(root, relPath), markdown);
     target.status = 'promoted';
     target.promotedTo = relPath;
     await writeLessonCandidates(root, candidates);

package/src/name.mjs

@@ -32,6 +32,15 @@ export const MANIFEST_FILE = 'simt.json';
 /** What the manifest file was called, and still is in every adopted repo. */
 export const MANIFEST_LEGACY = 'simt-dev.json';
 
+/** The projection lock: the input and output digests a frozen check compares, and the
+ *  locked `variants` winners `simt bench variants` records (ADR-086). */
+export const LOCK_FILE = 'simt.lock.json';
+
+/** What the lock was called. Read, not written: an adopted repo's lock under the old
+ *  name may hold variant winners nothing can regenerate, so it is read until the next
+ *  write migrates it (ADR-110). */
+export const LOCK_LEGACY = 'simt-dev.lock.json';
+
 /**
  * The namespace the generated region writes into a repository's files: the begin and end
  * markers, and the provenance header inside them. It follows the command, like the

package/src/node-version.mjs

@@ -0,0 +1,37 @@
+// The runtime floor, in one place both entry points read (review 0003 Q54).
+//
+// `package.json` declares `engines.node` and `pyproject.toml` declares a python
+// version; both are advisory to the installer, so an older runtime reached the CLI
+// and failed somewhere inside it — a syntax error, a missing API — instead of the one
+// sentence that says what to install. This module is deliberately tiny and has no
+// imports: the bootstrap that calls it must not load the tool that cannot run.
+
+/** The oldest Node this package runs on. Mirrors `package.json` `engines.node`. */
+export const MIN_NODE = '22.20.0';
+
+/**
+ * Whether `current` is at least `minimum`, compared component by component.
+ *
+ * A string compare is wrong ("9.0.0" > "22.20.0"), and `process.versions.node` may
+ * carry a pre-release suffix that `Number()` would turn into NaN, so the numeric
+ * prefix of each component is what counts.
+ *
+ * @param {string} current a version such as `22.20.0` or `23.1.0-rc.1`
+ * @param {string} [minimum]
+ * @returns {boolean}
+ */
+export function satisfiesMinimum(current, minimum = MIN_NODE) {
+  const parse = (value) =>
+    String(value)
+      .split('.')
+      .map((part) => Number.parseInt(part, 10))
+      .map((part) => (Number.isFinite(part) ? part : 0));
+  const have = parse(current);
+  const want = parse(minimum);
+  for (let i = 0; i < Math.max(have.length, want.length); i += 1) {
+    const a = have[i] ?? 0;
+    const b = want[i] ?? 0;
+    if (a !== b) return a > b;
+  }
+  return true;
+}

package/src/output/index.mjs

@@ -92,7 +92,27 @@ export function writeMode(flags) {
  * Truncation is always announced with an explicit line, never a silent ellipsis:
  * an agent that cannot tell a truncated answer from a complete one will guess.
  */
-export function emit(text, { maxBytes = 0, stream = process.stdout } = {}) {
+/**
+ * Answer one command's result on the surface the caller asked for.
+ *
+ * Every command that has both a document and a text report was choosing between them by
+ * hand, in the same five lines, in more than a dozen files - and a command that chose
+ * slightly differently printed a report where a caller had asked for JSON, which is how a
+ * script gets prose (review 0003 Q63).
+ *
+ * The renderer is a thunk because the surface is decided first: a command asked for JSON
+ * must not pay to render text nobody reads, and a caller cannot forget the branch.
+ */
+export function present(payload, renderText, flags) {
+  if (isJson(flags)) {
+    emitJson(payload);
+    return 'json';
+  }
+  emit(renderText());
+  return 'text';
+}
+
+export function emit(text, { maxBytes = maxBytesDefault, stream = process.stdout } = {}) {
   const body = text.endsWith('\n') ? text : `${text}\n`;
   const bytes = Buffer.byteLength(body);
   if (maxBytes > 0 && bytes > maxBytes) {
@@ -131,6 +151,19 @@ export const SCHEMA_VERSION = 1;
  */
 let prettyDefault = process.stdout.isTTY === true;
 
+// The byte ceiling is one flag with one reader: the envelope. Commands used to pass
+// `flags.maxBytes ?? 0` at seventy-eight call sites, which is seventy-eight chances to pass
+// a different number, or to forget and answer past the ceiling the caller set (review 0003
+// Q65). A ceiling of zero or a value that is not a number is no ceiling, the same way the
+// flag itself is read.
+let maxBytesDefault = 0;
+
+/** Set the byte ceiling every emit and every document inherits, from `--max-bytes`. */
+export function maxBytesLimit(bytes) {
+  const value = Number(bytes);
+  maxBytesDefault = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+
 export function jsonIndentDefault(pretty = process.stdout.isTTY === true) {
   prettyDefault = pretty;
 }
@@ -203,8 +236,83 @@ function fitJsonArrays(payload, maxBytes, pretty) {
   return null;
 }
 
-export function emitJson(value, { stream = process.stdout, pretty = prettyDefault, maxBytes = 0 } = {}) {
-  const payload = withSchemaVersion(value);
+/**
+ * Warnings a run accumulated, carried into the JSON document it prints.
+ *
+ * The same reason stderr is separate from stdout: a caller reading a document cannot
+ * see a note printed beside it. A command that ignored half of what it was asked still
+ * has to succeed or fail the same way, so the note belongs IN the result, and the text
+ * mode keeps the stderr line it already had (review 0003 Q62).
+ */
+let accumulated = [];
+
+// The path the dispatcher resolved. A command should not restate it: the ones that did
+// restated it wrongly (`plugin` printed `plugin claude`, `sync` printed `sync --check`),
+// and a document whose `command` disagrees with the argv that produced it is worse than
+// one with no `command` at all (review 0003 Q65).
+let canonicalCommand = null;
+
+/** Set the command path every JSON document will carry, or clear it with null. */
+export function jsonCommand(path) {
+  canonicalCommand = path ?? null;
+}
+
+// A document cannot name the exit code before the command has returned one. The
+// dispatcher captures what a command emits, then writes it once with the code attached;
+// writing first is how `ok: false` shipped alongside exit 0 (review 0003 Q65).
+let captured = null;
+
+/** Collect documents instead of writing them, so the dispatcher can add the exit code. */
+export function jsonCaptureStart() {
+  captured = [];
+}
+
+/** The captured documents and a reset, or an empty list when nothing was captured. */
+export function jsonCaptureTake() {
+  const docs = captured;
+  captured = null;
+  return docs;
+}
+
+/** Record a warning for the document this run prints. */
+export function warn(message) {
+  accumulated = [...accumulated, message];
+}
+
+/**
+ * Drop what a previous run in this process recorded.
+ *
+ * The collector is per process and a process can dispatch more than once - the MCP
+ * server and the tests both do. Without this, one command's notice appeared in the
+ * next command's document, which parity between the two surfaces caught (review 0003
+ * Q62).
+ */
+export function clearWarnings() {
+  accumulated = [];
+}
+
+/** The warnings this run has recorded, in order. */
+export function warnings() {
+  return accumulated;
+}
+
+export function emitJson(value, { stream = process.stdout, pretty = prettyDefault, maxBytes = maxBytesDefault } = {}) {
+  // `notices`, not `warnings`: `status` already reports a warning COUNT under that key,
+  // and a document cannot mean two things by one name. The collision is named here
+  // rather than bent into either shape (review 0003 Q62).
+  const carried =
+    accumulated.length > 0 && value !== null && typeof value === 'object' && !Array.isArray(value) && value.notices === undefined
+      ? { ...value, notices: accumulated }
+      : value;
+  const stamped =
+    canonicalCommand !== null && carried !== null && typeof carried === 'object' && !Array.isArray(carried)
+      ? { ...carried, command: canonicalCommand }
+      : carried;
+  if (captured !== null) {
+    captured.push({ value: stamped });
+    return true;
+  }
+  const payload = withSchemaVersion(stamped);
   const text = `${stringifyJson(payload, pretty)}\n`;
   // JSON is never byte-truncated: a cut document parses as a lie, and exit 0 calls it
   // true. Arrays shrink with a `truncated` record naming what lost how much, and a

package/src/packs/manage.mjs

@@ -511,6 +511,23 @@ export async function publishPack(dir, { apply = false } = {}) {
     return { pack: linted.pack, ok: false, published: false, skipped: false, planned: [], findings };
   }
 
+  // A preview is a preview. The registry read below is the one network call in this
+  // command, and running it to print a plan made `pack publish` — a preview by default
+  // — a network operation that failed offline without `--yes` (review 0003 Q58).
+  if (!apply) {
+    return {
+      pack: linted.pack,
+      ok: true,
+      published: false,
+      skipped: false,
+      planned: [
+        `npm view ${pkg}@${pack.version}  (check whether it is already live)`,
+        `npm publish  (in ${dir})`,
+      ],
+      findings,
+    };
+  }
+
   // Idempotent, the way the release twin is: a version that is already live is
   // skipped rather than republished, so a re-run after an interruption continues
   // where it stopped.
@@ -534,9 +551,6 @@ export async function publishPack(dir, { apply = false } = {}) {
   }
 
   const planned = [`npm publish  (in ${dir})`];
-  if (!apply) {
-    return { pack: linted.pack, ok: true, published: false, skipped: false, planned, findings };
-  }
   try {
     await exec('npm', ['publish'], { cwd: dir });
   } catch (error) {

package/src/packs.mjs

@@ -72,8 +72,26 @@ export async function packDigest(dir, { exclude = [] } = {}) {
     }
     for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
       const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
-      if (entry.isDirectory()) await walk(join(d, entry.name), rel);
-      else if (entry.isFile() && !excluded.has(rel)) files.push(rel);
+      if (entry.isDirectory()) {
+        await walk(join(d, entry.name), rel);
+      } else if (entry.isSymbolicLink()) {
+        // A link is not vendored bytes, and the loader follows it: the old walk skipped
+        // links while the projection read through them, so a rule reached by a link was
+        // projected without being covered by the pin (review 0003 Q58). A link to a
+        // file is hashed through its target, because `readFile` below follows it. A link
+        // to a directory is refused: recursing would let a pack's digest describe a tree
+        // it does not carry.
+        const target = await stat(join(d, entry.name)).catch(() => null);
+        if (target?.isDirectory()) {
+          const error = new Error(
+            `${rel} is a symbolic link to a directory; a pack is vendored bytes, and its digest cannot cover a tree it does not carry`,
+          );
+          error.code = 'PACK_SYMLINK';
+          error.path = rel;
+          throw error;
+        }
+        if (!excluded.has(rel)) files.push(rel);
+      } else if (entry.isFile() && !excluded.has(rel)) files.push(rel);
     }
   };
   await walk(dir);