@askdkc/kiokuko 0.1.17 → 0.1.20

package/dist/context/broker.js

@@ -1,21 +1,103 @@
-import { createHash, randomUUID } from 'node:crypto';
 import { KiokukoError } from '../errors.js';
-import { readAkinatorSession, readRunIntakeLink } from '../akinator/store.js';
-import { listContextDeliveries, readContextDelivery, recordContextDelivery } from './delivery.js';
-import { listContextFeedback } from './feedback.js';
+import { withImmediateTransaction } from '../db/transaction.js';
+import { listContextDeliveries, readContextDelivery, recordContextDeliveryInTransaction, } from './delivery.js';
+import { contextFeedbackSignals } from './feedback.js';
 import { buildRecommendations, RECOMMENDATION_POLICY_VERSION } from './recommendations.js';
-import { CONTEXT_RANKING_VERSION, rankContextCandidates } from './ranking.js';
-import { searchEntries } from '../memory/retrieval.js';
+import { CONTEXT_RANKING_VERSION, CONTEXT_SELECTION_REASON_ORDER, rankContextCandidates } from './ranking.js';
+import { rankedEntryHits } from '../memory/retrieval.js';
+import { readEntry } from '../memory/entries.js';
+import { decodeStoredStructuredScope, readEntryRevision } from '../memory/revisions.js';
 import { federatedEntries } from '../memory/federated-retrieval.js';
-import { projectLedger } from '../ledger/projection.js';
-import { LedgerStore } from '../ledger/store.js';
-import { prepareOfficialSourceSync, persistOfficialSourceSync } from '../knowledge/sources.js';
-import { canonicalContentHash } from '../serialization/validate.js';
+import { isRetrievableEntry } from '../memory/hybrid-retrieval.js';
+import { GLOBAL_WORKSPACE } from '../memory/workspaces.js';
+import { effectiveRetrievalScope, hasExplicitApplicability } from '../memory/structured-memory.js';
+import { canonicalContentHash, compareCanonicalStrings } from '../serialization/validate.js';
+import { entryOriginMatchesWorkspace } from './origin.js';
+import { isExternalSkillReference } from '../skills/store.js';
+import { contextRetrievalStateHash } from './selection-state.js';
+import { readContextRunRetrievalState } from './run-state.js';
+import { captureProjectManifestSnapshot, resolveProjectFingerprint, } from '../repository/project-fingerprint.js';
 export const CONTEXT_BROKER_POLICY_VERSION = `${CONTEXT_RANKING_VERSION}+${RECOMMENDATION_POLICY_VERSION}`;
 export const CONTEXT_BROKER_DEFAULT_LIMIT = 20;
 export const CONTEXT_BROKER_MAX_LIMIT = 100;
 export const CONTEXT_BROKER_DEFAULT_CHARACTER_BUDGET = 8_000;
 export const CONTEXT_BROKER_MAX_CHARACTER_BUDGET = 100_000;
+function normalizedGateDecision(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError('Context broker gate returned an invalid decision');
+    }
+    const prototype = Object.getPrototypeOf(value);
+    const keys = Reflect.ownKeys(value);
+    if ((prototype !== Object.prototype && prototype !== null)
+        || keys.some((key) => typeof key !== 'string'
+            || key !== 'persist' && key !== 'value' && key !== 'assertBeforePersist')
+        || !keys.includes('persist')
+        || !keys.includes('value')) {
+        throw new TypeError('Context broker gate returned an invalid decision');
+    }
+    const persistDescriptor = Object.getOwnPropertyDescriptor(value, 'persist');
+    const resultDescriptor = Object.getOwnPropertyDescriptor(value, 'value');
+    const assertionDescriptor = Object.getOwnPropertyDescriptor(value, 'assertBeforePersist');
+    if (persistDescriptor === undefined
+        || !Object.hasOwn(persistDescriptor, 'value')
+        || typeof persistDescriptor.value !== 'boolean'
+        || resultDescriptor === undefined
+        || !Object.hasOwn(resultDescriptor, 'value')
+        || assertionDescriptor !== undefined
+            && (!Object.hasOwn(assertionDescriptor, 'value') || typeof assertionDescriptor.value !== 'function')) {
+        throw new TypeError('Context broker gate returned an invalid decision');
+    }
+    return {
+        persist: persistDescriptor.value,
+        value: resultDescriptor.value,
+        ...(assertionDescriptor === undefined
+            ? {}
+            : { assertBeforePersist: assertionDescriptor.value }),
+    };
+}
+function contextDeliverySnapshotHash(delivery) {
+    return canonicalContentHash({
+        workspace: delivery.workspace,
+        deliveryId: delivery.deliveryId,
+        runId: delivery.runId,
+        throughSequence: delivery.throughSequence,
+        intakeSessionId: delivery.intakeSessionId,
+        taskProfileHash: delivery.taskProfileHash,
+        queryHash: delivery.queryHash,
+        policyVersion: delivery.policyVersion,
+        charBudget: delivery.charBudget,
+        charCount: delivery.charCount,
+        truncated: delivery.truncated,
+        createdAt: delivery.createdAt,
+        scoreSchemaVersion: delivery.scoreSchemaVersion ?? 1,
+        items: delivery.items.map((item) => ({
+            entryId: item.entryId,
+            entryRevision: item.entryRevision,
+            rank: item.rank,
+            scoreComponents: item.scoreComponents,
+            selectionReasons: item.selectionReasons,
+            ...(item.origin === undefined ? {} : { origin: item.origin }),
+        })),
+    });
+}
+function assertReplayDeliveryUnchanged(database, expected) {
+    let current;
+    try {
+        current = readContextDelivery(database, {
+            workspace: expected.workspace,
+            deliveryId: expected.deliveryId,
+        });
+    }
+    catch (error) {
+        if (error instanceof KiokukoError && error.code === 'NOT_FOUND') {
+            throw new KiokukoError('INTEGRITY_ERROR', 'Stored context delivery disappeared during replay');
+        }
+        throw error;
+    }
+    if (contextDeliverySnapshotHash(current) !== contextDeliverySnapshotHash(expected)) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context delivery changed during replay');
+    }
+}
 function invalid() {
     throw new KiokukoError('VALIDATION_ERROR', 'Context query input is invalid');
 }
@@ -73,58 +155,50 @@ function normalizeInput(input) {
         ...(value.characterBudget === undefined ? {} : { characterBudget: value.characterBudget }),
     };
 }
-function parseEventRows(store, runId) {
-    return store.readEvents(runId).map((row) => {
-        let payload;
-        try {
-            payload = JSON.parse(String(row.payload_json));
-        }
-        catch {
-            throw new KiokukoError('INTEGRITY_ERROR', 'Stored ledger payload is invalid');
-        }
-        const snapshot = {
-            eventId: String(row.event_id),
-            sequence: Number(row.sequence),
-            eventType: row.event_type,
-            ...(row.outcome === null ? {} : { outcome: row.outcome }),
-            ...(payload === undefined ? {} : { payload: payload }),
-        };
-        return snapshot;
-    });
+function normalizePersistence(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError('Context broker persistence adapter is invalid');
+    }
+    const object = value;
+    const prototype = Object.getPrototypeOf(object);
+    const keys = Reflect.ownKeys(object);
+    const descriptor = Object.getOwnPropertyDescriptor(object, 'enqueueWrite');
+    if ((prototype !== Object.prototype && prototype !== null)
+        || keys.some((key) => key !== 'enqueueWrite')
+        || descriptor !== undefined && !Object.hasOwn(descriptor, 'value')) {
+        throw new TypeError('Context broker persistence adapter is invalid');
+    }
+    const enqueueWrite = descriptor?.value;
+    if (enqueueWrite !== undefined && typeof enqueueWrite !== 'function') {
+        throw new TypeError('Context broker persistence adapter is invalid');
+    }
+    return enqueueWrite === undefined
+        ? {}
+        : { enqueueWrite: enqueueWrite };
 }
 function currentRunContext(database, runId) {
-    const run = new LedgerStore(database).readRun(runId);
-    if (!run)
-        notFound();
-    const link = readRunIntakeLink(database, { workspace: run.workspace, runId });
-    const session = readAkinatorSession(database, { workspace: run.workspace, sessionId: link.sessionId });
-    const status = session.status;
-    if (status === 'active') {
-        return {
-            run,
-            profile: session.profile,
-            profileHash: link.initialProfileHash ?? canonicalContentHash(session.profile),
-            recommendedTags: [...link.recommendedTags],
-            intakeSessionId: link.sessionId,
-            intakeStatus: status,
-            projection: null,
-        };
+    try {
+        return readContextRunRetrievalState(database, runId);
     }
-    const projection = projectLedger({
-        initialProfile: session.profile,
-        intakeStatus: status,
-        coverage: run.coverage,
-        throughSequence: run.lastSequence,
-        events: parseEventRows(new LedgerStore(database), runId),
-    });
+    catch (error) {
+        if (error instanceof KiokukoError
+            && error.code === 'NOT_FOUND'
+            && error.message === 'Context run was not found') {
+            notFound();
+        }
+        throw error;
+    }
+}
+/** Read the same authoritative run/intake/profile snapshot used to rank broker context. */
+export function readContextBrokerRunState(database, runId) {
+    const current = currentRunContext(database, runId);
     return {
-        run,
-        profile: projection.taskProfile,
-        profileHash: projection.profileHash,
-        recommendedTags: [...link.recommendedTags],
-        intakeSessionId: link.sessionId,
-        intakeStatus: status,
-        projection,
+        run: current.run,
+        taskProfile: { ...current.profile },
+        profileHash: current.profileHash,
+        recommendedTags: [...current.recommendedTags],
+        intakeSessionId: current.intakeSessionId,
+        status: current.intakeStatus === 'active' ? 'needs_answer' : current.intakeStatus,
     };
 }
 function preparedQuery(database, input) {
@@ -137,6 +211,21 @@ function preparedQuery(database, input) {
     const throughSequence = runContext?.run.lastSequence ?? 0;
     const taskProfileHash = runContext?.profileHash ?? canonicalContentHash(profile);
     const recommendedTags = runContext?.recommendedTags ?? input.recommendedTags ?? [];
+    const workspace = runContext?.run.workspace ?? requestedWorkspace;
+    const project = projectForWorkspace(database, workspace);
+    const projectState = project === undefined
+        ? null
+        : {
+            project,
+            fingerprint: resolveProjectFingerprint(database, project, captureProjectManifestSnapshot(project)),
+        };
+    const includeEcosystem = projectState !== null;
+    const selectionWorkspaces = !includeEcosystem
+        ? [workspace]
+        : [workspace, GLOBAL_WORKSPACE];
+    const retrievalStateHash = runContext === null || runContext.intakeStatus !== 'active'
+        ? contextRetrievalStateHash(database, selectionWorkspaces, { includeEcosystem })
+        : null;
     const queryShape = {
         runId: input.runId ?? null,
         workspace: input.runId === undefined ? requestedWorkspace : null,
@@ -148,10 +237,15 @@ function preparedQuery(database, input) {
         throughSequence,
         characterBudget: input.characterBudget ?? CONTEXT_BROKER_DEFAULT_CHARACTER_BUDGET,
         limit: input.limit ?? CONTEXT_BROKER_DEFAULT_LIMIT,
+        projectState,
+        retrievalStateHash,
+        runStateHash: runContext?.stateHash ?? null,
     };
     const queryHash = canonicalContentHash(queryShape);
     return {
-        workspace: runContext?.run.workspace ?? requestedWorkspace,
+        workspace,
+        selectionWorkspaces,
+        includeEcosystem,
         run: runContext?.run ?? null,
         taskProfile: profile,
         profileHash: taskProfileHash,
@@ -165,11 +259,16 @@ function preparedQuery(database, input) {
         intakeSessionId: runContext?.intakeSessionId ?? null,
         projection: runContext?.projection ?? null,
         runStatus: runContext === null ? 'unbound' : runContext.intakeStatus === 'active' ? 'needs_answer' : runContext.intakeStatus,
+        projectState,
+        retrievalStateHash,
+        runStateHash: runContext?.stateHash ?? null,
+        deliveryHistoryStateHash: null,
+        deliveryHistoryExcludeQueryHash: null,
         queryHash,
-        deliveryId: input.runId === undefined ? null : `context-${queryHash}`,
+        deliveryId: null,
     };
 }
-function entrySnapshot(entry, origin) {
+function entrySnapshot(entry, origin, selectionReasons = []) {
     return {
         id: entry.id,
         revision: entry.revision,
@@ -183,6 +282,7 @@ function entrySnapshot(entry, origin) {
         tags: [...entry.tags],
         scope: entry.scope,
         updatedAt: entry.updatedAt,
+        selectionReasons: [...selectionReasons],
         ...(origin === undefined ? {} : { origin }),
     };
 }
@@ -190,13 +290,48 @@ function retrievalQuery(query) {
     const values = [query.task, query.taskProfile.target, query.taskProfile.expected, ...query.recommendedTags].filter((value) => value !== null && value.length > 0);
     return values.join(' ').slice(0, 16_384) || 'kiokuko';
 }
+const APPLICABILITY_DETAIL_REASONS = new Set([
+    'language_match',
+    'database_match',
+    'runtime_match',
+    'tool_match',
+    'platform_match',
+    'framework_exact_match',
+    'framework_match',
+]);
+function canonicalRetrievedReasons(reasons) {
+    const normalized = reasons.map((reason) => {
+        if (APPLICABILITY_DETAIL_REASONS.has(reason))
+            return 'applicability_match';
+        if (CONTEXT_SELECTION_REASON_ORDER.includes(reason))
+            return reason;
+        throw new KiokukoError('INTEGRITY_ERROR', 'Retrieval returned an unknown selection reason');
+    });
+    const rank = (reason) => CONTEXT_SELECTION_REASON_ORDER.indexOf(reason);
+    return [...new Set(normalized)].sort((left, right) => rank(left) - rank(right) || compareCanonicalStrings(left, right));
+}
+function addRetrievedEntry(entries, value) {
+    const existing = entries.get(value.entry.id);
+    entries.set(value.entry.id, {
+        ...value,
+        selectionReasons: canonicalRetrievedReasons([...(existing?.selectionReasons ?? []), ...value.selectionReasons]),
+    });
+}
 function projectForWorkspace(database, workspace) {
     const row = database.prepare(`
     SELECT r.repository_id AS repositoryId, r.workspace, l.canonical_root AS repositoryRoot
       FROM repositories AS r JOIN repository_locations AS l ON l.repository_id = r.repository_id
-     WHERE r.workspace = ? ORDER BY l.last_seen_at DESC LIMIT 1
+     WHERE r.workspace = ? ORDER BY l.last_seen_at DESC, l.canonical_root ASC LIMIT 1
   `).get(workspace);
-    return row === undefined ? undefined : { repositoryRoot: row.repositoryRoot, repositoryId: row.repositoryId, workspace: row.workspace, source: 'location' };
+    if (row === undefined)
+        return undefined;
+    const { repositoryId, repositoryRoot, workspace: storedWorkspace } = row;
+    if (typeof repositoryId !== 'string' || repositoryId.length === 0
+        || typeof storedWorkspace !== 'string' || storedWorkspace !== workspace
+        || typeof repositoryRoot !== 'string' || repositoryRoot.length === 0) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context project binding is invalid');
+    }
+    return { repositoryRoot, repositoryId, workspace: storedWorkspace, source: 'location' };
 }
 async function retrieveEntries(database, query) {
     const terms = [query.task, query.taskProfile.target, query.taskProfile.expected, ...query.recommendedTags]
@@ -204,62 +339,154 @@ async function retrieveEntries(database, query) {
         .map((value) => value.slice(0, 2_000));
     const queries = [retrievalQuery(query), ...terms];
     const entries = new Map();
-    const project = projectForWorkspace(database, query.workspace);
     for (const value of queries) {
-        if (project !== undefined) {
-            for (const hit of await federatedEntries(database, { project, query: value, limit: 500 }))
-                entries.set(hit.entry.id, { entry: hit.entry, origin: hit.origin });
+        if (query.projectState !== null) {
+            for (const hit of await federatedEntries(database, {
+                project: query.projectState.project,
+                fingerprint: query.projectState.fingerprint,
+                query: value,
+                limit: 500,
+            })) {
+                addRetrievedEntry(entries, { entry: hit.entry, origin: hit.origin, selectionReasons: hit.selectionReasons });
+            }
         }
         else {
-            for (const entry of searchEntries(database, { workspace: query.workspace, query: value, limit: 500, includeSuperseded: false }).items)
-                entries.set(entry.id, { entry, origin: 'project' });
+            for (const hit of rankedEntryHits(database, { workspace: query.workspace, query: value, limit: 500, includeSuperseded: false }).hits) {
+                addRetrievedEntry(entries, {
+                    entry: readEntry(database, { workspace: query.workspace, entryId: hit.entryId }),
+                    origin: 'project',
+                    selectionReasons: ['project_origin', ...hit.reasons],
+                });
+            }
         }
     }
     return [...entries.values()];
 }
+function assertPreparedProjectState(database, query) {
+    const currentProject = projectForWorkspace(database, query.workspace);
+    if (query.projectState === null) {
+        if (currentProject !== undefined) {
+            throw new KiokukoError('CONFLICT', 'Context project state changed after ranking');
+        }
+        return;
+    }
+    if (currentProject === undefined
+        || canonicalContentHash(currentProject) !== canonicalContentHash(query.projectState.project)) {
+        throw new KiokukoError('CONFLICT', 'Context project state changed after ranking');
+    }
+    const manifestSnapshot = captureProjectManifestSnapshot(currentProject);
+    if (manifestSnapshot.manifestDigest !== query.projectState.fingerprint.manifestDigest) {
+        throw new KiokukoError('CONFLICT', 'Context project state changed after ranking');
+    }
+    const currentFingerprint = resolveProjectFingerprint(database, currentProject, manifestSnapshot, { readOnly: true });
+    if (canonicalContentHash(currentFingerprint) !== canonicalContentHash(query.projectState.fingerprint)) {
+        throw new KiokukoError('CONFLICT', 'Context project state changed after ranking');
+    }
+}
 async function rank(database, query, prior) {
     const entries = await retrieveEntries(database, query);
+    const feedback = entries.flatMap(({ entry }) => contextFeedbackSignals(database, entry.id).flatMap((signal) => Array.from({ length: signal.boundedInfluence }, () => ({ entryId: entry.id, verdict: signal.verdict }))));
     return rankContextCandidates({
         taskProfile: query.taskProfile,
         recommendedTags: query.recommendedTags,
         changedPaths: query.changedPaths,
         errorSignatures: query.errorSignatures,
         priorDelivered: prior.delivered,
-        feedback: prior.feedback,
-        candidates: entries.map(({ entry, origin }) => entrySnapshot(entry, origin)),
+        feedback,
+        candidates: entries.map(({ entry, origin, selectionReasons }) => entrySnapshot(entry, origin, selectionReasons)),
         limit: query.limit,
         characterBudget: query.characterBudget,
     });
 }
-function priorData(database, query) {
+function priorData(database, query, options = {}) {
     if (query.run === null)
-        return { delivered: [], feedback: [], stale: [] };
+        return { delivered: [], stale: [], stateHash: null };
     const deliveries = [];
     let cursor;
+    let complete = false;
     for (let page = 0; page < 10; page += 1) {
         const result = listContextDeliveries(database, { workspace: query.workspace, runId: query.run.runId, limit: 100, ...(cursor === undefined ? {} : { cursor }) });
         deliveries.push(...result.items);
-        if (result.nextCursor === null)
+        if (result.nextCursor === null) {
+            complete = true;
             break;
+        }
         cursor = result.nextCursor;
     }
-    const delivered = deliveries.flatMap((delivery) => delivery.items.map((item) => ({ entryId: item.entryId, revision: item.entryRevision })));
-    const feedbackPage = listContextFeedback(database, { workspace: query.workspace, runId: query.run.runId, limit: 100 });
-    const feedback = feedbackPage.records.map((record) => ({ entryId: record.entryId, verdict: record.verdict }));
-    const stale = deliveries.flatMap((delivery) => delivery.items.flatMap((item) => {
+    if (!complete) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Context delivery history exceeds the broker policy bound');
+    }
+    for (const delivery of deliveries) {
+        for (const item of delivery.items) {
+            currentRetrievableDeliveryEntry(database, query.workspace, item);
+        }
+    }
+    const stateDeliveries = deliveries.filter((delivery) => delivery.deliveryId !== options.excludeDeliveryId);
+    const delivered = stateDeliveries
+        .filter((delivery) => delivery.queryHash !== options.excludeDeliveredQueryHash)
+        .flatMap((delivery) => delivery.items.flatMap((item) => contextFeedbackSignals(database, item.entryId)
+        .some((signal) => signal.verdict === 'helpful')
+        ? []
+        : [{ entryId: item.entryId, revision: item.entryRevision }]));
+    const stale = stateDeliveries.flatMap((delivery) => delivery.items.flatMap((item) => {
         const current = database.prepare('SELECT current_revision FROM entries WHERE id = ?').get(item.entryId);
         return current && Number(current.current_revision) > item.entryRevision ? [{ entryId: item.entryId, deliveredRevision: item.entryRevision, currentRevision: Number(current.current_revision), stale: true }] : [];
     }));
-    return { delivered, feedback, stale };
+    return {
+        delivered,
+        stale,
+        stateHash: canonicalContentHash({
+            runId: query.run.runId,
+            excludeDeliveredQueryHash: options.excludeDeliveredQueryHash ?? null,
+            deliveries: stateDeliveries.map(contextDeliverySnapshotHash),
+            delivered,
+            stale,
+        }),
+    };
+}
+function historyAttestedDeliveryId(query, historyStateHash, excludeDeliveredQueryHash) {
+    return `context-${canonicalContentHash({
+        kind: 'context-delivery-history-attestation-v1',
+        queryHash: query.queryHash,
+        historyStateHash,
+        excludeDeliveredQueryHash,
+    })}`;
+}
+function deliveryHistoryExclusionForReplay(database, query, deliveryId) {
+    if (query.run === null)
+        return null;
+    const priorSameQuery = database.prepare(`
+    SELECT 1 AS present
+      FROM context_deliveries
+     WHERE run_id = ? AND query_hash = ? AND delivery_id <> ?
+     LIMIT 1
+  `).get(query.run.runId, query.queryHash, deliveryId);
+    if (priorSameQuery === undefined)
+        return null;
+    if (priorSameQuery.present !== 1) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context delivery history is invalid');
+    }
+    return query.queryHash;
+}
+function deliveryHistoryIsAttested(database, query, delivery) {
+    const excludeDeliveredQueryHash = deliveryHistoryExclusionForReplay(database, query, delivery.deliveryId);
+    const history = priorData(database, query, {
+        ...(excludeDeliveredQueryHash === null ? {} : { excludeDeliveredQueryHash }),
+        excludeDeliveryId: delivery.deliveryId,
+    });
+    if (history.stateHash === null) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context delivery history is invalid');
+    }
+    return delivery.deliveryId === historyAttestedDeliveryId(query, history.stateHash, excludeDeliveredQueryHash);
 }
 function outputContext(query, items, delivery) {
     const sourceItems = items.map((item, index) => ({
         entryId: item.entryId,
         entryRevision: item.revision,
         rank: index + 1,
-        scoreComponents: item.scoreComponents,
+        scoreComponents: { ...item.scoreComponents },
         selectionReasons: [...item.selectionReasons],
-        content: item.content,
+        content: { ...item.content },
         untrusted: true,
         ...(item.origin === undefined ? {} : { origin: item.origin }),
     }));
@@ -274,12 +501,12 @@ function outputContext(query, items, delivery) {
         untrusted: true,
     };
 }
-function deliveryInput(query, ranked, summary) {
+function deliveryInput(query, ranked) {
     const items = ranked.map((item, index) => ({
         entryId: item.entryId,
         entryRevision: item.revision,
         rank: index + 1,
-        scoreComponents: item.scoreComponents,
+        scoreComponents: { ...item.scoreComponents },
         selectionReasons: [...item.selectionReasons],
         ...(item.origin === undefined ? {} : { origin: item.origin }),
     }));
@@ -294,7 +521,6 @@ function deliveryInput(query, ranked, summary) {
         taskProfileHash: query.profileHash,
         queryHash: query.queryHash,
         policyVersion: CONTEXT_BROKER_POLICY_VERSION,
-        externalSyncSummary: summary,
         charBudget: query.characterBudget,
         charCount,
         truncated,
@@ -302,19 +528,74 @@ function deliveryInput(query, ranked, summary) {
         items,
     };
 }
-function emptyExternalSummary() {
-    return { attempted: false, imported: 0, sources: [] };
+function currentRetrievableDeliveryEntry(database, runWorkspace, item) {
+    const candidate = database.prepare('SELECT workspace FROM entries WHERE id = ?')
+        .get(item.entryId);
+    if (candidate === undefined) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context entry is missing');
+    }
+    if (typeof candidate.workspace !== 'string' || candidate.workspace.length === 0) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context entry is invalid');
+    }
+    const origin = item.origin ?? 'project';
+    let deliveredRevision;
+    try {
+        deliveredRevision = readEntryRevision(database, {
+            workspace: candidate.workspace,
+            entryId: item.entryId,
+            revision: item.entryRevision,
+        });
+    }
+    catch (error) {
+        if (error instanceof KiokukoError && error.code === 'NOT_FOUND') {
+            throw new KiokukoError('INTEGRITY_ERROR', 'Stored context entry revision is missing');
+        }
+        throw error;
+    }
+    const deliveredScope = decodeStoredStructuredScope(deliveredRevision.scope, origin !== 'project').canonicalScope;
+    if (!entryOriginMatchesWorkspace({ origin, runWorkspace, entryWorkspace: deliveredRevision.workspace })) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context entry origin is invalid');
+    }
+    if (origin === 'global'
+        && (deliveredScope.visibility !== 'global' || effectiveRetrievalScope(deliveredScope) !== 'global')) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context entry scope is invalid');
+    }
+    if (origin === 'ecosystem'
+        && (!Object.hasOwn(deliveredScope, 'retrievalScope')
+            || effectiveRetrievalScope(deliveredScope) !== 'ecosystem'
+            || !hasExplicitApplicability(deliveredScope))) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context entry scope is invalid');
+    }
+    if (isExternalSkillReference(deliveredRevision)) {
+        const mappings = database.prepare('SELECT COUNT(*) AS count FROM external_skill_entries WHERE entry_id = ?')
+            .get(item.entryId)?.count;
+        if (typeof mappings !== 'number' || !Number.isSafeInteger(mappings) || mappings < 1) {
+            throw new KiokukoError('INTEGRITY_ERROR', 'Stored context external entry mapping is missing');
+        }
+    }
+    const entry = readEntry(database, { workspace: candidate.workspace, entryId: item.entryId }, { requireStructuredScope: origin !== 'project' });
+    const retrievable = isRetrievableEntry(database, entry);
+    if (entry.revision !== item.entryRevision)
+        return null;
+    if (!retrievable)
+        return null;
+    if (entry.status === 'superseded')
+        return null;
+    return entry;
 }
 function storedContext(database, query, delivery) {
     let remaining = query.characterBudget;
+    let totalCharacterCount = 0;
+    let anyTruncated = false;
     const items = delivery.items.map((item) => {
-        const entry = database.prepare(`
-      SELECT r.entry_id AS id, r.revision, r.title, r.summary, r.body
-        FROM entry_revisions AS r
-       WHERE r.entry_id = ? AND r.revision = ?
-    `).get(item.entryId, item.entryRevision);
-        if (!entry)
-            throw new KiokukoError('INTEGRITY_ERROR', 'Stored context entry is missing');
+        const current = currentRetrievableDeliveryEntry(database, query.workspace, item);
+        if (current === null)
+            throw new KiokukoError('INTEGRITY_ERROR', 'Stored context entry is no longer retrievable');
+        const entry = readEntryRevision(database, {
+            entryId: item.entryId,
+            workspace: current.workspace,
+            revision: item.entryRevision,
+        });
         const take = (value, budget) => Array.from(value).slice(0, Math.max(0, budget)).join('');
         const count = (value) => Array.from(value).length;
         const title = take(entry.title, remaining);
@@ -323,6 +604,12 @@ function storedContext(database, query, delivery) {
         remaining -= count(summary ?? '');
         const bodyPreview = take(entry.body, remaining);
         remaining -= count(bodyPreview);
+        const characterCount = count(title) + count(summary ?? '') + count(bodyPreview);
+        const truncated = count(title) < count(entry.title)
+            || (entry.summary !== null && count(summary ?? '') < count(entry.summary))
+            || count(bodyPreview) < count(entry.body);
+        totalCharacterCount += characterCount;
+        anyTruncated ||= truncated;
         return {
             entryId: item.entryId,
             entryRevision: item.entryRevision,
@@ -333,13 +620,16 @@ function storedContext(database, query, delivery) {
                 title,
                 summary,
                 bodyPreview,
-                characterCount: title.length + (summary?.length ?? 0) + bodyPreview.length,
-                truncated: title.length < entry.title.length || (entry.summary !== null && summary?.length !== entry.summary.length) || bodyPreview.length < entry.body.length,
+                characterCount,
+                truncated,
             },
             untrusted: true,
             ...(item.origin === undefined ? {} : { origin: item.origin }),
         };
     });
+    if (totalCharacterCount !== delivery.charCount || anyTruncated !== delivery.truncated) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context character accounting is invalid');
+    }
     return {
         deliveryId: delivery.deliveryId,
         runId: delivery.runId,
@@ -351,13 +641,87 @@ function storedContext(database, query, delivery) {
         untrusted: true,
     };
 }
+function storedDeliveryIsRetrievable(database, query, delivery) {
+    if (delivery.throughSequence !== query.throughSequence) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored context delivery sequence is invalid');
+    }
+    if (!delivery.items.every((item) => currentRetrievableDeliveryEntry(database, query.workspace, item) !== null))
+        return false;
+    return !(delivery.taskProfileHash !== query.profileHash
+        || delivery.queryHash !== query.queryHash
+        || delivery.policyVersion !== CONTEXT_BROKER_POLICY_VERSION
+        || (delivery.scoreSchemaVersion ?? 1) !== 1
+        || delivery.charBudget !== query.characterBudget
+        || delivery.items.length > query.limit);
+}
+function assertPreparedSelectedEntries(database, query, result) {
+    if (result.context !== null
+        && result.context.items.some((item) => currentRetrievableDeliveryEntry(database, query.workspace, item) === null)) {
+        throw new KiokukoError('CONFLICT', 'Context delivery selection changed before return');
+    }
+}
+function assertPreparedBrokerState(database, query, result, expectedHistoryStateHash = query.deliveryHistoryStateHash) {
+    assertPreparedProjectState(database, query);
+    if (query.run === null) {
+        if (query.retrievalStateHash !== null
+            && contextRetrievalStateHash(database, query.selectionWorkspaces, { includeEcosystem: query.includeEcosystem }) !== query.retrievalStateHash) {
+            throw new KiokukoError('CONFLICT', 'Context selection state changed after ranking');
+        }
+        return;
+    }
+    const current = currentRunContext(database, query.run.runId);
+    const currentStatus = current.intakeStatus === 'active' ? 'needs_answer' : current.intakeStatus;
+    if (query.runStateHash === null
+        || current.stateHash !== query.runStateHash
+        || current.run.workspace !== query.workspace
+        || current.run.status !== query.run.status
+        || current.run.lastSequence !== query.throughSequence
+        || current.intakeSessionId !== query.intakeSessionId
+        || currentStatus !== query.runStatus
+        || current.profileHash !== query.profileHash
+        || canonicalContentHash([...current.recommendedTags].sort()) !== canonicalContentHash([...query.recommendedTags].sort())) {
+        throw new KiokukoError('CONFLICT', 'Context delivery conflicts with current run state');
+    }
+    if (result.context !== null && query.run.status !== 'active') {
+        throw new KiokukoError('CONFLICT', 'Context delivery conflicts with current run state');
+    }
+    assertPreparedSelectedEntries(database, query, result);
+    if (query.retrievalStateHash !== null
+        && contextRetrievalStateHash(database, query.selectionWorkspaces, { includeEcosystem: query.includeEcosystem }) !== query.retrievalStateHash) {
+        throw new KiokukoError('CONFLICT', 'Context selection state changed after ranking');
+    }
+    if (expectedHistoryStateHash !== null) {
+        const currentHistory = priorData(database, query, query.deliveryHistoryExcludeQueryHash === null
+            ? {}
+            : { excludeDeliveredQueryHash: query.deliveryHistoryExcludeQueryHash });
+        if (currentHistory.stateHash !== expectedHistoryStateHash) {
+            throw new KiokukoError('CONFLICT', 'Context delivery history changed after ranking');
+        }
+    }
+}
+function replayableDelivery(database, query) {
+    if (query.run === null)
+        return { delivery: null, found: false };
+    const rows = database.prepare(`
+    SELECT delivery_id AS deliveryId
+      FROM context_deliveries
+     WHERE run_id = ? AND query_hash = ?
+     ORDER BY delivery_id ASC
+  `).all(query.run.runId, query.queryHash);
+    for (const row of rows) {
+        const delivery = readContextDelivery(database, { workspace: query.workspace, deliveryId: row.deliveryId });
+        if (storedDeliveryIsRetrievable(database, query, delivery)
+            && deliveryHistoryIsAttested(database, query, delivery)) {
+            return { delivery, found: true };
+        }
+    }
+    return { delivery: null, found: rows.length > 0 };
+}
 export class ContextBroker {
     database;
-    options;
     inFlight = new Map();
-    constructor(database, options = {}) {
+    constructor(database) {
         this.database = database;
-        this.options = options;
     }
     listDeliveries(input) {
         const context = currentRunContext(this.database, input.runId);
@@ -372,6 +736,20 @@ export class ContextBroker {
         };
     }
     async query(rawInput, persistence = {}) {
+        return this.execute(rawInput, normalizePersistence(persistence));
+    }
+    async queryGated(rawInput, decide, persistence = {}) {
+        const normalizedPersistence = normalizePersistence(persistence);
+        const input = normalizeInput(rawInput);
+        const query = preparedQuery(this.database, input);
+        const prepared = await this.prepareResult(query);
+        const decision = normalizedGateDecision(decide(prepared.result));
+        const broker = decision.persist
+            ? await this.persistPrepared(prepared, normalizedPersistence, query, decision.assertBeforePersist)
+            : this.validatePrepared(prepared, query, decision.assertBeforePersist);
+        return { broker, value: decision.value };
+    }
+    async execute(rawInput, persistence) {
         const input = normalizeInput(rawInput);
         const query = preparedQuery(this.database, input);
         const previous = this.inFlight.get(query.queryHash);
@@ -388,6 +766,10 @@ export class ContextBroker {
         }
     }
     async queryPrepared(query, persistence) {
+        const prepared = await this.prepareResult(query);
+        return this.persistPrepared(prepared, persistence, query);
+    }
+    async prepareResult(query) {
         const base = {
             status: query.runStatus,
             taskProfile: { ...query.taskProfile },
@@ -398,63 +780,140 @@ export class ContextBroker {
             projection: query.projection,
             context: null,
             recommendations: query.projection === null ? [] : buildRecommendations({ projection: query.projection, broker: {} }),
-            externalSyncSummary: emptyExternalSummary(),
         };
         if (query.runStatus === 'needs_answer')
-            return base;
-        const prior = priorData(this.database, query);
-        const existing = query.deliveryId === null ? null : (() => {
-            try {
-                return readContextDelivery(this.database, { workspace: query.workspace, deliveryId: query.deliveryId });
-            }
-            catch (error) {
-                if (error instanceof KiokukoError && error.code === 'NOT_FOUND')
-                    return null;
-                throw error;
-            }
-        })();
-        if (existing) {
+            return { result: base, replayDelivery: null, pendingDelivery: null };
+        const replay = replayableDelivery(this.database, query);
+        const excludeDeliveredQueryHash = replay.delivery === null && replay.found ? query.queryHash : undefined;
+        const prior = priorData(this.database, query, excludeDeliveredQueryHash === undefined
+            ? {}
+            : { excludeDeliveredQueryHash });
+        query.deliveryHistoryStateHash = prior.stateHash;
+        query.deliveryHistoryExcludeQueryHash = excludeDeliveredQueryHash ?? null;
+        if (replay.delivery !== null) {
             return {
-                ...base,
-                context: storedContext(this.database, query, existing),
-                externalSyncSummary: existing.externalSyncSummary,
-                recommendations: query.projection === null ? [] : buildRecommendations({ projection: query.projection, broker: { staleDeliveredEntries: prior.stale } }),
+                result: {
+                    ...base,
+                    context: storedContext(this.database, query, replay.delivery),
+                    recommendations: query.projection === null ? [] : buildRecommendations({ projection: query.projection, broker: { staleDeliveredEntries: prior.stale } }),
+                },
+                replayDelivery: replay.delivery,
+                pendingDelivery: null,
             };
         }
-        let ranked = await rank(this.database, query, prior);
-        let externalSyncSummary = emptyExternalSummary();
-        if (ranked.length < query.limit && query.taskProfile !== undefined && this.options.allowExternalSkillFallback === true) {
-            const prepared = await prepareOfficialSourceSync({
-                workspace: query.workspace,
-                task: query.task,
-                profile: query.taskProfile,
-                recommendedTags: query.recommendedTags,
-                ...(this.options.fetchImpl === undefined ? {} : { fetchImpl: this.options.fetchImpl }),
-            });
-            const result = persistence.persistSources === undefined
-                ? persistOfficialSourceSync(this.database, { workspace: query.workspace, prepared })
-                : await persistence.persistSources(query.workspace, prepared);
-            externalSyncSummary = { attempted: result.attempted, imported: result.imported, sources: result.sources };
-            ranked = await rank(this.database, query, priorData(this.database, query));
+        const ranked = await rank(this.database, query, prior);
+        if (query.run !== null && prior.stateHash === null) {
+            throw new KiokukoError('INTEGRITY_ERROR', 'Stored context delivery history is invalid');
         }
+        const deliveryQuery = query.run === null
+            ? query
+            : {
+                ...query,
+                deliveryId: historyAttestedDeliveryId(query, prior.stateHash, query.deliveryHistoryExcludeQueryHash),
+            };
         const recommendations = query.projection === null
             ? []
             : buildRecommendations({ projection: query.projection, broker: { staleDeliveredEntries: prior.stale } });
-        const context = outputContext(query, ranked, null);
-        if (query.deliveryId === null || query.run === null) {
-            return { ...base, context, recommendations, externalSyncSummary };
+        const context = outputContext(deliveryQuery, ranked, null);
+        if (deliveryQuery.deliveryId === null || deliveryQuery.run === null) {
+            return { result: { ...base, context, recommendations }, replayDelivery: null, pendingDelivery: null };
         }
-        const deliveryRequest = deliveryInput(query, ranked, externalSyncSummary);
-        const delivery = persistence.persistDelivery === undefined
-            ? recordContextDelivery(this.database, deliveryRequest)
-            : await persistence.persistDelivery(deliveryRequest);
-        return { ...base, context: outputContext(query, ranked, delivery), recommendations, externalSyncSummary };
+        const deliveryRequest = deliveryInput(deliveryQuery, ranked);
+        return {
+            result: { ...base, context, recommendations },
+            replayDelivery: null,
+            pendingDelivery: { query: deliveryQuery, ranked, input: deliveryRequest },
+        };
+    }
+    async persistPrepared(prepared, persistence, query, assertBeforePersist) {
+        if (prepared.pendingDelivery === null) {
+            return withImmediateTransaction(this.database, () => {
+                if (prepared.replayDelivery !== null) {
+                    assertPreparedSelectedEntries(this.database, query, prepared.result);
+                    assertReplayDeliveryUnchanged(this.database, prepared.replayDelivery);
+                }
+                assertPreparedBrokerState(this.database, query, prepared.result);
+                if (assertBeforePersist !== undefined) {
+                    assertBeforePersist();
+                    if (prepared.replayDelivery !== null) {
+                        assertPreparedSelectedEntries(this.database, query, prepared.result);
+                        assertReplayDeliveryUnchanged(this.database, prepared.replayDelivery);
+                    }
+                    assertPreparedBrokerState(this.database, query, prepared.result);
+                }
+                return prepared.result;
+            });
+        }
+        const pendingDelivery = prepared.pendingDelivery;
+        let committedDelivery = null;
+        let committedHistoryStateHash = null;
+        let invocationCount = 0;
+        let acceptingInvocation = true;
+        const persist = () => {
+            if (!acceptingInvocation) {
+                throw new KiokukoError('INTEGRITY_ERROR', 'Context broker write adapter invoked persistence outside its queue operation');
+            }
+            invocationCount += 1;
+            if (invocationCount !== 1) {
+                throw new KiokukoError('INTEGRITY_ERROR', 'Context broker write adapter invoked persistence more than once');
+            }
+            committedDelivery = withImmediateTransaction(this.database, () => {
+                assertPreparedBrokerState(this.database, query, prepared.result);
+                if (assertBeforePersist !== undefined) {
+                    assertBeforePersist();
+                    assertPreparedBrokerState(this.database, query, prepared.result);
+                }
+                const delivery = recordContextDeliveryInTransaction(this.database, pendingDelivery.input);
+                committedHistoryStateHash = priorData(this.database, query, query.deliveryHistoryExcludeQueryHash === null
+                    ? {}
+                    : { excludeDeliveredQueryHash: query.deliveryHistoryExcludeQueryHash }).stateHash;
+                return delivery;
+            });
+            return committedDelivery;
+        };
+        let returned;
+        try {
+            returned = persistence.enqueueWrite === undefined
+                ? persist()
+                : await persistence.enqueueWrite(persist);
+        }
+        finally {
+            acceptingInvocation = false;
+        }
+        const committed = committedDelivery;
+        const committedHistory = committedHistoryStateHash;
+        if (invocationCount !== 1 || committed === null || committedHistory === null || returned !== committed) {
+            throw new KiokukoError('INTEGRITY_ERROR', 'Context broker write adapter returned an invalid result');
+        }
+        withImmediateTransaction(this.database, () => {
+            assertReplayDeliveryUnchanged(this.database, committed);
+            if (!deliveryHistoryIsAttested(this.database, query, committed)) {
+                throw new KiokukoError('CONFLICT', 'Context delivery history changed after ranking');
+            }
+            assertPreparedBrokerState(this.database, query, prepared.result, committedHistory);
+        });
+        return {
+            ...prepared.result,
+            context: outputContext(pendingDelivery.query, pendingDelivery.ranked, committed),
+        };
+    }
+    validatePrepared(prepared, query, assertBeforeReturn) {
+        return withImmediateTransaction(this.database, () => {
+            if (prepared.replayDelivery !== null) {
+                assertPreparedSelectedEntries(this.database, query, prepared.result);
+                assertReplayDeliveryUnchanged(this.database, prepared.replayDelivery);
+            }
+            assertPreparedBrokerState(this.database, query, prepared.result);
+            if (assertBeforeReturn !== undefined) {
+                assertBeforeReturn();
+                if (prepared.replayDelivery !== null) {
+                    assertPreparedSelectedEntries(this.database, query, prepared.result);
+                    assertReplayDeliveryUnchanged(this.database, prepared.replayDelivery);
+                }
+                assertPreparedBrokerState(this.database, query, prepared.result);
+            }
+            return prepared.result;
+        });
     }
-}
-export function contextBrokerQueryHash(input) {
-    return createHash('sha256').update(JSON.stringify(input), 'utf8').digest('hex');
-}
-export function newContextDeliveryId() {
-    return `context-${randomUUID()}`;
 }
 //# sourceMappingURL=broker.js.map