instar 1.3.830 → 1.3.831

package/dist/core/DecisionQualityRecorderImpl.d.ts

@@ -0,0 +1,192 @@
+/**
+ * DecisionQualityRecorderImpl — the concrete decision-quality substrate behind
+ * the router's settlement seam (llm-decision-quality-meter §5.2/§5.4/§5.5).
+ *
+ * Two write paths live here, both observe-only (never gate, never throw into
+ * the path they observe):
+ *
+ * 1. `recordSettlement` (the DecisionQualityRecorder contract, §5.1.5/FD7):
+ *    consumes the router's write-once DecisionSettlement. For every ENROLLED
+ *    settled decision it ALWAYS writes the ~250-byte content-free
+ *    `decision_quality` row (regardless of volume class — outcome rows always
+ *    have parents, counts are complete), validates the decision point against
+ *    the census (unknown → counted, row still written with the raw point id),
+ *    and writes the provenance JSONL row under the census VOLUME VALVE
+ *    (`full` always / `sampled:<rate>` deterministic FNV-1a on the correlation
+ *    id / `budget:<rows/day>` indexed COUNT since UTC-day start with a loud
+ *    droppedByBudget counter).
+ *
+ * 2. `annotateOutcome` (the §5.4 write-integrity CHOKEPOINT): the ONE path an
+ *    outcome annotation takes into the substrate. Keyed on the correlation id;
+ *    rung + evidence strength are DERIVED from the registered evidence rule —
+ *    never caller-supplied — and the chokepoint REJECTS + COUNTS: an invalid
+ *    grade enum, a rung mismatch (incl. an unregistered ruleId — DC r7), an
+ *    owner mismatch (gradedBy.component ≠ the rule's registered owning
+ *    component — ADV r5), and an unknown decision point. Accepted outcomes
+ *    land via `ledger.upsertOutcome` (idempotent on correlationId × gradedBy)
+ *    plus a JPL outcome trail row. The evidence RULES themselves (what grade a
+ *    respawn/realcheck proves) belong to their owning components — this module
+ *    only enforces the write-integrity contract.
+ *
+ * Gating (§5.7/FD6): `provenance.uniformSeam.enabled` resolves via
+ * `resolveDevAgentGate` (LIVE on a development agent, DARK on the fleet;
+ * omit-required — never seeded). `dryRun` defaults TRUE: metadata-only
+ * would-write log lines (component, decisionPoint, byte sizes — NEVER context
+ * content), with BOTH durable writes suppressed (§5.2).
+ */
+import type { DecisionSettlement, DecisionQualityRecorder } from './decisionQualityTypes.js';
+import type { FeatureMetricsLedger } from '../monitoring/FeatureMetricsLedger.js';
+import type { JudgmentProvenanceLog } from './JudgmentProvenanceLog.js';
+import { getCensusEntry, getVolumeClass, getRule } from '../data/provenanceCoverage.js';
+/** Outcome evidence-note hard bound (§5.2/§5.5 — clamped at annotate time, before storage). */
+export declare const EVIDENCE_NOTE_CLAMP = 500;
+export interface DecisionAnnotationRejectionCounters {
+    /** Annotations whose grade failed the FD3 enum (right|wrong|unknown). */
+    enumInvalid: number;
+    /** Unregistered ruleId, or a claimed rung disagreeing with the registry (§5.4.2). */
+    rungMismatch: number;
+    /** gradedBy.component ≠ the ruleId's registered owning component (ADV r5). */
+    ownerMismatch: number;
+    /** Census misses: settlement writes for undeclared points + annotations claiming one (§5.1.4/DC r7). */
+    unknownDecisionPoint: number;
+}
+/** The four §5.5 rejection-class counters (P10's route surface). */
+export declare function getDecisionAnnotationRejectionCounters(): Readonly<DecisionAnnotationRejectionCounters>;
+/** Test-only seam (the _resetDecisionQualityForTest precedent). */
+export declare function _resetDecisionAnnotationRejectionCountersForTest(): void;
+export type AnnotationRejectionClass = 'enum-invalid' | 'rung-mismatch' | 'owner-mismatch' | 'unknown-decision-point';
+export interface DecisionOutcomeAnnotationInput {
+    /** The §5.1 correlation id the outcome joins its decision on (§5.4.1). */
+    correlationId: string;
+    /** Registered, immutable, versioned evidence-rule id (§5.4.5). */
+    ruleId: string;
+    /** The grading component — MUST be the ruleId's registered owner (ADV r5). */
+    gradedBy: {
+        component: string;
+    };
+    /** FD3 grade — validated against the closed enum at the chokepoint. */
+    grade: string;
+    /**
+     * Optional rung CLAIM. The effective rung is ALWAYS derived from the
+     * registry; a supplied claim that disagrees is rejected (§5.4.2 — "an
+     * annotation claiming a ruleId whose registered rung disagrees").
+     */
+    claimedRung?: string;
+    /** ≤500 scrubbed chars, pointer-disciplined; NEVER served by /decision-quality. */
+    evidenceNote?: string;
+    /** Structured evidence (ids/hashes/enums) for the JPL outcome trail row. */
+    evidence?: Record<string, unknown>;
+    /**
+     * Orphan-attribution hint (FD10) — the census decision point this outcome
+     * belongs to. If supplied it must exist in the census (unknown → rejected
+     * + counted).
+     */
+    decisionPoint?: string;
+    /** Defaults to the recorder clock. */
+    ts?: number;
+}
+export interface DecisionOutcomeAnnotationResult {
+    /** True = the outcome row landed durably (orphan or not). */
+    applied: boolean;
+    rejected?: AnnotationRejectionClass;
+    /** True = no decision_quality parent on this machine (FD10 — counted, never an error). */
+    orphan?: boolean;
+    /** True = validated clean but suppressed by the §5.2 dry-run stage. */
+    dryRun?: boolean;
+    /** True = the seam resolves DARK on this agent (nothing counted, nothing written). */
+    disabled?: boolean;
+}
+/** The config slice the recorder resolves its gates from (§5.7). */
+export interface DecisionQualityRecorderConfig {
+    developmentAgent?: boolean;
+    provenance?: {
+        uniformSeam?: {
+            enabled?: boolean;
+            dryRun?: boolean;
+        };
+    };
+}
+/** The census lookups the recorder consumes (§5.6 — defaults to the real PROVENANCE_COVERAGE module). */
+export interface DecisionQualityCensus {
+    getCensusEntry: typeof getCensusEntry;
+    getVolumeClass: typeof getVolumeClass;
+}
+/** The evidence-rule registry lookup the annotate chokepoint consumes (§5.4.2 — defaults to RULE_REGISTRY). */
+export interface DecisionQualityRules {
+    getRule: typeof getRule;
+}
+export interface DecisionQualityRecorderImplOptions {
+    /** The quality substrate (decision_quality/decision_outcomes/rollup). Null = degraded (no SQLite writes). */
+    ledger: FeatureMetricsLedger | null;
+    /** The provenance JSONL store (FD9 — constructed unconditionally). Null = degraded (no JSONL rows). */
+    judgmentProvenance?: JudgmentProvenanceLog | null;
+    config: DecisionQualityRecorderConfig;
+    /** Census lookups — the typed PROVENANCE_COVERAGE module by default (test seam). */
+    census?: DecisionQualityCensus;
+    /** Rule-registry lookup — RULE_REGISTRY by default (test seam). */
+    rules?: DecisionQualityRules;
+    log?: (msg: string) => void;
+    now?: () => number;
+}
+export declare class DecisionQualityRecorderImpl implements DecisionQualityRecorder {
+    private readonly ledger;
+    private readonly jpl;
+    private readonly census;
+    private readonly rules;
+    private readonly enabled;
+    private readonly dryRun;
+    private readonly log;
+    private readonly nowFn;
+    constructor(opts: DecisionQualityRecorderImplOptions);
+    /** The resolved gate state (wiring-integrity/status surface). */
+    gateState(): {
+        enabled: boolean;
+        dryRun: boolean;
+    };
+    /**
+     * The router-settlement write (§5.1.5/FD7 — exactly one call per settled
+     * decision, isolated by the router; this method additionally never throws).
+     */
+    recordSettlement(s: DecisionSettlement): void;
+    /**
+     * Volume-class disposition for the provenance JSONL row (§5.6):
+     *  - `full` → always write (the FD4 always-write reservation);
+     *  - `sampled:<rate>` → deterministic FNV-1a bucket on the CORRELATION id
+     *    (the log's own sampling convention — a decision samples identically on
+     *    replay); malformed rate → write (the ratchet owns format; the seam
+     *    fails toward observability);
+     *  - `budget:<rows/day>` → indexed COUNT of decision_quality rows since
+     *    UTC-day start (restart-safe, no new state). An unverifiable count
+     *    (substrate degraded) → write, honestly logged by the ledger's own
+     *    degradation — never a fabricated drop;
+     *  - no class (unknown/pending/exempt point) → no JSONL row (an undeclared
+     *    point gets counts, never a provenance archive the census hasn't valved).
+     */
+    private resolveJsonlDisposition;
+    /**
+     * The §5.4 outcome-annotation write-integrity chokepoint. Callsites (the
+     * hog sentinel's grade-on-supersede/scan-tick rules, the completion
+     * realcheck arm, the grading endpoint) reach it via
+     * `annotateDecisionOutcome()` below — never `ledger.upsertOutcome` directly.
+     */
+    annotateOutcome(a: DecisionOutcomeAnnotationInput): DecisionOutcomeAnnotationResult;
+}
+/**
+ * Install the recorder at AgentServer construction: registers it as BOTH the
+ * router's settlement recorder (P2's `setDecisionQualityRecorder` singleton)
+ * AND the module-level annotate-chokepoint target. Pass null to uninstall.
+ */
+export declare function installDecisionQualityRecorder(impl: DecisionQualityRecorderImpl | null): void;
+/**
+ * The module-level annotate entry (§5.4) — what the hog/completion wiring and
+ * the grading endpoint call. No recorder installed (CLI without a server) →
+ * a clean no-op result.
+ */
+export declare function annotateDecisionOutcome(a: DecisionOutcomeAnnotationInput): DecisionOutcomeAnnotationResult;
+/**
+ * Parse the machineId segment out of a §5.1 correlation id
+ * (`d-<machineId8>-<uuid>` / `d-<uuid>`): the id itself is the carrier the
+ * FD10 routing follow-up reads. A bare-uuid id (single-machine mint) → null.
+ */
+export declare function machineIdSegmentOf(correlationId: string): string | null;
+//# sourceMappingURL=DecisionQualityRecorderImpl.d.ts.map

package/dist/core/DecisionQualityRecorderImpl.d.ts.map

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

package/dist/core/DecisionQualityRecorderImpl.js

@@ -0,0 +1,363 @@
+/**
+ * DecisionQualityRecorderImpl — the concrete decision-quality substrate behind
+ * the router's settlement seam (llm-decision-quality-meter §5.2/§5.4/§5.5).
+ *
+ * Two write paths live here, both observe-only (never gate, never throw into
+ * the path they observe):
+ *
+ * 1. `recordSettlement` (the DecisionQualityRecorder contract, §5.1.5/FD7):
+ *    consumes the router's write-once DecisionSettlement. For every ENROLLED
+ *    settled decision it ALWAYS writes the ~250-byte content-free
+ *    `decision_quality` row (regardless of volume class — outcome rows always
+ *    have parents, counts are complete), validates the decision point against
+ *    the census (unknown → counted, row still written with the raw point id),
+ *    and writes the provenance JSONL row under the census VOLUME VALVE
+ *    (`full` always / `sampled:<rate>` deterministic FNV-1a on the correlation
+ *    id / `budget:<rows/day>` indexed COUNT since UTC-day start with a loud
+ *    droppedByBudget counter).
+ *
+ * 2. `annotateOutcome` (the §5.4 write-integrity CHOKEPOINT): the ONE path an
+ *    outcome annotation takes into the substrate. Keyed on the correlation id;
+ *    rung + evidence strength are DERIVED from the registered evidence rule —
+ *    never caller-supplied — and the chokepoint REJECTS + COUNTS: an invalid
+ *    grade enum, a rung mismatch (incl. an unregistered ruleId — DC r7), an
+ *    owner mismatch (gradedBy.component ≠ the rule's registered owning
+ *    component — ADV r5), and an unknown decision point. Accepted outcomes
+ *    land via `ledger.upsertOutcome` (idempotent on correlationId × gradedBy)
+ *    plus a JPL outcome trail row. The evidence RULES themselves (what grade a
+ *    respawn/realcheck proves) belong to their owning components — this module
+ *    only enforces the write-integrity contract.
+ *
+ * Gating (§5.7/FD6): `provenance.uniformSeam.enabled` resolves via
+ * `resolveDevAgentGate` (LIVE on a development agent, DARK on the fleet;
+ * omit-required — never seeded). `dryRun` defaults TRUE: metadata-only
+ * would-write log lines (component, decisionPoint, byte sizes — NEVER context
+ * content), with BOTH durable writes suppressed (§5.2).
+ */
+import { setDecisionQualityRecorder } from './decisionQualityTypes.js';
+import { clampServedVerdictClass, clampServedPromptId, fnv1aSampleBucket, CONTEXT_HEAD_CLAMP, } from './JudgmentProvenanceLog.js';
+import { getCensusEntry, getVolumeClass, getRule } from '../data/provenanceCoverage.js';
+import { resolveDevAgentGate } from './devAgentGate.js';
+import { scrubString } from './CredentialAuditEmit.js';
+/** Outcome evidence-note hard bound (§5.2/§5.5 — clamped at annotate time, before storage). */
+export const EVIDENCE_NOTE_CLAMP = 500;
+const _rejectionCounters = {
+    enumInvalid: 0,
+    rungMismatch: 0,
+    ownerMismatch: 0,
+    unknownDecisionPoint: 0,
+};
+/** The four §5.5 rejection-class counters (P10's route surface). */
+export function getDecisionAnnotationRejectionCounters() {
+    return { ..._rejectionCounters };
+}
+/** Test-only seam (the _resetDecisionQualityForTest precedent). */
+export function _resetDecisionAnnotationRejectionCountersForTest() {
+    _rejectionCounters.enumInvalid = 0;
+    _rejectionCounters.rungMismatch = 0;
+    _rejectionCounters.ownerMismatch = 0;
+    _rejectionCounters.unknownDecisionPoint = 0;
+}
+export class DecisionQualityRecorderImpl {
+    ledger;
+    jpl;
+    census;
+    rules;
+    enabled;
+    dryRun;
+    log;
+    nowFn;
+    constructor(opts) {
+        this.ledger = opts.ledger ?? null;
+        this.jpl = opts.judgmentProvenance ?? null;
+        this.census = opts.census ?? { getCensusEntry, getVolumeClass };
+        this.rules = opts.rules ?? { getRule };
+        // §5.7/FD6: omit-required dev gate — LIVE on a development agent, DARK on
+        // the fleet; an explicit config value always wins. dryRun defaults TRUE.
+        this.enabled = resolveDevAgentGate(opts.config.provenance?.uniformSeam?.enabled, opts.config);
+        this.dryRun = opts.config.provenance?.uniformSeam?.dryRun !== false;
+        this.log = opts.log ?? (() => { });
+        this.nowFn = opts.now ?? (() => Date.now());
+    }
+    /** The resolved gate state (wiring-integrity/status surface). */
+    gateState() {
+        return { enabled: this.enabled, dryRun: this.dryRun };
+    }
+    /**
+     * The router-settlement write (§5.1.5/FD7 — exactly one call per settled
+     * decision, isolated by the router; this method additionally never throws).
+     */
+    recordSettlement(s) {
+        try {
+            if (!this.enabled)
+                return;
+            if (!s.enrolled || !s.provenance)
+                return; // Layer A only — nothing enrolled to write
+            const decisionPoint = typeof s.provenance.decisionPoint === 'string' ? s.provenance.decisionPoint : '';
+            if (!decisionPoint)
+                return; // keyless enrollment = unjoinable noise
+            const entry = this.census.getCensusEntry(decisionPoint);
+            // §5.1.4: validate decisionPoint ∈ census; unknowns are COUNTED but the
+            // decision_quality row is still written with the raw point id — counts
+            // must be complete (DC2-M3).
+            if (!entry)
+                _rejectionCounters.unknownDecisionPoint++;
+            const volumeClass = this.census.getVolumeClass(decisionPoint); // undefined unless census-wired
+            // Bounded served labels (§5.2) — the SAME clamp helpers the JPL envelope
+            // applies, so the SQLite row and the JSONL row can never disagree.
+            const verdict = clampServedVerdictClass(s.verdictClass);
+            const prompt = clampServedPromptId(s.provenance.promptId);
+            const qualityRecord = {
+                correlationId: s.correlationId,
+                decisionPoint,
+                feature: entry?.component,
+                verdictClass: verdict.value,
+                mintedBy: s.mintedBy,
+                volumeClass,
+                contentClass: entry?.contentClass,
+                machineId: machineIdSegmentOf(s.correlationId) ?? undefined,
+                model: s.settledAttempt.model,
+                framework: s.settledAttempt.framework,
+                promptId: prompt.value,
+                ts: s.settledAtMs,
+            };
+            // Context assembly (§5.1.3/§5.1.5): callerRef relocates INSIDE context
+            // (FD8); a raw-response head enters SCRUBBED + 300-clamped — never the
+            // served decision field; an errored settlement carries its error class.
+            const context = {
+                ...(s.provenance.context ?? {}),
+                ...(s.callerRef !== undefined ? { callerRef: scrubString(String(s.callerRef)).slice(0, 128) } : {}),
+                ...(s.rawResponseHead !== undefined
+                    ? { rawResponseHead: scrubString(s.rawResponseHead).slice(0, CONTEXT_HEAD_CLAMP) }
+                    : {}),
+                ...(s.errorClass !== undefined ? { errorClass: String(s.errorClass).slice(0, 128) } : {}),
+            };
+            const jplInput = {
+                component: entry?.component ?? 'unlabeled',
+                decisionPoint,
+                context,
+                optionsPresented: s.provenance.optionsPresented ?? [],
+                decision: s.verdictClass, // JPL applies the §5.2 clamp on seam rows
+                reason: 'router-settlement',
+                floor: 'observe-only settlement seam',
+                fallbackRung: 'llm',
+                // FD4: the always-write (arbiter-bypass) invariant is RESERVED for
+                // full-class points. (Seam rows bypass the JPL's global sampling knob
+                // regardless — the census volume valve below is their ONE valve.)
+                arbiter: volumeClass === 'full',
+                model: s.settledAttempt.model,
+                tokensIn: s.settledAttempt.usage?.inputTokens,
+                tokensOut: s.settledAttempt.usage?.outputTokens,
+                latencyMs: Math.max(0, s.settledAtMs - s.mintedAtMs),
+                correlationId: s.correlationId,
+                promptId: s.provenance.promptId, // JPL applies the §5.2 clamp
+                contentClass: entry?.contentClass,
+                mintedBy: s.mintedBy,
+            };
+            if (this.dryRun) {
+                // §5.2 dry-run stage: metadata-only would-write lines — component,
+                // decisionPoint, byte sizes, volume-class disposition. NEVER context
+                // content (that would violate the very posture the 0700/0600 store
+                // exists to contain). BOTH durable writes are suppressed.
+                const disposition = this.resolveJsonlDisposition(volumeClass, s, { selfAlreadyCounted: false });
+                this.log(`[decision-quality] dryRun would-write: decisionPoint=${safeLabel(decisionPoint)} ` +
+                    `component=${safeLabel(entry?.component ?? 'unknown')} census=${entry ? entry.status : 'unknown'} ` +
+                    `volumeClass=${volumeClass ?? 'none'} verdictClass=${safeLabel(verdict.value)} jsonl=${disposition} ` +
+                    `qualityRowBytes=${byteLength(qualityRecord)} provenanceRowBytes=${byteLength(jplInput)}`);
+                return;
+            }
+            // 1. The content-free decision_quality row — EVERY enrolled settlement,
+            //    REGARDLESS of volume class (§5.5/DC2-M3).
+            this.ledger?.recordDecision(qualityRecord);
+            // 2. The provenance JSONL row — governed by the census volume valve (§5.6).
+            const disposition = this.resolveJsonlDisposition(volumeClass, s, { selfAlreadyCounted: true });
+            if (disposition === 'write') {
+                this.jpl?.recordDecision(jplInput);
+            }
+            else if (disposition === 'budget-dropped') {
+                // Loud, never silent (§5.6/FD4).
+                this.ledger?.bumpQualityCounter(decisionPoint, 'droppedByBudget', { ts: s.settledAtMs });
+            }
+        }
+        catch (err) {
+            // @silent-fallback-ok: observability must never break the decision path
+            // it observes (§5.1.7) — the router additionally isolates this call.
+            this.log(`[decision-quality] settlement write failed (observability only): ${err.message}`);
+        }
+    }
+    /**
+     * Volume-class disposition for the provenance JSONL row (§5.6):
+     *  - `full` → always write (the FD4 always-write reservation);
+     *  - `sampled:<rate>` → deterministic FNV-1a bucket on the CORRELATION id
+     *    (the log's own sampling convention — a decision samples identically on
+     *    replay); malformed rate → write (the ratchet owns format; the seam
+     *    fails toward observability);
+     *  - `budget:<rows/day>` → indexed COUNT of decision_quality rows since
+     *    UTC-day start (restart-safe, no new state). An unverifiable count
+     *    (substrate degraded) → write, honestly logged by the ledger's own
+     *    degradation — never a fabricated drop;
+     *  - no class (unknown/pending/exempt point) → no JSONL row (an undeclared
+     *    point gets counts, never a provenance archive the census hasn't valved).
+     */
+    resolveJsonlDisposition(volumeClass, s, opts) {
+        if (!volumeClass)
+            return 'no-volume-class';
+        if (volumeClass === 'full')
+            return 'write';
+        if (volumeClass.startsWith('sampled:')) {
+            const rate = Number(volumeClass.slice('sampled:'.length));
+            if (!Number.isFinite(rate))
+                return 'write';
+            const clamped = Math.min(1, Math.max(0, rate));
+            return fnv1aSampleBucket(s.correlationId) < clamped ? 'write' : 'sampled-out';
+        }
+        if (volumeClass.startsWith('budget:')) {
+            const budget = Number.parseInt(volumeClass.slice('budget:'.length), 10);
+            if (!Number.isFinite(budget) || budget <= 0)
+                return 'write';
+            const d = new Date(s.settledAtMs);
+            const utcDayStart = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+            const counted = this.ledger?.countDecisionsSince(s.provenance?.decisionPoint ?? '', utcDayStart) ?? null;
+            if (counted === null)
+                return 'write'; // budget unverifiable — fail toward observability
+            const todayIncludingSelf = counted + (opts.selfAlreadyCounted ? 0 : 1);
+            return todayIncludingSelf <= budget ? 'write' : 'budget-dropped';
+        }
+        return 'write';
+    }
+    /**
+     * The §5.4 outcome-annotation write-integrity chokepoint. Callsites (the
+     * hog sentinel's grade-on-supersede/scan-tick rules, the completion
+     * realcheck arm, the grading endpoint) reach it via
+     * `annotateDecisionOutcome()` below — never `ledger.upsertOutcome` directly.
+     */
+    annotateOutcome(a) {
+        try {
+            if (!this.enabled)
+                return { applied: false, disabled: true };
+            // FD3 grade enum — validated first (§5.4.4).
+            if (a.grade !== 'right' && a.grade !== 'wrong' && a.grade !== 'unknown') {
+                _rejectionCounters.enumInvalid++;
+                return { applied: false, rejected: 'enum-invalid' };
+            }
+            // Rung is DERIVED from the registry, never caller-supplied (§5.4.2). An
+            // unregistered ruleId buckets under rung-mismatch (DC r7).
+            const rule = this.rules.getRule(a.ruleId);
+            if (!rule) {
+                _rejectionCounters.rungMismatch++;
+                return { applied: false, rejected: 'rung-mismatch' };
+            }
+            if (a.claimedRung !== undefined && a.claimedRung !== rule.rung) {
+                _rejectionCounters.rungMismatch++;
+                return { applied: false, rejected: 'rung-mismatch' };
+            }
+            // Owner check (ADV r5): a confused in-process annotator cannot inherit
+            // another rule's rung/precedence by claiming its id.
+            if (a.gradedBy?.component !== rule.owningComponent) {
+                _rejectionCounters.ownerMismatch++;
+                return { applied: false, rejected: 'owner-mismatch' };
+            }
+            // A supplied decision-point hint must exist in the census (§5.1.4/DC r7).
+            if (a.decisionPoint !== undefined && !this.census.getCensusEntry(a.decisionPoint)) {
+                _rejectionCounters.unknownDecisionPoint++;
+                return { applied: false, rejected: 'unknown-decision-point' };
+            }
+            const ts = a.ts ?? this.nowFn();
+            // Evidence note: scrubbed + ≤500-clamped BEFORE storage (§5.2/§5.5);
+            // never served by /decision-quality.
+            const evidenceNote = a.evidenceNote !== undefined ? scrubString(String(a.evidenceNote)).slice(0, EVIDENCE_NOTE_CLAMP) : undefined;
+            if (this.dryRun) {
+                // §5.2: while dryRun holds, the SQLite outcome write is suppressed too.
+                this.log(`[decision-quality] dryRun would-annotate: correlationId=${safeLabel(a.correlationId)} ` +
+                    `ruleId=${safeLabel(a.ruleId)} rung=${rule.rung} grade=${a.grade} gradedBy=${safeLabel(a.gradedBy.component)}` +
+                    (evidenceNote !== undefined ? ` evidenceNoteBytes=${Buffer.byteLength(evidenceNote, 'utf8')}` : ''));
+                return { applied: false, dryRun: true };
+            }
+            const res = this.ledger?.upsertOutcome({
+                correlationId: a.correlationId,
+                gradedBy: a.gradedBy.component,
+                ruleId: a.ruleId,
+                rung: rule.rung,
+                evidenceStrength: rule.evidenceStrength,
+                grade: a.grade,
+                effectiveWindowMs: rule.windowMs,
+                evidenceNote,
+                decisionPoint: a.decisionPoint,
+                ts,
+            });
+            if (!res?.applied)
+                return { applied: false };
+            // The JPL outcome trail row (§5.4.1 correlation keying) — structured
+            // evidence + the effective window (§5.4.5); grade re-validated at the
+            // JPL write by its own FD3 enum guard.
+            this.jpl?.annotateOutcome(a.correlationId, a.gradedBy.component, {
+                ...(a.evidence ?? {}),
+                ...(rule.windowMs !== undefined ? { windowMs: rule.windowMs } : {}),
+                ...(evidenceNote !== undefined ? { note: evidenceNote } : {}),
+                evidenceStrength: rule.evidenceStrength,
+            }, { grade: a.grade, gradedBy: a.gradedBy.component, ruleId: a.ruleId });
+            return { applied: true, orphan: res.orphan };
+        }
+        catch (err) {
+            // @silent-fallback-ok: annotation is observability — a failed write is
+            // repaired by idempotent re-runs (upserts converge), never a throw.
+            this.log(`[decision-quality] outcome annotation failed (observability only): ${err.message}`);
+            return { applied: false };
+        }
+    }
+}
+/* ── Module singleton wiring (the setFeatureMetricsRecorder pattern) ──────── */
+let _activeAnnotator = null;
+/**
+ * Install the recorder at AgentServer construction: registers it as BOTH the
+ * router's settlement recorder (P2's `setDecisionQualityRecorder` singleton)
+ * AND the module-level annotate-chokepoint target. Pass null to uninstall.
+ */
+export function installDecisionQualityRecorder(impl) {
+    setDecisionQualityRecorder(impl);
+    _activeAnnotator = impl;
+}
+/**
+ * The module-level annotate entry (§5.4) — what the hog/completion wiring and
+ * the grading endpoint call. No recorder installed (CLI without a server) →
+ * a clean no-op result.
+ */
+export function annotateDecisionOutcome(a) {
+    if (!_activeAnnotator)
+        return { applied: false, disabled: true };
+    return _activeAnnotator.annotateOutcome(a);
+}
+/* ── Small helpers ──────────────────────────────────────────────────────── */
+/** Log-hygiene clamp for identifiers interpolated into would-write lines. */
+function safeLabel(v) {
+    return String(v).replace(/[^\w./:<>-]/g, '_').slice(0, 64);
+}
+function byteLength(v) {
+    try {
+        return Buffer.byteLength(JSON.stringify(v) ?? '', 'utf8');
+    }
+    catch {
+        // @silent-fallback-ok: byte sizing feeds a dry-run log line only — an
+        // unserializable payload reports -1 rather than failing the settlement.
+        return -1;
+    }
+}
+/**
+ * Parse the machineId segment out of a §5.1 correlation id
+ * (`d-<machineId8>-<uuid>` / `d-<uuid>`): the id itself is the carrier the
+ * FD10 routing follow-up reads. A bare-uuid id (single-machine mint) → null.
+ */
+export function machineIdSegmentOf(correlationId) {
+    const m = /^[db]-(.+)$/.exec(correlationId);
+    if (!m)
+        return null;
+    const rest = m[1];
+    // A plain uuid (8-4-4-4-12 hex) means no machine segment.
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(rest))
+        return null;
+    const dash = rest.indexOf('-');
+    if (dash <= 0)
+        return null;
+    return rest.slice(0, dash);
+}
+//# sourceMappingURL=DecisionQualityRecorderImpl.js.map

package/dist/core/DecisionQualityRecorderImpl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DecisionQualityRecorderImpl.js","sourceRoot":"","sources":["../../src/core/DecisionQualityRecorderImpl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAGvE,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,+FAA+F;AAC/F,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAmBvC,MAAM,kBAAkB,GAAwC;IAC9D,WAAW,EAAE,CAAC;IACd,YAAY,EAAE,CAAC;IACf,aAAa,EAAE,CAAC;IAChB,oBAAoB,EAAE,CAAC;CACxB,CAAC;AAEF,oEAAoE;AACpE,MAAM,UAAU,sCAAsC;IACpD,OAAO,EAAE,GAAG,kBAAkB,EAAE,CAAC;AACnC,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,gDAAgD;IAC9D,kBAAkB,CAAC,WAAW,GAAG,CAAC,CAAC;IACnC,kBAAkB,CAAC,YAAY,GAAG,CAAC,CAAC;IACpC,kBAAkB,CAAC,aAAa,GAAG,CAAC,CAAC;IACrC,kBAAkB,CAAC,oBAAoB,GAAG,CAAC,CAAC;AAC9C,CAAC;AAwFD,MAAM,OAAO,2BAA2B;IACrB,MAAM,CAA8B;IACpC,GAAG,CAA+B;IAClC,MAAM,CAAwB;IAC9B,KAAK,CAAuB;IAC5B,OAAO,CAAU;IACjB,MAAM,CAAU;IAChB,GAAG,CAAwB;IAC3B,KAAK,CAAe;IAErC,YAAY,IAAwC;QAClD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;QAClC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;QAChE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,OAAO,EAAE,CAAC;QACvC,0EAA0E;QAC1E,yEAAyE;QACzE,IAAI,CAAC,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9F,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,KAAK,KAAK,CAAC;QACpE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,iEAAiE;IACjE,SAAS;QACP,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IACxD,CAAC;IAED;;;OAGG;IACH,gBAAgB,CAAC,CAAqB;QACpC,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,OAAO;gBAAE,OAAO;YAC1B,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,UAAU;gBAAE,OAAO,CAAC,2CAA2C;YACrF,MAAM,aAAa,GAAG,OAAO,CAAC,CAAC,UAAU,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;YACvG,IAAI,CAAC,aAAa;gBAAE,OAAO,CAAC,wCAAwC;YACpE,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;YACxD,wEAAwE;YACxE,uEAAuE;YACvE,6BAA6B;YAC7B,IAAI,CAAC,KAAK;gBAAE,kBAAkB,CAAC,oBAAoB,EAAE,CAAC;YACtD,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC,gCAAgC;YAE/F,yEAAyE;YACzE,mEAAmE;YACnE,MAAM,OAAO,GAAG,uBAAuB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;YACxD,MAAM,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAE1D,MAAM,aAAa,GAAG;gBACpB,aAAa,EAAE,CAAC,CAAC,aAAa;gBAC9B,aAAa;gBACb,OAAO,EAAE,KAAK,EAAE,SAAS;gBACzB,YAAY,EAAE,OAAO,CAAC,KAAK;gBAC3B,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,WAAW;gBACX,YAAY,EAAE,KAAK,EAAE,YAAY;gBACjC,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,SAAS;gBAC3D,KAAK,EAAE,CAAC,CAAC,cAAc,CAAC,KAAK;gBAC7B,SAAS,EAAE,CAAC,CAAC,cAAc,CAAC,SAAS;gBACrC,QAAQ,EAAE,MAAM,CAAC,KAAK;gBACtB,EAAE,EAAE,CAAC,CAAC,WAAW;aAClB,CAAC;YAEF,uEAAuE;YACvE,uEAAuE;YACvE,wEAAwE;YACxE,MAAM,OAAO,GAA4B;gBACvC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,IAAI,EAAE,CAAC;gBAC/B,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnG,GAAG,CAAC,CAAC,CAAC,eAAe,KAAK,SAAS;oBACjC,CAAC,CAAC,EAAE,eAAe,EAAE,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,EAAE;oBAClF,CAAC,CAAC,EAAE,CAAC;gBACP,GAAG,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC1F,CAAC;YACF,MAAM,QAAQ,GAAqB;gBACjC,SAAS,EAAE,KAAK,EAAE,SAAS,IAAI,WAAW;gBAC1C,aAAa;gBACb,OAAO;gBACP,gBAAgB,EAAE,CAAC,CAAC,UAAU,CAAC,gBAAgB,IAAI,EAAE;gBACrD,QAAQ,EAAE,CAAC,CAAC,YAAY,EAAE,0CAA0C;gBACpE,MAAM,EAAE,mBAAmB;gBAC3B,KAAK,EAAE,8BAA8B;gBACrC,YAAY,EAAE,KAAK;gBACnB,mEAAmE;gBACnE,sEAAsE;gBACtE,kEAAkE;gBAClE,OAAO,EAAE,WAAW,KAAK,MAAM;gBAC/B,KAAK,EAAE,CAAC,CAAC,cAAc,CAAC,KAAK;gBAC7B,QAAQ,EAAE,CAAC,CAAC,cAAc,CAAC,KAAK,EAAE,WAAW;gBAC7C,SAAS,EAAE,CAAC,CAAC,cAAc,CAAC,KAAK,EAAE,YAAY;gBAC/C,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,UAAU,CAAC;gBACpD,aAAa,EAAE,CAAC,CAAC,aAAa;gBAC9B,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,QAAQ,EAAE,6BAA6B;gBAC9D,YAAY,EAAE,KAAK,EAAE,YAAY;gBACjC,QAAQ,EAAE,CAAC,CAAC,QAAQ;aACrB,CAAC;YAEF,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,mEAAmE;gBACnE,qEAAqE;gBACrE,mEAAmE;gBACnE,0DAA0D;gBAC1D,MAAM,WAAW,GAAG,IAAI,CAAC,uBAAuB,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,CAAC,CAAC;gBAChG,IAAI,CAAC,GAAG,CACN,wDAAwD,SAAS,CAAC,aAAa,CAAC,GAAG;oBACjF,aAAa,SAAS,CAAC,KAAK,EAAE,SAAS,IAAI,SAAS,CAAC,WAAW,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,GAAG;oBACnG,eAAe,WAAW,IAAI,MAAM,iBAAiB,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,WAAW,GAAG;oBACrG,mBAAmB,UAAU,CAAC,aAAa,CAAC,uBAAuB,UAAU,CAAC,QAAQ,CAAC,EAAE,CAC5F,CAAC;gBACF,OAAO;YACT,CAAC;YAED,wEAAwE;YACxE,+CAA+C;YAC/C,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;YAE3C,4EAA4E;YAC5E,MAAM,WAAW,GAAG,IAAI,CAAC,uBAAuB,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/F,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;gBAC5B,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;YACrC,CAAC;iBAAM,IAAI,WAAW,KAAK,gBAAgB,EAAE,CAAC;gBAC5C,iCAAiC;gBACjC,IAAI,CAAC,MAAM,EAAE,kBAAkB,CAAC,aAAa,EAAE,iBAAiB,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YAC3F,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wEAAwE;YACxE,qEAAqE;YACrE,IAAI,CAAC,GAAG,CAAC,oEAAqE,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACzG,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACK,uBAAuB,CAC7B,WAA+B,EAC/B,CAAqB,EACrB,IAAqC;QAErC,IAAI,CAAC,WAAW;YAAE,OAAO,iBAAiB,CAAC;QAC3C,IAAI,WAAW,KAAK,MAAM;YAAE,OAAO,OAAO,CAAC;QAC3C,IAAI,WAAW,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;YAC1D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,OAAO,OAAO,CAAC;YAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;YAC/C,OAAO,iBAAiB,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC;QAChF,CAAC;QACD,IAAI,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACtC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;YACxE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;gBAAE,OAAO,OAAO,CAAC;YAC5D,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;YAClC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;YAClF,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,UAAU,EAAE,aAAa,IAAI,EAAE,EAAE,WAAW,CAAC,IAAI,IAAI,CAAC;YACzG,IAAI,OAAO,KAAK,IAAI;gBAAE,OAAO,OAAO,CAAC,CAAC,kDAAkD;YACxF,MAAM,kBAAkB,GAAG,OAAO,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACvE,OAAO,kBAAkB,IAAI,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC;QACnE,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,CAAiC;QAC/C,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,OAAO;gBAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;YAC7D,6CAA6C;YAC7C,IAAI,CAAC,CAAC,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxE,kBAAkB,CAAC,WAAW,EAAE,CAAC;gBACjC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;YACtD,CAAC;YACD,wEAAwE;YACxE,2DAA2D;YAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC1C,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,kBAAkB,CAAC,YAAY,EAAE,CAAC;gBAClC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;YACvD,CAAC;YACD,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC/D,kBAAkB,CAAC,YAAY,EAAE,CAAC;gBAClC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;YACvD,CAAC;YACD,uEAAuE;YACvE,qDAAqD;YACrD,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC,eAAe,EAAE,CAAC;gBACnD,kBAAkB,CAAC,aAAa,EAAE,CAAC;gBACnC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;YACxD,CAAC;YACD,0EAA0E;YAC1E,IAAI,CAAC,CAAC,aAAa,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC;gBAClF,kBAAkB,CAAC,oBAAoB,EAAE,CAAC;gBAC1C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,wBAAwB,EAAE,CAAC;YAChE,CAAC;YACD,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAChC,qEAAqE;YACrE,qCAAqC;YACrC,MAAM,YAAY,GAChB,CAAC,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAE/G,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,wEAAwE;gBACxE,IAAI,CAAC,GAAG,CACN,2DAA2D,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG;oBACtF,UAAU,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,IAAI,UAAU,CAAC,CAAC,KAAK,aAAa,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE;oBAC9G,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,sBAAsB,MAAM,CAAC,UAAU,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACtG,CAAC;gBACF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YAC1C,CAAC;YAED,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC;gBACrC,aAAa,EAAE,CAAC,CAAC,aAAa;gBAC9B,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS;gBAC9B,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,IAAI,EAAE,IAAI,CAAC,IAAmB;gBAC9B,gBAAgB,EAAE,IAAI,CAAC,gBAAoC;gBAC3D,KAAK,EAAE,CAAC,CAAC,KAAsB;gBAC/B,iBAAiB,EAAE,IAAI,CAAC,QAAQ;gBAChC,YAAY;gBACZ,aAAa,EAAE,CAAC,CAAC,aAAa;gBAC9B,EAAE;aACH,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,EAAE,OAAO;gBAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YAC7C,qEAAqE;YACrE,sEAAsE;YACtE,uCAAuC;YACvC,IAAI,CAAC,GAAG,EAAE,eAAe,CACvB,CAAC,CAAC,aAAa,EACf,CAAC,CAAC,QAAQ,CAAC,SAAS,EACpB;gBACE,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC;gBACrB,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnE,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7D,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;aACxC,EACD,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CACrE,CAAC;YACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;QAC/C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,uEAAuE;YACvE,oEAAoE;YACpE,IAAI,CAAC,GAAG,CAAC,sEAAuE,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;YACzG,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC;CACF;AAED,iFAAiF;AAEjF,IAAI,gBAAgB,GAAuC,IAAI,CAAC;AAEhE;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAAC,IAAwC;IACrF,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACjC,gBAAgB,GAAG,IAAI,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,CAAiC;IACvE,IAAI,CAAC,gBAAgB;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACjE,OAAO,gBAAgB,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,+EAA+E;AAE/E,6EAA6E;AAC7E,SAAS,SAAS,CAAC,CAAS;IAC1B,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,UAAU,CAAC,CAAU;IAC5B,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;QACtE,wEAAwE;QACxE,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,aAAqB;IACtD,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC5C,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClB,0DAA0D;IAC1D,IAAI,iEAAiE,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9F,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/core/IntelligenceRouter.d.ts

@@ -496,6 +496,39 @@ export declare class IntelligenceRouter implements IntelligenceProvider {
      */
     private warnNatureChainRejected;
     evaluate(prompt: string, options?: IntelligenceOptions): Promise<string>;
+    /**
+     * Mint the per-decision correlation id on a router-INTERNAL clone (§5.1.1).
+     * The caller's options object is NEVER mutated; `options.provenance` is
+     * consumed here (stripped before any per-attempt spread can carry it down —
+     * §5.1.6); `onCorrelationId` fires synchronously at mint, exactly once per
+     * `evaluate()` invocation INCLUDING calls that later throw, never after
+     * settlement — and a throwing callback is caught + counted, never propagated
+     * (the decision call is never failed by its audit trail, §5.1.4).
+     */
+    private mintDecision;
+    /**
+     * Run ONE attempt of the current decision (§5.1.5 — per-attempt capture
+     * scoping). Every attempt gets a FRESH options object: a spread of the
+     * internal clone (the symbol-keyed correlation id + mint marker ride the
+     * spread; the breaker consumes each copy's marker single-use) with fresh
+     * capture wrappers composed over the caller's callbacks and any attempt
+     * extras. Only the attempt whose promise the router actually returns
+     * contributes its capture to the settlement: a rejected attempt's callbacks
+     * land in its own unread capture, and any callback firing AFTER settlement
+     * (a withSwapTimeout-abandoned attempt) is discarded by the settled latch.
+     */
+    private runAttempt;
+    /** Write-once settlement on a SUCCESSFUL exit (FD7). */
+    private settleDecision;
+    /**
+     * Write-once settlement on ANY throwing exit (FD7): the decision still yields
+     * exactly one row — `'<errored>'` + the error class — so failure-swap-ladder
+     * quality is itself gradeable, without N phantom decisions.
+     */
+    private settleDecisionErrored;
+    /** The single settlement write — isolated so a recorder throw can never reach the decision path (§5.1.7). */
+    private recordSettlement;
+    private evaluateRouted;
     /**
      * NON-GATING bounded failure-swap (docs/specs/nongating-failure-swap.md). Invoked ONLY from
      * the non-gating branch of evaluate() after the PRIMARY suffered an INVOCATION-level failure