@dzhechkov/harness-core 0.7.12 → 0.8.2

package/src/sign.ts

@@ -14,11 +14,12 @@
 
 import { createHash, sign as cryptoSign, verify as cryptoVerify, createPrivateKey, createPublicKey, generateKeyPairSync } from 'node:crypto';
 import { readFileSync, existsSync, readdirSync, openSync, fstatSync, closeSync, constants as fsConstants } from 'node:fs';
-import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 
 export const MANIFEST_NAME = '.dz-manifest.json';
 export const SBOM_NAME = 'sbom.json';
-export const MANIFEST_VERSION = 1;
+/** v3 preserves order-sensitive package.json condition maps while canonicalising packer noise. */
+export const MANIFEST_VERSION = 3;
 
 export interface ManifestEntry {
   readonly path: string;
@@ -48,6 +49,16 @@ export interface VerifyResult {
 }
 
 
+/** CycloneDX 1.5 JSON for current output. Canonical JSON digests are always explicitly labelled. */
+export function buildSbom(manifest: Manifest): Sbom {
+  return buildSbomEnvelope(manifest, false);
+}
+
+/** Compatibility-only decoder target for v1 packs that historically mislabeled package.json. */
+function buildLegacySbomV1(manifest: Manifest): Sbom {
+  return buildSbomEnvelope(manifest, true);
+}
+
 /**
  * Files the PACKER REWRITES, so their bytes are not stable across two packs of the same unchanged
  * tree — hashing them raw makes a signature that can never verify.
@@ -59,10 +70,12 @@ export interface VerifyResult {
  * the publisher packs again, and the consumer receives the second one.
  *
  * These files are therefore hashed in a CANONICAL form — parsed, keys sorted, stable separators.
- * HONEST LIMIT: a pure reordering of keys becomes invisible to the signature. It changes nothing a
- * consumer can observe, and the alternative — excusing `package.json` from signing altogether — would
+ * HONEST LIMIT: key order, insignificant whitespace, and negative-zero spelling become invisible to
+ * the signature. JavaScript can distinguish negative zero with `Object.is`, but JSON/pnpm round-trips
+ * normalize it to zero; tolerating that packer rewrite is explicit here. The alternative — excusing
+ * `package.json` from signing altogether — would
  * leave the dependency pins and the bin map unsigned, which is the opposite of a fix. The two
- * differences that a consumer COULD observe — duplicate keys and precision-losing integers — are
+ * differences that remain unsafe across parsers — duplicate keys and precision-losing/non-finite numbers — are
  * refused canonicalisation outright; see `canonicalisationIsFaithful`.
  */
 const CANONICALISED_PACK_FILES: ReadonlySet<string> = new Set(['package.json']);
@@ -77,6 +90,28 @@ function stableJson(value: unknown): string {
   return JSON.stringify(value) ?? 'null';
 }
 
+/**
+ * v3 package.json canonical form. pnpm may reorder ordinary object keys, but Node's conditional
+ * `exports`/`imports` objects are first-match maps and TypeScript consumers can likewise observe
+ * `typesVersions` order. Preserve every descendant object order under those roots while sorting
+ * ordinary metadata keys. This authenticates entry-point semantics without reintroducing pnpm's
+ * nondeterministic dependency-key ordering.
+ */
+const ORDER_SENSITIVE_PACKAGE_ROOTS = new Set(['exports', 'imports', 'typesVersions']);
+function stablePackageJsonV2(value: unknown, preserveOrder = false, atRoot = true): string {
+  if (Array.isArray(value)) return '[' + value.map((item) => stablePackageJsonV2(item, preserveOrder, false)).join(',') + ']';
+  if (value !== null && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    const keys = Object.keys(record);
+    if (!preserveOrder) keys.sort();
+    return '{' + keys.map((key) => {
+      const childPreservesOrder = preserveOrder || (atRoot && ORDER_SENSITIVE_PACKAGE_ROOTS.has(key));
+      return JSON.stringify(key) + ':' + stablePackageJsonV2(record[key], childPreservesOrder, false);
+    }).join(',') + '}';
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
 /**
  * Is this JSON text one whose PARSED value is a faithful stand-in for its BYTES?
  *
@@ -87,13 +122,28 @@ function stableJson(value: unknown): string {
  *  - DUPLICATE KEYS. `{"bin":"evil","bin":"signed"}` parses to the signed value in every JavaScript
  *    parser (last wins), so it would hash as clean — while a first-wins parser in another language
  *    reads `evil` from the same signed bytes.
- *  - LOSSY INTEGERS. `9007199254740993` parses to `...992`, so two different byte strings share one
- *    canonical form.
+ *  - LOSSY NUMBERS. `9007199254740993` parses to `...992`, a long decimal can collapse to a shorter
+ *    value, and `1e999` becomes `Infinity` before JSON serialization turns it into `null`.
  *
  * Neither is reachable through `pnpm pack` — this is a guard against a hand-crafted artifact, not
- * against the packer. On either, the caller hashes the RAW bytes instead, so an injected duplicate
- * mismatches a canonical signature and the pack reads TAMPERED.
+ * against the packer. Current/v3 generation refuses either form instead of producing an SBOM that
+ * could mislabel a raw-byte fallback as a canonical digest. Consumer verification returns a mismatch
+ * for the same refusal because its no-follow hashing wrapper maps this throw to `null`.
  */
+function normalizedJsonNumber(literal: string): string | null {
+  const match = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(literal);
+  if (!match || !Number.isFinite(Number(literal))) return null;
+  const negative = match[1] === '-';
+  const fraction = match[3] ?? '';
+  let digits = `${match[2]}${fraction}`.replace(/^0+/, '');
+  // pnpm/JSON round-trips collapse every mathematical negative zero spelling to `0`.
+  if (digits === '') return '0';
+  let exponent = Number(match[4] ?? '0') - fraction.length;
+  if (!Number.isSafeInteger(exponent)) return null;
+  while (digits.endsWith('0')) { digits = digits.slice(0, -1); exponent += 1; }
+  return `${negative ? '-' : ''}${digits}e${exponent}`;
+}
+
 function canonicalisationIsFaithful(text: string): boolean {
   const scopes: Array<Set<string> | null> = []; // Set = inside an object, null = inside an array
   let i = 0;
@@ -126,9 +176,11 @@ function canonicalisationIsFaithful(text: string): boolean {
       const start = i;
       while (i < text.length && /[-+0-9eE.]/.test(text.charAt(i))) i++;
       const lit = text.slice(start, i);
-      // Only plain integers can lose precision silently; `1.0` and `1e0` spell the same value in
-      // every parser, so they are legitimate canonical equivalences, not a differential.
-      if (/^-?\d+$/.test(lit) && String(Number(lit)) !== lit) return false;
+      // Compare exact decimal values after removing insignificant spelling differences. This keeps
+      // `1`, `1.0`, and `1e0` equivalent while rejecting IEEE-754 rounding, overflow and underflow.
+      const exact = normalizedJsonNumber(lit);
+      const parsed = normalizedJsonNumber(String(Number(lit)));
+      if (exact === null || parsed === null || exact !== parsed) return false;
       continue;
     }
     i++;
@@ -138,26 +190,32 @@ function canonicalisationIsFaithful(text: string): boolean {
 
 /**
  * Hash the bytes of one pack file. A packer-rewritten file is hashed canonically; everything else
- * byte-for-byte. Unparseable JSON falls back to the RAW bytes rather than passing — a corrupt
- * `package.json` must be a mismatch, never a free pass.
+ * byte-for-byte. Unparseable, ambiguous, or precision-losing root `package.json` bytes are refused:
+ * a current/v3 signer must never emit a raw digest under a canonical-digest SBOM label.
  */
-export function hashPackBytes(relPath: string, bytes: Buffer): string {
+export function hashPackBytes(relPath: string, bytes: Buffer, manifestVersion = MANIFEST_VERSION): string {
   const rel = relPath.split(sep).join('/');
   if (CANONICALISED_PACK_FILES.has(rel)) {
     try {
       const text = bytes.toString('utf-8');
       if (!canonicalisationIsFaithful(text)) throw new Error('not canonicalisable');
-      return createHash('sha256').update(Buffer.from(stableJson(JSON.parse(text)), 'utf-8')).digest('hex');
-    } catch {
-      /* fall through to the raw bytes */
+      const parsed = JSON.parse(text) as unknown;
+      const canonical = manifestVersion >= 3 ? stablePackageJsonV2(parsed) : stableJson(parsed);
+      return createHash('sha256').update(Buffer.from(canonical, 'utf-8')).digest('hex');
+    } catch (error) {
+      throw new Error(`refusing non-canonicalisable ${rel}: ${String((error as Error)?.message ?? error)}`);
     }
   }
   return createHash('sha256').update(bytes).digest('hex');
 }
 
-/** sha256 of a file's bytes, hex. Follows symlinks — used only when building a manifest we control. */
-export function hashFile(absPath: string, relPath?: string): string {
-  return hashPackBytes(relPath ?? basename(absPath), readFileSync(absPath));
+/**
+ * sha256 of a file's bytes, hex. Follows symlinks — used only when building a manifest we control.
+ * Canonical pack rewriting is opt-in through the explicit root-relative path. Omitting `relPath`
+ * hashes raw bytes, so an unrelated nested file merely named `package.json` is never relaxed.
+ */
+export function hashFile(absPath: string, relPath?: string, manifestVersion = MANIFEST_VERSION): string {
+  return hashPackBytes(relPath ?? '', readFileSync(absPath), manifestVersion);
 }
 
 /**
@@ -167,14 +225,14 @@ export function hashFile(absPath: string, relPath?: string): string {
  *
  * Returns `null` when the path is not a regular file, or is a symlink.
  */
-export function hashRegularFileNoFollow(absPath: string, relPath?: string): string | null {
+export function hashRegularFileNoFollow(absPath: string, relPath?: string, manifestVersion = MANIFEST_VERSION): string | null {
   let fd: number | undefined;
   try {
     fd = openSync(absPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
     if (!fstatSync(fd).isFile()) return null;
     // Canonicalise the bytes ALREADY READ from this descriptor — never re-open, or the TOCTOU
     // window this function exists to close would be reopened by the fix.
-    return hashPackBytes(relPath ?? basename(absPath), readFileSync(fd));
+    return hashPackBytes(relPath ?? '', readFileSync(fd), manifestVersion);
   } catch {
     return null; // ELOOP on a symlink, ENOENT, EACCES — all fail closed
   } finally {
@@ -182,6 +240,24 @@ export function hashRegularFileNoFollow(absPath: string, relPath?: string): stri
   }
 }
 
+/** Read one regular file through the same no-follow descriptor used by hashing. */
+export function readRegularFileNoFollow(absPath: string, expectedLength?: number | readonly number[]): Buffer | null {
+  let fd: number | undefined;
+  try {
+    fd = openSync(absPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    const allowedLengths = Array.isArray(expectedLength) ? expectedLength : expectedLength === undefined ? null : [expectedLength];
+    if (!stat.isFile() || (allowedLengths !== null && !allowedLengths.includes(stat.size))) return null;
+    const bytes = readFileSync(fd);
+    if (allowedLengths !== null && !allowedLengths.includes(bytes.length)) return null;
+    return bytes;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
 /**
  * Cross-model security review (codex exec, 2026-07-10) — a SIGNED manifest is not a TRUSTED manifest.
  * Its own contents are attacker-controlled until the signature checks out, and even then they must be
@@ -224,31 +300,49 @@ export function checkManifestEntries(files: unknown): string | null {
 }
 
 /**
- * Directory names that are NOT pack content and are excluded from BOTH walks. node_modules/.git:
- * installed deps / VCS metadata. `.agentic-qe`/`.dz`: LOCAL RUNTIME STATE (learning DBs, RVF
+ * State-entry names that may be excluded from BOTH walks. node_modules/.git:
+ * installed deps / VCS metadata. `.agentic-qe`/`.dz`: LOCAL RUNTIME STATE entries (learning DBs, RVF
  * stores, witness keys) that background workers create inside pack cwds — gitignored, machine-
  * specific, never shipped. Signing them made 19 packs verify green LOCALLY (files present, hashes
  * match) and TAMPERED in CI (clean checkout lacks the gitignored state) — found live on GH run
  * #103, 2026-07-19. State is not content; the walks must never see it.
  */
-const EXCLUDED_DIRS = new Set(['node_modules', '.git', '.agentic-qe', '.dz']);
+const EXCLUDED_STATE_NAMES = new Set(['node_modules', '.git', '.agentic-qe', '.dz']);
+
+function isExcludedStateEntry(entry: {
+  name: string;
+  isDirectory(): boolean;
+  isSymbolicLink(): boolean;
+}): boolean {
+  if (!EXCLUDED_STATE_NAMES.has(entry.name)) return false;
+  // A worktree's `.git` is commonly a regular pointer file, and workspace/local-state entries may be
+  // symlinks. They remain VCS/dependency/runtime state. A same-named ordinary file other than `.git`
+  // is package content and must stay visible.
+  if (entry.name === '.git') return true;
+  return entry.isDirectory() || entry.isSymbolicLink();
+}
+
+/** Generated metadata FILES are self-excluded only at the pack root; directories remain content. */
+function isRootGeneratedMetadata(relDir: string, name: string, isFile: boolean): boolean {
+  return isFile && relDir === '' && (name === MANIFEST_NAME || name === SBOM_NAME);
+}
 
 /** Every file under `root`, POSIX-relative, excluding the manifest and the SBOM themselves. */
 export function listPackFiles(root: string): string[] {
   const out: string[] = [];
   const walk = (dir: string, rel: string): void => {
     for (const e of readdirSync(dir, { withFileTypes: true })) {
-      // Excluded dirs are unsigned territory BY DESIGN (see EXCLUDED_DIRS). The SIGN and VERIFY
+      // Role-classified state entries are unsigned territory BY DESIGN (see EXCLUDED_STATE_NAMES). The SIGN and VERIFY
       // walks MUST share these exclusions: an asymmetry here false-TAMPERs every pnpm workspace
       // pack whose node_modules holds symlinks (found live arming task #36 — 10 of 23 packs).
-      if (EXCLUDED_DIRS.has(e.name)) continue;
-      if (e.name === MANIFEST_NAME || e.name === SBOM_NAME) continue;
+      if (isExcludedStateEntry(e)) continue;
+      if (isRootGeneratedMetadata(rel, e.name, e.isFile())) continue;
       const abs = join(dir, e.name);
       const r = rel ? rel + '/' + e.name : e.name;
       if (e.isDirectory()) walk(abs, r);
-      // NOT else-isFile: a symlink (or other non-file) OUTSIDE the excluded dirs must stay VISIBLE to the
+      // NOT else-isFile: a symlink (or other non-file) OUTSIDE role-classified state must stay VISIBLE to the
       // verify sweep — it fails as "present but not signed" / "is a symlink" (R3-4: a smuggled symlink is a
-      // finding, not something to silently ignore). Only EXCLUDED_DIRS are exempt territory.
+      // finding, not something to silently ignore). Only EXCLUDED_STATE_NAMES entries are exempt territory.
       else out.push(r);
     }
   };
@@ -265,8 +359,8 @@ export function listSignablePackFiles(root: string): string[] {
   const out: string[] = [];
   const walk = (dir: string, rel: string): void => {
     for (const e of readdirSync(dir, { withFileTypes: true })) {
-      if (EXCLUDED_DIRS.has(e.name)) continue;
-      if (e.name === MANIFEST_NAME || e.name === SBOM_NAME) continue;
+      if (isExcludedStateEntry(e)) continue;
+      if (isRootGeneratedMetadata(rel, e.name, e.isFile())) continue;
       const abs = join(dir, e.name);
       const r = rel ? rel + '/' + e.name : e.name;
       if (e.isDirectory()) walk(abs, r);
@@ -356,19 +450,6 @@ export function verifyManifest(
   root: string,
   signed: SignedManifest | null | undefined,
   pubKeyPem: string,
-  /**
-   * The paths the pack actually SHIPS, when the caller can establish them (from `npm pack`). The
-   * added-file sweep is then scoped to those, because a working-tree file `files[]` excludes was
-   * never "added to the pack" — it simply is not part of it.
-   *
-   * Omit it and the sweep covers the whole tree, exactly as before. That is correct for the case that
-   * matters most: a consumer verifying an EXTRACTED tarball, where the tree IS the shipped set.
-   *
-   * This parameter exists because the signer and the sweep must never disagree about what a pack
-   * contains — the 10-false-TAMPERED lesson, recorded at `packFiles` and re-learned on 2026-08-21 the
-   * moment the signer started scoping and the sweep did not.
-   */
-  shippedPaths?: readonly string[],
 ): VerifyResult {
   const fail = (path: string, reason: string): VerifyResult => ({ ok: false, failures: [{ path, reason }] });
 
@@ -378,6 +459,9 @@ export function verifyManifest(
   if (typeof manifest.version !== 'number' || !Number.isInteger(manifest.version)) {
     return fail(MANIFEST_NAME, 'manifest version is not an integer');
   }
+  if (![1, 2, MANIFEST_VERSION].includes(manifest.version)) {
+    return fail(MANIFEST_NAME, `unsupported manifest version ${manifest.version}`);
+  }
   if (!isSafeManifestPath(manifest.pack)) {
     return fail(MANIFEST_NAME, 'manifest pack name is unsafe: ' + JSON.stringify(manifest.pack));
   }
@@ -405,6 +489,8 @@ export function verifyManifest(
   if (!sigOk) return fail(MANIFEST_NAME, 'signature does not verify against the pinned key');
 
   const failures: VerifyFailure[] = [];
+  const sbomFailure = verifySbomAgainstManifest(root, manifest);
+  if (sbomFailure !== null) failures.push({ path: SBOM_NAME, reason: sbomFailure });
   for (const entry of manifest.files) {
     const abs = join(root, entry.path);
     if (!existsSync(abs)) {
@@ -412,9 +498,9 @@ export function verifyManifest(
       continue;
     }
     // One open, O_NOFOLLOW, fstat the descriptor, hash from it: no symlink follow, no TOCTOU window.
-    const digest = hashRegularFileNoFollow(abs, entry.path);
+    const digest = hashRegularFileNoFollow(abs, entry.path, manifest.version);
     if (digest === null) {
-      failures.push({ path: entry.path, reason: 'is a symlink or not a regular file — refusing to hash it' });
+      failures.push({ path: entry.path, reason: 'is a symlink, not a regular file, unreadable, or outside the canonical JSON domain — refusing to hash it' });
       continue;
     }
     if (digest !== entry.sha256) {
@@ -423,14 +509,10 @@ export function verifyManifest(
   }
 
   // Bidirectional, always: hashing only what the manifest lists lets an attacker ADD a file.
-  const shipped = shippedPaths === undefined ? null : new Set(shippedPaths);
   const present = listPackFiles(root);
   const listed = new Set(manifest.files.map((f) => f.path));
   for (const rel of present) {
     const p = rel.split(sep).join('/');
-    // A file the pack does not ship is not an ADDED file; scoping here is what keeps the sweep and the
-    // signer describing the same object.
-    if (shipped !== null && !shipped.has(p)) continue;
     if (!listed.has(p)) failures.push({ path: p, reason: 'present in the pack but not signed' });
   }
 
@@ -467,7 +549,10 @@ export function assertKeyOutsideTree(keyPath: string, repoRoot: string): void {
 export interface SbomComponent {
   readonly type: 'file';
   readonly name: string;
-  readonly hashes: readonly { readonly alg: 'SHA-256'; readonly content: string }[];
+  /** Raw file-byte digests only. A canonical JSON verification digest must never masquerade here. */
+  readonly hashes?: readonly { readonly alg: 'SHA-256'; readonly content: string }[];
+  /** Explicit verification-digest metadata for packer-rewritten JSON such as package.json. */
+  readonly properties?: readonly { readonly name: string; readonly value: string }[];
 }
 
 export interface Sbom {
@@ -478,21 +563,56 @@ export interface Sbom {
   readonly components: readonly SbomComponent[];
 }
 
-/** CycloneDX 1.5 JSON, hand-built — it is JSON against a schema, not a reason for a dependency. */
-export function buildSbom(manifest: Manifest): Sbom {
+function buildSbomEnvelope(manifest: Manifest, legacyV1PackageHash: boolean): Sbom {
   return {
     bomFormat: 'CycloneDX',
     specVersion: '1.5',
     version: 1,
     metadata: { component: { type: 'library', name: manifest.pack } },
-    components: manifest.files.map((f) => ({
-      type: 'file' as const,
-      name: f.path,
-      hashes: [{ alg: 'SHA-256' as const, content: f.sha256 }],
-    })),
+    components: [...manifest.files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)).map((f) =>
+      !legacyV1PackageHash && CANONICALISED_PACK_FILES.has(f.path)
+        ? {
+            type: 'file' as const,
+            name: f.path,
+            properties: [
+              { name: 'dz:digest-basis', value: manifest.version >= 3
+                ? 'package-json-ordered-conditions-v2' : 'recursive-key-sorted-json-v1' },
+              { name: manifest.version >= 3
+                ? 'dz:canonical-json-sha256-v2' : 'dz:canonical-json-sha256-v1', value: f.sha256 },
+            ],
+          }
+        : {
+            type: 'file' as const,
+            name: f.path,
+            hashes: [{ alg: 'SHA-256' as const, content: f.sha256 }],
+          }),
   };
 }
 
+/**
+ * ADR-003: SBOM authenticity is acyclic. The SBOM is not self-hashed; instead its sole canonical
+ * value is derived from the already signature-authenticated manifest and compared byte-for-byte.
+ */
+export function verifySbomAgainstManifest(root: string, manifest: Manifest): string | null {
+  if (![1, 2, MANIFEST_VERSION].includes(manifest.version)) {
+    return `unsupported manifest version ${manifest.version}`;
+  }
+  const expected = JSON.stringify(buildSbom(manifest), null, 2) + '\n';
+  const accepted = manifest.version === 1
+    ? [expected, JSON.stringify(buildLegacySbomV1(manifest), null, 2) + '\n']
+    : [expected];
+  const bytes = readRegularFileNoFollow(join(root, SBOM_NAME), [...new Set(accepted.map((value) => Buffer.byteLength(value)))]);
+  if (bytes === null) return 'missing, symlinked, not a regular file, or has a non-canonical byte length';
+  const actual = bytes.toString('utf8');
+  if (!canonicalisationIsFaithful(actual)) return 'JSON is malformed, ambiguous, or precision-losing';
+  try {
+    JSON.parse(actual);
+  } catch {
+    return 'JSON is malformed';
+  }
+  return accepted.includes(actual) ? null : 'content does not equal canonical CycloneDX derived from the signed manifest';
+}
+
 // ── The publish gate (FR-4), as a pure decision ─────────────────────────────
 //
 // The operator's decision was "the publish gate BLOCKS". Reality intervened: with no trust root

package/src/store-location.ts

@@ -0,0 +1,76 @@
+/**
+ * store-location — one sentence about WHERE a learning store lives, used by every command that
+ * touches one.
+ *
+ * MEASURED 2026-08-27: `dz teach` and `dz recall` both resolve their store as
+ * `resolve(cwd, --project ?? '.')` (`cli.ts:2882`, `:3450`) — plain cwd, no git-root walk, no
+ * upward search, and no config key or environment variable to pin a canonical root. Neither
+ * command printed the path.
+ *
+ * So a user who runs `dz teach` in eight project directories gets eight isolated stores and
+ * believes they are accumulating. The path alone does not reveal that: `/home/u/proj/.dz` looks
+ * equally deliberate whether it was chosen or defaulted into. **That difference is the defect**,
+ * so the line names the SOURCE, not only the location.
+ *
+ * This ships BEFORE the intended per-session mode on purpose. A mode set once and forgotten lies
+ * silently, and a mode is only safe when its effect is visible on every operation it governs.
+ */
+
+import { join } from 'node:path';
+
+/**
+ * Who decided this path. `global` is separate from `cwd`/`explicit` because the advice differs:
+ * "pass --project" is useful for a cwd-derived store and MISLEADING for the home store, which
+ * neither the cwd nor --project chose (cross-family QE, 2026-08-27: `--project /tmp/p --to global`
+ * printed the right path under the wrong explanation).
+ */
+export type StoreOrigin = 'explicit' | 'cwd' | 'global';
+
+export interface StoreLocation {
+  /** Absolute path of the store directory — `<projectRoot>/.dz`. */
+  readonly path: string;
+  /** Where the project root came from: an explicit `--project`, or the current directory. */
+  readonly origin: StoreOrigin;
+}
+
+/**
+ * Describe the store a command is about to use.
+ *
+ * `projectOption` is the RAW `--project` value as the user typed it (or `undefined`), and
+ * `resolvedRoot` is what the command already computed. Both are taken rather than re-resolving,
+ * so this helper can never disagree with the command about which directory was chosen — a second,
+ * independent resolution is exactly how two lookalike code paths come to name different stores.
+ */
+export function describeStoreLocation(
+  resolvedRoot: string,
+  projectOption: string | undefined,
+  /**
+   * Overrides the derived origin when the caller KNOWS what chose the path — today only the
+   * cross-project home store, which neither the cwd nor `--project` selected. Omit it and the
+   * origin is derived exactly as before, so every existing call is unchanged.
+   */
+  origin?: StoreOrigin,
+): StoreLocation {
+  return {
+    path: join(resolvedRoot, '.dz'),
+    origin: origin ?? (projectOption === undefined ? 'cwd' : 'explicit'),
+  };
+}
+
+/**
+ * The one human line, shared by every command.
+ *
+ * Two commands writing this sentence independently is how they come to disagree about what a store
+ * is — the lookalike-normalisation class this repo has already paid for once.
+ *
+ * `verb` is what the command did with the store, so the line reads naturally in both directions:
+ * "store (written): …" and "store (read): …".
+ */
+export function storeLocationLine(loc: StoreLocation, verb: 'written' | 'read'): string {
+  const because = loc.origin === 'explicit'
+    ? 'from --project'
+    : loc.origin === 'global'
+      ? 'the cross-project store in your home directory'
+      : 'from the current directory — pass --project to choose deliberately';
+  return `  store (${verb}): ${loc.path}  [${because}]`;
+}

package/src/store-lock.ts

@@ -68,6 +68,8 @@ export const LOCK_TIMEOUT_MS = 10_000;
 
 /** `proper-lockfile` silently clamps `stale` up to this minimum. */
 const MIN_STALE_MS = 2_000;
+/** Highest accepted environment override; keeps proper-lockfile's heartbeat timer in range. */
+const MAX_STALE_MS = 600_000;
 
 /** Path of the lock guarding a project's pattern store (a DIRECTORY when held). */
 export function storeLockPath(projectRoot: string): string {
@@ -115,6 +117,11 @@ const defaultTimeoutMs = (): number => {
   return Number.isFinite(env) && env > 0 ? env : LOCK_TIMEOUT_MS;
 };
 
+export function resolveStaleMs(): number {
+  const env = Number(process.env['DZ_STORE_LOCK_STALE_MS']);
+  return Number.isFinite(env) && env > 0 && env <= MAX_STALE_MS ? env : STALE_LOCK_MS;
+}
+
 const sleep = (ms: number): Promise<void> => new Promise((r) => { setTimeout(r, ms); });
 
 /** Synchronous sleep without spinning (Atomics.wait on a throwaway buffer). */
@@ -176,7 +183,7 @@ function tryAcquire(projectRoot: string, staleMs: number, onCompromised: (e: Err
 
 function resolveOpts(opts: StoreLockOptions): { staleMs: number; timeoutMs: number; pollMs: number } {
   return {
-    staleMs: Math.max(opts.staleMs ?? STALE_LOCK_MS, MIN_STALE_MS),
+    staleMs: Math.max(opts.staleMs ?? resolveStaleMs(), MIN_STALE_MS),
     timeoutMs: opts.timeoutMs ?? defaultTimeoutMs(),
     pollMs: opts.pollMs ?? 25,
   };

package/src/store-merge.ts

@@ -0,0 +1,91 @@
+/**
+ * store-merge — read two learning stores together, and never merge them on disk.
+ *
+ * The design comes from our own shipped precedent, `learning_bridge.py:23`:
+ *
+ *   "the compounding objection was answered by making RECALL read both stores rather than by
+ *    merging them"
+ *
+ * and `:880`: "two stores are different stores, whatever mechanism might have made them the same."
+ *
+ * That precedent records an ASYMMETRY, and it is the whole design here: WRITING needs a choice —
+ * is this lesson about this project, or general? — while READING almost never does. You want your
+ * project's specifics AND your accumulated expertise. So recall reads both, always, with no mode:
+ * a mode here would only add a way to be wrong, and a mode set once and forgotten lies silently.
+ *
+ * The cross-project store is not a new kind of thing. MEASURED: `~/.dz` already exists, and
+ * `loadPatterns(projectRoot)` already takes a root — so the global store is simply a project store
+ * whose root is the home directory. Same code, same format, nothing to migrate.
+ */
+
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+
+/** Which store a record came from. `both` means the same record exists in each. */
+export type HitOrigin = 'project' | 'global' | 'both';
+
+export interface OriginTagged {
+  readonly origin: HitOrigin;
+}
+
+/**
+ * The cross-project store's root: the home directory.
+ *
+ * Taken as a parameter rather than read from the environment inside the merge, so the pure half
+ * stays testable without a filesystem and a caller cannot be surprised by which home it meant.
+ */
+export function globalStoreRoot(home: string = homedir()): string {
+  return resolve(home);
+}
+
+/**
+ * Are these two roots the same store?
+ *
+ * If a user runs `dz recall` FROM their home directory, "read both" would read one file twice and
+ * double every hit. Resolved-path comparison, before either read — cheaper and more certain than
+ * de-duplicating afterwards.
+ */
+export function sameStore(projectRoot: string, globalRoot: string): boolean {
+  return resolve(projectRoot) === resolve(globalRoot);
+}
+
+/**
+ * Merge two record sets into one origin-tagged list.
+ *
+ * `key` decides identity. It is supplied by the caller rather than assumed here, because two
+ * lookalike identity rules is how a merge quietly starts treating one record as two — the class
+ * this repo has already paid for.
+ *
+ * ORDER: project records first, then global-only ones. A project's own lessons are the more
+ * specific answer to a question asked inside that project, and a reader scanning from the top
+ * should meet them first. Records present in BOTH keep the project position and are labelled
+ * `both`, because that is where the reader will look for them.
+ */
+export function mergeStoreHits<T>(
+  projectRecords: readonly T[],
+  globalRecords: readonly T[],
+  key: (r: T) => string,
+): (T & OriginTagged)[] {
+  const inGlobal = new Set(globalRecords.map(key));
+  const seen = new Set<string>();
+  const out: (T & OriginTagged)[] = [];
+
+  for (const r of projectRecords) {
+    const k = key(r);
+    if (seen.has(k)) continue;          // a store with an internal duplicate stays one record here
+    seen.add(k);
+    out.push({ ...r, origin: inGlobal.has(k) ? 'both' : 'project' });
+  }
+  for (const r of globalRecords) {
+    const k = key(r);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push({ ...r, origin: 'global' });
+  }
+  return out;
+}
+
+/** How the header should describe what was read — "1 store" is a fact worth stating, not assuming. */
+export function storeCountLabel(count: number): string {
+  return count === 1 ? '1 store' : `${count} stores`;
+}