attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/attention/cognition.js

@@ -0,0 +1,245 @@
+const clamp01 = (value) => (value < 0 ? 0 : value > 1 ? 1 : value);
+/**
+ * Rounds to three decimals, so receipts and snapshots stay byte-stable.
+ */
+const round3 = (value) => Math.round(value * 1000) / 1000;
+/**
+ * Named law parameters. Every entry states whether the value is measured on
+ * humans or a convention of this implementation, because a protocol may cite a
+ * direction it cannot cite a magnitude for.
+ */
+export const CognitiveLaws = {
+    /**
+     * Prospect theory's loss-asymmetry median estimate (Kahneman & Tversky 1992).
+     */
+    lossAsymmetry: { value: 2.25, status: "measured", source: "λ ≈ 2.25, median across studies" },
+    /**
+     * Vigilance half-life in *cycles*, not minutes: a convention pending measurement.
+     */
+    vigilanceTau: { value: 12, status: "convention", source: "calibrate per model from receipts" },
+    /**
+     * Inhibition-of-return kernel: distinct from novelty decay.
+     */
+    iorTau: { value: 3, status: "convention", source: "seconds-scale effect mapped onto cycles" },
+    /**
+     * Base chunk capacity before load is applied (Cowan 2001: ~4 unrehearsed).
+     */
+    baseCapacity: { value: 4, status: "measured", source: "Cowan 2001, BBS 24(1):87–114" },
+    /**
+     * Load may consume at most half of capacity.
+     */
+    loadPenalty: { value: 0.5, status: "convention", source: "monotone, bounded" },
+    /**
+     * Below this load, spare capacity must not be filled with novelty (Lavie).
+     */
+    noveltyLoadFloor: { value: 0.3, status: "convention", source: "Lavie 2005, TiCS 9(2):75–82" },
+    /**
+     * Arousal narrows breadth by raising the goal-fit exponent (Easterbrook 1959).
+     */
+    arousalNarrowing: { value: 0.5, status: "convention", source: "Easterbrook 1959, Psych Review 66:183–201" },
+    /**
+     * Screening overhead charged per candidate scored.
+     */
+    metaCharge: { value: 0.1, status: "convention", source: "Russell & Wefald 1991" },
+    /**
+     * How strongly a class's realised value moves its future priority.
+     */
+    valueLearning: { value: 2, status: "convention", source: "Anderson, Laurent & Yantis 2011, PNAS 108(25); calibrate per host" },
+};
+/**
+ * Estimate the state from the ledger.
+ *
+ * Two timescales of the same signal are kept apart on purpose: `arousal` is
+ * *recent* error pressure (fast, phasic) while `mastery` is the long-run success
+ * rate (slow, trait-like). Collapsing them into one number loses the fact that a
+ * competent agent can be briefly alarmed, and an incompetent one can be calm.
+ */
+export const estimateCognitiveState = (input) => {
+    const frames = input.frames;
+    const last = frames.length > 0 ? frames[frames.length - 1] : undefined;
+    const baseCapacity = input.baseCapacity ?? CognitiveLaws.baseCapacity.value;
+    const tau = input.tauVigilance ?? CognitiveLaws.vigilanceTau.value;
+    const window = input.window ?? 12;
+    let cyclesSinceRest = frames.length;
+    for (let index = frames.length - 1; index >= 0; index -= 1) {
+        if (frames[index].mode === "rest") {
+            cyclesSinceRest = frames.length - 1 - index;
+            break;
+        }
+    }
+    const active = last ? last.slots.filter((slot) => slot.state === "active") : [];
+    const chunks = active.reduce((sum, slot) => sum + (typeof (slot.chunk_weight) === "number" ? slot.chunk_weight : 1), 0);
+    const deferred = (last?.ignored ?? []).filter((item) => item.reason === "deferred" || item.reason === "budget");
+    const rootCapacity = Math.max(1, baseCapacity);
+    const load = clamp01(0.6 * Math.min(1, chunks / rootCapacity) + 0.4 * Math.min(1, deferred.length / 8));
+    const recent = input.receipts.slice(Math.max(0, input.receipts.length - window));
+    const scored = recent.filter((receipt) => receipt.outcome !== (void 0));
+    const failures = scored.filter((receipt) => receipt.outcome === "blocked" || receipt.outcome === "failure").length;
+    const partials = scored.filter((receipt) => receipt.outcome === "partial").length;
+    const failureRate = scored.length > 0 ? failures / scored.length : 0;
+    const partialRate = scored.length > 0 ? partials / scored.length : 0;
+    const arousal = clamp01(0.75 * failureRate + 0.25 * partialRate);
+    const allScored = input.receipts.filter((receipt) => receipt.outcome !== (void 0));
+    const wins = allScored.filter((receipt) => receipt.outcome === "success").length;
+    const mastery = allScored.length > 0 ? clamp01(wins / allScored.length) : 0.5;
+    const vigilance = clamp01(Math.exp(-cyclesSinceRest / Math.max(1, tau)));
+    const capacityEff = Math.min(9, Math.max(1, Math.round(rootCapacity * (1 - CognitiveLaws.loadPenalty.value * load))));
+    const dominantRole = dominantRoleOf(active);
+    return {
+        load: round3(load),
+        vigilance: round3(vigilance),
+        arousal: round3(arousal),
+        mastery: round3(mastery),
+        accountability: clamp01(input.accountability ?? 0),
+        cyclesSinceRest,
+        capacityEff,
+        pLapse: round3(1 - vigilance),
+        dominantRole,
+        source: allScored.length >= 30 ? "measured" : "default",
+        samples: allScored.length,
+    };
+};
+/**
+ * The role with the most chunk weight in a focus set; ties resolve to the first seen.
+ */
+const dominantRoleOf = (slots) => {
+    const weight = new Map();
+    for (let index = 0; index < slots.length; index += 1) {
+        const slot = slots[index];
+        const chunks = typeof (slot.chunk_weight) === "number" ? slot.chunk_weight : 1;
+        weight.set(slot.role, (weight.get(slot.role) ?? 0) + chunks);
+    }
+    let best = undefined;
+    let bestWeight = -1;
+    const entries = [...weight];
+    for (let index = 0; index < entries.length; index += 1) {
+        const [role, total] = entries[index];
+        if (total > bestWeight) {
+            best = role;
+            bestWeight = total;
+        }
+    }
+    return best;
+};
+/**
+ * The history multiplier: value learning minus inhibition of return.
+ *
+ * These are two mechanisms with opposite signs, not one "novelty" knob. A
+ * candidate that paid off is worth re-selecting; a candidate just rejected is
+ * worth *not* re-selecting, and both facts must survive into the next cycle.
+ */
+export const historyFactor = (history) => {
+    if (!history) {
+        return 1;
+    }
+    const realized = typeof (history.realized) === "number" ? history.realized : 0.5;
+    const learned = 1 + CognitiveLaws.valueLearning.value * (realized - 0.5);
+    const age = typeof (history.lastIgnoredAge) === "number" ? history.lastIgnoredAge : Number.POSITIVE_INFINITY;
+    const ior = age === Number.POSITIVE_INFINITY ? 0 : 0.5 * Math.exp(-age / CognitiveLaws.iorTau.value);
+    return Math.max(0.1, learned - ior);
+};
+export const salienceFromState = (candidate, state) => {
+    const gamma = 1 + CognitiveLaws.arousalNarrowing.value * state.arousal;
+    const openness = state.load >= CognitiveLaws.noveltyLoadFloor.value ? 1 : 0;
+    const value = candidate.voi * Math.pow(clamp01(candidate.goalFit), gamma) * (1 + 0.5 * clamp01(candidate.novelty) * openness) * historyFactor(candidate.history);
+    const switchTokens = candidate.switchCostTokens ?? 0;
+    const loadOnSwitch = 1 + state.load;
+    const cost = 1 +
+        2 * clamp01(candidate.costTokens / 2000) +
+        3 * clamp01(candidate.risk) +
+        0.5 * clamp01(switchTokens / 2000) * loadOnSwitch +
+        CognitiveLaws.metaCharge.value;
+    const capped = Math.min(clamp01(value / cost), clamp01(candidate.trustCap));
+    const floor = typeof (candidate.hardFloor) === "number" ? clamp01(candidate.hardFloor) : 0;
+    return round3(Math.max(capped, floor));
+};
+export const selectFromState = (candidates, state, options) => {
+    const threshold = options.threshold ?? 0.12;
+    const capacity = Math.max(1, options.capacity ?? state.capacityEff);
+    const switchCost = options.switchCostTokens ?? 0;
+    const scored = candidates
+        .map((candidate) => ({ candidate, score: salienceFromState(candidate, state) }))
+        .sort((left, right) => right.score - left.score);
+    const ignored = [];
+    const slots = [];
+    let usedChunks = 0;
+    let remaining = options.budgetTokens;
+    let floorConflict = false;
+    for (let index = 0; index < scored.length; index += 1) {
+        const entry = scored[index];
+        const chunks = Math.max(1, typeof (entry.candidate.chunkWeight) === "number" ? Math.floor(entry.candidate.chunkWeight) : 1);
+        const reserved = (entry.candidate.hardFloor ?? 0) > 0;
+        if (usedChunks + chunks > capacity) {
+            if (reserved) {
+                floorConflict = true;
+            }
+            ignored.push({ target: entry.candidate.target, reason: "capacity", revisit_if: "焦点释放后" });
+            continue;
+        }
+        const cost = entry.candidate.costTokens;
+        const withSwitch = cost + (entry.candidate.role === state.dominantRole ? 0 : switchCost);
+        if (withSwitch > remaining) {
+            ignored.push({ target: entry.candidate.target, reason: "budget", revisit_if: "预算恢复后" });
+            continue;
+        }
+        if (!reserved && entry.score < threshold) {
+            ignored.push({
+                target: entry.candidate.target,
+                reason: reasonForIgnore(entry.candidate, state),
+                revisit_if: entry.candidate.target.kind === "unknown" ? "VOI 上升或目标改变" : "重新评估后",
+            });
+            continue;
+        }
+        remaining -= withSwitch;
+        usedChunks += chunks;
+        slots.push({
+            target: entry.candidate.target,
+            role: entry.candidate.role,
+            tier: entry.candidate.tier,
+            salience: entry.score,
+            voi: entry.candidate.voi,
+            cost: { tokens: cost },
+            budget: { tokens: withSwitch },
+            why: entry.candidate.why,
+            state: "active",
+        });
+    }
+    let impasse = undefined;
+    if (floorConflict) {
+        impasse = "INFEASIBLE";
+    }
+    else if (slots.length === 0) {
+        impasse = "STUCK";
+    }
+    else if (slots.length > 1 && Math.abs(slots[0].salience - slots[1].salience) < 0.02) {
+        impasse = "TIE";
+    }
+    return { slots, ignored, impasse, capacityUsed: usedChunks };
+};
+const reasonForIgnore = (candidate, state) => {
+    const age = candidate.history?.lastIgnoredAge;
+    if (typeof (age) === "number" && age <= CognitiveLaws.iorTau.value) {
+        return "inhibited";
+    }
+    if (state.pLapse > 0.5 && candidate.uncertainty > 0.5) {
+        return "low_sensitivity";
+    }
+    return "low_voi";
+};
+export const respectsCognitiveMonotonicity = (base, state) => {
+    const at = (over = {}, stateOver = {}) => salienceFromState({ ...base, ...over }, { ...state, ...stateOver });
+    const reference = at();
+    const checks = [
+        at({ voi: Math.min(1, base.voi + 0.1) }) >= reference,
+        at({ costTokens: base.costTokens + 200 }) <= reference,
+        at({ risk: Math.min(1, base.risk + 0.1) }) <= reference,
+        at({ trustCap: Math.min(base.trustCap, 0.2) }) <= reference,
+        at({ history: { ...base.history, realized: 1 } }) >= reference,
+        at({ history: { ...base.history, lastIgnoredAge: 0, lastSelectedAge: 0 } }) <= reference,
+        at({ hardFloor: 1 }) >= reference,
+        at({ switchCostTokens: 2000 }) <= reference,
+        at({}, { arousal: 1 }) <= reference,
+        at({}, { load: 0 }) <= reference,
+    ];
+    return checks.every((ok) => ok);
+};

package/lib/attention/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Public attention entry: one state object, one shift action.
+ *
+ * The lower-level candidate scoring, interrupt broker and resource planner are
+ * implementation details during migration. They are not part of this surface.
+ */
+export { Attention, toShiftAction } from "./attention.js";
+export type { AttentionForce, AttentionForceKind, AttentionItem, AttentionOptions, AttentionShift, AttentionShiftResult, AttentionSnapshot, AttentionSubject } from "./attention.js";

package/lib/attention/index.js

@@ -0,0 +1,7 @@
+/**
+ * Public attention entry: one state object, one shift action.
+ *
+ * The lower-level candidate scoring, interrupt broker and resource planner are
+ * implementation details during migration. They are not part of this surface.
+ */
+export { Attention, toShiftAction } from "./attention.js";

package/lib/attention/interrupts.d.ts

@@ -0,0 +1,97 @@
+import type { Budget, Id, Ref, Timestamp } from "../types/common.js";
+import type { Receipt } from "../receipt/receipt.js";
+import type { AttentionRequest, InterruptClass } from "./socialTypes.js";
+import { AttentionBroker, type AttentionDecision, type AttentionPolicy } from "./social.js";
+/**
+ * The Attention Ledger's missing object: an `Interrupt`.
+ *
+ * `AttentionBroker` makes a grant/defer/deny decision, but the decision is not
+ * itself an auditable ledger row and deferred requests never expire unless a
+ * caller manually resolves them. This wrapper turns each decision into an
+ * `Interrupt` record, emits the matching receipt, and sweeps deferred requests
+ * whose response window has elapsed.
+ *
+ * It deliberately does not replace `AttentionBroker`: policy, quiet hours,
+ * cooldowns and debt stay in one place.
+ */
+export type InterruptStatus = "granted" | "deferred" | "denied" | "answered" | "expired" | "withdrawn";
+export interface InterruptRecord {
+    amp: "0.1";
+    kind: "interrupt";
+    id: Id;
+    request: Id;
+    class: InterruptClass;
+    target: Ref;
+    urgency: number;
+    granted: boolean;
+    status: InterruptStatus;
+    cost: Budget;
+    at: Timestamp;
+    expires?: Timestamp;
+    debt_weight: number;
+    reason: string;
+    receipt: Id;
+}
+export interface AttentionLedgerOptions {
+    now: () => Timestamp;
+    policy?: Partial<AttentionPolicy>;
+    /**
+     * Response window for a deferred request that carries no `expires`.
+     */
+    defaultExpiryMs?: number;
+    onReceipt?: (receipt: Receipt) => void;
+}
+export declare const MaxExternalShare: number;
+export interface AdmissionVerdict {
+    ok: boolean;
+    reason?: string;
+}
+type ExternalAdmissionInput = {
+    role: string;
+    share: number;
+    goalSlot?: boolean;
+    maxShare?: number;
+};
+/**
+ * A-4: external content may be present, but it cannot buy its own salience and
+ * cannot occupy the goal slot. The numeric share is the proportion of the
+ * assembled context attributable to external content.
+ */
+export declare const admitExternal: (input: ExternalAdmissionInput) => AdmissionVerdict;
+/**
+ * Interrupt-producing facade over `AttentionBroker`.
+ *
+ * Every submitted request produces exactly one `InterruptRecord` and one
+ * `Receipt` (op `ask`). Deferred records own debt until resolved or expired;
+ * `sweep()` closes the bookkeeping for elapsed windows.
+ */
+export declare class AttentionLedger {
+    readonly broker: AttentionBroker;
+    private readonly now;
+    private readonly defaultExpiryMs;
+    private readonly onReceipt?;
+    private readonly records;
+    private readonly byRequest;
+    private seq;
+    constructor(options: AttentionLedgerOptions);
+    submit(request: AttentionRequest): {
+        interrupt: InterruptRecord;
+        decision: AttentionDecision;
+        receipt: Receipt;
+    };
+    /**
+     * Resolve a deferred request. Returns the updated record or undefined.
+     */
+    resolve(requestId: Id, outcome?: "answered" | "expired" | "withdrawn"): InterruptRecord | undefined;
+    /**
+     * Expire deferred requests whose response window has elapsed.
+     * Idempotent: already-resolved/expired records are skipped.
+     */
+    sweep(at?: Timestamp): InterruptRecord[];
+    all(): readonly InterruptRecord[];
+    get(requestId: Id): InterruptRecord | undefined;
+    open(): InterruptRecord[];
+    grantedCount(): number;
+    debtScore(at?: Timestamp): number;
+}
+export {};

package/lib/attention/interrupts.js

@@ -0,0 +1,151 @@
+import { AttentionBroker } from "./social.js";
+export const MaxExternalShare = 0.15;
+/**
+ * A-4: external content may be present, but it cannot buy its own salience and
+ * cannot occupy the goal slot. The numeric share is the proportion of the
+ * assembled context attributable to external content.
+ */
+export const admitExternal = (input) => {
+    if (input.goalSlot) {
+        return { ok: false, reason: "external content cannot occupy the goal slot" };
+    }
+    if (!Number.isFinite(input.share) || input.share < 0 || input.share > 1) {
+        return { ok: false, reason: `invalid external share: ${`${input.share}`}` };
+    }
+    const limit = input.maxShare ?? MaxExternalShare;
+    if (!Number.isFinite(limit) || limit < 0 || limit > 1) {
+        throw new RangeError("maxShare must be in [0, 1]");
+    }
+    if (input.share > limit) {
+        return { ok: false, reason: `external share ${input.share} exceeds ${limit}` };
+    }
+    return { ok: true };
+};
+const addTimestamps = (at, ms) => new Date(Date.parse(at) + ms).toISOString();
+/**
+ * Interrupt-producing facade over `AttentionBroker`.
+ *
+ * Every submitted request produces exactly one `InterruptRecord` and one
+ * `Receipt` (op `ask`). Deferred records own debt until resolved or expired;
+ * `sweep()` closes the bookkeeping for elapsed windows.
+ */
+export class AttentionLedger {
+    broker;
+    now;
+    defaultExpiryMs;
+    onReceipt;
+    records = [];
+    byRequest = new Map();
+    seq = 0;
+    constructor(options) {
+        this.now = options.now;
+        this.defaultExpiryMs = options.defaultExpiryMs ?? 60_000;
+        this.onReceipt = options.onReceipt;
+        this.broker = new AttentionBroker({ now: options.now, policy: options.policy });
+    }
+    submit(request) {
+        if (this.byRequest.has(request.id)) {
+            throw new Error(`duplicate interrupt request: ${request.id}`);
+        }
+        const decision = this.broker.submit(request);
+        const status = statusOf(decision);
+        this.seq += 1;
+        const id = `int.${this.seq}`;
+        const expires = status === "deferred" ? (request.expires ?? addTimestamps(decision.at, this.defaultExpiryMs)) : request.expires;
+        const interrupt = {
+            amp: "0.1",
+            kind: "interrupt",
+            id,
+            request: request.id,
+            class: request.class,
+            target: request.target,
+            urgency: request.urgency,
+            granted: status === "granted",
+            status,
+            cost: request.cost,
+            at: decision.at,
+            expires,
+            debt_weight: request.urgency,
+            reason: decision.reason,
+            receipt: `rc.ask.${this.seq}`,
+        };
+        const receipt = {
+            amp: "0.1",
+            kind: "receipt",
+            id: interrupt.receipt,
+            op: "ask",
+            target: request.target,
+            at: decision.at,
+            usage: { interrupts: status === "granted" ? 1 : 0, ...request.cost },
+            outcome: status === "denied" ? "blocked" : status === "deferred" ? "partial" : "success",
+            note: `${request.class}:${status}:${decision.reason}`,
+        };
+        this.records.push(interrupt);
+        this.byRequest.set(request.id, interrupt);
+        this.onReceipt?.(receipt);
+        return { interrupt, decision, receipt };
+    }
+    /**
+     * Resolve a deferred request. Returns the updated record or undefined.
+     */
+    resolve(requestId, outcome = "answered") {
+        const record = this.byRequest.get(requestId);
+        if (!record || record.status !== "deferred") {
+            return undefined;
+        }
+        try {
+            this.broker.resolve(requestId, outcome);
+        }
+        catch {
+            /**
+             * The broker may already have closed the debt through a prior sweep.
+             */
+        }
+        record.status = outcome;
+        return record;
+    }
+    /**
+     * Expire deferred requests whose response window has elapsed.
+     * Idempotent: already-resolved/expired records are skipped.
+     */
+    sweep(at = this.now()) {
+        const now = Date.parse(at);
+        const expired = [];
+        for (let index = 0; index < this.records.length; index += 1) {
+            const record = this.records[index];
+            if (record.status !== "deferred" || record.expires === (void 0)) {
+                continue;
+            }
+            if (Date.parse(record.expires) > now) {
+                continue;
+            }
+            this.resolve(record.request, "expired");
+            expired.push(record);
+        }
+        return expired;
+    }
+    all() {
+        return this.records;
+    }
+    get(requestId) {
+        return this.byRequest.get(requestId);
+    }
+    open() {
+        return this.records.filter((record) => record.status === "deferred");
+    }
+    grantedCount() {
+        return this.records.filter((record) => record.status === "granted").length;
+    }
+    debtScore(at = this.now()) {
+        return this.broker.debtScore(at);
+    }
+}
+const statusOf = (decision) => {
+    if (decision.decision === "grant") {
+        return "granted";
+    }
+    if (decision.decision === "defer") {
+        return "deferred";
+    }
+    return "denied";
+};

package/lib/attention/resource.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Attention as a bounded, multi-dimensional resource.
+ *
+ * This is the resource layer above `cognition.ts`:
+ * - `ProcessAttention` is the agent-level capacity, reserve and recovery debt.
+ * - `ThreadAttention` is the per-task allocation inside that capacity.
+ *
+ * CPU analogies are structural only: a CPU can run at 100% indefinitely, a
+ * person cannot. The policy therefore caps foreground utilization below 1,
+ * keeps a safety/reserve floor, and schedules rest when recovery debt is high.
+ */
+import type { Pid } from "../types/common.js";
+import type { CognitiveState } from "./cognition.js";
+export interface AttentionResourcePolicy {
+    /**
+     * Working-memory chunks assumed when no measured capacity exists.
+     */
+    baseSlots: number;
+    /**
+     * Fraction kept away from foreground work (background, safety, recovery).
+     */
+    reserveRatio: number;
+    /**
+     * Hard safety floor, in slots, reserved even under pressure.
+     */
+    safetyFloorRatio: number;
+    /**
+     * Foreground utilization ceiling; must stay below 1.0.
+     */
+    maxForegroundUtil: number;
+    /**
+     * Minimum allocation for an admitted task, in slots.
+     */
+    minSliceSlots: number;
+    /**
+     * Rest after this many cycles without a rest frame.
+     */
+    restAfterCycles: number;
+    /**
+     * Rest when vigilance falls to this level.
+     */
+    vigilanceFloor: number;
+    /**
+     * Rest when load reaches this level.
+     */
+    loadCeiling: number;
+    /**
+     * Rest when recovery debt reaches this level.
+     */
+    recoveryDebtThreshold: number;
+}
+export declare const DefaultAttentionPolicy: AttentionResourcePolicy;
+export interface ProcessAttention {
+    pid: Pid;
+    /**
+     * Effective working-memory slots after load penalty.
+     */
+    effectiveSlots: number;
+    /**
+     * Foreground ceiling (`floor(effective * maxForegroundUtil)`).
+     */
+    foregroundCap: number;
+    /**
+     * Slots kept out of foreground allocation.
+     */
+    reserveSlots: number;
+    /**
+     * Hard safety floor inside the reserve.
+     */
+    safetySlots: number;
+    state: CognitiveState;
+    /**
+     * [0, 1] accumulated need for rest.
+     */
+    recoveryDebt: number;
+    /**
+     * True when the policy says no foreground work should run.
+     */
+    offline: boolean;
+}
+export type ThreadDeferReason = "budget" | "offline" | "low-priority" | "floor";
+export interface ThreadAttentionCandidate {
+    tid: number;
+    pid: Pid;
+    priority: number;
+    /**
+     * Desired slots; the planner clamps to capacity.
+     */
+    preferredSlots: number;
+    /**
+     * Minimum slots if admitted; defaults to policy.minSliceSlots.
+     */
+    minSlots?: number;
+    /**
+     * Background tasks use the reserve and never the foreground slot.
+     */
+    foreground?: boolean;
+    /**
+     * Extra pressure from role/context switching.
+     */
+    switchCost?: number;
+    role?: string;
+}
+export interface ThreadAttention {
+    tid: number;
+    pid: Pid;
+    slots: number;
+    foreground: boolean;
+    priority: number;
+    switchCost: number;
+    role?: string;
+}
+export interface DeferredAttention {
+    tid: number;
+    reason: ThreadDeferReason;
+}
+export interface AttentionPlan {
+    process: ProcessAttention;
+    foreground?: ThreadAttention;
+    background: ThreadAttention[];
+    deferred: DeferredAttention[];
+    /**
+     * Allocated slots / effective slots.
+     */
+    utilization: number;
+    /**
+     * Deferred pressure plus switch cost, [0, 1+].
+     */
+    pressure: number;
+    /**
+     * True when the policy wants a rest frame.
+     */
+    rest: boolean;
+}
+export declare const recoveryDebtOf: (state: CognitiveState) => number;
+export declare const shouldRest: (state: CognitiveState, policy?: AttentionResourcePolicy) => boolean;
+export declare const processAttention: (pid: Pid, state: CognitiveState, policy?: AttentionResourcePolicy) => ProcessAttention;
+/**
+ * Allocate one foreground task and, from the reserve, background tasks.
+ *
+ * Floors are intentionally asymmetric: safety is always reserved, every
+ * admitted task gets `minSlots`, but a deferred task gets no floor. Guaranteeing
+ * a floor to every candidate would make admission meaningless under pressure.
+ */
+export declare const planAttention: (process: ProcessAttention, candidates: readonly ThreadAttentionCandidate[], policy?: AttentionResourcePolicy) => AttentionPlan;
+/**
+ * Rest restores vigilance, reduces load and clears the rest counter.
+ */
+export declare const applyRest: (state: CognitiveState, cycles?: number) => CognitiveState;
+export interface OutcomeStats {
+    successes: number;
+    attempts: number;
+    errors: number;
+    rework: number;
+    attentionSlots: number;
+}
+/**
+ * Efficiency is useful outcomes per unit of attention, not raw utilization.
+ * Errors and rework are subtracted so a busy-but-wrong agent cannot win.
+ */
+export declare const qualityAdjustedThroughput: (stats: OutcomeStats) => number;
+export declare const attentionHealth: (plan: AttentionPlan) => {
+    utilization: number;
+    pressure: number;
+    headroom: number;
+    rest: boolean;
+};