@askdkc/kiokuko 0.1.17 → 0.1.19

package/dist/context/scoped-broker.js

@@ -1,15 +1,66 @@
-import { canonicalContentHash } from '../serialization/validate.js';
+import { KiokukoError } from '../errors.js';
+import { canonicalContentHash, compareCanonicalStrings } from '../serialization/validate.js';
+import { readEntry } from '../memory/entries.js';
+import { decodeStoredStructuredScope, readEntryRevision } from '../memory/revisions.js';
 import { ensureGlobalWorkspace, GLOBAL_WORKSPACE, resolveProjectWorkspace } from '../memory/workspaces.js';
 import { federatedEntries } from '../memory/federated-retrieval.js';
-import { recordContextDelivery } from './delivery.js';
-import { readRunIntakeLink } from '../akinator/store.js';
+import { isRetrievableEntry } from '../memory/hybrid-retrieval.js';
+import { effectiveRetrievalScope, hasExplicitApplicability } from '../memory/structured-memory.js';
+import { readContextDelivery, recordContextDeliveryInTransaction } from './delivery.js';
 import { CONTEXT_SELECTION_REASON_ORDER } from './ranking.js';
-export const SCOPED_CONTEXT_POLICY_VERSION = 'context-ranking-v3';
+import { withImmediateTransaction } from '../db/transaction.js';
+import { contextFeedbackSignals } from './feedback.js';
+import { captureProjectManifestSnapshot, resolveProjectFingerprint, } from '../repository/project-fingerprint.js';
+import { entryOriginMatchesWorkspace } from './origin.js';
+import { isExternalSkillReference } from '../skills/store.js';
+import { contextRetrievalStateHash, ordinaryContextSelectionStateHash } from './selection-state.js';
+import { readContextRunRetrievalState } from './run-state.js';
+export const SCOPED_CONTEXT_POLICY_VERSION = 'context-ranking-v4';
+export const SCOPED_CONTEXT_DEFAULT_CHARACTER_BUDGET = 8_000;
+export const SCOPED_CONTEXT_MAX_CHARACTER_BUDGET = 100_000;
+function normalizedScopedGateDecision(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError('Scoped context 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('Scoped context 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('Scoped context gate returned an invalid decision');
+    }
+    return {
+        persist: persistDescriptor.value,
+        value: resultDescriptor.value,
+        ...(assertionDescriptor === undefined
+            ? {}
+            : { assertBeforePersist: assertionDescriptor.value }),
+    };
+}
 const MAX_LIMIT = 100;
-const MAX_BUDGET = 100_000;
 function normalize(value) {
     return value.normalize('NFKC').toLowerCase();
 }
+function characterCount(value) {
+    return Array.from(value).length;
+}
+function takeCharacters(value, limit) {
+    return Array.from(value).slice(0, Math.max(0, limit)).join('');
+}
 function textFor(query) {
     return [
         query.task,
@@ -60,7 +111,7 @@ function applicabilityScore(entry, queryText, origin) {
         conflict: false,
     };
 }
-function entryScore(entry, origin, retrieval, exact, query, queryText) {
+function entryScore(entry, origin, retrieval, exact, queryText) {
     const scope = origin;
     const status = entry.status === 'verified' ? 100 : entry.status === 'candidate' ? 40 : 0;
     const trust = entry.trustLevel === 'system_verified' ? 30 : entry.trustLevel === 'source_verified' ? 25 : entry.trustLevel === 'user_asserted' ? 15 : 0;
@@ -76,7 +127,7 @@ function entryScore(entry, origin, retrieval, exact, query, queryText) {
         origin: scope,
         title: entry.title,
         summary: entry.summary,
-        bodyPreview: entry.summary ?? entry.body,
+        bodyPreview: entry.body,
         score,
         scoreComponents: {
             status,
@@ -99,51 +150,378 @@ function entryScore(entry, origin, retrieval, exact, query, queryText) {
     };
 }
 function feedbackScore(database, entryId) {
-    const rows = database.prepare(`
-    SELECT verdict, COUNT(DISTINCT run_id) AS runs
-    FROM context_feedback
-    WHERE entry_id = ?
-    GROUP BY verdict
-  `).all(entryId);
     let score = 0;
     const reasons = [];
-    for (const row of rows) {
-        const influence = Math.min(2, Number(row.runs));
-        if (row.verdict === 'helpful') {
-            score += 3 * influence;
+    for (const signal of contextFeedbackSignals(database, entryId)) {
+        if (signal.verdict === 'helpful') {
+            score += 3 * signal.boundedInfluence;
             reasons.push('helpful_feedback');
         }
-        if (row.verdict === 'irrelevant') {
-            score -= 2 * influence;
+        if (signal.verdict === 'irrelevant') {
+            score -= 2 * signal.boundedInfluence;
             reasons.push('irrelevant_feedback');
         }
-        if (row.verdict === 'stale') {
-            score -= 3 * influence;
+        if (signal.verdict === 'stale') {
+            score -= 3 * signal.boundedInfluence;
             reasons.push('stale_feedback');
         }
-        if (row.verdict === 'conflicting') {
-            score -= 3 * influence;
+        if (signal.verdict === 'conflicting') {
+            score -= 3 * signal.boundedInfluence;
             reasons.push('conflicting_feedback');
         }
     }
     return { score: Math.max(-6, Math.min(6, score)), reasons };
 }
-export async function queryScopedContext(database, raw) {
-    const project = raw.project ?? await resolveProjectWorkspace(database, raw.cwd);
+function assertScopedSelectionState(database, workspaces, expectedHash) {
+    if (contextRetrievalStateHash(database, workspaces, { includeEcosystem: workspaces.length > 0 }) !== expectedHash) {
+        throw new KiokukoError('CONFLICT', 'Scoped context catalog changed after ranking');
+    }
+}
+function fitScopedItems(ordered, limit, characterBudget) {
+    const items = [];
+    let remaining = characterBudget;
+    let truncated = false;
+    for (const item of ordered) {
+        if (items.length >= limit) {
+            truncated = true;
+            break;
+        }
+        const metadataCost = characterCount(item.title) + characterCount(item.summary ?? '');
+        if (metadataCost > remaining) {
+            if (items.length === 0) {
+                throw new KiokukoError('VALIDATION_ERROR', 'Scoped context character budget cannot fit candidate metadata');
+            }
+            truncated = true;
+            break;
+        }
+        const bodyPreview = takeCharacters(item.bodyPreview, remaining - metadataCost);
+        if (characterCount(bodyPreview) < characterCount(item.bodyPreview))
+            truncated = true;
+        const cost = metadataCost + characterCount(bodyPreview);
+        items.push({
+            ...item,
+            bodyPreview,
+            scoreComponents: { ...item.scoreComponents },
+            selectionReasons: [...item.selectionReasons],
+        });
+        remaining -= cost;
+    }
+    return { items, charCount: characterBudget - remaining, truncated };
+}
+function scopedRunContext(database, runId) {
+    if (runId === undefined)
+        return null;
+    let state;
+    try {
+        state = readContextRunRetrievalState(database, runId);
+    }
+    catch (error) {
+        if (error instanceof KiokukoError && error.code === 'NOT_FOUND') {
+            throw new KiokukoError('VALIDATION_ERROR', 'Scoped context run is invalid');
+        }
+        throw error;
+    }
+    return {
+        runId,
+        workspace: state.run.workspace,
+        status: state.run.status,
+        throughSequence: state.run.lastSequence,
+        createdAt: state.run.createdAt,
+        intakeSessionId: state.intakeSessionId,
+        profileHash: state.profileHash,
+        stateHash: state.stateHash,
+    };
+}
+function scopedDeliveryId(delivery) {
+    return `context-${canonicalContentHash({
+        kind: 'scoped-context-delivery-v1',
+        workspace: delivery.workspace,
+        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 assertScopedDeliveryIdentity(delivery) {
+    if (delivery.deliveryId !== scopedDeliveryId(delivery)) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored scoped context character accounting is invalid');
+    }
+}
+function assertScopedReplayDeliveryUnchanged(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 scoped context delivery disappeared during replay');
+        }
+        throw error;
+    }
+    assertScopedDeliveryIdentity(current);
+    if (scopedDeliveryId(current) !== scopedDeliveryId(expected)) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored scoped context delivery changed during replay');
+    }
+}
+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 scoped context entry is missing');
+    }
+    if (typeof candidate.workspace !== 'string' || candidate.workspace.length === 0) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored scoped 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 scoped 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 scoped context entry origin is invalid');
+    }
+    if (origin === 'global'
+        && (deliveredScope.visibility !== 'global' || effectiveRetrievalScope(deliveredScope) !== 'global')) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored scoped context entry scope is invalid');
+    }
+    if (origin === 'ecosystem'
+        && (!Object.hasOwn(deliveredScope, 'retrievalScope')
+            || effectiveRetrievalScope(deliveredScope) !== 'ecosystem'
+            || !hasExplicitApplicability(deliveredScope))) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored scoped 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 scoped 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 storedDeliveryIsRetrievable(database, delivery, throughSequence, taskProfileHash, limit, characterBudget) {
+    assertScopedDeliveryIdentity(delivery);
+    if (delivery.throughSequence !== throughSequence)
+        return false;
+    if (!delivery.items.every((item) => currentRetrievableDeliveryEntry(database, delivery.workspace, item) !== null))
+        return false;
+    return !(delivery.taskProfileHash !== taskProfileHash
+        || delivery.policyVersion !== SCOPED_CONTEXT_POLICY_VERSION
+        || delivery.scoreSchemaVersion !== 2
+        || delivery.charBudget !== characterBudget
+        || delivery.items.length > limit);
+}
+function replayableDelivery(database, run, queryHash, taskProfileHash, limit, characterBudget) {
+    if (run === null)
+        return null;
+    const rows = database.prepare(`
+    SELECT delivery_id AS deliveryId
+      FROM context_deliveries
+     WHERE run_id = ? AND query_hash = ?
+     ORDER BY delivery_id ASC
+  `).all(run.runId, queryHash);
+    for (const row of rows) {
+        const delivery = readContextDelivery(database, { workspace: run.workspace, deliveryId: row.deliveryId });
+        if (storedDeliveryIsRetrievable(database, delivery, run.throughSequence, taskProfileHash, limit, characterBudget))
+            return delivery;
+    }
+    return null;
+}
+function storedScopedItems(database, delivery) {
+    assertScopedDeliveryIdentity(delivery);
+    const fullItems = delivery.items.map((item) => {
+        const current = currentRetrievableDeliveryEntry(database, delivery.workspace, item);
+        if (current === null)
+            throw new KiokukoError('INTEGRITY_ERROR', 'Stored scoped context entry is no longer retrievable');
+        const revision = readEntryRevision(database, {
+            entryId: item.entryId,
+            workspace: current.workspace,
+            revision: item.entryRevision,
+        });
+        const scoreComponents = item.scoreComponents;
+        return {
+            entryId: item.entryId,
+            revision: item.entryRevision,
+            origin: item.origin ?? 'project',
+            title: revision.title,
+            summary: revision.summary,
+            bodyPreview: revision.body,
+            score: Object.values(scoreComponents).reduce((total, component) => total + component, 0),
+            scoreComponents: { ...scoreComponents },
+            selectionReasons: [...item.selectionReasons],
+            metadata: { storedData: true, untrusted: true, instructions: false },
+        };
+    });
+    const fitted = fitScopedItems(fullItems, fullItems.length || 1, delivery.charBudget);
+    if (fitted.charCount !== delivery.charCount
+        || fitted.items.length !== delivery.items.length
+        || (fitted.truncated && !delivery.truncated)) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Stored scoped context character accounting is invalid');
+    }
+    return fitted.items;
+}
+function deliveryItems(items) {
+    const allowedReasons = new Set(CONTEXT_SELECTION_REASON_ORDER);
+    return items.map((item, index) => ({
+        entryId: item.entryId,
+        entryRevision: item.revision,
+        rank: index + 1,
+        scoreComponents: { ...item.scoreComponents },
+        selectionReasons: [...new Set([
+                ...item.selectionReasons.filter((reason) => allowedReasons.has(reason)),
+                item.scoreComponents.status >= 100 ? 'verified' : 'candidate',
+            ])].sort((left, right) => CONTEXT_SELECTION_REASON_ORDER.findIndex((reason) => reason === left)
+            - CONTEXT_SELECTION_REASON_ORDER.findIndex((reason) => reason === right)),
+        ...(item.origin === 'project' ? {} : { origin: item.origin }),
+    }));
+}
+function deliveryRequest(run, taskProfileHash, queryHash, characterBudget, fitted) {
+    return {
+        workspace: run.workspace,
+        runId: run.runId,
+        throughSequence: run.throughSequence,
+        intakeSessionId: run.intakeSessionId,
+        taskProfileHash,
+        queryHash,
+        policyVersion: SCOPED_CONTEXT_POLICY_VERSION,
+        charBudget: characterBudget,
+        charCount: fitted.charCount,
+        truncated: fitted.truncated,
+        createdAt: run.createdAt,
+        scoreSchemaVersion: 2,
+        items: deliveryItems(fitted.items),
+    };
+}
+async function prepareScopedContext(database, raw) {
+    const taskProfileHash = canonicalContentHash(raw.taskProfile);
+    const run = scopedRunContext(database, raw.runId);
+    if (run !== null && run.profileHash !== taskProfileHash) {
+        throw new KiokukoError('CONFLICT', 'Scoped context task profile does not match its run');
+    }
+    const resolvedProject = raw.project ?? await resolveProjectWorkspace(database, raw.cwd);
+    const project = resolvedProject === undefined ? undefined : { ...resolvedProject };
+    if (run !== null && (project === undefined || run.workspace !== project.workspace)) {
+        throw new KiokukoError('VALIDATION_ERROR', 'Scoped context run is invalid');
+    }
+    if (raw.fingerprint !== undefined && project === undefined) {
+        throw new KiokukoError('VALIDATION_ERROR', 'Scoped context fingerprint requires a project');
+    }
+    const manifestSnapshot = project === undefined ? undefined : captureProjectManifestSnapshot(project);
+    if (raw.fingerprint !== undefined
+        && manifestSnapshot !== undefined
+        && raw.fingerprint.manifestDigest !== manifestSnapshot.manifestDigest) {
+        throw new KiokukoError('CONFLICT', 'Project manifest changed while task context was being prepared');
+    }
+    const fingerprint = project === undefined || manifestSnapshot === undefined
+        ? undefined
+        : resolveProjectFingerprint(database, project, manifestSnapshot);
+    if (raw.fingerprint !== undefined
+        && fingerprint !== undefined
+        && canonicalContentHash(raw.fingerprint) !== canonicalContentHash(fingerprint)) {
+        throw new KiokukoError('CONFLICT', 'Project manifest changed while task context was being prepared');
+    }
+    const projectState = project === undefined || fingerprint === undefined ? null : { project, fingerprint };
     ensureGlobalWorkspace(database);
     const limit = raw.limit ?? 20;
-    const characterBudget = raw.characterBudget ?? 8_000;
-    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIMIT || !Number.isSafeInteger(characterBudget) || characterBudget < 1 || characterBudget > MAX_BUDGET) {
-        throw new Error('Scoped context bounds are invalid');
+    const characterBudget = raw.characterBudget ?? SCOPED_CONTEXT_DEFAULT_CHARACTER_BUDGET;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIMIT || !Number.isSafeInteger(characterBudget) || characterBudget < 1 || characterBudget > SCOPED_CONTEXT_MAX_CHARACTER_BUDGET) {
+        throw new KiokukoError('VALIDATION_ERROR', 'Scoped context bounds are invalid');
     }
     const queryText = textFor(raw);
-    const taskProfileHash = canonicalContentHash(raw.taskProfile);
-    const queryHash = canonicalContentHash({ task: raw.task, taskProfile: raw.taskProfile, recommendedTags: raw.recommendedTags ?? [], changedPaths: raw.changedPaths ?? [], errorSignatures: raw.errorSignatures ?? [] });
+    const selectionWorkspaces = project === undefined ? [] : [project.workspace, GLOBAL_WORKSPACE];
+    const selectionStateHash = ordinaryContextSelectionStateHash(database, selectionWorkspaces, {
+        includeEcosystem: project !== undefined,
+    });
+    const retrievalStateHash = contextRetrievalStateHash(database, selectionWorkspaces, {
+        includeEcosystem: project !== undefined,
+    });
+    const queryHash = canonicalContentHash({
+        task: raw.task,
+        taskProfile: raw.taskProfile,
+        recommendedTags: raw.recommendedTags ?? [],
+        changedPaths: raw.changedPaths ?? [],
+        errorSignatures: raw.errorSignatures ?? [],
+        project: project === undefined ? null : {
+            workspace: project.workspace,
+            repositoryId: project.repositoryId,
+            repositoryRoot: project.repositoryRoot,
+            fingerprint,
+        },
+        limit,
+        characterBudget,
+        policyVersion: SCOPED_CONTEXT_POLICY_VERSION,
+        retrievalStateHash,
+        runStateHash: run?.stateHash ?? null,
+    });
+    const replay = replayableDelivery(database, run, queryHash, taskProfileHash, limit, characterBudget);
+    if (replay !== null) {
+        return {
+            result: {
+                project: project ?? null,
+                taskProfileHash,
+                queryHash,
+                policyVersion: SCOPED_CONTEXT_POLICY_VERSION,
+                items: storedScopedItems(database, replay),
+                deliveryId: replay.deliveryId,
+                truncated: replay.truncated,
+                untrusted: true,
+            },
+            replayDelivery: replay,
+            selectionStateHash,
+            retrievalStateHash,
+            selectionWorkspaces,
+            pendingDelivery: null,
+            run,
+            projectState,
+        };
+    }
     const candidates = new Map();
-    const federated = project === undefined ? [] : await federatedEntries(database, { project, query: queryText, limit: 200 });
+    const federated = project === undefined ? [] : await federatedEntries(database, {
+        project,
+        ...(fingerprint === undefined ? {} : { fingerprint }),
+        query: queryText,
+        limit: 200,
+    });
     for (const hit of federated) {
         const entry = hit.entry;
-        const item = entryScore(entry, hit.origin, hit.score, hit.selectionReasons.includes('exact_signal_match'), raw, queryText);
+        const item = entryScore(entry, hit.origin, hit.score, hit.selectionReasons.includes('exact_signal_match'), queryText);
         item.selectionReasons.push(...hit.selectionReasons);
         item.selectionReasons = [...new Set(item.selectionReasons)];
         const feedback = feedbackScore(database, entry.id);
@@ -156,86 +534,114 @@ export async function queryScopedContext(database, raw) {
         if (previous === undefined || item.score > previous.score)
             candidates.set(item.entryId, item);
     }
-    const ordered = [...candidates.values()].sort((left, right) => right.score - left.score || left.entryId.localeCompare(right.entryId));
-    const items = [];
-    let remaining = characterBudget;
-    for (const item of ordered.slice(0, limit + 1)) {
-        const body = Array.from(item.bodyPreview).slice(0, remaining).join('');
-        const cost = Array.from(item.title).length + Array.from(item.summary ?? '').length + body.length;
-        if (remaining <= 0)
-            break;
-        items.push({ ...item, bodyPreview: body, scoreComponents: { ...item.scoreComponents }, selectionReasons: [...item.selectionReasons] });
-        remaining -= cost;
-    }
-    let deliveryId = null;
-    if (raw.runId !== undefined) {
-        const run = database.prepare('SELECT run_id, workspace, last_sequence, created_at FROM ledger_runs WHERE run_id = ?').get(raw.runId);
-        if (!run || project === undefined || run.workspace !== project.workspace)
-            throw new Error('Scoped context run is invalid');
-        const link = readRunIntakeLink(database, { workspace: run.workspace, runId: raw.runId });
-        // queryHash is intentionally stable, but delivery_id is a global primary
-        // key. Include the run so the same successful reasoning path can recur in
-        // independent runs without colliding, while replay within one run remains
-        // idempotent.
-        deliveryId = `context-${canonicalContentHash({ runId: raw.runId, queryHash })}`;
-        const allowedReasons = new Set(CONTEXT_SELECTION_REASON_ORDER);
-        const deliveryItems = items.slice(0, limit).map((item, index) => ({
-            entryId: item.entryId,
-            entryRevision: item.revision,
-            rank: index + 1,
-            scoreComponents: {
-                status: item.scoreComponents.status,
-                trust: item.scoreComponents.trust,
-                confidence: item.scoreComponents.confidence,
-                retrieval: item.scoreComponents.retrieval,
-                taskAffinity: item.scoreComponents.taskAffinity,
-                recommendedTags: item.scoreComponents.recommendedTags,
-                scopeAffinity: item.scoreComponents.scopeAffinity,
-                applicability: item.scoreComponents.applicability,
-                pathOverlap: item.scoreComponents.pathOverlap,
-                errorSignature: item.scoreComponents.errorSignature,
-                exactSignal: item.scoreComponents.exactSignal,
-                feedback: item.scoreComponents.feedback,
-                recency: 0,
-                contradiction: 0,
-            },
-            selectionReasons: [...new Set([...item.selectionReasons.filter((reason) => allowedReasons.has(reason)), item.scoreComponents.status >= 100 ? 'verified' : 'candidate'])]
-                .sort((left, right) => CONTEXT_SELECTION_REASON_ORDER.findIndex((reason) => reason === left) - CONTEXT_SELECTION_REASON_ORDER.findIndex((reason) => reason === right)),
-            ...(item.origin === 'project' ? {} : { origin: item.origin }),
-        }));
-        recordContextDelivery(database, {
-            workspace: run.workspace,
-            deliveryId,
-            runId: raw.runId,
-            throughSequence: run.last_sequence,
-            intakeSessionId: link.sessionId,
+    const ordered = [...candidates.values()].sort((left, right) => right.score - left.score || compareCanonicalStrings(left.entryId, right.entryId));
+    const fitted = fitScopedItems(ordered, limit, characterBudget);
+    return {
+        result: {
+            project: project ?? null,
             taskProfileHash,
             queryHash,
             policyVersion: SCOPED_CONTEXT_POLICY_VERSION,
-            externalSyncSummary: { attempted: false, imported: 0, sources: [] },
-            charBudget: characterBudget,
-            charCount: deliveryItems.reduce((total, item) => total + (items.find((candidate) => candidate.entryId === item.entryId)?.bodyPreview.length ?? 0), 0),
-            truncated: ordered.length > limit || items.length > limit,
-            createdAt: run.created_at,
-            scoreSchemaVersion: 2,
-            items: deliveryItems,
+            items: fitted.items,
+            deliveryId: null,
+            truncated: fitted.truncated,
+            untrusted: true,
+        },
+        replayDelivery: null,
+        selectionStateHash,
+        retrievalStateHash,
+        selectionWorkspaces,
+        pendingDelivery: run === null ? null : deliveryRequest(run, taskProfileHash, queryHash, characterBudget, fitted),
+        run,
+        projectState,
+    };
+}
+function assertPreparedScopedRun(database, run) {
+    const current = readContextRunRetrievalState(database, run.runId);
+    if (run.status !== 'active'
+        || current.run.workspace !== run.workspace
+        || current.run.status !== run.status
+        || current.run.lastSequence !== run.throughSequence
+        || current.intakeSessionId !== run.intakeSessionId
+        || current.profileHash !== run.profileHash
+        || current.stateHash !== run.stateHash) {
+        throw new KiokukoError('CONFLICT', 'Scoped context run changed before persistence');
+    }
+}
+function assertPreparedScopedState(database, prepared) {
+    if (prepared.projectState !== null) {
+        const manifestSnapshot = captureProjectManifestSnapshot(prepared.projectState.project);
+        if (manifestSnapshot.manifestDigest !== prepared.projectState.fingerprint.manifestDigest) {
+            throw new KiokukoError('CONFLICT', 'Scoped context project state changed after ranking');
+        }
+        const currentFingerprint = resolveProjectFingerprint(database, prepared.projectState.project, manifestSnapshot, { readOnly: true });
+        if (canonicalContentHash(currentFingerprint) !== canonicalContentHash(prepared.projectState.fingerprint)) {
+            throw new KiokukoError('CONFLICT', 'Scoped context project state changed after ranking');
+        }
+    }
+    if (prepared.run !== null)
+        assertPreparedScopedRun(database, prepared.run);
+    const workspace = prepared.run?.workspace ?? prepared.result.project?.workspace;
+    if (workspace !== undefined && prepared.result.items.some((item) => currentRetrievableDeliveryEntry(database, workspace, {
+        entryId: item.entryId,
+        entryRevision: item.revision,
+        origin: item.origin,
+    }) === null)) {
+        throw new KiokukoError('CONFLICT', 'Scoped context selection changed before return');
+    }
+    assertScopedSelectionState(database, prepared.selectionWorkspaces, prepared.retrievalStateHash);
+    if (prepared.replayDelivery !== null) {
+        assertScopedReplayDeliveryUnchanged(database, prepared.replayDelivery);
+    }
+}
+function persistPreparedScopedContext(database, prepared, assertBeforePersist) {
+    if (prepared.pendingDelivery === null) {
+        return withImmediateTransaction(database, () => {
+            assertPreparedScopedState(database, prepared);
+            if (assertBeforePersist !== undefined) {
+                assertBeforePersist();
+                assertPreparedScopedState(database, prepared);
+            }
+            return prepared.result;
         });
     }
-    return {
-        project: project ?? null,
-        taskProfileHash,
-        queryHash,
-        policyVersion: SCOPED_CONTEXT_POLICY_VERSION,
-        items: items.slice(0, limit),
-        deliveryId,
-        truncated: ordered.length > limit || items.length > limit,
-        untrusted: true,
-    };
+    const request = prepared.pendingDelivery;
+    return withImmediateTransaction(database, () => {
+        if (prepared.run === null)
+            throw new KiokukoError('INTEGRITY_ERROR', 'Stored scoped context run is invalid');
+        assertPreparedScopedState(database, prepared);
+        if (assertBeforePersist !== undefined) {
+            assertBeforePersist();
+            assertPreparedScopedState(database, prepared);
+        }
+        const delivery = recordContextDeliveryInTransaction(database, { ...request, deliveryId: scopedDeliveryId(request) });
+        return {
+            ...prepared.result,
+            items: storedScopedItems(database, delivery),
+            deliveryId: delivery.deliveryId,
+            truncated: delivery.truncated,
+        };
+    });
 }
-export function entryOrigin(entry) {
-    return entry.workspace === GLOBAL_WORKSPACE ? 'global' : 'project';
+export async function queryScopedContext(database, raw) {
+    return persistPreparedScopedContext(database, await prepareScopedContext(database, raw));
 }
-export function structuredScope(entry) {
-    return { ...entry.scope };
+export async function queryScopedContextGated(database, raw, decide) {
+    const prepared = await prepareScopedContext(database, raw);
+    const decision = normalizedScopedGateDecision(decide(prepared.result));
+    if (!decision.persist) {
+        withImmediateTransaction(database, () => {
+            assertPreparedScopedState(database, prepared);
+            if (decision.assertBeforePersist !== undefined) {
+                decision.assertBeforePersist();
+                assertPreparedScopedState(database, prepared);
+            }
+        });
+    }
+    return {
+        context: decision.persist ? persistPreparedScopedContext(database, prepared, decision.assertBeforePersist) : null,
+        value: decision.value,
+        selectionStateHash: prepared.selectionStateHash,
+    };
 }
 //# sourceMappingURL=scoped-broker.js.map