attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/governance/budget.js

@@ -0,0 +1,424 @@
+import { BudgetDimensions, ElasticityLimits, GovernanceError, budgetTotals } from "./types.js";
+import { canApprove } from "./perspectives.js";
+const sumBudget = (left, right) => {
+    const added = budgetTotals(right);
+    const result = { ...left };
+    for (let index = 0; index < BudgetDimensions.length; index += 1) {
+        const dimension = BudgetDimensions[index];
+        result[dimension] = left[dimension] + added[dimension];
+    }
+    return result;
+};
+const projectedRatio = (used, cap, amount) => {
+    const added = budgetTotals(amount);
+    let ratio = 0;
+    for (let index = 0; index < BudgetDimensions.length; index += 1) {
+        const dimension = BudgetDimensions[index];
+        if (cap[dimension] <= 0) {
+            continue;
+        }
+        ratio = Math.max(ratio, (used[dimension] + added[dimension]) / cap[dimension]);
+    }
+    return ratio;
+};
+/**
+ * Reject negative, NaN or infinite amounts before any arithmetic. A negative
+ * charge would otherwise mint quota.
+ */
+const validateBudget = (budget, label) => {
+    for (let index = 0; index < BudgetDimensions.length; index += 1) {
+        const value = budget[BudgetDimensions[index]];
+        if (value === (void 0)) {
+            continue;
+        }
+        if (!Number.isFinite(value) || value < 0) {
+            throw new GovernanceError("budget-invalid", `${label}.${BudgetDimensions[index]} must be a finite non-negative number`);
+        }
+    }
+};
+const snapshotOf = (state) => {
+    const ratio = projectedRatio(state.used, state.cap, {});
+    return {
+        scope: state.scope,
+        id: state.id,
+        cap: { ...state.cap },
+        used: { ...state.used },
+        ratio,
+        frozen: state.frozen,
+        elasticity: state.elasticity,
+        ...(state.frozenReason === (void 0) ? {} : { frozenReason: state.frozenReason }),
+    };
+};
+/**
+ * The three-ledger meter.
+ *
+ * Elasticity semantics:
+ *   - low: up to +20% is appended automatically; beyond that the ledger freezes;
+ *   - medium: anything above the cap needs a finance `budget.top-up` approval,
+ *     up to +35%;
+ *   - high: up to +50% is appended automatically and settled by a post audit.
+ */
+export class GovernanceBudget {
+    now;
+    global;
+    reserve;
+    perspectives = new Map();
+    agents = new Map();
+    records = [];
+    audits = [];
+    transfers = [];
+    constructor(options) {
+        if (typeof (options.now) !== "function") {
+            throw new TypeError("GovernanceBudget requires a clock");
+        }
+        this.now = options.now;
+        this.global = this.state("global", "global", options.global);
+        this.reserve = this.state("reserve", "reserve", options.reserve);
+        const configured = options.perspectives ?? [];
+        for (let index = 0; index < configured.length; index += 1) {
+            const entry = configured[index];
+            this.perspectives.set(entry.perspective, this.state("perspective", entry.perspective, entry));
+        }
+        const agentLedgers = options.agents ?? [];
+        for (let index = 0; index < agentLedgers.length; index += 1) {
+            const entry = agentLedgers[index];
+            this.agents.set(entry.agent, this.state("agent", entry.agent, entry));
+        }
+    }
+    /**
+     * Open a perspective ledger. Re-opening with a different cap is rejected:
+     * a budget change is an approval, not a convenience call.
+     */
+    openPerspective(perspective, cap, elasticity = "low") {
+        const existing = this.perspectives.get(perspective);
+        if (existing !== (void 0)) {
+            throw new GovernanceError("budget-frozen", `ledger for ${perspective} already exists`);
+        }
+        const state = this.state("perspective", perspective, { cap, elasticity });
+        this.perspectives.set(perspective, state);
+        return snapshotOf(state);
+    }
+    /**
+     * Open an agent ledger (an agent's own quota).
+     */
+    openAgent(agent, cap, elasticity = "low") {
+        const existing = this.agents.get(agent);
+        if (existing !== (void 0)) {
+            throw new GovernanceError("budget-frozen", `ledger for agent ${agent} already exists`);
+        }
+        const state = this.state("agent", agent, { cap, elasticity });
+        this.agents.set(agent, state);
+        return snapshotOf(state);
+    }
+    /**
+     * Transfer allocation between a perspective and an agent. A sub-agent's
+     * quota is funded from its parent; the total allocation is conserved.
+     * The finance `budget.allocation` approval is mandatory.
+     */
+    reallocate = (from, to, request) => {
+        const amount = request.amount;
+        const approval = request.approval;
+        const reason = request.reason;
+        const options = request.options ?? {};
+        validateBudget(amount, "reallocation");
+        const targetFrom = this.lookup(from.scope, from.id);
+        const existingTo = to.scope === "perspective" ? this.perspectives.get(to.id) : this.agents.get(to.id);
+        const targetTo = existingTo ?? this.state(to.scope, to.id, { cap: {}, elasticity: options.toElasticity ?? "low" });
+        if (targetFrom.frozen) {
+            return { ok: false, code: "frozen", from: snapshotOf(targetFrom), to: snapshotOf(targetTo), detail: `${from.id} is frozen` };
+        }
+        if (targetTo.frozen) {
+            return { ok: false, code: "frozen", from: snapshotOf(targetFrom), to: snapshotOf(targetTo), detail: `${to.id} is frozen` };
+        }
+        const valid = approval.granted === true &&
+            approval.subject === "budget.allocation" &&
+            canApprove(approval.by, "budget.allocation") &&
+            options.requestedBy !== (void 0) &&
+            options.requestedBy !== approval.by;
+        if (!valid) {
+            return { ok: false, code: "approval-required", from: snapshotOf(targetFrom), to: snapshotOf(targetTo), detail: "a finance budget.allocation approval is required" };
+        }
+        const moved = budgetTotals(amount);
+        for (let index = 0; index < BudgetDimensions.length; index += 1) {
+            const dimension = BudgetDimensions[index];
+            if (moved[dimension] <= 0) {
+                continue;
+            }
+            const available = targetFrom.cap[dimension] - targetFrom.used[dimension];
+            if (targetFrom.cap[dimension] <= 0 || moved[dimension] > available) {
+                return {
+                    ok: false,
+                    code: "insufficient",
+                    from: snapshotOf(targetFrom),
+                    to: snapshotOf(targetTo),
+                    detail: `${dimension}: ${moved[dimension]} requested, ${Math.max(0, available)} available`,
+                };
+            }
+        }
+        for (let index = 0; index < BudgetDimensions.length; index += 1) {
+            const dimension = BudgetDimensions[index];
+            targetFrom.cap[dimension] -= moved[dimension];
+            targetTo.cap[dimension] += moved[dimension];
+        }
+        if (existingTo === (void 0)) {
+            if (to.scope === "perspective") {
+                this.perspectives.set(to.id, targetTo);
+            }
+            else {
+                this.agents.set(to.id, targetTo);
+            }
+        }
+        this.transfers.push({
+            at: this.now(),
+            fromScope: from.scope,
+            fromId: from.id,
+            toScope: to.scope,
+            toId: to.id,
+            amount: moved,
+            reason,
+            approvalId: approval.id,
+        });
+        return { ok: true, code: "reallocated", from: snapshotOf(targetFrom), to: snapshotOf(targetTo), detail: `moved ${reason}` };
+    };
+    /**
+     * Charge one ledger. Denials are values; a frozen ledger refuses before
+     * arithmetic so no caller can spend past a freeze.
+     */
+    charge(request) {
+        validateBudget(request.amount, "charge");
+        const target = this.resolve(request);
+        const snapshot = snapshotOf(target);
+        if (target.frozen) {
+            return this.reject("frozen", snapshot, snapshot.ratio, target.frozenReason ?? "ledger is frozen");
+        }
+        if (request.scope === "reserve") {
+            if (request.escalation !== true) {
+                return this.reject("reserve-restricted", snapshot, snapshot.ratio, "the reserve ledger only funds escalations");
+            }
+            if (!this.approved(request, "budget.reserve")) {
+                return this.reject("approval-required", snapshot, snapshot.ratio, "a reserve charge needs a finance budget.reserve approval");
+            }
+            if (projectedRatio(target.used, target.cap, request.amount) > 0.5 && !this.boardApproved(request.boardApproval)) {
+                return this.reject("approval-required", snapshot, snapshot.ratio, "a reserve draw above 50% also needs a board approval");
+            }
+        }
+        const ratio = projectedRatio(target.used, target.cap, request.amount);
+        const limit = ElasticityLimits[target.elasticity];
+        if (ratio <= 1) {
+            this.commit(target, request, "charged", ratio);
+            return { ok: true, code: "charged", ledger: snapshotOf(target), ratio, detail: "within cap" };
+        }
+        if (ratio <= 1 + limit.autoRatio) {
+            const code = limit.postAudit ? "charged-post-audit" : "charged";
+            this.commit(target, request, code, ratio);
+            if (limit.postAudit) {
+                this.audits.push({ at: this.now(), scope: target.scope, ledgerId: target.id, amount: budgetTotals(request.amount), reason: request.reason });
+            }
+            return { ok: true, code, ledger: snapshotOf(target), ratio, detail: `within ${Math.round(limit.autoRatio * 100)}% elasticity` };
+        }
+        if (limit.requiresApproval && ratio <= 1 + limit.hardRatio) {
+            if (!this.approved(request, "budget.top-up")) {
+                return this.reject("approval-required", snapshot, ratio, "over cap; finance top-up approval required");
+            }
+            this.commit(target, request, "charged-with-approval", ratio);
+            return {
+                ok: true,
+                code: "charged-with-approval",
+                ledger: snapshotOf(target),
+                ratio,
+                detail: "over cap with finance approval",
+                ...(request.approval === (void 0) ? {} : { approvalId: request.approval.id }),
+            };
+        }
+        target.frozen = true;
+        target.frozenReason = `hard ceiling at ${Math.round((1 + limit.hardRatio) * 100)}% of cap`;
+        this.records.push({
+            at: this.now(),
+            scope: target.scope,
+            ledgerId: target.id,
+            amount: budgetTotals(request.amount),
+            reason: request.reason,
+            code: "exhausted",
+        });
+        return this.reject("exhausted", snapshotOf(target), ratio, target.frozenReason);
+    }
+    /**
+     * Freeze one ledger. Finance owns this right; the reason is mandatory so a
+     * later audit can tell a policy freeze from an incident freeze.
+     */
+    freeze(scope, id, reason, by = "finance") {
+        if (!canApprove(by, "budget.freeze")) {
+            throw new GovernanceError("approval-not-permitted", `${by} may not freeze a ledger`);
+        }
+        const target = this.lookup(scope, id);
+        target.frozen = true;
+        target.frozenReason = reason;
+        return snapshotOf(target);
+    }
+    /**
+     * Unfreeze requires a finance approval on record.
+     */
+    unfreeze(scope, id, approval) {
+        if (approval.granted !== true || !canApprove(approval.by, "budget.freeze")) {
+            throw new GovernanceError("approval-not-permitted", "unfreeze requires a granted finance approval");
+        }
+        const target = this.lookup(scope, id);
+        target.frozen = false;
+        delete target.frozenReason;
+        return snapshotOf(target);
+    }
+    /**
+     * Draw from the escalation reserve. Every draw needs a finance approval; a
+     * draw above half the reserve also needs a board `budget.major-top-up`
+     * approval (spec section 8). The board approval is never inferred from the
+     * finance one.
+     */
+    drawReserve(amount, approval, reason, boardApproval) {
+        validateBudget(amount, "reserve draw");
+        if (approval.granted !== true || approval.subject !== "budget.reserve" || !canApprove(approval.by, "budget.reserve")) {
+            throw new GovernanceError("approval-required", "reserve draws require a granted finance budget.reserve approval");
+        }
+        const ratio = projectedRatio(this.reserve.used, this.reserve.cap, amount);
+        if (ratio > 0.5) {
+            const boardApproved = this.boardApproved(boardApproval);
+            if (!boardApproved) {
+                throw new GovernanceError("approval-required", "a reserve draw above 50% also needs a board budget.major-top-up approval");
+            }
+        }
+        return this.charge({
+            scope: "reserve",
+            amount,
+            reason,
+            escalation: true,
+            approval,
+            requestedBy: "general-manager",
+            ...(boardApproval === (void 0) ? {} : { boardApproval }),
+        });
+    }
+    snapshot(scope, id) {
+        const ledgerId = id ?? (scope === "global" || scope === "reserve" ? scope : "");
+        return snapshotOf(this.lookup(scope, ledgerId));
+    }
+    /**
+     * Remaining allocation on one ledger (cap minus used, per dimension).
+     */
+    remaining(scope, id) {
+        const target = this.lookup(scope, id ?? (scope === "global" || scope === "reserve" ? scope : ""));
+        const result = budgetTotals({});
+        for (let index = 0; index < BudgetDimensions.length; index += 1) {
+            const dimension = BudgetDimensions[index];
+            result[dimension] = Math.max(0, target.cap[dimension] - target.used[dimension]);
+        }
+        return result;
+    }
+    snapshots() {
+        return [snapshotOf(this.global), snapshotOf(this.reserve), ...this.perspectives.values(), ...this.agents.values()].map(snapshotOf);
+    }
+    /**
+     * End-of-task settlement: every ledger, every transfer, every post-audit
+     * entry and the freeze list, so the archive phase can attach one object.
+     */
+    settle() {
+        const perspectives = [...this.perspectives.values()].map(snapshotOf);
+        const agents = [...this.agents.values()].map(snapshotOf);
+        const frozen = [snapshotOf(this.global), snapshotOf(this.reserve), ...perspectives, ...agents].filter((entry) => entry.frozen);
+        return {
+            global: snapshotOf(this.global),
+            reserve: snapshotOf(this.reserve),
+            perspectives,
+            agents,
+            transfers: this.transfers.map((record) => ({ ...record, amount: { ...record.amount } })),
+            charges: this.records.length,
+            postAudit: [...this.audits],
+            frozen,
+            balanced: this.records.every((record) => record.code !== "exhausted"),
+        };
+    }
+    history() {
+        return this.records.map((record) => ({ ...record, amount: { ...record.amount } }));
+    }
+    transferHistory() {
+        return this.transfers.map((record) => ({ ...record, amount: { ...record.amount } }));
+    }
+    state(scope, id, config) {
+        validateBudget(config.cap, `ledger ${id}`);
+        return {
+            scope,
+            id,
+            cap: budgetTotals(config.cap),
+            used: budgetTotals({}),
+            elasticity: config.elasticity,
+            frozen: false,
+        };
+    }
+    resolvedId(request) {
+        if (request.scope === "perspective") {
+            if (request.perspective === (void 0)) {
+                throw new GovernanceError("budget-exhausted", "a perspective charge needs a perspective id");
+            }
+            return request.perspective;
+        }
+        if (request.scope === "agent") {
+            if (request.agent === (void 0)) {
+                throw new GovernanceError("budget-exhausted", "an agent charge needs an agent id");
+            }
+            return request.agent;
+        }
+        return request.scope;
+    }
+    resolve(request) {
+        return this.lookup(request.scope, this.resolvedId(request));
+    }
+    lookup(scope, id) {
+        if (scope === "global") {
+            return this.global;
+        }
+        if (scope === "reserve") {
+            return this.reserve;
+        }
+        if (scope === "agent") {
+            const agentLedger = this.agents.get(id);
+            if (agentLedger === (void 0)) {
+                throw new GovernanceError("budget-exhausted", `no ledger for agent ${id}`);
+            }
+            return agentLedger;
+        }
+        const found = this.perspectives.get(id);
+        if (found === (void 0)) {
+            throw new GovernanceError("budget-exhausted", `no ledger for perspective ${id}`);
+        }
+        return found;
+    }
+    approved(request, subject) {
+        const approval = request.approval;
+        if (approval === (void 0) || approval.granted !== true || approval.subject !== subject) {
+            return false;
+        }
+        if (!canApprove(approval.by, subject)) {
+            return false;
+        }
+        return request.requestedBy !== (void 0) && request.requestedBy !== approval.by;
+    }
+    boardApproved(approval) {
+        return approval !== (void 0) && approval.granted === true && approval.subject === "budget.major-top-up" && canApprove(approval.by, "budget.major-top-up");
+    }
+    commit(target, request, code, ratio) {
+        target.used = sumBudget(target.used, request.amount);
+        this.records.push({
+            at: this.now(),
+            scope: target.scope,
+            ledgerId: target.id,
+            amount: budgetTotals(request.amount),
+            reason: request.reason,
+            code,
+            ...(request.requestedBy === (void 0) ? {} : { requestedBy: request.requestedBy }),
+            ...(request.approval === (void 0) ? {} : { approvalId: request.approval.id }),
+        });
+        if (ratio > 1) {
+            this.audits.push({ at: this.now(), scope: target.scope, ledgerId: target.id, amount: budgetTotals(request.amount), reason: request.reason });
+        }
+    }
+    reject(code, ledger, ratio, detail) {
+        return { ok: false, code, ledger, ratio, detail };
+    }
+}

package/lib/governance/context.d.ts

@@ -0,0 +1,159 @@
+/**
+ * The three-layer context (spec section 3).
+ *
+ *   - global core: goal, signed capability statement, hard constraints,
+ *     priorities, budget, task state, versioned board strategy, scenario and
+ *     mode labels. Every perspective reads it; only the board or a human
+ *     writes it.
+ *   - perspective-private context: the manifest, local reasoning, tool results
+ *     and private budget. Only that perspective may read it, and switching
+ *     seals it.
+ *   - shared receipt blackboard: conclusions, evidence refs, confidence,
+ *     budget spent, manifest version, scenario/mode labels, open questions and
+ *     escalation requests. Each perspective writes only its own receipts.
+ *
+ * The default inheritance is the board strategy summary, not the whole board
+ * context; `expandGlobal` opens the full record on demand.
+ */
+import type { Budget, Digest, Id, Ref, Timestamp } from "../types/common.js";
+import type { ApprovalGrant, EscalationRef, ManifestRef, ModeWeights, PerspectiveId, ScenarioId } from "./types.js";
+export interface StrategyView {
+    version: number;
+    digest: Digest;
+    /**
+     * What a perspective inherits by default.
+     */
+    summary: string;
+    /**
+     * The full board record, expanded only on demand.
+     */
+    detail: string;
+}
+export interface GlobalCore {
+    goal: string;
+    strategy: StrategyView;
+    constraints: string[];
+    priorities: string[];
+    taskState: string;
+    scenario: ScenarioId;
+    modes: ModeWeights;
+    budget: Budget;
+    version: number;
+}
+/**
+ * The read-only projection a perspective receives by default.
+ */
+export interface GlobalCoreView {
+    goal: string;
+    strategyVersion: number;
+    strategyDigest: Digest;
+    strategySummary: string;
+    constraints: string[];
+    priorities: string[];
+    taskState: string;
+    scenario: ScenarioId;
+    modes: ModeWeights;
+    budget: Budget;
+    version: number;
+}
+export interface PrivateNote {
+    at: Timestamp;
+    kind: "reasoning" | "tool-result" | "observation";
+    text: string;
+    refs?: Ref[];
+}
+export interface PrivateContext {
+    perspective: PerspectiveId;
+    manifest: ManifestRef;
+    notes: PrivateNote[];
+    openedAt: Timestamp;
+    sealed: boolean;
+}
+export interface BoardReceiptInput {
+    conclusion: string;
+    evidence: Ref[];
+    confidence: number;
+    budget: Budget;
+    manifest: ManifestRef;
+    scenario: ScenarioId;
+    modes: ModeWeights;
+    openQuestions?: string[];
+    escalation?: EscalationRef;
+    audience?: PerspectiveId[];
+}
+export interface BoardReceipt extends BoardReceiptInput {
+    id: Id;
+    from: PerspectiveId;
+    at: Timestamp;
+    digest: Digest;
+    openQuestions: string[];
+}
+export interface ContextLayersOptions {
+    core: GlobalCore;
+    now: () => Timestamp;
+}
+export interface ContextSnapshot {
+    core: GlobalCore;
+    privateContexts: Array<{
+        perspective: PerspectiveId;
+        notes: number;
+        sealed: boolean;
+    }>;
+    receipts: BoardReceipt[];
+    version: number;
+}
+export declare class ContextLayers {
+    private core;
+    private readonly now;
+    private readonly privateContexts;
+    private readonly receipts;
+    private active;
+    private counter;
+    constructor(options: ContextLayersOptions);
+    /**
+     * The default view: summary only, no full board record.
+     */
+    global(viewer: PerspectiveId): GlobalCoreView;
+    /**
+     * Expand the full board record on demand. The access is not hidden: the
+     * caller records it in its own receipt.
+     */
+    expandGlobal(viewer: PerspectiveId): GlobalCore;
+    /**
+     * Only the board or a human may write the global core. The change bumps
+     * the version so every perspective can detect that its assumption is stale.
+     */
+    writeGlobal(by: PerspectiveId | "human", patch: Partial<GlobalCore>, approval?: ApprovalGrant): GlobalCore;
+    /**
+     * Open a perspective's private context and seal the previously active one.
+     * The caller cannot keep reading the old view through this object.
+     */
+    openPerspective(id: PerspectiveId, manifest: ManifestRef): PrivateContext;
+    seal(id?: PerspectiveId): void;
+    /**
+     * Append a private note. Only the owner of an open context may write it.
+     */
+    writePrivate(id: PerspectiveId, note: PrivateNote): PrivateContext;
+    /**
+     * Read a private context. Only the owner may read it, sealed or not.
+     */
+    readPrivate(id: PerspectiveId, viewer: PerspectiveId): PrivateContext | undefined;
+    /**
+     * Write one receipt to the shared blackboard. The writer must be the active
+     * perspective and the receipt must match its manifest version.
+     */
+    writeReceipt(from: PerspectiveId, input: BoardReceiptInput): BoardReceipt;
+    /**
+     * The blackboard is not public: the management and audit perspectives see
+     * everything, execution perspectives see their own receipts and receipts
+     * addressed to them.
+     */
+    readReceipts(viewer: PerspectiveId): BoardReceipt[];
+    readReceipt(id: Id, viewer: PerspectiveId): BoardReceipt | undefined;
+    /**
+     * Receipts that requested escalation, used by the workflow's escalation
+     * phase.
+     */
+    escalations(): BoardReceipt[];
+    snapshot(): ContextSnapshot;
+}