@zq-silk/yui 0.13.9 → 0.14.0

package/dist/coordination/workMailbox.js

@@ -1,76 +1,178 @@
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
 const RECENT_DEDUPE_KEY_LIMIT = 256;
-function requireText(value, label) {
-    const normalized = value.trim();
-    if (normalized.length === 0) {
-        throw new Error(`${label} must not be empty`);
-    }
-    return normalized;
+export function createWorkMailbox(target) {
+    return {
+        schemaVersion: 5,
+        target: copyTarget(target),
+        nextSequence: 1,
+        processing: null,
+        pending: null,
+        recentDedupeKeys: []
+    };
 }
-function requireInteger(value, minimum, label) {
-    if (!Number.isInteger(value) || value < minimum) {
-        throw new Error(`${label} must be an integer greater than or equal to ${minimum}`);
+export function validateWorkMailbox(value) {
+    const mailbox = record(value, "WorkMailbox");
+    exact(mailbox, ["schemaVersion", "target", "nextSequence", "processing", "pending", "recentDedupeKeys"], "WorkMailbox");
+    if (mailbox.schemaVersion !== 5)
+        throw new Error("WorkMailbox must use schemaVersion 5");
+    const target = parseTarget(mailbox.target);
+    const nextSequence = requireInteger(mailbox.nextSequence, 1, "WorkMailbox nextSequence");
+    const processing = mailbox.processing === null ? null : parseProcessing(mailbox.processing);
+    const pending = mailbox.pending === null ? null : parseBatch(mailbox.pending, "WorkMailbox pending");
+    const recentDedupeKeys = requireStringArray(mailbox.recentDedupeKeys, "WorkMailbox recent dedupe keys");
+    if (recentDedupeKeys.length > RECENT_DEDUPE_KEY_LIMIT) {
+        throw new Error("WorkMailbox recent dedupe keys exceed the bounded limit");
     }
-    return value;
-}
-function record(value, label) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error(`${label} must be an object`);
+    const activeKeys = new Set();
+    for (const batch of [processing?.batch, pending]) {
+        if (batch === null || batch === undefined)
+            continue;
+        if (batch.toSequence >= nextSequence) {
+            throw new Error("WorkMailbox batch sequence must be lower than nextSequence");
+        }
+        for (const key of batch.dedupeKeys) {
+            if (activeKeys.has(key) || recentDedupeKeys.includes(key)) {
+                throw new Error("WorkMailbox batches contain an already-consumed dedupe key");
+            }
+            activeKeys.add(key);
+        }
     }
-    return value;
+    return {
+        schemaVersion: 5,
+        target,
+        nextSequence,
+        processing,
+        pending,
+        recentDedupeKeys
+    };
 }
-function exact(value, keys, label) {
-    const expected = new Set(keys);
-    const unknown = Object.keys(value).find((key) => !expected.has(key));
-    if (unknown !== undefined)
-        throw new Error(`${label} has unknown field: ${unknown}`);
-    const missing = keys.find((key) => !Object.hasOwn(value, key));
-    if (missing !== undefined)
-        throw new Error(`${label} is missing field: ${missing}`);
+export function enqueueSignal(mailbox, signal) {
+    validateWorkMailbox(mailbox);
+    const reason = requireText(signal.reason, "signal reason");
+    const occurredAt = requireTimestamp(signal.occurredAt, "signal occurredAt");
+    const source = requireText(signal.source ?? "yui", "signal source");
+    const sequence = mailbox.nextSequence;
+    const dedupeKey = signal.dedupeKey === undefined
+        ? `sequence:${sequence}`
+        : requireText(signal.dedupeKey, "signal dedupeKey");
+    if (mailboxContainsDedupeKey(mailbox, dedupeKey))
+        return mailbox;
+    const incoming = {
+        fromSequence: sequence,
+        toSequence: sequence,
+        reasons: [reason],
+        refs: appendUnique([], signal.refs.map(copyRef), mailboxEntityRefKey),
+        requestCount: 1,
+        firstQueuedAt: occurredAt,
+        lastQueuedAt: occurredAt,
+        sources: [source],
+        dedupeKeys: [dedupeKey],
+        ...(signal.factRevision === undefined
+            ? {}
+            : { highestFactRevision: requireInteger(signal.factRevision, 0, "signal factRevision") })
+    };
+    return validateWorkMailbox({
+        ...mailbox,
+        nextSequence: sequence + 1,
+        pending: mailbox.pending === null ? incoming : mergeBatches(mailbox.pending, incoming)
+    });
 }
-function requireString(value, label) {
-    if (typeof value !== "string")
-        throw new Error(`${label} must be a string`);
-    return requireText(value, label);
+export function mailboxHasPending(mailbox) {
+    return mailbox.pending !== null;
 }
-function requireTimestamp(value, label) {
-    const timestamp = requireString(value, label);
-    if (!Number.isFinite(Date.parse(timestamp)))
-        throw new Error(`${label} must be a timestamp`);
-    return timestamp;
+export function nextPendingBatch(mailbox) {
+    return mailbox.pending;
 }
-function requireStringArray(value, label) {
-    if (!Array.isArray(value))
-        throw new Error(`${label} must be an array`);
-    const result = value.map((item, index) => requireString(item, `${label}[${index}]`));
-    if (new Set(result).size !== result.length)
-        throw new Error(`${label} must not contain duplicates`);
-    return result;
+export function mailboxHasWork(mailbox) {
+    return mailbox.processing !== null || mailbox.pending !== null;
 }
-function copyTarget(target) {
-    switch (target.kind) {
-        case "task":
-            return { kind: "task", taskId: requireText(target.taskId, "taskId") };
-        case "role":
-            return {
-                kind: "role",
-                taskId: requireText(target.taskId, "taskId"),
-                roleName: requireText(target.roleName, "roleName")
-            };
-        case "role-runtime":
-            return {
-                kind: "role-runtime",
-                taskId: requireText(target.taskId, "taskId"),
-                roleName: requireText(target.roleName, "roleName")
-            };
-        case "global-role-runtime":
-            return {
-                kind: "global-role-runtime",
-                roleName: requireText(target.roleName, "roleName")
-            };
-        case "operator":
-            return { kind: "operator" };
+export function mailboxBatches(mailbox) {
+    return [mailbox.processing?.batch, mailbox.pending]
+        .filter((batch) => batch !== null && batch !== undefined);
+}
+export function claimPending(mailbox, options) {
+    validateWorkMailbox(mailbox);
+    if (mailbox.processing !== null)
+        throw new Error("Mailbox is already processing a batch");
+    if (mailbox.pending === null)
+        throw new Error("Mailbox has no pending work to claim");
+    return validateWorkMailbox({
+        ...mailbox,
+        processing: {
+            batchId: requireText(options.batchId, "batch id"),
+            batch: mailbox.pending,
+            owner: requireText(options.owner, "claim owner"),
+            startedAt: requireTimestamp(options.startedAt, "claim startedAt")
+        },
+        pending: null
+    });
+}
+export function bindExecution(mailbox, batchId, executionRef) {
+    const processing = requireProcessing(mailbox, batchId);
+    return validateWorkMailbox({
+        ...mailbox,
+        processing: { ...processing, executionRef: copyRef(executionRef) }
+    });
+}
+export function completeProcessing(mailbox, batchId) {
+    const processing = requireProcessing(mailbox, batchId);
+    return validateWorkMailbox({
+        ...mailbox,
+        processing: null,
+        recentDedupeKeys: rememberDedupeKeys(mailbox.recentDedupeKeys, processing.batch.dedupeKeys)
+    });
+}
+export function releaseProcessing(mailbox, batchId) {
+    const processing = requireProcessing(mailbox, batchId);
+    return validateWorkMailbox({
+        ...mailbox,
+        processing: null,
+        pending: mailbox.pending === null
+            ? processing.batch
+            : mergeBatches(processing.batch, mailbox.pending)
+    });
+}
+/**
+ * Consumes a whole wake or the exact submitted sequence prefix. Newer signals
+ * merged while the Provider request was in flight remain pending.
+ */
+export function consumePendingBatch(mailbox, through) {
+    validateWorkMailbox(mailbox);
+    if (mailbox.pending === null)
+        throw new Error("Mailbox has no pending batch");
+    const pending = mailbox.pending;
+    if (through !== undefined) {
+        if (through.fromSequence !== pending.fromSequence
+            || !Number.isInteger(through.toSequence)
+            || through.toSequence < through.fromSequence
+            || through.toSequence > pending.toSequence) {
+            throw new Error("Mailbox consumed sequence does not match the pending prefix");
+        }
+        if (through.toSequence < pending.toSequence) {
+            const consumedCount = through.toSequence - through.fromSequence + 1;
+            const keysAreSequenceAligned = pending.dedupeKeys.length === pending.requestCount;
+            const consumedKeys = keysAreSequenceAligned
+                ? pending.dedupeKeys.slice(0, consumedCount)
+                : [];
+            return validateWorkMailbox({
+                ...mailbox,
+                pending: {
+                    ...pending,
+                    fromSequence: through.toSequence + 1,
+                    requestCount: pending.toSequence - through.toSequence,
+                    dedupeKeys: keysAreSequenceAligned
+                        ? pending.dedupeKeys.slice(consumedCount)
+                        : pending.dedupeKeys
+                },
+                recentDedupeKeys: rememberDedupeKeys(mailbox.recentDedupeKeys, consumedKeys)
+            });
+        }
     }
+    return validateWorkMailbox({
+        ...mailbox,
+        recentDedupeKeys: rememberDedupeKeys(mailbox.recentDedupeKeys, pending.dedupeKeys),
+        pending: null
+    });
 }
 export function mailboxTargetKey(target) {
     const copied = copyTarget(target);
@@ -84,45 +186,22 @@ export function mailboxTargetKey(target) {
             return `global-role-runtime/${encodeURIComponent(copied.roleName)}`;
     }
 }
-function copyRef(ref) {
-    if (!("taskId" in ref)) {
-        if (ref.type !== "task" && ref.type !== "session") {
-            throw new Error(`entity reference taskId is required for ${ref.type}`);
-        }
-        return {
-            type: ref.type,
-            id: requireText(ref.id, "entity reference id")
-        };
-    }
-    const validated = validateTaskRecordReference({
-        taskId: ref.taskId,
-        localId: ref.id
-    }, mailboxTaskRecordKind(ref.type));
-    return {
-        type: ref.type,
-        taskId: validated.taskId,
-        id: validated.localId
-    };
-}
 export function mailboxEntityRefKey(ref) {
     return !("taskId" in ref)
         ? `${ref.type}\u0000${ref.id}`
         : `${ref.type}\u0000${ref.taskId}\u0000${ref.id}`;
 }
-function appendUnique(existing, incoming, keyOf) {
-    const result = [...existing];
-    const keys = new Set(existing.map(keyOf));
-    for (const value of incoming) {
-        const key = keyOf(value);
-        if (!keys.has(key)) {
-            keys.add(key);
-            result.push(value);
-        }
-    }
-    return result;
+function mailboxContainsDedupeKey(mailbox, key) {
+    return mailbox.recentDedupeKeys.includes(key)
+        || mailbox.pending?.dedupeKeys.includes(key) === true
+        || mailbox.processing?.batch.dedupeKeys.includes(key) === true;
+}
+function rememberDedupeKeys(existing, dedupeKeys) {
+    return appendUnique(existing, dedupeKeys, (value) => value)
+        .slice(-RECENT_DEDUPE_KEY_LIMIT);
 }
 function mergeBatches(left, right) {
-    const merged = {
+    return {
         fromSequence: Math.min(left.fromSequence, right.fromSequence),
         toSequence: Math.max(left.toSequence, right.toSequence),
         reasons: appendUnique(left.reasons, right.reasons, (reason) => reason),
@@ -136,158 +215,12 @@ function mergeBatches(left, right) {
             : right.lastQueuedAt,
         sources: appendUnique(left.sources, right.sources, (source) => source),
         dedupeKeys: appendUnique(left.dedupeKeys, right.dedupeKeys, (key) => key),
-        deliveryModes: appendUnique(left.deliveryModes, right.deliveryModes, (mode) => mode),
         ...((left.highestFactRevision ?? right.highestFactRevision) === undefined
             ? {}
             : {
                 highestFactRevision: Math.max(left.highestFactRevision ?? 0, right.highestFactRevision ?? 0)
             })
     };
-    return merged;
-}
-function requireProcessing(mailbox, batchId) {
-    const normalizedBatchId = requireText(batchId, "batch id");
-    if (mailbox.processing === null) {
-        throw new Error("Mailbox has no processing batch");
-    }
-    if (mailbox.processing.batchId !== normalizedBatchId) {
-        throw new Error(`Mailbox processing batch id does not match ${normalizedBatchId}`);
-    }
-    return mailbox.processing;
-}
-export function createWorkMailbox(target) {
-    return {
-        schemaVersion: 3,
-        target: copyTarget(target),
-        nextSequence: 1,
-        processing: null,
-        pending: {
-            normal: null,
-            userCorrection: null,
-            cursors: { normal: 0, userCorrection: 0 },
-            recentDedupeKeys: []
-        },
-        inputDelivery: null
-    };
-}
-export function validateWorkMailbox(value) {
-    const mailbox = record(value, "WorkMailbox");
-    exact(mailbox, ["schemaVersion", "target", "nextSequence", "processing", "pending", "inputDelivery"], "WorkMailbox");
-    if (mailbox.schemaVersion !== 3)
-        throw new Error("WorkMailbox must use schemaVersion 3");
-    const target = parseTarget(mailbox.target);
-    const nextSequence = requireInteger(mailbox.nextSequence, 1, "WorkMailbox nextSequence");
-    const processing = mailbox.processing === null ? null : parseProcessing(mailbox.processing);
-    const pending = parsePendingLanes(mailbox.pending);
-    for (const cursor of [pending.cursors.normal, pending.cursors.userCorrection]) {
-        if (cursor >= nextSequence) {
-            throw new Error("WorkMailbox lane cursor must be lower than nextSequence");
-        }
-    }
-    if (pending.normal !== null && pending.normal.fromSequence <= pending.cursors.normal) {
-        throw new Error("WorkMailbox normal pending batch is behind its cursor");
-    }
-    if (pending.userCorrection !== null
-        && pending.userCorrection.fromSequence <= pending.cursors.userCorrection) {
-        throw new Error("WorkMailbox user-correction pending batch is behind its cursor");
-    }
-    const inputDelivery = mailbox.inputDelivery === null
-        ? null
-        : parseInputDelivery(mailbox.inputDelivery);
-    const batches = [
-        processing?.batch,
-        pending.normal,
-        pending.userCorrection,
-        inputDelivery?.batch
-    ].filter((batch) => batch !== null && batch !== undefined);
-    const activeDedupeKeys = new Set();
-    for (const batch of batches) {
-        if (batch.toSequence >= nextSequence) {
-            throw new Error("WorkMailbox batch sequence must be lower than nextSequence");
-        }
-        for (const dedupeKey of batch.dedupeKeys) {
-            if (activeDedupeKeys.has(dedupeKey)) {
-                throw new Error("WorkMailbox active batches share a dedupe key");
-            }
-            activeDedupeKeys.add(dedupeKey);
-        }
-    }
-    if (inputDelivery !== null && target.kind !== "role" && target.kind !== "operator") {
-        throw new Error("WorkMailbox inputDelivery requires a Role or Operator target");
-    }
-    return { schemaVersion: 3, target, nextSequence, processing, pending, inputDelivery };
-}
-function parsePendingLanes(value) {
-    const lanes = record(value, "WorkMailbox pending");
-    exact(lanes, ["normal", "userCorrection", "cursors", "recentDedupeKeys"], "WorkMailbox pending");
-    const cursors = record(lanes.cursors, "WorkMailbox pending cursors");
-    exact(cursors, ["normal", "userCorrection"], "WorkMailbox pending cursors");
-    const recentDedupeKeys = requireStringArray(lanes.recentDedupeKeys, "WorkMailbox recent dedupe keys");
-    if (recentDedupeKeys.length > RECENT_DEDUPE_KEY_LIMIT) {
-        throw new Error("WorkMailbox recent dedupe keys exceed the bounded limit");
-    }
-    return {
-        normal: lanes.normal === null ? null : parseBatch(lanes.normal, "WorkMailbox pending normal"),
-        userCorrection: lanes.userCorrection === null
-            ? null
-            : parseBatch(lanes.userCorrection, "WorkMailbox pending userCorrection"),
-        cursors: {
-            normal: requireInteger(cursors.normal, 0, "WorkMailbox normal cursor"),
-            userCorrection: requireInteger(cursors.userCorrection, 0, "WorkMailbox user-correction cursor")
-        },
-        recentDedupeKeys
-    };
-}
-function parseTarget(value) {
-    const target = record(value, "WorkMailbox target");
-    switch (target.kind) {
-        case "operator":
-            exact(target, ["kind"], "WorkMailbox operator target");
-            return { kind: "operator" };
-        case "task":
-            exact(target, ["kind", "taskId"], "WorkMailbox task target");
-            return { kind: "task", taskId: requireString(target.taskId, "WorkMailbox target taskId") };
-        case "role":
-            exact(target, ["kind", "taskId", "roleName"], "WorkMailbox role target");
-            return {
-                kind: "role",
-                taskId: requireString(target.taskId, "WorkMailbox target taskId"),
-                roleName: requireString(target.roleName, "WorkMailbox target roleName")
-            };
-        case "role-runtime":
-            exact(target, ["kind", "taskId", "roleName"], "WorkMailbox role runtime target");
-            return {
-                kind: "role-runtime",
-                taskId: requireString(target.taskId, "WorkMailbox target taskId"),
-                roleName: requireString(target.roleName, "WorkMailbox target roleName")
-            };
-        case "global-role-runtime":
-            exact(target, ["kind", "roleName"], "WorkMailbox global role runtime target");
-            return {
-                kind: "global-role-runtime",
-                roleName: requireString(target.roleName, "WorkMailbox target roleName")
-            };
-        default:
-            throw new Error("WorkMailbox target kind is invalid");
-    }
-}
-function parseRef(value, label) {
-    const ref = record(value, label);
-    const types = [
-        "task", "run", "work-item", "input", "session", "message", "event"
-    ];
-    if (!types.includes(ref.type))
-        throw new Error(`${label} type is invalid`);
-    if (ref.type === "task" || ref.type === "session") {
-        exact(ref, ["type", "id"], label);
-        return { type: ref.type, id: requireString(ref.id, `${label} id`) };
-    }
-    exact(ref, ["type", "taskId", "id"], label);
-    return copyRef({
-        type: ref.type,
-        taskId: requireString(ref.taskId, `${label} taskId`),
-        id: requireString(ref.id, `${label} id`)
-    });
 }
 function parseBatch(value, label) {
     const batch = record(value, label);
@@ -300,8 +233,7 @@ function parseBatch(value, label) {
         "firstQueuedAt",
         "lastQueuedAt",
         "sources",
-        "dedupeKeys",
-        "deliveryModes"
+        "dedupeKeys"
     ];
     exact(batch, batch.highestFactRevision === undefined ? required : [...required, "highestFactRevision"], label);
     const fromSequence = requireInteger(batch.fromSequence, 1, `${label} fromSequence`);
@@ -316,10 +248,10 @@ function parseBatch(value, label) {
     if (!Array.isArray(batch.refs))
         throw new Error(`${label} refs must be an array`);
     const refs = batch.refs.map((ref, index) => parseRef(ref, `${label} refs[${index}]`));
-    const refKeys = refs.map(mailboxEntityRefKey);
-    if (new Set(refKeys).size !== refKeys.length)
+    if (new Set(refs.map(mailboxEntityRefKey)).size !== refs.length) {
         throw new Error(`${label} refs must not contain duplicates`);
-    const result = {
+    }
+    return {
         fromSequence,
         toSequence,
         reasons,
@@ -329,384 +261,182 @@ function parseBatch(value, label) {
         lastQueuedAt: requireTimestamp(batch.lastQueuedAt, `${label} lastQueuedAt`),
         sources: requireStringArray(batch.sources, `${label} sources`),
         dedupeKeys: requireStringArray(batch.dedupeKeys, `${label} dedupeKeys`),
-        deliveryModes: parseDeliveryModes(batch.deliveryModes, `${label} deliveryModes`),
         ...(batch.highestFactRevision === undefined
             ? {}
             : {
                 highestFactRevision: requireInteger(batch.highestFactRevision, 0, `${label} highestFactRevision`)
             })
     };
-    return result;
-}
-function parseDeliveryModes(value, label) {
-    const modes = requireStringArray(value, label);
-    for (const mode of modes) {
-        if (mode !== "followup" && mode !== "steer-if-safe" && mode !== "inject") {
-            throw new Error(`${label} contains an invalid delivery mode`);
-        }
-    }
-    return modes;
 }
 function parseProcessing(value) {
     const processing = record(value, "WorkMailbox processing");
-    const required = ["batchId", "lane", "batch", "owner", "startedAt"];
+    const required = ["batchId", "batch", "owner", "startedAt"];
     exact(processing, processing.executionRef === undefined ? required : [...required, "executionRef"], "WorkMailbox processing");
     const result = {
         batchId: requireString(processing.batchId, "WorkMailbox processing batchId"),
-        lane: parseLane(processing.lane, "WorkMailbox processing lane"),
         batch: parseBatch(processing.batch, "WorkMailbox processing batch"),
         owner: requireString(processing.owner, "WorkMailbox processing owner"),
         startedAt: requireTimestamp(processing.startedAt, "WorkMailbox processing startedAt")
     };
     return processing.executionRef === undefined
         ? result
-        : { ...result, executionRef: parseRef(processing.executionRef, "WorkMailbox processing executionRef") };
+        : {
+            ...result,
+            executionRef: parseRef(processing.executionRef, "WorkMailbox processing executionRef")
+        };
 }
-function parseInputDelivery(value) {
-    const input = record(value, "WorkMailbox inputDelivery");
-    const required = [
-        "attemptId",
-        "lane",
-        "mode",
-        "batch",
-        "owner",
-        "status",
-        "startedAt",
-        "executionRef"
-    ];
-    const optional = [
-        ...(input.pushedAt === undefined ? [] : ["pushedAt"]),
-        ...(input.unknownReason === undefined ? [] : ["unknownReason"]),
-        ...(input.providerFence === undefined ? [] : ["providerFence"])
-    ];
-    exact(input, [...required, ...optional], "WorkMailbox inputDelivery");
-    const lane = parseLane(input.lane, "WorkMailbox inputDelivery lane");
-    const mode = parseDeliveryMode(input.mode, "WorkMailbox inputDelivery mode");
-    if (input.status !== "dispatching" && input.status !== "delivery-unknown") {
-        throw new Error("WorkMailbox inputDelivery status is invalid");
-    }
-    const status = input.status;
-    if ((status === "delivery-unknown") !== (input.unknownReason !== undefined)) {
-        throw new Error("WorkMailbox delivery-unknown requires exactly one unknownReason");
-    }
-    const result = {
-        attemptId: requireString(input.attemptId, "WorkMailbox inputDelivery attemptId"),
-        lane,
-        mode,
-        batch: parseBatch(input.batch, "WorkMailbox inputDelivery batch"),
-        owner: requireString(input.owner, "WorkMailbox inputDelivery owner"),
-        status,
-        startedAt: requireTimestamp(input.startedAt, "WorkMailbox inputDelivery startedAt"),
-        executionRef: parseRef(input.executionRef, "WorkMailbox inputDelivery executionRef"),
-        ...(input.pushedAt === undefined
-            ? {}
-            : { pushedAt: requireTimestamp(input.pushedAt, "WorkMailbox inputDelivery pushedAt") }),
-        ...(input.unknownReason === undefined
-            ? {}
-            : { unknownReason: requireString(input.unknownReason, "WorkMailbox inputDelivery unknownReason") }),
-        ...(input.providerFence === undefined
-            ? {}
-            : { providerFence: parseProviderFence(input.providerFence) })
-    };
-    if (result.pushedAt !== undefined
-        && Date.parse(result.pushedAt) < Date.parse(result.startedAt)) {
-        throw new Error("WorkMailbox inputDelivery pushedAt is earlier than startedAt");
+function parseTarget(value) {
+    const target = record(value, "WorkMailbox target");
+    switch (target.kind) {
+        case "operator":
+            exact(target, ["kind"], "WorkMailbox operator target");
+            return { kind: "operator" };
+        case "task":
+            exact(target, ["kind", "taskId"], "WorkMailbox task target");
+            return { kind: "task", taskId: requireString(target.taskId, "WorkMailbox target taskId") };
+        case "role":
+        case "role-runtime":
+            exact(target, ["kind", "taskId", "roleName"], `WorkMailbox ${target.kind} target`);
+            return {
+                kind: target.kind,
+                taskId: requireString(target.taskId, "WorkMailbox target taskId"),
+                roleName: requireString(target.roleName, "WorkMailbox target roleName")
+            };
+        case "global-role-runtime":
+            exact(target, ["kind", "roleName"], "WorkMailbox global role runtime target");
+            return {
+                kind: "global-role-runtime",
+                roleName: requireString(target.roleName, "WorkMailbox target roleName")
+            };
+        default:
+            throw new Error("WorkMailbox target kind is invalid");
     }
-    return result;
 }
-function parseProviderFence(value) {
-    const fence = record(value, "WorkMailbox inputDelivery providerFence");
-    exact(fence, fence.nativeTurnId === undefined
-        ? ["conversationId", "activationId"]
-        : ["conversationId", "activationId", "nativeTurnId"], "WorkMailbox inputDelivery providerFence");
-    return {
-        conversationId: requireString(fence.conversationId, "Provider Conversation id"),
-        activationId: requireString(fence.activationId, "Provider Activation id"),
-        ...(fence.nativeTurnId === undefined
-            ? {}
-            : { nativeTurnId: requireString(fence.nativeTurnId, "Provider Turn id") })
-    };
+function parseRef(value, label) {
+    const ref = record(value, label);
+    const types = [
+        "task", "turn", "work-item", "input", "session", "message", "event"
+    ];
+    if (!types.includes(ref.type))
+        throw new Error(`${label} type is invalid`);
+    if (ref.type === "task" || ref.type === "session") {
+        exact(ref, ["type", "id"], label);
+        return { type: ref.type, id: requireString(ref.id, `${label} id`) };
+    }
+    exact(ref, ["type", "taskId", "id"], label);
+    return copyRef({
+        type: ref.type,
+        taskId: requireString(ref.taskId, `${label} taskId`),
+        id: requireString(ref.id, `${label} id`)
+    });
 }
-function parseLane(value, label) {
-    if (value !== "normal" && value !== "user-correction") {
-        throw new Error(`${label} is invalid`);
+function requireProcessing(mailbox, batchId) {
+    validateWorkMailbox(mailbox);
+    const normalizedBatchId = requireText(batchId, "batch id");
+    if (mailbox.processing === null)
+        throw new Error("Mailbox has no processing batch");
+    if (mailbox.processing.batchId !== normalizedBatchId) {
+        throw new Error(`Mailbox processing batch id does not match ${normalizedBatchId}`);
     }
-    return value;
+    return mailbox.processing;
 }
-function parseDeliveryMode(value, label) {
-    if (value !== "followup" && value !== "steer-if-safe" && value !== "inject") {
-        throw new Error(`${label} is invalid`);
+function copyTarget(target) {
+    switch (target.kind) {
+        case "operator": return { kind: "operator" };
+        case "task": return { kind: "task", taskId: requireText(target.taskId, "taskId") };
+        case "role":
+        case "role-runtime":
+            return {
+                kind: target.kind,
+                taskId: requireText(target.taskId, "taskId"),
+                roleName: requireText(target.roleName, "roleName")
+            };
+        case "global-role-runtime":
+            return {
+                kind: "global-role-runtime",
+                roleName: requireText(target.roleName, "roleName")
+            };
     }
-    return value;
 }
-export function enqueueSignal(mailbox, signal) {
-    const reason = requireText(signal.reason, "signal reason");
-    const occurredAt = requireText(signal.occurredAt, "signal occurredAt");
-    const lane = signal.lane ?? "normal";
-    const laneKey = lane === "normal" ? "normal" : "userCorrection";
-    const deliveryMode = signal.deliveryMode ?? "followup";
-    const source = requireText(signal.source ?? "yui", "signal source");
-    const refs = signal.refs.map(copyRef);
-    const sequence = mailbox.nextSequence;
-    const dedupeKey = signal.dedupeKey === undefined
-        ? `sequence:${sequence}`
-        : requireText(signal.dedupeKey, "signal dedupeKey");
-    if (mailboxContainsDedupeKey(mailbox, dedupeKey))
-        return mailbox;
-    const incoming = {
-        fromSequence: sequence,
-        toSequence: sequence,
-        reasons: [reason],
-        refs: appendUnique([], refs, mailboxEntityRefKey),
-        requestCount: 1,
-        firstQueuedAt: occurredAt,
-        lastQueuedAt: occurredAt,
-        sources: [source],
-        dedupeKeys: [dedupeKey],
-        deliveryModes: [deliveryMode],
-        ...(signal.factRevision === undefined
-            ? {}
-            : { highestFactRevision: requireInteger(signal.factRevision, 0, "signal factRevision") })
-    };
-    return {
-        ...mailbox,
-        nextSequence: sequence + 1,
-        pending: {
-            ...mailbox.pending,
-            [laneKey]: mailbox.pending[laneKey] === null
-                ? incoming
-                : mergeBatches(mailbox.pending[laneKey], incoming)
+function copyRef(ref) {
+    if (!("taskId" in ref)) {
+        if (ref.type !== "task" && ref.type !== "session") {
+            throw new Error(`entity reference taskId is required for ${ref.type}`);
         }
-    };
-}
-function mailboxContainsDedupeKey(mailbox, key) {
-    if (mailbox.pending.recentDedupeKeys.includes(key))
-        return true;
-    return [
-        mailbox.pending.normal,
-        mailbox.pending.userCorrection,
-        mailbox.processing?.batch,
-        mailbox.inputDelivery?.batch
-    ].some((batch) => batch?.dedupeKeys.includes(key) === true);
-}
-export function pendingLane(mailbox, lane) {
-    return lane === "normal" ? mailbox.pending.normal : mailbox.pending.userCorrection;
-}
-export function mailboxHasPending(mailbox) {
-    return mailbox.pending.normal !== null || mailbox.pending.userCorrection !== null;
-}
-export function nextPendingLane(mailbox) {
-    if (mailbox.pending.userCorrection !== null)
-        return "user-correction";
-    return mailbox.pending.normal === null ? null : "normal";
-}
-export function nextPendingBatch(mailbox) {
-    const lane = nextPendingLane(mailbox);
-    return lane === null ? null : pendingLane(mailbox, lane);
-}
-export function mailboxHasWork(mailbox) {
-    return mailbox.processing !== null
-        || mailbox.inputDelivery !== null
-        || mailboxHasPending(mailbox);
-}
-export function mailboxBatches(mailbox) {
-    return [
-        mailbox.processing?.batch,
-        mailbox.inputDelivery?.batch,
-        mailbox.pending.userCorrection,
-        mailbox.pending.normal
-    ].filter((batch) => batch !== null && batch !== undefined);
+        return { type: ref.type, id: requireText(ref.id, "entity reference id") };
+    }
+    const validated = validateTaskRecordReference({
+        taskId: ref.taskId,
+        localId: ref.id
+    }, mailboxTaskRecordKind(ref.type));
+    return { type: ref.type, taskId: validated.taskId, id: validated.localId };
 }
 function mailboxTaskRecordKind(type) {
     switch (type) {
-        case "run": return "agentRun";
+        case "turn": return "turn";
         case "work-item": return "workItem";
         case "input": return "inputRequest";
         case "message": return "message";
         case "event": return "event";
     }
 }
-export function claimPending(mailbox, options) {
-    if (mailbox.processing !== null) {
-        throw new Error("Mailbox is already processing a batch");
-    }
-    const lane = options.lane ?? nextPendingLane(mailbox);
-    if (lane === null) {
-        throw new Error("Mailbox has no pending work to claim");
-    }
-    const batch = pendingLane(mailbox, lane);
-    if (batch === null)
-        throw new Error(`Mailbox has no pending ${lane} work to claim`);
-    const processing = {
-        batchId: requireText(options.batchId, "batch id"),
-        lane,
-        batch,
-        owner: requireText(options.owner, "claim owner"),
-        startedAt: requireText(options.startedAt, "claim startedAt")
-    };
-    return {
-        ...mailbox,
-        processing,
-        pending: {
-            ...mailbox.pending,
-            [lane === "normal" ? "normal" : "userCorrection"]: null
-        }
-    };
-}
-export function bindExecution(mailbox, batchId, executionRef) {
-    const processing = requireProcessing(mailbox, batchId);
-    return {
-        ...mailbox,
-        processing: { ...processing, executionRef: copyRef(executionRef) }
-    };
-}
-export function completeProcessing(mailbox, batchId) {
-    const processing = requireProcessing(mailbox, batchId);
-    const lane = processing.lane;
-    return validateWorkMailbox({
-        ...mailbox,
-        processing: null,
-        pending: advanceLaneCursor(mailbox.pending, lane, processing.batch)
-    });
-}
-export function releaseProcessing(mailbox, batchId) {
-    const processing = requireProcessing(mailbox, batchId);
-    const lane = processing.lane;
-    const key = lane === "normal" ? "normal" : "userCorrection";
-    const released = mailbox.pending[key] === null
-        ? processing.batch
-        : mergeBatches(processing.batch, mailbox.pending[key]);
-    return {
-        ...mailbox,
-        processing: null,
-        pending: { ...mailbox.pending, [key]: released }
-    };
-}
-function requireInputDelivery(mailbox, attemptId) {
-    const id = requireText(attemptId, "input delivery attempt id");
-    if (mailbox.inputDelivery === null)
-        throw new Error("Mailbox has no input delivery");
-    if (mailbox.inputDelivery.attemptId !== id) {
-        throw new Error(`Mailbox input delivery does not match ${id}`);
+function appendUnique(existing, incoming, keyOf) {
+    const result = [...existing];
+    const keys = new Set(existing.map(keyOf));
+    for (const value of incoming) {
+        const key = keyOf(value);
+        if (keys.has(key))
+            continue;
+        keys.add(key);
+        result.push(value);
     }
-    return mailbox.inputDelivery;
+    return result;
 }
-export function claimInputDelivery(mailbox, options) {
-    if (mailbox.inputDelivery !== null) {
-        if (mailbox.inputDelivery.attemptId === options.attemptId)
-            return mailbox;
-        throw new Error("Mailbox already has an input delivery");
+function record(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
     }
-    const batch = pendingLane(mailbox, options.lane);
-    if (batch === null)
-        throw new Error(`Mailbox has no pending ${options.lane} input`);
-    const inputDelivery = {
-        attemptId: requireText(options.attemptId, "input delivery attempt id"),
-        lane: options.lane,
-        mode: options.mode,
-        batch,
-        owner: requireText(options.owner, "input delivery owner"),
-        status: "dispatching",
-        startedAt: requireTimestamp(options.startedAt, "input delivery startedAt"),
-        executionRef: copyRef(options.executionRef),
-        ...(options.providerFence === undefined
-            ? {}
-            : { providerFence: parseProviderFence(options.providerFence) })
-    };
-    return validateWorkMailbox({
-        ...mailbox,
-        pending: {
-            ...mailbox.pending,
-            [options.lane === "normal" ? "normal" : "userCorrection"]: null
-        },
-        inputDelivery
-    });
-}
-export function markInputDeliveryPushed(mailbox, attemptId, pushedAt) {
-    const delivery = requireInputDelivery(mailbox, attemptId);
-    if (delivery.pushedAt !== undefined)
-        return mailbox;
-    const timestamp = requireTimestamp(pushedAt.toISOString(), "input delivery pushedAt");
-    return validateWorkMailbox({
-        ...mailbox,
-        inputDelivery: { ...delivery, pushedAt: timestamp }
-    });
+    return value;
 }
-export function markInputDeliveryUnknown(mailbox, attemptId, reason, observedAt) {
-    const delivery = requireInputDelivery(mailbox, attemptId);
-    const timestamp = requireTimestamp(observedAt.toISOString(), "delivery unknown observedAt");
-    return validateWorkMailbox({
-        ...mailbox,
-        inputDelivery: {
-            ...delivery,
-            status: "delivery-unknown",
-            unknownReason: requireText(reason, "delivery unknown reason"),
-            pushedAt: delivery.pushedAt ?? timestamp
-        }
-    });
+function exact(value, keys, label) {
+    const expected = new Set(keys);
+    const unknown = Object.keys(value).find((key) => !expected.has(key));
+    if (unknown !== undefined)
+        throw new Error(`${label} has unknown field: ${unknown}`);
+    const missing = keys.find((key) => !Object.hasOwn(value, key));
+    if (missing !== undefined)
+        throw new Error(`${label} is missing field: ${missing}`);
 }
-export function completeInputDelivery(mailbox, attemptId, _acceptedAt) {
-    const delivery = requireInputDelivery(mailbox, attemptId);
-    return validateWorkMailbox({
-        ...mailbox,
-        inputDelivery: null,
-        pending: advanceLaneCursor(mailbox.pending, delivery.lane, delivery.batch)
-    });
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid`);
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} must not be empty`);
+    return normalized;
 }
-export function consumePendingBatch(mailbox, lane) {
-    const key = lane === "normal" ? "normal" : "userCorrection";
-    const batch = mailbox.pending[key];
-    if (batch === null)
-        throw new Error(`Mailbox has no pending ${lane} batch`);
-    return validateWorkMailbox({
-        ...mailbox,
-        pending: {
-            ...advanceLaneCursor(mailbox.pending, lane, batch),
-            [key]: null
-        }
-    });
+function requireString(value, label) {
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    return requireText(value, label);
 }
-function advanceLaneCursor(pending, lane, batch) {
-    const key = lane === "normal" ? "normal" : "userCorrection";
-    const recentDedupeKeys = appendUnique(pending.recentDedupeKeys, batch.dedupeKeys, (value) => value).slice(-RECENT_DEDUPE_KEY_LIMIT);
-    return {
-        ...pending,
-        cursors: {
-            ...pending.cursors,
-            [key]: Math.max(pending.cursors[key], batch.toSequence)
-        },
-        recentDedupeKeys
-    };
+function requireTimestamp(value, label) {
+    const timestamp = requireString(value, label);
+    if (!Number.isFinite(Date.parse(timestamp)))
+        throw new Error(`${label} must be a timestamp`);
+    return timestamp;
 }
-export function releaseInputDelivery(mailbox, attemptId) {
-    const delivery = requireInputDelivery(mailbox, attemptId);
-    if (delivery.pushedAt !== undefined || delivery.status === "delivery-unknown") {
-        throw new Error("A pushed or delivery-unknown input cannot return to pending");
+function requireInteger(value, minimum, label) {
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new Error(`${label} must be an integer greater than or equal to ${minimum}`);
     }
-    const key = delivery.lane === "normal" ? "normal" : "userCorrection";
-    return validateWorkMailbox({
-        ...mailbox,
-        pending: {
-            ...mailbox.pending,
-            [key]: mailbox.pending[key] === null
-                ? delivery.batch
-                : mergeBatches(delivery.batch, mailbox.pending[key])
-        },
-        inputDelivery: null
-    });
+    return value;
 }
-/** Exact Provider readback proved that a previously uncertain mutation is absent. */
-export function resolveInputDeliveryNotAccepted(mailbox, attemptId) {
-    const delivery = requireInputDelivery(mailbox, attemptId);
-    const key = delivery.lane === "normal" ? "normal" : "userCorrection";
-    return validateWorkMailbox({
-        ...mailbox,
-        pending: {
-            ...mailbox.pending,
-            [key]: mailbox.pending[key] === null
-                ? delivery.batch
-                : mergeBatches(delivery.batch, mailbox.pending[key])
-        },
-        inputDelivery: null
-    });
+function requireStringArray(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array`);
+    const result = value.map((item, index) => requireString(item, `${label}[${index}]`));
+    if (new Set(result).size !== result.length)
+        throw new Error(`${label} must not contain duplicates`);
+    return result;
 }