@dsh-enhanced/assistant-evaluation 0.1.65 → 0.1.67

package/lib/attention-tuning.js

@@ -0,0 +1,1044 @@
+import { createHash } from 'node:crypto';
+import { canonicalEvaluationScope, EvaluationStoreError } from './store.js';
+/**
+ * WP22 slice 2: bounded, tighten-only attention tuning with exact-version
+ * cohort rollback. A cohort is one notification `(lane, sourceId)` inside one
+ * Evaluation scope. Versions are immutable and bound to their exact parent.
+ *
+ * WP22 slice 3 (explicit opt-in): a loosening request is sealed against a
+ * hash-partitioned holdout the proposer never reads, replayed independently
+ * on a later tick, and adopted only inside an owner one-time grant; outside
+ * it a structured owner question is recorded instead. Without the opt-in,
+ * loosening is rejected exactly as in slice 2.
+ */
+export const ATTENTION_TUNING_PROTOCOL = 'assistant-evaluation/attention-tuning/v1';
+/** Fixed code constants; neither configuration nor a request can widen them. */
+export const attentionTuningBounds = Object.freeze({
+    interruptionCostDelta: Object.freeze({ min: 0, max: 100, step: 10 }),
+    minimumUtilityDelta: Object.freeze({ min: 0, max: 100, step: 10 }),
+    quietExtensionMinutes: Object.freeze({ min: 0, max: 120, step: 30 }),
+});
+/** Fixed single-step order: cheapest reversible lever first, mute last. */
+export const attentionTuningOrder = Object.freeze(['interruptionCostDelta', 'minimumUtilityDelta', 'quietExtensionMinutes', 'muted']);
+export const defaultAttentionTuningParameters = Object.freeze({
+    interruptionCostDelta: 0, minimumUtilityDelta: 0, quietExtensionMinutes: 0, muted: false,
+});
+function invalid(message) {
+    throw new EvaluationStoreError('invalid-input', `attention tuning: ${message}`);
+}
+function stable(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).filter(key => record[key] !== undefined).sort()
+        .map(key => `${JSON.stringify(key)}:${stable(record[key])}`).join(',')}}`;
+}
+function sha256(value) {
+    return createHash('sha256').update(stable(value)).digest('hex');
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object') {
+        for (const entry of Object.values(value))
+            deepFreeze(entry);
+        Object.freeze(value);
+    }
+    return value;
+}
+function identifier(value, label, max) {
+    if (typeof value !== 'string' || value.length < 1 || value.length > max || value.trim() !== value || /\p{Cc}/u.test(value)) {
+        invalid(`${label} must be a bounded identifier`);
+    }
+    return value;
+}
+export function normalizeAttentionCohort(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid('cohort must be an object');
+    const record = input;
+    if (Object.keys(record).some(key => key !== 'lane' && key !== 'sourceId'))
+        invalid('cohort has unknown fields');
+    return Object.freeze({ lane: identifier(record.lane, 'cohort.lane', 64), sourceId: identifier(record.sourceId, 'cohort.sourceId', 256) });
+}
+/** Strict shape check only; bounds and step alignment are judged separately so a request can be recorded. */
+export function normalizeAttentionTuningParameters(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid('parameters must be an object');
+    const record = input;
+    const keys = Object.keys(record).sort();
+    if (stable(keys) !== stable([...attentionTuningOrder].sort()))
+        invalid('parameters must name exactly the tunable fields');
+    for (const key of ['interruptionCostDelta', 'minimumUtilityDelta', 'quietExtensionMinutes']) {
+        if (!Number.isSafeInteger(record[key]))
+            invalid(`${key} must be an integer`);
+    }
+    if (typeof record.muted !== 'boolean')
+        invalid('muted must be a boolean');
+    return Object.freeze({
+        interruptionCostDelta: record.interruptionCostDelta,
+        minimumUtilityDelta: record.minimumUtilityDelta,
+        quietExtensionMinutes: record.quietExtensionMinutes,
+        muted: record.muted,
+    });
+}
+/** Clamp every numeric field into its fixed bound (snapped down to the step grid). */
+export function clampAttentionTuning(input) {
+    const clamp = (key) => {
+        const { min, max, step } = attentionTuningBounds[key];
+        const value = Math.min(max, Math.max(min, Math.trunc(input[key])));
+        return min + Math.floor((value - min) / step) * step;
+    };
+    return Object.freeze({
+        interruptionCostDelta: clamp('interruptionCostDelta'),
+        minimumUtilityDelta: clamp('minimumUtilityDelta'),
+        quietExtensionMinutes: clamp('quietExtensionMinutes'),
+        muted: input.muted === true,
+    });
+}
+export function withinAttentionTuningBounds(input) {
+    return stable(clampAttentionTuning(input)) === stable(input);
+}
+/** True when any field would make notifications more frequent than `current`. */
+export function isAttentionLoosening(current, next) {
+    return next.interruptionCostDelta < current.interruptionCostDelta
+        || next.minimumUtilityDelta < current.minimumUtilityDelta
+        || next.quietExtensionMinutes < current.quietExtensionMinutes
+        || (current.muted && !next.muted);
+}
+function atLeastRate(numerator, denominator, ratePpm) {
+    return BigInt(numerator) * 1000000n >= BigInt(ratePpm) * BigInt(denominator);
+}
+/**
+ * Pure tighten-only tuner. With at least `minSample` decided notifications and
+ * a negative (rejected + expired-unhandled) rate at or above the threshold, it
+ * proposes exactly one step on the first non-maxed parameter in fixed order;
+ * mute additionally requires `muteRatePpm`. Never proposes loosening.
+ */
+export function proposeAttentionTuning(currentInput, stats, policy) {
+    const current = clampAttentionTuning(currentInput);
+    if (stats.decided < policy.minSample || stats.decided === 0)
+        return deepFreeze({ kind: 'no-op', reason: 'insufficient-sample' });
+    if (!atLeastRate(stats.negative, stats.decided, policy.negativeRatePpm))
+        return deepFreeze({ kind: 'no-op', reason: 'below-threshold' });
+    for (const parameter of attentionTuningOrder) {
+        if (parameter === 'muted') {
+            if (current.muted || !atLeastRate(stats.negative, stats.decided, policy.muteRatePpm))
+                continue;
+            return deepFreeze({ kind: 'tighten', change: { parameter, from: false, to: true }, parameters: { ...current, muted: true } });
+        }
+        const { max, step } = attentionTuningBounds[parameter];
+        if (current[parameter] >= max)
+            continue;
+        const to = Math.min(max, current[parameter] + step);
+        return deepFreeze({ kind: 'tighten', change: { parameter, from: current[parameter], to }, parameters: { ...current, [parameter]: to } });
+    }
+    return deepFreeze({ kind: 'no-op', reason: 'at-bound' });
+}
+/**
+ * Regression test for an observing version: the post-adoption negative rate
+ * must exceed the basis (parent-era) rate by more than the margin. Cross
+ * multiplication keeps it exact; acceptances only lower the rate, so positive
+ * evidence can never satisfy it.
+ */
+export function attentionRegressed(basis, post, policy) {
+    if (post.decided < policy.minSample || post.decided === 0 || basis.decided === 0)
+        return false;
+    const left = BigInt(post.negative) * BigInt(basis.decided) * 1000000n;
+    const right = BigInt(basis.negative) * BigInt(post.decided) * 1000000n + BigInt(policy.regressionMarginPpm) * BigInt(basis.decided) * BigInt(post.decided);
+    return left > right;
+}
+/**
+ * WP22 slice 3: sealed holdout partition. Membership is a pure function of the
+ * notification id under a fixed protocol salt and modulus, so it is
+ * reproducible by any auditor and never chosen by the proposer.
+ */
+export const ATTENTION_HOLDOUT_PROTOCOL = 'assistant-evaluation/attention-holdout/v1';
+export const attentionHoldoutModulus = 4;
+export const ATTENTION_LOOSENING_PROTOCOL = 'assistant-evaluation/attention-loosening/v1';
+export const ATTENTION_LOOSENING_GRANT_PROTOCOL = 'assistant-evaluation/attention-loosening-grant/v1';
+export const ATTENTION_OWNER_QUESTION_PROTOCOL = 'assistant-evaluation/attention-owner-question/v1';
+export function attentionHoldoutMember(notificationId) {
+    const hex = createHash('sha256').update(`${ATTENTION_HOLDOUT_PROTOCOL}\n${notificationId}`).digest('hex');
+    return Number.parseInt(hex.slice(0, 8), 16) % attentionHoldoutModulus === 0;
+}
+/** True when `a` suppresses at least everything `b` suppresses (every field at least as tight). */
+export function attentionTighterOrEqual(a, b) {
+    return a.interruptionCostDelta >= b.interruptionCostDelta
+        && a.minimumUtilityDelta >= b.minimumUtilityDelta
+        && a.quietExtensionMinutes >= b.quietExtensionMinutes
+        && (a.muted || !b.muted);
+}
+/** One parameter moved toward the default by whole grid steps, or an unmute; anything else is undefined. */
+export function attentionLooseningChange(current, next) {
+    const changed = attentionTuningOrder.filter(key => current[key] !== next[key]);
+    if (changed.length !== 1)
+        return undefined;
+    const parameter = changed[0];
+    if (parameter === 'muted')
+        return current.muted && !next.muted ? Object.freeze({ parameter, from: true, to: false, steps: 1 }) : undefined;
+    const delta = current[parameter] - next[parameter];
+    const { step } = attentionTuningBounds[parameter];
+    if (delta <= 0 || delta % step !== 0)
+        return undefined;
+    return Object.freeze({ parameter, from: current[parameter], to: next[parameter], steps: delta / step });
+}
+const positiveOutcomes = ['accepted', 'reacted'];
+/**
+ * Deterministic counterfactual replay of a loosening on holdout records.
+ * Notifications carry no per-message utility, so each is attributed by the
+ * era it was sent under: an era at least as tight as a configuration proves
+ * that configuration would also have sent it. Passing requires enough
+ * discriminating evidence, an extra-interruption rate below the tuning
+ * threshold minus the regression margin, a candidate-wide negative rate below
+ * the tightening threshold (so it would not be immediately re-tightened), and
+ * more owner-valued notifications recovered than extra interruptions added.
+ */
+export function replayAttentionLoosening(records, parent, candidate, policy) {
+    const tally = () => ({ decided: 0, positive: 0, negative: 0 });
+    const shared = tally();
+    const discriminating = tally();
+    const unattributable = tally();
+    for (const record of records) {
+        const positive = positiveOutcomes.includes(record.outcome);
+        const negative = negativeOutcomes.includes(record.outcome);
+        if (!positive && !negative)
+            continue;
+        const bucket = attentionTighterOrEqual(record.era, parent) ? shared
+            : attentionTighterOrEqual(record.era, candidate) ? discriminating : unattributable;
+        bucket.decided += 1;
+        if (positive)
+            bucket.positive += 1;
+        else
+            bucket.negative += 1;
+    }
+    const maxDiscriminatingNegativeRatePpm = Math.max(0, policy.negativeRatePpm - policy.regressionMarginPpm);
+    const candidateDecided = shared.decided + discriminating.decided;
+    const candidateNegative = shared.negative + discriminating.negative;
+    const reason = discriminating.decided < policy.minSample || discriminating.decided === 0 ? 'insufficient-holdout'
+        : BigInt(discriminating.negative) * 1000000n > BigInt(maxDiscriminatingNegativeRatePpm) * BigInt(discriminating.decided) ? 'extra-interruptions'
+            : atLeastRate(candidateNegative, candidateDecided, policy.negativeRatePpm) ? 'candidate-negative-rate'
+                : discriminating.positive <= discriminating.negative ? 'no-net-benefit'
+                    : undefined;
+    return deepFreeze({
+        protocol: ATTENTION_LOOSENING_PROTOCOL, shared, discriminating, unattributable,
+        parent: { falsePositives: shared.negative, misses: discriminating.positive },
+        candidate: { falsePositives: candidateNegative, misses: 0 },
+        thresholds: { minSample: policy.minSample, maxDiscriminatingNegativeRatePpm, maxCandidateNegativeRatePpm: policy.negativeRatePpm },
+        verdict: reason === undefined ? 'pass' : 'fail',
+        ...(reason === undefined ? {} : { reason }),
+    });
+}
+export function normalizeAttentionLooseningGrant(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid('grant must be an object');
+    const record = input;
+    const fields = ['expiresAt', 'grantId', 'lowerBound', 'maxAdoptions', 'maxStepsPerAdoption', 'upperBound'];
+    if (stable(Object.keys(record).sort()) !== stable(fields))
+        invalid('grant must name exactly the grant fields');
+    const grantId = identifier(record.grantId, 'grant.grantId', 128);
+    const lowerBound = normalizeAttentionTuningParameters(record.lowerBound);
+    const upperBound = normalizeAttentionTuningParameters(record.upperBound);
+    if (!withinAttentionTuningBounds(lowerBound) || !withinAttentionTuningBounds(upperBound))
+        invalid('grant bounds must lie on the fixed tuning grid');
+    if (!attentionTighterOrEqual(upperBound, lowerBound))
+        invalid('grant upperBound must be at least as tight as lowerBound');
+    const integer = (key, min, max) => {
+        const value = record[key];
+        if (!Number.isSafeInteger(value) || value < min || value > max)
+            invalid(`grant.${key} must be an integer in [${min}, ${max}]`);
+        return value;
+    };
+    return deepFreeze({
+        grantId, lowerBound: { ...lowerBound }, upperBound: { ...upperBound },
+        // A sealed proposal moves one parameter by whole grid steps; the widest
+        // fixed grid (interruptionCostDelta 0..100 step 10) allows 10. Capping
+        // grants lower would make an exact one-time grant impossible to state.
+        maxStepsPerAdoption: integer('maxStepsPerAdoption', 1, 10),
+        maxAdoptions: integer('maxAdoptions', 1, 10),
+        expiresAt: integer('expiresAt', 0, Number.MAX_SAFE_INTEGER),
+    });
+}
+/** Every way a holdout-accepted loosening falls outside the active grant; empty means adoptable. */
+export function attentionGrantExceeded(grant, used, parent, candidate, steps, now) {
+    if (grant === undefined)
+        return Object.freeze(['no-grant']);
+    const exceeded = [];
+    if (now >= grant.expiresAt)
+        exceeded.push('grant-expired');
+    if (used >= grant.maxAdoptions)
+        exceeded.push('grant-exhausted');
+    if (!attentionTighterOrEqual(grant.upperBound, parent) || !attentionTighterOrEqual(candidate, grant.lowerBound))
+        exceeded.push('outside-bounds');
+    if (steps > grant.maxStepsPerAdoption)
+        exceeded.push('step-too-large');
+    return Object.freeze(exceeded);
+}
+/** Single-step tightening check for an explicit request. */
+function singleStep(current, next) {
+    const changed = attentionTuningOrder.filter(key => current[key] !== next[key]);
+    if (changed.length !== 1)
+        return undefined;
+    const parameter = changed[0];
+    if (parameter === 'muted')
+        return { parameter, from: current.muted, to: next.muted };
+    if (next[parameter] - current[parameter] !== attentionTuningBounds[parameter].step)
+        return undefined;
+    return { parameter, from: current[parameter], to: next[parameter] };
+}
+function versionDigest(input) {
+    return sha256({
+        protocol: input.protocol, scopeKey: input.scopeKey, cohort: input.cohort, version: input.version,
+        parentVersion: input.parentVersion, parentDigest: input.parentDigest, parameters: input.parameters,
+        basis: input.basis, change: input.change, origin: input.origin,
+    });
+}
+const negativeOutcomes = ['rejected', 'expired-unhandled'];
+/**
+ * Cohort filter: a linked-alias fallback report reached the owner on another
+ * channel, so its outcome says nothing about the origin cohort's parameters.
+ * Stats, holdout seals/replays and cohort discovery all use this filter;
+ * route-free (pre-existing) records count as origin.
+ */
+const originRoute = `coalesce(json_extract(r.record_json, '$.route.kind'), 'origin')='origin'`;
+/**
+ * Durable ledger over the same Evaluation database as the notification canon.
+ * All decisions recompute inside BEGIN IMMEDIATE so concurrent ticks or a
+ * restart mid-observation converge on one head.
+ */
+export class AttentionTuningLedger {
+    #database;
+    #now;
+    #questions;
+    constructor(database, now, questions) {
+        this.#database = database;
+        this.#now = now;
+        this.#questions = questions;
+    }
+    #transaction(fn) {
+        this.#database.exec('BEGIN IMMEDIATE');
+        try {
+            const value = fn();
+            this.#database.exec('COMMIT');
+            return value;
+        }
+        catch (error) {
+            this.#database.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    /** Current-head (id, outcome, notifiedAt) rows for one cohort, notified in [from, to), in id order. */
+    #records(scopeKey, cohort, fromNotifiedAt, toNotifiedAt) {
+        return this.#database.prepare(`SELECT h.notification_id AS notification_id, h.outcome AS outcome, h.occurred_at AS occurred_at
+      FROM evaluation_notification_outcome_heads h
+      JOIN evaluation_notification_outcome_revisions r ON r.notification_id=h.notification_id AND r.version=h.version
+      WHERE h.scope_key=? AND h.occurred_at>=? AND h.occurred_at<?
+        AND json_extract(r.record_json, '$.lane')=? AND json_extract(r.record_json, '$.sourceId')=?
+        AND ${originRoute}
+      ORDER BY h.notification_id`).all(scopeKey, fromNotifiedAt, toNotifiedAt, cohort.lane, cohort.sourceId);
+    }
+    /** Holdout membership for a window: ids only. Outcomes are deliberately not part of the seal. */
+    #holdout(scopeKey, cohort, fromNotifiedAt, toNotifiedAt) {
+        const ids = this.#records(scopeKey, cohort, fromNotifiedAt, toNotifiedAt).map(row => row.notification_id).filter(attentionHoldoutMember);
+        const digest = sha256({ protocol: ATTENTION_HOLDOUT_PROTOCOL, modulus: attentionHoldoutModulus, scopeKey, cohort: { lane: cohort.lane, sourceId: cohort.sourceId },
+            fromNotifiedAt, toNotifiedAt, ids });
+        return deepFreeze({ ids, seal: { protocol: ATTENTION_HOLDOUT_PROTOCOL, modulus: attentionHoldoutModulus, count: ids.length, digest } });
+    }
+    /**
+     * Current-head outcome counts for one cohort, notified in [from, to).
+     * `training` excludes the sealed holdout partition; every proposer uses it
+     * once the slice-3 opt-in is on, so no proposal is fitted to holdout data.
+     */
+    stats(scopeKey, cohort, fromNotifiedAt, toNotifiedAt, partition = 'all') {
+        if (partition === 'training') {
+            const counts = new Map();
+            for (const row of this.#records(scopeKey, cohort, fromNotifiedAt, toNotifiedAt)) {
+                if (!attentionHoldoutMember(row.notification_id))
+                    counts.set(row.outcome, (counts.get(row.outcome) ?? 0) + 1);
+            }
+            return this.#summarize(fromNotifiedAt, toNotifiedAt, [...counts].map(([outcome, count]) => ({ outcome, count })));
+        }
+        const rows = this.#database.prepare(`SELECT h.outcome AS outcome, COUNT(*) AS count
+      FROM evaluation_notification_outcome_heads h
+      JOIN evaluation_notification_outcome_revisions r ON r.notification_id=h.notification_id AND r.version=h.version
+      WHERE h.scope_key=? AND h.occurred_at>=? AND h.occurred_at<?
+        AND json_extract(r.record_json, '$.lane')=? AND json_extract(r.record_json, '$.sourceId')=?
+        AND ${originRoute}
+      GROUP BY h.outcome`).all(scopeKey, fromNotifiedAt, toNotifiedAt, cohort.lane, cohort.sourceId);
+        return this.#summarize(fromNotifiedAt, toNotifiedAt, rows);
+    }
+    #summarize(fromNotifiedAt, toNotifiedAt, rows) {
+        const count = (outcome) => rows.find(row => row.outcome === outcome)?.count ?? 0;
+        const accepted = count('accepted');
+        const reacted = count('reacted');
+        const rejected = count('rejected');
+        const expiredUnhandled = count('expired-unhandled');
+        return Object.freeze({
+            fromNotifiedAt, toNotifiedAt,
+            total: rows.reduce((sum, row) => sum + row.count, 0),
+            accepted, reacted, rejected, expiredUnhandled,
+            decided: accepted + reacted + rejected + expiredUnhandled,
+            negative: negativeOutcomes.reduce((sum, outcome) => sum + count(outcome), 0),
+        });
+    }
+    /** Scopes that have at least one notification in the cohort, plus scopes with a tuning head. */
+    scopes(cohort) {
+        const rows = this.#database.prepare(`SELECT DISTINCT json_extract(r.record_json, '$.scope.workspace') AS workspace,
+        json_extract(r.record_json, '$.scope.preset') AS preset
+      FROM evaluation_notification_outcome_heads h
+      JOIN evaluation_notification_outcome_revisions r ON r.notification_id=h.notification_id AND r.version=h.version
+      WHERE json_extract(r.record_json, '$.lane')=? AND json_extract(r.record_json, '$.sourceId')=? AND ${originRoute}
+      UNION SELECT workspace, preset FROM evaluation_attention_tuning_heads WHERE lane=? AND source_id=?
+      ORDER BY workspace, preset`).all(cohort.lane, cohort.sourceId, cohort.lane, cohort.sourceId);
+        return Object.freeze(rows.map(row => Object.freeze({ workspace: row.workspace, preset: row.preset })));
+    }
+    #scopeWatermark(scopeKey) {
+        return this.#database.prepare('SELECT watermark FROM evaluation_notification_watermarks WHERE scope_key=?')
+            .get(scopeKey)?.watermark ?? 0;
+    }
+    #head(scopeKey, cohort) {
+        return this.#database.prepare('SELECT * FROM evaluation_attention_tuning_heads WHERE scope_key=? AND lane=? AND source_id=?')
+            .get(scopeKey, cohort.lane, cohort.sourceId);
+    }
+    #row(scopeKey, cohort, version) {
+        return this.#database.prepare('SELECT * FROM evaluation_attention_tuning_versions WHERE scope_key=? AND lane=? AND source_id=? AND version=?')
+            .get(scopeKey, cohort.lane, cohort.sourceId, version);
+    }
+    /** Parse and digest-verify one stored version; undefined when unreadable or tampered. */
+    #verified(scopeKey, cohort, version) {
+        const row = this.#row(scopeKey, cohort, version);
+        if (row === undefined)
+            return undefined;
+        try {
+            const parentDigest = row.parent_version === 0 ? null : this.#row(scopeKey, cohort, row.parent_version)?.digest ?? null;
+            if (row.parent_version !== 0 && parentDigest === null)
+                return undefined;
+            const parameters = normalizeAttentionTuningParameters(JSON.parse(row.parameters_json));
+            if (!withinAttentionTuningBounds(parameters))
+                return undefined;
+            const body = {
+                protocol: ATTENTION_TUNING_PROTOCOL, scopeKey, cohort: { lane: cohort.lane, sourceId: cohort.sourceId }, version: row.version,
+                parentVersion: row.parent_version, parentDigest, parameters,
+                basis: JSON.parse(row.basis_json),
+                change: JSON.parse(row.change_json), origin: row.origin,
+            };
+            if (versionDigest(body) !== row.digest)
+                return undefined;
+            return deepFreeze({ ...body, digest: row.digest, createdAt: row.created_at });
+        }
+        catch {
+            return undefined;
+        }
+    }
+    #versionNumbers(scopeKey, cohort) {
+        return this.#database.prepare('SELECT version FROM evaluation_attention_tuning_versions WHERE scope_key=? AND lane=? AND source_id=? ORDER BY version')
+            .all(scopeKey, cohort.lane, cohort.sourceId).map(row => row.version);
+    }
+    /**
+     * Active parameters for a consumer. A version that cannot be read or fails
+     * digest verification falls back along its recorded parent chain, then to
+     * the built-in default; a consumer never sees an unverified overlay.
+     */
+    current(scopeInput, cohortInput) {
+        const { scopeKey } = canonicalEvaluationScope(scopeInput);
+        const cohort = normalizeAttentionCohort(cohortInput);
+        return this.#current(scopeKey, cohort);
+    }
+    #current(scopeKey, cohort) {
+        const active = this.#head(scopeKey, cohort)?.active_version ?? 0;
+        let version = active;
+        let fallback = false;
+        const seen = new Set();
+        while (version > 0 && !seen.has(version)) {
+            seen.add(version);
+            const verified = this.#verified(scopeKey, cohort, version);
+            if (verified !== undefined) {
+                return deepFreeze({ scopeKey, cohort: { ...cohort }, version, digest: verified.digest, parameters: { ...verified.parameters }, source: fallback ? 'parent-fallback' : 'active' });
+            }
+            fallback = true;
+            const parent = this.#database.prepare('SELECT parent_version FROM evaluation_attention_tuning_versions WHERE scope_key=? AND lane=? AND source_id=? AND version=?')
+                .get(scopeKey, cohort.lane, cohort.sourceId, version)?.parent_version;
+            version = Number.isSafeInteger(parent) && parent >= 0 && parent < version ? parent : 0;
+        }
+        return deepFreeze({ scopeKey, cohort: { ...cohort }, version: 0, digest: null, parameters: { ...defaultAttentionTuningParameters }, source: active === 0 ? 'active' : 'default' });
+    }
+    status(scopeInput, cohortInput, eventLimit = 50) {
+        const { scopeKey } = canonicalEvaluationScope(scopeInput);
+        const cohort = normalizeAttentionCohort(cohortInput);
+        const head = this.#head(scopeKey, cohort);
+        const versions = this.#versionNumbers(scopeKey, cohort)
+            .map(version => this.#verified(scopeKey, cohort, version)).filter(value => value !== undefined);
+        const events = this.#database.prepare(`SELECT sequence, kind, from_version, to_version, reason, detail_json, occurred_at
+      FROM evaluation_attention_tuning_events WHERE scope_key=? AND lane=? AND source_id=? ORDER BY sequence DESC LIMIT ?`)
+            .all(scopeKey, cohort.lane, cohort.sourceId, eventLimit).reverse().map(row => ({
+            sequence: row.sequence, kind: row.kind, fromVersion: row.from_version, toVersion: row.to_version,
+            reason: row.reason, detail: JSON.parse(row.detail_json), occurredAt: row.occurred_at,
+        }));
+        return deepFreeze({
+            current: this.#current(scopeKey, cohort),
+            state: head?.state ?? 'idle',
+            ...(head?.observe_from == null ? {} : { observeFrom: head.observe_from }),
+            ...(head?.observe_until == null ? {} : { observeUntil: head.observe_until }),
+            versions, events,
+        });
+    }
+    #event(scopeKey, cohort, kind, fromVersion, toVersion, reason, detail, idempotencyKey, now) {
+        this.#database.prepare(`INSERT INTO evaluation_attention_tuning_events
+      (scope_key, lane, source_id, kind, from_version, to_version, reason, detail_json, idempotency_key, occurred_at) VALUES (?,?,?,?,?,?,?,?,?,?)
+      ON CONFLICT(idempotency_key) DO NOTHING`)
+            .run(scopeKey, cohort.lane, cohort.sourceId, kind, fromVersion, toVersion, reason, stable(detail), idempotencyKey, now);
+    }
+    #adopt(scope, scopeKey, cohort, head, current, proposal, stats, origin, observationMs, now, loosening) {
+        // Parent is the verified version the consumer is actually running.
+        const parentVersion = current.version;
+        const scopeWatermark = this.#scopeWatermark(scopeKey);
+        const idempotencyKey = `adopt:${sha256([scopeKey, cohort.lane, cohort.sourceId, parentVersion, current.digest, scopeWatermark, proposal.change, origin,
+            ...(loosening === undefined ? [] : [loosening.proposalId])])}`;
+        const existing = this.#database.prepare('SELECT version FROM evaluation_attention_tuning_versions WHERE idempotency_key=?')
+            .get(idempotencyKey);
+        if (existing !== undefined)
+            return existing.version;
+        const version = (head?.latest_version ?? 0) + 1;
+        const body = {
+            protocol: ATTENTION_TUNING_PROTOCOL, scopeKey, cohort: { lane: cohort.lane, sourceId: cohort.sourceId }, version,
+            parentVersion, parentDigest: current.digest, parameters: proposal.parameters,
+            basis: { stats, scopeWatermark }, change: proposal.change, origin,
+        };
+        const digest = versionDigest(body);
+        this.#database.prepare(`INSERT INTO evaluation_attention_tuning_versions
+      (scope_key, lane, source_id, version, parent_version, parameters_json, basis_json, change_json, origin, digest, idempotency_key, created_at)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`).run(scopeKey, cohort.lane, cohort.sourceId, version, parentVersion, stable(body.parameters), stable(body.basis), stable(body.change), origin, digest, idempotencyKey, now);
+        const observeUntil = now + observationMs;
+        if (head === undefined) {
+            this.#database.prepare(`INSERT INTO evaluation_attention_tuning_heads
+        (scope_key, lane, source_id, workspace, preset, active_version, latest_version, state, observing_version, observe_from, observe_until, changed_at)
+        VALUES (?,?,?,?,?,?,?, 'observing', ?,?,?,?)`).run(scopeKey, cohort.lane, cohort.sourceId, scope.workspace, scope.preset, version, version, version, now, observeUntil, now);
+        }
+        else {
+            this.#database.prepare(`UPDATE evaluation_attention_tuning_heads SET active_version=?, latest_version=?, state='observing',
+        observing_version=?, observe_from=?, observe_until=?, changed_at=? WHERE scope_key=? AND lane=? AND source_id=?`)
+                .run(version, version, version, now, observeUntil, now, scopeKey, cohort.lane, cohort.sourceId);
+        }
+        this.#event(scopeKey, cohort, 'adopted', parentVersion, version, loosening !== undefined ? 'holdout-accepted' : origin === 'auto' ? 'negative-rate-threshold' : 'owner-request', { digest, change: proposal.change, stats, scopeWatermark, ...loosening }, idempotencyKey, now);
+        return version;
+    }
+    /**
+     * One deterministic step for one cohort: monitor an observing version
+     * (rollback to its exact parent on regression, settle at window end), or
+     * when idle propose and adopt a single bounded tightening step.
+     */
+    tick(scopeInput, cohortInput, policy, options) {
+        const { scope, scopeKey } = canonicalEvaluationScope(scopeInput);
+        const cohort = normalizeAttentionCohort(cohortInput);
+        return this.#transaction(() => {
+            const now = this.#now();
+            const head = this.#head(scopeKey, cohort);
+            if (head?.state === 'observing') {
+                const observed = head.observing_version;
+                const version = this.#verified(scopeKey, cohort, observed);
+                const post = this.stats(scopeKey, cohort, head.observe_from, now + 1);
+                // An unverifiable observing version is reverted exactly like a regression.
+                if (version === undefined || attentionRegressed(version.basis.stats, post, policy)) {
+                    const parent = this.#database.prepare('SELECT parent_version FROM evaluation_attention_tuning_versions WHERE scope_key=? AND lane=? AND source_id=? AND version=?')
+                        .get(scopeKey, cohort.lane, cohort.sourceId, observed)?.parent_version ?? 0;
+                    this.#database.prepare(`UPDATE evaluation_attention_tuning_heads SET active_version=?, state='idle', observing_version=NULL,
+            observe_from=NULL, observe_until=NULL, changed_at=? WHERE scope_key=? AND lane=? AND source_id=?`)
+                        .run(parent, now, scopeKey, cohort.lane, cohort.sourceId);
+                    this.#event(scopeKey, cohort, 'rolled-back', observed, parent, version === undefined ? 'version-unverifiable' : 'negative-rate-regressed', { basis: version?.basis.stats ?? null, post }, `rollback:${sha256([scopeKey, cohort.lane, cohort.sourceId, observed, parent])}`, now);
+                    return Object.freeze({ action: 'rolled-back', fromVersion: observed, toVersion: parent });
+                }
+                if (now >= head.observe_until) {
+                    this.#database.prepare(`UPDATE evaluation_attention_tuning_heads SET state='idle', observing_version=NULL,
+            observe_from=NULL, observe_until=NULL, changed_at=? WHERE scope_key=? AND lane=? AND source_id=?`)
+                        .run(now, scopeKey, cohort.lane, cohort.sourceId);
+                    this.#event(scopeKey, cohort, 'settled', observed, observed, 'observation-complete', { post }, `settle:${sha256([scopeKey, cohort.lane, cohort.sourceId, observed, head.observe_from])}`, now);
+                    return Object.freeze({ action: 'settled', version: observed });
+                }
+                return Object.freeze({ action: 'observing', version: observed });
+            }
+            if (options.loosening !== undefined) {
+                // A sealed loosening proposal is judged before any new tightening so
+                // its parent cannot move underneath it.
+                const pending = this.#pendingProposal(scopeKey, cohort);
+                if (pending !== undefined)
+                    return this.#decideLoosening(scope, scopeKey, cohort, head, pending, policy, options.loosening, options.observationMs, now);
+            }
+            const current = this.#current(scopeKey, cohort);
+            // Evidence is only counted since the last change, so an adopted or
+            // rolled-back version is never re-judged on its predecessor's sample.
+            const from = Math.max(0, head?.changed_at ?? 0, now - options.evaluationWindowMs);
+            const stats = this.stats(scopeKey, cohort, from, now + 1, options.loosening === undefined ? 'all' : 'training');
+            const proposal = proposeAttentionTuning(current.parameters, stats, policy);
+            if (proposal.kind === 'no-op')
+                return Object.freeze({ action: 'no-op', reason: proposal.reason });
+            const version = this.#adopt(scope, scopeKey, cohort, head, current, proposal, stats, 'auto', options.observationMs, now);
+            return Object.freeze({ action: 'adopted', version, change: proposal.change });
+        });
+    }
+    /**
+     * Explicit parameter request. Any loosening field is rejected with
+     * `loosening-requires-holdout` and recorded; so is every other rejection.
+     * A single in-bounds tightening step is adopted with an observation window.
+     */
+    request(scopeInput, cohortInput, parametersInput, options) {
+        const { scope, scopeKey } = canonicalEvaluationScope(scopeInput);
+        const cohort = normalizeAttentionCohort(cohortInput);
+        const requested = normalizeAttentionTuningParameters(parametersInput);
+        return this.#transaction(() => {
+            const now = this.#now();
+            const head = this.#head(scopeKey, cohort);
+            const current = this.#current(scopeKey, cohort);
+            if (options.loosening !== undefined && isAttentionLoosening(current.parameters, requested)) {
+                return this.#proposeLoosening(scopeKey, cohort, head, current, requested, options.enabled, options.loosening, now);
+            }
+            const change = singleStep(current.parameters, requested);
+            const reason = isAttentionLoosening(current.parameters, requested) ? 'loosening-requires-holdout'
+                : !withinAttentionTuningBounds(requested) ? 'out-of-bounds'
+                    : stable(requested) === stable(current.parameters) ? 'no-change'
+                        : change === undefined ? 'not-single-step'
+                            : !options.enabled ? 'auto-adoption-disabled'
+                                : head?.state === 'observing' ? 'observation-in-progress'
+                                    : undefined;
+            if (reason !== undefined || change === undefined) {
+                const code = reason ?? 'not-single-step';
+                this.#event(scopeKey, cohort, 'request-rejected', current.version, current.version, code, { current: current.parameters, requested }, null, now);
+                return Object.freeze({ status: 'rejected', reason: code });
+            }
+            const stats = this.stats(scopeKey, cohort, Math.max(0, head?.changed_at ?? 0, now - options.evaluationWindowMs), now + 1, options.loosening === undefined ? 'all' : 'training');
+            const version = this.#adopt(scope, scopeKey, cohort, head, current, { change, parameters: requested }, stats, 'request', options.observationMs, now);
+            return deepFreeze({ status: 'adopted', version, change });
+        });
+    }
+    /**
+     * Slice 3 loosening request: validate, then seal a proposal that names the
+     * holdout membership by digest only. Nothing is adopted here; a later tick
+     * replays the holdout independently and checks the owner grant.
+     */
+    #proposeLoosening(scopeKey, cohort, head, current, requested, enabled, loosening, now) {
+        const change = attentionLooseningChange(current.parameters, requested);
+        const reason = !withinAttentionTuningBounds(requested) ? 'out-of-bounds'
+            : change === undefined ? 'not-single-parameter'
+                : !enabled ? 'auto-adoption-disabled'
+                    : head?.state === 'observing' ? 'observation-in-progress'
+                        : this.#pendingProposal(scopeKey, cohort) !== undefined ? 'proposal-pending'
+                            : this.#openQuestion(scopeKey, cohort) ? 'owner-question-pending'
+                                : undefined;
+        if (reason !== undefined || change === undefined) {
+            const code = reason ?? 'not-single-parameter';
+            this.#event(scopeKey, cohort, 'request-rejected', current.version, current.version, code, { current: current.parameters, requested }, null, now);
+            return Object.freeze({ status: 'rejected', reason: code });
+        }
+        const window = { fromNotifiedAt: Math.max(0, now - loosening.replayWindowMs), toNotifiedAt: now + 1 };
+        const holdout = this.#holdout(scopeKey, cohort, window.fromNotifiedAt, window.toNotifiedAt);
+        const body = {
+            protocol: ATTENTION_LOOSENING_PROTOCOL, scopeKey, cohort: { lane: cohort.lane, sourceId: cohort.sourceId },
+            ordinal: this.#database.prepare(`SELECT COUNT(*) AS count FROM evaluation_attention_loosening_proposals
+        WHERE scope_key=? AND lane=? AND source_id=?`).get(scopeKey, cohort.lane, cohort.sourceId).count + 1,
+            parentVersion: current.version, parentDigest: current.digest, parent: { ...current.parameters }, candidate: { ...requested },
+            change: { parameter: change.parameter, from: change.from, to: change.to }, steps: change.steps, window,
+            holdout: holdout.seal,
+            basis: { stats: this.stats(scopeKey, cohort, window.fromNotifiedAt, window.toNotifiedAt, 'training'), scopeWatermark: this.#scopeWatermark(scopeKey) },
+            createdAt: now,
+        };
+        const proposalId = sha256(body);
+        this.#database.prepare(`INSERT INTO evaluation_attention_loosening_proposals
+      (proposal_id, scope_key, lane, source_id, parent_version, proposal_json, holdout_digest, created_at) VALUES (?,?,?,?,?,?,?,?)`)
+            .run(proposalId, scopeKey, cohort.lane, cohort.sourceId, current.version, stable(body), holdout.seal.digest, now);
+        return deepFreeze({ status: 'proposed', proposalId, holdout: { ...holdout.seal } });
+    }
+    #pendingProposal(scopeKey, cohort) {
+        return this.#database.prepare(`SELECT p.* FROM evaluation_attention_loosening_proposals p
+      LEFT JOIN evaluation_attention_loosening_decisions d ON d.proposal_id=p.proposal_id
+      WHERE p.scope_key=? AND p.lane=? AND p.source_id=? AND d.proposal_id IS NULL
+      ORDER BY p.created_at, p.rowid LIMIT 1`).get(scopeKey, cohort.lane, cohort.sourceId);
+    }
+    /**
+     * A recorded owner reply closes the question even though the grant row it
+     * was asked under is unchanged; only a different grant or a reply closes
+     * it, and the latest question stays open until then.
+     */
+    #openQuestion(scopeKey, cohort) {
+        const question = this.#database.prepare(`SELECT question_id, question_json FROM evaluation_attention_owner_questions
+      WHERE scope_key=? AND lane=? AND source_id=? ORDER BY created_at DESC, rowid DESC LIMIT 1`)
+            .get(scopeKey, cohort.lane, cohort.sourceId);
+        if (question === undefined)
+            return false;
+        let parsed;
+        try {
+            parsed = JSON.parse(question.question_json);
+        }
+        catch {
+            return true;
+        }
+        return parsed.grantId === this.#latestGrantId(scopeKey, cohort) && !this.#replied(question.question_id);
+    }
+    /** True once any reply (authorize or decline) is recorded for this exact question. */
+    #replied(questionId) {
+        return this.#database.prepare('SELECT 1 AS present FROM evaluation_attention_owner_question_replies WHERE question_id=?')
+            .get(questionId) !== undefined;
+    }
+    /**
+     * WP22 slice 4: the latest owner question of a cohort, verified against its
+     * content id, and whether it is still open (same rule as `#openQuestion`,
+     * including the slice-5 rule that any recorded reply closes it). Older
+     * questions are always closed. A row whose body no longer hashes to its id
+     * is reported as `unverifiable` and must never be delivered.
+     */
+    latestOwnerQuestion(scopeInput, cohortInput) {
+        const { scopeKey } = canonicalEvaluationScope(scopeInput);
+        const cohort = normalizeAttentionCohort(cohortInput);
+        const row = this.#database.prepare(`SELECT question_id, question_json FROM evaluation_attention_owner_questions
+      WHERE scope_key=? AND lane=? AND source_id=? ORDER BY created_at DESC, rowid DESC LIMIT 1`)
+            .get(scopeKey, cohort.lane, cohort.sourceId);
+        if (row === undefined)
+            return undefined;
+        let question;
+        try {
+            question = JSON.parse(row.question_json);
+        }
+        catch {
+            return 'unverifiable';
+        }
+        if (sha256(question) !== row.question_id || question.protocol !== ATTENTION_OWNER_QUESTION_PROTOCOL
+            || question.scopeKey !== scopeKey || question.cohort?.lane !== cohort.lane || question.cohort?.sourceId !== cohort.sourceId)
+            return 'unverifiable';
+        return deepFreeze({ questionId: row.question_id, question,
+            open: question.grantId === this.#latestGrantId(scopeKey, cohort) && !this.#replied(row.question_id) });
+    }
+    #latestGrantId(scopeKey, cohort) {
+        return this.#database.prepare(`SELECT grant_id FROM evaluation_attention_loosening_grants
+      WHERE scope_key=? AND lane=? AND source_id=? ORDER BY created_at DESC, rowid DESC LIMIT 1`)
+            .get(scopeKey, cohort.lane, cohort.sourceId)?.grant_id ?? null;
+    }
+    /**
+     * Slice 5 evidence-backed apply path for one exact owner reply. Inside one
+     * transaction it verifies the cohort's latest question against its content
+     * id, records the reply, and then:
+     * - `decline` writes the proposal's one terminal `owner-declined` decision;
+     * - `authorize-once` creates a bounded one-time grant whose bounds are
+     *   exactly the questioned proposal's parent/candidate, charged once, and
+     *   leaves adoption to the next tuning tick's independent holdout replay;
+     * - a proposal that already has a decision (a question recorded before the
+     *   reply loop was enabled) returns `proposal-terminal` and changes nothing.
+     * Record-only callers keep using `AttentionOwnerQuestionLedger.recordReply`.
+     */
+    applyOwnerQuestionReply(scopeInput, cohortInput, questionIdInput, choiceInput, options) {
+        const { scope, scopeKey } = canonicalEvaluationScope(scopeInput);
+        const cohort = normalizeAttentionCohort(cohortInput);
+        if (typeof questionIdInput !== 'string' || !/^[a-f0-9]{64}$/u.test(questionIdInput))
+            invalid('question id is not recognised');
+        const choice = choiceInput === 'authorize-once' || choiceInput === 'decline'
+            ? choiceInput : undefined;
+        if (choice === undefined)
+            invalid('choice is not recognised');
+        if (!Number.isSafeInteger(options.noticeTtlMs) || options.noticeTtlMs < 1)
+            invalid('owner question notice TTL is invalid');
+        const questions = this.#questions;
+        if (questions === undefined)
+            invalid('owner question ledger is unavailable');
+        return this.#transaction(() => {
+            const now = this.#now();
+            const latest = this.latestOwnerQuestion(scope, cohort);
+            if (latest === undefined || latest === 'unverifiable' || latest.questionId !== questionIdInput) {
+                return Object.freeze({ status: 'rejected', reason: 'unknown-question' });
+            }
+            const question = latest.question;
+            const questionId = latest.questionId;
+            const expired = now >= question.createdAt + options.noticeTtlMs;
+            const reply = questions.recordReplyInTransaction(scope, cohort, questionId, choice, latest.open, expired);
+            if (reply.status === 'rejected')
+                return reply;
+            const decided = this.#database.prepare('SELECT 1 AS present FROM evaluation_attention_loosening_decisions WHERE proposal_id=?')
+                .get(question.proposalId) !== undefined;
+            if (decided) {
+                return Object.freeze({ status: 'applied', questionId: questionId, choice,
+                    proposalId: question.proposalId, grantId: null, adoption: 'proposal-terminal' });
+            }
+            if (choice === 'decline') {
+                const version = this.#current(scopeKey, cohort).version;
+                this.#decision(scopeKey, cohort, question.proposalId, 'rejected', 'owner-declined', null, null, question.replay, now);
+                this.#event(scopeKey, cohort, 'request-rejected', version, version, 'owner-declined', { proposalId: question.proposalId, questionId: questionId, choice }, `owner-question:${questionId}`, now);
+                return Object.freeze({ status: 'applied', questionId: questionId, choice,
+                    proposalId: question.proposalId, grantId: null, adoption: 'declined' });
+            }
+            // Exactly the questioned proposal: parent as the tightest start, its
+            // candidate as the loosest end, one adoption, the proposal's step size.
+            const grant = normalizeAttentionLooseningGrant({
+                grantId: `owner-question:${questionId}`,
+                lowerBound: { ...question.candidate }, upperBound: { ...question.parent },
+                maxStepsPerAdoption: question.steps, maxAdoptions: 1, expiresAt: now + options.noticeTtlMs,
+            });
+            const digest = this.#grantDigest(scopeKey, cohort, grant);
+            const existing = this.#database.prepare(`SELECT digest FROM evaluation_attention_loosening_grants
+        WHERE scope_key=? AND lane=? AND source_id=? AND grant_id=?`)
+                .get(scopeKey, cohort.lane, cohort.sourceId, grant.grantId);
+            if (existing === undefined) {
+                this.#database.prepare(`INSERT INTO evaluation_attention_loosening_grants
+          (scope_key, lane, source_id, grant_id, grant_json, digest, created_at) VALUES (?,?,?,?,?,?,?)`)
+                    .run(scopeKey, cohort.lane, cohort.sourceId, grant.grantId, stable(grant), digest, now);
+            }
+            else if (existing.digest !== digest) {
+                // Rolls the recorded reply back with this transaction; never leaves an
+                // authorization pointing at a grant id it did not create.
+                invalid('owner question grant conflicts with an existing grant');
+            }
+            return Object.freeze({ status: 'applied', questionId: questionId, choice,
+                proposalId: question.proposalId, grantId: grant.grantId, adoption: 'deferred' });
+        });
+    }
+    #verifiedProposal(row, scopeKey, cohort) {
+        try {
+            const body = JSON.parse(row.proposal_json);
+            if (sha256(body) !== row.proposal_id || body.protocol !== ATTENTION_LOOSENING_PROTOCOL || body.scopeKey !== scopeKey
+                || body.cohort.lane !== cohort.lane || body.cohort.sourceId !== cohort.sourceId || body.parentVersion !== row.parent_version
+                || body.holdout.digest !== row.holdout_digest || body.holdout.protocol !== ATTENTION_HOLDOUT_PROTOCOL || body.holdout.modulus !== attentionHoldoutModulus)
+                return undefined;
+            const parent = normalizeAttentionTuningParameters(body.parent);
+            const candidate = normalizeAttentionTuningParameters(body.candidate);
+            const change = attentionLooseningChange(parent, candidate);
+            if (!withinAttentionTuningBounds(parent) || !withinAttentionTuningBounds(candidate) || change === undefined || change.steps !== body.steps)
+                return undefined;
+            return deepFreeze(body);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    #grantDigest(scopeKey, cohort, grant) {
+        return sha256({ protocol: ATTENTION_LOOSENING_GRANT_PROTOCOL, scopeKey, cohort: { lane: cohort.lane, sourceId: cohort.sourceId }, grant });
+    }
+    /** Latest grant for the cohort; `unverifiable` when its stored body fails the digest. */
+    #activeGrant(scopeKey, cohort) {
+        const row = this.#database.prepare(`SELECT grant_id, grant_json, digest, created_at FROM evaluation_attention_loosening_grants
+      WHERE scope_key=? AND lane=? AND source_id=? ORDER BY created_at DESC, rowid DESC LIMIT 1`)
+            .get(scopeKey, cohort.lane, cohort.sourceId);
+        if (row === undefined)
+            return undefined;
+        try {
+            const grant = normalizeAttentionLooseningGrant(JSON.parse(row.grant_json));
+            if (grant.grantId !== row.grant_id || this.#grantDigest(scopeKey, cohort, grant) !== row.digest)
+                return 'unverifiable';
+            return Object.freeze({ grant, digest: row.digest, createdAt: row.created_at });
+        }
+        catch {
+            return 'unverifiable';
+        }
+    }
+    /** Adoptions charged to a grant. Decisions are immutable, so a rollback never refunds quota. */
+    #grantUsed(scopeKey, cohort, grantId) {
+        return this.#database.prepare(`SELECT COUNT(*) AS count FROM evaluation_attention_loosening_decisions
+      WHERE scope_key=? AND lane=? AND source_id=? AND grant_id=? AND decision='adopted'`)
+            .get(scopeKey, cohort.lane, cohort.sourceId, grantId).count;
+    }
+    /** Parameters in force at a notification time, from the append-only adopted/rolled-back events. */
+    #eraResolver(scopeKey, cohort) {
+        const changes = this.#database.prepare(`SELECT to_version, occurred_at FROM evaluation_attention_tuning_events
+      WHERE scope_key=? AND lane=? AND source_id=? AND kind IN ('adopted','rolled-back') ORDER BY sequence`)
+            .all(scopeKey, cohort.lane, cohort.sourceId);
+        const cache = new Map();
+        return notifiedAt => {
+            let version = 0;
+            for (const change of changes)
+                if (change.occurred_at <= notifiedAt)
+                    version = change.to_version;
+            if (version === 0)
+                return defaultAttentionTuningParameters;
+            if (!cache.has(version))
+                cache.set(version, this.#verified(scopeKey, cohort, version)?.parameters);
+            return cache.get(version);
+        };
+    }
+    #decision(scopeKey, cohort, proposalId, decision, reason, grantId, version, replay, now) {
+        this.#database.prepare(`INSERT INTO evaluation_attention_loosening_decisions
+      (proposal_id, scope_key, lane, source_id, decision, reason, grant_id, version, replay_json, decided_at) VALUES (?,?,?,?,?,?,?,?,?,?)`)
+            .run(proposalId, scopeKey, cohort.lane, cohort.sourceId, decision, reason, grantId, version, stable(replay), now);
+    }
+    /**
+     * Independent acceptance of one sealed proposal: verify it, require the
+     * exact parent still in force, recompute holdout membership against the
+     * frozen digest, replay parent vs candidate on holdout outcomes only, then
+     * adopt inside the owner grant or record an owner question. Every outcome
+     * is one immutable decision row plus a schema-15 tuning event.
+     */
+    #decideLoosening(scope, scopeKey, cohort, head, row, policy, loosening, observationMs, now) {
+        const proposalId = row.proposal_id;
+        const current = this.#current(scopeKey, cohort);
+        const reject = (reason, replay) => {
+            this.#decision(scopeKey, cohort, proposalId, 'rejected', reason, null, null, replay, now);
+            this.#event(scopeKey, cohort, 'request-rejected', current.version, current.version, reason, { proposalId, replay }, `loosening:${proposalId}`, now);
+            return Object.freeze({ action: 'loosening-rejected', reason, proposalId });
+        };
+        const proposal = this.#verifiedProposal(row, scopeKey, cohort);
+        if (proposal === undefined)
+            return reject('proposal-unverifiable', null);
+        if (current.version !== proposal.parentVersion || current.digest !== proposal.parentDigest
+            || stable(current.parameters) !== stable(proposal.parent))
+            return reject('stale-parent', null);
+        if (proposal.basis.stats.decided < policy.minSample)
+            return reject('insufficient-basis', null);
+        const { fromNotifiedAt, toNotifiedAt } = proposal.window;
+        const holdout = this.#holdout(scopeKey, cohort, fromNotifiedAt, toNotifiedAt);
+        if (holdout.seal.digest !== proposal.holdout.digest)
+            return reject('holdout-drifted', null);
+        const members = new Set(holdout.ids);
+        const era = this.#eraResolver(scopeKey, cohort);
+        const records = [];
+        for (const record of this.#records(scopeKey, cohort, fromNotifiedAt, toNotifiedAt)) {
+            if (!members.has(record.notification_id))
+                continue;
+            const parameters = era(record.occurred_at);
+            if (parameters === undefined)
+                return reject('era-unverifiable', null);
+            records.push({ era: parameters, outcome: record.outcome });
+        }
+        const replay = replayAttentionLoosening(records, proposal.parent, proposal.candidate, policy);
+        if (replay.verdict === 'fail')
+            return reject('holdout-failed', replay);
+        const active = this.#activeGrant(scopeKey, cohort);
+        const grant = active === 'unverifiable' ? undefined : active?.grant;
+        const exceeded = active === 'unverifiable' ? ['grant-unverifiable']
+            : attentionGrantExceeded(grant, grant === undefined ? 0 : this.#grantUsed(scopeKey, cohort, grant.grantId), proposal.parent, proposal.candidate, proposal.steps, now);
+        if (exceeded.length > 0 || grant === undefined) {
+            const replyLoop = loosening.ownerQuestionReplyLoop;
+            if (replyLoop !== undefined) {
+                const existing = this.#ownerQuestionForProposal(proposalId, scopeKey, cohort);
+                if (existing === 'unverifiable')
+                    return reject('proposal-unverifiable', replay);
+                if (existing !== undefined) {
+                    // Slice 5 deferred state: the proposal stays undecided while the
+                    // question is open, so the next tick can still adopt it. A terminal
+                    // decision is written only on decline, unusable authorization or
+                    // notice TTL expiry, never on first sight. Its event uses the
+                    // question-scoped key because the question-created event already
+                    // holds the proposal-scoped key.
+                    const terminate = (reason) => {
+                        this.#decision(scopeKey, cohort, proposalId, 'rejected', reason, null, null, replay, now);
+                        this.#event(scopeKey, cohort, 'request-rejected', current.version, current.version, reason, { proposalId, questionId: existing.questionId, replay }, `owner-question:${existing.questionId}`, now);
+                        return Object.freeze({ action: 'loosening-rejected', reason, proposalId });
+                    };
+                    const reply = this.#questions?.reply(existing.questionId);
+                    if (reply?.choice === 'decline')
+                        return terminate('owner-declined');
+                    if (reply?.choice === 'authorize-once')
+                        return terminate('owner-authorization-unusable');
+                    if (now >= existing.question.createdAt + replyLoop.noticeTtlMs)
+                        return terminate('owner-question-expired');
+                    return deepFreeze({ action: 'owner-question', questionId: existing.questionId, proposalId, exceeded: [...exceeded] });
+                }
+                const askedUnder = this.#latestGrantId(scopeKey, cohort);
+                const body = {
+                    protocol: ATTENTION_OWNER_QUESTION_PROTOCOL, kind: 'attention-loosening-authorization', scopeKey,
+                    cohort: { lane: cohort.lane, sourceId: cohort.sourceId }, proposalId,
+                    parentVersion: proposal.parentVersion, parentDigest: proposal.parentDigest, parent: proposal.parent, candidate: proposal.candidate,
+                    change: proposal.change, steps: proposal.steps, replay, exceeded: [...exceeded], grantId: askedUnder,
+                    choices: ['authorize-once', 'decline'], delivery: 'not-sent', createdAt: now,
+                };
+                const questionId = sha256(body);
+                this.#database.prepare(`INSERT INTO evaluation_attention_owner_questions
+          (question_id, proposal_id, scope_key, lane, source_id, question_json, created_at) VALUES (?,?,?,?,?,?,?)`)
+                    .run(questionId, proposalId, scopeKey, cohort.lane, cohort.sourceId, stable(body), now);
+                // No decision row: the deferred proposal remains pending until the
+                // reply or TTL closes it, so a one-time grant can still adopt it.
+                this.#event(scopeKey, cohort, 'request-rejected', current.version, current.version, 'loosening-requires-owner', { proposalId, questionId, exceeded }, `loosening:${proposalId}`, now);
+                return deepFreeze({ action: 'owner-question', questionId, proposalId, exceeded: [...exceeded] });
+            }
+            const askedUnder = this.#latestGrantId(scopeKey, cohort);
+            const body = {
+                protocol: ATTENTION_OWNER_QUESTION_PROTOCOL, kind: 'attention-loosening-authorization', scopeKey,
+                cohort: { lane: cohort.lane, sourceId: cohort.sourceId }, proposalId,
+                parentVersion: proposal.parentVersion, parentDigest: proposal.parentDigest, parent: proposal.parent, candidate: proposal.candidate,
+                change: proposal.change, steps: proposal.steps, replay, exceeded: [...exceeded], grantId: askedUnder,
+                choices: ['authorize-once', 'decline'], delivery: 'not-sent', createdAt: now,
+            };
+            const questionId = sha256(body);
+            this.#database.prepare(`INSERT INTO evaluation_attention_owner_questions
+        (question_id, proposal_id, scope_key, lane, source_id, question_json, created_at) VALUES (?,?,?,?,?,?,?)`)
+                .run(questionId, proposalId, scopeKey, cohort.lane, cohort.sourceId, stable(body), now);
+            this.#decision(scopeKey, cohort, proposalId, 'owner-question', 'loosening-requires-owner', askedUnder, null, replay, now);
+            this.#event(scopeKey, cohort, 'request-rejected', current.version, current.version, 'loosening-requires-owner', { proposalId, questionId, exceeded }, `loosening:${proposalId}`, now);
+            return deepFreeze({ action: 'owner-question', questionId, proposalId, exceeded: [...exceeded] });
+        }
+        const version = this.#adopt(scope, scopeKey, cohort, head, current, { change: proposal.change, parameters: proposal.candidate }, proposal.basis.stats, 'request', observationMs, now, { proposalId, grantId: grant.grantId });
+        this.#decision(scopeKey, cohort, proposalId, 'adopted', 'holdout-accepted', grant.grantId, version, replay, now);
+        return deepFreeze({ action: 'loosening-adopted', version, change: { ...proposal.change }, proposalId, grantId: grant.grantId });
+    }
+    /** One immutable question row for a proposal, verified against its content id. */
+    #ownerQuestionForProposal(proposalId, scopeKey, cohort) {
+        const row = this.#database.prepare(`SELECT question_id, question_json FROM evaluation_attention_owner_questions
+      WHERE proposal_id=? AND scope_key=? AND lane=? AND source_id=?`)
+            .get(proposalId, scopeKey, cohort.lane, cohort.sourceId);
+        if (row === undefined)
+            return undefined;
+        try {
+            const question = JSON.parse(row.question_json);
+            if (sha256(question) !== row.question_id || question.protocol !== ATTENTION_OWNER_QUESTION_PROTOCOL
+                || question.proposalId !== proposalId || question.scopeKey !== scopeKey
+                || question.cohort?.lane !== cohort.lane || question.cohort?.sourceId !== cohort.sourceId)
+                return 'unverifiable';
+            return deepFreeze({ questionId: row.question_id, question });
+        }
+        catch {
+            return 'unverifiable';
+        }
+    }
+    /**
+     * Record an owner one-time pre-authorization. Grants are immutable; the
+     * latest one is active and its quota is never refunded. Re-sending the same
+     * grant is idempotent; reusing an id with different content is rejected.
+     */
+    grant(scopeInput, cohortInput, grantInput) {
+        const { scopeKey } = canonicalEvaluationScope(scopeInput);
+        const cohort = normalizeAttentionCohort(cohortInput);
+        const grant = normalizeAttentionLooseningGrant(grantInput);
+        return this.#transaction(() => {
+            const now = this.#now();
+            const digest = this.#grantDigest(scopeKey, cohort, grant);
+            const existing = this.#database.prepare(`SELECT digest FROM evaluation_attention_loosening_grants
+        WHERE scope_key=? AND lane=? AND source_id=? AND grant_id=?`).get(scopeKey, cohort.lane, cohort.sourceId, grant.grantId);
+            if (existing !== undefined) {
+                return existing.digest === digest ? Object.freeze({ status: 'granted', grantId: grant.grantId, digest })
+                    : Object.freeze({ status: 'rejected', reason: 'grant-conflict' });
+            }
+            if (now >= grant.expiresAt)
+                return Object.freeze({ status: 'rejected', reason: 'grant-expired' });
+            this.#database.prepare(`INSERT INTO evaluation_attention_loosening_grants
+        (scope_key, lane, source_id, grant_id, grant_json, digest, created_at) VALUES (?,?,?,?,?,?,?)`)
+                .run(scopeKey, cohort.lane, cohort.sourceId, grant.grantId, stable(grant), digest, now);
+            return Object.freeze({ status: 'granted', grantId: grant.grantId, digest });
+        });
+    }
+    looseningStatus(scopeInput, cohortInput, limit = 50) {
+        const { scopeKey } = canonicalEvaluationScope(scopeInput);
+        const cohort = normalizeAttentionCohort(cohortInput);
+        const active = this.#activeGrant(scopeKey, cohort);
+        const grant = active === undefined || active === 'unverifiable' ? null : (() => {
+            const used = this.#grantUsed(scopeKey, cohort, active.grant.grantId);
+            return { ...active, used, remaining: Math.max(0, active.grant.maxAdoptions - used) };
+        })();
+        const rows = this.#database.prepare(`SELECT * FROM evaluation_attention_loosening_proposals
+      WHERE scope_key=? AND lane=? AND source_id=? ORDER BY created_at DESC, rowid DESC LIMIT ?`)
+            .all(scopeKey, cohort.lane, cohort.sourceId, limit).reverse();
+        const proposals = rows.flatMap(row => {
+            const proposal = this.#verifiedProposal(row, scopeKey, cohort);
+            if (proposal === undefined)
+                return [];
+            const decided = this.#database.prepare(`SELECT decision, reason, grant_id, version, replay_json, decided_at
+        FROM evaluation_attention_loosening_decisions WHERE proposal_id=?`).get(row.proposal_id);
+            const decision = decided === undefined ? null : {
+                decision: decided.decision, reason: decided.reason, grantId: decided.grant_id, version: decided.version,
+                replay: JSON.parse(decided.replay_json), decidedAt: decided.decided_at,
+            };
+            return [{ proposalId: row.proposal_id, proposal, decision }];
+        });
+        const questions = this.#database.prepare(`SELECT question_id, question_json FROM evaluation_attention_owner_questions
+      WHERE scope_key=? AND lane=? AND source_id=? ORDER BY created_at DESC, rowid DESC LIMIT ?`)
+            .all(scopeKey, cohort.lane, cohort.sourceId, limit).reverse()
+            .map(row => ({ questionId: row.question_id, question: JSON.parse(row.question_json) }));
+        return deepFreeze({ grant, proposals, questions });
+    }
+    counts() {
+        const versions = this.#database.prepare('SELECT COUNT(*) AS count FROM evaluation_attention_tuning_versions').get();
+        const events = this.#database.prepare('SELECT COUNT(*) AS count FROM evaluation_attention_tuning_events').get();
+        return { versions: versions.count, events: events.count };
+    }
+}
+//# sourceMappingURL=attention-tuning.js.map