@zq-silk/yui 0.8.1 → 0.8.2

package/dist/runtime/providerRuntimeIdentity.js

@@ -1,7 +1,7 @@
 export function createProviderRuntimeBinding(input) {
     const startedAt = timestamp(input.startedAt, "Provider Activation startedAt");
     return validateProviderRuntimeBinding({
-        schemaVersion: 1,
+        schemaVersion: 2,
         providerNamespace: identity(input.providerNamespace, "Provider namespace"),
         accountScope: identity(input.accountScope, "Provider account scope"),
         runId: identity(input.runId, "Run id"),
@@ -18,11 +18,20 @@ export function createProviderRuntimeBinding(input) {
                 conversationId: input.conversationId,
                 generation: 1,
                 status: "active",
-                writerLease: true,
                 startedAt
-            }]
+            }],
+        authority: {
+            epoch: 1,
+            owner: "controller",
+            holderId: input.activationId,
+            changedAt: startedAt
+        },
+        turn: null
     });
 }
+export function currentProviderAuthority(binding) {
+    return validateProviderRuntimeBinding(binding).authority;
+}
 export function currentProviderConversation(binding) {
     validateProviderRuntimeBinding(binding);
     return binding.conversations.find((entry) => (entry.epoch === binding.currentConversationEpoch && entry.status === "current"));
@@ -31,25 +40,46 @@ export function currentProviderActivation(binding) {
     const conversation = currentProviderConversation(binding);
     return [...binding.activations].reverse().find((entry) => (entry.conversationId === conversation.conversationId && entry.status === "active")) ?? null;
 }
+/** Rebinds the live Conversation state to the next Yui Run without resetting authority. */
+export function rebindProviderRuntimeRun(raw, runId) {
+    const binding = validateProviderRuntimeBinding(raw);
+    if (providerTurnIsActive(binding.turn)) {
+        throw new Error("Provider Runtime cannot bind another Run while a Turn is unsettled.");
+    }
+    return validateProviderRuntimeBinding({
+        ...binding,
+        runId: identity(runId, "Run id")
+    });
+}
 export function startProviderActivation(raw, input) {
     const binding = validateProviderRuntimeBinding(raw);
     if (currentProviderActivation(binding) !== null) {
         throw new Error("Provider Conversation already has a live writer Activation.");
     }
+    if (binding.authority.owner !== "none") {
+        throw new Error("Provider Conversation authority must be unowned before a new Activation starts.");
+    }
     const conversation = currentProviderConversation(binding);
     const generation = binding.activations
         .filter((entry) => entry.conversationId === conversation.conversationId)
         .reduce((maximum, entry) => Math.max(maximum, entry.generation), 0) + 1;
+    const startedAt = timestamp(input.startedAt, "Provider Activation startedAt");
+    const activationId = identity(input.activationId, "Provider Activation id");
     return validateProviderRuntimeBinding({
         ...binding,
         activations: [...binding.activations, {
-                activationId: identity(input.activationId, "Provider Activation id"),
+                activationId,
                 conversationId: conversation.conversationId,
                 generation,
                 status: "active",
-                writerLease: true,
-                startedAt: timestamp(input.startedAt, "Provider Activation startedAt")
-            }]
+                startedAt
+            }],
+        authority: {
+            epoch: binding.authority.epoch + 1,
+            owner: "controller",
+            holderId: activationId,
+            changedAt: startedAt
+        }
     });
 }
 export function endProviderActivation(raw, activationId, input) {
@@ -70,13 +100,161 @@ export function endProviderActivation(raw, activationId, input) {
             ? {
                 ...entry,
                 status: input.status,
-                writerLease: false,
                 endedAt,
                 ...(input.reason === undefined
                     ? {}
                     : { terminalReason: identity(input.reason, "Provider Activation terminal reason") })
             }
-            : entry)
+            : entry),
+        authority: {
+            epoch: binding.authority.epoch + 1,
+            owner: "none",
+            changedAt: endedAt
+        }
+    });
+}
+/**
+ * Compare-and-swap the only Provider writer. A stale Controller or detached
+ * terminal cannot regain authority with an older epoch.
+ */
+export function transferProviderAuthority(raw, input) {
+    const binding = validateProviderRuntimeBinding(raw);
+    if (binding.authority.epoch !== input.expectedEpoch
+        || binding.authority.owner !== input.expectedOwner) {
+        throw new Error("Provider authority fence is stale.");
+    }
+    if (providerTurnIsActive(binding.turn)) {
+        throw new Error("Provider authority cannot transfer while a Turn is unsettled.");
+    }
+    const active = currentProviderActivation(binding);
+    const changedAt = timestamp(input.changedAt, "Provider authority changedAt");
+    if (Date.parse(changedAt) < Date.parse(binding.authority.changedAt)) {
+        throw new Error("Provider authority changedAt moved backwards.");
+    }
+    let holderId;
+    if (input.owner === "none") {
+        if (input.holderId !== undefined) {
+            throw new Error("Unowned Provider authority cannot name a holder.");
+        }
+    }
+    else {
+        if (active === null) {
+            throw new Error("Provider authority requires a live Activation.");
+        }
+        holderId = identity(input.holderId, "Provider authority holder id");
+        if (input.owner === "controller" && holderId !== active.activationId) {
+            throw new Error("Controller authority must be held by the live Activation.");
+        }
+    }
+    return validateProviderRuntimeBinding({
+        ...binding,
+        authority: {
+            epoch: binding.authority.epoch + 1,
+            owner: input.owner,
+            ...(holderId === undefined ? {} : { holderId }),
+            changedAt
+        }
+    });
+}
+export function beginProviderTurn(raw, input) {
+    const binding = validateProviderRuntimeBinding(raw);
+    const attemptId = identity(input.attemptId, "Provider input attempt id");
+    if (binding.turn?.attemptId === attemptId
+        && binding.turn.authorityEpoch === input.authorityEpoch
+        && binding.turn.status === "submitting") {
+        return binding;
+    }
+    if (binding.authority.epoch !== input.authorityEpoch
+        || binding.authority.owner === "none"
+        || binding.authority.owner === "unknown") {
+        throw new Error("Provider Turn authority fence is stale.");
+    }
+    if (providerTurnIsActive(binding.turn)) {
+        throw new Error("Provider Conversation already has an unsettled Turn.");
+    }
+    const submittedAt = timestamp(input.submittedAt, "Provider Turn submittedAt");
+    return validateProviderRuntimeBinding({
+        ...binding,
+        turn: {
+            attemptId,
+            authorityEpoch: input.authorityEpoch,
+            status: "submitting",
+            submittedAt,
+            updatedAt: submittedAt
+        }
+    });
+}
+export function acceptProviderTurn(raw, input) {
+    const binding = validateProviderRuntimeBinding(raw);
+    const attemptId = identity(input.attemptId, "Provider input attempt id");
+    const turn = binding.turn;
+    if (turn === null || turn.attemptId !== attemptId
+        || (turn.status !== "submitting" && turn.status !== "delivery-unknown")) {
+        throw new Error("Provider Turn does not match an acceptable delivery state.");
+    }
+    const acceptedAt = orderedTurnTimestamp(turn, input.acceptedAt, "Provider Turn acceptedAt");
+    return validateProviderRuntimeBinding({
+        ...binding,
+        turn: {
+            ...turn,
+            status: "accepted",
+            turnId: identity(input.turnId, "Provider Turn id"),
+            updatedAt: acceptedAt
+        }
+    });
+}
+export function markProviderTurnDeliveryUnknown(raw, input) {
+    const binding = validateProviderRuntimeBinding(raw);
+    const turn = requireProviderTurn(binding, input.attemptId, "submitting");
+    const observedAt = orderedTurnTimestamp(turn, input.observedAt, "Provider Turn unknownAt");
+    return validateProviderRuntimeBinding({
+        ...binding,
+        turn: {
+            ...turn,
+            status: "delivery-unknown",
+            terminalReason: identity(input.reason, "Provider Turn unknown reason"),
+            updatedAt: observedAt
+        }
+    });
+}
+/** Exact negative acknowledgement before a Provider Turn identity existed. */
+export function rejectProviderTurn(raw, input) {
+    const binding = validateProviderRuntimeBinding(raw);
+    const turn = binding.turn;
+    if (turn === null || turn.attemptId !== identity(input.attemptId, "Provider input attempt id")
+        || (turn.status !== "submitting" && turn.status !== "delivery-unknown")) {
+        throw new Error("Provider Turn does not match a rejectable delivery state.");
+    }
+    const rejectedAt = orderedTurnTimestamp(turn, input.rejectedAt, "Provider Turn rejectedAt");
+    return validateProviderRuntimeBinding({
+        ...binding,
+        turn: {
+            ...turn,
+            status: "rejected",
+            terminalReason: identity(input.reason, "Provider Turn rejection reason"),
+            updatedAt: rejectedAt
+        }
+    });
+}
+export function settleProviderTurn(raw, input) {
+    const binding = validateProviderRuntimeBinding(raw);
+    const turn = binding.turn;
+    const turnId = identity(input.turnId, "Provider Turn id");
+    if (turn === null || turn.turnId !== turnId
+        || (turn.status !== "accepted" && turn.status !== "running")) {
+        throw new Error("Provider Turn settlement does not match the current Turn.");
+    }
+    const settledAt = orderedTurnTimestamp(turn, input.settledAt, "Provider Turn settledAt");
+    return validateProviderRuntimeBinding({
+        ...binding,
+        turn: {
+            ...turn,
+            status: input.status,
+            updatedAt: settledAt,
+            ...(input.reason === undefined
+                ? {}
+                : { terminalReason: identity(input.reason, "Provider Turn terminal reason") })
+        }
     });
 }
 export function updateProviderConversationRecoverability(raw, recoverability) {
@@ -98,7 +276,7 @@ export function supersedeProviderConversation(raw, input) {
     if (!input.noUnsettledInputDelivery) {
         throw new Error("Cannot replace a Provider Conversation with unsettled input delivery.");
     }
-    if (!input.writerUmbrellaClear || currentProviderActivation(binding) !== null) {
+    if (binding.authority.owner !== "none" || currentProviderActivation(binding) !== null) {
         throw new Error("Cannot replace a Provider Conversation while its writer umbrella is owned.");
     }
     const switchedAt = timestamp(input.switchedAt, "Provider Conversation switch timestamp");
@@ -123,14 +301,19 @@ export function supersedeProviderConversation(raw, input) {
                 conversationId: input.conversationId,
                 generation: 1,
                 status: "active",
-                writerLease: true,
                 startedAt: switchedAt
-            }]
+            }],
+        authority: {
+            epoch: binding.authority.epoch + 1,
+            owner: "controller",
+            holderId: input.activationId,
+            changedAt: switchedAt
+        }
     });
 }
 export function validateProviderRuntimeBinding(value) {
-    if (value.schemaVersion !== 1)
-        throw new Error("Provider Runtime Binding schemaVersion must be 1.");
+    if (value.schemaVersion !== 2)
+        throw new Error("Provider Runtime Binding schemaVersion must be 2.");
     identity(value.providerNamespace, "Provider namespace");
     identity(value.accountScope, "Provider account scope");
     identity(value.runId, "Run id");
@@ -197,8 +380,8 @@ export function validateProviderRuntimeBinding(value) {
         }
         timestamp(activation.startedAt, "Provider Activation startedAt");
         if (activation.status === "active") {
-            if (!activation.writerLease || activation.endedAt !== undefined) {
-                throw new Error("Active Provider Activation must hold its writer lease.");
+            if (activation.endedAt !== undefined) {
+                throw new Error("Active Provider Activation cannot have endedAt.");
             }
             if (activeByConversation.has(activation.conversationId)) {
                 throw new Error("Provider Conversation has multiple live writer Activations.");
@@ -206,14 +389,81 @@ export function validateProviderRuntimeBinding(value) {
             activeByConversation.add(activation.conversationId);
         }
         else {
-            if (activation.writerLease || activation.endedAt === undefined) {
-                throw new Error("Terminal Provider Activation must release its writer lease.");
-            }
+            if (activation.endedAt === undefined)
+                throw new Error("Terminal Provider Activation requires endedAt.");
             timestamp(activation.endedAt, "Provider Activation endedAt");
         }
     }
+    integer(value.authority.epoch, 1, "Provider authority epoch");
+    timestamp(value.authority.changedAt, "Provider authority changedAt");
+    if (!["controller", "human", "none", "unknown"].includes(value.authority.owner)) {
+        throw new Error("Provider authority owner is invalid.");
+    }
+    const active = currentActivationUnchecked(value);
+    if (value.authority.owner === "controller" || value.authority.owner === "human") {
+        const holderId = identity(value.authority.holderId, "Provider authority holder id");
+        if (active === null)
+            throw new Error("Owned Provider authority requires a live Activation.");
+        if (value.authority.owner === "controller" && holderId !== active.activationId) {
+            throw new Error("Controller authority must be held by the live Activation.");
+        }
+    }
+    else if (value.authority.holderId !== undefined) {
+        throw new Error("Unowned or unknown Provider authority cannot name a holder.");
+    }
+    if (active !== null && (value.authority.owner === "none" || value.authority.owner === "unknown")) {
+        throw new Error("A live Provider Activation requires an exact writer authority.");
+    }
+    if (!Object.hasOwn(value, "turn"))
+        throw new Error("Provider Runtime Binding requires Turn state.");
+    if (value.turn !== null)
+        validateProviderTurn(value.turn, value.authority.epoch);
     return value;
 }
+function validateProviderTurn(turn, currentAuthorityEpoch) {
+    identity(turn.attemptId, "Provider input attempt id");
+    integer(turn.authorityEpoch, 1, "Provider Turn authority epoch");
+    if (turn.authorityEpoch > currentAuthorityEpoch) {
+        throw new Error("Provider Turn authority epoch is ahead of current authority.");
+    }
+    if (!["submitting", "accepted", "running", "completed", "failed", "cancelled", "rejected", "delivery-unknown"]
+        .includes(turn.status)) {
+        throw new Error("Provider Turn status is invalid.");
+    }
+    timestamp(turn.submittedAt, "Provider Turn submittedAt");
+    timestamp(turn.updatedAt, "Provider Turn updatedAt");
+    if (Date.parse(turn.updatedAt) < Date.parse(turn.submittedAt)) {
+        throw new Error("Provider Turn updatedAt is earlier than submittedAt.");
+    }
+    const hasAcceptedIdentity = turn.status === "accepted" || turn.status === "running"
+        || turn.status === "completed" || turn.status === "failed" || turn.status === "cancelled";
+    if (hasAcceptedIdentity)
+        identity(turn.turnId, "Provider Turn id");
+    else if (turn.turnId !== undefined)
+        throw new Error("Unaccepted Provider Turn cannot have a Turn id.");
+}
+function requireProviderTurn(binding, attemptId, status) {
+    const id = identity(attemptId, "Provider input attempt id");
+    if (binding.turn === null || binding.turn.attemptId !== id || binding.turn.status !== status) {
+        throw new Error("Provider Turn does not match the expected delivery state.");
+    }
+    return binding.turn;
+}
+function orderedTurnTimestamp(turn, value, label) {
+    const normalized = timestamp(value, label);
+    if (Date.parse(normalized) < Date.parse(turn.updatedAt)) {
+        throw new Error(`${label} moved backwards.`);
+    }
+    return normalized;
+}
+function providerTurnIsActive(turn) {
+    return turn !== null && ["submitting", "accepted", "running", "delivery-unknown"]
+        .includes(turn.status);
+}
+function currentActivationUnchecked(binding) {
+    const current = binding.conversations.find((entry) => (entry.epoch === binding.currentConversationEpoch && entry.status === "current"));
+    return current === undefined ? null : [...binding.activations].reverse().find((entry) => (entry.conversationId === current.conversationId && entry.status === "active")) ?? null;
+}
 function identity(value, label) {
     if (typeof value !== "string" || value.trim().length === 0)
         throw new Error(`${label} is invalid.`);

package/dist/runtime/runtimeBinding.js

@@ -1,18 +1,23 @@
 import { normalizeRuntimeOwner } from "./runtimeOwner.js";
 import { requireSafeIdentity, requireText } from "./validation.js";
+import { validateProviderAuthorityFence } from "./providerAuthorityFence.js";
 export function createRuntimeBinding(input) {
     const hostCreated = input.hostCreated === undefined
         ? undefined
         : requireBoolean(input.hostCreated, "Runtime host-created flag");
-    const initialPromptRunId = input.initialPromptRunId === undefined
+    const initialTurnRunId = input.initialTurnRunId === undefined
         ? undefined
-        : requireSafeIdentity(input.initialPromptRunId, "Initial prompt Run id");
-    if (initialPromptRunId !== undefined && hostCreated !== true) {
-        throw new TypeError("An initial prompt Run id requires a newly-created runtime host.");
-    }
-    const launchPromptUncertainRunId = input.launchPromptUncertainRunId === undefined
+        : requireSafeIdentity(input.initialTurnRunId, "Initial Turn Run id");
+    const initialTurnDeliveryUnknownRunId = input.initialTurnDeliveryUnknownRunId === undefined
+        ? undefined
+        : requireSafeIdentity(input.initialTurnDeliveryUnknownRunId, "Delivery-unknown initial Turn Run id");
+    const initialTurnRejectedRunId = input.initialTurnRejectedRunId === undefined
         ? undefined
-        : requireSafeIdentity(input.launchPromptUncertainRunId, "Uncertain launch prompt Run id");
+        : requireSafeIdentity(input.initialTurnRejectedRunId, "Rejected initial Turn Run id");
+    if ([initialTurnRunId, initialTurnDeliveryUnknownRunId, initialTurnRejectedRunId]
+        .filter((value) => value !== undefined).length > 1) {
+        throw new TypeError("Runtime binding must report at most one initial Turn outcome.");
+    }
     return {
         id: requireSafeIdentity(input.id, "Runtime binding id"),
         launchId: requireSafeIdentity(input.launchId, "Launch id"),
@@ -21,13 +26,17 @@ export function createRuntimeBinding(input) {
         adapterId: requireSafeIdentity(input.adapterId, "Agent adapter id"),
         hostRef: requireText(input.hostRef, "Session host reference"),
         ...(hostCreated === undefined ? {} : { hostCreated }),
-        ...(initialPromptRunId === undefined ? {} : { initialPromptRunId }),
-        ...(launchPromptUncertainRunId === undefined
+        ...(initialTurnRunId === undefined ? {} : { initialTurnRunId }),
+        ...(initialTurnDeliveryUnknownRunId === undefined
             ? {}
-            : { launchPromptUncertainRunId }),
+            : { initialTurnDeliveryUnknownRunId }),
+        ...(initialTurnRejectedRunId === undefined ? {} : { initialTurnRejectedRunId }),
         ...(input.nativeSessionId === undefined
             ? {}
-            : { nativeSessionId: requireText(input.nativeSessionId, "Native session id") })
+            : { nativeSessionId: requireText(input.nativeSessionId, "Native session id") }),
+        ...(input.providerAuthority === undefined
+            ? {}
+            : { providerAuthority: validateProviderAuthorityFence(input.providerAuthority) })
     };
 }
 function requireBoolean(value, label) {