kestrel.markets/src/cli/backend/catalog-records.ts

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

/**
 * # cli/backend/catalog-records — the LOADER for the baked catalog-conformant contract fixture (kestrel-djm.5, kestrel-nvxb)
 *
 * The pre-computed, content-addressed protocol artifacts the catalog-conformant contract server
 * ({@link ./mock.ts}) serves so the SDK's HTTP transport returns the SAME protocol Blotter / transcript /
 * grade / root the LOCAL projection yields (the djm.5 headline reconciliation).
 *
 * kestrel-nvxb (arch-review A8): the ~7,200-line generated `CATALOG_RECORDS` literal that used to live INLINE
 * in this source file — 99% of the largest file in the tree — is now a BUILD ARTIFACT at
 * {@link ../../../artifacts/sdk/catalog-records.json}, generated by scripts/sdk/bake-catalog-records.ts. This
 * module is a thin, hand-written, STABLE loader: it statically imports that JSON data artifact (a pure-data
 * value edge — no engine, no code) and re-exports it under the djm.2 protocol types. Moving the literal out
 * of `src/` does NOT change the served bytes: `mock.ts`'s `json()` stringifies the SAME in-memory objects in
 * the SAME key order (JSON.parse preserves the artifact's key order), so `GET /catalog` and the served
 * records are byte-identical to the old inline form.
 *
 * Guards on this fixture:
 *  - tests/sdk.transports.test.ts            — HTTP↔LOCAL protocol digest parity (the drift guard).
 *  - tests/sdk.transport-fixture-freshness.test.ts — every baked record byte-equals a fresh LOCAL engine run.
 *  - tests/cli.mock-catalog-bytes.test.ts    — the REAL mock server serves byte-identical records through the
 *                                              loader+artifact seam (the kestrel-nvxb served-byte parity guard).
 * Regenerate on any engine / catalog-root change:
 *   bun scripts/sdk/bake-catalog-records.ts
 *
 * LIGHT: the loader imports ONLY the pure-data JSON artifact + type-only protocol imports (erased) — the
 * server stays on the light remote graph (tests/package.boundary.test.ts).
 */

import type { Blotter, GradeResult } from "../../protocol/index.ts";
import type { CatalogEntry } from "../../protocol/catalog.ts";
import type { TurnBody } from "../../protocol/session.ts";
import catalogRecordsArtifact from "../../../artifacts/sdk/catalog-records.json" with { type: "json" };

/** A pentad-chained transcript entry as carried on the wire (the djm.2 TurnEntry, ids as plain strings). */
export interface WireTurnEntry {
  readonly kind: "turn";
  readonly sessionId: string;
  readonly ordinal: number;
  readonly parentHash: string;
  readonly frameRoot: string;
  readonly authoredSha256: string;
  readonly body: TurnBody;
  readonly entryHash: string;
}

/** The complete server-computed record of ONE catalog Session run — the pre-computed truth the HTTP
 * transport replays. Every field is a djm.2 protocol fact; the `frames` are the delivered Frames (opaque
 * here — the transport re-exposes them verbatim). */
export interface CatalogSessionRecord {
  readonly entryId: string;
  readonly sessionId: string;
  readonly blotter: Blotter;
  readonly grade: GradeResult;
  readonly tipHash: string;
  readonly conformanceRoot: string;
  readonly artifacts: readonly string[];
  readonly entries: readonly WireTurnEntry[];
  readonly frames: readonly unknown[];
}

/** The on-disk shape of the baked data artifact (artifacts/sdk/catalog-records.json) — the three protocol
 * facts the light server replays. The JSON is machine-generated (bake-catalog-records.ts) and content-pinned
 * by the freshness + served-byte guards, so the cast is safe: any structural drift trips a RED guard. */
interface CatalogRecordsArtifact {
  readonly catalogEntries: readonly CatalogEntry[];
  readonly records: Record<string, CatalogSessionRecord>;
  readonly sessionToEntry: Readonly<Record<string, string>>;
}

const artifact = catalogRecordsArtifact as unknown as CatalogRecordsArtifact;

/** The djm.8 mirror view — the SAME CatalogEntry[] the LOCAL loader yields (baked so the light server needs
 * no engine to serve GET /catalog). The transport-parity test pins byte-equality with `catalogEntries()`. */
export const CATALOG_ENTRIES: readonly CatalogEntry[] = artifact.catalogEntries;

/** The baked per-entry Session records, keyed by catalog entry id. */
export const CATALOG_RECORDS: Record<string, CatalogSessionRecord> = artifact.records;

/** Reverse map: a baked Session id → its catalog entry id (the server dispatches /grade on the graded
 * Blotter's sessionId). */
export const SESSION_TO_ENTRY: Readonly<Record<string, string>> = artifact.sessionToEntry;