@ponythewhite/base-context 1.0.9 → 1.0.11

package/dist/core/canonical-context.js

@@ -1,5 +1,5 @@
 import { stringifyBoundedJson } from "./bounded-json.js";
-import { CONTEXT_EPOCH_DETAIL, CONTEXT_EPOCH_RENDERER, CONTEXT_POLICY_EPOCH_RENDERER, CONTEXT_SKILL_EPOCH_RENDERER, CONTEXT_TOOL_EPOCH_RENDERER, CONTEXT_TOOL_SUMMARY_RENDERER, contextEpochMode, readContextEpoch, retainedContextRequestContract, snapshotContextEpoch, } from "./context-epoch.js";
+import { CONTEXT_EPOCH_DETAIL, CONTEXT_EPOCH_RENDERER, CONTEXT_INTERRUPTED_TOOL_RENDERER, CONTEXT_POLICY_EPOCH_RENDERER, CONTEXT_SKILL_EPOCH_RENDERER, CONTEXT_TOOL_EPOCH_RENDERER, CONTEXT_TOOL_SUMMARY_RENDERER, contextEpochMode, readContextEpoch, retainedContextRequestContract, snapshotContextEpoch, } from "./context-epoch.js";
 import { createCompactionSummaryMessage, createCustomMessage } from "./messages.js";
 import { PUBLIC_CONTEXT_RENDERER, PUBLIC_TOOL_CONTINUATION_RENDERER, renderPublicHistory, renderToolContinuation, } from "./public-context.js";
 import { renderResourceView } from "./resource-view.js";
@@ -261,11 +261,13 @@ export function prepareCanonicalEpoch(messages, selectedUnitIds, representation,
     return {
         checkpoint: snapshotContextEpoch({
             version: context.toolContinuations?.length ? 6 : 4,
-            renderer: context.selectedSkills?.length
-                ? CONTEXT_SKILL_EPOCH_RENDERER
-                : context.toolContinuations?.length
-                    ? CONTEXT_TOOL_EPOCH_RENDERER
-                    : CONTEXT_EPOCH_RENDERER,
+            renderer: context.toolContinuations?.some((group) => group.calls.some((call) => call.admission === "absent"))
+                ? CONTEXT_INTERRUPTED_TOOL_RENDERER
+                : context.selectedSkills?.length
+                    ? CONTEXT_SKILL_EPOCH_RENDERER
+                    : context.toolContinuations?.length
+                        ? CONTEXT_TOOL_EPOCH_RENDERER
+                        : CONTEXT_EPOCH_RENDERER,
             ...(context.selectedSkills?.length ? { selectedSkills: context.selectedSkills } : {}),
             ...(context.toolContinuations?.length ? { toolContinuations: context.toolContinuations } : {}),
             source: context.source,
@@ -283,8 +285,27 @@ export function prepareCanonicalEpoch(messages, selectedUnitIds, representation,
         messages: chosen,
     };
 }
-/** Use only a replay contract granted to these recovery results by an actual accepted request. */
-export function canonicalRecoveryBoundary(messages) {
+/** Missing prerequisite only; source, closure and projection failures remain ordinary errors. */
+export class MissingRecoveryReplayContractError extends Error {
+    constructor() {
+        super("Recovery compaction requires an accepted replay contract for its selected results");
+        this.name = "MissingRecoveryReplayContractError";
+    }
+}
+function sameRecoverySource(left, right, ownerStillCurrent = false) {
+    return (JSON.stringify(left) === JSON.stringify(right) ||
+        (ownerStillCurrent &&
+            left.sessionId === right.sessionId &&
+            left.sessionFile === right.sessionFile &&
+            left.persistent === right.persistent));
+}
+function sameRecoveryReference(left, right, ownerStillCurrent = false) {
+    return (sameRecoverySource(left.source, right.source, ownerStillCurrent) &&
+        JSON.stringify(left.ref) === JSON.stringify(right.ref) &&
+        left.sourceRevision === right.sourceRevision);
+}
+/** Use accepted coverage, or the exact actual-projection permit of a rejected oversized candidate. */
+export function canonicalRecoveryBoundary(messages, authorization) {
     const context = compiledEpochContexts.get(messages);
     const units = getCanonicalViewUnits(messages);
     if (!context || !units)
@@ -294,18 +315,36 @@ export function canonicalRecoveryBoundary(messages) {
     const recoveries = units.flatMap((unit, index) => (unit.kind === "recovery" ? [context.references[index]] : []));
     if (!recoveries.length)
         return;
+    if (authorization) {
+        // The captured native owner may certify bookkeeping-only appends, never new context or a branch change.
+        const ownerStillCurrent = authorization.isSourceCurrent?.();
+        if (ownerStillCurrent === false ||
+            !sameRecoverySource(context.source, authorization.source, ownerStillCurrent === true) ||
+            context.resourceRevision !== authorization.resourceRevision ||
+            recoveries.length !== authorization.recoveries.length ||
+            recoveries.some((reference) => !reference ||
+                !authorization.recoveries.some((covered) => sameRecoveryReference(reference, covered, ownerStillCurrent === true))))
+            throw new Error("Recovery compaction authorization no longer matches its captured source");
+        return latestLiteralReference(context.references)?.ref.entryId;
+    }
     const checkpoint = context.checkpoint;
-    if (!checkpoint?.representation ||
-        checkpoint.replayContract !== "message-groups" ||
-        recoveries.some((reference) => !reference || reference.ref.sequence > checkpoint.source.sourceSequence))
-        throw new Error("Recovery compaction requires an accepted replay contract for its selected results");
+    const inherited = checkpoint?.includeSummary === true && checkpoint.replayContract === "message-groups";
+    if (checkpoint?.replayContract !== "message-groups" ||
+        recoveries.some((reference) => !reference ||
+            (checkpoint.representation
+                ? reference.ref.sequence > checkpoint.source.sourceSequence
+                : !inherited ||
+                    !context.inheritedRecoveryCoverage?.some((covered) => sameRecoveryReference(reference, covered)))))
+        throw new MissingRecoveryReplayContractError();
     return checkpoint.literalTailId;
 }
 /** Retain exact recovery evidence. An accepted public-window transition replaces whole old protocol groups. */
-export function prepareRecoveryCompaction(messages, firstKeptEntryId, maxBytes) {
-    const boundary = canonicalRecoveryBoundary(messages);
+export function prepareRecoveryCompaction(messages, firstKeptEntryId, maxBytes, authorization) {
+    const boundary = canonicalRecoveryBoundary(messages, authorization);
     const context = compiledEpochContexts.get(messages);
-    const publicWindow = context?.checkpoint?.publicWindow === true && context.checkpoint.replayContract === "message-groups";
+    const publicWindow = authorization
+        ? authorization.publicWindow
+        : context?.checkpoint?.publicWindow === true && context.checkpoint.replayContract === "message-groups";
     if (!boundary && !publicWindow && !context?.selectedSkills?.length && !context?.toolContinuations?.length)
         return;
     if (!context)
@@ -349,11 +388,13 @@ export function prepareRecoveryCompaction(messages, firstKeptEntryId, maxBytes)
         return;
     return snapshotContextEpoch({
         ...(toolGroups.size ? { version: 8, mode: context.mode } : { version: 4 }),
-        renderer: toolGroups.size
-            ? CONTEXT_TOOL_SUMMARY_RENDERER
-            : context.selectedSkills?.length
-                ? CONTEXT_SKILL_EPOCH_RENDERER
-                : CONTEXT_EPOCH_RENDERER,
+        renderer: context.toolContinuations?.some((group) => group.calls.some((call) => call.admission === "absent"))
+            ? CONTEXT_INTERRUPTED_TOOL_RENDERER
+            : toolGroups.size
+                ? CONTEXT_TOOL_SUMMARY_RENDERER
+                : context.selectedSkills?.length
+                    ? CONTEXT_SKILL_EPOCH_RENDERER
+                    : CONTEXT_EPOCH_RENDERER,
         ...(toolGroups.size ? { toolContinuations: context.toolContinuations } : {}),
         ...(context.selectedSkills?.length ? { selectedSkills: context.selectedSkills } : {}),
         source: context.source,
@@ -947,6 +988,12 @@ export class CanonicalContextCompiler {
         }
         const replayUnits = bindMessageReplayUnits(messages, sourceUnits, unitLimits);
         const frozenGroups = checkpoint?.toolContinuations ?? [];
+        const assistantSequences = messages
+            .flatMap((message) => {
+            const reference = epochReferences.get(message);
+            return message.role === "assistant" && reference ? [reference.ref.sequence] : [];
+        })
+            .sort((left, right) => left - right);
         const candidates = messages.flatMap((message, index) => {
             if (message.role !== "assistant")
                 return [];
@@ -962,6 +1009,8 @@ export class CanonicalContextCompiler {
                     index,
                     reference,
                     prior,
+                    nextAssistantSequence: assistantSequences.find((sequence) => sequence > reference.ref.sequence) ?? Infinity,
+                    unqualifiedIntent: false,
                     intents: new Map(),
                 },
             ];
@@ -977,21 +1026,32 @@ export class CanonicalContextCompiler {
             countBytes(metadata);
             return hydrateCapturedHistoryEntry(metadata, maxSourceBytes, view.readPayload);
         };
-        const acceptIntent = async (metadata) => {
-            if (metadata.kind !== "tool_intent" ||
-                metadata.qualification !== "native-tool-execution" ||
-                metadata.retention === "retained-import")
+        const acceptIntent = async (metadata, selected = candidates) => {
+            if (metadata.kind !== "tool_intent")
                 return;
             const hydrated = await readToolEvidence(metadata);
             const entry = hydrated.entry;
-            if (entry.type !== "tool_intent" ||
-                entry.assistant?.sessionId !== view.source.sessionId ||
-                entry.assistant.sessionFile !== view.source.sessionFile)
+            if (entry.type !== "tool_intent")
                 return;
-            const candidate = candidates.find((item) => item.reference.ref.entryId === entry.assistant?.entryId);
+            const invocation = entry.invocation;
+            const ownerMatch = selected.find((item) => item.reference.ref.entryId === entry.assistant?.entryId);
+            const candidate = ownerMatch ??
+                selected.find((item) => metadata.sequence > item.reference.ref.sequence &&
+                    metadata.sequence < item.nextAssistantSequence &&
+                    item.message.content.some((part) => part.type === "toolCall" &&
+                        part.id === invocation.toolCallId &&
+                        part.name === invocation.toolName));
             if (!candidate)
                 return;
-            const invocation = entry.invocation;
+            // A present but unqualified/copied intent is not an absence of admission.
+            if (metadata.qualification !== "native-tool-execution" ||
+                metadata.retention === "retained-import" ||
+                entry.assistant?.sessionId !== view.source.sessionId ||
+                entry.assistant.sessionFile !== view.source.sessionFile ||
+                entry.assistant.entryId !== candidate.reference.ref.entryId) {
+                candidate.unqualifiedIntent = true;
+                return;
+            }
             const call = candidate.message.content.filter((part) => part.type === "toolCall")[invocation.sourceOrder];
             if (!Number.isSafeInteger(invocation.sourceOrder) ||
                 !call ||
@@ -1004,33 +1064,49 @@ export class CanonicalContextCompiler {
                 throw new Error("Tool continuation has ambiguous original intent");
             candidate.intents.set(invocation.sourceOrder, hydrated);
         };
+        const absentPrefixes = new Map();
         for (const candidate of candidates) {
             if (!candidate.prior)
                 continue;
             if (!Array.isArray(candidate.prior.calls))
                 throw new Error("Invalid committed tool continuation");
             for (const call of candidate.prior.calls) {
+                if (call.admission === "absent") {
+                    if (checkpoint?.renderer !== CONTEXT_INTERRUPTED_TOOL_RENDERER ||
+                        !call.source ||
+                        call.source.sourceSequence < candidate.reference.ref.sequence ||
+                        call.intent !== undefined ||
+                        call.executionId !== undefined ||
+                        call.outcome !== undefined ||
+                        call.result !== undefined)
+                        throw new Error("Invalid committed absent tool admission");
+                    const key = JSON.stringify(call.source);
+                    const prefix = absentPrefixes.get(key) ?? { source: call.source, candidates: [] };
+                    if (!prefix.candidates.includes(candidate))
+                        prefix.candidates.push(candidate);
+                    absentPrefixes.set(key, prefix);
+                    continue;
+                }
                 const actual = await view.get(call.intent.id);
                 if (!actual || actual.revision !== call.intent.revision || actual.sequence !== call.intent.sequence)
                     throw new Error("Committed tool intent is unavailable on this captured branch");
-                await acceptIntent(actual);
+                await acceptIntent(actual, [candidate]);
             }
         }
-        const newGroups = candidates.filter((candidate) => !candidate.prior);
-        if (newGroups.length) {
-            let after = Math.min(...newGroups.map((candidate) => candidate.reference.ref.sequence));
+        const scanIntents = async (readView, selected) => {
+            let after = Math.min(...selected.map((candidate) => candidate.reference.ref.sequence));
             let scanned = 0;
             for (;;) {
-                const page = await view.page(after, Math.min(128, maxMessages - scanned + 1));
+                const page = await readView.page(after, Math.min(128, maxMessages - scanned + 1));
                 scanned += page.events.length;
                 if (scanned > maxMessages)
                     throw new Error("Tool continuation source item budget exceeded");
                 if (page.coverage !== "complete")
                     throw new Error("Tool continuation source coverage is incomplete");
                 for (const metadata of page.events) {
-                    // Frozen intent refs were already read exactly; do not count them twice as another execution.
-                    if (!candidates.some((candidate) => candidate.prior?.calls.some((call) => call.intent.id === metadata.id)))
-                        await acceptIntent(metadata);
+                    // Frozen qualified refs were already checked exactly, not another execution.
+                    if (!selected.some((candidate) => [...candidate.intents.values()].some((intent) => intent.source.id === metadata.id)))
+                        await acceptIntent(metadata, selected);
                 }
                 if (page.nextAfter === null)
                     break;
@@ -1038,23 +1114,69 @@ export class CanonicalContextCompiler {
                     throw new Error("Tool continuation source page did not advance");
                 after = page.nextAfter;
             }
+        };
+        const newGroups = candidates.filter((candidate) => !candidate.prior);
+        if (newGroups.length)
+            await scanIntents(view, newGroups);
+        for (const prefix of absentPrefixes.values()) {
+            if (!view.atSnapshot)
+                throw new Error("Absent tool admission requires its captured source");
+            await scanIntents(await view.atSnapshot(prefix.source), prefix.candidates);
         }
+        const checkAbsentScope = async (candidate) => {
+            const entry = next.get(candidate.reference.ref.entryId)?.entry;
+            const output = entry?.type === "message" ? entry.requestOutput : undefined;
+            // This correlation limits the public-history scope. It never qualifies a tool owner or outcome.
+            if (!output ||
+                typeof output.operationId !== "string" ||
+                !output.operationId ||
+                !Array.isArray(output.attemptIds) ||
+                output.attemptIds.some((id) => typeof id !== "string") ||
+                !output.source ||
+                output.source.sessionId !== view.source.sessionId ||
+                output.source.sessionFile !== view.source.sessionFile ||
+                !output.source.persistent ||
+                !Number.isSafeInteger(output.source.sourceSequence) ||
+                output.source.sourceSequence >= candidate.reference.ref.sequence ||
+                !view.atSnapshot)
+                throw new Error("View-unit replay group is incomplete: original tool owner is unqualified");
+            await view.atSnapshot(output.source);
+        };
         const toolContinuations = [];
         const pendingPublicMessageGroups = [];
         for (const candidate of candidates) {
             const toolCalls = candidate.message.content.filter((part) => part.type === "toolCall");
             if (!toolCalls.length ||
-                candidate.intents.size !== toolCalls.length ||
+                candidate.unqualifiedIntent ||
                 (candidate.prior && candidate.prior.calls.length !== toolCalls.length))
                 throw new Error("View-unit replay group is incomplete: original tool owner is unqualified");
+            if (candidate.intents.size !== toolCalls.length)
+                await checkAbsentScope(candidate);
             const members = [candidate.index];
             const calls = [];
             for (let order = 0; order < toolCalls.length; order++) {
                 const intent = candidate.intents.get(order);
+                const original = candidate.prior?.calls[order];
+                if (!intent) {
+                    if (original && original.admission !== "absent")
+                        throw new Error("Committed tool intent is unavailable on this captured branch");
+                    if (messages.some((message) => {
+                        const sequence = epochReferences.get(message)?.ref.sequence;
+                        return (message.role === "toolResult" &&
+                            message.toolCallId === toolCalls[order].id &&
+                            sequence !== undefined &&
+                            sequence > candidate.reference.ref.sequence &&
+                            sequence < candidate.nextAssistantSequence);
+                    }))
+                        throw new Error("Tool outcome lacks its original finalized owner");
+                    calls.push(original ?? { admission: "absent", source: { ...view.source } });
+                    continue;
+                }
+                if (original?.admission === "absent")
+                    throw new Error("Committed absent tool admission changed");
                 if (intent.entry.type !== "tool_intent")
                     throw new Error("Invalid native tool intent");
                 const invocation = intent.entry.invocation;
-                const original = candidate.prior?.calls[order];
                 if (original &&
                     (original.executionId !== invocation.executionId || original.intent.id !== intent.source.id))
                     throw new Error("Committed tool execution identity changed");
@@ -1137,10 +1259,94 @@ export class CanonicalContextCompiler {
                 units: selectionUnits,
                 limits: unitLimits,
                 ...(mode === "on" && (taskFrameRebased || checkpoint) ? { requiresEpoch: true } : {}),
+                ...(mode === "on" && sourceUnits.some((unit) => unit.kind === "recovery")
+                    ? { recoveryContractRequested: true }
+                    : {}),
                 ...(pendingPublicMessageGroups.length ? { pendingPublicMessageGroups } : {}),
             },
         });
+        const inheritedRecoveryCoverage = [];
+        if (checkpoint?.includeSummary &&
+            checkpoint.replayContract === "message-groups" &&
+            closedUnits.some((unit) => unit.kind === "recovery")) {
+            const prefix = await view.atSnapshot(checkpoint.source);
+            const suffix = new Map();
+            const frozenViews = new Map();
+            let capturedMessages = 0;
+            let retained = false;
+            let cursor;
+            for (;;) {
+                const page = await prefix.contextManifest({ cursor, limit: 128 });
+                if (page.selection !== "known")
+                    throw new Error("Summary recovery source is unavailable");
+                if (!cursor && page.summaryRef) {
+                    // The frozen source may itself have pinned views before its literal manifest.
+                    const entry = await hydrate(page.summaryRef, undefined, prefix);
+                    const metadata = await prefix.get(page.summaryRef.entryId);
+                    const prior = entry.type === "compaction" &&
+                        metadata?.qualification === "native-context-epoch" &&
+                        metadata.retention !== "retained-import"
+                        ? readContextEpoch(entry.details, maxSourceBytes)
+                        : undefined;
+                    if ((!prior || prior.includeSummary) && page.summaryRef.entryId === checkpoint.literalTailId)
+                        retained = true;
+                    capturedMessages += prior?.views.length ?? 0;
+                    for (const pinned of prior?.views ?? []) {
+                        if (pinned.ref.entryId === checkpoint.literalTailId)
+                            retained = true;
+                        if (retained) {
+                            suffix.set(pinned.ref.entryId, pinned.ref);
+                            frozenViews.set(pinned.ref.entryId, pinned);
+                        }
+                    }
+                }
+                for (const ref of page.refs) {
+                    if (ref.entryId === checkpoint.literalTailId)
+                        retained = true;
+                    if (retained)
+                        suffix.set(ref.entryId, ref);
+                }
+                capturedMessages += page.refs.length;
+                if (capturedMessages > maxMessages)
+                    throw new Error("Summary recovery source exceeds its message budget");
+                if (!page.nextCursor)
+                    break;
+                cursor = page.nextCursor;
+            }
+            for (const [index, message] of closedMessages.entries()) {
+                if (closedUnits[index].kind !== "recovery")
+                    continue;
+                const reference = epochReferences.get(message);
+                if (checkpoint.views.some((covered) => sameRecoveryReference(reference, covered))) {
+                    inheritedRecoveryCoverage.push(reference);
+                    continue;
+                }
+                const frozen = suffix.get(reference.ref.entryId);
+                if (!frozen || JSON.stringify(frozen) !== JSON.stringify(reference.ref))
+                    continue;
+                const pinned = frozenViews.get(frozen.entryId);
+                if (pinned) {
+                    if (reference.sourceRevision === pinned.sourceRevision)
+                        inheritedRecoveryCoverage.push(reference);
+                    continue;
+                }
+                const revisions = [frozen.revision];
+                const entry = next.get(frozen.entryId)?.entry;
+                if (entry?.type === "message" &&
+                    entry.message.role === "toolResult" &&
+                    entry.message.toolName === "ipython") {
+                    const updates = await prefix.contextUpdates({
+                        kind: "ipython-sent-message",
+                        toolCallId: entry.message.toolCallId,
+                    });
+                    revisions.push(...updates.refs.map((update) => update.revision));
+                }
+                if (reference.sourceRevision === JSON.stringify(revisions))
+                    inheritedRecoveryCoverage.push(reference);
+            }
+        }
         compiledEpochContexts.set(closedMessages, {
+            ...(inheritedRecoveryCoverage.length ? { inheritedRecoveryCoverage } : {}),
             ...(purpose === "read" ? { readOnly: true } : {}),
             mode,
             source: { ...view.source },