session-orchestrator 5.6.0 → 5.8.0

package/scripts/lib/fleet-protocol.mjs

@@ -21,12 +21,18 @@
  * expired lease is `none`, a lease that cannot be read or validated is
  * `unreadable`, and neither is ever `active`.
  *
+ * An auflagen file is keyed by the semantic session id, which collides across
+ * repos (`main-<date>-session-N`), so it is only accepted when its mandatory
+ * `repo` field resolves to the reader's own git common dir ({@link readAuflagen},
+ * #1520 / navigator#190).
+ *
  * Session ids become file names, so {@link isSafeSessionId} is the security
  * boundary between check-in input and the filesystem: every path builder that
  * takes a session id refuses an unsafe one with a TypeError.
  */
 
-import { promises as fs } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import fsSync, { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -286,3 +292,94 @@ export async function readNavigatorLease({ now = Date.now(), env, home } = {}) {
   if (Date.parse(lease.laeuft_ab) <= now) return { state: 'none' };
   return { state: 'active', lease };
 }
+
+/** Timeout for the `git rev-parse` calls in {@link readAuflagen}. */
+const GIT_TIMEOUT_MS = 5_000;
+
+/**
+ * Absolute, realpath'd git common dir of `dir` — the same value for a main tree,
+ * any of its linked worktrees, and the `.git` directory itself — or null when
+ * `dir` is not inside a git repository (or git is unavailable).
+ * @param {string} dir
+ * @returns {string|null}
+ */
+function gitCommonDir(dir) {
+  try {
+    const out = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      env: gitEnv(),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: GIT_TIMEOUT_MS,
+    }).trim();
+    if (!out) return null;
+    return realpathSyncSafe(out);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The only environment variables forwarded to `git`. An inherited `GIT_DIR`
+ * outranks `-C`, so both sides of the repo comparison would resolve to the
+ * same directory and a foreign repo's Auflagen would be ACCEPTED. Same
+ * allowlist as `git-config-drift.mjs` / `check-banner-parity.mjs`.
+ */
+const GIT_ENV_ALLOWLIST = Object.freeze(['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'TZ']);
+
+function gitEnv() {
+  /** @type {Record<string, string>} */
+  const env = {};
+  for (const k of GIT_ENV_ALLOWLIST) if (process.env[k] !== undefined) env[k] = /** @type {string} */ (process.env[k]);
+  return env;
+}
+
+/** @param {string} p */
+function realpathSyncSafe(p) {
+  try {
+    return fsSync.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * Read this session's conditions file and accept it only when it belongs to the
+ * reader's repository. Never throws; fail-closed.
+ *
+ * The file's mandatory `repo` field (an absolute path to the target repo's
+ * toplevel or its git common dir, written by the navigator) and `repoRoot` are
+ * both resolved to their git common dir, so a session in a linked worktree
+ * matches a file naming the main tree. Every `rejected` result means: behave as
+ * if no file existed (Standard-Auflagen apply).
+ *
+ * @param {string} sessionId
+ * @param {{ repoRoot?: string, env?: Record<string, string|undefined>, home?: string }} [opts]
+ * @returns {Promise<
+ *   | { state: 'absent' }
+ *   | { state: 'accepted', auflagen: Record<string, unknown> }
+ *   | { state: 'rejected', reason: 'unsafe-session-id'|'unreadable'|'invalid-json'|'repo-missing'|'repo-unresolved'|'repo-mismatch' }
+ * >}
+ */
+export async function readAuflagen(sessionId, { repoRoot = process.cwd(), env, home } = {}) {
+  if (!isSafeSessionId(sessionId)) return { state: 'rejected', reason: 'unsafe-session-id' };
+  let raw;
+  try {
+    raw = await fs.readFile(auflagenPath(sessionId, { env, home }), 'utf8');
+  } catch (err) {
+    if (err && /** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return { state: 'absent' };
+    return { state: 'rejected', reason: 'unreadable' };
+  }
+  let auflagen;
+  try {
+    auflagen = JSON.parse(raw);
+  } catch {
+    return { state: 'rejected', reason: 'invalid-json' };
+  }
+  if (!isPlainObject(auflagen)) return { state: 'rejected', reason: 'invalid-json' };
+  const fileRepo = auflagen.repo;
+  if (typeof fileRepo !== 'string' || !path.isAbsolute(fileRepo)) return { state: 'rejected', reason: 'repo-missing' };
+  const own = gitCommonDir(repoRoot);
+  if (!own) return { state: 'rejected', reason: 'repo-unresolved' };
+  if (gitCommonDir(fileRepo) !== own) return { state: 'rejected', reason: 'repo-mismatch' };
+  return { state: 'accepted', auflagen };
+}

package/scripts/lib/instruction-budget-guard.mjs

@@ -88,11 +88,13 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
-import { scanEventsBackwards } from './events.mjs';
+import { eventsFilePath, scanEventsBackwards } from './events.mjs';
 import {
   FRONTMATTER_NOT_AT_TOP,
   loadApplicableRules,
+  isRuleExpired,
   parseGlobsFrontmatter,
+  ruleExpiryInstantMs,
 } from './rule-loader.mjs';
 
 /** Default directive ceiling (operator-chosen growth ratchet just above the ~457 baseline). */
@@ -846,11 +848,11 @@ const MS_PER_DAY = 86_400_000;
  * declares no expiry or an unparseable one.
  *
  * Negative ⇒ already expired. The comparison basis is deliberately the SAME one
- * `rule-loader.mjs` `applyGates` uses — `Date.parse(expires-at) < now`, i.e. a
- * bare `YYYY-MM-DD` is UTC midnight — so "expired" here means exactly "the
- * loader already filters it out of every wave's rule set", never a second
- * definition of the same word. `Math.floor` therefore returns `-1` for a rule
- * that expired at midnight today: past, but by less than a day.
+ * `rule-loader.mjs` `applyGates` uses — `ruleExpiryInstantMs`, where a bare
+ * `YYYY-MM-DD` is INCLUSIVE and expires at the FOLLOWING UTC midnight (#1521) —
+ * so "expired" here means exactly "the loader already filters it out of every
+ * wave's rule set", never a second definition of the same word. `0` therefore
+ * means "last day: still loads today", `-1` "dropped at the last midnight".
  *
  * An unparseable date returns `null` (fail-OPEN, matching the loader, which
  * warns and ignores the expiry rather than excluding the file) — the malformed
@@ -863,17 +865,18 @@ export function daysUntilGeneratedRuleExpiry(opts = {}) {
   const meta = opts.meta;
   if (!meta || typeof meta !== 'object') return null;
   if (!Object.prototype.hasOwnProperty.call(meta, 'expires-at')) return null;
-  const expiresAt = Date.parse(String(meta['expires-at']));
-  if (!Number.isFinite(expiresAt)) return null;
+  const expiresAt = ruleExpiryInstantMs(meta['expires-at']);
+  if (expiresAt === null) return null;
 
-  const raw = opts.now;
-  let now;
-  if (raw instanceof Date) now = raw.getTime();
-  else if (typeof raw === 'number' && Number.isFinite(raw)) now = raw;
-  else if (typeof raw === 'string' && Number.isFinite(Date.parse(raw))) now = Date.parse(raw);
-  else now = Date.now();
+  return Math.floor((expiresAt - nowMs(opts.now)) / MS_PER_DAY);
+}
 
-  return Math.floor((expiresAt - now) / MS_PER_DAY);
+/** `now` as epoch ms: Date, number or parseable string; anything else → the process clock. */
+function nowMs(raw) {
+  if (raw instanceof Date) return raw.getTime();
+  if (typeof raw === 'number' && Number.isFinite(raw)) return raw;
+  if (typeof raw === 'string' && Number.isFinite(Date.parse(raw))) return Date.parse(raw);
+  return Date.now();
 }
 
 /**
@@ -888,8 +891,12 @@ export function daysUntilGeneratedRuleExpiry(opts = {}) {
  * @returns {boolean}
  */
 export function isExpiredGeneratedRule(opts = {}) {
-  const days = daysUntilGeneratedRuleExpiry(opts);
-  return days !== null && days < 0;
+  const meta = opts.meta;
+  if (!meta || typeof meta !== 'object') return false;
+  if (!Object.prototype.hasOwnProperty.call(meta, 'expires-at')) return false;
+  // The loader's own predicate, not `days < 0`: flooring whole days would call
+  // the rule live for the first millisecond after the boundary (#1521).
+  return isRuleExpired(meta['expires-at'], nowMs(opts.now));
 }
 
 /**
@@ -1335,7 +1342,7 @@ const RECONCILE_SCAN_BUDGET_MS = 150;
  */
 function readLastReconcileCapped(repoRoot) {
   if (typeof repoRoot !== 'string' || repoRoot === '') return null;
-  const filePath = join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+  const filePath = eventsFilePath(repoRoot); // #1514 point 1: the repo's one ledger
   let capped = null;
   let scan;
   try {

package/scripts/lib/io.mjs

@@ -16,7 +16,7 @@
  * #457; writeJsonAtomicSync extracted for #558 M1.
  */
 
-import { writeFile, rename, mkdir } from 'node:fs/promises';
+import { writeFile, rename, mkdir, copyFile, unlink } from 'node:fs/promises';
 import {
   mkdirSync,
   writeFileSync,
@@ -888,7 +888,10 @@ export async function writeJsonAtomic(filePath, value, opts = {}) {
  * @param {object} [opts]
  * @param {number} [opts.indent=2]      JSON.stringify indent.
  * @param {string} [opts.tmpPrefix='.tmp']  Tmp-file prefix (callers pick their domain prefix).
- * @returns {{ ok: true } | { ok: false, reason: 'fs-error', error: string }}
+ * @returns {{ ok: true } | { ok: false, reason: 'fs-error', error: string, code: string|null }}
+ *   `code` is the failing call's `err.code` (`'ENOSPC'`, `'EACCES'`, …), or `null`
+ *   when the error carried none (a serialization TypeError, the partial-adapter
+ *   refusal). Additive (#1032): `error` keeps its exact text.
  */
 export function writeJsonAtomicSync(filePath, data, opts = {}) {
   const { indent = 2, tmpPrefix = '.tmp' } = opts;
@@ -897,7 +900,7 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
   try {
     body = JSON.stringify(data, null, indent) + '\n';
   } catch (err) {
-    return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
+    return _fsErrorEnvelope(err);
   }
 
   const res = atomicWriteWithBackup(filePath, body, { tmpPrefix });
@@ -941,26 +944,32 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
  * envelope is returned. Without that, every failed write leaves a
  * `<tmpPrefix>.<hex>` behind — the board writer's failure mode is a retry loop,
  * so the litter accumulates in the operator's vault directory. The cleanup is
- * attempted only when the write actually created the tmp file, and its own
- * failure is swallowed: a leaked tmp is worse than a silent unlink miss, and
- * neither may mask the original error.
+ * attempted once the tmp path has been chosen — including a write that created
+ * the file and then failed mid-way — and its own failure is swallowed: a leaked
+ * tmp is worse than a silent unlink miss, and neither may mask the original
+ * error.
  *
  * ── BV-004 ceiling + revisit trigger ────────────────────────────────────────
- * TWO PRODUCTION CALL-SITES: `vault-status/board-writer.mjs#writeBoard`
- * (`backup: false`) and {@link writeJsonAtomicSync}, which carries 12 further
- * call-sites across 9 files behind it. That second one is the load-bearing
+ * THREE PRODUCTION CALL-SITES (re-measured 2026-10-03 @ 0e0c4b08 with
+ * `rg -n "atomicWriteWithBackup\(" scripts hooks skills --glob '*.mjs'`):
+ * `vault-status/board-writer.mjs#writeBoard` (`backup: false`),
+ * `reconcile/rule-expiry-sweep.mjs` (no `backup`, i.e. `false`) and
+ * {@link writeJsonAtomicSync}, which carries 14 further call-sites across 11
+ * files behind it (`rg -n "writeJsonAtomicSync\("` over the same scope, minus
+ * the definition and `host-identity.mjs`'s private `_writeJsonAtomicSync`
+ * copy, which does NOT route through this helper). That last one is the load-bearing
  * evidence — the previous revision of this note recorded ONE call-site and
  * concluded the signature was unproven, while the function with an identical
  * body sat 60 lines above in this same file, unmigrated. The cheapest possible
  * migration going unmade is not a neutral fact about a helper: it is the
  * measurement that the helper is not paying for itself.
  *
- * What the second call-site does NOT prove: `writeJsonAtomicSync` passes
+ * What the `writeJsonAtomicSync` call-site does NOT prove: it passes
  * `backup: false` and no `fs`, so the backup half and the injection seam still
  * rest on tests plus one board-writer flag. REVISIT TRIGGER — when a sweep
  * migrates the remaining hand-rolled sites, re-check before widening:
- * (a) whether an `async` twin is needed rather than bolting a promise mode onto
- * this one (three known sites are `fs/promises`), and (b) whether rotation
+ * (a) answered (#1032): the async twin is {@link atomicWriteText}, not a
+ * promise mode on this function; and (b) whether rotation
  * belongs here after all (it does only if ≥2 migrated callers want the SAME
  * keep-N). If NO caller ever passes `backup: true` in production, that half is
  * still the part to shrink back.
@@ -977,7 +986,9 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
  *   Injectable fs (tests). Omitted methods fall back to `node:fs` — EXCEPT on
  *   the backup path, which fails closed (see below).
  * @returns {{ ok: true, path: string, bytes: number, backupPath: string|null }
- *   | { ok: false, reason: 'fs-error', error: string }}
+ *   | { ok: false, reason: 'fs-error', error: string, code: string|null }}
+ *   `code` is the failing call's `err.code`, or `null` when there was none
+ *   (additive, #1032 — a caller that must re-throw with the same code can now).
  */
 export function atomicWriteWithBackup(filePath, body, opts = {}) {
   const {
@@ -1011,20 +1022,15 @@ export function atomicWriteWithBackup(filePath, body, opts = {}) {
   // methods are guarded, not just `copyFileSync` — a missing `existsSync` probes
   // the real target and silently decides the backup branch from it, which is the
   // same escape one step earlier.
-  if (backup && injectedFs) {
-    for (const method of ['existsSync', 'copyFileSync']) {
-      if (typeof injectedFs[method] !== 'function') {
-        return {
-          ok: false,
-          reason: 'fs-error',
-          error: `partial fs adapter: ${method} required for backup`,
-        };
-      }
-    }
-  }
+  const refusal = _partialAdapterRefusal(backup, injectedFs, ['existsSync', 'copyFileSync']);
+  if (refusal) return refusal;
 
+  // Assigned BEFORE the write, and cleanup keys on it rather than on the write
+  // having returned: `writeFileSync` can create the tmp file and THEN throw
+  // (ENOSPC / EIO mid-write), and a flag set only after it returned leaked
+  // exactly that file (#1032). Unlinking a tmp that was never created throws
+  // ENOENT, which the cleanup swallows.
   let tmpFile = null;
-  let tmpCreated = false;
 
   try {
     const dir = dirname(filePath);
@@ -1032,34 +1038,170 @@ export function atomicWriteWithBackup(filePath, body, opts = {}) {
 
     let backupPath = null;
     if (backup && fsExists(filePath)) {
-      const stamp = (now instanceof Date ? now : new Date()).toISOString().replace(/[:.]/g, '-');
-      backupPath = `${filePath}.bak-${stamp}`;
+      backupPath = _backupPathFor(filePath, now);
       fsCopyFile(filePath, backupPath);
     }
 
-    tmpFile = path.join(dir, `${tmpPrefix}.${randomBytes(6).toString('hex')}`);
+    tmpFile = _tmpPathFor(dir, tmpPrefix);
     fsWriteFile(tmpFile, body, encoding);
-    tmpCreated = true;
     fsRename(tmpFile, filePath);
 
-    return {
-      ok: true,
-      path: filePath,
-      bytes: Buffer.isBuffer(body) ? body.length : Buffer.byteLength(String(body), encoding),
-      backupPath,
-    };
+    return { ok: true, path: filePath, bytes: _byteLength(body, encoding), backupPath };
   } catch (err) {
-    // Only when the write got far enough to create it. The name carries 12 hex
-    // chars of entropy, so this cannot collide with a caller's real file.
-    if (tmpCreated) {
+    // The name carries 12 hex chars of entropy, so this cannot collide with a
+    // caller's real file.
+    if (tmpFile !== null) {
       try {
         fsUnlink(tmpFile);
       } catch {
         // Best-effort: never let cleanup replace the error the caller needs.
       }
     }
-    return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
+    return _fsErrorEnvelope(err);
+  }
+}
+
+/**
+ * Async twin of {@link atomicWriteWithBackup} (#1032): same tmp naming
+ * (`<dir>/<tmpPrefix>.<12 hex>`), same backup stamp, SAME envelope — and like
+ * the sync helper it RESOLVES on failure and never rejects. A `promise` mode on
+ * the sync function was rejected on purpose: one contract with two failure
+ * directions (`ok:false` vs. reject) is the bug class this envelope exists to
+ * end. Callers whose contract is to throw re-raise via {@link envelopeToError},
+ * which keeps the message and `err.code`.
+ *
+ * Shared with the sync helper: tmp/backup naming, byte count, the error
+ * envelope and the partial-adapter refusal. The five-step flow itself is
+ * spelled twice — sync calls and awaited calls cannot share one body without a
+ * generator driver, which would put an indirection on the hook-hot sync path
+ * for ~15 lines of saved control flow.
+ *
+ * Backup differs in one detail: it copies and treats `ENOENT` as "first write,
+ * nothing to snapshot" instead of probing `existsSync` first — the same result
+ * without a check-then-act window.
+ *
+ * @param {string} filePath  Target path; parent dirs created with mkdir -p semantics.
+ * @param {string|Buffer} body  Bytes to write, verbatim. Never inspected.
+ * @param {object} [opts]
+ * @param {BufferEncoding} [opts.encoding='utf8']  Encoding for a string `body`.
+ * @param {boolean} [opts.backup=false]  Snapshot the existing file to `.bak-<ISO>` first.
+ * @param {string} [opts.tmpPrefix='.tmp']  Tmp-file prefix (callers pick their domain prefix).
+ * @param {Date} [opts.now]  Clock seam for the backup stamp (tests).
+ * @param {{ mkdir?: Function, writeFile?: Function, rename?: Function,
+ *   copyFile?: Function, unlink?: Function }} [opts.fs]
+ *   Injectable `fs/promises`-shaped object (tests). Omitted methods fall back to
+ *   `node:fs/promises` — except `copyFile` under `backup: true`, which fails closed.
+ * @returns {Promise<{ ok: true, path: string, bytes: number, backupPath: string|null }
+ *   | { ok: false, reason: 'fs-error', error: string, code: string|null }>}
+ */
+export async function atomicWriteText(filePath, body, opts = {}) {
+  const {
+    encoding = 'utf8',
+    backup = false,
+    tmpPrefix = '.tmp',
+    now = new Date(),
+    fs: injectedFs,
+  } = opts;
+
+  const fsMkdir = injectedFs?.mkdir ?? mkdir;
+  const fsWriteFile = injectedFs?.writeFile ?? writeFile;
+  const fsRename = injectedFs?.rename ?? rename;
+  const fsCopyFile = injectedFs?.copyFile ?? copyFile;
+  const fsUnlink = injectedFs?.unlink ?? unlink;
+
+  const refusal = _partialAdapterRefusal(backup, injectedFs, ['copyFile']);
+  if (refusal) return refusal;
+
+  let tmpFile = null;
+
+  try {
+    const dir = dirname(filePath);
+    await fsMkdir(dir, { recursive: true });
+
+    let backupPath = null;
+    if (backup) {
+      const candidate = _backupPathFor(filePath, now);
+      try {
+        await fsCopyFile(filePath, candidate);
+        backupPath = candidate;
+      } catch (err) {
+        if (err?.code !== 'ENOENT') throw err;
+      }
+    }
+
+    tmpFile = _tmpPathFor(dir, tmpPrefix);
+    await fsWriteFile(tmpFile, body, encoding);
+    await fsRename(tmpFile, filePath);
+
+    return { ok: true, path: filePath, bytes: _byteLength(body, encoding), backupPath };
+  } catch (err) {
+    if (tmpFile !== null) {
+      try {
+        await fsUnlink(tmpFile);
+      } catch {
+        // Best-effort: never let cleanup replace the error the caller needs.
+      }
+    }
+    return _fsErrorEnvelope(err);
+  }
+}
+
+/**
+ * Re-raise a failed {@link atomicWriteText} / {@link atomicWriteWithBackup}
+ * envelope as an Error carrying the original message and `code`, for call-sites
+ * whose own contract is to throw (#1032).
+ *
+ * @param {{ error: string, code?: string|null }} envelope
+ * @returns {Error & { code?: string }}
+ */
+export function envelopeToError(envelope) {
+  const err = new Error(envelope.error);
+  if (envelope.code) err.code = envelope.code;
+  return err;
+}
+
+/** @returns {{ ok: false, reason: 'fs-error', error: string, code: string|null }} */
+function _fsErrorEnvelope(err) {
+  return {
+    ok: false,
+    reason: 'fs-error',
+    error: err?.message ?? String(err),
+    code: typeof err?.code === 'string' ? err.code : null,
+  };
+}
+
+/**
+ * Backup-path fail-closed for a partial injected adapter (see the rationale in
+ * {@link atomicWriteWithBackup}). Returns the refusal envelope, or null.
+ */
+function _partialAdapterRefusal(backup, injectedFs, methods) {
+  if (!backup || !injectedFs) return null;
+  for (const method of methods) {
+    if (typeof injectedFs[method] !== 'function') {
+      return {
+        ok: false,
+        reason: 'fs-error',
+        error: `partial fs adapter: ${method} required for backup`,
+        code: null,
+      };
+    }
   }
+  return null;
+}
+
+/** `<filePath>.bak-<ISO>` with `:`/`.` → `-`, so a lexical sort is chronological. */
+function _backupPathFor(filePath, now) {
+  const stamp = (now instanceof Date ? now : new Date()).toISOString().replace(/[:.]/g, '-');
+  return `${filePath}.bak-${stamp}`;
+}
+
+/** Sibling tmp path (same filesystem → atomic rename): `<dir>/<tmpPrefix>.<12 hex>`. */
+function _tmpPathFor(dir, tmpPrefix) {
+  return path.join(dir, `${tmpPrefix}.${randomBytes(6).toString('hex')}`);
+}
+
+function _byteLength(body, encoding) {
+  return Buffer.isBuffer(body) ? body.length : Buffer.byteLength(String(body), encoding);
 }
 
 /**

package/scripts/lib/learnings/candidates.mjs

@@ -48,11 +48,11 @@
  * re-derived (not re-cited) if a threshold is ever revisited.
  *
  * **Stage 0 — corpus prep (once per run).**
- *   1. Read through the existing funnel (`io.mjs::readLearnings` →
- *      `schema.mjs::normalizeLearning`) so producer dialects (`files` →
- *      `file_paths`) and type aliases (`gotcha` → `anti-pattern`) are already
- *      canonical. The in-memory entry point re-applies {@link normalizeDialects}
- *      so both entry points score the same shape.
+ *   1. Canonicalise producer dialects (`files` → `file_paths`) and type
+ *      aliases (`gotcha` → `anti-pattern`): the caller reads through the
+ *      existing funnel (`io.mjs::readLearnings` → `schema.mjs::normalizeLearning`),
+ *      and the entry point re-applies {@link normalizeDialects} so raw
+ *      in-memory records score the same shape.
  *   2. Drop expired records — they may neither seed a pool nor join one.
  *   3. Derive `learning_key` = `` `${type}/${kebab(title || subject)}` `` using
  *      the SHARED {@link kebab}. A divergent kebab does not produce an ugly
@@ -184,8 +184,7 @@
  */
 
 import { tokenize } from './affinity.mjs';
-import { readLearnings } from './io.mjs';
-import { kebab } from './kebab.mjs';
+import { learningKeyOf } from './kebab.mjs';
 import { normalizeDialects } from './schema.mjs';
 
 // ---------------------------------------------------------------------------
@@ -218,7 +217,7 @@ export const PATH_BOOST_EXACT = 0.05;
 export const PATH_BOOST_DIR = 0.025;
 
 /** How many leading directory segments define the directory-prefix boost. */
-export const DIR_PREFIX_SEGMENTS = 2;
+const DIR_PREFIX_SEGMENTS = 2;
 
 /**
  * Documented ceiling for consumers (accepted failure mode 2): a pool graph walk
@@ -229,7 +228,7 @@ export const DIR_PREFIX_SEGMENTS = 2;
 export const MAX_POOL_HOPS = 2;
 
 /** Token length floor — tokens shorter than this are dropped before stoplisting. */
-export const MIN_TOKEN_LENGTH = 3;
+const MIN_TOKEN_LENGTH = 3;
 
 /** Cap on the reported `sharedTokens` — a diagnostic for the judge, not a payload. */
 const SHARED_TOKEN_CAP = 8;
@@ -441,27 +440,18 @@ export function emptyPools() {
 /**
  * Logical identity of a learning: `` `${type}/${kebab(title || subject)}` ``.
  *
- * Returns `null` when either half is unusable — mirroring
- * `validate/check-learning-provenance.mjs::learningKeyOf`, so an unkeyable
- * record simply does not participate in the exact-key pass. It still seeds and
+ * Returns `null` when either half is unusable (non-record input, blank
+ * type/title/subject, or an all-symbol title that kebabs to '') — delegates to
+ * the shared `kebab.mjs::learningKeyOf` (#1021) so the key space cannot fork
+ * from the provenance checker's. An unkeyable record simply does not
+ * participate in the exact-key pass. It still seeds and
  * joins pools: a missing title is not a reason to hide a learning from dedupe.
  *
  * @param {unknown} record
  * @returns {string|null}
  */
 export function learningKey(record) {
-  if (!_isRecord(record)) return null;
-  const type = typeof record.type === 'string' ? record.type.trim() : '';
-  const titleOrSubject =
-    (typeof record.title === 'string' && record.title.trim() !== '' ? record.title : '') ||
-    (typeof record.subject === 'string' && record.subject.trim() !== '' ? record.subject : '');
-  if (type === '' || titleOrSubject === '') return null;
-  const slug = kebab(titleOrSubject);
-  // `kebab` may legally return '' (all-symbol input) — an empty slug is not an
-  // identity, so such a record is unkeyable rather than colliding with every
-  // other empty-slug record of the same type.
-  if (slug === '') return null;
-  return `${type}/${slug}`;
+  return learningKeyOf(record);
 }
 
 /**
@@ -714,23 +704,3 @@ export function buildCandidatePools(records, opts = {}) {
     return emptyPools();
   }
 }
-
-/**
- * File entry-point: read through the existing funnel (`readLearnings` →
- * `normalizeLearning`, so dialects and type aliases are canonical), then pool.
- *
- * There is no second reader here on purpose — a private read path would be a
- * second place for the dialect normalization to drift out of.
- *
- * @param {string} filePath — absolute path to learnings.jsonl
- * @param {object} [opts] — everything {@link buildCandidatePools} accepts
- * @returns {Promise<CandidatePools>} {@link emptyPools} on a missing/unreadable file
- */
-export async function buildCandidatePoolsFromFile(filePath, opts = {}) {
-  try {
-    const { entries } = await readLearnings(filePath);
-    return buildCandidatePools(entries, opts);
-  } catch {
-    return emptyPools();
-  }
-}

package/scripts/lib/learnings/io.mjs

@@ -262,6 +262,11 @@ export async function readLearningsSnapshot(filePath) {
  * malformed too (#1500): `normalizeLearning` turned it into a record of
  * defaults alone, and every rewrite wrote that invented record back.
  *
+ * A UTF-8 BOM (U+FEFF) in front of the FIRST line — an editor's save — is
+ * stripped before parsing, so that line is an entry, not malformed (#1506.5b).
+ * A BOM inside the file (line 2+) stays malformed: that is a concatenation
+ * artefact the drop-malformed preview reports as `bom`.
+ *
  * @param {string} raw
  * @returns {{entries: object[], malformed: string[], malformedLineNumbers: number[]}}
  *   `malformedLineNumbers[i]` is the 1-based line of `malformed[i]` in `raw`
@@ -273,7 +278,7 @@ export function parseLearningsText(raw) {
   raw.split('\n').forEach((line, i) => {
     if (line.trim().length === 0) return;
     try {
-      const parsed = JSON.parse(line);
+      const parsed = JSON.parse(i === 0 && line.charCodeAt(0) === 0xfeff ? line.slice(1) : line);
       if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new TypeError('not a JSON object');
       }
@@ -414,7 +419,7 @@ const BACKUP_KEEP = 3;
  * @param {string} fileName — sibling filename to classify
  * @returns {string|null} the suffix after the delimiter, or `null`
  */
-export function backupSuffixOf(baseName, fileName) {
+function backupSuffixOf(baseName, fileName) {
   const stem = `${baseName}.bak`;
   if (!fileName.startsWith(stem)) return null;
   const delim = fileName[stem.length];