@zq-silk/yui 0.6.8 → 0.6.10

package/dist/runtime/providerRuntimeIdentity.js

@@ -0,0 +1,232 @@
+export function createProviderRuntimeBinding(input) {
+    const startedAt = timestamp(input.startedAt, "Provider Activation startedAt");
+    return validateProviderRuntimeBinding({
+        schemaVersion: 1,
+        providerNamespace: identity(input.providerNamespace, "Provider namespace"),
+        accountScope: identity(input.accountScope, "Provider account scope"),
+        runId: identity(input.runId, "Run id"),
+        currentConversationEpoch: 1,
+        conversations: [{
+                conversationId: identity(input.conversationId, "Provider Conversation id"),
+                epoch: 1,
+                status: "current",
+                recoverability: "unknown",
+                createdAt: startedAt
+            }],
+        activations: [{
+                activationId: identity(input.activationId, "Provider Activation id"),
+                conversationId: input.conversationId,
+                generation: 1,
+                status: "active",
+                writerLease: true,
+                startedAt
+            }]
+    });
+}
+export function currentProviderConversation(binding) {
+    validateProviderRuntimeBinding(binding);
+    return binding.conversations.find((entry) => (entry.epoch === binding.currentConversationEpoch && entry.status === "current"));
+}
+export function currentProviderActivation(binding) {
+    const conversation = currentProviderConversation(binding);
+    return [...binding.activations].reverse().find((entry) => (entry.conversationId === conversation.conversationId && entry.status === "active")) ?? null;
+}
+export function startProviderActivation(raw, input) {
+    const binding = validateProviderRuntimeBinding(raw);
+    if (currentProviderActivation(binding) !== null) {
+        throw new Error("Provider Conversation already has a live writer Activation.");
+    }
+    const conversation = currentProviderConversation(binding);
+    const generation = binding.activations
+        .filter((entry) => entry.conversationId === conversation.conversationId)
+        .reduce((maximum, entry) => Math.max(maximum, entry.generation), 0) + 1;
+    return validateProviderRuntimeBinding({
+        ...binding,
+        activations: [...binding.activations, {
+                activationId: identity(input.activationId, "Provider Activation id"),
+                conversationId: conversation.conversationId,
+                generation,
+                status: "active",
+                writerLease: true,
+                startedAt: timestamp(input.startedAt, "Provider Activation startedAt")
+            }]
+    });
+}
+export function endProviderActivation(raw, activationId, input) {
+    const binding = validateProviderRuntimeBinding(raw);
+    const id = identity(activationId, "Provider Activation id");
+    const target = binding.activations.find((entry) => entry.activationId === id);
+    if (target === undefined)
+        throw new Error(`Provider Activation is not recorded: ${id}.`);
+    if (target.status !== "active")
+        return binding;
+    const endedAt = timestamp(input.endedAt, "Provider Activation endedAt");
+    if (Date.parse(endedAt) < Date.parse(target.startedAt)) {
+        throw new Error("Provider Activation endedAt is earlier than startedAt.");
+    }
+    return validateProviderRuntimeBinding({
+        ...binding,
+        activations: binding.activations.map((entry) => entry.activationId === id
+            ? {
+                ...entry,
+                status: input.status,
+                writerLease: false,
+                endedAt,
+                ...(input.reason === undefined
+                    ? {}
+                    : { terminalReason: identity(input.reason, "Provider Activation terminal reason") })
+            }
+            : entry)
+    });
+}
+export function updateProviderConversationRecoverability(raw, recoverability) {
+    const binding = validateProviderRuntimeBinding(raw);
+    const current = currentProviderConversation(binding);
+    return validateProviderRuntimeBinding({
+        ...binding,
+        conversations: binding.conversations.map((entry) => entry.epoch === current.epoch
+            ? { ...entry, recoverability }
+            : entry)
+    });
+}
+export function supersedeProviderConversation(raw, input) {
+    const binding = validateProviderRuntimeBinding(raw);
+    const current = currentProviderConversation(binding);
+    if (current.recoverability !== "unrecoverable") {
+        throw new Error("Current Provider Conversation is not exactly unrecoverable.");
+    }
+    if (!input.noUnsettledInputDelivery) {
+        throw new Error("Cannot replace a Provider Conversation with unsettled input delivery.");
+    }
+    if (!input.writerUmbrellaClear || 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");
+    const epoch = current.epoch + 1;
+    return validateProviderRuntimeBinding({
+        ...binding,
+        currentConversationEpoch: epoch,
+        conversations: [
+            ...binding.conversations.map((entry) => entry.epoch === current.epoch
+                ? { ...entry, status: "superseded", supersededAt: switchedAt }
+                : entry),
+            {
+                conversationId: identity(input.conversationId, "Provider Conversation id"),
+                epoch,
+                status: "current",
+                recoverability: "unknown",
+                createdAt: switchedAt
+            }
+        ],
+        activations: [...binding.activations, {
+                activationId: identity(input.activationId, "Provider Activation id"),
+                conversationId: input.conversationId,
+                generation: 1,
+                status: "active",
+                writerLease: true,
+                startedAt: switchedAt
+            }]
+    });
+}
+export function validateProviderRuntimeBinding(value) {
+    if (value.schemaVersion !== 1)
+        throw new Error("Provider Runtime Binding schemaVersion must be 1.");
+    identity(value.providerNamespace, "Provider namespace");
+    identity(value.accountScope, "Provider account scope");
+    identity(value.runId, "Run id");
+    integer(value.currentConversationEpoch, 1, "Current Provider Conversation epoch");
+    if (!Array.isArray(value.conversations) || value.conversations.length === 0) {
+        throw new Error("Provider Runtime Binding requires a Conversation.");
+    }
+    const conversationIds = new Set();
+    const epochs = new Set();
+    let currentCount = 0;
+    for (const conversation of value.conversations) {
+        identity(conversation.conversationId, "Provider Conversation id");
+        integer(conversation.epoch, 1, "Provider Conversation epoch");
+        if (conversationIds.has(conversation.conversationId) || epochs.has(conversation.epoch)) {
+            throw new Error("Provider Runtime Binding contains duplicate Conversation identity.");
+        }
+        conversationIds.add(conversation.conversationId);
+        epochs.add(conversation.epoch);
+        if (conversation.status !== "current" && conversation.status !== "superseded") {
+            throw new Error("Provider Conversation status is invalid.");
+        }
+        if (!["unknown", "recoverable", "unrecoverable"].includes(conversation.recoverability)) {
+            throw new Error("Provider Conversation recoverability is invalid.");
+        }
+        timestamp(conversation.createdAt, "Provider Conversation createdAt");
+        if (conversation.status === "current") {
+            currentCount += 1;
+            if (conversation.epoch !== value.currentConversationEpoch) {
+                throw new Error("Current Provider Conversation epoch is inconsistent.");
+            }
+            if (conversation.supersededAt !== undefined) {
+                throw new Error("Current Provider Conversation cannot be superseded.");
+            }
+        }
+        else if (conversation.supersededAt === undefined) {
+            throw new Error("Superseded Provider Conversation requires supersededAt.");
+        }
+        else {
+            timestamp(conversation.supersededAt, "Provider Conversation supersededAt");
+        }
+    }
+    if (currentCount !== 1)
+        throw new Error("Provider Runtime Binding requires one current Conversation.");
+    const activationIds = new Set();
+    const activeByConversation = new Set();
+    const generations = new Set();
+    for (const activation of value.activations) {
+        identity(activation.activationId, "Provider Activation id");
+        if (activationIds.has(activation.activationId)) {
+            throw new Error("Provider Runtime Binding contains duplicate Activation identity.");
+        }
+        activationIds.add(activation.activationId);
+        if (!conversationIds.has(activation.conversationId)) {
+            throw new Error("Provider Activation references an unknown Conversation.");
+        }
+        integer(activation.generation, 1, "Provider Activation generation");
+        const generationKey = `${activation.conversationId}\u0000${activation.generation}`;
+        if (generations.has(generationKey)) {
+            throw new Error("Provider Runtime Binding contains duplicate Activation generation.");
+        }
+        generations.add(generationKey);
+        if (!["active", "ended", "failed"].includes(activation.status)) {
+            throw new Error("Provider Activation status is invalid.");
+        }
+        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 (activeByConversation.has(activation.conversationId)) {
+                throw new Error("Provider Conversation has multiple live writer Activations.");
+            }
+            activeByConversation.add(activation.conversationId);
+        }
+        else {
+            if (activation.writerLease || activation.endedAt === undefined) {
+                throw new Error("Terminal Provider Activation must release its writer lease.");
+            }
+            timestamp(activation.endedAt, "Provider Activation endedAt");
+        }
+    }
+    return value;
+}
+function identity(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`${label} is invalid.`);
+    return value.trim();
+}
+function timestamp(value, label) {
+    const normalized = identity(value, label);
+    if (!Number.isFinite(Date.parse(normalized)))
+        throw new Error(`${label} must be a timestamp.`);
+    return normalized;
+}
+function integer(value, minimum, label) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+        throw new Error(`${label} is invalid.`);
+    return value;
+}

package/dist/runtime/providerRuntimeReconciler.js

@@ -0,0 +1,166 @@
+import { continuationOwnsWriterUmbrella, observeProviderContinuation, providerContinuationKey } from "./providerContinuation.js";
+const BASE_RECONCILE_MS = 2_000;
+const MAX_RECONCILE_MS = 5 * 60_000;
+const CIRCUIT_ERROR_LIMIT = 5;
+const QUERY_TIMEOUT_MS = 5_000;
+/**
+ * Reconciles only already-known children, grouped under one Conversation and
+ * Activation generation. Missing entries settle ownership only for an exact
+ * snapshot; partial/unavailable absence is never terminal evidence.
+ */
+export async function reconcileKnownDetachedContinuations(input) {
+    const candidates = input.continuations.filter((entry) => (entry.attachment === "detached" && continuationOwnsWriterUmbrella(entry)));
+    if (candidates.length === 0) {
+        return { continuations: input.continuations, schedule: null, quality: "exact", changed: false };
+    }
+    const first = candidates[0];
+    const groupKey = [
+        first.identity.providerNamespace,
+        first.identity.accountScope,
+        first.identity.conversationId,
+        first.identity.activationId
+    ].join("\u0000");
+    if (candidates.some((entry) => [
+        entry.identity.providerNamespace,
+        entry.identity.accountScope,
+        entry.identity.conversationId,
+        entry.identity.activationId
+    ].join("\u0000") !== groupKey)) {
+        throw new Error("Provider reconcile input must contain one Conversation/Activation group.");
+    }
+    const nowMs = input.now.getTime();
+    if (input.previous?.circuitOpenUntil !== undefined
+        && Date.parse(input.previous.circuitOpenUntil) > nowMs) {
+        return {
+            continuations: input.continuations,
+            schedule: input.previous,
+            quality: "unavailable",
+            changed: false
+        };
+    }
+    let result;
+    try {
+        const raw = await withTimeout(input.port.queryKnownContinuations({
+            providerNamespace: first.identity.providerNamespace,
+            accountScope: first.identity.accountScope,
+            conversationId: first.identity.conversationId,
+            activationId: first.identity.activationId,
+            continuations: Object.freeze(candidates.map((entry) => Object.freeze({
+                continuationId: entry.identity.continuationId,
+                generation: entry.identity.generation
+            })))
+        }), QUERY_TIMEOUT_MS);
+        result = validateQueryResult(raw, new Set(candidates.map((entry) => (providerContinuationKey(entry.identity)))));
+    }
+    catch {
+        const errors = (input.previous?.consecutiveErrors ?? 0) + 1;
+        const delay = backoff(input.previous?.attempts ?? 0);
+        const circuitOpenUntil = errors >= CIRCUIT_ERROR_LIMIT
+            ? new Date(nowMs + MAX_RECONCILE_MS).toISOString()
+            : undefined;
+        return {
+            continuations: input.continuations,
+            schedule: {
+                key: groupKey,
+                attempts: (input.previous?.attempts ?? 0) + 1,
+                consecutiveErrors: errors,
+                nextReconcileAt: new Date(nowMs + delay).toISOString(),
+                ...(circuitOpenUntil === undefined ? {} : { circuitOpenUntil })
+            },
+            quality: "unavailable",
+            changed: false
+        };
+    }
+    const observations = new Map(result.continuations.map((entry) => [entry.key, entry]));
+    let changed = false;
+    const updated = input.continuations.map((continuation) => {
+        const observed = observations.get(providerContinuationKey(continuation.identity));
+        if (observed === undefined) {
+            // Exact absence closes a known child mechanically, without inventing a
+            // successful outcome or ResultRef. Partial absence preserves ownership.
+            if (result.quality !== "exact")
+                return continuation;
+            const next = observeProviderContinuation(continuation, {
+                execution: "quiescent",
+                outcome: "unknown",
+                attachment: "detached",
+                observation: "exact",
+                mayWriteWorkspace: false,
+                observedAt: input.now.toISOString()
+            });
+            changed ||= next !== continuation;
+            return next;
+        }
+        const next = observeProviderContinuation(continuation, {
+            execution: observed.execution,
+            outcome: observed.outcome,
+            attachment: "detached",
+            observation: result.quality,
+            mayWriteWorkspace: observed.mayWriteWorkspace,
+            observedAt: input.now.toISOString(),
+            ...(observed.resultRef === undefined ? {} : { resultRef: observed.resultRef }),
+            ...(observed.providerSequence === undefined
+                ? {}
+                : { providerSequence: observed.providerSequence })
+        });
+        changed ||= next !== continuation;
+        return next;
+    });
+    const unsettled = updated.some((entry) => (entry.attachment === "detached" && continuationOwnsWriterUmbrella(entry)));
+    return {
+        continuations: Object.freeze(updated),
+        schedule: unsettled
+            ? {
+                key: groupKey,
+                attempts: (input.previous?.attempts ?? 0) + 1,
+                consecutiveErrors: 0,
+                nextReconcileAt: new Date(nowMs + backoff(input.previous?.attempts ?? 0)).toISOString()
+            }
+            : null,
+        quality: result.quality,
+        changed
+    };
+}
+function validateQueryResult(input, expectedKeys) {
+    if (input === null || typeof input !== "object"
+        || !["exact", "partial", "unavailable"].includes(input.quality)
+        || !Array.isArray(input.continuations)) {
+        throw new Error("Provider continuation metadata response is invalid.");
+    }
+    const seen = new Set();
+    for (const entry of input.continuations) {
+        if (entry === null || typeof entry !== "object"
+            || typeof entry.key !== "string" || !expectedKeys.has(entry.key)
+            || seen.has(entry.key)
+            || !["active", "quiescent", "unknown"].includes(entry.execution)
+            || !["pending", "succeeded", "failed", "cancelled", "unknown"].includes(entry.outcome)
+            || typeof entry.mayWriteWorkspace !== "boolean"
+            || (entry.execution === "active" && entry.outcome !== "pending")
+            || (entry.execution === "quiescent" && entry.outcome === "pending")
+            || (entry.providerSequence !== undefined
+                && (!Number.isSafeInteger(entry.providerSequence) || entry.providerSequence < 0))) {
+            throw new Error("Provider continuation metadata entry is invalid or conflicting.");
+        }
+        seen.add(entry.key);
+    }
+    return input;
+}
+async function withTimeout(promise, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error("Provider continuation metadata query timed out.")), timeoutMs);
+                timer.unref?.();
+            })
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function backoff(attempts) {
+    return Math.min(MAX_RECONCILE_MS, BASE_RECONCILE_MS * (2 ** Math.min(attempts, 8)));
+}

package/dist/runtime/runtimeContinuationProjection.js

@@ -0,0 +1,34 @@
+import { foldContinuationObservation } from "./continuationManager.js";
+import { continuationOwnsWriterUmbrella, providerContinuationKey } from "./providerContinuation.js";
+import { runtimeObservationFromTaskEvent } from "./runtimeObservation.js";
+export function projectProviderContinuations(events) {
+    const projected = new Map();
+    const observations = events
+        .map(runtimeObservationFromTaskEvent)
+        .filter((entry) => (entry !== null && entry.kind.startsWith("continuation.")));
+    // Fold in durable Task-event order. Provider sequence is an identity-local
+    // monotonic fence applied by ProviderContinuation; it is not a global clock.
+    // In particular, Controller-derived exact snapshots intentionally have no
+    // Provider sequence and must not be moved before the Provider start fact.
+    for (const observation of observations) {
+        const fence = observation.fence;
+        if (fence.conversationId === undefined || fence.activationId === undefined
+            || fence.continuationId === undefined || fence.continuationGeneration === undefined) {
+            continue;
+        }
+        const key = [
+            fence.driverId,
+            fence.agentId,
+            fence.conversationId,
+            fence.activationId,
+            fence.continuationId,
+            fence.continuationGeneration
+        ].join("\u0000");
+        const result = foldContinuationObservation(projected.get(key) ?? null, observation);
+        projected.set(providerContinuationKey(result.continuation.identity), result.continuation);
+    }
+    return Object.freeze([...projected.values()].sort((left, right) => (providerContinuationKey(left.identity).localeCompare(providerContinuationKey(right.identity)))));
+}
+export function blockingProviderContinuations(events) {
+    return projectProviderContinuations(events).filter((entry) => (continuationOwnsWriterUmbrella(entry) || entry.identityConflict));
+}