@tenphi/akno-core 0.13.0 → 0.13.2

package/dist/write/mutation-receipts.js

@@ -0,0 +1,331 @@
+import path from 'node:path';
+import { AknoError } from '@tenphi/akno-protocol';
+import { sha256 } from "../store/ids.js";
+import { normalizeSlug } from "../ops/write.js";
+const REPLAY_SAFE_OPERATIONS = ['write', 'move', 'forget', 'folder'];
+// A process can open the same knowledge base twice because its pid already owns the write lock.
+// Key by database path as well as receipt identity so those handles still agree which call is live.
+const activeReceipts = new Set();
+const MAX_RESULT_BYTES = 64 * 1024;
+export function isReplaySafeOperation(operation) {
+    return REPLAY_SAFE_OPERATIONS.includes(operation);
+}
+/**
+ * Bind a caller-owned key before the first effect and return a completed request without
+ * reapplying it. Incomplete rows fail closed: only a process that knows it never crossed the
+ * mutation boundary may discard its reservation and let the caller try again.
+ */
+export async function executeReplaySafeMutation(ctx, operation, parsedInput, work) {
+    const { idempotency_key: key, ...operationInput } = parsedInput;
+    if (!key)
+        return work(ctx, operationInput);
+    const requestHash = mutationRequestHash(operation, operationInput);
+    const identity = receiptIdentity(ctx.config.dbPath, ctx.actor, operation, key);
+    const existing = readReceipt(ctx.store, ctx.actor, operation, key);
+    if (existing) {
+        assertSameRequest(existing, requestHash);
+        if (existing.state === 'completed') {
+            return replayResult(ctx, operation, operationInput, existing);
+        }
+        if (activeReceipts.has(identity)) {
+            throw new AknoError('busy', `${operation} with this idempotency key is still running`, {
+                operation,
+                idempotency_key: key,
+                state: existing.state,
+            });
+        }
+        throw interruptedError(existing);
+    }
+    const now = new Date().toISOString();
+    ctx.store.db
+        .prepare(`INSERT INTO mutation_receipts(
+         actor, operation, idempotency_key, request_hash, state, started_at
+       ) VALUES(?, ?, ?, ?, 'reserved', ?)`)
+        .run(ctx.actor, operation, key, requestHash, now);
+    const receipt = {
+        actor: ctx.actor,
+        operation,
+        idempotencyKey: key,
+        requestHash,
+        started: false,
+    };
+    activeReceipts.add(identity);
+    try {
+        const result = await work({ ...ctx, mutationReceipt: receipt }, operationInput);
+        if (!receipt.started && isRetryablePrecondition(result)) {
+            deleteReceipt(ctx.store, receipt);
+            return result;
+        }
+        if (receipt.started)
+            assertJournalCommit(ctx.store, receipt, result);
+        const stored = compactResult(operation, result);
+        const updated = ctx.store.db
+            .prepare(`UPDATE mutation_receipts
+            SET state = 'completed', result = ?, completed_at = ?
+          WHERE actor = ? AND operation = ? AND idempotency_key = ? AND request_hash = ?
+            AND state IN ('reserved', 'running', 'committed')`)
+            .run(stored, new Date().toISOString(), ctx.actor, operation, key, requestHash);
+        if (updated.changes !== 1) {
+            throw new AknoError('internal', `could not complete the ${operation} mutation receipt`);
+        }
+        return result;
+    }
+    catch (error) {
+        if (receipt.started) {
+            ctx.store.db
+                .prepare(`UPDATE mutation_receipts
+              SET state = 'interrupted', result = NULL, completed_at = NULL
+            WHERE actor = ? AND operation = ? AND idempotency_key = ? AND request_hash = ?
+              AND state IN ('running', 'committed')`)
+                .run(ctx.actor, operation, key, requestHash);
+        }
+        else {
+            deleteReceipt(ctx.store, receipt);
+        }
+        throw error;
+    }
+    finally {
+        activeReceipts.delete(identity);
+    }
+}
+/** Mark the durable boundary immediately before the first filesystem effect. */
+export function beginMutation(ctx) {
+    const receipt = ctx.mutationReceipt;
+    if (!receipt || receipt.started)
+        return;
+    const updated = ctx.store.db
+        .prepare(`UPDATE mutation_receipts SET state = 'running'
+        WHERE actor = ? AND operation = ? AND idempotency_key = ? AND request_hash = ?
+          AND state = 'reserved'`)
+        .run(receipt.actor, receipt.operation, receipt.idempotencyKey, receipt.requestHash);
+    if (updated.changes !== 1) {
+        throw new AknoError('internal', `could not start the ${receipt.operation} mutation receipt`);
+    }
+    receipt.started = true;
+}
+/**
+ * A new writer proves the old process is gone. Reservations never reached the mutation boundary;
+ * every later state might have changed Markdown and therefore remains as an explicit interruption.
+ */
+export function recoverInterruptedMutationReceipts(ctx) {
+    if (!ctx.writable)
+        return;
+    ctx.store.transaction(() => {
+        const rows = ctx.store.db
+            .prepare("SELECT actor, operation, idempotency_key, state FROM mutation_receipts WHERE state != 'completed'")
+            .all();
+        const remove = ctx.store.db.prepare(`DELETE FROM mutation_receipts
+        WHERE actor = ? AND operation = ? AND idempotency_key = ? AND state = 'reserved'`);
+        const interrupt = ctx.store.db.prepare(`UPDATE mutation_receipts SET state = 'interrupted', result = NULL, completed_at = NULL
+        WHERE actor = ? AND operation = ? AND idempotency_key = ?
+          AND state IN ('running', 'committed')`);
+        for (const row of rows) {
+            if (activeReceipts.has(receiptIdentity(ctx.config.dbPath, row.actor, row.operation, row.idempotency_key))) {
+                continue;
+            }
+            if (row.state === 'reserved')
+                remove.run(row.actor, row.operation, row.idempotency_key);
+            else
+                interrupt.run(row.actor, row.operation, row.idempotency_key);
+        }
+    });
+}
+function mutationRequestHash(operation, input) {
+    return sha256(stableJson({ operation, request: canonicalRequest(operation, input) }));
+}
+function canonicalRequest(operation, input) {
+    const request = withoutUndefined(input);
+    if (operation === 'write') {
+        if (typeof request.slug === 'string')
+            request.slug = normalizeSlug(request.slug);
+        if (typeof request.propose_slug === 'string')
+            request.propose_slug = normalizeSlug(request.propose_slug);
+        if (Array.isArray(request.documents)) {
+            request.documents = request.documents.map((document) => isRecord(document) && typeof document.path === 'string'
+                ? { ...document, path: path.resolve(document.path) }
+                : document);
+        }
+        request.dry_run = request.dry_run ?? false;
+    }
+    else if (operation === 'move') {
+        if (typeof request.from === 'string')
+            request.from = normalizeSlug(request.from);
+        if (typeof request.to === 'string')
+            request.to = normalizeSlug(request.to);
+    }
+    else if (operation === 'forget') {
+        if (typeof request.slug === 'string')
+            request.slug = request.slug.replace(/\.(md|markdown)$/i, '');
+    }
+    else {
+        if (typeof request.path === 'string')
+            request.path = normalizeSlug(request.path).replace(/\/\*+$/, '');
+        const role = typeof request.role === 'string' ? request.role : 'knowledge';
+        request.role = role;
+        request.remember = request.remember ?? (role === 'knowledge' ? 'integrate' : 'deny');
+        request.dry_run = request.dry_run ?? false;
+    }
+    return request;
+}
+function compactResult(operation, result) {
+    const safe = withoutUndefined({ ...result });
+    delete safe.removed;
+    delete safe.rule;
+    if (operation === 'folder' && result.rule !== undefined) {
+        if (result.outcome === 'noop') {
+            safe.rebuild_existing_rule = true;
+            safe.rule_hash = sha256(stableJson(result.rule));
+        }
+        else {
+            safe.rebuild_rule = true;
+        }
+    }
+    let encoded = stableJson(safe);
+    if (Buffer.byteLength(encoded) <= MAX_RESULT_BYTES)
+        return encoded;
+    const bounded = withoutUndefined({
+        status: result.status,
+        outcome: result.outcome,
+        change_id: result.change_id,
+        removed_from: result.removed_from,
+        trashed: result.trashed,
+        path: result.path,
+        glob: result.glob,
+        rules_file: result.rules_file,
+        result_truncated: true,
+    });
+    encoded = stableJson(bounded);
+    if (Buffer.byteLength(encoded) > MAX_RESULT_BYTES) {
+        throw new AknoError('internal', 'mutation result locator exceeded its storage bound');
+    }
+    return encoded;
+}
+function replayResult(ctx, operation, input, receipt) {
+    if (!receipt.result)
+        throw new AknoError('internal', 'completed mutation receipt has no result locator');
+    const result = JSON.parse(receipt.result);
+    if (result.rebuild_rule && operation === 'folder') {
+        result.rule = folderRuleFromRequest(input);
+        delete result.rebuild_rule;
+    }
+    if (result.rebuild_existing_rule && operation === 'folder' && typeof result.glob === 'string') {
+        const rule = currentFolderRule(ctx, result.glob);
+        if (rule && sha256(stableJson(rule)) === result.rule_hash)
+            result.rule = rule;
+        delete result.rebuild_existing_rule;
+        delete result.rule_hash;
+    }
+    if (operation === 'forget' && receipt.change_id && (input.fact || input.memory)) {
+        const removed = removedTextFromJournal(ctx.store, receipt.change_id);
+        if (removed !== null)
+            result.removed = removed;
+    }
+    delete result.result_truncated;
+    return { ...result, replayed: true };
+}
+function folderRuleFromRequest(input) {
+    const role = typeof input.role === 'string' ? input.role : 'knowledge';
+    return withoutUndefined({
+        description: input.description,
+        role,
+        remember: input.remember ?? (role === 'knowledge' ? 'integrate' : 'deny'),
+        about: input.about,
+        type: input.type,
+        ingest: input.ingest,
+        rank: input.rank,
+        route: input.route,
+    });
+}
+function currentFolderRule(ctx, glob) {
+    const compiled = ctx.config.rules.find((rule) => rule.glob === glob);
+    if (!compiled)
+        return null;
+    const { glob: _glob, source: _source, specificity: _specificity, ...rule } = compiled;
+    return withoutUndefined(rule);
+}
+function removedTextFromJournal(store, changeId) {
+    const row = store.db
+        .prepare(`SELECT before, after FROM change_files
+        WHERE change_id = ? AND before IS NOT NULL AND after IS NOT NULL ORDER BY ord LIMIT 1`)
+        .get(changeId);
+    if (!row)
+        return null;
+    const before = row.before.split('\n');
+    const after = row.after.split('\n');
+    let prefix = 0;
+    while (prefix < before.length && prefix < after.length && before[prefix] === after[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < before.length - prefix &&
+        suffix < after.length - prefix &&
+        before[before.length - 1 - suffix] === after[after.length - 1 - suffix]) {
+        suffix++;
+    }
+    const removed = before.slice(prefix, before.length - suffix);
+    return removed.length > 0 ? removed.join('\n') : null;
+}
+function readReceipt(store, actor, operation, key) {
+    return store.db
+        .prepare(`SELECT * FROM mutation_receipts
+        WHERE actor = ? AND operation = ? AND idempotency_key = ?`)
+        .get(actor, operation, key);
+}
+function assertSameRequest(receipt, requestHash) {
+    if (receipt.request_hash === requestHash)
+        return;
+    throw new AknoError('conflict', 'this idempotency key is already bound to a different request', {
+        operation: receipt.operation,
+        idempotency_key: receipt.idempotency_key,
+    });
+}
+function assertJournalCommit(store, receipt, result) {
+    const row = readReceipt(store, receipt.actor, receipt.operation, receipt.idempotencyKey);
+    if (row?.state !== 'committed' ||
+        typeof result.change_id !== 'string' ||
+        row.change_id !== result.change_id) {
+        throw new AknoError('internal', `${receipt.operation} crossed its mutation boundary without an atomic journal commit`);
+    }
+}
+function interruptedError(receipt) {
+    return new AknoError('interrupted', `${receipt.operation} with this idempotency key may already have changed the knowledge base`, {
+        operation: receipt.operation,
+        idempotency_key: receipt.idempotency_key,
+        state: receipt.state,
+        ...(receipt.change_id ? { change_id: receipt.change_id } : {}),
+        recovery: receipt.change_id
+            ? 'Inspect the recorded change before deciding whether to undo or continue with a new idempotency key.'
+            : 'Inspect the requested destination before continuing with a new idempotency key.',
+    });
+}
+function isRetryablePrecondition(result) {
+    return ['requires_folder', 'requires_approval', 'conflict'].includes(String(result.outcome));
+}
+function deleteReceipt(store, receipt) {
+    store.db
+        .prepare(`DELETE FROM mutation_receipts
+        WHERE actor = ? AND operation = ? AND idempotency_key = ? AND request_hash = ?`)
+        .run(receipt.actor, receipt.operation, receipt.idempotencyKey, receipt.requestHash);
+}
+function receiptIdentity(dbPath, actor, operation, key) {
+    return `${dbPath}\0${actor}\0${operation}\0${key}`;
+}
+function withoutUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function stableJson(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .filter((key) => value[key] !== undefined)
+        .sort()
+        .map((key) => [key, sortValue(value[key])]));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=mutation-receipts.js.map

package/dist/write/mutation-receipts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-receipts.js","sourceRoot":"","sources":["../../src/write/mutation-receipts.ts"],"names":[],"mappings":"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"}

package/dist/write/retain.d.ts

@@ -7,8 +7,8 @@ import type { FolderCatalogEntry } from '../kb/folders.ts';
  * consumed by keyed `retain` and unkeyed `remember`; keeping the interpretation here prevents
  * the two public operations from gradually learning different meanings for the same source.
  */
-export declare const RETAIN_PROMPT_VERSION = "retain-extraction-language-v57";
-export declare const RETAIN_VERIFIER_VERSION = "retain-verifier-language-v41";
+export declare const RETAIN_PROMPT_VERSION = "retain-extraction-language-v59";
+export declare const RETAIN_VERIFIER_VERSION = "retain-verifier-language-v42";
 /** All fields are required or nullable so constrained-decoding endpoints can keep strict mode. */
 export declare const RETAIN_SCHEMA: z.ZodObject<{
     candidates: z.ZodArray<z.ZodObject<{
@@ -149,7 +149,10 @@ export type RetainCandidate = ProvidedRetainCandidate & {
     /** Compatibility fields consumed by the existing remember result and evidence archive. */
     origin?: 'user' | 'assistant';
     evidence?: string;
+    /** Verifier-derived boundary for automatic placement; never supplied by the extraction model. */
+    retention_scope?: RetentionScope;
 };
+type RetentionScope = 'global' | 'entity' | 'document' | 'event' | 'task' | 'unknown';
 export interface RetainHeldCandidate {
     hold_stage?: 'validation' | 'verification';
     candidate_id: string;
@@ -203,4 +206,5 @@ export declare function cleanCandidateBatch(value: unknown, options: CandidateCl
     held: RetainHeldCandidate[];
 };
 export declare function modelCallReceipt(model: ModelClient, outcome: ModelOutcome<unknown>): RetainModelCallReceipt;
+export {};
 //# sourceMappingURL=retain.d.ts.map

package/dist/write/retain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retain.d.ts","sourceRoot":"","sources":["../../src/write/retain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"retain.d.ts","sourceRoot":"","sources":["../../src/write/retain.ts"],"names":[],"mappings":"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"}

package/dist/write/retain.js

@@ -21,8 +21,8 @@ import { SEMANTIC_COMPARISON_CONTRACT, PROPOSITION_SCOPE_CONTRACT, aggregateSema
  * consumed by keyed `retain` and unkeyed `remember`; keeping the interpretation here prevents
  * the two public operations from gradually learning different meanings for the same source.
  */
-export const RETAIN_PROMPT_VERSION = 'retain-extraction-language-v57';
-export const RETAIN_VERIFIER_VERSION = 'retain-verifier-language-v41';
+export const RETAIN_PROMPT_VERSION = 'retain-extraction-language-v59';
+export const RETAIN_VERIFIER_VERSION = 'retain-verifier-language-v42';
 const MAX_CANDIDATE_TEXT_UNITS = 400;
 const RETRIEVAL_UNIT_CONTRACT = `A retained record is one independently retrievable semantic unit:
 the selected proposition together with every source qualification governing its truth, knowledge state,
@@ -153,6 +153,9 @@ own sentence with an explicit subject, keeping exactly whether the person lacks
 or personally performed a check. Choose subject and page after that qualified record. They describe its source-supported canonical identity,
 not an action phrase constructed from its words. A proposed page is only a taxonomy suggestion, never proof
 of ownership; use only the supplied admitted pages or creatable folders, and keep an unresolved home null.
+For a durable document-scoped preference, choose the named document as subject, not merely the person
+who expressed the preference. Never propose that person's general page, a bare year, or a domain index
+as the document's home. If the document identity or home is unresolved, leave the page null.
 When the outer narrator supplies a later corrective clarification of an inner report, close the inner
 speaker's reported clause before the clarification and explicitly name the narrator as its source.
 Keep both clauses in the same readable candidate with their shared verification limits. Do not move the
@@ -189,7 +192,12 @@ uses active, cancelled or superseded; question uses active or resolved. A questi
 none: uncertainty about its answer does not make the question itself tentative or asserted.
 
 Keep durable facts, accepted decisions, stated preferences, active plans, actual events, durable open
-questions, and proven experience. Keep a considered, rejected, tentative, hypothetical, cancelled,
+questions, and proven experience. A command to finish or clean up this one document or task is not
+a standing preference, even when phrased in the first person. A question asked only to complete the
+current task is not automatically a durable open question; an unresolved question worth returning to is.
+Keep the original document, person, project, trip, or event scope in the readable record. Do not turn
+an advertisement, quotation, or nearby project mention into a fact about that project. Keep a
+considered, rejected, tentative, hypothetical, cancelled,
 completed, or superseded item only when its readable sentence explicitly preserves that status.
 When relevant to the supplied retention mission, discussed hypotheses, fictional examples, suspicions,
 and unaccepted proposals are useful records too. Lack of established truth is not a reason to discard them.
@@ -319,6 +327,21 @@ actor, an asserted alternative, lost evidentiary limits or lost personal nonsele
 For ordinary_tentative, tentative qualifies the selected uncertain proposition normally. Do not interpret
 record-level metadata as syntactically modifying every verb regardless of the supplied label definition.
 
+Independently classify retention admission from the complete source before approving placement.
+For each candidate, retention.durability is durable only when the selected proposition remains useful
+beyond this one source-processing task. A one-task command, a transient live reading, and a question
+whose only purpose is finishing the current task are not durable. A genuine standing preference and
+an unresolved question worth revisiting are durable, even if their wording is brief. Choose uncertain
+when the source does not establish which. Classify source_scope from the selected source proposition,
+not the candidate's proposed page or subject label. Classify candidate_scope from the readable text:
+global for a standing preference across tasks, including a named person's cross-context preference;
+entity for one named product/project/trip/booking or one person's specific profile fact,
+document for one named document, event for one occurrence, task for a one-task instruction, and
+unknown when the boundary is absent. A document-specific command restated as a global deletion
+preference has source_scope=document and candidate_scope=global, even if its words are source-entailing
+in isolation. Never widen a source's scope to make a destination convenient. Admission and factual
+support are separate decisions: a faithful task-only record can still be held as not durable.
+
 For every supplied candidate id, first audit its exact frame and use comparison.source_meaning and
 comparison.candidate_meaning to identify the governing retained predicate and its actor separately from
 subordinate or coupled propositions. Preserve every selected predicate and qualification; naming a governing
@@ -728,7 +751,12 @@ export async function runRetain(text, model, options = {}) {
             modelUsage: { extraction: extractionReceipt, ...repairUsage, verification: verified.receipt },
         };
     }
-    const accepted = cleaned.candidates.filter((candidate) => verified.accepted.has(candidate.candidate_id));
+    const accepted = cleaned.candidates
+        .filter((candidate) => verified.accepted.has(candidate.candidate_id))
+        .map((candidate) => ({
+        ...candidate,
+        retention_scope: verified.scopes.get(candidate.candidate_id),
+    }));
     const heldByVerification = cleaned.candidates
         .filter((candidate) => !verified.accepted.has(candidate.candidate_id))
         .map((candidate) => ({
@@ -762,6 +790,7 @@ async function verifyCandidates(model, source, candidates, repairObligations, re
     const outcomes = [];
     const accepted = new Set();
     const reasons = new Map();
+    const scopes = new Map();
     // Two disjoint candidates fit the default derive-role ceiling without truncating a large batch.
     // Relations still see the complete candidate context; candidates themselves are never evidence.
     for (let start = 0; start < candidates.length; start += 2) {
@@ -772,6 +801,7 @@ async function verifyCandidates(model, source, candidates, repairObligations, re
             return {
                 accepted: new Set(),
                 reasons: new Map(),
+                scopes: new Map(),
                 error: checked.error,
                 receipt: modelCallReceipt(model, aggregateSemanticOutcomes(outcomes)),
             };
@@ -779,6 +809,8 @@ async function verifyCandidates(model, source, candidates, repairObligations, re
             accepted.add(id);
         for (const [id, reason] of checked.reasons)
             reasons.set(id, reason);
+        for (const [id, scope] of checked.scopes)
+            scopes.set(id, scope);
     }
     // A source-supported relation still cannot persist when its target record was withheld.
     // Iterate because a rejected target may invalidate a chain spanning several verification batches.
@@ -797,6 +829,7 @@ async function verifyCandidates(model, source, candidates, repairObligations, re
     return {
         accepted,
         reasons,
+        scopes,
         error: null,
         receipt: modelCallReceipt(model, aggregateSemanticOutcomes(outcomes)),
     };
@@ -832,6 +865,11 @@ async function verifyCandidateBatch(model, source, candidates, repairObligations
             proposition_supported: semanticVerdictFields.proposition_supported,
             action_arguments_preserved: semanticVerdictFields.action_arguments_preserved,
             qualification_scope_preserved: semanticVerdictFields.qualification_scope_preserved,
+            retention: z.strictObject({
+                durability: z.enum(['durable', 'task_only', 'transient', 'uncertain']),
+                source_scope: z.enum(['global', 'entity', 'document', 'event', 'task', 'unknown']),
+                candidate_scope: z.enum(['global', 'entity', 'document', 'event', 'task', 'unknown']),
+            }),
             reason_code: reason.nullable(),
         });
     });
@@ -889,6 +927,7 @@ async function verifyCandidateBatch(model, source, candidates, repairObligations
         return {
             accepted: new Set(),
             reasons: new Map(),
+            scopes: new Map(),
             outcome,
             error: outcome.error ?? 'verification failed',
         };
@@ -915,7 +954,13 @@ async function verifyCandidateBatch(model, source, candidates, repairObligations
                 verdict.qualification_scope_preserved) ||
                 verdict.reason_code === null))) {
         model.reportInvalidResponse();
-        return { accepted: new Set(), reasons: new Map(), outcome, error: 'verification returned invalid JSON' };
+        return {
+            accepted: new Set(),
+            reasons: new Map(),
+            scopes: new Map(),
+            outcome,
+            error: 'verification returned invalid JSON',
+        };
     }
     const byId = new Map(parsed.data.verdicts.map((verdict) => [verdict.candidate_id, verdict]));
     if (parsed.data.verdicts.length !== candidates.length ||
@@ -925,6 +970,7 @@ async function verifyCandidateBatch(model, source, candidates, repairObligations
         return {
             accepted: new Set(),
             reasons: new Map(),
+            scopes: new Map(),
             outcome,
             error: 'verification omitted or duplicated candidate verdicts',
         };
@@ -940,14 +986,35 @@ async function verifyCandidateBatch(model, source, candidates, repairObligations
         // A source-side classification is compared with immutable metadata, independently of
         // positive prose verdicts. Disagreement is a semantic hold, never permission to relabel.
         verdict.source_selected_polarity ===
-            candidates.find((candidate) => candidate.candidate_id === verdict.candidate_id).polarity)
+            candidates.find((candidate) => candidate.candidate_id === verdict.candidate_id).polarity &&
+        admissionReason(verdict.retention) === null)
         .map((verdict) => verdict.candidate_id));
     const reasons = new Map();
+    const scopes = new Map();
     for (const verdict of parsed.data.verdicts) {
-        if (!accepted.has(verdict.candidate_id))
-            reasons.set(verdict.candidate_id, verdict.reason_code ?? 'discourse_uncertain');
+        if (accepted.has(verdict.candidate_id))
+            scopes.set(verdict.candidate_id, verdict.retention.source_scope);
+        if (!accepted.has(verdict.candidate_id)) {
+            const semanticFailure = !verdict.proposition_supported ||
+                !verdict.action_arguments_preserved ||
+                !verdict.qualification_scope_preserved ||
+                verdict.source_selected_polarity !==
+                    candidates.find((candidate) => candidate.candidate_id === verdict.candidate_id).polarity;
+            reasons.set(verdict.candidate_id, semanticFailure
+                ? (verdict.reason_code ?? 'discourse_uncertain')
+                : (verdict.reason_code ?? admissionReason(verdict.retention) ?? 'discourse_uncertain'));
+        }
     }
-    return { accepted, reasons, outcome, error: null };
+    return { accepted, reasons, scopes, outcome, error: null };
+}
+function admissionReason(retention) {
+    if (retention.durability === 'task_only' || retention.durability === 'transient')
+        return 'not_durable';
+    if (retention.durability === 'uncertain' || retention.source_scope === 'unknown')
+        return 'noncanonical_without_context';
+    if (retention.source_scope !== retention.candidate_scope)
+        return 'scope_mismatch';
+    return retention.source_scope === 'task' ? 'scope_mismatch' : null;
 }
 /** Source spellings help classification; generated subjects cannot certify their own language. */
 function retentionLanguageReferences(source) {