@motebit/protocol 0.7.0 → 1.0.0

package/dist/plan-lifecycle.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Plan-lifecycle event payload types — wire format for `plan-lifecycle-v1.md`.
+ *
+ * A plan is the execution backbone for a goal: an ordered list of steps,
+ * each with its own description, status, and tool-call accounting. Plans
+ * are created and advanced by `@motebit/runtime`'s plan-execution
+ * orchestrator; events are emitted at every state transition so the event
+ * log captures an append-only audit trail of every plan run.
+ *
+ * Because plans cross device boundaries (multi-device sync replays plan
+ * history) and delegation boundaries (when a step is delegated, the
+ * delegator logs the delegation; the worker logs its own plan events
+ * against its own motebit_id and the result returns via
+ * `AgentTaskCompleted`), the payload of every plan-lifecycle event must be
+ * pinned as a wire-format type so a non-TypeScript implementer validates
+ * payloads against the committed JSON Schema rather than TypeScript's
+ * structural view.
+ *
+ * Seven event types cover the full lifecycle:
+ *   1. `plan_created`        — plan materialized with N steps
+ *   2. `plan_step_started`   — step N entered running state
+ *   3. `plan_step_completed` — step N reached terminal success
+ *   4. `plan_step_failed`    — step N reached terminal failure
+ *   5. `plan_step_delegated` — step N handed off to a remote agent
+ *   6. `plan_completed`      — every step finished; plan is done
+ *   7. `plan_failed`         — plan terminated before completion
+ *
+ * Every type named here is referenced by a `### X.Y — Name` section under a
+ * `#### Wire format (foundation law)` block in `spec/plan-lifecycle-v1.md`,
+ * so `check-spec-coverage` (invariant #9) keeps the spec and types in
+ * lockstep. Implementing package declaration lives in
+ * `packages/runtime/package.json`'s `motebit.implements` array, enforced by
+ * `check-spec-impl-coverage` (invariant #31).
+ */
+/**
+ * Emitted when `@motebit/runtime`'s plan engine materializes a plan from
+ * a goal or a direct prompt. Each step has its own lifecycle events; this
+ * event records the top-level plan identity and step count.
+ */
+export interface PlanCreatedPayload {
+    /** Stable identifier of the plan. UUID v4 at creation. */
+    readonly plan_id: string;
+    /** Human-readable title summarizing the plan's goal. */
+    readonly title: string;
+    /** Total number of steps the plan was materialized with. */
+    readonly total_steps: number;
+    /** Owning goal when the plan was created in service of a scheduled or on-demand goal. */
+    readonly goal_id?: string;
+}
+/**
+ * Emitted when a plan step transitions from `pending` to `running`. The
+ * step has been chosen and the runtime is about to invoke the
+ * corresponding tool or agent call.
+ */
+export interface PlanStepStartedPayload {
+    readonly plan_id: string;
+    /** Stable identifier of this step. UUID v4, unique within the plan. */
+    readonly step_id: string;
+    /** Zero-based position of the step within its plan. */
+    readonly ordinal: number;
+    /** Human-readable description of what this step does. */
+    readonly description: string;
+    readonly goal_id?: string;
+}
+/**
+ * Emitted when a plan step completes successfully. Carries the tool-call
+ * count so consumers can reconstruct execution cost without replaying
+ * every `tool_used` event. When the step was delegated, `task_id`
+ * carries the delegation identifier so the terminal event joins
+ * payload-directly to its `plan_step_delegated` predecessor — receivers
+ * do not have to maintain a separate task→step index.
+ */
+export interface PlanStepCompletedPayload {
+    readonly plan_id: string;
+    readonly step_id: string;
+    readonly ordinal: number;
+    /** Number of tool calls the step performed. */
+    readonly tool_calls_made: number;
+    /** Delegation task id. Present iff this step was delegated (§3.7). */
+    readonly task_id?: string;
+    readonly goal_id?: string;
+}
+/**
+ * Emitted when a plan step terminates in failure. Carries a free-text
+ * error message; consumers MUST NOT parse it semantically. Receivers MAY
+ * correlate `error` with surrounding `tool_used` events or with a receipt
+ * from a delegated step, but the error string itself is implementation-
+ * detail rationale.
+ */
+export interface PlanStepFailedPayload {
+    readonly plan_id: string;
+    readonly step_id: string;
+    readonly ordinal: number;
+    /** Error message from the failing step. */
+    readonly error: string;
+    /** Delegation task id. Present iff this step was delegated (§3.7). */
+    readonly task_id?: string;
+    readonly goal_id?: string;
+}
+/**
+ * Emitted when a plan step is handed off to a remote agent via
+ * delegation. The delegator logs this event and then waits for the
+ * corresponding `AgentTaskCompleted` / `AgentTaskFailed` event to resume
+ * the plan. The `task_id` is the delegation's relay-issued id; the
+ * `routing_choice` (when present) carries the routing provenance picked
+ * by the semiring so downstream audit can reconstruct why this agent was
+ * chosen.
+ */
+export interface PlanStepDelegatedPayload {
+    readonly plan_id: string;
+    readonly step_id: string;
+    readonly ordinal: number;
+    /** Relay-issued task identifier. Matches the subsequent `AgentTaskCompleted.task_id`. */
+    readonly task_id: string;
+    /**
+     * Routing provenance picked by the semiring. Opaque to this spec; the
+     * motebit semiring module defines the field set. Consumers MAY read
+     * known fields (trust score, latency estimate) but MUST tolerate
+     * additional fields for forward compatibility.
+     */
+    readonly routing_choice?: Record<string, unknown>;
+    readonly goal_id?: string;
+}
+/**
+ * Emitted when every step in a plan has reached a terminal state and the
+ * plan itself is considered done. A plan completes when all its steps
+ * completed or when the plan engine decided to stop short (e.g. the goal
+ * was achieved before the final step). Either way, `plan_completed`
+ * signals the plan record is closed.
+ */
+export interface PlanCompletedPayload {
+    readonly plan_id: string;
+    readonly goal_id?: string;
+}
+/**
+ * Emitted when a plan terminates before completion — a step failed and
+ * the plan engine could not recover, the plan was cancelled, or a policy
+ * gate rejected further execution. The `reason` string is free-text
+ * rationale for the failure.
+ */
+export interface PlanFailedPayload {
+    readonly plan_id: string;
+    /** Free-text failure rationale. Consumers MUST NOT parse it semantically. */
+    readonly reason: string;
+    readonly goal_id?: string;
+}
+//# sourceMappingURL=plan-lifecycle.d.ts.map

package/dist/plan-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-lifecycle.d.ts","sourceRoot":"","sources":["../src/plan-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/dist/plan-lifecycle.js

@@ -0,0 +1,36 @@
+/**
+ * Plan-lifecycle event payload types — wire format for `plan-lifecycle-v1.md`.
+ *
+ * A plan is the execution backbone for a goal: an ordered list of steps,
+ * each with its own description, status, and tool-call accounting. Plans
+ * are created and advanced by `@motebit/runtime`'s plan-execution
+ * orchestrator; events are emitted at every state transition so the event
+ * log captures an append-only audit trail of every plan run.
+ *
+ * Because plans cross device boundaries (multi-device sync replays plan
+ * history) and delegation boundaries (when a step is delegated, the
+ * delegator logs the delegation; the worker logs its own plan events
+ * against its own motebit_id and the result returns via
+ * `AgentTaskCompleted`), the payload of every plan-lifecycle event must be
+ * pinned as a wire-format type so a non-TypeScript implementer validates
+ * payloads against the committed JSON Schema rather than TypeScript's
+ * structural view.
+ *
+ * Seven event types cover the full lifecycle:
+ *   1. `plan_created`        — plan materialized with N steps
+ *   2. `plan_step_started`   — step N entered running state
+ *   3. `plan_step_completed` — step N reached terminal success
+ *   4. `plan_step_failed`    — step N reached terminal failure
+ *   5. `plan_step_delegated` — step N handed off to a remote agent
+ *   6. `plan_completed`      — every step finished; plan is done
+ *   7. `plan_failed`         — plan terminated before completion
+ *
+ * Every type named here is referenced by a `### X.Y — Name` section under a
+ * `#### Wire format (foundation law)` block in `spec/plan-lifecycle-v1.md`,
+ * so `check-spec-coverage` (invariant #9) keeps the spec and types in
+ * lockstep. Implementing package declaration lives in
+ * `packages/runtime/package.json`'s `motebit.implements` array, enforced by
+ * `check-spec-impl-coverage` (invariant #31).
+ */
+export {};
+//# sourceMappingURL=plan-lifecycle.js.map

package/dist/plan-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-lifecycle.js","sourceRoot":"","sources":["../src/plan-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG"}

package/dist/semiring.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Semiring — the algebraic foundation for agent network computation.
+ *
+ * A semiring (S, ⊕, ⊗, 0, 1) satisfies:
+ *   (S, ⊕, 0) — commutative monoid (aggregation of parallel alternatives)
+ *   (S, ⊗, 1) — monoid (sequential composition)
+ *   ⊗ distributes over ⊕: a ⊗ (b ⊕ c) = (a ⊗ b) ⊕ (a ⊗ c)
+ *   0 annihilates: a ⊗ 0 = 0 ⊗ a = 0
+ *
+ * Different semirings model different routing concerns over the same graph:
+ *   Trust:       (max, ×, 0, 1)  → most trusted delegation chain
+ *   Cost:        (min, +, ∞, 0)  → cheapest agent pipeline
+ *   Latency:     (min, +, ∞, 0)  → fastest sequential path
+ *   Bottleneck:  (max, min, 0, 1) → widest bottleneck path (capacity)
+ *   Reliability: (max, ×, 0, 1)  → most reliable chain
+ *   Boolean:     (∨, ∧, ⊥, ⊤)   → reachability
+ *
+ * One graph. One algorithm. Swap the semiring. Different answer.
+ */
+export interface Semiring<T> {
+    /** Additive identity. The "worst" or "impossible" value. */
+    readonly zero: T;
+    /** Multiplicative identity. Passthrough / no-op edge. */
+    readonly one: T;
+    /** ⊕: aggregate parallel alternatives (commutative, associative). */
+    add(a: T, b: T): T;
+    /** ⊗: compose sequential edges (associative). */
+    mul(a: T, b: T): T;
+    /**
+     * Value equality. Used by graph traversal for convergence detection.
+     * Defaults to `===` when absent — correct for primitive semirings (number, boolean).
+     * Required for compound semirings (record, product, annotated) where `add()`
+     * returns a new object even when the value is semantically unchanged.
+     *
+     * Declared as a property (not method) so extracting it doesn't trigger
+     * unbound-method lint — semiring objects are plain data, never class instances.
+     */
+    readonly eq?: ((a: T, b: T) => boolean) | undefined;
+}
+/** (max, ×, 0, 1) — most trusted delegation chain through the network. */
+export declare const TrustSemiring: Semiring<number>;
+/**
+ * (min, +, ∞, 0) — cheapest path through the agent network.
+ * Tropical semiring. Same algebra as Dijkstra / Bellman-Ford.
+ */
+export declare const CostSemiring: Semiring<number>;
+/** (min, +, ∞, 0) — fastest sequential path (sum of edge latencies). */
+export declare const LatencySemiring: Semiring<number>;
+/** (max, min, 0, ∞) — widest bottleneck path (capacity-limited routing). */
+export declare const BottleneckSemiring: Semiring<number>;
+/** (max, ×, 0, 1) — most reliable chain (probability product). */
+export declare const ReliabilitySemiring: Semiring<number>;
+/**
+ * (min, +, ∞, 0) — lowest regulatory risk path.
+ * Risk accumulates along delegation chains (additive composition),
+ * parallel alternatives pick the lowest-risk route (min choice).
+ *
+ * Edge weights represent risk scores: 0 = no risk, ∞ = impossible.
+ * Jurisdictional data handling, compliance requirements, audit depth —
+ * all accumulate when one agent delegates to another.
+ */
+export declare const RegulatoryRiskSemiring: Semiring<number>;
+/** (∨, ∧, false, true) — can agent A reach agent B? */
+export declare const BooleanSemiring: Semiring<boolean>;
+/**
+ * (max, +, -∞, 0) — numerically stable max-product via log-space.
+ *
+ * Multiplying many small probabilities or confidences (each < 1) in
+ * linear space underflows fast: twenty 0.1-confidence edges collapse
+ * to 10⁻²⁰, which starts losing precision before then and hits
+ * denormals by 50. In log space the product becomes a sum; max stays
+ * max. Isomorphic to `ReliabilitySemiring` via x ↦ log(x), but callers
+ * skip the intermediate floats and stay stable over deep chains.
+ *
+ * Used by memory-graph's `recallConfidentChain` lens — most-confident
+ * reasoning chain through the memory graph. Also valid as the Viterbi
+ * recurrence semiring on DAG-structured trellises (when HMM-shape
+ * inference joins the codebase as a separate primitive).
+ */
+export declare const MaxProductLogSemiring: Semiring<number>;
+/**
+ * Product semiring: optimize multiple concerns simultaneously.
+ *
+ * (A × B, ⊕_A × ⊕_B, ⊗_A × ⊗_B, (0_A, 0_B), (1_A, 1_B))
+ *
+ * One graph traversal computes trust × cost × latency in a single pass.
+ */
+export declare function productSemiring<A, B>(sa: Semiring<A>, sb: Semiring<B>): Semiring<readonly [A, B]>;
+/**
+ * Lift a scalar semiring into a named-fields record semiring.
+ * Useful when you want labeled dimensions instead of nested tuples.
+ *
+ *   const Multi = recordSemiring({ trust: TrustSemiring, cost: CostSemiring });
+ *   // Semiring<{ trust: number; cost: number }>
+ */
+export declare function recordSemiring<R extends Record<string, unknown>>(fields: {
+    [K in keyof R]: Semiring<R[K]>;
+}): Semiring<R>;
+/**
+ * Map a semiring through an isomorphism.
+ * Useful for wrapping/unwrapping branded types or unit conversions.
+ */
+export declare function mappedSemiring<T, U>(base: Semiring<T>, to: (t: T) => U, from: (u: U) => T): Semiring<U>;
+//# sourceMappingURL=semiring.d.ts.map

package/dist/semiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semiring.d.ts","sourceRoot":"","sources":["../src/semiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IAChB,qEAAqE;IACrE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACnB,iDAAiD;IACjD,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACrD;AAID,0EAA0E;AAC1E,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAK1C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAKzC,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAK5C,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAK/C,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAKhD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAKnD,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,OAAO,CAK7C,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAKlD,CAAC;AAIF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAYjG;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE;KACvE,CAAC,IAAI,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/B,GAAG,QAAQ,CAAC,CAAC,CAAC,CAwCd;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EACjC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EACf,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAChB,QAAQ,CAAC,CAAC,CAAC,CAUb"}

package/dist/semiring.js

@@ -0,0 +1,187 @@
+/**
+ * Semiring — the algebraic foundation for agent network computation.
+ *
+ * A semiring (S, ⊕, ⊗, 0, 1) satisfies:
+ *   (S, ⊕, 0) — commutative monoid (aggregation of parallel alternatives)
+ *   (S, ⊗, 1) — monoid (sequential composition)
+ *   ⊗ distributes over ⊕: a ⊗ (b ⊕ c) = (a ⊗ b) ⊕ (a ⊗ c)
+ *   0 annihilates: a ⊗ 0 = 0 ⊗ a = 0
+ *
+ * Different semirings model different routing concerns over the same graph:
+ *   Trust:       (max, ×, 0, 1)  → most trusted delegation chain
+ *   Cost:        (min, +, ∞, 0)  → cheapest agent pipeline
+ *   Latency:     (min, +, ∞, 0)  → fastest sequential path
+ *   Bottleneck:  (max, min, 0, 1) → widest bottleneck path (capacity)
+ *   Reliability: (max, ×, 0, 1)  → most reliable chain
+ *   Boolean:     (∨, ∧, ⊥, ⊤)   → reachability
+ *
+ * One graph. One algorithm. Swap the semiring. Different answer.
+ */
+// ── Concrete Semirings ──────────────────────────────────────────────
+/** (max, ×, 0, 1) — most trusted delegation chain through the network. */
+export const TrustSemiring = {
+    zero: 0,
+    one: 1,
+    add: (a, b) => Math.max(a, b),
+    mul: (a, b) => a * b,
+};
+/**
+ * (min, +, ∞, 0) — cheapest path through the agent network.
+ * Tropical semiring. Same algebra as Dijkstra / Bellman-Ford.
+ */
+export const CostSemiring = {
+    zero: Infinity,
+    one: 0,
+    add: (a, b) => Math.min(a, b),
+    mul: (a, b) => a + b,
+};
+/** (min, +, ∞, 0) — fastest sequential path (sum of edge latencies). */
+export const LatencySemiring = {
+    zero: Infinity,
+    one: 0,
+    add: (a, b) => Math.min(a, b),
+    mul: (a, b) => a + b,
+};
+/** (max, min, 0, ∞) — widest bottleneck path (capacity-limited routing). */
+export const BottleneckSemiring = {
+    zero: 0,
+    one: Infinity,
+    add: (a, b) => Math.max(a, b),
+    mul: (a, b) => Math.min(a, b),
+};
+/** (max, ×, 0, 1) — most reliable chain (probability product). */
+export const ReliabilitySemiring = {
+    zero: 0,
+    one: 1,
+    add: (a, b) => Math.max(a, b),
+    mul: (a, b) => a * b,
+};
+/**
+ * (min, +, ∞, 0) — lowest regulatory risk path.
+ * Risk accumulates along delegation chains (additive composition),
+ * parallel alternatives pick the lowest-risk route (min choice).
+ *
+ * Edge weights represent risk scores: 0 = no risk, ∞ = impossible.
+ * Jurisdictional data handling, compliance requirements, audit depth —
+ * all accumulate when one agent delegates to another.
+ */
+export const RegulatoryRiskSemiring = {
+    zero: Infinity,
+    one: 0,
+    add: (a, b) => Math.min(a, b),
+    mul: (a, b) => a + b,
+};
+/** (∨, ∧, false, true) — can agent A reach agent B? */
+export const BooleanSemiring = {
+    zero: false,
+    one: true,
+    add: (a, b) => a || b,
+    mul: (a, b) => a && b,
+};
+/**
+ * (max, +, -∞, 0) — numerically stable max-product via log-space.
+ *
+ * Multiplying many small probabilities or confidences (each < 1) in
+ * linear space underflows fast: twenty 0.1-confidence edges collapse
+ * to 10⁻²⁰, which starts losing precision before then and hits
+ * denormals by 50. In log space the product becomes a sum; max stays
+ * max. Isomorphic to `ReliabilitySemiring` via x ↦ log(x), but callers
+ * skip the intermediate floats and stay stable over deep chains.
+ *
+ * Used by memory-graph's `recallConfidentChain` lens — most-confident
+ * reasoning chain through the memory graph. Also valid as the Viterbi
+ * recurrence semiring on DAG-structured trellises (when HMM-shape
+ * inference joins the codebase as a separate primitive).
+ */
+export const MaxProductLogSemiring = {
+    zero: -Infinity,
+    one: 0,
+    add: (a, b) => Math.max(a, b),
+    mul: (a, b) => a + b,
+};
+// ── Semiring Combinators ────────────────────────────────────────────
+/**
+ * Product semiring: optimize multiple concerns simultaneously.
+ *
+ * (A × B, ⊕_A × ⊕_B, ⊗_A × ⊗_B, (0_A, 0_B), (1_A, 1_B))
+ *
+ * One graph traversal computes trust × cost × latency in a single pass.
+ */
+export function productSemiring(sa, sb) {
+    const saEq = sa.eq;
+    const sbEq = sb.eq;
+    const eqA = (a, b) => (saEq ? saEq(a, b) : a === b);
+    const eqB = (a, b) => (sbEq ? sbEq(a, b) : a === b);
+    return {
+        zero: [sa.zero, sb.zero],
+        one: [sa.one, sb.one],
+        add: (x, y) => [sa.add(x[0], y[0]), sb.add(x[1], y[1])],
+        mul: (x, y) => [sa.mul(x[0], y[0]), sb.mul(x[1], y[1])],
+        eq: (x, y) => eqA(x[0], y[0]) && eqB(x[1], y[1]),
+    };
+}
+/**
+ * Lift a scalar semiring into a named-fields record semiring.
+ * Useful when you want labeled dimensions instead of nested tuples.
+ *
+ *   const Multi = recordSemiring({ trust: TrustSemiring, cost: CostSemiring });
+ *   // Semiring<{ trust: number; cost: number }>
+ */
+export function recordSemiring(fields) {
+    const keys = Object.keys(fields);
+    const zero = {};
+    const one = {};
+    const eqs = {};
+    for (const k of keys) {
+        const f = fields[k];
+        zero[k] = f.zero;
+        one[k] = f.one;
+        const fEq = f.eq;
+        eqs[k] = fEq
+            ? (a, b) => fEq(a, b)
+            : (a, b) => a === b;
+    }
+    return {
+        zero,
+        one,
+        add(a, b) {
+            const r = {};
+            for (const k of keys) {
+                const f = fields[k];
+                r[k] = f.add(a[k], b[k]);
+            }
+            return r;
+        },
+        mul(a, b) {
+            const r = {};
+            for (const k of keys) {
+                const f = fields[k];
+                r[k] = f.mul(a[k], b[k]);
+            }
+            return r;
+        },
+        eq(a, b) {
+            for (const k of keys) {
+                if (!eqs[k](a[k], b[k]))
+                    return false;
+            }
+            return true;
+        },
+    };
+}
+/**
+ * Map a semiring through an isomorphism.
+ * Useful for wrapping/unwrapping branded types or unit conversions.
+ */
+export function mappedSemiring(base, to, from) {
+    const bEq = base.eq;
+    const baseEq = (a, b) => (bEq ? bEq(a, b) : a === b);
+    return {
+        zero: to(base.zero),
+        one: to(base.one),
+        add: (a, b) => to(base.add(from(a), from(b))),
+        mul: (a, b) => to(base.mul(from(a), from(b))),
+        eq: (a, b) => baseEq(from(a), from(b)),
+    };
+}
+//# sourceMappingURL=semiring.js.map

package/dist/semiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semiring.js","sourceRoot":"","sources":["../src/semiring.ts"],"names":[],"mappings":"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"}

package/dist/settlement-mode.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Settlement mode types — relay-mediated vs peer-to-peer settlement.
+ *
+ * Permissive floor (Apache-2.0): these types define the interoperable format
+ * for settlement mode selection and payment proof verification.
+ */
+/** How money moves for a task: through the relay's virtual accounts, or directly onchain. */
+export type SettlementMode = "relay" | "p2p";
+/**
+ * Proof of direct onchain payment from delegator to worker.
+ * Submitted by the delegator at task submission time.
+ */
+export interface P2pPaymentProof {
+    /** Onchain transaction signature (Solana base58, 87-88 chars). */
+    tx_hash: string;
+    /** Chain identifier (e.g., "solana"). */
+    chain: string;
+    /** CAIP-2 network identifier. */
+    network: string;
+    /** Worker's declared settlement address (base58 for Solana). */
+    to_address: string;
+    /** Exact payment amount in micro-units (USDC 6 decimals). Must match expected amount. */
+    amount_micro: number;
+}
+/** Verification status of an onchain payment proof. */
+export type PaymentVerificationStatus = "pending" | "verified" | "failed";
+/**
+ * Relay-signed attestation of an agent's available balance.
+ *
+ * Workers verify this before starting expensive p2p tasks where
+ * the relay doesn't escrow. Short TTL (5 minutes) prevents stale attestations.
+ *
+ * Verification: strip `signature`, canonicalJson the rest, Ed25519 verify
+ * against the relay's public key (from /.well-known/motebit.json).
+ */
+export interface SolvencyProof {
+    /** The agent whose balance is attested. */
+    motebit_id: string;
+    /** Available balance in micro-units (after dispute holds). */
+    balance_available: number;
+    /** The amount the requester asked about. */
+    amount_requested: number;
+    /** Whether balance_available >= amount_requested. */
+    sufficient: boolean;
+    /** Relay that issued this proof. */
+    relay_id: string;
+    /** When the proof was generated (ms since epoch). */
+    attested_at: number;
+    /** When the proof expires (ms since epoch). attested_at + 300_000. */
+    expires_at: number;
+    /** Ed25519 signature over canonical JSON of all other fields. */
+    signature: string;
+}
+/**
+ * Result of policy-based settlement mode evaluation.
+ *
+ * The eligibility check considers: mutual opt-in, trust level,
+ * interaction history, active disputes, and declared settlement capabilities.
+ */
+export interface SettlementEligibility {
+    /** Whether p2p settlement is allowed for this pair + task. */
+    allowed: boolean;
+    /** Selected settlement mode. */
+    mode: SettlementMode;
+    /** Human-readable reason for the decision. */
+    reason: string;
+}
+//# sourceMappingURL=settlement-mode.d.ts.map

package/dist/settlement-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-mode.d.ts","sourceRoot":"","sources":["../src/settlement-mode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,6FAA6F;AAC7F,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,KAAK,CAAC;AAI7C;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,YAAY,EAAE,MAAM,CAAC;CACtB;AAID,uDAAuD;AACvD,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAI1E;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,UAAU,EAAE,OAAO,CAAC;IACpB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,OAAO,EAAE,OAAO,CAAC;IACjB,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/settlement-mode.js

@@ -0,0 +1,8 @@
+/**
+ * Settlement mode types — relay-mediated vs peer-to-peer settlement.
+ *
+ * Permissive floor (Apache-2.0): these types define the interoperable format
+ * for settlement mode selection and payment proof verification.
+ */
+export {};
+//# sourceMappingURL=settlement-mode.js.map

package/dist/settlement-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-mode.js","sourceRoot":"","sources":["../src/settlement-mode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/tool-mode.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Tool cost-tier taxonomy.
+ *
+ * Every `ToolDefinition` declares one of these modes. The motebit's
+ * tool registry sorts the list by tier, so when the model scans its
+ * available tools it sees structured / cheap options first and the
+ * pixel-level fallback last. Cost tiers (hybrid engine doctrine):
+ *
+ *   - **api** — structured, semantically rich, KB round-trip.
+ *     MCP tools, web_search, read_url, memory ops, file I/O, goals.
+ *     The default for any tool that moves text or structured data.
+ *
+ *   - **ax** — accessibility-tree extraction: DOM, AX API, reader
+ *     shapes. Structured but lossy (visual context discarded). Used
+ *     when the target surface exposes a hierarchy the motebit can
+ *     read without screen capture. Today: the web Reader / virtual
+ *     browser path. Tomorrow: macOS AXUIElement traversal for native
+ *     apps.
+ *
+ *   - **pixels** — screen capture + synthetic input. Works on every
+ *     app (legacy software, games, custom UI) but costs ~30k tokens
+ *     per observation even downscaled and crosses a whole-screen
+ *     privacy surface. The universal fallback — reserved for
+ *     surfaces that have no API and no accessibility tree.
+ *
+ * `ToolMode` is a closed string-literal union, following the `SuiteId`
+ * registry pattern. Adding a tier is additive (new entry + new
+ * priority arm in the registry sort). Removing one is a wire-format
+ * break — third parties declare `mode` in their tool definitions and
+ * that claim is stable.
+ */
+export type ToolMode = "api" | "ax" | "pixels";
+/**
+ * All declared modes in priority order (cheapest first). Consumers
+ * that need to rank or enumerate tool modes iterate this array rather
+ * than hard-coding the order.
+ */
+export declare const TOOL_MODES: readonly ["api", "ax", "pixels"];
+/**
+ * Priority index of a declared mode (0 = cheapest). Tools without a
+ * `mode` declaration sort to the end (`TOOL_MODES.length`) — they are
+ * neither rejected nor prioritized, just deprioritized relative to
+ * explicit tiers.
+ */
+export declare function toolModePriority(mode: ToolMode | undefined): number;
+//# sourceMappingURL=tool-mode.d.ts.map

package/dist/tool-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-mode.d.ts","sourceRoot":"","sources":["../src/tool-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,IAAI,GAAG,QAAQ,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,UAAU,kCAAmC,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAInE"}