dsh-llm-fallbacks 0.6.5 → 0.6.7

package/scripts/session-logs/catalog.ts

@@ -67,12 +67,20 @@ const CATALOG_PACKAGE_DIR = 'dsh-session-format-catalog'
 export const CATALOG_ENV_VAR = 'DSH_SESSION_FORMAT_CATALOG'
 
 /**
- * The oldest released catalog this tool accepts as its oracle: the format
+ * The oldest released catalog this tool accepts as its oracle AND the format
  * generation it repairs TO (`CURRENT_VERSION_FLOOR`, the pre-V3 scope). A catalog
  * below it cannot read a successor this tool would write, so `--apply` must
  * refuse rather than verify its own output against a build the GUI does not run.
  * One constant for both the selection scope and the oracle floor: they are the
  * same number and must not drift.
+ *
+ * The repair target stays at this floor even when the installed build is newer:
+ * the tool only repairs logs BELOW the floor, and the next released edge
+ * (V3→V4) requires historical child evidence (one parent's complete child
+ * descriptors) that a single-log repair cannot produce. The successor is
+ * therefore encoded through the newer build's own `historicalSessionFormatCatalog`
+ * (see {@link CatalogHandle.floor}) and the host migrates it onward, with its own
+ * child facts, exactly like any other readable pre-V3 session it opens.
  */
 export const REQUIRED_CATALOG_VERSION = 3
 
@@ -131,24 +139,77 @@ export interface CatalogHandle {
   readonly packageVersion: string | null
   /** The released catalog module's `sessionFormatCatalog` export. */
   readonly catalog: ReleasedCatalog
+  /**
+   * The catalog generation this tool REPAIRS TO — the format floor
+   * ({@link REQUIRED_CATALOG_VERSION}): the declared catalog itself when the
+   * resolved build is AT the floor, otherwise that build's
+   * `historicalSessionFormatCatalog` export (the V0–V3 reader/encoder).
+   *
+   * Every restore, classification and published successor goes through this
+   * catalog, so the successor's header version (and the `N` in its canonical
+   * filename) is the floor, never a generation whose migration needs evidence a
+   * single-log repair cannot supply. `null` when the resolved build is newer than
+   * the floor but exposes no usable historical catalog: the caller refuses the
+   * whole run through {@link catalogVersionRefusal} (fatal, exit 2) instead of
+   * publishing a generation it cannot restore, verify or hand to the host.
+   */
+  readonly floor: ReleasedCatalog | null
 }
 
 /**
  * Why a resolved catalog may not be used as this run's oracle, or `null` when it
  * may. The caller turns a non-`null` reason into a fatal (exit 2) refusal: a
  * below-floor catalog would encode a successor this tool's own read-back cannot
- * vouch for, and the GUI would not run it either.
+ * vouch for, and the GUI would not run it either; a newer build without a usable
+ * repair floor could not be restored or encoded at all.
  */
 export function catalogVersionRefusal(handle: CatalogHandle): string | null {
   const version = handle.catalog.currentVersion
-  if (typeof version === 'number' && Number.isSafeInteger(version) && version >= REQUIRED_CATALOG_VERSION) {
-    return null
+  if (!(typeof version === 'number' && Number.isSafeInteger(version) && version >= REQUIRED_CATALOG_VERSION)) {
+    return `the resolved released catalog at ${handle.modulePath}`
+      + `${handle.packageVersion === null ? '' : ` (package version ${handle.packageVersion})`}`
+      + ` declares currentVersion ${JSON.stringify(version)}, but this tool requires at least `
+      + `${REQUIRED_CATALOG_VERSION}: it would publish a successor that build cannot read. `
+      + 'Point --catalog (or DSH_SESSION_FORMAT_CATALOG) at the catalog of the release the GUI runs.'
+  }
+  if (handle.floor === null) {
+    return `the resolved released catalog at ${handle.modulePath}`
+      + `${handle.packageVersion === null ? '' : ` (package version ${handle.packageVersion})`}`
+      + ` declares currentVersion ${version}, but it exposes no usable historicalSessionFormatCatalog at the `
+      + `repair floor (v${REQUIRED_CATALOG_VERSION}). This tool repairs pre-V3 logs by publishing a v`
+      + `${REQUIRED_CATALOG_VERSION} successor: the V3→V4 edge needs historical child evidence that a single-log `
+      + 'repair cannot supply, so the floor reader/encoder is what restores and verifies the successor and the '
+      + 'host migrates it onward when it opens the session. Point --catalog (or DSH_SESSION_FORMAT_CATALOG) at '
+      + `a build that declares currentVersion >= ${REQUIRED_CATALOG_VERSION} and still exports `
+      + 'historicalSessionFormatCatalog.'
+  }
+  const floorVersion = handle.floor.currentVersion
+  if (!(typeof floorVersion === 'number' && Number.isSafeInteger(floorVersion)
+    && floorVersion >= REQUIRED_CATALOG_VERSION && floorVersion <= version)) {
+    return `the resolved released catalog at ${handle.modulePath} exposes a repair-floor catalog that declares `
+      + `currentVersion ${JSON.stringify(floorVersion)}, but this tool requires a floor of at least `
+      + `${REQUIRED_CATALOG_VERSION} no greater than the declared currentVersion ${version}. `
+      + 'Point --catalog (or DSH_SESSION_FORMAT_CATALOG) at the catalog of the release the GUI runs.'
   }
-  return `the resolved released catalog at ${handle.modulePath}`
-    + `${handle.packageVersion === null ? '' : ` (package version ${handle.packageVersion})`}`
-    + ` declares currentVersion ${JSON.stringify(version)}, but this tool requires at least `
-    + `${REQUIRED_CATALOG_VERSION}: it would publish a successor that build cannot read. `
-    + 'Point --catalog (or DSH_SESSION_FORMAT_CATALOG) at the catalog of the release the GUI runs.'
+  return null
+}
+
+/**
+ * The catalog generation this tool repairs TO (see {@link CatalogHandle.floor}).
+ *
+ * Callers reach this only after {@link catalogVersionRefusal} accepted the handle;
+ * the throw is the fail-closed backstop for a caller that skipped that gate (a
+ * restore or encode through a missing floor must never degrade to "nothing was
+ * published").
+ */
+export function repairCatalog(handle: CatalogHandle): ReleasedCatalog {
+  if (handle.floor === null) {
+    throw new Error(
+      `the resolved session-format catalog exposes no usable repair-floor catalog (v${REQUIRED_CATALOG_VERSION}): `
+      + 'refusing to restore or encode a successor with it',
+    )
+  }
+  return handle.floor
 }
 
 /** Inputs for {@link resolveCatalog}. */
@@ -195,19 +256,44 @@ async function loadCatalog(
   const modulePath = resolveCatalogEntry(candidate, env)
   if (modulePath === null) return null
   try {
-    const loaded = (await import(pathToFileURL(modulePath).href)) as { sessionFormatCatalog?: unknown }
+    const loaded = (await import(pathToFileURL(modulePath).href)) as {
+      sessionFormatCatalog?: unknown
+      historicalSessionFormatCatalog?: unknown
+    }
     if (!isReleasedCatalog(loaded.sessionFormatCatalog)) return null
     return {
       modulePath,
       resolvedBy,
       packageVersion: catalogPackageVersion(modulePath),
       catalog: loaded.sessionFormatCatalog,
+      floor: floorCatalogOf(loaded.sessionFormatCatalog, loaded.historicalSessionFormatCatalog),
     }
   } catch {
     return null
   }
 }
 
+/**
+ * The catalog generation this tool repairs TO: the declared catalog itself when
+ * the resolved build is at or below the floor, otherwise that build's
+ * `historicalSessionFormatCatalog` export.
+ *
+ * A build newer than the floor publishes nothing but its own current generation,
+ * and the released V3→V4 edge needs historical child evidence no single-log
+ * repair can produce; the historical export is that build's own V0–V3
+ * reader/encoder, so restoring through it and encoding the floor generation is
+ * the only successor the tool can both verify and hand to the host.
+ *
+ * @param catalog the module's declared `sessionFormatCatalog`.
+ * @param historical the module's `historicalSessionFormatCatalog`, unknown.
+ * @returns the floor catalog, or `null` when a newer build exposes none.
+ */
+function floorCatalogOf(catalog: ReleasedCatalog, historical: unknown): ReleasedCatalog | null {
+  if (catalog.currentVersion <= REQUIRED_CATALOG_VERSION) return catalog
+  if (isReleasedCatalog(historical) && historical.currentVersion === REQUIRED_CATALOG_VERSION) return historical
+  return null
+}
+
 /**
  * The owning catalog package's own `version`, walking up from a module entry to
  * the nearest `package.json` that names the catalog package; `null` when none is
@@ -526,7 +612,12 @@ function refusalClass(error: unknown): RefusalClass {
  * The restore runs under the pinned policy
  * `createRestore(header, { recovery: 'recoverable', validation: 'transformed' })`
  * and every row is decoded before `finish()`, so the class is the one the
- * released chain raises first for this log.
+ * released chain raises first for this log on its way to the REPAIR FLOOR
+ * ({@link CatalogHandle.floor}) — the pre-V3 chain this tool repairs along and
+ * the generation it publishes. With a newer installed build the floor is that
+ * build's `historicalSessionFormatCatalog`; the host's forward migration from
+ * the floor to current (which needs corpus-level child evidence) is outside a
+ * single log's verdict.
  *
  * Returned classes: `'ok'` when the restore completes, `'source-kind'`,
  * `'subagent-descriptor-version'`, `'unknown-event-type'` for the three released
@@ -539,7 +630,7 @@ function refusalClass(error: unknown): RefusalClass {
  */
 export function classifyWithCatalog(rows: readonly ParsedRow[], catalog: CatalogHandle): RefusalClass {
   try {
-    restoreRows(catalog.catalog, rows, { recovery: 'recoverable', validation: 'transformed' })
+    restoreRows(repairCatalog(catalog), rows, { recovery: 'recoverable', validation: 'transformed' })
     return 'ok'
   } catch (error) {
     return refusalClass(error)

package/scripts/session-logs/publish.ts

@@ -14,7 +14,11 @@
  *     (`ZSTD_c_checksumFlag`), exactly like the released writer.
  * The successor's records come from the RELEASED encoder
  * (`encodeCurrentHeader` / `encodeCurrentEvent`), not from the input rows, so
- * the written generation is whatever the catalog considers current.
+ * the written generation is whatever the catalog's REPAIR FLOOR considers
+ * current — v3 when the installed build is newer (see `CatalogHandle.floor`).
+ * The host then migrates that v3 generation onward to the installed current
+ * format with its own historical child evidence; this module never paints a
+ * generation whose migration needs corpus-level facts a single log lacks.
  *
  * COMPRESSION — Node's `node:zlib` zstd API, no `zstd` CLI (measured on
  * v24.18.0: `zstdCompress`/`zstdDecompress` exist and are used here):
@@ -66,7 +70,7 @@ import { link, readFile, rm, writeFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { constants, zstdCompressSync, zstdDecompressSync } from 'node:zlib'
 import type { CatalogHandle, ReleasedArtifact, ReleasedCatalog } from './catalog.ts'
-import { restoreRows } from './catalog.ts'
+import { repairCatalog, restoreRows } from './catalog.ts'
 import type { ParsedRow } from './rules.ts'
 
 /** Zstandard frame magic (little-endian `0xFD2FB528`). */
@@ -333,8 +337,9 @@ function sizeToNumber(buffer: Buffer, offset: number, width: number): number | n
  * function, which it receives from `runRepair`'s dynamic import of this module
  * (a static import would defeat the `node:zlib` zstd runtime probe that must run
  * first). `publishSuccessor` derives its target from the RESTORED header's
- * version, the CLI's probe from the resolved catalog's declared
- * `currentVersion` — see the probe's comment in `repair-session-logs.ts`.
+ * version (the repair floor), and the CLI's probe resolves the floor's
+ * `currentVersion` through the catalog handle — the two agree for every released
+ * catalog, whose restore settles at the floor it was chosen for.
  */
 export function successorFilename(version: number): string {
   return version === 0 ? 'session.jsonl.zstd' : `session.v${version}.jsonl.zstd`
@@ -382,6 +387,13 @@ export async function publishSuccessor(
   sourceDigest: string,
 ): Promise<PublishedSuccessor> {
   const handle = assertCatalog(catalog)
+  // The generation this tool repairs TO: the declared catalog itself on a build
+  // at the floor, the build's own historical V0–V3 catalog on a newer one. A
+  // restore through the newer build's current catalog would demand historical
+  // child evidence this single-log tool cannot produce; the floor restore has no
+  // such requirement, and the host migrates the published floor generation
+  // onward with its own child facts.
+  const floor = repairCatalog(handle)
   const originalBytes = await readFile(logPath)
   const originalDigest = sha256(originalBytes)
   if (originalDigest !== sourceDigest) {
@@ -394,7 +406,7 @@ export async function publishSuccessor(
   // Defensive copy: the caller's rows alias `form` / `summary` / `sections`
   // objects, and the released restore may normalize the artifact in place.
   const rows = structuredClone(normalizedRows)
-  const artifact = restoreRows(handle.catalog, rows, { recovery: 'strict', validation: 'transformed' })
+  const artifact = restoreRows(floor, rows, { recovery: 'strict', validation: 'transformed' })
   const generation = artifact.header.version
   const targetPath = join(dirname(logPath), successorFilename(generation))
   if (resolve(targetPath) === resolve(logPath)) {
@@ -405,10 +417,10 @@ export async function publishSuccessor(
   // (lazily): materializing them all first would hold a second copy of the session
   // alongside the restored artifact it was built from.
   const encodedEvents = function* (): Generator<Record<string, unknown>> {
-    for (const event of artifact.events) yield handle.catalog.encodeCurrentEvent(event)
+    for (const event of artifact.events) yield floor.encodeCurrentEvent(event)
   }
   const bytes = encodeZstdFrames(
-    handle.catalog.encodeCurrentHeader(artifact.header, artifact.inheritedEventCount),
+    floor.encodeCurrentHeader(artifact.header, artifact.inheritedEventCount),
     encodedEvents(),
   )
 
@@ -422,8 +434,10 @@ export async function publishSuccessor(
     // names instead of ignoring them.
     await writeFile(temporaryPath, bytes, { flag: 'wx', mode: 0o600 })
     // Read the staged generation back with the host's current-generation policy
-    // BEFORE it becomes visible under its canonical name.
-    verifyGeneration(handle.catalog, await readFile(temporaryPath), generation)
+    // BEFORE it becomes visible under its canonical name. The floor catalog is
+    // the one that must read it: it is the build whose encoder wrote it and the
+    // same historical reader the host uses for a pre-current generation.
+    verifyGeneration(floor, await readFile(temporaryPath), generation)
     outcome = await publishExclusive(temporaryPath, targetPath, sha256(bytes))
   } catch (error) {
     try {