create-principles-disciple 1.132.2 → 1.132.4

package/codex-adapter/dist/ingestion/codex-home.d.ts

@@ -0,0 +1,19 @@
+export type CodexHomeResolution = {
+    ok: true;
+    home: string;
+} | {
+    ok: false;
+    reason: string;
+    nextAction: string;
+};
+/**
+ * Canonicalize a Windows path to its final long form. Node's JS realpath
+ * preserves 8.3 short-name segments (ADMINI~1), while hook payloads carry
+ * the long form — containment comparisons must use one canonical form, so
+ * prefer the native realpath (GetFinalPathNameByHandle) and fall back to
+ * the JS implementation where native is unavailable.
+ */
+export declare function canonicalizePath(target: string): string;
+export declare function resolveCodexHome(env?: {
+    CODEX_HOME?: string | undefined;
+}): CodexHomeResolution;

package/codex-adapter/dist/ingestion/codex-home.js

@@ -0,0 +1,43 @@
+/**
+ * Codex home resolution (G1 probe report §7, source-pinned from
+ * codex-rs/utils/home-dir/src/lib.rs find_codex_home).
+ *
+ * Rules: CODEX_HOME, when set and non-empty, MUST already exist and be a
+ * directory and is canonicalized; a missing path or a file path is an error.
+ * When unset, the home comes from the OS home directory plus `.codex`, and
+ * existence is NOT verified. There is one OS-generic implementation.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Canonicalize a Windows path to its final long form. Node's JS realpath
+ * preserves 8.3 short-name segments (ADMINI~1), while hook payloads carry
+ * the long form — containment comparisons must use one canonical form, so
+ * prefer the native realpath (GetFinalPathNameByHandle) and fall back to
+ * the JS implementation where native is unavailable.
+ */
+export function canonicalizePath(target) {
+    try {
+        return fs.realpathSync.native(target);
+    }
+    catch {
+        return fs.realpathSync(target);
+    }
+}
+export function resolveCodexHome(env = process.env) {
+    const configured = env.CODEX_HOME;
+    if (configured !== undefined && configured.trim() !== '') {
+        try {
+            const stats = fs.statSync(configured);
+            if (!stats.isDirectory()) {
+                return { ok: false, reason: 'codex_home_not_directory', nextAction: 'CODEX_HOME must point at an existing directory (Codex fatal-error contract).' };
+            }
+            return { ok: true, home: canonicalizePath(configured) };
+        }
+        catch {
+            return { ok: false, reason: 'codex_home_unavailable', nextAction: 'CODEX_HOME is set but does not exist; unset it or create the directory.' };
+        }
+    }
+    return { ok: true, home: path.join(os.homedir(), '.codex') };
+}

package/codex-adapter/dist/ingestion/codex-version.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Supported Codex ingestion version contract (Codex Governance Closure
+ * Slice A; ADR-0020 §11.2 + G1 probe report §9).
+ *
+ * The G1 contract baseline is: minimum supported Codex 0.148.0, verified
+ * on-device at 0.150.1. The transcript itself carries `session_meta.
+ * payload.cli_version`, which is the version signal available inside a hook
+ * subprocess (hook payloads carry no version field — G1 fixture contract).
+ *
+ * Older-than-minimum and newer-than-verified versions both degrade
+ * explicitly; an unknown version must never silently guess record fields.
+ * Adopting a newer Codex version requires re-running the contract probe and
+ * refreshing the fixtures (G1 report §9 drift-detection boundary).
+ */
+export declare const CODEX_INGESTION_MIN_VERSION = "0.148.0";
+export declare const CODEX_INGESTION_VERIFIED_VERSION = "0.150.1";
+export type CodexVersionClassification = {
+    status: 'supported';
+} | {
+    status: 'unsupported_below';
+    reason: 'unsupported_codex_version';
+} | {
+    status: 'unverified_above';
+    reason: 'codex_version_unverified';
+} | {
+    status: 'unknown';
+    reason: 'codex_version_unverified';
+};
+export declare const CODEX_VERSION_NEXT_ACTION = "rerun the Codex contract probe / update supported fixtures (docs/architecture/CODEX_G1_CONTRACT_PROBE_REPORT.md \u00A79)";
+export declare function classifyCodexVersion(cliVersion: string | null | undefined): CodexVersionClassification;

package/codex-adapter/dist/ingestion/codex-version.js

@@ -0,0 +1,53 @@
+/**
+ * Supported Codex ingestion version contract (Codex Governance Closure
+ * Slice A; ADR-0020 §11.2 + G1 probe report §9).
+ *
+ * The G1 contract baseline is: minimum supported Codex 0.148.0, verified
+ * on-device at 0.150.1. The transcript itself carries `session_meta.
+ * payload.cli_version`, which is the version signal available inside a hook
+ * subprocess (hook payloads carry no version field — G1 fixture contract).
+ *
+ * Older-than-minimum and newer-than-verified versions both degrade
+ * explicitly; an unknown version must never silently guess record fields.
+ * Adopting a newer Codex version requires re-running the contract probe and
+ * refreshing the fixtures (G1 report §9 drift-detection boundary).
+ */
+export const CODEX_INGESTION_MIN_VERSION = '0.148.0';
+export const CODEX_INGESTION_VERIFIED_VERSION = '0.150.1';
+export const CODEX_VERSION_NEXT_ACTION = 'rerun the Codex contract probe / update supported fixtures (docs/architecture/CODEX_G1_CONTRACT_PROBE_REPORT.md §9)';
+function isDigits(value) {
+    return value.length > 0 && /^[0-9]+$/.test(value);
+}
+function parseSemver(value) {
+    const parts = value.trim().split('.');
+    if (parts.length < 3)
+        return null;
+    const [major, minor, patch] = parts;
+    if (major === undefined || minor === undefined || patch === undefined)
+        return null;
+    if (!isDigits(major) || !isDigits(minor) || !isDigits(patch))
+        return null;
+    return { major: Number(major), minor: Number(minor), patch: Number(patch) };
+}
+function compareSemver(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    return a.patch - b.patch;
+}
+export function classifyCodexVersion(cliVersion) {
+    if (typeof cliVersion !== 'string' || cliVersion.trim().length === 0) {
+        return { status: 'unknown', reason: 'codex_version_unverified' };
+    }
+    const version = parseSemver(cliVersion);
+    const min = parseSemver(CODEX_INGESTION_MIN_VERSION);
+    const verified = parseSemver(CODEX_INGESTION_VERIFIED_VERSION);
+    if (!version || !min || !verified)
+        return { status: 'unknown', reason: 'codex_version_unverified' };
+    if (compareSemver(version, min) < 0)
+        return { status: 'unsupported_below', reason: 'unsupported_codex_version' };
+    if (compareSemver(version, verified) > 0)
+        return { status: 'unverified_above', reason: 'codex_version_unverified' };
+    return { status: 'supported' };
+}

package/codex-adapter/dist/ingestion/ingestion-fields.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Codex hook payload field extraction (Slice A) — shared by the live
+ * observation ingestor and the Slice B admission orchestrator.
+ */
+export interface PayloadFields {
+    transcriptPath: string | null;
+    sessionId: string;
+    turnId: string | null;
+    prompt: string | null;
+    toolUseId: string | null;
+    toolName: string | null;
+    toolInput: unknown;
+    toolResponse: unknown;
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function own(value: Record<string, unknown>, key: string): unknown;
+export declare function extractFields(raw: unknown): PayloadFields | null;

package/codex-adapter/dist/ingestion/ingestion-fields.js

@@ -0,0 +1,28 @@
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function own(value, key) {
+    return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+export function extractFields(raw) {
+    if (!isRecord(raw))
+        return null;
+    const transcriptPath = own(raw, 'transcript_path');
+    if (transcriptPath !== null && typeof transcriptPath !== 'string')
+        return null;
+    const sessionId = own(raw, 'session_id');
+    const turnId = own(raw, 'turn_id');
+    const prompt = own(raw, 'prompt');
+    const toolUseId = own(raw, 'tool_use_id');
+    const toolName = own(raw, 'tool_name');
+    return {
+        transcriptPath: transcriptPath ?? null,
+        sessionId: typeof sessionId === 'string' ? sessionId : '',
+        turnId: typeof turnId === 'string' ? turnId : null,
+        prompt: typeof prompt === 'string' ? prompt : null,
+        toolUseId: typeof toolUseId === 'string' ? toolUseId : null,
+        toolName: typeof toolName === 'string' ? toolName : null,
+        toolInput: own(raw, 'tool_input'),
+        toolResponse: own(raw, 'tool_response'),
+    };
+}

package/codex-adapter/dist/ingestion/ingestion.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Codex conversation ingestion orchestrator (Codex Governance Closure
+ * Slice A; SPEC rev 2 §7/§9/§17).
+ *
+ * Called by pd-hook ONLY after both `host.codex` and
+ * `codex_conversation_ingestion` are enabled — the flag check happens
+ * before any transcript filesystem I/O, so flag-off means this module is
+ * never entered and the transcript boundary receives zero calls (SPEC §10
+ * hard privacy invariant, proven by a port spy test).
+ *
+ * Responsibilities: extract validated ingestion fields from the raw hook
+ * payload (Codex protocol facts live in the adapter, not host-runtime),
+ * authorize the transcript path, run bounded incremental decoding from the
+ * durable checkpoint, apply the supported-version guard, and hand the
+ * projected observations to the host-neutral host-runtime seam.
+ *
+ * Stop (`turn_complete`) is the turn-complete ingestion trigger (G1 §2);
+ * live `UserPromptSubmit`/`PostToolUse` contribute live observations that
+ * the transcript replay later converges with (SPEC §10 source precedence).
+ */
+import type { HostEventKind } from '@principles/core/host';
+import { type GovernanceSignalCandidate } from '@principles/host-runtime';
+import { type TranscriptPort } from './transcript-decoder.js';
+export interface CodexIngestionOptions {
+    readonly workspaceDir: string;
+    readonly env?: {
+        CODEX_HOME?: string | undefined;
+    };
+    readonly now?: Date;
+    readonly port?: TranscriptPort;
+}
+export type CodexIngestionOutcome = {
+    status: 'ok';
+    inserted: number;
+    enriched: number;
+    duplicates: number;
+    warnings: readonly string[];
+    lagBytes: number;
+    /** Slice B: normalized admission candidates for the committed observations (host-neutral; consumed by pd-hook's admission pass). */
+    readonly admissionCandidates: readonly GovernanceSignalCandidate[];
+    readonly rolloutIdentity: string;
+} | {
+    status: 'degraded';
+    reason: string;
+    nextAction: string;
+    warnings: readonly string[];
+};
+/** Test seam: inject/inspect the transcript filesystem boundary (zero-read proofs). */
+export declare function setCodexTranscriptPortForTest(port: TranscriptPort | null): void;
+export declare function ingestCodexConversation(rawPayload: unknown, kind: HostEventKind, options: CodexIngestionOptions): CodexIngestionOutcome;
+export interface CodexTranscriptFromPathArgs {
+    readonly workspaceDir: string;
+    /** Absolute transcript path (catch-up resolves it by exact rollout identity before calling). */
+    readonly transcriptPath: string;
+    /** Fallback root session when neither the transcript nor the checkpoint carries one. */
+    readonly fallbackRootSessionId: string;
+    readonly env?: {
+        CODEX_HOME?: string | undefined;
+    };
+    readonly now?: Date;
+    readonly port?: TranscriptPort;
+}
+/**
+ * PRI-624 (Slice C): bounded incremental ingest of one known rollout from its
+ * durable checkpoint, driven by an explicit transcript path instead of a live
+ * hook payload. The path is re-authorized through the same
+ * `validateCodexTranscriptPath` containment + post-open identity contract the
+ * hook path uses (SPEC §9) — callers MUST only pass paths resolved from
+ * previously-authenticated rollouts (checkpoints), never discovered sessions.
+ */
+export declare function ingestCodexTranscriptFromPath(args: CodexTranscriptFromPathArgs): CodexIngestionOutcome;

package/codex-adapter/dist/ingestion/ingestion.js

@@ -0,0 +1,248 @@
+import { ingestGovernanceObservations, readGovernanceCheckpoint, } from '@principles/host-runtime';
+import { resolveCodexHome } from './codex-home.js';
+import { validateCodexTranscriptPath } from './transcript-path.js';
+import { classifyCodexVersion, CODEX_VERSION_NEXT_ACTION } from './codex-version.js';
+import { decodeTranscriptWindow, createNodeTranscriptPort, CODEX_INGESTION_MAX_BATCH_BYTES, TranscriptReplacedError } from './transcript-decoder.js';
+import { extractFields } from './ingestion-fields.js';
+import { buildLiveCorrectionCandidate, buildLiveToolCandidate, buildTranscriptCandidates } from './admission.js';
+let activePort = null;
+/** Test seam: inject/inspect the transcript filesystem boundary (zero-read proofs). */
+export function setCodexTranscriptPortForTest(port) {
+    activePort = port;
+}
+function activeTranscriptPort(options) {
+    return options.port ?? activePort ?? createNodeTranscriptPort();
+}
+function ingestLiveObservation({ fields, rolloutIdentity, workspaceDir, now }) {
+    const nowIso = now.toISOString();
+    let observation = null;
+    if (fields.turnId !== null && fields.prompt !== null) {
+        observation = {
+            hostKind: 'codex',
+            rolloutIdentity,
+            rootSessionId: fields.sessionId,
+            hostTurnId: fields.turnId,
+            kind: 'user_turn',
+            logicalObservationKey: `codex|${rolloutIdentity}|${fields.turnId}|user`,
+            visibleText: fields.prompt,
+            source: 'live_hook',
+            completeness: 'complete',
+            observedAt: nowIso,
+        };
+    }
+    else if (fields.turnId !== null && fields.toolUseId !== null) {
+        observation = {
+            hostKind: 'codex',
+            rolloutIdentity,
+            rootSessionId: fields.sessionId,
+            hostTurnId: fields.turnId,
+            kind: 'tool_call',
+            logicalObservationKey: `codex|${rolloutIdentity}|${fields.toolUseId}`,
+            toolUseId: fields.toolUseId,
+            toolFacts: {
+                toolName: fields.toolName,
+                params: fields.toolInput ?? null,
+                result: fields.toolResponse ?? null,
+            },
+            source: 'live_hook',
+            completeness: 'complete',
+            observedAt: nowIso,
+        };
+    }
+    if (observation === null) {
+        return { status: 'degraded', reason: 'transcript_path_invalid', nextAction: 'the live event lacks turn/prompt/tool identity; no observation was written.', warnings: [] };
+    }
+    const result = ingestGovernanceObservations({
+        workspaceDir,
+        observations: [observation],
+        now,
+    });
+    if (!result.ok)
+        return { status: 'degraded', reason: result.reason ?? 'governance_write_failed', nextAction: result.nextAction ?? 'inspect the workspace trajectory database.', warnings: result.warnings };
+    // Slice B: hand the live observation to the admission pass as a normalized
+    // candidate (SPEC §12) — the caller (pd-hook) runs detection/admission.
+    const candidate = observation.kind === 'user_turn'
+        ? buildLiveCorrectionCandidate({ fields, rolloutIdentity })
+        : buildLiveToolCandidate({ fields, rolloutIdentity });
+    return {
+        status: 'ok', inserted: result.inserted, enriched: result.enriched, duplicates: result.duplicates, warnings: result.warnings, lagBytes: 0,
+        admissionCandidates: candidate !== null ? [candidate] : [],
+        rolloutIdentity,
+    };
+}
+function ingestTranscriptDelta({ fallbackRootSessionId, canonicalPath, identity, rolloutIdentity, workspaceDir, now, port }) {
+    const checkpoint = readGovernanceCheckpoint({ workspaceDir, hostKind: 'codex', rolloutIdentity });
+    if (checkpoint !== null && !('byteOffset' in checkpoint) && 'ok' in checkpoint && checkpoint.ok === false) {
+        return { status: 'degraded', reason: checkpoint.reason, nextAction: checkpoint.nextAction, warnings: [] };
+    }
+    const existing = checkpoint !== null && 'byteOffset' in checkpoint ? checkpoint : null;
+    const offset = existing !== null ? existing.byteOffset : 0;
+    let window;
+    try {
+        // Post-open revalidation (SPEC §9): the port must prove the opened
+        // object still carries the identity the validator approved.
+        window = port.read({ canonicalPath, offset, maxBytes: CODEX_INGESTION_MAX_BATCH_BYTES, expectedIdentity: identity });
+    }
+    catch (error) {
+        if (error instanceof TranscriptReplacedError) {
+            return { status: 'degraded', reason: 'transcript_replaced', nextAction: 'the transcript changed identity after validation (replacement or symlink swap); refusing to read — the next Stop revalidates the current file.', warnings: [] };
+        }
+        const detail = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200);
+        return { status: 'degraded', reason: `transcript_read_failed:${detail}`, nextAction: 'verify the transcript file still exists and is a regular file inside the Codex sessions root.', warnings: [] };
+    }
+    if (offset > window.fileSize) {
+        // The file shrank below the committed cursor: replaced or truncated —
+        // never guess; hold the checkpoint and degrade explicitly.
+        return { status: 'degraded', reason: 'checkpoint_inconsistent', nextAction: 'the transcript is shorter than the committed checkpoint; run the audited recovery/quarantine path once available or re-ingest from a fresh rollout.', warnings: [] };
+    }
+    const byteBoundReached = offset + window.bytes.length < window.fileSize;
+    const decoded = decodeTranscriptWindow({
+        bytes: window.bytes,
+        fileOffset: offset,
+        byteBoundReached,
+        rolloutIdentity,
+        fallbackRootSessionId: existing !== null ? existing.rootSessionId : fallbackRootSessionId,
+        nowIso: now.toISOString(),
+    });
+    // Supported-version guard (SPEC §9): the version signal lives in the
+    // transcript session_meta (or the committed checkpoint after the first
+    // batch). Anything below the verified floor or above the verified ceiling
+    // degrades explicitly — never guess record fields of an unknown contract.
+    const cliVersion = decoded.rolloutMeta.cliVersion ?? existing?.cliVersion ?? null;
+    const version = classifyCodexVersion(cliVersion);
+    if (version.status !== 'supported') {
+        return {
+            status: 'degraded',
+            reason: `${version.reason}:${cliVersion ?? 'unknown'}`,
+            nextAction: CODEX_VERSION_NEXT_ACTION,
+            warnings: decoded.warnings,
+        };
+    }
+    const degradations = [];
+    if (decoded.stop.kind === 'malformed') {
+        degradations.push({ reason: 'transcript_record_malformed', ...(decoded.stop.ordinal !== null ? { ordinal: decoded.stop.ordinal } : {}), nextAction: 'the record is stable-invalid; run the audited quarantine command once available (Slice D). Later records remain as lag.' });
+    }
+    else if (decoded.stop.kind === 'oversized_record') {
+        degradations.push({ reason: 'transcript_record_too_large', nextAction: 'a single transcript record exceeds the bounded-read window; inspect the rollout file.' });
+    }
+    const rootSessionId = decoded.rolloutMeta.rootSessionId ?? existing?.rootSessionId ?? fallbackRootSessionId;
+    const result = ingestGovernanceObservations({
+        workspaceDir,
+        rollout: {
+            hostKind: 'codex',
+            rolloutIdentity,
+            rootSessionId,
+            ...(decoded.rolloutMeta.parentRolloutIdentity !== null ? { parentRolloutIdentity: decoded.rolloutMeta.parentRolloutIdentity } : {}),
+            ...(decoded.rolloutMeta.agentIdentity !== null ? { agentIdentity: decoded.rolloutMeta.agentIdentity } : {}),
+            ...(decoded.rolloutMeta.agentDepth !== null ? { agentDepth: decoded.rolloutMeta.agentDepth } : {}),
+        },
+        observations: decoded.observations,
+        checkpoint: {
+            hostKind: 'codex',
+            rolloutIdentity,
+            byteOffset: decoded.nextByteOffset,
+            lastOrdinal: decoded.lastOrdinal >= 0 ? decoded.lastOrdinal : existing?.lastOrdinal ?? 0,
+            cliVersion: cliVersion ?? undefined,
+            rootSessionId,
+            incompleteTail: decoded.stop.kind === 'incomplete_tail',
+        },
+        ...(degradations.length > 0 ? { degradations } : {}),
+        ...(decoded.compactionTimestamp !== null ? { compactionTimestamp: decoded.compactionTimestamp } : {}),
+        ...(decoded.rollbackTurns.length > 0 ? { rollbackTurns: decoded.rollbackTurns } : {}),
+        now,
+    });
+    const warnings = [...decoded.warnings, ...result.warnings];
+    if (!result.ok) {
+        return { status: 'degraded', reason: result.reason ?? 'governance_write_failed', nextAction: result.nextAction ?? 'inspect the workspace trajectory database.', warnings };
+    }
+    if (decoded.stop.kind === 'incomplete_tail') {
+        warnings.push('transcript_incomplete_tail');
+    }
+    if (decoded.stop.kind === 'malformed') {
+        // The store already committed the records before the malformed line and
+        // held the checkpoint at it; surface the stable failure loudly (SPEC §14.2).
+        return {
+            status: 'degraded',
+            reason: 'transcript_record_malformed',
+            nextAction: 'the record is stable-invalid; run the audited quarantine command once available (Slice D). Later records remain as lag.',
+            warnings,
+        };
+    }
+    if (decoded.stop.kind === 'oversized_record') {
+        return {
+            status: 'degraded',
+            reason: 'transcript_record_too_large',
+            nextAction: 'a single transcript record exceeds the bounded-read window; inspect the rollout file.',
+            warnings,
+        };
+    }
+    return {
+        status: 'ok',
+        inserted: result.inserted,
+        enriched: result.enriched,
+        duplicates: result.duplicates,
+        warnings,
+        lagBytes: Math.max(0, window.fileSize - decoded.nextByteOffset),
+        // Slice B: transcript-only user turns / tool calls that were never seen
+        // live get their admission evaluation here (SPEC §10/§12) — already
+        // admitted logical keys no-op on the marker.
+        admissionCandidates: buildTranscriptCandidates(decoded.observations),
+        rolloutIdentity,
+    };
+}
+export function ingestCodexConversation(rawPayload, kind, options) {
+    const fields = extractFields(rawPayload);
+    if (fields === null || fields.sessionId.length === 0) {
+        return { status: 'degraded', reason: 'transcript_path_invalid', nextAction: 'the hook payload lacks the required Codex identity fields.', warnings: [] };
+    }
+    if (fields.transcriptPath === null) {
+        // SPEC §9: never scan for another file; keep a neutral degraded result.
+        return { status: 'degraded', reason: 'transcript_unavailable', nextAction: 'Codex supplied no transcript for this event; nothing is read or fabricated.', warnings: [] };
+    }
+    const home = resolveCodexHome(options.env);
+    if (!home.ok)
+        return { status: 'degraded', reason: home.reason, nextAction: home.nextAction, warnings: [] };
+    const validated = validateCodexTranscriptPath(fields.transcriptPath, home.home);
+    if (!validated.ok)
+        return { status: 'degraded', reason: validated.reason, nextAction: validated.nextAction, warnings: [] };
+    const now = options.now ?? new Date();
+    if (kind === 'before_prompt_build' || kind === 'after_tool_call') {
+        return ingestLiveObservation({ fields, rolloutIdentity: validated.rolloutIdentity, workspaceDir: options.workspaceDir, now });
+    }
+    return ingestTranscriptDelta({
+        fallbackRootSessionId: fields.sessionId,
+        canonicalPath: validated.canonicalPath,
+        identity: validated.identity,
+        rolloutIdentity: validated.rolloutIdentity,
+        workspaceDir: options.workspaceDir,
+        env: options.env ?? {},
+        now,
+        port: activeTranscriptPort(options),
+    });
+}
+/**
+ * PRI-624 (Slice C): bounded incremental ingest of one known rollout from its
+ * durable checkpoint, driven by an explicit transcript path instead of a live
+ * hook payload. The path is re-authorized through the same
+ * `validateCodexTranscriptPath` containment + post-open identity contract the
+ * hook path uses (SPEC §9) — callers MUST only pass paths resolved from
+ * previously-authenticated rollouts (checkpoints), never discovered sessions.
+ */
+export function ingestCodexTranscriptFromPath(args) {
+    const home = resolveCodexHome(args.env);
+    if (!home.ok)
+        return { status: 'degraded', reason: home.reason, nextAction: home.nextAction, warnings: [] };
+    const validated = validateCodexTranscriptPath(args.transcriptPath, home.home);
+    if (!validated.ok)
+        return { status: 'degraded', reason: validated.reason, nextAction: validated.nextAction, warnings: [] };
+    return ingestTranscriptDelta({
+        fallbackRootSessionId: args.fallbackRootSessionId,
+        canonicalPath: validated.canonicalPath,
+        identity: validated.identity,
+        rolloutIdentity: validated.rolloutIdentity,
+        workspaceDir: args.workspaceDir,
+        env: args.env ?? {},
+        now: args.now ?? new Date(),
+        port: args.port ?? activeTranscriptPort({ workspaceDir: args.workspaceDir }),
+    });
+}

package/codex-adapter/dist/ingestion/transcript-decoder.d.ts

@@ -0,0 +1,72 @@
+import type { GovernanceObservationInput } from '@principles/host-runtime';
+export declare const CODEX_INGESTION_MAX_BATCH_BYTES: number;
+export declare const CODEX_INGESTION_MAX_BATCH_RECORDS = 256;
+export interface TranscriptReadResult {
+    /** Raw bytes read from [offset, offset+maxBytes) — never a decoded string, so multi-byte UTF-8 never corrupts offset math. */
+    readonly bytes: Buffer;
+    readonly fileSize: number;
+}
+/** Identity the validator captured pre-open; the port must re-prove it post-open (SPEC §9 TOCTOU). */
+export interface TranscriptExpectedIdentity {
+    readonly dev: number;
+    readonly ino: number;
+    readonly size: number;
+    readonly mtimeMs: number;
+}
+/** Arguments for one bounded transcript window read. */
+export interface TranscriptReadRequest {
+    readonly canonicalPath: string;
+    readonly offset: number;
+    readonly maxBytes: number;
+    /** Pre-open identity from the validator; the port re-proves it post-open. */
+    readonly expectedIdentity?: TranscriptExpectedIdentity;
+}
+/** Filesystem boundary for the transcript read — injectable so tests can spy. */
+export interface TranscriptPort {
+    read(request: TranscriptReadRequest): TranscriptReadResult;
+}
+/** Thrown by the port when the opened object is not the validated one (replacement/TOCTOU). */
+export declare class TranscriptReplacedError extends Error {
+    constructor();
+}
+export declare function createNodeTranscriptPort(): TranscriptPort;
+export type TranscriptDecodeStop = {
+    kind: 'eof';
+} | {
+    kind: 'incomplete_tail';
+} | {
+    kind: 'malformed';
+    ordinal: number | null;
+} | {
+    kind: 'byte_bound';
+} | {
+    kind: 'oversized_record';
+};
+export interface DecodedDelta {
+    readonly observations: readonly GovernanceObservationInput[];
+    readonly rolloutMeta: {
+        rootSessionId: string | null;
+        cliVersion: string | null;
+        parentRolloutIdentity: string | null;
+        agentIdentity: string | null;
+        agentDepth: number | null;
+    };
+    readonly compactionTimestamp: string | null;
+    readonly rollbackTurns: readonly number[];
+    readonly stop: TranscriptDecodeStop;
+    /** Checkpoint byte offset to commit: start of the first unconsumed byte. */
+    readonly nextByteOffset: number;
+    /** Highest ordinal consumed (for the checkpoint's last_ordinal). */
+    readonly lastOrdinal: number;
+    readonly warnings: readonly string[];
+}
+export interface DecodeTranscriptWindowInput {
+    readonly bytes: Buffer;
+    readonly fileOffset: number;
+    /** True when bytes.length did not reach EOF — the window was cut by the bounded read. */
+    readonly byteBoundReached: boolean;
+    readonly rolloutIdentity: string;
+    readonly fallbackRootSessionId: string | null;
+    readonly nowIso: string;
+}
+export declare function decodeTranscriptWindow(input: DecodeTranscriptWindowInput): DecodedDelta;