@principles/codex-adapter 0.1.0 → 0.1.2

package/dist/codec/input-decoder.d.ts

@@ -3,6 +3,7 @@ export declare const CODEX_EVENT_PRE_TOOL_USE = "PreToolUse";
 export declare const CODEX_EVENT_POST_TOOL_USE = "PostToolUse";
 export declare const CODEX_EVENT_USER_PROMPT_SUBMIT = "UserPromptSubmit";
 export declare const CODEX_EVENT_SESSION_START = "SessionStart";
+export declare const CODEX_EVENT_STOP = "Stop";
 export declare const CODEX_EVENT_SESSION_END = "SessionEnd";
 export declare class CodexDecoderError extends Error {
     readonly reason: string;

package/dist/codec/input-decoder.js

@@ -1,13 +1,22 @@
+import { CODEX_INGESTION_MIN_VERSION } from '../ingestion/codex-version.js';
+// Two contract baselines coexist deliberately (G1 probe report §9): the
+// four pre-ingestion events pin their payload contract to codex-cli 0.147.0,
+// while the Stop / ingestion-side fields follow the ingestion baseline
+// (CODEX_INGESTION_MIN_VERSION = 0.148.0). Each message names the baseline
+// that defines it — never mix them.
+const FOUR_EVENT_CONTRACT_VERSION = '0.147.0';
 export const CODEX_EVENT_PRE_TOOL_USE = 'PreToolUse';
 export const CODEX_EVENT_POST_TOOL_USE = 'PostToolUse';
 export const CODEX_EVENT_USER_PROMPT_SUBMIT = 'UserPromptSubmit';
 export const CODEX_EVENT_SESSION_START = 'SessionStart';
+export const CODEX_EVENT_STOP = 'Stop';
 export const CODEX_EVENT_SESSION_END = 'SessionEnd';
 const EVENT_KINDS = new Map([
     [CODEX_EVENT_PRE_TOOL_USE, 'before_tool_call'],
     [CODEX_EVENT_POST_TOOL_USE, 'after_tool_call'],
     [CODEX_EVENT_USER_PROMPT_SUBMIT, 'before_prompt_build'],
     [CODEX_EVENT_SESSION_START, 'session_start'],
+    [CODEX_EVENT_STOP, 'turn_complete'],
 ]);
 export class CodexDecoderError extends Error {
     reason;
@@ -28,13 +37,13 @@ function own(value, key) {
 function requiredString(value, key) {
     const candidate = own(value, key);
     if (typeof candidate !== 'string' || candidate.trim().length === 0) {
-        throw new CodexDecoderError(`missing or malformed required field "${key}"`, `Use the exact codex-cli 0.147.0 ${key} field.`);
+        throw new CodexDecoderError(`missing or malformed required field "${key}"`, `Use the exact codex-cli ${FOUR_EVENT_CONTRACT_VERSION} ${key} field.`);
     }
     return candidate;
 }
 function requiredNullableString(value, key) {
     if (!Object.hasOwn(value, key))
-        throw new CodexDecoderError(`missing required field "${key}"`, `Use the exact codex-cli 0.147.0 ${key} field.`);
+        throw new CodexDecoderError(`missing required field "${key}"`, `Use the exact codex-cli ${FOUR_EVENT_CONTRACT_VERSION} ${key} field.`);
     const candidate = own(value, key);
     if (candidate !== null && typeof candidate !== 'string') {
         throw new CodexDecoderError(`malformed required field "${key}"`, `${key} must be a string or null.`);
@@ -43,7 +52,7 @@ function requiredNullableString(value, key) {
 }
 function requiredUnknown(value, key) {
     if (!Object.hasOwn(value, key))
-        throw new CodexDecoderError(`missing required field "${key}"`, `Use the exact codex-cli 0.147.0 ${key} field.`);
+        throw new CodexDecoderError(`missing required field "${key}"`, `Use the exact codex-cli ${FOUR_EVENT_CONTRACT_VERSION} ${key} field.`);
     return own(value, key);
 }
 function validateCommon(raw, needsTurn) {
@@ -61,7 +70,7 @@ export function decodeCodexInput(raw) {
     const eventName = requiredString(raw, 'hook_event_name');
     const kind = EVENT_KINDS.get(eventName);
     if (!kind)
-        throw new CodexDecoderError(`unknown hook_event_name "${eventName}"`, 'Configure only PreToolUse, PostToolUse, UserPromptSubmit, or SessionStart.');
+        throw new CodexDecoderError(`unknown hook_event_name "${eventName}"`, 'Configure only PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, or Stop.');
     const common = validateCommon(raw, kind !== 'session_start');
     let context;
     let rawPayload = raw;
@@ -76,6 +85,16 @@ export function decodeCodexInput(raw) {
     else if (kind === 'before_prompt_build') {
         context = { ...common, promptContent: requiredString(raw, 'prompt') };
     }
+    else if (kind === 'turn_complete') {
+        // Stop is the G1-verified turn-complete event (probe report §2). Its
+        // payload carries stop_hook_active (required boolean); PD consumes the
+        // already-flushed transcript, never last_assistant_message directly.
+        const stopHookActive = own(raw, 'stop_hook_active');
+        if (typeof stopHookActive !== 'boolean') {
+            throw new CodexDecoderError('missing or malformed required field "stop_hook_active"', `Use the exact codex-cli ${CODEX_INGESTION_MIN_VERSION} stop_hook_active field.`);
+        }
+        context = { ...common };
+    }
     else {
         context = { ...common, source: requiredString(raw, 'source') };
     }

package/dist/host-adapter.js

@@ -4,7 +4,11 @@ const SUBSCRIBED_EVENTS = [
     'after_tool_call',
     'before_prompt_build',
     'session_start',
-    // 'session_end' deferred to post-MVP
+    // Stop = turn_complete is the G1-verified turn-complete event (probe
+    // report §2); it drives bounded governance-observation ingestion, not a
+    // dispatch route. session_end stays deferred (SPEC §8: never register both
+    // Stop and SessionEnd for turn completion).
+    'turn_complete',
 ];
 export class CodexHooksHostAdapter {
     hostId = 'codex';

package/dist/index.d.ts

@@ -9,3 +9,11 @@ export { CodexHooksHostAdapter } from './host-adapter.js';
 export { processHookInvocation } from './pd-hook.js';
 export type { PdHookResult } from './pd-hook.js';
 export * from './codec/index.js';
+export { resolveCodexHome, canonicalizePath } from './ingestion/codex-home.js';
+export { validateCodexTranscriptPath } from './ingestion/transcript-path.js';
+export type { TranscriptPathValidation, TranscriptFileIdentity } from './ingestion/transcript-path.js';
+export { classifyCodexVersion, CODEX_INGESTION_MIN_VERSION, CODEX_INGESTION_VERIFIED_VERSION } from './ingestion/codex-version.js';
+export { ingestCodexConversation, setCodexTranscriptPortForTest } from './ingestion/ingestion.js';
+export type { CodexIngestionOptions, CodexIngestionOutcome } from './ingestion/ingestion.js';
+export { decodeTranscriptWindow, createNodeTranscriptPort, TranscriptReplacedError, CODEX_INGESTION_MAX_BATCH_BYTES, CODEX_INGESTION_MAX_BATCH_RECORDS } from './ingestion/transcript-decoder.js';
+export type { TranscriptPort, TranscriptExpectedIdentity, DecodedDelta, TranscriptDecodeStop } from './ingestion/transcript-decoder.js';

package/dist/index.js

@@ -8,3 +8,8 @@
 export { CodexHooksHostAdapter } from './host-adapter.js';
 export { processHookInvocation } from './pd-hook.js';
 export * from './codec/index.js';
+export { resolveCodexHome, canonicalizePath } from './ingestion/codex-home.js';
+export { validateCodexTranscriptPath } from './ingestion/transcript-path.js';
+export { classifyCodexVersion, CODEX_INGESTION_MIN_VERSION, CODEX_INGESTION_VERIFIED_VERSION } from './ingestion/codex-version.js';
+export { ingestCodexConversation, setCodexTranscriptPortForTest } from './ingestion/ingestion.js';
+export { decodeTranscriptWindow, createNodeTranscriptPort, TranscriptReplacedError, CODEX_INGESTION_MAX_BATCH_BYTES, CODEX_INGESTION_MAX_BATCH_RECORDS } from './ingestion/transcript-decoder.js';

package/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/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/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/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/dist/ingestion/ingestion.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 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;
+} | {
+    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;

package/dist/ingestion/ingestion.js

@@ -0,0 +1,234 @@
+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';
+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 isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function own(value, key) {
+    return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+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'),
+    };
+}
+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 };
+    return { status: 'ok', inserted: result.inserted, enriched: result.enriched, duplicates: result.duplicates, warnings: result.warnings, lagBytes: 0 };
+}
+function ingestTranscriptDelta({ fields, 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 : fields.sessionId,
+        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 ?? fields.sessionId;
+    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),
+    };
+}
+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({
+        fields,
+        canonicalPath: validated.canonicalPath,
+        identity: validated.identity,
+        rolloutIdentity: validated.rolloutIdentity,
+        workspaceDir: options.workspaceDir,
+        env: options.env ?? {},
+        now,
+        port: activeTranscriptPort(options),
+    });
+}

package/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;

package/dist/ingestion/transcript-decoder.js

@@ -0,0 +1,485 @@
+/**
+ * Codex rollout transcript incremental decoder (Codex Governance Closure
+ * Slice A; SPEC rev 2 §9, G1 probe report §6).
+ *
+ * Decodes a bounded byte window from the durable checkpoint offset and
+ * projects ONLY governance-relevant visible facts (SPEC §12 privacy
+ * boundary): genuine visible user messages (`content_item_kinds[0] ===
+ * "user.text"` — host-injected context arrives as user-role records with
+ * other kinds), visible assistant commentary/final messages, and tool
+ * execution facts anchored on the `event_msg item_completed
+ * CommandExecution` record whose `item.id` IS the hook `tool_use_id` id
+ * space (the G1-verified bridge; the model-level `call_id` is a different
+ * space). Hidden reasoning, system/developer prompts, world_state,
+ * host-injected context, and unknown record bodies are identified by shape
+ * and dropped before persistence — never projected, logged, or emitted.
+ *
+ * Failure classes are distinct (SPEC §14): an incomplete final line (no
+ * trailing newline at EOF) is a transient append/flush boundary — the
+ * checkpoint does not advance past it and the next ingestion retries; a
+ * complete line that fails JSON parsing or envelope validation is a stable
+ * malformed record — decoding stops at it without advancing, with a
+ * structured reason. Unknown-but-well-formed record types are skipped with
+ * a bounded warning and DO advance.
+ */
+import fs from 'node:fs';
+export const CODEX_INGESTION_MAX_BATCH_BYTES = 1024 * 1024;
+export const CODEX_INGESTION_MAX_BATCH_RECORDS = 256;
+/** Thrown by the port when the opened object is not the validated one (replacement/TOCTOU). */
+export class TranscriptReplacedError extends Error {
+    constructor() {
+        super('transcript_replaced_after_validation');
+        this.name = 'TranscriptReplacedError';
+    }
+}
+function identityMatches(opened, expected) {
+    // Size+mtime fingerprint must ALWAYS hold. When the platform reports a
+    // Number-safe inode on both sides, the inode must match too (it is what
+    // catches delete+recreate replacements whose inode got reused on Linux CI
+    // with a same-ms write; a same-size same-ms recreate remains outside the
+    // threat model for an append-only host-owned file). On platforms whose
+    // ino exceeds Number.MAX_SAFE_INTEGER (Windows file IDs), the inode is not
+    // reliably comparable and the fingerprint alone decides. A false refusal
+    // is the safe direction: the hook degrades observably and the next Stop
+    // revalidates and retries.
+    if (opened.size !== expected.size || opened.mtimeMs !== expected.mtimeMs)
+        return false;
+    const comparableIno = expected.ino !== 0 && expected.dev !== 0
+        && opened.ino !== 0 && Number.isSafeInteger(expected.ino) && Number.isSafeInteger(opened.ino);
+    if (comparableIno)
+        return opened.ino === expected.ino && opened.dev === expected.dev;
+    return true;
+}
+export function createNodeTranscriptPort() {
+    return {
+        read({ canonicalPath, offset, maxBytes, expectedIdentity }) {
+            const fd = fs.openSync(canonicalPath, 'r');
+            try {
+                // Post-open revalidation (G1 §7 / SPEC §9): fstat the OPEN OBJECT —
+                // not the path — and re-prove it is the regular file the validator
+                // approved, still at the expected identity. A path swapped between
+                // validation and open (replacement/symlink TOCTOU) is refused before
+                // a single byte is read.
+                const stats = fs.fstatSync(fd);
+                if (!stats.isFile())
+                    throw new Error('transcript_is_not_regular_file');
+                if (expectedIdentity !== undefined && !identityMatches(stats, expectedIdentity)) {
+                    throw new TranscriptReplacedError();
+                }
+                const length = Math.max(0, Math.min(maxBytes, stats.size - offset));
+                if (length === 0)
+                    return { bytes: Buffer.alloc(0), fileSize: stats.size };
+                const buffer = Buffer.alloc(length);
+                const bytesRead = fs.readSync(fd, buffer, 0, length, offset);
+                // Post-read byte bound re-verification (EP-08): never trust the
+                // pre-read stat for the enforced cap.
+                const actual = bytesRead < 0 ? 0 : bytesRead;
+                if (actual > maxBytes)
+                    throw new Error('transcript_read_exceeded_bound');
+                return { bytes: buffer.subarray(0, actual), fileSize: stats.size };
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        },
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function own(value, key) {
+    return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+function metadataTurnId(payload) {
+    const passthrough = own(payload, 'internal_chat_message_metadata_passthrough');
+    if (!isRecord(passthrough))
+        return null;
+    const turnId = own(passthrough, 'turn_id');
+    return typeof turnId === 'string' && turnId.length > 0 ? turnId : null;
+}
+function contentItemKinds(payload) {
+    const passthrough = own(payload, 'internal_chat_message_metadata_passthrough');
+    if (!isRecord(passthrough))
+        return [];
+    const kinds = own(passthrough, 'content_item_kinds');
+    if (!Array.isArray(kinds))
+        return [];
+    return kinds.filter((kind) => typeof kind === 'string');
+}
+function joinContentText(payload, type) {
+    const content = own(payload, 'content');
+    if (!Array.isArray(content))
+        return null;
+    const parts = [];
+    for (const item of content) {
+        if (!isRecord(item))
+            continue;
+        if (own(item, 'type') === type && typeof own(item, 'text') === 'string')
+            parts.push(own(item, 'text'));
+    }
+    return parts.length > 0 ? parts.join('') : null;
+}
+function warnBounded(context, warning) {
+    if (context.warnings.length < 16)
+        context.warnings.push(warning);
+}
+function applySessionMeta(context, payload) {
+    const sessionId = own(payload, 'session_id');
+    if (typeof sessionId === 'string' && sessionId.length > 0 && context.meta.rootSessionId === null) {
+        // Root-session lineage only. For subagent rollouts this value is the
+        // PARENT thread id (G1 §4 collision trap) — rollout identity comes from
+        // the file uuid, never from session_meta.session_id.
+        context.meta.rootSessionId = sessionId;
+    }
+    const cliVersion = own(payload, 'cli_version');
+    if (typeof cliVersion === 'string' && cliVersion.length > 0 && context.meta.cliVersion === null) {
+        context.meta.cliVersion = cliVersion;
+    }
+    const source = own(payload, 'source');
+    const spawn = isRecord(source) ? own(source, 'subagent') : undefined;
+    const threadSpawn = isRecord(spawn) ? own(spawn, 'thread_spawn') : undefined;
+    if (isRecord(threadSpawn)) {
+        const parentThreadId = own(threadSpawn, 'parent_thread_id');
+        if (typeof parentThreadId === 'string' && parentThreadId.length > 0)
+            context.meta.parentRolloutIdentity = parentThreadId;
+        const nickname = own(threadSpawn, 'agent_nickname');
+        const agentPath = own(threadSpawn, 'agent_path');
+        const identity = typeof nickname === 'string' && nickname.length > 0 ? nickname : typeof agentPath === 'string' && agentPath.length > 0 ? agentPath : null;
+        if (identity !== null)
+            context.meta.agentIdentity = identity;
+        const depth = own(threadSpawn, 'depth');
+        if (typeof depth === 'number' && Number.isInteger(depth) && depth >= 0)
+            context.meta.agentDepth = depth;
+    }
+    else {
+        const forkedFrom = own(payload, 'forked_from_id');
+        if (typeof forkedFrom === 'string' && forkedFrom.length > 0 && context.meta.parentRolloutIdentity === null) {
+            context.meta.parentRolloutIdentity = forkedFrom;
+        }
+    }
+}
+function joinItemText(item) {
+    const content = own(item, 'content');
+    if (!Array.isArray(content))
+        return null;
+    const parts = [];
+    for (const entry of content) {
+        if (!isRecord(entry))
+            continue;
+        // UserMessage items use "text", AgentMessage items use "Text".
+        const type = own(entry, 'type');
+        if ((type === 'text' || type === 'Text') && typeof own(entry, 'text') === 'string') {
+            parts.push(own(entry, 'text'));
+        }
+    }
+    return parts.length > 0 ? parts.join('') : null;
+}
+function observationBase(context, turnId) {
+    return {
+        hostKind: 'codex',
+        rolloutIdentity: context.rolloutIdentity,
+        rootSessionId: context.meta.rootSessionId ?? context.fallbackRootSessionId ?? turnId,
+        hostTurnId: turnId,
+    };
+}
+function projectRecord(context, record) {
+    const { type, payload, ordinal, recordByteStart, timestamp } = record;
+    const observedAt = timestamp ?? context.nowIso;
+    if (type === 'session_meta') {
+        applySessionMeta(context, payload);
+        return;
+    }
+    if (type === 'compacted') {
+        // Marker: replacement_history becomes the logical history going forward;
+        // replaced records must not be re-imported as new turns (G1 §6). The
+        // store tombstones prior unpromoted observations at ingest time.
+        context.compactionTimestamp = observedAt;
+        return;
+    }
+    if (type === 'world_state' || type === 'inter_agent_communication_metadata') {
+        // Environment/host snapshots — identified and dropped (privacy boundary).
+        return;
+    }
+    if (type === 'turn_context') {
+        // Per-turn host configuration (sandbox/permissions/model) — known type,
+        // no governance projection, no warning.
+        return;
+    }
+    if (type === 'response_item') {
+        const payloadType = own(payload, 'type');
+        if (payloadType === 'reasoning')
+            return; // hidden/encrypted reasoning — never projected
+        if (payloadType === 'custom_tool_call' || payloadType === 'function_call') {
+            const turnId = metadataTurnId(payload);
+            const callId = own(payload, 'call_id');
+            const name = own(payload, 'name');
+            if (turnId !== null) {
+                const queue = context.modelCallsByTurn.get(turnId) ?? [];
+                queue.push({ callId: typeof callId === 'string' ? callId : null, name: typeof name === 'string' ? name : null });
+                context.modelCallsByTurn.set(turnId, queue);
+            }
+            return;
+        }
+        if (payloadType === 'message' && own(payload, 'role') === 'user') {
+            // 0.150.1 marks genuine visible user input with content_item_kinds[0]
+            // === "user.text"; host-injected context carries other kinds. 0.148.0
+            // does not emit content_item_kinds at all, so this channel is used ONLY
+            // when the discriminator exists — the authoritative cross-version user
+            // channel is the item_completed UserMessage record below.
+            const kinds = contentItemKinds(payload);
+            if (kinds.length === 0 || kinds[0] !== 'user.text')
+                return;
+            const turnId = metadataTurnId(payload);
+            if (turnId === null) {
+                warnBounded(context, `observation_skipped_missing_identity:${ordinal}`);
+                return;
+            }
+            const text = joinContentText(payload, 'input_text');
+            context.observations.push({
+                ...observationBase(context, turnId),
+                kind: 'user_turn',
+                logicalObservationKey: `codex|${context.rolloutIdentity}|${turnId}|user`,
+                transcriptRecordKey: `codex|${context.rolloutIdentity}|${ordinal}`,
+                recordOrdinal: ordinal,
+                recordByteStart,
+                visibleText: text ?? undefined,
+                source: 'transcript',
+                completeness: text !== null ? 'complete' : 'partial',
+                observedAt,
+            });
+            return;
+        }
+        // Assistant/developer response_item messages are not projected here: the
+        // item_completed AgentMessage channel is the cross-version visible
+        // assistant source (0.148.0 lacks content_item_kinds discriminators).
+        return;
+    }
+    if (type === 'event_msg') {
+        const payloadType = own(payload, 'type');
+        if (payloadType === 'item_completed') {
+            const item = own(payload, 'item');
+            if (!isRecord(item))
+                return;
+            const itemType = own(item, 'type');
+            const turnId = own(payload, 'turn_id');
+            if (itemType === 'UserMessage') {
+                // Only genuine visible user turns produce UserMessage completions —
+                // host-injected context never does (both supported versions).
+                if (typeof turnId !== 'string' || turnId.length === 0) {
+                    warnBounded(context, `observation_skipped_missing_identity:${ordinal}`);
+                    return;
+                }
+                const text = joinItemText(item);
+                context.observations.push({
+                    ...observationBase(context, turnId),
+                    kind: 'user_turn',
+                    logicalObservationKey: `codex|${context.rolloutIdentity}|${turnId}|user`,
+                    transcriptRecordKey: `codex|${context.rolloutIdentity}|${ordinal}`,
+                    recordOrdinal: ordinal,
+                    recordByteStart,
+                    visibleText: text ?? undefined,
+                    source: 'transcript',
+                    completeness: text !== null ? 'complete' : 'partial',
+                    observedAt,
+                });
+                return;
+            }
+            if (itemType === 'AgentMessage') {
+                if (typeof turnId !== 'string' || turnId.length === 0) {
+                    warnBounded(context, `observation_skipped_missing_identity:${ordinal}`);
+                    return;
+                }
+                const itemId = own(item, 'id');
+                if (typeof itemId !== 'string' || itemId.length === 0) {
+                    warnBounded(context, `observation_skipped_missing_identity:${ordinal}`);
+                    return;
+                }
+                const text = joinItemText(item);
+                // AgentMessage phase sits on the item (fixture-verified; keep the
+                // payload sibling as a tolerated alternative).
+                const phase = own(item, 'phase') ?? own(payload, 'phase');
+                context.observations.push({
+                    ...observationBase(context, turnId),
+                    kind: 'assistant_turn',
+                    logicalObservationKey: `codex|${context.rolloutIdentity}|${turnId}|${itemId}`,
+                    transcriptRecordKey: `codex|${context.rolloutIdentity}|${ordinal}`,
+                    recordOrdinal: ordinal,
+                    recordByteStart,
+                    assistantItemId: itemId,
+                    phase: typeof phase === 'string' ? phase : undefined,
+                    visibleText: text ?? undefined,
+                    source: 'transcript',
+                    completeness: text !== null ? 'complete' : 'partial',
+                    observedAt,
+                });
+                return;
+            }
+            if (itemType === 'CommandExecution') {
+                const toolUseId = own(item, 'id');
+                if (typeof toolUseId !== 'string' || toolUseId.length === 0 || typeof turnId !== 'string' || turnId.length === 0) {
+                    warnBounded(context, `observation_skipped_missing_identity:${ordinal}`);
+                    return;
+                }
+                // FIFO-pair with the model-level call in the same turn for the tool
+                // name / call_id enrichment (execution order; G1 bridge fixture).
+                const queue = context.modelCallsByTurn.get(turnId);
+                const paired = queue !== undefined && queue.length > 0 ? queue.shift() : undefined;
+                if (queue !== undefined && queue.length === 0)
+                    context.modelCallsByTurn.delete(turnId);
+                const exitCode = own(item, 'exit_code');
+                const command = own(item, 'command');
+                const stdout = own(item, 'stdout');
+                const stderr = own(item, 'stderr');
+                context.observations.push({
+                    ...observationBase(context, turnId),
+                    kind: 'tool_call',
+                    logicalObservationKey: `codex|${context.rolloutIdentity}|${toolUseId}`,
+                    transcriptRecordKey: `codex|${context.rolloutIdentity}|${ordinal}`,
+                    recordOrdinal: ordinal,
+                    recordByteStart,
+                    toolUseId,
+                    transcriptToolCallId: paired?.callId ?? undefined,
+                    toolFacts: {
+                        toolName: paired?.name ?? null,
+                        exitCode: typeof exitCode === 'number' ? exitCode : null,
+                        command: Array.isArray(command) ? command.filter((part) => typeof part === 'string').slice(0, 8) : null,
+                        stdout: typeof stdout === 'string' ? stdout : null,
+                        stderr: typeof stderr === 'string' ? stderr : null,
+                    },
+                    source: 'transcript',
+                    completeness: 'complete',
+                    observedAt,
+                });
+                return;
+            }
+            return;
+        }
+        if (payloadType === 'thread_rolled_back') {
+            // Documented rule (G1 runtime contract, thread_rollout_truncation.rs):
+            // rollback appends a marker carrying num_turns; physical records remain
+            // while effective logical history is truncated.
+            const numTurns = own(payload, 'num_turns');
+            if (typeof numTurns === 'number' && Number.isInteger(numTurns) && numTurns > 0) {
+                context.rollbackTurns.push(numTurns);
+            }
+            return;
+        }
+        // task_started / turn_context / token_count / task_complete /
+        // thread_settings_applied: known turn bookkeeping — no projection.
+        return;
+    }
+    warnBounded(context, `unknown_record_type_skipped:${type}`);
+}
+function decodeLine(lineBytes) {
+    const text = lineBytes.toString('utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { record: null, type: null, ordinal: null, timestamp: null, payload: null };
+    }
+    if (!isRecord(parsed))
+        return { record: null, type: null, ordinal: null, timestamp: null, payload: null };
+    const type = own(parsed, 'type');
+    const ordinal = own(parsed, 'ordinal');
+    const timestamp = own(parsed, 'timestamp');
+    const payload = own(parsed, 'payload');
+    const validEnvelope = typeof type === 'string' && type.length > 0
+        && typeof ordinal === 'number' && Number.isInteger(ordinal)
+        && (payload === undefined || isRecord(payload));
+    if (!validEnvelope) {
+        return { record: parsed, type: null, ordinal: typeof ordinal === 'number' && Number.isInteger(ordinal) ? ordinal : null, timestamp: null, payload: null };
+    }
+    return {
+        record: parsed,
+        type,
+        ordinal,
+        timestamp: typeof timestamp === 'string' ? timestamp : null,
+        payload: payload === undefined ? {} : payload,
+    };
+}
+function finish(context, nextByteOffset, lastOrdinal) {
+    return {
+        observations: context.observations,
+        rolloutMeta: context.meta,
+        compactionTimestamp: context.compactionTimestamp,
+        rollbackTurns: context.rollbackTurns,
+        nextByteOffset,
+        lastOrdinal,
+        warnings: context.warnings,
+    };
+}
+export function decodeTranscriptWindow(input) {
+    const context = {
+        rolloutIdentity: input.rolloutIdentity,
+        fallbackRootSessionId: input.fallbackRootSessionId,
+        nowIso: input.nowIso,
+        observations: [],
+        meta: { rootSessionId: null, cliVersion: null, parentRolloutIdentity: null, agentIdentity: null, agentDepth: null },
+        modelCallsByTurn: new Map(),
+        compactionTimestamp: null,
+        rollbackTurns: [],
+        warnings: [],
+    };
+    const { bytes } = input;
+    if (bytes.length === 0) {
+        return { ...finish(context, input.fileOffset, -1), stop: { kind: 'eof' } };
+    }
+    // UTF-8 multi-byte sequences never contain 0x0A, so splitting the byte
+    // window at newline bytes is safe and keeps the checkpoint byte-exact.
+    const lastNewline = bytes.lastIndexOf(0x0a);
+    const completeEnd = lastNewline + 1; // exclusive byte end of the newline-terminated region
+    const tailBytes = bytes.subarray(completeEnd); // bytes after the final newline (no terminator)
+    let cursor = input.fileOffset;
+    let lastOrdinal = -1;
+    let recordsConsumed = 0;
+    let lineStart = 0;
+    while (lineStart < completeEnd) {
+        const lineEnd = bytes.indexOf(0x0a, lineStart);
+        if (lineEnd === -1 || lineEnd >= completeEnd)
+            break;
+        const lineBytes = bytes.subarray(lineStart, lineEnd);
+        const recordByteStart = cursor;
+        cursor = input.fileOffset + lineEnd + 1;
+        lineStart = lineEnd + 1;
+        if (lineBytes.length === 0 || lineBytes.toString('utf8').trim().length === 0)
+            continue;
+        if (recordsConsumed >= CODEX_INGESTION_MAX_BATCH_RECORDS) {
+            return { ...finish(context, recordByteStart, lastOrdinal), stop: { kind: 'byte_bound' } };
+        }
+        const line = decodeLine(lineBytes);
+        if (line.record === null || line.type === null) {
+            // A newline-terminated line that does not parse (or fails the record
+            // envelope) is a stable malformed record: stop here without advancing
+            // past it (SPEC §14.2).
+            return { ...finish(context, recordByteStart, lastOrdinal), stop: { kind: 'malformed', ordinal: line.ordinal } };
+        }
+        recordsConsumed += 1;
+        lastOrdinal = line.ordinal;
+        projectRecord(context, { type: line.type, payload: line.payload ?? {}, ordinal: line.ordinal, recordByteStart, timestamp: line.timestamp });
+    }
+    if (tailBytes.length > 0) {
+        const tailStart = cursor; // byte offset where the unterminated tail begins
+        if (input.byteBoundReached) {
+            // The window ended mid-line because of the byte bound — the line is not
+            // known-incomplete; leave it wholly unread and report bounded lag.
+            if (lastNewline === -1) {
+                return { ...finish(context, input.fileOffset, lastOrdinal), stop: { kind: 'oversized_record' } };
+            }
+            return { ...finish(context, tailStart, lastOrdinal), stop: { kind: 'byte_bound' } };
+        }
+        const line = decodeLine(tailBytes);
+        if (line.record !== null && line.type !== null) {
+            // A parseable final line without a trailing newline is a complete
+            // record; consume it and advance the checkpoint to EOF.
+            lastOrdinal = line.ordinal;
+            projectRecord(context, { type: line.type, payload: line.payload ?? {}, ordinal: line.ordinal, recordByteStart: tailStart, timestamp: line.timestamp });
+            return { ...finish(context, tailStart + tailBytes.length, lastOrdinal), stop: { kind: 'eof' } };
+        }
+        // Incomplete final line: transient append/flush boundary — do not
+        // advance past the previous record; the next ingestion retries (SPEC §14.1).
+        return { ...finish(context, tailStart, lastOrdinal), stop: { kind: 'incomplete_tail' } };
+    }
+    return { ...finish(context, cursor, lastOrdinal), stop: input.byteBoundReached ? { kind: 'byte_bound' } : { kind: 'eof' } };
+}

package/dist/ingestion/transcript-path.d.ts

@@ -0,0 +1,23 @@
+/**
+ * File identity captured at validation time. The open/read seam re-proves
+ * the opened object still has this identity BEFORE any byte is read — the
+ * G1 §7 / SPEC §9 post-open revalidation that closes the validate→open
+ * TOCTOU window (path replacement, symlink swap).
+ */
+export interface TranscriptFileIdentity {
+    readonly dev: number;
+    readonly ino: number;
+    readonly size: number;
+    readonly mtimeMs: number;
+}
+export type TranscriptPathValidation = {
+    ok: true;
+    canonicalPath: string;
+    rolloutIdentity: string;
+    identity: TranscriptFileIdentity;
+} | {
+    ok: false;
+    reason: 'transcript_path_invalid' | 'transcript_path_outside_codex_home';
+    nextAction: string;
+};
+export declare function validateCodexTranscriptPath(transcriptPath: string, codexHome: string): TranscriptPathValidation;

package/dist/ingestion/transcript-path.js

@@ -0,0 +1,87 @@
+/**
+ * Codex transcript path authorization (Codex Governance Closure SPEC rev 2
+ * §9; Slice A SPEC §11).
+ *
+ * The ONLY valid transcript source is the path explicitly supplied by the
+ * authenticated Codex hook — never a scan of `$CODEX_HOME/sessions`, never a
+ * "latest session" guess. Validation covers the real repository/OS path
+ * model: absolute path, `..` traversal rejection, canonical (realpath)
+ * normalization, containment under the resolved Codex home's `sessions`
+ * root at segment boundaries, symlink/junction escape rejection (realpath
+ * collapses them; containment is checked on the canonical form), and a
+ * regular-file requirement. The rollout identity — one physical transcript,
+ * distinct from the root session id (G1 §4 subagent/fork traps) — is the
+ * uuid embedded in the Codex rollout file name.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonicalizePath } from './codex-home.js';
+const UUID_HEX = /^[0-9a-fA-F]+$/;
+function isHex(value) {
+    return UUID_HEX.test(value);
+}
+/** rollout-<timestamp>-<uuid>.jsonl — returns the rollout uuid, or null when the name is off-contract. */
+function parseRolloutFileName(fileName) {
+    if (!fileName.startsWith('rollout-') || !fileName.endsWith('.jsonl'))
+        return null;
+    const stem = fileName.slice('rollout-'.length, -'.jsonl'.length);
+    const parts = stem.split('-');
+    if (parts.length < 6)
+        return null; // at least one timestamp segment + the five uuid groups
+    const [a, b, c, d, e] = parts.slice(-5);
+    if (a === undefined || b === undefined || c === undefined || d === undefined || e === undefined)
+        return null;
+    if (a.length !== 8 || b.length !== 4 || c.length !== 4 || d.length !== 4 || e.length !== 12)
+        return null;
+    if (!isHex(a) || !isHex(b) || !isHex(c) || !isHex(d) || !isHex(e))
+        return null;
+    return parts.slice(-5).join('-').toLowerCase();
+}
+function isAbsolutePath(value) {
+    return path.isAbsolute(value);
+}
+function hasParentTraversal(value) {
+    return value.split(/[\\/]+/).includes('..');
+}
+function isContained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative.length > 0 && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+export function validateCodexTranscriptPath(transcriptPath, codexHome) {
+    if (!isAbsolutePath(transcriptPath) || hasParentTraversal(transcriptPath)) {
+        return { ok: false, reason: 'transcript_path_invalid', nextAction: 'Codex must supply an absolute transcript_path without traversal segments.' };
+    }
+    const fileName = path.basename(transcriptPath);
+    const rolloutIdentity = parseRolloutFileName(fileName);
+    if (rolloutIdentity === null) {
+        return { ok: false, reason: 'transcript_path_invalid', nextAction: 'the transcript file name does not match the Codex rollout contract (rollout-<timestamp>-<uuid>.jsonl).' };
+    }
+    let canonicalHome;
+    let canonicalPath;
+    try {
+        // Canonicalize both sides to the final long form: Node's JS realpath
+        // preserves 8.3 short-name segments while payloads carry long forms.
+        canonicalHome = canonicalizePath(codexHome);
+        canonicalPath = canonicalizePath(transcriptPath);
+    }
+    catch {
+        return { ok: false, reason: 'transcript_path_invalid', nextAction: 'the transcript path (or the Codex home) does not resolve to an existing location.' };
+    }
+    // realpath collapses symlinks/junctions; checking containment on the
+    // canonical form rejects escapes that traverse links out of the sessions root.
+    if (!isContained(path.join(canonicalHome, 'sessions'), canonicalPath)) {
+        return { ok: false, reason: 'transcript_path_outside_codex_home', nextAction: 'the transcript is not inside the resolved CODEX_HOME sessions root; refusing to read outside the authenticated Codex home.' };
+    }
+    let stats;
+    try {
+        stats = fs.statSync(canonicalPath);
+    }
+    catch {
+        return { ok: false, reason: 'transcript_path_invalid', nextAction: 'the transcript file disappeared during validation.' };
+    }
+    if (!stats.isFile()) {
+        return { ok: false, reason: 'transcript_path_invalid', nextAction: 'the transcript path is not a regular file.' };
+    }
+    const identity = { dev: stats.dev, ino: Number(stats.ino), size: stats.size, mtimeMs: stats.mtimeMs };
+    return { ok: true, canonicalPath, rolloutIdentity: rolloutIdentity.toLowerCase(), identity };
+}

package/dist/pd-hook.js

@@ -6,6 +6,7 @@ import { createProductionHostRuntime, loadPdConfigForPlugin, resolveNearestPdWor
 import { computeFeatureFlagsFromConfig } from '@principles/core/runtime-v2';
 import { CodexHooksHostAdapter } from './host-adapter.js';
 import { CodexDecoderError, CodexEncoderError } from './codec/index.js';
+import { ingestCodexConversation } from './ingestion/ingestion.js';
 const MAX_DIAGNOSTIC = 500;
 function diagnostic(reason, nextAction) {
     const boundedReason = reason.replace(/\s+/g, ' ').trim().slice(0, MAX_DIAGNOSTIC);
@@ -15,6 +16,32 @@ function diagnostic(reason, nextAction) {
 function errorMessage(error) {
     return error instanceof Error ? error.message.slice(0, MAX_DIAGNOSTIC) : 'unknown_error';
 }
+// Bounded governance-observation ingestion (Codex Governance Closure Slice
+// A). Runs only when BOTH host.codex and codex_conversation_ingestion are
+// enabled — the flag gate below happens BEFORE any transcript path
+// validation or filesystem I/O, so flag-off means the transcript boundary
+// receives zero calls (SPEC §10 hard privacy invariant).
+function runConversationIngestion(args) {
+    const { rawPayload, kind, workspaceDir, env } = args;
+    if (kind !== 'turn_complete' && kind !== 'before_prompt_build' && kind !== 'after_tool_call')
+        return [];
+    const diagnostics = [];
+    try {
+        const outcome = ingestCodexConversation(rawPayload, kind, { workspaceDir, env });
+        if (outcome.status === 'degraded') {
+            diagnostics.push(diagnostic(outcome.reason, outcome.nextAction));
+        }
+        else {
+            for (const warning of outcome.warnings.slice(0, 2)) {
+                diagnostics.push(diagnostic(warning, 'Inspect PD Workspace governance-observation state; ingestion continued.'));
+            }
+        }
+    }
+    catch (error) {
+        diagnostics.push(diagnostic(`codex_ingestion_unexpected:${errorMessage(error)}`, 'Retry the next Codex turn; if it repeats, inspect PD stderr and the Workspace trajectory database.'));
+    }
+    return diagnostics;
+}
 export async function processHookInvocation(rawStdin, _env = process.env, cwd = process.cwd()) {
     let parsed;
     try {
@@ -50,6 +77,20 @@ export async function processHookInvocation(rawStdin, _env = process.env, cwd =
     if (flags['host.codex']?.enabled !== true) {
         return { stdout: {}, exitCode: 0, stderr: [diagnostic('host.codex_disabled', 'Set features.host.codex.enabled=true in the selected Workspace to enable PD.')] };
     }
+    const ingestionEnabled = flags.codex_conversation_ingestion?.enabled === true;
+    if (event.kind === 'turn_complete') {
+        // Stop is the turn-complete ingestion trigger (G1 §2): no dispatch route,
+        // and Codex's Stop output schema has no hookSpecificOutput — the neutral
+        // result is exactly `{}` on stdout (runtime contract: "PD emits empty
+        // stdout on Stop"). Flag-off preserves the zero-transcript-read invariant
+        // and emits ONE bounded structured feature_disabled fact per completed
+        // turn on stderr — never stdout, and never on the per-tool events (that
+        // would be per-event noise).
+        const stderr = ingestionEnabled
+            ? runConversationIngestion({ rawPayload: parsed, kind: event.kind, workspaceDir: resolution.workspaceDir, env: _env })
+            : [diagnostic('feature_disabled', 'Set features.codex_conversation_ingestion.enabled=true in the selected Workspace .pd/config.yaml to enable bounded conversation ingestion.')];
+        return { stdout: {}, exitCode: 0, stderr };
+    }
     try {
         if (event.kind === 'session_start') {
             const health = await createProductionHostRuntime().health(resolution.workspaceDir);
@@ -57,8 +98,11 @@ export async function processHookInvocation(rawStdin, _env = process.env, cwd =
                 return { stdout: {}, exitCode: 0, stderr: [diagnostic(health.reason ?? 'runtime_unhealthy', health.nextAction ?? 'Inspect the Workspace runtime.')] };
             return { stdout: adapter.encodeOutput({ decision: 'allow', source: event.source }, 'session_start'), exitCode: 0, stderr: [] };
         }
+        const ingestionDiagnostics = ingestionEnabled
+            ? runConversationIngestion({ rawPayload: parsed, kind: event.kind, workspaceDir: resolution.workspaceDir, env: _env })
+            : [];
         const result = await createProductionHostRuntime().dispatch(event);
-        const stderr = (result.warnings ?? []).slice(0, 16).map((warning) => diagnostic(warning, 'Inspect PD Workspace state and retry; the hook failed open.'));
+        const stderr = [...(result.warnings ?? []).slice(0, 16).map((warning) => diagnostic(warning, 'Inspect PD Workspace state and retry; the hook failed open.')), ...ingestionDiagnostics];
         return { stdout: adapter.encodeOutput(result, event.kind), exitCode: 0, stderr };
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/codex-adapter",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Codex CLI host adapter for Principles Disciple — implements HostAdapter interface for OpenAI Codex CLI's stdin/stdout JSON hook model (ADR-0020).",
   "type": "module",
   "main": "./dist/index.js",