@zq-silk/yui 0.6.0 → 0.6.2

package/dist/telemetry/telemetryCompaction.js

@@ -0,0 +1,251 @@
+import { DEFAULT_TERMINAL_KEEP } from "./telemetryConfig.js";
+/**
+ * Issue 09 — historical compaction.
+ *
+ * Progress events that were appended to semantic Task event history (legacy
+ * behavior) are folded into the telemetry tables inside the Home's `yui.db`:
+ * the newest `keep` rows per Run/generation become the retained window, and
+ * every Run/generation gets an accurate aggregate
+ * (count/first/last/maxSequence/errorCount). The semantic progress events are
+ * then removed through the store's public transaction adapter. Semantic
+ * evidence (Run dispatch/delivery/terminal receipts, Session lifecycle,
+ * Review, Decision, Integration, ...) is never touched.
+ *
+ * Compaction runs on a staged copy of a Home. The caller promotes the staged
+ * copy only after this module validates the result; a validation failure
+ * throws and leaves the original history unchanged.
+ */
+export const PROGRESS_EVENT_TYPE = "runtime.provider-turn-progress";
+/**
+ * Scan a store and build the compaction plan. Read-only: nothing is modified.
+ */
+export function planTelemetryCompaction(store, options = {}) {
+    const keep = options.terminalKeep ?? DEFAULT_TERMINAL_KEEP;
+    const tasks = [];
+    let progressEvents = 0;
+    let generations = 0;
+    let telemetryRows = 0;
+    for (const task of store.listTasks()) {
+        const taskPlan = planTaskCompaction(task.id, store.listEvents(task.id), keep);
+        if (taskPlan === null)
+            continue;
+        tasks.push(taskPlan);
+        progressEvents += taskPlan.progressEventIds.length;
+        generations += taskPlan.generations.length;
+        for (const generation of taskPlan.generations)
+            telemetryRows += generation.window.length;
+    }
+    return {
+        tasks,
+        totals: { tasks: tasks.length, progressEvents, generations, telemetryRows }
+    };
+}
+function planTaskCompaction(taskId, events, keep) {
+    const byGeneration = new Map();
+    const progressEventIds = [];
+    let malformedKept = 0;
+    for (const event of events) {
+        if (event.type !== PROGRESS_EVENT_TYPE)
+            continue;
+        const runId = event.payload.runId;
+        const progressId = event.payload.progressId;
+        if (typeof runId !== "string" || typeof progressId !== "string") {
+            // Fail closed: an anomalous progress row stays semantic and is reported.
+            malformedKept++;
+            continue;
+        }
+        const roleName = typeof event.payload.roleName === "string" ? event.payload.roleName : "unknown";
+        const generation = typeof event.payload.launchId === "string" && event.payload.launchId !== ""
+            ? event.payload.launchId
+            : typeof event.payload.nativeSessionId === "string" && event.payload.nativeSessionId !== ""
+                ? event.payload.nativeSessionId
+                : "unbound";
+        const key = `${roleName}\u0000${runId}\u0000${generation}`;
+        const group = byGeneration.get(key);
+        if (group === undefined)
+            byGeneration.set(key, [event]);
+        else
+            group.push(event);
+        progressEventIds.push(event.id);
+    }
+    if (progressEventIds.length === 0 && malformedKept === 0)
+        return null;
+    const generations = [];
+    for (const group of byGeneration.values()) {
+        generations.push(planGenerationCompaction(taskId, group, keep));
+    }
+    return { taskId, progressEventIds, malformedKept, generations };
+}
+function planGenerationCompaction(taskId, events, keep) {
+    const first = events[0];
+    const roleName = typeof first.payload.roleName === "string" ? first.payload.roleName : "unknown";
+    const runId = first.payload.runId;
+    const generation = typeof first.payload.launchId === "string" && first.payload.launchId !== ""
+        ? first.payload.launchId
+        : typeof first.payload.nativeSessionId === "string" && first.payload.nativeSessionId !== ""
+            ? first.payload.nativeSessionId
+            : "unbound";
+    const ordered = [...events].sort(compareProgressEvents);
+    let firstAt = progressAt(ordered[0]);
+    let lastAt = firstAt;
+    let maxSequence = null;
+    let errorCount = 0;
+    for (const event of ordered) {
+        const at = progressAt(event);
+        if (at < firstAt)
+            firstAt = at;
+        if (at > lastAt)
+            lastAt = at;
+        const sequence = event.payload.sequence;
+        if (typeof sequence === "string") {
+            const value = Number(sequence);
+            if (Number.isSafeInteger(value) && (maxSequence === null || value > maxSequence)) {
+                maxSequence = value;
+            }
+        }
+        if ((typeof event.payload.error === "string" && event.payload.error !== "")
+            || (typeof event.payload.errorKind === "string" && event.payload.errorKind !== "")) {
+            errorCount++;
+        }
+    }
+    const window = ordered.slice(-keep).map((event) => ({
+        taskId,
+        roleName,
+        runId,
+        generation,
+        progressId: event.payload.progressId,
+        ...(typeof event.payload.sequence === "string"
+            && Number.isSafeInteger(Number(event.payload.sequence))
+            ? { sequence: Number(event.payload.sequence) }
+            : {}),
+        payload: { ...event.payload },
+        receivedAt: progressAt(event)
+    }));
+    return {
+        roleName,
+        runId,
+        generation,
+        aggregate: {
+            taskId,
+            roleName,
+            runId,
+            generation,
+            firstAt,
+            lastAt,
+            count: ordered.length,
+            maxSequence,
+            errorCount
+        },
+        window
+    };
+}
+function compareProgressEvents(a, b) {
+    const seqA = numericSequence(a);
+    const seqB = numericSequence(b);
+    if (seqA !== null && seqB !== null && seqA !== seqB)
+        return seqA - seqB;
+    const atA = Date.parse(progressAt(a));
+    const atB = Date.parse(progressAt(b));
+    if (atA !== atB)
+        return atA - atB;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function numericSequence(event) {
+    const raw = event.payload.sequence;
+    if (typeof raw !== "string")
+        return null;
+    const value = Number(raw);
+    return Number.isSafeInteger(value) ? value : null;
+}
+function progressAt(event) {
+    const raw = event.payload.progressAt;
+    if (typeof raw === "string" && Number.isFinite(Date.parse(raw)))
+        return raw;
+    return event.createdAt;
+}
+/**
+ * Apply a plan to a staged Home. The telemetry windows/aggregates are imported
+ * first and validated, then the semantic progress events are removed inside
+ * one store transaction and validated again. Throws on any validation
+ * failure; the caller must discard the staged Home in that case. A crash
+ * between the two phases leaves the staged Home in the equivalent of
+ * dual-write state (telemetry imported, semantic progress still present),
+ * which is harmless and re-runnable.
+ */
+export function applyTelemetryCompaction(store, telemetry, plan, options) {
+    const now = options.now ?? new Date();
+    const keep = options.terminalKeep ?? DEFAULT_TERMINAL_KEEP;
+    if (!options.dryRun) {
+        // Import first and validate the sidecar before touching semantic history:
+        // a validation failure leaves the staged Home's semantic events intact.
+        for (const task of plan.tasks) {
+            for (const generation of task.generations) {
+                telemetry.importGeneration(generation.window, generation.aggregate);
+            }
+        }
+        validateAggregates(telemetry, plan);
+        store.transaction(() => {
+            for (const task of plan.tasks) {
+                if (task.progressEventIds.length === 0)
+                    continue;
+                store.removeEvents(task.taskId, task.progressEventIds);
+            }
+        });
+        validateSemanticClean(store, plan);
+    }
+    return {
+        schemaVersion: 1,
+        createdAt: now.toISOString(),
+        dryRun: options.dryRun,
+        source: options.source,
+        terminalKeep: keep,
+        totals: plan.totals,
+        tasks: plan.tasks.map((task) => ({
+            taskId: task.taskId,
+            removedProgressEvents: options.dryRun ? 0 : task.progressEventIds.length,
+            generations: task.generations.map((generation) => generation.aggregate)
+        })),
+        validation: "passed"
+    };
+}
+/**
+ * Verify every planned Run/generation aggregate in the sidecar matches the
+ * plan (count, first/last, max sequence) before semantic history is touched.
+ */
+function validateAggregates(telemetry, plan) {
+    for (const task of plan.tasks) {
+        for (const generation of task.generations) {
+            const stored = telemetry.aggregateGeneration(generation.aggregate.taskId, generation.aggregate.roleName, generation.aggregate.runId, generation.aggregate.generation);
+            if (stored === null) {
+                throw new Error(`Compaction validation failed: missing aggregate for Run ${generation.aggregate.runId}.`);
+            }
+            const expected = generation.aggregate;
+            if (stored.count !== expected.count
+                || stored.firstAt !== expected.firstAt
+                || stored.lastAt !== expected.lastAt
+                || stored.maxSequence !== expected.maxSequence
+                || stored.errorCount !== expected.errorCount) {
+                throw new Error(`Compaction validation failed: aggregate mismatch for Run ${expected.runId} `
+                    + `(expected count=${expected.count} first=${expected.firstAt} last=${expected.lastAt} `
+                    + `maxSequence=${String(expected.maxSequence)} errors=${expected.errorCount}; `
+                    + `got count=${stored.count} first=${stored.firstAt} last=${stored.lastAt} `
+                    + `maxSequence=${String(stored.maxSequence)} errors=${stored.errorCount}).`);
+            }
+        }
+    }
+}
+/** Verify no planned progress event remains in semantic history. */
+function validateSemanticClean(store, plan) {
+    for (const task of plan.tasks) {
+        if (task.progressEventIds.length === 0)
+            continue;
+        const remaining = new Set(store.listEvents(task.taskId)
+            .filter((event) => event.type === PROGRESS_EVENT_TYPE)
+            .map((event) => event.id));
+        for (const id of task.progressEventIds) {
+            if (remaining.has(id)) {
+                throw new Error(`Compaction validation failed: progress event ${task.taskId}/${id} still present.`);
+            }
+        }
+    }
+}

package/dist/telemetry/telemetryConfig.js

@@ -0,0 +1,64 @@
+/**
+ * Issue 09 — telemetry retention & compaction configuration.
+ *
+ * Telemetry lives in the Home's authoritative `yui.db` (database-only
+ * direction). Its activation is an explicit per-Home switch so the feature
+ * can be rolled out (legacy → dual → bounded) and rolled back independently
+ * of every other Issue. Retention defaults are the schema's own constants
+ * (§4.4); the environment only overrides them.
+ */
+import { TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_RUN_CAP } from "../storage/sqliteSchema.js";
+export const DEFAULT_TELEMETRY_MODE = "legacy";
+/** Terminal Run/generation progress rows retained after prune. */
+export const DEFAULT_TERMINAL_KEEP = TELEMETRY_KEEP_PER_GENERATION;
+/** Hard cap of progress rows per Run while it is still active. */
+export const DEFAULT_RUN_CAP = TELEMETRY_RUN_CAP;
+/**
+ * Absolute ceiling for the configurable Run cap. Retention can be tuned but
+ * never disabled: every Home keeps a computable upper bound on telemetry
+ * rows (Tasks × Runs × cap).
+ */
+export const MAX_RUN_CAP = 10_000_000;
+const TELEMETRY_MODES = ["legacy", "dual", "bounded"];
+/**
+ * Resolve `YUI_TELEMETRY_MODE` (default `legacy`). Only the three exact
+ * values (case-insensitive) are accepted; anything else fails closed at
+ * startup instead of silently changing progress routing.
+ */
+export function resolveTelemetryMode(env = process.env) {
+    const raw = env.YUI_TELEMETRY_MODE?.trim().toLowerCase();
+    if (raw === undefined || raw === "")
+        return DEFAULT_TELEMETRY_MODE;
+    if (!TELEMETRY_MODES.includes(raw)) {
+        throw new TypeError(`YUI_TELEMETRY_MODE must be one of ${TELEMETRY_MODES.join(", ")}; got ${JSON.stringify(raw)}.`);
+    }
+    return raw;
+}
+/**
+ * Resolve the terminal-Run retention window (`YUI_TELEMETRY_TERMINAL_KEEP`,
+ * default 200). Must be a positive integer.
+ */
+export function resolveTerminalKeep(env = process.env) {
+    return resolvePositiveInteger(env.YUI_TELEMETRY_TERMINAL_KEEP, DEFAULT_TERMINAL_KEEP, "YUI_TELEMETRY_TERMINAL_KEEP");
+}
+/**
+ * Resolve the active-Run hard cap (`YUI_TELEMETRY_RUN_CAP`, default 50,000).
+ * Must be a positive integer not exceeding {@link MAX_RUN_CAP}; the cap
+ * cannot be disabled.
+ */
+export function resolveRunCap(env = process.env) {
+    const cap = resolvePositiveInteger(env.YUI_TELEMETRY_RUN_CAP, DEFAULT_RUN_CAP, "YUI_TELEMETRY_RUN_CAP");
+    if (cap > MAX_RUN_CAP) {
+        throw new TypeError(`YUI_TELEMETRY_RUN_CAP must not exceed ${MAX_RUN_CAP.toLocaleString("en-US")} (retention cannot be disabled).`);
+    }
+    return cap;
+}
+function resolvePositiveInteger(raw, fallback, label) {
+    if (raw === undefined || raw.trim() === "")
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`${label} must be a positive integer; got ${JSON.stringify(raw)}.`);
+    }
+    return value;
+}

package/dist/telemetry/telemetryRouter.js

@@ -0,0 +1,32 @@
+/**
+ * Route one provider progress observation according to `telemetry.mode`:
+ *
+ * - `legacy`  — semantic event only (master behavior).
+ * - `dual`    — semantic event plus best-effort sidecar upsert.
+ * - `bounded` — sidecar upsert only; semantic events stop carrying progress.
+ *
+ * The sidecar write is best-effort and isolated: a sink failure must never
+ * block or roll back the semantic lane.
+ */
+export function routeProviderProgress(input) {
+    const { mode, entry, semanticExists, writeSemantic, sink } = input;
+    if (mode === "bounded") {
+        safeObserve(sink, entry);
+        return "applied";
+    }
+    if (semanticExists)
+        return "applied";
+    writeSemantic();
+    if (mode === "dual")
+        safeObserve(sink, entry);
+    return "applied";
+}
+function safeObserve(sink, entry) {
+    try {
+        sink.observe(entry);
+    }
+    catch {
+        // Telemetry is best-effort by contract; sinks must not throw, but a
+        // broken sink must never take down the semantic lane.
+    }
+}

package/dist/telemetry/telemetryStore.js

@@ -0,0 +1,19 @@
+/** No-op sink for `legacy` mode and for callers without a sidecar. */
+export class NullTelemetrySink {
+    mode;
+    constructor(mode = "legacy") {
+        this.mode = mode;
+    }
+    observe(_entry) { }
+    health() {
+        return {
+            mode: this.mode,
+            available: false,
+            dropped: 0,
+            coalesced: 0,
+            lastError: null,
+            rows: 0
+        };
+    }
+    async close() { }
+}

package/dist/telemetry/telemetryWiring.js

@@ -0,0 +1,33 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveRunCap, resolveTelemetryMode, resolveTerminalKeep } from "./telemetryConfig.js";
+import { SqliteTelemetryStore } from "./sqliteTelemetryStore.js";
+import { COMMITTED_DATABASE_FILENAME } from "../storage/upgrade/sqliteStateMigration.js";
+/**
+ * Open the telemetry sidecar for a Home, resolved from the environment
+ * (`YUI_TELEMETRY_MODE`, default `legacy`). Returns null in legacy mode so
+ * callers keep the exact master behavior and never touch the database.
+ *
+ * Telemetry lives in the Home's authoritative `yui.db`. A Home without a
+ * database has not reached SQLite storage yet, so dual/bounded mode fails
+ * closed at startup with a bounded diagnosis instead of silently creating an
+ * empty database (which would corrupt Home classification). Once opened, the
+ * store fails isolated: a broken sidecar only increments its dropped counter
+ * and never blocks the semantic lane.
+ */
+export function openSchedulerTelemetry(home, env = process.env) {
+    const mode = resolveTelemetryMode(env);
+    if (mode === "legacy")
+        return null;
+    const dbPath = join(home, COMMITTED_DATABASE_FILENAME);
+    if (!existsSync(dbPath)) {
+        throw new Error(`YUI_TELEMETRY_MODE=${mode} requires SQLite storage, but ${dbPath} does not exist. `
+            + "Migrate this Home to the database backend first (yui upgrade).");
+    }
+    const store = new SqliteTelemetryStore(home, {
+        mode,
+        terminalKeep: resolveTerminalKeep(env),
+        runCap: resolveRunCap(env)
+    });
+    return { mode, sink: store, reader: store };
+}

package/dist/tmux/tmuxManager.js

@@ -723,6 +723,25 @@ export class TmuxManager {
         const snapshot = await this.sessionWindowNamesAsync(taskId);
         return snapshot.names.includes(roleName) ? "running" : "exited";
     }
+    /** Exact pane process state for one Role, used by owner-identity recording. */
+    inspectRolePane(taskId, roleName) {
+        const pane = this.inspectPane(taskId, roleName);
+        return {
+            ...(pane.pid === undefined ? {} : { pid: pane.pid }),
+            target: pane.target,
+            dead: pane.dead,
+            currentCommand: pane.currentCommand
+        };
+    }
+    async inspectRolePaneAsync(taskId, roleName) {
+        const pane = await this.inspectPaneAsync(taskId, roleName);
+        return {
+            ...(pane.pid === undefined ? {} : { pid: pane.pid }),
+            target: pane.target,
+            dead: pane.dead,
+            currentCommand: pane.currentCommand
+        };
+    }
     stopTask(taskId) {
         const taskSession = this.sessionName(taskId);
         const sessions = this.taskSessionGroupNames(taskId);
@@ -1037,7 +1056,7 @@ function launchCommand(launch) {
 function isExplicitlyAbsentTmuxSession(error) {
     if (!(error instanceof CommandExecutionError))
         return false;
-    return /can't find (?:session|window|pane)|no server running|error connecting to .+ \(No such file or directory\)/i
+    return /can't find (?:session|window|pane)|no server running|no current target|session not found|error connecting to .+ \(No such file or directory\)/i
         .test(error.stderr);
 }
 function isUnavailableTmuxStatus(error) {

package/dist/tmux/tmuxSocketEndpoint.js

@@ -0,0 +1,20 @@
+import { join, resolve } from "node:path";
+/**
+ * Exact same-user directory in which `tmux -L` publishes a named server.
+ * TMUX_TMPDIR is tmux's only configurable root; TMPDIR/TMP/TEMP do not apply.
+ */
+export function tmuxSocketDirectory(environment = process.env) {
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    return join(resolve(nonEmptyTmuxTmpdir(environment) ?? "/tmp"), `tmux-${uid}`);
+}
+/** Pins an invoked tmux process to the same root selected above. */
+export function tmuxSocketEnvironment(environment = process.env) {
+    return {
+        ...environment,
+        TMUX_TMPDIR: nonEmptyTmuxTmpdir(environment)
+    };
+}
+function nonEmptyTmuxTmpdir(environment) {
+    const configured = environment.TMUX_TMPDIR;
+    return configured !== undefined && configured.length > 0 ? configured : undefined;
+}

package/dist/verification/gateArtifact.js

@@ -0,0 +1,216 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { requireIdentity, requirePositiveInteger, requireText, requireTimestamp } from "../domain/validation.js";
+/**
+ * Issue 08: the reusable exact-SHA gate evidence record.
+ *
+ * A GateArtifact binds one gate run to its full identity tuple: Project,
+ * candidate commit, VerificationPlan digest, toolchain digest, and (for L2)
+ * the source/base/target boundary. The same tuple reuses the same successful
+ * artifact; any tuple change invalidates it. Artifacts are stored in the
+ * SQLite `gate_artifacts` / `gate_artifact_logs` tables, backend-neutral
+ * through the GateArtifactStorePort.
+ */
+export const GATE_ARTIFACT_SCHEMA_VERSION = 1;
+/** The evidence-reference scheme carried in manifests and queue entries. */
+export const GATE_ARTIFACT_REF_PREFIX = "gate-artifact:";
+export function gateArtifactRef(key) {
+    return `${GATE_ARTIFACT_REF_PREFIX}${key}`;
+}
+export function parseGateArtifactRef(ref) {
+    return ref.startsWith(GATE_ARTIFACT_REF_PREFIX)
+        ? ref.slice(GATE_ARTIFACT_REF_PREFIX.length)
+        : undefined;
+}
+/** Content-addressed key: the same identity tuple always maps to one key. */
+export function gateArtifactKey(identity) {
+    return createHash("sha256")
+        .update(canonicalJson(identity))
+        .digest("hex");
+}
+export function createGateArtifact(identity, metadata, now) {
+    const timestamp = now.toISOString();
+    return validateGateArtifact({
+        schemaVersion: GATE_ARTIFACT_SCHEMA_VERSION,
+        key: gateArtifactKey(identity),
+        projectId: identity.projectId,
+        level: identity.level,
+        commit: identity.commit,
+        planId: requireIdentity(metadata.planId, "GateArtifact planId"),
+        planVersion: requireText(metadata.planVersion, "GateArtifact planVersion"),
+        planDigest: identity.planDigest,
+        toolchainDigest: identity.toolchainDigest,
+        ...(identity.boundary === undefined ? {} : { boundary: identity.boundary }),
+        steps: Object.freeze([]),
+        generator: requireText(metadata.generator, "GateArtifact generator"),
+        status: "incomplete",
+        outcome: "unknown",
+        potentialReuseCount: 0,
+        reuseCount: 0,
+        createdAt: timestamp,
+        lastUsedAt: timestamp
+    });
+}
+/** Terminalize an artifact with its step results. */
+export function completeGateArtifact(artifact, steps, outcome, now) {
+    validateGateArtifact(artifact);
+    if (artifact.status !== "incomplete") {
+        throw new Error(`GateArtifact is already complete: ${artifact.key}.`);
+    }
+    const timestamp = now.toISOString();
+    return validateGateArtifact({
+        ...artifact,
+        steps,
+        status: "complete",
+        outcome,
+        completedAt: timestamp,
+        lastUsedAt: timestamp
+    });
+}
+/** Record a shadow potential-reuse observation (record mode). */
+export function recordGateArtifactPotentialReuse(artifact, now) {
+    validateGateArtifact(artifact);
+    return validateGateArtifact({
+        ...artifact,
+        potentialReuseCount: artifact.potentialReuseCount + 1,
+        lastUsedAt: now.toISOString()
+    });
+}
+/** Record an actual reuse (reuse/enforce mode). */
+export function recordGateArtifactReuse(artifact, now) {
+    validateGateArtifact(artifact);
+    if (artifact.status !== "complete" || artifact.outcome !== "succeeded") {
+        throw new Error(`Only a complete successful GateArtifact can be reused: ${artifact.key}.`);
+    }
+    return validateGateArtifact({
+        ...artifact,
+        reuseCount: artifact.reuseCount + 1,
+        lastUsedAt: now.toISOString()
+    });
+}
+export function validateGateArtifact(artifact) {
+    if (artifact.schemaVersion !== GATE_ARTIFACT_SCHEMA_VERSION) {
+        throw new Error(`GateArtifact must use schemaVersion ${GATE_ARTIFACT_SCHEMA_VERSION}.`);
+    }
+    requireIdentity(artifact.projectId, "GateArtifact projectId");
+    if (artifact.level !== "L1" && artifact.level !== "L2") {
+        throw new Error(`GateArtifact level is invalid: ${String(artifact.level)}.`);
+    }
+    requireCommit(artifact.commit, "GateArtifact commit");
+    requireDigest(artifact.planDigest, "GateArtifact planDigest");
+    requireDigest(artifact.toolchainDigest, "GateArtifact toolchainDigest");
+    requireDigest(artifact.key, "GateArtifact key");
+    if (artifact.key !== gateArtifactKey({
+        projectId: artifact.projectId,
+        level: artifact.level,
+        commit: artifact.commit,
+        planDigest: artifact.planDigest,
+        toolchainDigest: artifact.toolchainDigest,
+        ...(artifact.boundary === undefined ? {} : { boundary: artifact.boundary })
+    })) {
+        throw new Error("GateArtifact key does not match its identity tuple.");
+    }
+    if (artifact.level === "L2" && artifact.boundary === undefined) {
+        throw new Error("An L2 GateArtifact requires a target boundary.");
+    }
+    if (artifact.boundary !== undefined) {
+        requireText(artifact.boundary.targetRef, "GateArtifact boundary targetRef");
+        requireCommit(artifact.boundary.baseHead, "GateArtifact boundary baseHead");
+    }
+    if (!["incomplete", "complete"].includes(artifact.status)) {
+        throw new Error(`GateArtifact status is invalid: ${String(artifact.status)}.`);
+    }
+    if (!["unknown", "succeeded", "failed"].includes(artifact.outcome)) {
+        throw new Error(`GateArtifact outcome is invalid: ${String(artifact.outcome)}.`);
+    }
+    if (artifact.status === "incomplete" && artifact.outcome !== "unknown") {
+        throw new Error("An incomplete GateArtifact must have outcome unknown.");
+    }
+    if (artifact.status === "complete" && artifact.outcome === "unknown") {
+        throw new Error("A complete GateArtifact must have a terminal outcome.");
+    }
+    const names = new Set();
+    for (const step of artifact.steps) {
+        requireIdentity(step.name, "GateArtifact step name");
+        if (names.has(step.name)) {
+            throw new Error(`GateArtifact step names must be unique: ${step.name}.`);
+        }
+        names.add(step.name);
+        requireText(step.command, `GateArtifact step ${step.name} command`);
+        if (!["passed", "failed", "skipped"].includes(step.outcome)) {
+            throw new Error(`GateArtifact step ${step.name} outcome is invalid.`);
+        }
+        requirePositiveInteger(step.durationMs + 1, `GateArtifact step ${step.name} durationMs`);
+        requireText(step.logPath, `GateArtifact step ${step.name} logPath`);
+        if (isAbsolute(step.logPath) || step.logPath.includes("..")) {
+            throw new Error(`GateArtifact step ${step.name} logPath must be relative.`);
+        }
+        requireDigest(step.logDigest, `GateArtifact step ${step.name} logDigest`);
+        if (!Number.isSafeInteger(step.logBytes) || step.logBytes < 0) {
+            throw new Error(`GateArtifact step ${step.name} logBytes is invalid.`);
+        }
+    }
+    requirePositiveInteger(artifact.potentialReuseCount + 1, "GateArtifact potentialReuseCount");
+    requirePositiveInteger(artifact.reuseCount + 1, "GateArtifact reuseCount");
+    requireTimestamp(artifact.createdAt, "GateArtifact createdAt");
+    requireTimestamp(artifact.lastUsedAt, "GateArtifact lastUsedAt");
+    if (artifact.completedAt !== undefined) {
+        requireTimestamp(artifact.completedAt, "GateArtifact completedAt");
+    }
+    return artifact;
+}
+/**
+ * Verify that every step log is present in the log map and matches its
+ * recorded digest. A lost or corrupted log means the artifact cannot serve
+ * as complete L2 evidence: consumers must treat it as a gap.
+ */
+export function verifyGateArtifactLogs(artifact, logs) {
+    const missing = [];
+    const corrupted = [];
+    for (const step of artifact.steps) {
+        const content = logs.get(step.name);
+        if (content === undefined) {
+            missing.push(step.name);
+            continue;
+        }
+        const digest = createHash("sha256").update(content).digest("hex");
+        if (digest !== step.logDigest || content.length !== step.logBytes) {
+            corrupted.push(step.name);
+        }
+    }
+    return Object.freeze({
+        ok: missing.length === 0 && corrupted.length === 0,
+        missing: Object.freeze(missing),
+        corrupted: Object.freeze(corrupted)
+    });
+}
+export function isReusableGateArtifact(artifact) {
+    return artifact.status === "complete" && artifact.outcome === "succeeded";
+}
+function requireCommit(value, label) {
+    const normalized = requireText(value, label).toLowerCase();
+    if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u.test(normalized)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function requireDigest(value, label) {
+    const normalized = requireText(value, label).toLowerCase();
+    if (!/^[a-f0-9]{64}$/u.test(normalized)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value === "object" && value !== null) {
+        const entries = Object.entries(value)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+        return Object.fromEntries(entries.map(([key, entry]) => [key, canonicalize(entry)]));
+    }
+    return value;
+}