alp-code 0.9.0

package/dist/src/cli/mode-selector.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModeSelector = void 0;
+const node_stream_1 = require("node:stream");
+const node_readline_1 = require("node:readline");
+const modes_1 = require("../agents/modes");
+const mode_preference_store_1 = require("./mode-preference-store");
+/**
+ * Menu chọn **nấc**, không phải chọn runtime.
+ *
+ * Từ khi mỗi vai ở mỗi nấc chỉ có một model, model quyết định CLI — nên câu hỏi lúc mở phiên
+ * không còn là "chạy Claude hay Codex" mà là "việc này khó cỡ nào". Menu vẫn giữ nguyên
+ * khuôn cũ: nhớ lựa chọn lần trước, hỏi một lần trên TTY, Ctrl+C là huỷ chứ không phải chọn
+ * bừa.
+ */
+const MODES = modes_1.MODE_IDS;
+function normalizeKeypress(sequence, key = {}) {
+    if (key.ctrl && key.name === "c")
+        return "cancel";
+    if (key.name === "up")
+        return "up";
+    if (key.name === "down")
+        return "down";
+    if (key.name === "return" ||
+        key.name === "enter" ||
+        sequence === "\r" ||
+        sequence === "\n") {
+        return "enter";
+    }
+    return "other";
+}
+function createKeypressReader(input) {
+    const decoder = new node_stream_1.PassThrough();
+    const queued = [];
+    const waiting = [];
+    let terminalError = null;
+    const onKeypress = (sequence, key) => {
+        const value = normalizeKeypress(sequence, key);
+        const waiter = waiting.shift();
+        if (waiter)
+            waiter.resolve(value);
+        else
+            queued.push(value);
+    };
+    const onError = (error) => {
+        terminalError = error;
+        for (const waiter of waiting.splice(0))
+            waiter.reject(error);
+    };
+    const onData = (chunk) => {
+        decoder.write(chunk);
+    };
+    (0, node_readline_1.emitKeypressEvents)(decoder);
+    decoder.on("keypress", onKeypress);
+    input.on("data", onData);
+    input.on("error", onError);
+    return {
+        read() {
+            const queuedKey = queued.shift();
+            if (queuedKey !== undefined)
+                return Promise.resolve(queuedKey);
+            if (terminalError !== null)
+                return Promise.reject(terminalError);
+            return new Promise((resolve, reject) => {
+                waiting.push({ resolve, reject });
+            });
+        },
+        close() {
+            input.removeListener("data", onData);
+            input.removeListener("error", onError);
+            decoder.removeListener("keypress", onKeypress);
+            decoder.destroy();
+        },
+    };
+}
+function renderMenu(output, current, selectedIndex, redraw) {
+    if (redraw)
+        output.write(`\u001b[${MODES.length + 1}A`);
+    for (const [index, mode] of MODES.entries()) {
+        const pointer = index === selectedIndex ? "❯" : " ";
+        const persisted = mode === current ? " (current)" : "";
+        output.write(`\r\u001b[2K  ${pointer} ${mode.padEnd(6)}${persisted} — ${modes_1.MODE_PROFILES[mode].summary}\n`);
+    }
+    output.write("\r\u001b[2K↑/↓ select · Enter confirm · Ctrl+C cancel\n");
+}
+class ModeSelector {
+    preferenceStore;
+    input;
+    output;
+    injectedReadKey;
+    constructor(options = {}) {
+        this.preferenceStore = options.preferenceStore ?? new mode_preference_store_1.FileModePreferenceStore();
+        this.input = options.input ?? process.stdin;
+        this.output = options.output ?? process.stdout;
+        this.injectedReadKey = options.readKey;
+    }
+    async select(input) {
+        if (input.requestedMode !== undefined) {
+            if (!MODES.includes(input.requestedMode)) {
+                throw new Error(`invalid mode \`${String(input.requestedMode)}\``);
+            }
+            return { ok: true, mode: input.requestedMode, source: "explicit" };
+        }
+        const preference = await this.preferenceStore.read();
+        if (preference.warning) {
+            this.output.write(`WARNING  ${preference.warning}\n`);
+        }
+        const current = preference.mode ?? modes_1.DEFAULT_MODE;
+        if (!input.interactive) {
+            return {
+                ok: true,
+                mode: current,
+                source: preference.mode === null ? "default" : "persisted",
+            };
+        }
+        const selected = await this.prompt(current);
+        if (selected === null)
+            return { ok: false, exitCode: 130 };
+        await this.preferenceStore.write(selected);
+        return { ok: true, mode: selected, source: "interactive" };
+    }
+    async prompt(current) {
+        if (!this.injectedReadKey && !this.input) {
+            throw new Error("interactive mode selection requires terminal input");
+        }
+        const wasFlowing = this.input?.readableFlowing === true;
+        const wasRaw = Boolean(this.input?.isRaw);
+        const keypress = this.injectedReadKey || !this.input
+            ? null
+            : createKeypressReader(this.input);
+        const readKey = this.injectedReadKey ?? keypress.read;
+        let changedRawMode = false;
+        let selectedIndex = Math.max(0, MODES.indexOf(current));
+        this.output.write("\nSelect mode for this ALP session:\n");
+        this.output.write("\u001b[?25l");
+        try {
+            if (keypress &&
+                !wasRaw &&
+                typeof this.input?.setRawMode === "function") {
+                this.input.setRawMode(true);
+                changedRawMode = true;
+            }
+            if (keypress && typeof this.input?.resume === "function") {
+                this.input.resume();
+            }
+            renderMenu(this.output, current, selectedIndex, false);
+            for (;;) {
+                const key = await readKey();
+                if (key === "up") {
+                    selectedIndex = (selectedIndex - 1 + MODES.length) % MODES.length;
+                    renderMenu(this.output, current, selectedIndex, true);
+                }
+                else if (key === "down") {
+                    selectedIndex = (selectedIndex + 1) % MODES.length;
+                    renderMenu(this.output, current, selectedIndex, true);
+                }
+                else if (key === "enter") {
+                    return MODES[selectedIndex];
+                }
+                else if (key === "cancel") {
+                    return null;
+                }
+            }
+        }
+        finally {
+            keypress?.close();
+            if (keypress &&
+                !wasFlowing &&
+                typeof this.input?.pause === "function") {
+                this.input.pause();
+            }
+            if (changedRawMode)
+                this.input?.setRawMode?.(false);
+            this.output.write("\u001b[?25h");
+        }
+    }
+}
+exports.ModeSelector = ModeSelector;

package/dist/src/cli/update-check.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileUpdateCheckStore = void 0;
+exports.spawnBackgroundUpdateCheck = spawnBackgroundUpdateCheck;
+exports.checkForUpdate = checkForUpdate;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+const promises_1 = require("node:fs/promises");
+const state_paths_1 = require("../state-paths");
+const TTL_MS = 24 * 60 * 60 * 1000;
+class FileUpdateCheckStore {
+    file;
+    constructor(options = {}) {
+        this.file = options.file ?? (0, node_path_1.join)((0, state_paths_1.stateHome)(), "update-check.json");
+    }
+    async read() {
+        try {
+            const parsed = JSON.parse(await (0, promises_1.readFile)(this.file, "utf8"));
+            return typeof parsed?.checkedAt === "number"
+                ? { checkedAt: parsed.checkedAt, latestTag: typeof parsed.latestTag === "string" ? parsed.latestTag : null }
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async write(cache) {
+        const dir = (0, node_path_1.dirname)(this.file);
+        await (0, promises_1.mkdir)(dir, { recursive: true, mode: 0o700 });
+        const tmp = (0, node_path_1.join)(dir, `.${(0, node_crypto_1.randomUUID)()}.update-check.tmp`);
+        try {
+            await (0, promises_1.writeFile)(tmp, `${JSON.stringify(cache)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            await (0, promises_1.rename)(tmp, this.file);
+        }
+        catch (error) {
+            await (0, promises_1.rm)(tmp, { force: true });
+            throw error;
+        }
+    }
+}
+exports.FileUpdateCheckStore = FileUpdateCheckStore;
+function spawnBackgroundUpdateCheck(repoRoot) {
+    try {
+        const child = (0, node_child_process_1.spawn)(process.execPath, [(0, node_path_1.join)(repoRoot, "scripts", "lib", "update-check-worker.cjs")], {
+            cwd: repoRoot,
+            detached: true,
+            stdio: "ignore",
+            env: process.env,
+        });
+        child.unref();
+    }
+    catch {
+        /* best-effort; never affect the current command */
+    }
+}
+function isNewer(repoRoot, latestTag, currentVersion) {
+    const semver = (0, node_module_1.createRequire)(__filename)((0, node_path_1.join)(repoRoot, "scripts", "lib", "semver-lite.cjs"));
+    try {
+        return semver.compare(latestTag, currentVersion) > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function checkForUpdate(input) {
+    const now = input.now ?? Date.now();
+    const cached = await input.store.read();
+    if (!cached || now - cached.checkedAt >= TTL_MS)
+        (input.triggerBackgroundRefresh ?? spawnBackgroundUpdateCheck)(input.repoRoot);
+    if (!cached?.latestTag)
+        return null;
+    if (!isNewer(input.repoRoot, cached.latestTag, input.currentVersion))
+        return null;
+    return `UPDATE    phiên bản mới ${cached.latestTag} hiện có (đang dùng v${input.currentVersion}) — chạy \`alp update\`\n`;
+}

package/dist/src/context/checkpoint.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHECKPOINT_MAX_BYTES = exports.PIN_MAX_BYTES = void 0;
+exports.checkpointDigest = checkpointDigest;
+exports.seedCheckpoint = seedCheckpoint;
+exports.readCheckpoint = readCheckpoint;
+exports.writeCheckpoint = writeCheckpoint;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const zod_1 = require("zod");
+const adapter_files_1 = require("../runtime/adapter-files");
+/** §6 Size limits — one pin, and the checkpoint as a whole, in UTF-8 bytes. */
+exports.PIN_MAX_BYTES = 4 * 1024;
+exports.CHECKPOINT_MAX_BYTES = 128 * 1024;
+const EXECUTION_ID_PATTERN = /^exec_[a-zA-Z0-9_-]+$/;
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+const continuityPinSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    text: zod_1.z.string().min(1).refine((value) => byteLength(value) <= exports.PIN_MAX_BYTES, {
+        message: `pin text exceeds ${exports.PIN_MAX_BYTES} bytes`,
+    }),
+    source: zod_1.z.enum(["execution", "principal", "agent"]),
+    createdAt: zod_1.z.string().min(1),
+});
+const checkpointSchema = zod_1.z.object({
+    version: zod_1.z.literal(1),
+    executionId: zod_1.z.string().regex(EXECUTION_ID_PATTERN, "invalid execution ID"),
+    policyHash: zod_1.z.string().min(1),
+    runtime: zod_1.z.enum(["claude", "codex"]).nullable(),
+    createdAt: zod_1.z.string().min(1),
+    updatedAt: zod_1.z.string().min(1),
+    objective: zod_1.z.string().nullable(),
+    decisions: zod_1.z.array(continuityPinSchema),
+    constraints: zod_1.z.array(continuityPinSchema),
+    openItems: zod_1.z.array(continuityPinSchema),
+    nextActions: zod_1.z.array(continuityPinSchema),
+    integrity: zod_1.z.object({ checkpointSha256: zod_1.z.string().length(64) }),
+}).superRefine((value, ctx) => {
+    if (byteLength(JSON.stringify(value)) > exports.CHECKPOINT_MAX_BYTES) {
+        ctx.addIssue({ code: "custom", message: `checkpoint exceeds ${exports.CHECKPOINT_MAX_BYTES} bytes` });
+    }
+});
+/**
+ * Sort object keys recursively so two checkpoints with the same logical content hash the
+ * same regardless of the key order they happen to be written or read in. Arrays keep their
+ * order — pins are a sequence, not a set.
+ */
+function sortForDigest(value) {
+    if (Array.isArray(value))
+        return value.map(sortForDigest);
+    if (value !== null && typeof value === "object") {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = sortForDigest(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/** SHA-256 over the checkpoint's canonical JSON, excluding `integrity` itself. */
+function checkpointDigest(checkpoint) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(sortForDigest(checkpoint))).digest("hex");
+}
+/** The checkpoint an execution starts with: no pins, objective seeded from the task. */
+function seedCheckpoint(input) {
+    const timestamp = (input.now ?? (() => new Date().toISOString()))();
+    const body = {
+        version: 1,
+        executionId: input.executionId,
+        policyHash: input.policyHash,
+        runtime: null,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        objective: input.objective,
+        decisions: [],
+        constraints: [],
+        openItems: [],
+        nextActions: [],
+    };
+    return { ...body, integrity: { checkpointSha256: checkpointDigest(body) } };
+}
+/**
+ * Fail closed (invariant 6): a checkpoint that doesn't parse, doesn't hash, or is bound to a
+ * different execution or policy is never returned as usable — the caller gets a reason
+ * instead, and decides on its own whether that means "inject nothing" or "abort".
+ */
+async function readCheckpoint(path, binding) {
+    let raw;
+    try {
+        raw = await (0, promises_1.readFile)(path, "utf8");
+    }
+    catch (error) {
+        return { ok: false, reason: `cannot read checkpoint: ${error.message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: "checkpoint is not valid JSON" };
+    }
+    const result = checkpointSchema.safeParse(parsed);
+    if (!result.success) {
+        return { ok: false, reason: `checkpoint failed schema validation: ${result.error.issues[0]?.message ?? "invalid"}` };
+    }
+    const value = result.data;
+    const { integrity, ...rest } = value;
+    if (checkpointDigest(rest) !== integrity.checkpointSha256) {
+        return { ok: false, reason: "checkpoint digest mismatch" };
+    }
+    if (value.executionId !== binding.executionId || value.policyHash !== binding.policyHash) {
+        return { ok: false, reason: "checkpoint policy binding mismatch" };
+    }
+    return { ok: true, value };
+}
+/**
+ * Validates before touching the filesystem at all, so a rejected write (oversize pin,
+ * oversize checkpoint) never runs `atomicRuntimeFile` — the file on disk, if any, is left
+ * exactly as it was. A write that does reach `atomicRuntimeFile` is itself temp-file-then-
+ * rename, so a process killed mid-write leaves the prior file intact too.
+ */
+async function writeCheckpoint(path, checkpoint) {
+    // Callers often pass a full `ContinuityCheckpointV1` they already have in hand (e.g. a
+    // seeded or previously-read one) — TS only checks excess properties on literals, so a
+    // stale `integrity` can arrive here at runtime despite the `Omit` type. Strip it before
+    // hashing rather than hash whatever happened to be attached.
+    const { integrity: _stale, ...body } = checkpoint;
+    const value = { ...body, integrity: { checkpointSha256: checkpointDigest(body) } };
+    const parsed = checkpointSchema.parse(value);
+    await (0, adapter_files_1.atomicRuntimeFile)(path, `${JSON.stringify(parsed, null, 2)}\n`);
+    return parsed;
+}

package/dist/src/context/compact-journal.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOURNAL_ROTATE_BYTES = exports.JOURNAL_LINE_MAX_BYTES = void 0;
+exports.appendCompactJournalLine = appendCompactJournalLine;
+exports.rotateCompactJournalIfNeeded = rotateCompactJournalIfNeeded;
+exports.replayCompactJournal = replayCompactJournal;
+exports.reduceCompactJournal = reduceCompactJournal;
+const promises_1 = require("node:fs/promises");
+const zod_1 = require("zod");
+const compact_payload_1 = require("./compact-payload");
+const EXECUTION_ID_PATTERN = /^exec_[a-zA-Z0-9_-]+$/;
+/** §6 size limits. */
+exports.JOURNAL_LINE_MAX_BYTES = 16 * 1024;
+exports.JOURNAL_ROTATE_BYTES = 1024 * 1024;
+const envelopeSchema = zod_1.z.object({
+    v: zod_1.z.literal(1),
+    at: zod_1.z.string().min(1),
+    executionId: zod_1.z.string().regex(EXECUTION_ID_PATTERN, "invalid execution ID"),
+    policyHash: zod_1.z.string().min(1),
+    runtime: zod_1.z.enum(["claude", "codex"]),
+    phase: zod_1.z.enum(["pre", "post"]),
+    source: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+});
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+/**
+ * The TS append path used by the CLI and by tests. The hook itself (`compact-record.cjs`)
+ * is zero-dependency and appends with a raw `appendFileSync` — this reimplements the same
+ * one-syscall, `O_APPEND` shape so both writers produce lines the other can replay, without
+ * pulling the hook into the dependency graph this module already has (invariant 4).
+ */
+async function appendCompactJournalLine(path, envelope) {
+    const line = `${JSON.stringify(envelope)}\n`;
+    if (byteLength(line) > exports.JOURNAL_LINE_MAX_BYTES) {
+        throw new Error(`journal line exceeds ${exports.JOURNAL_LINE_MAX_BYTES} bytes`);
+    }
+    await (0, promises_1.appendFile)(path, line, { encoding: "utf8", mode: 0o600, flag: "a" });
+}
+/**
+ * Rotates `path` to `path.1` (overwriting any prior `.1`) when it has reached
+ * `JOURNAL_ROTATE_BYTES`. Called from `alp context status|validate`, never from the hook —
+ * the hook only ever appends (invariant 4).
+ */
+async function rotateCompactJournalIfNeeded(path) {
+    let size;
+    try {
+        size = (await (0, promises_1.stat)(path)).size;
+    }
+    catch {
+        return false;
+    }
+    if (size < exports.JOURNAL_ROTATE_BYTES)
+        return false;
+    await (0, promises_1.rename)(path, `${path}.1`);
+    return true;
+}
+async function readIfExists(path) {
+    try {
+        return await (0, promises_1.readFile)(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads `path.1` (if rotation has happened) then `path`, in that order, and turns every
+ * well-formed line into a `CompactEventV1`. A line that is not valid JSON, or does not match
+ * the envelope schema, is dropped and counted rather than failing the whole replay — a
+ * single corrupted append (e.g. a process killed mid-write) must not make the rest of the
+ * journal unreadable.
+ */
+async function replayCompactJournal(path) {
+    const rotated = await readIfExists(`${path}.1`);
+    const current = await readIfExists(path);
+    const lines = [rotated ?? "", current ?? ""]
+        .join("\n")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    const events = [];
+    let droppedLines = 0;
+    for (const line of lines) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            droppedLines += 1;
+            continue;
+        }
+        const result = envelopeSchema.safeParse(parsed);
+        if (!result.success) {
+            droppedLines += 1;
+            continue;
+        }
+        const envelope = result.data;
+        const normalized = (0, compact_payload_1.normalizeCompactEvent)({
+            runtime: envelope.runtime,
+            phase: envelope.phase,
+            // `normalizeCompactEvent` treats this as unknown input and filters it against its own
+            // per-runtime whitelist; the envelope schema only guarantees an object, not that its
+            // values are already strings.
+            source: envelope.source,
+            observedAt: envelope.at,
+        });
+        if (!normalized.ok) {
+            droppedLines += 1;
+            continue;
+        }
+        events.push(normalized.value);
+    }
+    return { events: Object.freeze(events), droppedLines };
+}
+/** The pairing key a `started`/`completed` pair share — `dedupeKey` without its phase suffix. */
+function pairKeyOf(event) {
+    return event.dedupeKey.slice(0, event.dedupeKey.lastIndexOf("|"));
+}
+/**
+ * Folds a replayed event list into the state `alp context status` reports. Duplicate lines
+ * (same `dedupeKey`, e.g. a hook retried by the runtime) are collapsed before anything else,
+ * so `generation` counts distinct completions rather than journal lines.
+ *
+ * `pending` tracks only the single most recent `started` — a later `started` always
+ * supersedes an earlier, still-unmatched one (the orphaned-`PreCompact` case measured on
+ * Claude 2026-09-04), and a `completed` only clears it when the pairing key actually
+ * matches: a late completion for an older event must not clear a newer pending one.
+ */
+function reduceCompactJournal(events) {
+    const seenDedupeKeys = new Set();
+    let generation = 0;
+    let lastCompleted = null;
+    let pending = null;
+    let pendingPairKey = null;
+    for (const event of events) {
+        if (seenDedupeKeys.has(event.dedupeKey))
+            continue;
+        seenDedupeKeys.add(event.dedupeKey);
+        const pairKey = pairKeyOf(event);
+        if (event.phase === "started") {
+            pending = event;
+            pendingPairKey = pairKey;
+            continue;
+        }
+        generation += 1;
+        lastCompleted = event;
+        if (pairKey === pendingPairKey) {
+            pending = null;
+            pendingPairKey = null;
+        }
+    }
+    return { generation, pending, lastCompleted };
+}

package/dist/src/context/compact-payload.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterCompactSource = filterCompactSource;
+exports.normalizeCompactEvent = normalizeCompactEvent;
+/**
+ * Per-runtime whitelist of hook payload keys a journal line may carry.
+ *
+ * A whitelist, not a blacklist, because a payload is a floor and not a ceiling: the schemas
+ * compiled into both binaries under-declare what they actually send. A live Claude
+ * `SessionStart` on 2026-09-03 carried `seconds_since_last_response`, `context_tokens`,
+ * `prompt_cache_likely_expired` and `estimated_cache_write_usd` that no schema mentions, and
+ * carried a different set per `source`. A blacklist would have leaked every one of them into
+ * a file ALP keeps.
+ *
+ * What is deliberately absent, and why:
+ * - `compact_summary` (Claude, 22-32 KB measured) — invariant 8. It is provider history the
+ *   runtime already holds, and one line of it would blow the 16 KiB journal line limit.
+ * - `custom_instructions` (Claude `PreCompact`) — free text from the user's own prompt.
+ * - `transcript_path`, `cwd` — paths ALP already knows and does not need duplicated per line.
+ * - `hook_event_name` — the phase comes from the hook's argv, which is the value ALP
+ *   controls; trusting the payload's own name for it would let the payload pick its bucket.
+ * - `permission_mode` — policy state, owned by ALP, not something to re-learn from a hook.
+ */
+const SOURCE_WHITELIST = Object.freeze({
+    claude: Object.freeze(["session_id", "trigger", "model", "prompt_id", "agent_id", "agent_type"]),
+    codex: Object.freeze(["session_id", "trigger", "model", "turn_id", "agent_id", "agent_type"]),
+});
+/** Per §6 size limits. A whitelisted key with an over-long value is truncated, not dropped. */
+const MAX_VALUE_LENGTH = 256;
+/**
+ * Which key carries the runtime's own id for the event.
+ *
+ * Measured 2026-09-03/04: Claude's `prompt_id` is the same value across `PreCompact`,
+ * `SessionStart(source="compact")` and `PostCompact` of one compaction. Codex's `turn_id`
+ * behaves differently by launch mode — one id per compaction in an inherited TTY, but a
+ * single root-turn id shared by every compaction under `exec` (23 of them in one session).
+ * That is why `dedupeKey` prefers an ALP-assigned sequence; see `normalizeCompactEvent`.
+ */
+const EVENT_ID_KEY = Object.freeze({
+    claude: "prompt_id",
+    codex: "turn_id",
+});
+const PHASE_BY_WIRE = Object.freeze({
+    pre: "started",
+    post: "completed",
+});
+function isRuntimeId(value) {
+    return value === "claude" || value === "codex";
+}
+/**
+ * Copy the whitelisted scalars out of a raw hook payload.
+ *
+ * Scalars only: a whitelisted key holding an object or array is dropped rather than
+ * stringified, because the point is to keep the line small and predictable, and nothing ALP
+ * reads back needs a nested value. Numbers and booleans are kept as their string spelling so
+ * a journal line has exactly one value type.
+ */
+function filterCompactSource(runtime, payload) {
+    if (typeof payload !== "object" || payload === null)
+        return Object.freeze({});
+    const raw = payload;
+    const source = {};
+    for (const key of SOURCE_WHITELIST[runtime]) {
+        const value = raw[key];
+        if (typeof value === "string")
+            source[key] = value.slice(0, MAX_VALUE_LENGTH);
+        else if (typeof value === "number" || typeof value === "boolean")
+            source[key] = String(value);
+    }
+    return Object.freeze(source);
+}
+function readTrigger(source) {
+    const trigger = source.trigger;
+    return trigger === "manual" || trigger === "auto" ? trigger : "unknown";
+}
+/**
+ * Turn one journal line into a `CompactEventV1`, or say why it cannot be one.
+ *
+ * Rejects a structurally wrong line — unknown runtime, unknown phase, a `session_id` that is
+ * present but not a string — because those mean the line was written by something other than
+ * ALP's hook and guessing at it would put fiction in the reduced state. Tolerates a bad
+ * `trigger`, which degrades to `"unknown"`: the type has that state precisely so a future
+ * trigger value cannot fail an otherwise good replay.
+ */
+function normalizeCompactEvent(input) {
+    const issues = [];
+    if (!isRuntimeId(input.runtime))
+        issues.push(`runtime: unknown runtime ${JSON.stringify(input.runtime)}`);
+    if (input.phase !== "pre" && input.phase !== "post") {
+        issues.push(`phase: expected "pre" or "post", received ${JSON.stringify(input.phase)}`);
+    }
+    if (typeof input.observedAt !== "string" || input.observedAt.length === 0) {
+        issues.push("observedAt: expected a non-empty timestamp");
+    }
+    if (typeof input.source !== "object" || input.source === null) {
+        issues.push("source: expected an object");
+    }
+    if (issues.length > 0)
+        return { ok: false, issues: Object.freeze(issues) };
+    const source = filterCompactSource(input.runtime, input.source);
+    const runtimeSessionId = source.session_id ?? null;
+    const runtimeEventId = source[EVENT_ID_KEY[input.runtime]] ?? null;
+    // The compaction's identity, in the order of how well each spelling was measured to
+    // separate one compaction from the next. `observedAt` last so that a line missing every
+    // id still dedupes against a re-append of itself rather than against a different event.
+    const identity = input.sequence === undefined
+        ? runtimeEventId ?? input.observedAt
+        : String(input.sequence);
+    return {
+        ok: true,
+        value: Object.freeze({
+            dedupeKey: [input.runtime, runtimeSessionId ?? "-", identity, PHASE_BY_WIRE[input.phase]].join("|"),
+            runtime: input.runtime,
+            phase: PHASE_BY_WIRE[input.phase],
+            trigger: readTrigger(source),
+            runtimeSessionId,
+            runtimeEventId,
+            observedAt: input.observedAt,
+        }),
+    };
+}