@zq-silk/yui 0.15.8 → 0.15.11

package/dist/message/inputControlResolution.js

@@ -0,0 +1,106 @@
+import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
+/**
+ * Turn statuses that mean a Turn record is present and not yet terminal. This is
+ * only "there is something here", not "it is safe to target": `submitting` is a
+ * call still in flight and `delivery-unknown` is an outbound whose acceptance was
+ * never proven. Both are separated from `accepted` below (decision-3 §3/§8) so an
+ * unconfirmed delivery is reported as DELIVERY_UNKNOWN, never silently steered or
+ * cancelled as if it were a clean active Turn.
+ */
+const PRESENT_TURN_STATUSES = new Set(["submitting", "accepted", "delivery-unknown"]);
+/**
+ * The scope-generic core. It takes an already-fetched Session set and the owner
+ * decoration for a resolved target, so Task and Global callers share the exact
+ * same capability, present-Turn, authority, and target-match logic.
+ *
+ * @param decorate Adds the owner-specific fields to a resolved target. For a
+ *   Task Role it attaches the taskId; for a Global Role it attaches nothing.
+ */
+function resolveInputControl(sessions, kind, expectedTarget, roleName) {
+    const active = sessions?.sessions[sessions.activeAgentId];
+    // Capability is read from the declared Driver of the current active Session,
+    // never hardcoded by Agent name (decision-3 §7). When there is no active
+    // Session at all there is also no current Turn to target.
+    if (sessions == null || active === undefined || active.status !== "active") {
+        return { outcome: "no-active-turn", code: "NO_ACTIVE_TURN",
+            detail: "No active native Session holds a current Turn for this Role." };
+    }
+    const capabilities = builtinAgentDriverRegistry().requireByAdapterId(active.adapterId).capabilities;
+    if (kind === "steer" && capabilities.input.steer !== "fenced") {
+        return { outcome: "unsupported", code: "STEER_UNSUPPORTED",
+            detail: `Agent plan '${active.adapterId}' cannot steer its current Turn; `
+                + "the input is saved for an explicit interrupt --then-message or a queue." };
+    }
+    if (kind === "interrupt" && capabilities.control.interruptDelivery !== "native") {
+        return { outcome: "unsupported", code: "INTERRUPT_UNSUPPORTED",
+            detail: `Agent plan '${active.adapterId}' has no native interrupt; Yui will not `
+                + "stop the owned process, kill, restart, or detach it." };
+    }
+    // A Global Role now carries the same optional providerBinding as a Task Role;
+    // both read it the same way. Its absence is "no current Turn", never an error.
+    const binding = "providerBinding" in sessions ? sessions.providerBinding ?? null : null;
+    const turn = binding?.run ?? null;
+    if (binding === null || turn === null || !PRESENT_TURN_STATUSES.has(turn.status)) {
+        return { outcome: "no-active-turn", code: "NO_ACTIVE_TURN",
+            detail: "The Provider is not running a Turn now; there is nothing to steer or interrupt." };
+    }
+    // A human writer fence (an interactive takeover) owns the Turn; the Controller
+    // must not steer or cancel across it.
+    if (binding.authority.owner !== "controller") {
+        return { outcome: "target-changed", code: "TARGET_CHANGED",
+            detail: `Provider authority is ${binding.authority.owner}-held; release the takeover before a managed control.` };
+    }
+    const observedId = turn.nativeTurnId ?? turn.attemptId;
+    if (expectedTarget !== observedId
+        && !(turn.nativeTurnId !== undefined && expectedTarget === turn.attemptId)) {
+        return { outcome: "target-changed", code: "TARGET_CHANGED",
+            detail: `The current Turn is ${observedId}, not ${expectedTarget}; re-read the Session before retrying.` };
+    }
+    // The right Turn is confirmed; now report its own delivery state. decision-3
+    // §3/§8, message-3 #7: an original Turn still in flight (`submitting`) or whose
+    // acceptance was never proven (`delivery-unknown`) is not a safe target.
+    // Steering it would push a second input onto an unconfirmed one; cancelling it
+    // would guess a stop against an attempt that may not have landed. Report
+    // DELIVERY_UNKNOWN so the caller confirms the original attempt first — never a
+    // silent downgrade to another action (§10).
+    if (turn.status !== "accepted") {
+        return { outcome: "delivery-unknown", code: "DELIVERY_UNKNOWN",
+            detail: `The current Turn's own delivery is ${turn.status}; confirm the original attempt `
+                + "before steering or interrupting. Do not reissue under a new requestId or a different action." };
+    }
+    if (kind === "steer" && turn.nativeTurnId === undefined) {
+        return { outcome: "delivery-unknown", code: "DELIVERY_UNKNOWN",
+            detail: "The Provider has not supplied an exact native Turn id for steering." };
+    }
+    return { outcome: "ready", target: {
+            roleName, agentId: active.agentId, adapterId: active.adapterId,
+            nativeSessionId: active.nativeSessionId,
+            ...(turn.nativeTurnId === undefined ? {} : { nativeTurnId: turn.nativeTurnId }),
+            attemptId: turn.attemptId,
+            authority: { epoch: binding.authority.epoch, owner: "controller",
+                holderId: binding.authority.holderId ?? "controller" }
+        } };
+}
+/**
+ * Resolve a live steer/interrupt against a Task Role's current native Turn.
+ *
+ * @param expectedTarget The Leader's exact expectation for the current Turn,
+ *   as observed (its nativeTurnId, or its attemptId when no native id exists).
+ *   A steer/interrupt that no longer matches is TARGET_CHANGED, never retargeted.
+ */
+export function resolveTaskInputControl(store, taskId, roleName, kind, expectedTarget) {
+    const resolution = resolveInputControl(store.getTaskRoleSessionSet(taskId, roleName), kind, expectedTarget, roleName);
+    // A Task target carries its taskId so the live edge addresses the exact Host.
+    return resolution.outcome === "ready"
+        ? { outcome: "ready", target: { taskId, ...resolution.target } }
+        : resolution;
+}
+/**
+ * Resolve a live steer/interrupt against a Global Role's current native Turn
+ * (decision-3 §6/§9). Identical contract to the Task resolver, reading the
+ * Global Role's own Session set; the resolved target carries no taskId because a
+ * Global Role has no owning Task and never fabricates one.
+ */
+export function resolveGlobalInputControl(store, roleName, kind, expectedTarget) {
+    return resolveInputControl(store.getGlobalRoleSessionSet(roleName), kind, expectedTarget, roleName);
+}

package/dist/message/message.js

@@ -1,5 +1,26 @@
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
 export const TASK_MESSAGE_KINDS = ["user", "operator", "role-result", "system"];
+/**
+ * How a user/operator submission asks its Task to react (task-32 Requirement A).
+ *
+ * - `record`: save only. No Leader wake, no planning, no activation.
+ * - `discuss`: save and route to planning (the default when a submission omits
+ *   an intent, so an old client keeps its existing Leader-waking behaviour).
+ * - `develop`: save the requirement and its activation intent; an unplanned
+ *   Draft records an activation request and queues only activation processing.
+ *
+ * The intent is never inferred from body text and is only meaningful on a
+ * user/operator submission: a role-result or system Message can never carry one,
+ * so an internal Agent report cannot acquire develop authority.
+ */
+export const TASK_SUBMISSION_INTENTS = ["record", "discuss", "develop"];
+/** The two durable input actions an authorized caller can choose (decision-3).
+ * `interrupt` is a control operation, not a persisted Message action, so it is
+ * absent here. */
+export const TASK_MESSAGE_INPUT_ACTIONS = ["queue", "steer"];
+/** The recordable outcomes of a steer's one live control attempt (message-5 gap
+ * D). `not-submitted` is not here: it is the absence of a record, not a value. */
+export const TASK_MESSAGE_INPUT_CONTROL_OUTCOMES = ["pending", "accepted", "rejected", "delivery-unknown"];
 export function createTaskMessage(id, taskId, body, kind, author, now, context = {}) {
     validateKindAndAuthor(kind, author);
     const message = {
@@ -12,6 +33,44 @@ export function createTaskMessage(id, taskId, body, kind, author, now, context =
         ...(context.wakePolicy === undefined
             ? {}
             : { wakePolicy: context.wakePolicy }),
+        ...(context.intent === undefined
+            ? {}
+            : { intent: context.intent }),
+        ...(context.submissionKey === undefined
+            ? {}
+            : { submissionKey: requireText(context.submissionKey, "Message submission key") }),
+        ...(context.inputControl === undefined
+            ? {}
+            : { inputControl: {
+                    action: context.inputControl.action,
+                    requestId: requireSafeIdentity(context.inputControl.requestId, "Message input requestId"),
+                    ...(context.inputControl.expectedTarget === undefined
+                        ? {} : { expectedTarget: requireText(context.inputControl.expectedTarget, "Message input expectedTarget") })
+                } }),
+        ...(context.interruptThen === undefined
+            ? {}
+            : { interruptThen: {
+                    requestId: requireSafeIdentity(context.interruptThen.requestId, "Message interrupt requestId"),
+                    targetAttemptId: requireText(context.interruptThen.targetAttemptId, "Message interrupt targetAttemptId"),
+                    targetRoleName: context.interruptThen.targetRoleName,
+                    targetAgentId: context.interruptThen.targetAgentId,
+                    targetAdapterId: context.interruptThen.targetAdapterId,
+                    targetNativeSessionId: context.interruptThen.targetNativeSessionId,
+                    targetAuthorityEpoch: context.interruptThen.targetAuthorityEpoch,
+                    targetAuthorityHolderId: context.interruptThen.targetAuthorityHolderId,
+                    ...(context.interruptThen.targetNativeTurnId === undefined ? {} : {
+                        targetNativeTurnId: context.interruptThen.targetNativeTurnId
+                    }),
+                    ...(context.interruptThen.notDeliveredReason === undefined ? {} : {
+                        notDeliveredReason: context.interruptThen.notDeliveredReason
+                    }),
+                    ...(context.interruptThen.targetRunId === undefined
+                        ? {} : { targetRunId: context.interruptThen.targetRunId }),
+                    ...(context.interruptThen.reusedInput === undefined ? {} : { reusedInput: {
+                            action: context.interruptThen.reusedInput.action,
+                            requestId: requireSafeIdentity(context.interruptThen.reusedInput.requestId, "Reused input requestId")
+                        } })
+                } }),
         ...(context.runId === undefined
             ? {}
             : { runId: requireSafeIdentity(context.runId, "Message AgentRun id") }),
@@ -29,6 +88,69 @@ export function createTaskMessage(id, taskId, body, kind, author, now, context =
 export function taskMessageAuthorLabel(author) {
     return author.type === "role" ? author.roleName : author.type;
 }
+/**
+ * The four visible states a later reader distinguishes for a steer input
+ * (message-5 gap D): the absence of any live attempt is `not-submitted`, and a
+ * recorded attempt reports its own observed outcome. A non-steer Message has no
+ * control state and returns `undefined`. This is the single reader other CLI
+ * invocations, the Web surface, and the Leader's Context read all use, so no
+ * consumer reconstructs the state from raw fields.
+ */
+export function taskMessageInputControlState(message) {
+    const wasSteer = message.inputControl?.action === "steer"
+        || message.interruptThen?.reusedInput?.action === "steer";
+    if (!wasSteer)
+        return undefined;
+    return message.control?.outcome ?? "not-submitted";
+}
+/**
+ * Record the observed disposition of a steer's one live control attempt as an
+ * independent, idempotent, monotonic control op (decision-3 §3/§8, message-5 gap
+ * D). The op is keyed by the exact `receiptId` fence and the steer's own
+ * `requestId`; a record naming a different Message's receipt or a different
+ * input identity is refused, so an outcome can never be folded onto the wrong
+ * Message or fork a second op. Terminals never rewind to `pending` and never
+ * overwrite a different terminal — a repeated or out-of-order live/Host record
+ * is absorbed, never a conflicting second write. The frozen business
+ * {@link TaskMessageInputControl} intent is left untouched.
+ */
+export function recordTaskMessageControlOutcome(message, record) {
+    const inputRequestId = message.inputControl?.requestId ?? message.interruptThen?.reusedInput?.requestId;
+    const wasSteer = message.inputControl?.action === "steer"
+        || message.interruptThen?.reusedInput?.action === "steer";
+    if (!wasSteer || inputRequestId === undefined) {
+        throw new Error("Only a steer input Message records a live control outcome.");
+    }
+    if (record.requestId !== inputRequestId) {
+        throw new Error("Control outcome requestId must match the steer input identity.");
+    }
+    const existing = message.control;
+    if (existing !== undefined && existing.receiptId !== record.receiptId) {
+        throw new Error("Control outcome receiptId cannot name another control op.");
+    }
+    // Monotonic freeze (decision-3 §8, message-5 gap D). Once any terminal is
+    // proven it is final: a later `pending` never rewinds it and a different
+    // terminal never overwrites it — the first proven terminal wins. While still
+    // `pending`, an identical repeat is idempotent. Each frozen/absorbed case
+    // returns the Message unchanged so a fold can persist without a second write.
+    if (existing !== undefined) {
+        if (existing.outcome === "accepted" || existing.outcome === "rejected")
+            return message;
+        if (record.outcome === "pending" || record.outcome === existing.outcome)
+            return message;
+    }
+    const updated = {
+        ...message,
+        control: {
+            requestId: requireSafeIdentity(record.requestId, "Message control requestId"),
+            receiptId: requireText(record.receiptId, "Message control receiptId"),
+            outcome: record.outcome,
+            observedAt: record.observedAt.toISOString()
+        }
+    };
+    validateTaskMessage(updated);
+    return updated;
+}
 /** A role-result reference never duplicates the execution's report body. */
 export function expandTaskMessageResult(message, getRun) {
     if (message.resultRef === undefined)
@@ -57,6 +179,24 @@ export function updateDraftTaskMessage(message, update) {
     validateTaskMessage(updated);
     return updated;
 }
+/**
+ * Attach the §2.3 receipt a keyed submission earned, in the same transaction that
+ * saved and routed the Message. The receipt is a write-once fact: it is only set
+ * on a keyed Message that has none yet, so a replay (which never re-routes) can
+ * never overwrite the disposition the original submission recorded.
+ */
+export function withSubmissionReceipt(message, receipt) {
+    validateTaskMessage(message);
+    if (message.submissionKey === undefined) {
+        throw new Error(`A submission receipt requires a submission key: ${message.id}.`);
+    }
+    if (message.submissionReceipt !== undefined) {
+        throw new Error(`Submission receipt is already recorded: ${message.id}.`);
+    }
+    const updated = { ...message, submissionReceipt: receipt };
+    validateTaskMessage(updated);
+    return updated;
+}
 export function validateTaskMessage(message) {
     if (message.schemaVersion !== 3)
         throw new Error("Task Message must use schemaVersion 3.");
@@ -74,6 +214,90 @@ export function validateTaskMessage(message) {
         && message.kind !== "operator") {
         throw new Error("Message wakePolicy is only valid for user/operator messages.");
     }
+    if (message.intent !== undefined
+        && !TASK_SUBMISSION_INTENTS.includes(message.intent)) {
+        throw new Error(`Message intent is invalid: ${String(message.intent)}.`);
+    }
+    if (message.intent !== undefined
+        && message.kind !== "user"
+        && message.kind !== "operator") {
+        throw new Error("Message intent is only valid for user/operator messages.");
+    }
+    if (message.submissionKey !== undefined) {
+        requireText(message.submissionKey, "Message submission key");
+        if (message.kind !== "user" && message.kind !== "operator") {
+            throw new Error("Message submission key is only valid for user/operator messages.");
+        }
+    }
+    if (message.submissionReceipt !== undefined && message.submissionKey === undefined) {
+        throw new Error("Message submission receipt requires a submission key.");
+    }
+    if (message.inputControl !== undefined) {
+        if (!TASK_MESSAGE_INPUT_ACTIONS.includes(message.inputControl.action)) {
+            throw new Error(`Message input action is invalid: ${String(message.inputControl.action)}.`);
+        }
+        requireSafeIdentity(message.inputControl.requestId, "Message input requestId");
+        if (message.inputControl.expectedTarget !== undefined) {
+            requireText(message.inputControl.expectedTarget, "Message input expectedTarget");
+            if (message.inputControl.action !== "steer") {
+                throw new Error("Only a steer input binds an expectedTarget.");
+            }
+        }
+    }
+    if (message.interruptThen !== undefined) {
+        requireSafeIdentity(message.interruptThen.requestId, "Message interrupt requestId");
+        requireText(message.interruptThen.targetAttemptId, "Message interrupt targetAttemptId");
+        requireSafeIdentity(message.interruptThen.targetRoleName, "Message interrupt target Role");
+        requireSafeIdentity(message.interruptThen.targetAgentId, "Message interrupt target Agent");
+        requireSafeIdentity(message.interruptThen.targetAdapterId, "Message interrupt target Adapter");
+        requireText(message.interruptThen.targetNativeSessionId, "Message interrupt target Session");
+        requireText(message.interruptThen.targetAuthorityHolderId, "Message interrupt authority holder");
+        if (message.interruptThen.notDeliveredReason !== undefined) {
+            requireText(message.interruptThen.notDeliveredReason, "Message interrupt nondelivery reason");
+        }
+        if (!Number.isSafeInteger(message.interruptThen.targetAuthorityEpoch)
+            || message.interruptThen.targetAuthorityEpoch < 1)
+            throw new Error("Invalid interrupt authority epoch.");
+        if (message.interruptThen.targetRunId !== undefined) {
+            validateTaskRecordReference({ taskId: message.taskId, localId: message.interruptThen.targetRunId }, "run");
+        }
+        if (message.interruptThen.reusedInput !== undefined) {
+            if (!TASK_MESSAGE_INPUT_ACTIONS.includes(message.interruptThen.reusedInput.action)) {
+                throw new Error(`Reused input action is invalid: ${String(message.interruptThen.reusedInput.action)}.`);
+            }
+            requireSafeIdentity(message.interruptThen.reusedInput.requestId, "Reused input requestId");
+        }
+        // A then-handoff is an explicit deliverable Message, never an auto-queued
+        // steer: the two intents are mutually exclusive by construction. The prior
+        // steer identity, when one existed, is preserved as reusedInput provenance
+        // rather than left live on inputControl.
+        if (message.inputControl?.action === "steer") {
+            throw new Error("An interrupt-then handoff cannot also be a steer input.");
+        }
+    }
+    if (message.control !== undefined) {
+        requireSafeIdentity(message.control.requestId, "Message control requestId");
+        requireText(message.control.receiptId, "Message control receiptId");
+        if (!TASK_MESSAGE_INPUT_CONTROL_OUTCOMES.includes(message.control.outcome)) {
+            throw new Error(`Message control outcome is invalid: ${String(message.control.outcome)}.`);
+        }
+        if (typeof message.control.observedAt !== "string" || Number.isNaN(Date.parse(message.control.observedAt))) {
+            throw new Error("Message control observedAt is invalid.");
+        }
+        // A recorded control outcome is the disposition of a live steer attempt; it
+        // only exists for a steer input, or for the reused-steer provenance a
+        // handoff preserved. It is never fabricated on a plain queue or a Message
+        // that never carried a steer (decision-3 §3, message-5 gap D).
+        const inputRequestId = message.inputControl?.requestId ?? message.interruptThen?.reusedInput?.requestId;
+        const wasSteer = message.inputControl?.action === "steer"
+            || message.interruptThen?.reusedInput?.action === "steer";
+        if (!wasSteer || inputRequestId === undefined) {
+            throw new Error("Only a steer input Message records a live control outcome.");
+        }
+        if (message.control.requestId !== inputRequestId) {
+            throw new Error("Message control requestId must match the steer input identity.");
+        }
+    }
     if (message.runId !== undefined)
         requireSafeIdentity(message.runId, "Message AgentRun id");
     if (message.recipient !== undefined) {
@@ -130,6 +354,205 @@ export function validateTaskMessage(message) {
         throw new Error("Message createdAt is invalid.");
     }
 }
+/**
+ * The author kinds a Global Role input can carry. A Global Role has no Task
+ * Assignment, so a `role-result` (which references a Task AgentRun) is not one
+ * of them; user/operator/system inputs are (decision-3 §9/§11).
+ */
+export const GLOBAL_ROLE_MESSAGE_KINDS = ["user", "operator", "system", "agent"];
+export function createGlobalRoleMessage(id, roleName, body, kind, author, now, context = {}) {
+    validateGlobalKindAndAuthor(kind, author);
+    const message = {
+        schemaVersion: 1,
+        id: validateGlobalRoleMessageId(id),
+        roleName: requireSafeIdentity(roleName, "Global message Role name"),
+        kind,
+        author: { type: author.type },
+        body: requireBody(body),
+        ...(context.inputControl === undefined
+            ? {}
+            : { inputControl: {
+                    action: context.inputControl.action,
+                    requestId: requireSafeIdentity(context.inputControl.requestId, "Message input requestId"),
+                    ...(context.inputControl.expectedTarget === undefined
+                        ? {} : { expectedTarget: requireText(context.inputControl.expectedTarget, "Message input expectedTarget") })
+                } }),
+        createdAt: now.toISOString()
+    };
+    validateGlobalRoleMessage(message);
+    return message;
+}
+export function validateGlobalRoleMessage(message) {
+    if (message.schemaVersion !== 1)
+        throw new Error("Global Role Message must use schemaVersion 1.");
+    validateGlobalRoleMessageId(message.id);
+    requireSafeIdentity(message.roleName, "Global message Role name");
+    requireBody(message.body);
+    validateGlobalKindAndAuthor(message.kind, message.author);
+    if (message.deliveryTarget !== undefined) {
+        requireText(message.deliveryTarget.agentId, "Global input Agent");
+        requireText(message.deliveryTarget.nativeSessionId, "Global input Session");
+    }
+    if (message.control !== undefined) {
+        requireSafeIdentity(message.control.requestId, "Global input requestId");
+        requireText(message.control.receiptId, "Global input receiptId");
+        if (!TASK_MESSAGE_INPUT_CONTROL_OUTCOMES.includes(message.control.outcome)
+            || !Number.isFinite(Date.parse(message.control.observedAt)))
+            throw new Error("Global input disposition is invalid.");
+    }
+    if (message.inputControl !== undefined) {
+        if (!TASK_MESSAGE_INPUT_ACTIONS.includes(message.inputControl.action)) {
+            throw new Error(`Message input action is invalid: ${String(message.inputControl.action)}.`);
+        }
+        requireSafeIdentity(message.inputControl.requestId, "Message input requestId");
+        if (message.inputControl.expectedTarget !== undefined) {
+            requireText(message.inputControl.expectedTarget, "Message input expectedTarget");
+            if (message.inputControl.action !== "steer") {
+                throw new Error("Only a steer input binds an expectedTarget.");
+            }
+        }
+    }
+    if (message.delivery !== undefined) {
+        if (message.delivery.via !== "provider" && message.delivery.via !== "transport") {
+            throw new Error(`Global message delivery via is invalid: ${String(message.delivery.via)}.`);
+        }
+        if (typeof message.delivery.deliveredAt !== "string"
+            || Number.isNaN(Date.parse(message.delivery.deliveredAt))) {
+            throw new Error("Global message delivery deliveredAt is invalid.");
+        }
+        // Receipt evidence is shared by queue, explicit then and native steer.
+        if (message.inputControl === undefined && message.interruptThen === undefined) {
+            throw new Error("Only a durable Global input records Provider delivery.");
+        }
+    }
+    if (message.interruptThen !== undefined) {
+        requireSafeIdentity(message.interruptThen.requestId, "Global message interrupt requestId");
+        requireText(message.interruptThen.targetAttemptId, "Global message interrupt targetAttemptId");
+        requireText(message.interruptThen.targetNativeSessionId, "Global interrupt target Session");
+        requireText(message.interruptThen.targetAgentId, "Global interrupt target Agent");
+        requireText(message.interruptThen.targetAuthorityHolderId, "Global interrupt writer");
+        if (!Number.isSafeInteger(message.interruptThen.targetAuthorityEpoch)
+            || message.interruptThen.targetAuthorityEpoch < 1)
+            throw new Error("Global interrupt epoch is invalid.");
+        if (message.interruptThen.targetNativeTurnId !== undefined) {
+            requireText(message.interruptThen.targetNativeTurnId, "Global message interrupt targetNativeTurnId");
+        }
+        if (message.interruptThen.reusedInput !== undefined) {
+            if (!TASK_MESSAGE_INPUT_ACTIONS.includes(message.interruptThen.reusedInput.action)) {
+                throw new Error(`Reused input action is invalid: ${String(message.interruptThen.reusedInput.action)}.`);
+            }
+            requireSafeIdentity(message.interruptThen.reusedInput.requestId, "Reused input requestId");
+        }
+    }
+    if (message.notDelivered !== undefined) {
+        requireText(message.notDelivered.reason, "Global message nondelivery reason");
+        if (typeof message.notDelivered.at !== "string"
+            || Number.isNaN(Date.parse(message.notDelivered.at))) {
+            throw new Error("Global message nondelivery timestamp is invalid.");
+        }
+        // A delivered Message is a settled positive fact; a not-delivered fact is its
+        // visible negative twin. The two are mutually exclusive on one Message.
+        if (message.delivery !== undefined) {
+            throw new Error("A Global message cannot be both delivered and not-delivered.");
+        }
+        if (message.inputControl?.action !== "queue" && message.interruptThen === undefined) {
+            throw new Error("Only a queued or interrupt-then Global message records a nondelivery.");
+        }
+    }
+    if (typeof message.createdAt !== "string" || Number.isNaN(Date.parse(message.createdAt))) {
+        throw new Error("Message createdAt is invalid.");
+    }
+}
+/** A Global message local id is `global-message-<n>`; it carries no Task id. */
+export function validateGlobalRoleMessageId(localId) {
+    const normalized = requireSafeIdentity(localId, "Global message id");
+    if (!/^global-message-[1-9]\d*$/.test(normalized)) {
+        throw new Error(`Global message id is invalid: ${localId}.`);
+    }
+    return normalized;
+}
+/**
+ * Return a copy of a queued Global Message marked delivered at its next legal
+ * opportunity — the Role's own authorized Context read (decision-3 §9). Only a
+ * `queue` input may be consumed this way and only once: a Message that already
+ * carries a delivery is returned unchanged, so a repeated self-read is
+ * idempotent and never re-delivers. A steer/interrupt Message, which targets the
+ * exact current Turn rather than a queued next opportunity, is never delivered
+ * here.
+ */
+export function markGlobalRoleMessageDelivered(message, now, via = "provider") {
+    if (message.inputControl === undefined && message.interruptThen === undefined) {
+        throw new Error("Only a durable Global input is delivered by a Provider.");
+    }
+    if (message.delivery?.via === "provider" || message.delivery?.via === via)
+        return message;
+    const delivered = {
+        ...message,
+        ...(message.control === undefined ? {} : { control: {
+                ...message.control, outcome: via === "provider" ? "accepted" : "pending", observedAt: now.toISOString()
+            } }),
+        delivery: { deliveredAt: now.toISOString(), via }
+    };
+    validateGlobalRoleMessage(delivered);
+    return delivered;
+}
+/**
+ * Return a copy of an already-saved durable Global Message that claims the single
+ * interrupt-then continuation of an exact interrupted native Turn (decision-3
+ * §4). The original input identity, when the Message carried one, is preserved as
+ * `reusedInput` provenance rather than erased, so a replay of that requestId
+ * keeps resolving to this same Message and never creates a second input.
+ */
+export function claimGlobalRoleMessageInterruptThen(message, claim) {
+    const { inputControl, notDelivered: _priorNondelivery, ...rest } = message;
+    const claimed = {
+        ...rest,
+        interruptThen: {
+            requestId: requireSafeIdentity(claim.requestId, "Global message interrupt requestId"),
+            targetAttemptId: requireText(claim.targetAttemptId, "Global message interrupt targetAttemptId"),
+            targetNativeSessionId: claim.targetNativeSessionId,
+            targetAgentId: claim.targetAgentId,
+            targetAuthorityEpoch: claim.targetAuthorityEpoch,
+            targetAuthorityHolderId: claim.targetAuthorityHolderId,
+            ...(claim.targetNativeTurnId === undefined
+                ? {}
+                : { targetNativeTurnId: requireText(claim.targetNativeTurnId, "Global message interrupt targetNativeTurnId") }),
+            ...(inputControl === undefined ? {} : { reusedInput: inputControl })
+        }
+    };
+    validateGlobalRoleMessage(claimed);
+    return claimed;
+}
+/**
+ * Return a copy of a durable Global Message marked visibly not-delivered
+ * (decision-3 §5/§10), the Global twin of the Task {@link markNotDelivered}. An
+ * ordinary queue entry or a claimed interrupt-then handoff whose target can never
+ * prove a safe boundary fails here and stops holding the Role's pending set,
+ * rather than silently wedging it. It is idempotent for the same reason — a
+ * Message already carrying this exact reason is returned unchanged — and a
+ * delivered Message is never overwritten with a nondelivery.
+ */
+export function markGlobalRoleMessageNotDelivered(message, reason, now) {
+    if (message.delivery !== undefined) {
+        throw new Error("A delivered Global message cannot be marked not-delivered.");
+    }
+    if (message.notDelivered?.reason === reason)
+        return message;
+    const marked = {
+        ...message,
+        notDelivered: { reason: requireText(reason, "Global message nondelivery reason"), at: now.toISOString() }
+    };
+    validateGlobalRoleMessage(marked);
+    return marked;
+}
+function validateGlobalKindAndAuthor(kind, author) {
+    if (!GLOBAL_ROLE_MESSAGE_KINDS.includes(kind)) {
+        throw new Error(`Global message kind is invalid: ${String(kind)}.`);
+    }
+    if (author?.type !== kind) {
+        throw new Error(`Global message kind ${kind} requires a ${kind} author.`);
+    }
+}
 function validateKindAndAuthor(kind, author) {
     if (!TASK_MESSAGE_KINDS.includes(kind))
         throw new Error(`Message kind is invalid: ${String(kind)}.`);