attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/governance/cooperation.js

@@ -0,0 +1,350 @@
+import { GovernanceError } from "./types.js";
+import { verifyAttentionManifest } from "./attentionManifest.js";
+import { verifyCredential } from "./credential.js";
+import { betaMean } from "../bayes/engine.js";
+import { digestOf } from "../semantic/canonical.js";
+const Messages = new Set(["manifest", "task", "receipt", "escalation", "audit-request"]);
+const DefaultMaxRefs = 16;
+const DefaultMaxSummary = 280;
+export const manifestSummaryOf = (manifest) => ({
+    id: manifest.id,
+    version: manifest.version,
+    scenario: manifest.scenario,
+    modes: { ...manifest.modes },
+    evidenceFloor: manifest.evidenceFloor,
+    focus: manifest.focus.length,
+    digest: manifest.digest,
+});
+const messageDigest = (message) => {
+    const body = { ...message };
+    delete body.digest;
+    return digestOf(body);
+};
+/**
+ * Verify a message digest after transport.
+ */
+export const verifyAgentMessage = (message) => messageDigest(message) === message.digest;
+export class CooperationBus {
+    now;
+    legal;
+    maxRefs;
+    maxSummary;
+    agents = new Map();
+    inboxes = new Map();
+    seen = new Set();
+    board = [];
+    counter = 0;
+    constructor(options) {
+        if (typeof (options.now) !== "function") {
+            throw new TypeError("CooperationBus requires a clock");
+        }
+        this.now = options.now;
+        this.legal = options.legal;
+        this.maxRefs = options.maxRefs ?? DefaultMaxRefs;
+        this.maxSummary = options.maxSummary ?? DefaultMaxSummary;
+    }
+    register(agent) {
+        if (this.agents.has(agent.agentId)) {
+            throw new GovernanceError("registry-invalid", `${agent.agentId} is already registered`);
+        }
+        this.agents.set(agent.agentId, {
+            ...agent,
+            manifest: agent.manifest,
+            reliability: { ...agent.reliability },
+            budget: { ...agent.budget },
+        });
+        this.inboxes.set(agent.agentId, []);
+    }
+    /**
+     * Replace an agent's manifest after a legitimate re-derivation.
+     */
+    refresh(agentId, manifest) {
+        const agent = this.agents.get(agentId);
+        if (agent === (void 0)) {
+            throw new GovernanceError("registry-invalid", `${agentId} is not registered`);
+        }
+        agent.manifest = manifest;
+    }
+    unregister(agentId) {
+        this.inboxes.delete(agentId);
+        return this.agents.delete(agentId);
+    }
+    agent(agentId) {
+        const found = this.agents.get(agentId);
+        return found === (void 0) ? undefined : { ...found, manifest: found.manifest, reliability: { ...found.reliability }, budget: { ...found.budget } };
+    }
+    agentsOf(perspective) {
+        return [...this.agents.values()].filter((agent) => agent.perspective === perspective);
+    }
+    /**
+     * Broadcast a manifest summary. This is the only message that needs no
+     * credential: it contains no payload and no private context.
+     */
+    announce(from, at) {
+        const deliveries = [];
+        const ids = [...this.agents.keys()];
+        for (let index = 0; index < ids.length; index += 1) {
+            const to = ids[index];
+            if (to === from) {
+                continue;
+            }
+            deliveries.push(this.send({ from, to, kind: "manifest", at }));
+        }
+        return deliveries;
+    }
+    /**
+     * Send one structured message. The sender's manifest and, for task or
+     * escalation messages, the credential are validated before delivery.
+     */
+    send(input) {
+        const sender = this.agents.get(input.from);
+        if (sender === (void 0)) {
+            return { ok: false, code: "unknown-sender", detail: `${input.from} is not registered` };
+        }
+        const recipient = this.agents.get(input.to);
+        if (recipient === (void 0)) {
+            return { ok: false, code: "unknown-recipient", detail: `${input.to} is not registered` };
+        }
+        if (input.from === input.to) {
+            return { ok: false, code: "self-send", detail: "an agent cannot message itself" };
+        }
+        if (this.legal !== (void 0) && (this.legal.isBlocked() || this.legal.isFrozen(sender.perspective))) {
+            return { ok: false, code: "legal-blocked", detail: "the sender is frozen or the breaker is active" };
+        }
+        const verdict = verifyAttentionManifest(sender.manifest, input.at);
+        if (!verdict.ok) {
+            return { ok: false, code: "manifest-invalid", detail: verdict.detail ?? "sender manifest is not valid" };
+        }
+        if (input.summary !== (void 0) && input.summary.length > this.maxSummary) {
+            return { ok: false, code: "payload-too-large", detail: `summary exceeds ${this.maxSummary} characters` };
+        }
+        const refs = input.refs ?? [];
+        if (refs.length > this.maxRefs) {
+            return { ok: false, code: "payload-too-large", detail: `more than ${this.maxRefs} refs` };
+        }
+        if (input.kind === "task" || input.kind === "escalation") {
+            if (input.credential === (void 0)) {
+                return { ok: false, code: "credential-missing", detail: `${input.kind} messages need a switch credential` };
+            }
+            const checked = verifyCredential(input.credential, {
+                at: input.at,
+                to: recipient.perspective,
+                manifest: { id: recipient.manifest.id, version: recipient.manifest.version },
+                readRefs: refs,
+            });
+            if (!checked.valid) {
+                return {
+                    ok: false,
+                    code: checked.code === "credential-scope" ? "scope-escape" : "credential-invalid",
+                    detail: `${checked.code}: ${checked.detail}`,
+                };
+            }
+        }
+        if (input.kind === "receipt") {
+            if (input.receipt === (void 0) || input.receipt.conclusion.trim().length === 0 || input.receipt.confidence < 0 || input.receipt.confidence > 1) {
+                return { ok: false, code: "receipt-invalid", detail: "a receipt needs a conclusion and confidence in [0, 1]" };
+            }
+            if (input.receipt.manifest.id !== sender.manifest.id || input.receipt.manifest.version !== sender.manifest.version) {
+                return { ok: false, code: "receipt-invalid", detail: "the receipt cites a different manifest version" };
+            }
+        }
+        if (input.kind === "audit-request" && recipient.perspective !== "supervisory") {
+            return { ok: false, code: "credential-invalid", detail: "audit requests go to the supervisory perspective" };
+        }
+        this.counter += 1;
+        const body = {
+            id: `msg.${this.counter}`,
+            from: input.from,
+            to: input.to,
+            kind: input.kind,
+            at: input.at,
+            manifest: manifestSummaryOf(sender.manifest),
+            ...(input.summary === (void 0) ? {} : { summary: input.summary }),
+            ...(refs.length === 0 ? {} : { refs: refs.map((ref) => ({ ...ref })) }),
+            ...(input.credential === (void 0) ? {} : { credential: input.credential }),
+            ...(input.receipt === (void 0) ? {} : { receipt: { ...input.receipt, evidence: input.receipt.evidence.map((ref) => ({ ...ref })) } }),
+            ...(input.escalation === (void 0) ? {} : { escalation: { ...input.escalation, evidence: input.escalation.evidence.map((ref) => ({ ...ref })) } }),
+        };
+        const message = { ...body, digest: messageDigest(body) };
+        const inbox = this.inboxes.get(input.to) ?? [];
+        inbox.push(message);
+        this.inboxes.set(input.to, inbox);
+        this.seen.add(message.id);
+        this.board.push(message);
+        return { ok: true, code: "delivered", detail: `${message.id} delivered`, message };
+    }
+    /**
+     * Admit a message that arrived over a transport. The receiver re-verifies
+     * the digest, the sender's current manifest, the credential and the receipt
+     * version before the message enters the inbox.
+     */
+    receive(message) {
+        const sender = this.agents.get(message.from);
+        if (sender === (void 0)) {
+            return { ok: false, code: "unknown-sender", detail: `${message.from} is not registered` };
+        }
+        const recipient = this.agents.get(message.to);
+        if (recipient === (void 0)) {
+            return { ok: false, code: "unknown-recipient", detail: `${message.to} is not registered` };
+        }
+        if (message.from === message.to) {
+            return { ok: false, code: "self-send", detail: "an agent cannot message itself" };
+        }
+        if (!Messages.has(message.kind)) {
+            return { ok: false, code: "manifest-invalid", detail: `${`${message.kind}`} is not a message kind` };
+        }
+        if (!verifyAgentMessage(message)) {
+            return { ok: false, code: "manifest-invalid", detail: "message digest does not match" };
+        }
+        if (message.manifest.id !== sender.manifest.id || message.manifest.version !== sender.manifest.version) {
+            return { ok: false, code: "manifest-invalid", detail: "the message cites a stale manifest version" };
+        }
+        if (this.legal !== (void 0) && (this.legal.isBlocked() || this.legal.isFrozen(sender.perspective))) {
+            return { ok: false, code: "legal-blocked", detail: "the sender is frozen or the breaker is active" };
+        }
+        const verdict = verifyAttentionManifest(sender.manifest, message.at);
+        if (!verdict.ok) {
+            return { ok: false, code: "manifest-invalid", detail: verdict.detail ?? "sender manifest is not valid" };
+        }
+        if (message.summary !== (void 0) && message.summary.length > this.maxSummary) {
+            return { ok: false, code: "payload-too-large", detail: `summary exceeds ${this.maxSummary} characters` };
+        }
+        const refs = message.refs ?? [];
+        if (refs.length > this.maxRefs) {
+            return { ok: false, code: "payload-too-large", detail: `more than ${this.maxRefs} refs` };
+        }
+        if (message.kind === "task" || message.kind === "escalation") {
+            if (message.credential === (void 0)) {
+                return { ok: false, code: "credential-missing", detail: `${message.kind} messages need a switch credential` };
+            }
+            const checked = verifyCredential(message.credential, {
+                at: message.at,
+                to: recipient.perspective,
+                manifest: { id: recipient.manifest.id, version: recipient.manifest.version },
+                readRefs: refs,
+            });
+            if (!checked.valid) {
+                return {
+                    ok: false,
+                    code: checked.code === "credential-scope" ? "scope-escape" : "credential-invalid",
+                    detail: `${checked.code}: ${checked.detail}`,
+                };
+            }
+        }
+        if (message.kind === "receipt") {
+            if (message.receipt === (void 0) || message.receipt.conclusion.trim().length === 0 || message.receipt.confidence < 0 || message.receipt.confidence > 1) {
+                return { ok: false, code: "receipt-invalid", detail: "a receipt needs a conclusion and confidence in [0, 1]" };
+            }
+            if (message.receipt.manifest.id !== sender.manifest.id || message.receipt.manifest.version !== sender.manifest.version) {
+                return { ok: false, code: "receipt-invalid", detail: "the receipt cites a different manifest version" };
+            }
+        }
+        if (message.kind === "audit-request" && recipient.perspective !== "supervisory") {
+            return { ok: false, code: "credential-invalid", detail: "audit requests go to the supervisory perspective" };
+        }
+        if (this.seen.has(message.id)) {
+            return { ok: true, code: "delivered", detail: `${message.id} duplicate ignored`, message };
+        }
+        this.seen.add(message.id);
+        const inbox = this.inboxes.get(message.to) ?? [];
+        inbox.push(message);
+        this.inboxes.set(message.to, inbox);
+        this.board.push(message);
+        return { ok: true, code: "delivered", detail: `${message.id} received`, message };
+    }
+    inbox(agentId, at) {
+        const agent = this.agents.get(agentId);
+        if (agent === (void 0)) {
+            throw new GovernanceError("registry-invalid", `${agentId} is not registered`);
+        }
+        const messages = this.inboxes.get(agentId) ?? [];
+        return messages.map((message) => {
+            if (!verifyAgentMessage(message)) {
+                return { ok: false, code: "manifest-invalid", detail: "message digest does not match" };
+            }
+            if (message.credential !== (void 0)) {
+                const checked = verifyCredential(message.credential, {
+                    at,
+                    to: agent.perspective,
+                    manifest: { id: agent.manifest.id, version: agent.manifest.version },
+                });
+                if (!checked.valid) {
+                    return { ok: false, code: "credential-invalid", detail: `${checked.code}: ${checked.detail}` };
+                }
+            }
+            return { ok: true, code: "delivered", detail: message.id, message };
+        });
+    }
+    /**
+     * Prune the communication graph: reliability x information value.
+     */
+    route(from, candidates, options = {}) {
+        const limit = Math.max(0, options.limit ?? 3);
+        const scored = [];
+        for (let index = 0; index < candidates.length; index += 1) {
+            const id = candidates[index];
+            if (id === from) {
+                continue;
+            }
+            const agent = this.agents.get(id);
+            if (agent === (void 0)) {
+                continue;
+            }
+            const value = Math.max(0, options.voi?.[id] ?? 0);
+            scored.push({ id, score: betaMean(agent.reliability) * (1 + value) });
+        }
+        scored.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
+        return scored.slice(0, limit).map((entry) => entry.id);
+    }
+    /**
+     * Update a recipient's reliability from an observed outcome.
+     */
+    observe(agentId, success, weight = 1) {
+        const agent = this.agents.get(agentId);
+        if (agent === (void 0)) {
+            throw new GovernanceError("registry-invalid", `${agentId} is not registered`);
+        }
+        const delta = Math.max(0, weight);
+        agent.reliability = {
+            alpha: agent.reliability.alpha + (success ? delta : 0),
+            beta: agent.reliability.beta + (success ? 0 : delta),
+        };
+        return { ...agent.reliability };
+    }
+    /**
+     * The shared, structured board. It contains message summaries, not private
+     * reasoning, so supervisory audit can read it without inheriting execution
+     * context.
+     */
+    boardEntries() {
+        return this.board.map((message) => message);
+    }
+    /**
+     * An independent audit request: evidence refs only, no receipt body and no
+     * private context. The supervisory agent can trace by reference.
+     */
+    auditRequest(from, evidence, at) {
+        const supervisory = [...this.agents.values()].find((agent) => agent.perspective === "supervisory");
+        if (supervisory === (void 0)) {
+            return { ok: false, code: "unknown-recipient", detail: "no supervisory agent is registered" };
+        }
+        return this.send({ from, to: supervisory.agentId, kind: "audit-request", at, refs: [...evidence], summary: "independent evidence audit" });
+    }
+    /**
+     * Convenience: hand a task to a target with a credential.
+     */
+    handoff(from, to, credential, refs, at, summary) {
+        return this.send({
+            from,
+            to,
+            kind: "task",
+            at,
+            credential,
+            refs: [...refs],
+            ...(summary === (void 0) ? {} : { summary }),
+        });
+    }
+    nowValue() {
+        return this.now();
+    }
+}

package/lib/governance/credential.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The switch credential (spec section 5).
+ *
+ * A credential authorises a target perspective to look at a named scope for a
+ * short time. It carries references, not content. It is issued by the general
+ * manager and countersigned by legal and finance; all three sign-offs are
+ * required before it is valid.
+ *
+ * A credential never replaces a manifest: the credential says what may be
+ * seen, the manifest says what to look at, how deep and at what cost.
+ */
+import type { Digest, Id, Ref, Timestamp } from "../types/common.js";
+import type { BehaviorConstraints, CredentialBudget, ManifestRef, ModeWeights, PerspectiveId, ScenarioId, Signoff, SignerInput } from "./types.js";
+export declare const DefaultCredentialTtlMs: number;
+export declare const MaxCredentialTtlMs: number;
+/**
+ * A credential before the three sign-offs are attached.
+ */
+export interface CredentialDraft {
+    id?: Id;
+    from: PerspectiveId;
+    to: PerspectiveId;
+    reason: string;
+    /**
+     * What the target may read. Refs only; no bodies.
+     */
+    visibleScope: Ref[];
+    /**
+     * The payload handed over. Must be a subset of the visible scope.
+     */
+    payloadRefs: Ref[];
+    budget: CredentialBudget;
+    constraints: BehaviorConstraints;
+    manifest: ManifestRef;
+    scenario: ScenarioId;
+    modes?: Partial<ModeWeights>;
+    issuedAt: Timestamp;
+    ttlMs?: number;
+    notes?: string[];
+}
+/**
+ * The signed credential.
+ */
+export interface SwitchCredential {
+    kind: "switch-credential";
+    id: Id;
+    from: PerspectiveId;
+    to: PerspectiveId;
+    reason: string;
+    visibleScope: Ref[];
+    payloadRefs: Ref[];
+    budget: CredentialBudget;
+    constraints: BehaviorConstraints;
+    manifest: ManifestRef;
+    scenario: ScenarioId;
+    modes: ModeWeights;
+    issuedAt: Timestamp;
+    expires: Timestamp;
+    digest: Digest;
+    signoffs: Signoff[];
+    notes?: string[];
+}
+export interface CredentialRevocation {
+    credentialId: Id;
+    by: PerspectiveId;
+    at: Timestamp;
+    reason: string;
+}
+export interface CredentialVerdict {
+    valid: boolean;
+    code: string;
+    detail: string;
+}
+export interface VerifyCredentialRequest {
+    at: Timestamp;
+    to: PerspectiveId;
+    manifest?: ManifestRef;
+    readRefs?: Ref[];
+    revoked?: readonly CredentialRevocation[];
+}
+type CredentialDigestFn = (credential: Omit<SwitchCredential, "digest" | "signoffs"> | SwitchCredential) => Digest;
+export declare const credentialDigest: CredentialDigestFn;
+/**
+ * Issue a credential. Throws when the direction, the time window or the
+ * three-party signature set is wrong; a credential that needs a fourth
+ * signature (board authorisation for a strategic target) is issued with it.
+ */
+type IssueCredential = (draft: CredentialDraft, signers: readonly SignerInput[]) => SwitchCredential;
+export declare const issueCredential: IssueCredential;
+/**
+ * Verify a credential against a request. Codes are stable so callers can map
+ * them to receipts without parsing prose.
+ */
+type VerifyCredential = (credential: SwitchCredential, request: VerifyCredentialRequest) => CredentialVerdict;
+export declare const verifyCredential: VerifyCredential;
+/**
+ * Minimal read check: the ref must be inside the visible scope.
+ */
+type CanRead = (credential: SwitchCredential, ref: Ref) => boolean;
+export declare const canRead: CanRead;
+/**
+ * Revocation is an event, not an edit: the credential stays byte-identical and
+ * the verifier consults the revocation list.
+ */
+type RevokeCredential = (credential: SwitchCredential, by: PerspectiveId, reason: string, at: Timestamp) => CredentialRevocation;
+export declare const revokeCredential: RevokeCredential;
+/**
+ * One-line audit text for a frame or receipt.
+ */
+type CredentialText = (credential: SwitchCredential) => string;
+export declare const credentialSummary: CredentialText;
+/**
+ * The target perspective's layer, exposed so callers do not import the
+ * registry just to log a handoff.
+ */
+export declare const credentialTargetLayer: CredentialText;
+export {};