attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/assignment/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Responsibility and interaction assignment types.
+ *
+ * These mirror `docs/schemas/responsibility.schema.json` and
+ * `docs/schemas/interaction.schema.json`. The runtime ledgers in
+ * `assign.ts` and `binding.ts` own validation and lifecycle; this module
+ * owns only the wire shapes.
+ */
+import type { Budget, Criterion, Digest, Id, Ref, Signature, Tier, Timestamp } from "../types/common.js";
+import type { InteractionKind } from "../interaction/interaction.js";
+import type { Performative } from "../protocol/protocol.js";
+export type { Performative };
+export type AssignmentStatus = "proposed" | "accepted" | "declined" | "active" | "blocked" | "discharged" | "breached" | "revoked" | "expired";
+export type AssignmentAcceptanceState = "pending" | "accepted" | "declined";
+/**
+ * One observable unit of responsibility. `conflicts_with` is a separation-of-
+ * duties edge: the referenced duty may not be held by the same assignee while
+ * the two windows overlap.
+ */
+export interface Duty {
+    id: Id;
+    statement: string;
+    scope: string[];
+    acceptance: Criterion[];
+    evidence_required?: string[];
+    conflicts_with?: Id[];
+    delegable?: boolean;
+}
+/**
+ * RACI vocabulary. `accountable` is a single id by construction; the ledger
+ * additionally rejects two active assignments that claim the same duty.
+ */
+export interface Raci {
+    accountable: Id;
+    responsible: Id[];
+    consulted?: Id[];
+    informed?: Id[];
+}
+export interface AssignmentAcceptance {
+    required: boolean;
+    state: AssignmentAcceptanceState;
+    by?: Id;
+    at?: Timestamp;
+    digest?: Digest;
+    note?: string;
+}
+export interface AssignmentEvidence {
+    required: string[];
+    produced: Ref[];
+}
+export interface AssignmentWindow {
+    from: Timestamp;
+    to: Timestamp;
+}
+export interface ResponsibilityAssignment {
+    amp: "0.1";
+    kind: "responsibility-assignment";
+    id: Id;
+    version: number;
+    parent?: Id;
+    assigner: Id;
+    assignee: Id;
+    role?: string;
+    duties: Duty[];
+    raci?: Raci;
+    authority: string[];
+    budget: Budget;
+    window: AssignmentWindow;
+    acceptance?: AssignmentAcceptance;
+    evidence?: AssignmentEvidence;
+    out_of_scope?: string[];
+    delegable: boolean;
+    depth: number;
+    status: AssignmentStatus;
+    why: string;
+    created: Timestamp;
+    digest?: Digest;
+    signatures?: Signature[];
+}
+export type BindingStatus = "proposed" | "active" | "suspended" | "closed" | "breached" | "revoked";
+export type BindingDirection = "one-way" | "request-response" | "duplex" | "broadcast";
+export type ProtocolRole = "initiator" | "responder" | "observer";
+export type ChannelKind = "local" | "a2a" | "mcp" | "http" | "human";
+export type EscalationWhen = "timeout" | "authority_exceeded" | "conflict" | "budget_exhausted" | "integrity_failure" | "manual";
+export type BindingFallback = "queue" | "drop" | "escalate";
+export interface ProtocolRoleBinding {
+    party: Id;
+    role: ProtocolRole;
+}
+export interface InteractionProtocol {
+    id: string;
+    version: string;
+    roles: ProtocolRoleBinding[];
+}
+export interface InteractionChannel {
+    kind: ChannelKind;
+    endpoint?: string;
+    auth?: "none" | "ed25519" | "oauth" | "mtls";
+}
+export interface InteractionCadence {
+    max_turns: number;
+    max_messages: number;
+    response_within_ms: number;
+    interval_ms?: number;
+}
+export interface InteractionExpectations {
+    format?: string;
+    language?: string;
+    evidence_tier?: Tier;
+}
+export interface InteractionEscalation {
+    when: EscalationWhen;
+    to: Id;
+    within_ms: number;
+    fallback?: BindingFallback;
+}
+export interface InteractionHandoff {
+    required_state: Ref[];
+    acceptance: "ack" | "receipt";
+}
+export interface InteractionBinding {
+    amp: "0.1";
+    kind: "interaction-binding";
+    id: Id;
+    version: number;
+    assignment?: Id;
+    parties: Id[];
+    purpose: Ref;
+    channel: InteractionChannel;
+    protocol: InteractionProtocol;
+    mode_mix: Partial<Record<InteractionKind, number>>;
+    direction: BindingDirection;
+    cadence: InteractionCadence;
+    expectations?: InteractionExpectations;
+    escalation?: InteractionEscalation[];
+    handoff?: InteractionHandoff;
+    budget?: Budget;
+    status: BindingStatus;
+    why: string;
+    created: Timestamp;
+    digest?: Digest;
+    signatures?: Signature[];
+}
+export type AssignmentEventType = "assignment.proposed" | "assignment.accepted" | "assignment.declined" | "assignment.activated" | "assignment.blocked" | "assignment.resumed" | "assignment.discharged" | "assignment.breached" | "assignment.revoked" | "assignment.expired";
+export interface AssignmentEvent {
+    type: AssignmentEventType;
+    assignment: Id;
+    at: Timestamp;
+    by: Id;
+    reason?: string;
+    digest?: Digest;
+}
+export type BindingEventType = "binding.proposed" | "binding.acked" | "binding.activated" | "binding.suspended" | "binding.resumed" | "binding.message" | "binding.escalated" | "binding.handoff" | "binding.closed" | "binding.breached" | "binding.revoked";
+export interface BindingEvent {
+    type: BindingEventType;
+    binding: Id;
+    at: Timestamp;
+    by: Id;
+    reason?: string;
+    digest?: Digest;
+}
+export interface BindingMessageRecord {
+    binding: Id;
+    sequence: number;
+    from: Id;
+    to: Id;
+    performative: Performative;
+    at: Timestamp;
+}

package/lib/assignment/types.js

@@ -0,0 +1 @@
+export {};

package/lib/attention/budget.d.ts

@@ -25,7 +25,7 @@ export declare class Dispatcher {
     private used;
     constructor(lease: Budget);
     run<T>(fn: () => T, cost?: CallCost): T;
-    private charge;
+    private nextUsage;
     usage(): Usage;
     remaining(): Required<Pick<Budget, "tokens" | "calls" | "ms">>;
 }

package/lib/attention/budget.js

@@ -23,24 +23,46 @@ export class Dispatcher {
     lease;
     used = { tokens: 0, calls: 0, ms: 0 };
     constructor(lease) {
-        this.lease = lease;
+        for (const dimension of ["tokens", "calls", "ms"]) {
+            const limit = lease[dimension];
+            if (limit !== (void 0) && (!Number.isFinite(limit) || limit < 0)) {
+                throw new RangeError(`budget ${dimension} must be a finite non-negative number`);
+            }
+        }
+        this.lease = { ...lease };
     }
     run(fn, cost = {}) {
-        this.charge("tokens", cost.tokens ?? 0);
-        this.charge("calls", cost.calls ?? 1);
-        this.charge("ms", cost.ms ?? 0);
+        const amounts = {
+            tokens: cost.tokens ?? 0,
+            calls: cost.calls ?? 1,
+            ms: cost.ms ?? 0,
+        };
+        for (const dimension of ["tokens", "calls", "ms"]) {
+            const amount = amounts[dimension];
+            if (!Number.isFinite(amount) || amount < 0) {
+                throw new RangeError(`call cost ${dimension} must be a finite non-negative number`);
+            }
+        }
+        // Validate every dimension and compute all next values before mutating
+        // usage. A failed multi-dimensional charge must be fully atomic.
+        const next = {
+            tokens: this.nextUsage("tokens", amounts.tokens),
+            calls: this.nextUsage("calls", amounts.calls),
+            ms: this.nextUsage("ms", amounts.ms),
+        };
+        this.used = next;
         return fn();
     }
-    charge(dimension, amount) {
-        if (amount === 0) {
-            return;
+    nextUsage(dimension, amount) {
+        const next = this.used[dimension] + amount;
+        if (!Number.isFinite(next)) {
+            throw new RangeError(`budget ${dimension} would overflow`);
         }
         const limit = this.lease[dimension];
-        const next = this.used[dimension] + amount;
         if (limit !== (void 0) && next > limit) {
             throw new BudgetExceeded(dimension, limit, next);
         }
-        this.used[dimension] = next;
+        return next;
     }
     usage() {
         return { tokens: this.used.tokens, calls: this.used.calls, ms: this.used.ms };

package/lib/bayes/engine.js

@@ -211,7 +211,8 @@ export class BayesianEngine {
     priors;
     sourceWeights;
     constructor(priors = {}, sourceWeights = {}) {
-        this.priors = { ...DefaultPriors, ...priors };
+        const supplied = { ...DefaultPriors, ...priors };
+        this.priors = Object.fromEntries(Object.entries(supplied).map(([dimension, belief]) => [dimension, { ...belief }]));
         this.sourceWeights = { ...sourceWeights };
     }
     scoreDimensions(evidence, dimensions) {

package/lib/bayes/reliability.js

@@ -2,33 +2,48 @@ export class SourceReliability {
     prior;
     beliefs = new Map();
     constructor(prior = { alpha: 2, beta: 2 }) {
-        this.prior = prior;
+        if (!Number.isFinite(prior.alpha) || !Number.isFinite(prior.beta) || prior.alpha < 0 || prior.beta < 0) {
+            throw new RangeError("reliability prior must contain finite non-negative counts");
+        }
+        this.prior = { ...prior };
     }
     observe(source, correct, weight = 1) {
+        if (!Number.isFinite(weight) || weight < 0) {
+            throw new RangeError("reliability weight must be a finite non-negative number");
+        }
         const current = this.beliefs.get(source) ?? { ...this.prior, observations: 0 };
-        const amount = Math.max(0, weight);
-        current.alpha += correct ? amount : 0;
-        current.beta += correct ? 0 : amount;
-        current.observations += 1;
-        this.beliefs.set(source, current);
-        return current;
+        const next = {
+            alpha: current.alpha + (correct ? weight : 0),
+            beta: current.beta + (correct ? 0 : weight),
+            observations: current.observations + 1,
+        };
+        if (!Number.isFinite(next.alpha) || !Number.isFinite(next.beta) || !Number.isSafeInteger(next.observations)) {
+            throw new RangeError("reliability observation would overflow");
+        }
+        this.beliefs.set(source, next);
+        return { ...next };
     }
     weight(source) {
         const belief = this.beliefs.get(source);
         if (belief === (void 0)) {
             return 1;
         }
-        const total = belief.alpha + belief.beta;
-        return total === 0 ? 1 : belief.alpha / total;
+        const scale = Math.max(belief.alpha, belief.beta);
+        return scale === 0 ? 1 : (belief.alpha / scale) / (belief.alpha / scale + belief.beta / scale);
     }
     weights() {
         return Object.fromEntries([...this.beliefs.keys()].map((source) => [source, this.weight(source)]));
     }
     snapshot() {
-        return Object.fromEntries(this.beliefs);
+        return Object.fromEntries([...this.beliefs].map(([source, belief]) => [source, { ...belief }]));
     }
     load(snapshot) {
         const entries = Object.entries(snapshot);
+        for (const [, belief] of entries) {
+            if (!Number.isFinite(belief.alpha) || !Number.isFinite(belief.beta) || belief.alpha < 0 || belief.beta < 0 || !Number.isSafeInteger(belief.observations) || belief.observations < 0) {
+                throw new RangeError("reliability snapshot must contain finite non-negative counts and safe observation counts");
+            }
+        }
         for (let i = 0; i < entries.length; i += 1) {
             const source = entries[i][0];
             const belief = entries[i][1];

package/lib/boundary/frame.d.ts

@@ -7,6 +7,11 @@
  * the part of the exclusion list that does not fit as `deferred`, so nothing is
  * silently dropped.
  *
+ * Construction is a rebuild, not a reference copy: every retained field is
+ * checked against a whitelist and recreated, and then the frame (with
+ * `deferred`) is recursively frozen. A caller that mutates its draft after
+ * construction cannot change a frame that has already been digested.
+ *
  * The frame is not extended with new fields: `frame.schema.json` sets
  * `additionalProperties: false`, so aggregates belong to a later capacity layer,
  * not to this object.
@@ -38,7 +43,8 @@ export interface FrameBoundaryOptions {
      */
     maxSlots?: number;
     /**
-     * Visible exclusions kept on the frame; the rest is returned as `deferred`. Defaults to 50.
+     * Visible exclusions kept on the frame; the rest is returned as `deferred`.
+     * Defaults to 50 and may not be raised above it.
      */
     maxIgnored?: number;
     /**
@@ -55,9 +61,9 @@ export interface FrameBoundaryResult {
 }
 type FrameBoundaryBuilder = (draft: FrameDraft, refs: RefTable, options?: FrameBoundaryOptions) => FrameBoundaryResult;
 /**
- * Validate a draft and return the only frame it permits.
- *
- * @throws BoundaryRejection `invalid_frame` with every problem found.
+ * Public entry point. A revoked `Proxy`, a throwing getter or an exotic
+ * `refs` object can still throw while the draft is inspected; the boundary
+ * contract is that callers only ever see `BoundaryRejection`.
  */
 export declare const frameFrom: FrameBoundaryBuilder;
 export {};