@zq-silk/yui 0.2.0 → 0.4.2

package/dist/integration/integrationAttempt.js

@@ -0,0 +1,142 @@
+import { normalizedUniqueIdentities, normalizedUniqueText, requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
+import { validateTaskRecordReference } from "../task/taskRecordReference.js";
+import { normalizeCheckResult } from "./checkResult.js";
+export function createIntegrationAttempt(input, now) {
+    const timestamp = now.toISOString();
+    return validateIntegrationAttempt({
+        schemaVersion: 2,
+        id: input.id,
+        taskId: input.taskId,
+        projectId: input.projectId,
+        targetRef: input.targetRef,
+        expectedHead: input.expectedHead,
+        changeSetIds: [...input.changeSetIds],
+        checkCommands: normalizedUniqueText(input.checkCommands ?? [], "Integration check command"),
+        status: "running",
+        createdAt: timestamp,
+        updatedAt: timestamp
+    });
+}
+export function requireLeaderDecision(attempt, report, now) {
+    validateIntegrationAttempt(attempt);
+    const continuingAfterResolution = attempt.status === "blocked"
+        && attempt.resolution?.action === "manual-resolution";
+    if (attempt.status !== "running" && !continuingAfterResolution) {
+        throw new Error(`Integration cannot request a decision from ${attempt.status}.`);
+    }
+    const { resolution: _previousResolution, endedAt: _endedAt, ...unresolved } = attempt;
+    return validateIntegrationAttempt({
+        ...unresolved,
+        status: "blocked",
+        conflict: normalizeConflictReport(report),
+        updatedAt: now.toISOString()
+    });
+}
+export function recordResolutionDecision(attempt, decision, now) {
+    validateIntegrationAttempt(attempt);
+    if (attempt.status !== "blocked" || attempt.conflict === undefined) {
+        throw new Error("Integration has no pending semantic decision.");
+    }
+    if (decision.action !== "manual-resolution" && decision.action !== "reject") {
+        throw new Error(`Resolution action is invalid: ${String(decision.action)}.`);
+    }
+    const timestamp = now.toISOString();
+    return validateIntegrationAttempt({
+        ...attempt,
+        status: decision.action === "reject" ? "failed" : "blocked",
+        resolution: {
+            action: decision.action,
+            rationale: requireText(decision.rationale, "Resolution rationale"),
+            decidedBy: "leader",
+            decidedAt: timestamp
+        },
+        updatedAt: timestamp,
+        ...(decision.action === "reject" ? { endedAt: timestamp } : {})
+    });
+}
+export function updateIntegrationAttempt(attempt, patch, now) {
+    validateIntegrationAttempt(attempt);
+    const status = patch.status ?? attempt.status;
+    const terminal = ["committed", "failed"].includes(status);
+    const updated = {
+        ...attempt,
+        ...patch,
+        status,
+        updatedAt: now.toISOString(),
+        ...(terminal ? { endedAt: now.toISOString() } : {})
+    };
+    if (!terminal && updated.endedAt !== undefined) {
+        const { endedAt: _endedAt, ...active } = updated;
+        return validateIntegrationAttempt(active);
+    }
+    return validateIntegrationAttempt(updated);
+}
+export function validateIntegrationAttempt(attempt) {
+    if (attempt.schemaVersion !== 2) {
+        throw new Error("IntegrationAttempt must use schemaVersion 2.");
+    }
+    validateTaskRecordReference({
+        taskId: attempt.taskId,
+        localId: attempt.id
+    }, "integrationAttempt");
+    requireIdentity(attempt.projectId, "Project id");
+    requireText(attempt.targetRef, "Integration target ref");
+    requireCommit(attempt.expectedHead, "Integration expected head");
+    normalizedUniqueIdentities(attempt.changeSetIds, "ChangeSet id");
+    for (const changeSetId of attempt.changeSetIds) {
+        validateTaskRecordReference({ taskId: attempt.taskId, localId: changeSetId }, "changeSet");
+    }
+    normalizedUniqueText(attempt.checkCommands, "Integration check command");
+    if (attempt.changeSetIds.length === 0) {
+        throw new Error("IntegrationAttempt requires at least one ChangeSet.");
+    }
+    if (attempt.candidateCommit !== undefined) {
+        requireCommit(attempt.candidateCommit, "Integration candidate commit");
+    }
+    if (![
+        "running",
+        "blocked",
+        "validating",
+        "committed",
+        "failed"
+    ].includes(attempt.status)) {
+        throw new Error(`Integration status is invalid: ${String(attempt.status)}.`);
+    }
+    if (attempt.conflict !== undefined)
+        normalizeConflictReport(attempt.conflict);
+    if (attempt.status === "blocked" && attempt.conflict === undefined) {
+        throw new Error("A blocked Integration needs a ConflictReport.");
+    }
+    if (attempt.resolution !== undefined) {
+        if (attempt.resolution.action !== "manual-resolution"
+            && attempt.resolution.action !== "reject") {
+            throw new Error(`Resolution action is invalid: ${String(attempt.resolution.action)}.`);
+        }
+        requireText(attempt.resolution.rationale, "Resolution rationale");
+        if (attempt.resolution.decidedBy !== "leader") {
+            throw new Error("Only the Leader may record a ResolutionDecision.");
+        }
+        requireTimestamp(attempt.resolution.decidedAt, "Resolution decidedAt");
+    }
+    attempt.checks?.forEach(normalizeCheckResult);
+    requireTimestamp(attempt.createdAt, "Integration Attempt createdAt");
+    requireTimestamp(attempt.updatedAt, "Integration Attempt updatedAt");
+    if (["committed", "failed"].includes(attempt.status)) {
+        requireTimestamp(attempt.endedAt ?? "", "Integration Attempt endedAt");
+    }
+    return attempt;
+}
+function normalizeConflictReport(report) {
+    const affectedPaths = normalizedUniqueText(report.affectedPaths, "Conflict path");
+    return {
+        affectedPaths,
+        summary: requireText(report.summary, "Conflict summary")
+    };
+}
+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;
+}

package/dist/interaction/operatorPresentation.js

@@ -0,0 +1,96 @@
+import { formatTimestamp } from "../output/timePresentation.js";
+import { formatInputRequestReceiptId, formatTaskRecordReference } from "../task/taskRecordReference.js";
+export function createInputRequestOperatorPresentation(request, context) {
+    const policy = request.policy;
+    const recommendation = policy.kind === "recommended"
+        ? request.choices.find(({ key }) => key === policy.recommendedChoiceKey)
+        : undefined;
+    if (policy.kind === "recommended" && recommendation === undefined) {
+        throw new Error(`Input request ${request.id} recommendation ${policy.recommendedChoiceKey} is missing.`);
+    }
+    return {
+        category: "attention",
+        taskId: request.taskId,
+        receiptId: formatInputRequestReceiptId(request.taskId, request.id),
+        source: { kind: "input-request", taskId: request.taskId, localId: request.id },
+        text: [
+            "A Task Leader is waiting for a boundary decision. Inspect it before involving the user.",
+            "Present it only when it is a user-owned choice, authorization, credential, unavailable external fact, or irreversible operation.",
+            `If it is an implementation, scheduling, review, or recoverable runtime choice, do not present it to the user; return it to the Leader with: yui task input cancel ${request.taskId} ${request.id} --reason \"Operator returned: not a user-owned boundary\"`,
+            "For a user-owned boundary, do not answer it yourself; do not answer or choose on the user's behalf; relay the user's exact response only.",
+            `Task: ${request.taskId}`,
+            `Input: ${request.id}`,
+            `Question: ${request.question}`,
+            ...(request.choices.length === 0
+                ? ["Answer type: free text"]
+                : ["Choices:", ...request.choices.map(({ key, label }) => `  ${key}: ${label}`)]),
+            ...(policy.kind === "required"
+                ? ["Decision policy: this requires the user's response; there is no automatic fallback."]
+                : [
+                    `Agent recommendation: ${recommendation.key}: ${recommendation.label}`,
+                    `Automatic fallback after: ${formatTimestamp(policy.timeoutAt, context.timeZone)}`
+                ]),
+            `Inspect: yui task input show ${formatTaskRecordReference(request.taskId, request.id, "inputRequest")}`,
+            request.choices.length === 0
+                ? `After the user replies: yui task input answer ${formatTaskRecordReference(request.taskId, request.id, "inputRequest")} --text "<answer>"`
+                : `After the user chooses: yui task input answer ${formatTaskRecordReference(request.taskId, request.id, "inputRequest")} --choice <key>`
+        ].join("\n")
+    };
+}
+export function createLeaderRecoveryOperatorPresentation(notification) {
+    return {
+        category: "attention",
+        taskId: notification.taskId,
+        receiptId: `leader-recovery:${notification.taskId}:${notification.createdAt}`,
+        source: { kind: "leader-recovery", id: notification.taskId },
+        text: [
+            "A Task cannot recover its Leader automatically and needs user attention.",
+            `Task: ${notification.taskId}`,
+            `Failure: ${notification.message}`,
+            `Inspect: yui task show ${notification.taskId}`,
+            "Recovery status: yui jobs list",
+            `Retry after inspection: yui jobs retry leader-recovery:${notification.taskId}`
+        ].join("\n")
+    };
+}
+export function createLeaderStallOperatorPresentation(notification) {
+    return {
+        category: "attention",
+        taskId: notification.taskId,
+        receiptId: `leader-stall:${notification.taskId}:${notification.runId}:${notification.progressAt}`,
+        source: {
+            kind: "leader-stall",
+            id: `${notification.runId}:${notification.progressAt}`
+        },
+        text: [
+            "A Task Leader is truly stalled and needs user attention.",
+            `Task: ${notification.taskId}`,
+            `Leader Run: ${notification.runId}`,
+            `lastProgressAt: ${notification.progressAt}`,
+            "Classification: truly-stalled",
+            `Evidence: ${notification.evidenceKey}`,
+            "Controller preserved the exact Run/Session fence and performed no automatic Enter, reset, retry, kill, or Session replacement.",
+            `Inspect: yui task context ${notification.taskId}`,
+            "Choose the supported continuation, reset, retry, Agent change, or user-input action only after inspection."
+        ].join("\n")
+    };
+}
+export function createTaskTerminalOperatorPresentation(notification) {
+    const action = notification.status === "completed" ? "completed" : "retired";
+    const actor = notification.by === "leader"
+        ? "its Leader"
+        : notification.by === "operator"
+            ? "the Operator"
+            : "the user";
+    return {
+        category: "information",
+        taskId: notification.taskId,
+        receiptId: `task-terminal:${notification.taskId}:${notification.status}:${notification.createdAt}`,
+        source: { kind: "task-terminal", id: notification.taskId },
+        text: [
+            `Task ${notification.taskId} was ${action} by ${actor}.`,
+            `Summary: ${notification.summary}`,
+            `Inspect: yui task show ${notification.taskId}`
+        ].join("\n")
+    };
+}

package/dist/lifecycle/canonicalLifecycleEvent.js

@@ -0,0 +1,342 @@
+export function isPreInputReadinessSupported(capability) {
+    return capability.status === "supported";
+}
+export class CanonicalLifecycleError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = "CanonicalLifecycleError";
+    }
+}
+const RUN_SCOPED_PHASES = new Set([
+    "prompt-pushed",
+    "provider-accepted",
+    "turn-progress",
+    "turn-terminal"
+]);
+/**
+ * Phases that assert durable provider truth about a Run. Every one must carry
+ * the complete run-scoped identity — runId AND the generation fences
+ * (nativeSessionId + launchId) AND, where the transport owns it, the receiptId —
+ * because a missing or wrong fence must fail closed rather than advance a Run or
+ * its successor.
+ */
+const PROVIDER_TRUTH_PHASES = new Set([
+    "provider-accepted",
+    "turn-progress",
+    "turn-terminal"
+]);
+/**
+ * The (source, evidence) combinations each phase is allowed to carry. This is
+ * where "receipt/pane/PID/liveness remain non-acceptance evidence" is enforced
+ * structurally: only `provider-native-durable` may advance provider truth
+ * (acceptance/progress/terminal), so neither a transport/liveness signal nor a
+ * shape-only `adapter-mapped` observation can ever forge or terminalize a turn.
+ * `adapter-mapped` remains permissible only for the pre-acceptance
+ * session-started/ready phases, whose fold never advances Run truth.
+ */
+const PHASE_EVIDENCE_MATRIX = {
+    "host-process-created": { sources: ["controller"], evidence: ["controller"] },
+    "provider-session-started": {
+        sources: ["provider-native"],
+        evidence: ["adapter-mapped", "provider-native-durable"]
+    },
+    "provider-ready": {
+        sources: ["provider-native"],
+        evidence: ["adapter-mapped", "provider-native-durable"]
+    },
+    "prompt-pushed": { sources: ["transport"], evidence: ["transport"] },
+    "provider-accepted": {
+        sources: ["provider-native"],
+        evidence: ["provider-native-durable"]
+    },
+    "turn-progress": {
+        sources: ["provider-native"],
+        evidence: ["provider-native-durable"]
+    },
+    "turn-terminal": {
+        sources: ["provider-native"],
+        evidence: ["provider-native-durable"]
+    }
+};
+/**
+ * Builds a validated canonical event, failing closed if the phase, source,
+ * evidence, or identity fence are inconsistent. Callers (adapters, transport,
+ * the controller) must go through here so downstream folds can trust the shape.
+ */
+export function createCanonicalLifecycleEvent(input) {
+    const rule = PHASE_EVIDENCE_MATRIX[input.phase];
+    if (rule === undefined) {
+        throw new CanonicalLifecycleError(`Unknown canonical lifecycle phase: ${String(input.phase)}.`);
+    }
+    if (!rule.sources.includes(input.source)) {
+        throw new CanonicalLifecycleError(`Phase ${input.phase} rejects source ${input.source}; only ${rule.sources.join("/")} may prove it.`);
+    }
+    if (!rule.evidence.includes(input.evidence)) {
+        throw new CanonicalLifecycleError(`Phase ${input.phase} rejects evidence ${input.evidence}; only ${rule.evidence.join("/")} may prove it.`);
+    }
+    const fence = normalizeFence(input.fence);
+    if (RUN_SCOPED_PHASES.has(input.phase) && fence.runId === undefined) {
+        throw new CanonicalLifecycleError(`Phase ${input.phase} requires a runId fence.`);
+    }
+    // Provider-truth phases must carry the complete generation fence so a stale or
+    // wrong generation can never advance the Run.
+    if (PROVIDER_TRUTH_PHASES.has(input.phase)) {
+        if (fence.nativeSessionId === undefined) {
+            throw new CanonicalLifecycleError(`Phase ${input.phase} requires a nativeSessionId fence.`);
+        }
+        if (fence.launchId === undefined) {
+            throw new CanonicalLifecycleError(`Phase ${input.phase} requires a launchId fence.`);
+        }
+    }
+    if (input.phase === "prompt-pushed" && fence.receiptId === undefined) {
+        throw new CanonicalLifecycleError("A prompt-pushed event requires a transport receiptId.");
+    }
+    if (input.phase === "provider-accepted" && fence.receiptId === undefined) {
+        throw new CanonicalLifecycleError("A provider-accepted event requires the transport receiptId it accepts.");
+    }
+    // Readiness must be explicit: provider-ready requires an explicit boolean and
+    // the provider-native variant that justifies it; every other phase forbids
+    // both so an ambiguous readiness claim can never be silently coerced.
+    if (input.phase === "provider-ready") {
+        if (typeof input.preInputReady !== "boolean") {
+            throw new CanonicalLifecycleError("A provider-ready event requires an explicit boolean preInputReady.");
+        }
+        if (input.readinessVariant !== undefined) {
+            requireEventText(input.readinessVariant, "readinessVariant");
+        }
+    }
+    else {
+        if (input.preInputReady !== undefined) {
+            throw new CanonicalLifecycleError("preInputReady is only meaningful on provider-ready.");
+        }
+        if (input.readinessVariant !== undefined) {
+            throw new CanonicalLifecycleError("readinessVariant is only meaningful on provider-ready.");
+        }
+    }
+    if (input.sequence !== undefined && !Number.isSafeInteger(input.sequence)) {
+        throw new CanonicalLifecycleError("sequence must be a safe integer.");
+    }
+    return Object.freeze({
+        phase: input.phase,
+        source: input.source,
+        evidence: input.evidence,
+        fence,
+        ...(input.preInputReady === undefined ? {} : { preInputReady: input.preInputReady }),
+        ...(input.readinessVariant === undefined ? {} : { readinessVariant: input.readinessVariant }),
+        ...(input.sequence === undefined ? {} : { sequence: input.sequence }),
+        ...(input.summary === undefined ? {} : { summary: input.summary })
+    });
+}
+/**
+ * The provider-neutral decision. Given a validated canonical event and the
+ * consumer's current expectation, it returns what should happen — idempotent for
+ * duplicates, deferred for not-yet-applicable facts, obsolete for stale/wrong
+ * generation, fail-closed for contract violations. It reads only phase / source
+ * / evidence / identity, never the adapter name, and mutates nothing.
+ */
+export function foldCanonicalLifecycleEvent(event, expectation) {
+    const identity = matchesFence(expectation, event);
+    if (identity !== null) {
+        return { outcome: "obsolete", reason: identity };
+    }
+    switch (event.phase) {
+        case "host-process-created":
+            return { outcome: "mark-host-created" };
+        case "provider-session-started": {
+            if (expectation.terminal)
+                return { outcome: "obsolete", reason: "session-started-after-terminal" };
+            // Idempotent on replay: a duplicate hook for an already-applied
+            // session-started fact is a no-op, read from existing durable state.
+            if (expectation.sessionStarted) {
+                return { outcome: "idempotent", reason: "already-session-started" };
+            }
+            // Discovery may bind a previously-unknown native id, but only under the
+            // exact launch fence and only when none is bound yet.
+            if (expectation.boundNativeSessionId === undefined
+                && event.fence.nativeSessionId !== undefined
+                && event.fence.launchId !== undefined
+                && event.fence.launchId === expectation.fence.launchId) {
+                return { outcome: "bind-native-session", nativeSessionId: event.fence.nativeSessionId };
+            }
+            return { outcome: "mark-session-started" };
+        }
+        case "provider-ready": {
+            if (expectation.terminal)
+                return { outcome: "obsolete", reason: "ready-after-terminal" };
+            // Idempotent on replay against existing durable ready state.
+            if (expectation.ready)
+                return { outcome: "idempotent", reason: "already-ready" };
+            // preInputReady is guaranteed an explicit boolean by construction.
+            return { outcome: "mark-ready", preInputReady: event.preInputReady === true };
+        }
+        case "prompt-pushed":
+            if (expectation.terminal)
+                return { outcome: "obsolete", reason: "push-after-terminal" };
+            if (expectation.accepted)
+                return { outcome: "obsolete", reason: "push-after-accepted" };
+            // Exactly one push: a repeat for an already-pushed Run is a no-op, never a
+            // second Enter.
+            if (expectation.pushed)
+                return { outcome: "idempotent", reason: "already-pushed" };
+            return { outcome: "mark-pushed" };
+        case "provider-accepted":
+            // Only an identity-matched durable native event can move accepted/delivered,
+            // and only after the independently committed transport receipt. Provider
+            // acceptance and transport acknowledgement are deliberately separate
+            // evidence layers: neither may repair or infer the other.
+            if (!expectation.pushed)
+                return { outcome: "fail-closed", reason: "accept-without-push" };
+            if (expectation.terminal)
+                return { outcome: "obsolete", reason: "accept-after-terminal" };
+            if (expectation.accepted)
+                return { outcome: "idempotent", reason: "already-accepted" };
+            return { outcome: "advance-accepted" };
+        case "turn-progress":
+            // Progress only exists inside an accepted turn; a completion never promotes
+            // acceptance, so progress before acceptance is a contract violation.
+            if (!expectation.accepted)
+                return { outcome: "fail-closed", reason: "progress-without-accept" };
+            if (expectation.terminal)
+                return { outcome: "obsolete", reason: "progress-after-terminal" };
+            return { outcome: "advance-progress" };
+        case "turn-terminal":
+            if (expectation.terminal)
+                return { outcome: "idempotent", reason: "already-terminal" };
+            if (expectation.accepted)
+                return { outcome: "advance-terminal" };
+            // A terminal for a pushed-but-unaccepted Run must NOT promote acceptance;
+            // hold the immutable fact until (or unless) acceptance folds first.
+            if (expectation.pushed)
+                return { outcome: "deferred", reason: "terminal-before-accept" };
+            return { outcome: "fail-closed", reason: "terminal-without-push" };
+        default:
+            return { outcome: "fail-closed", reason: `unhandled-phase:${String(event.phase)}` };
+    }
+}
+/**
+ * Returns null when the event belongs to the expected generation/Run, or a
+ * mismatch reason otherwise. Owner/adapter and run-scoped runId are always
+ * compared. Provider-truth phases (acceptance/progress/terminal) require the
+ * COMPLETE generation fence — nativeSessionId, launchId, and (for acceptance)
+ * receiptId must be present and equal, so a missing or wrong generation/receipt
+ * fails closed rather than advancing a Run or its successor. Where a native id
+ * is already bound, every run-scoped fact must match it.
+ */
+function matchesFence(expectation, event) {
+    const expected = expectation.fence;
+    const actual = event.fence;
+    const phase = event.phase;
+    if (expected.taskId !== actual.taskId)
+        return "fence-mismatch:taskId";
+    if (expected.roleName !== actual.roleName)
+        return "fence-mismatch:roleName";
+    if (expected.agentId !== actual.agentId)
+        return "fence-mismatch:agentId";
+    if (expected.adapterId !== actual.adapterId)
+        return "fence-mismatch:adapterId";
+    // Run-scoped phases must name the exact expected Run.
+    if (RUN_SCOPED_PHASES.has(phase)) {
+        if (expected.runId === undefined)
+            return "fence-mismatch:expected-run-missing";
+        if (actual.runId !== expected.runId)
+            return "fence-mismatch:runId";
+    }
+    else if (actual.runId !== undefined
+        && expected.runId !== undefined
+        && actual.runId !== expected.runId) {
+        return "fence-mismatch:runId";
+    }
+    // Provider-truth phases require the complete, equal generation fence. A
+    // provider-accepted event additionally must carry the exact receipt it accepts.
+    if (PROVIDER_TRUTH_PHASES.has(phase)) {
+        if (actual.nativeSessionId === undefined)
+            return "fence-mismatch:missing-native-session";
+        if (actual.launchId === undefined)
+            return "fence-mismatch:missing-launch";
+        if (expected.launchId !== undefined && actual.launchId !== expected.launchId) {
+            return "fence-mismatch:launchId";
+        }
+        // Once a native id is bound, every provider-truth fact must match it. Before
+        // binding (discovery still open) the expected fence's own nativeSessionId, if
+        // present, still constrains it.
+        const boundNative = expectation.boundNativeSessionId ?? expected.nativeSessionId;
+        if (boundNative !== undefined && actual.nativeSessionId !== boundNative) {
+            return "fence-mismatch:nativeSessionId";
+        }
+        if (phase === "provider-accepted") {
+            if (actual.receiptId === undefined)
+                return "fence-mismatch:missing-receipt";
+            if (expected.receiptId !== undefined && actual.receiptId !== expected.receiptId) {
+                return "fence-mismatch:receiptId";
+            }
+        }
+        return null;
+    }
+    // Pre-acceptance phases (host/session/ready and the transport push): compare
+    // the generation dimensions that are present on both sides. A push must match
+    // its expected receipt when both name one.
+    if (actual.nativeSessionId !== undefined
+        && expectation.boundNativeSessionId !== undefined
+        && actual.nativeSessionId !== expectation.boundNativeSessionId) {
+        return "fence-mismatch:nativeSessionId";
+    }
+    if (actual.nativeSessionId !== undefined
+        && expected.nativeSessionId !== undefined
+        && actual.nativeSessionId !== expected.nativeSessionId) {
+        return "fence-mismatch:nativeSessionId";
+    }
+    if (actual.launchId !== undefined
+        && expected.launchId !== undefined
+        && actual.launchId !== expected.launchId) {
+        return "fence-mismatch:launchId";
+    }
+    if (phase === "prompt-pushed"
+        && actual.receiptId !== undefined
+        && expected.receiptId !== undefined
+        && actual.receiptId !== expected.receiptId) {
+        return "fence-mismatch:receiptId";
+    }
+    return null;
+}
+function normalizeFence(fence) {
+    const taskId = requireFenceText(fence.taskId, "taskId");
+    const roleName = requireFenceText(fence.roleName, "roleName");
+    const agentId = requireFenceText(fence.agentId, "agentId");
+    if (fence.adapterId !== "codex" && fence.adapterId !== "claude") {
+        throw new CanonicalLifecycleError(`Unsupported adapter fence: ${String(fence.adapterId)}.`);
+    }
+    return Object.freeze({
+        taskId,
+        roleName,
+        agentId,
+        adapterId: fence.adapterId,
+        ...(fence.runId === undefined ? {} : { runId: requireFenceText(fence.runId, "runId") }),
+        ...(fence.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: requireFenceText(fence.nativeSessionId, "nativeSessionId") }),
+        ...(fence.launchId === undefined ? {} : { launchId: requireFenceText(fence.launchId, "launchId") }),
+        ...(fence.receiptId === undefined ? {} : { receiptId: requireFenceText(fence.receiptId, "receiptId") })
+    });
+}
+function requireFenceText(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new CanonicalLifecycleError(`Fence ${label} is invalid.`);
+    }
+    const text = value.trim();
+    if (text.length === 0 || text.length > 1_024) {
+        throw new CanonicalLifecycleError(`Fence ${label} is invalid.`);
+    }
+    return text;
+}
+function requireEventText(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new CanonicalLifecycleError(`${label} is invalid.`);
+    }
+    const text = value.trim();
+    if (text.length === 0 || text.length > 1_024) {
+        throw new CanonicalLifecycleError(`${label} is invalid.`);
+    }
+    return text;
+}