@motebit/protocol 1.2.0 → 2.0.0

package/dist/settlement-asset.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Settlement-asset types — the closed vocabulary of stablecoin assets
+ * the protocol clears settlement in.
+ *
+ * Permissive floor (Apache-2.0). Layer 0. Sub-phase A of the
+ * asset-pluggability commitment named in
+ * [`docs/doctrine/off-ramp-as-user-action.md`](../../../docs/doctrine/off-ramp-as-user-action.md)
+ * § "Asset pluggability":
+ *
+ *   > "settlement is asset-pluggable. USDC is the bootstrap stablecoin.
+ *   > A `SettlementAsset` closed union (`"USDC"` only at land) with a
+ *   > bespoke coverage test should ship as sub-phase A of this arc — a
+ *   > typed vocabulary consumers can reference, promoted to the 8th
+ *   > registered registry per `registry-pattern-canonical.md` when a
+ *   > second asset (PYUSD, USDP, etc.) arrives as a real consumer
+ *   > (sub-phase B)."
+ *
+ * Sub-phase A intentionally stops short of the full eight-artifact
+ * registered-registry set: the per-registry coverage gate, perturbation
+ * probe, drift-defenses inventory entry, and `REGISTERED_REGISTRIES`
+ * append are deferred until a second asset materializes as a real
+ * consumer. With a single literal there is no cross-implementation
+ * drift surface to defend against yet; the four criteria in
+ * [`docs/doctrine/registry-pattern-canonical.md`](../../../docs/doctrine/registry-pattern-canonical.md)
+ * § "When to add a registry to `REGISTERED_REGISTRIES`" require "real
+ * or anticipated drift," which this sub-phase does not meet. What it
+ * does meet: interop law (the field is signed on `SovereignRail` and
+ * read by independent verifiers), multi-consumer (rail + relay book-
+ * keeping + agent discovery), wire-format presence (`SovereignRail.asset`
+ * is the protocol-shaped boundary). Three of four criteria → bespoke
+ * coverage; the fourth criterion gates the registry promotion.
+ *
+ * **The registry membership IS the protocol-vs-product wall** (per the
+ * off-ramp doctrine memo's "asset-pluggability" section): if `"MOTE"`
+ * is ever added to `ALL_SETTLEMENT_ASSETS`, it's protocol; if it
+ * isn't, it's a motebit-cloud product overlay that converts to/from a
+ * protocol-level asset at its boundaries. A future MOTE stablecoin is
+ * **not** an architectural endpoint — it's a candidate motebit-cloud
+ * convenience product, evaluated against asset-pluggability when its
+ * compliance, market, and economic case can stand on its own
+ * (deferred per the `feedback_no_mote_stablecoin` memory).
+ *
+ * Semantic note — `SettlementAsset` is distinct from "currency".
+ * `BatchWithdrawalItem.currency`, `DepositResult.currency`,
+ * `WithdrawalResult.currency`, `CapabilityPrice.currency`, and
+ * `BudgetAllocation.currency` retain `string` typing because they
+ * mix fiat ("USD" via Stripe) and stablecoin ("USDC" via x402) across
+ * guest-rail kinds. Only fields whose semantic is unambiguously a
+ * settlement asset — `SovereignRail.asset` is the canonical site —
+ * tighten to this closed union. The fiat/stablecoin distinction lives
+ * at the rail-kind boundary, not in this vocabulary.
+ */
+/**
+ * The closed set of stablecoin assets the protocol clears settlement in.
+ *
+ * Single member at land — USDC is the bootstrap stablecoin. Additions
+ * are intentional protocol-level work (sub-phase B): new union member +
+ * `ALL_SETTLEMENT_ASSETS` entry + sibling-rail support + registry-
+ * pattern-canonical promotion to the 8th registered registry.
+ *
+ * Why a closed union, not `string`: a third-party motebit implementation
+ * receiving a `SovereignRail.asset` value of `"USDT"` or `"DAI"` from a
+ * peer should fail-closed (unknown asset) rather than silently continue.
+ * The vocabulary IS the interop boundary.
+ */
+export type SettlementAsset = "USDC";
+/**
+ * Canonical iteration order over `SettlementAsset`, frozen. The single
+ * source of truth for "every settlement asset" — exhaustive switches,
+ * bookkeeping enumerations, and the future per-registry coverage gate
+ * (sub-phase B) enumerate through this array.
+ *
+ * Same shape as `ALL_SUITE_IDS`, `ALL_TOKEN_AUDIENCES`,
+ * `ALL_CONTENT_ARTIFACT_TYPES`, `ALL_TASK_SHAPES`,
+ * `ALL_SENSITIVITY_LEVELS`, `ALL_EVENT_TYPES`, `ALL_SETTLEMENT_MODES`.
+ * The array shape is established before the registry is registered so
+ * that the sub-phase B promotion is a one-line `REGISTERED_REGISTRIES`
+ * append, not a refactor.
+ */
+export declare const ALL_SETTLEMENT_ASSETS: readonly SettlementAsset[];
+/**
+ * Type guard — narrows `unknown` to `SettlementAsset`. Consumers that
+ * derive settlement-asset values from external sources (peer rail
+ * announcements, signed `SovereignRail` declarations, discovery
+ * responses) call this before dispatching so an unchecked cast is a
+ * fail-open path the type system can't catch.
+ *
+ * Same shape as `isSuiteId`, `isTokenAudience`, `isContentArtifactType`,
+ * `isTaskShape`, `isSensitivityLevel`, `isEventType`, `isSettlementMode`.
+ */
+export declare function isSettlementAsset(value: unknown): value is SettlementAsset;
+//# sourceMappingURL=settlement-asset.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-asset.d.ts","sourceRoot":"","sources":["../src/settlement-asset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC;AAErC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,eAAe,EAErC,CAAC;AAExB;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E"}

package/dist/settlement-asset.js

@@ -0,0 +1,82 @@
+/**
+ * Settlement-asset types — the closed vocabulary of stablecoin assets
+ * the protocol clears settlement in.
+ *
+ * Permissive floor (Apache-2.0). Layer 0. Sub-phase A of the
+ * asset-pluggability commitment named in
+ * [`docs/doctrine/off-ramp-as-user-action.md`](../../../docs/doctrine/off-ramp-as-user-action.md)
+ * § "Asset pluggability":
+ *
+ *   > "settlement is asset-pluggable. USDC is the bootstrap stablecoin.
+ *   > A `SettlementAsset` closed union (`"USDC"` only at land) with a
+ *   > bespoke coverage test should ship as sub-phase A of this arc — a
+ *   > typed vocabulary consumers can reference, promoted to the 8th
+ *   > registered registry per `registry-pattern-canonical.md` when a
+ *   > second asset (PYUSD, USDP, etc.) arrives as a real consumer
+ *   > (sub-phase B)."
+ *
+ * Sub-phase A intentionally stops short of the full eight-artifact
+ * registered-registry set: the per-registry coverage gate, perturbation
+ * probe, drift-defenses inventory entry, and `REGISTERED_REGISTRIES`
+ * append are deferred until a second asset materializes as a real
+ * consumer. With a single literal there is no cross-implementation
+ * drift surface to defend against yet; the four criteria in
+ * [`docs/doctrine/registry-pattern-canonical.md`](../../../docs/doctrine/registry-pattern-canonical.md)
+ * § "When to add a registry to `REGISTERED_REGISTRIES`" require "real
+ * or anticipated drift," which this sub-phase does not meet. What it
+ * does meet: interop law (the field is signed on `SovereignRail` and
+ * read by independent verifiers), multi-consumer (rail + relay book-
+ * keeping + agent discovery), wire-format presence (`SovereignRail.asset`
+ * is the protocol-shaped boundary). Three of four criteria → bespoke
+ * coverage; the fourth criterion gates the registry promotion.
+ *
+ * **The registry membership IS the protocol-vs-product wall** (per the
+ * off-ramp doctrine memo's "asset-pluggability" section): if `"MOTE"`
+ * is ever added to `ALL_SETTLEMENT_ASSETS`, it's protocol; if it
+ * isn't, it's a motebit-cloud product overlay that converts to/from a
+ * protocol-level asset at its boundaries. A future MOTE stablecoin is
+ * **not** an architectural endpoint — it's a candidate motebit-cloud
+ * convenience product, evaluated against asset-pluggability when its
+ * compliance, market, and economic case can stand on its own
+ * (deferred per the `feedback_no_mote_stablecoin` memory).
+ *
+ * Semantic note — `SettlementAsset` is distinct from "currency".
+ * `BatchWithdrawalItem.currency`, `DepositResult.currency`,
+ * `WithdrawalResult.currency`, `CapabilityPrice.currency`, and
+ * `BudgetAllocation.currency` retain `string` typing because they
+ * mix fiat ("USD" via Stripe) and stablecoin ("USDC" via x402) across
+ * guest-rail kinds. Only fields whose semantic is unambiguously a
+ * settlement asset — `SovereignRail.asset` is the canonical site —
+ * tighten to this closed union. The fiat/stablecoin distinction lives
+ * at the rail-kind boundary, not in this vocabulary.
+ */
+/**
+ * Canonical iteration order over `SettlementAsset`, frozen. The single
+ * source of truth for "every settlement asset" — exhaustive switches,
+ * bookkeeping enumerations, and the future per-registry coverage gate
+ * (sub-phase B) enumerate through this array.
+ *
+ * Same shape as `ALL_SUITE_IDS`, `ALL_TOKEN_AUDIENCES`,
+ * `ALL_CONTENT_ARTIFACT_TYPES`, `ALL_TASK_SHAPES`,
+ * `ALL_SENSITIVITY_LEVELS`, `ALL_EVENT_TYPES`, `ALL_SETTLEMENT_MODES`.
+ * The array shape is established before the registry is registered so
+ * that the sub-phase B promotion is a one-line `REGISTERED_REGISTRIES`
+ * append, not a refactor.
+ */
+export const ALL_SETTLEMENT_ASSETS = Object.freeze([
+    "USDC",
+]);
+/**
+ * Type guard — narrows `unknown` to `SettlementAsset`. Consumers that
+ * derive settlement-asset values from external sources (peer rail
+ * announcements, signed `SovereignRail` declarations, discovery
+ * responses) call this before dispatching so an unchecked cast is a
+ * fail-open path the type system can't catch.
+ *
+ * Same shape as `isSuiteId`, `isTokenAudience`, `isContentArtifactType`,
+ * `isTaskShape`, `isSensitivityLevel`, `isEventType`, `isSettlementMode`.
+ */
+export function isSettlementAsset(value) {
+    return typeof value === "string" && ALL_SETTLEMENT_ASSETS.includes(value);
+}
+//# sourceMappingURL=settlement-asset.js.map

package/dist/settlement-asset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-asset.js","sourceRoot":"","sources":["../src/settlement-asset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAmBH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAA+B,MAAM,CAAC,MAAM,CAAC;IAC7E,MAAM;CACc,CAAC,CAAC;AAExB;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,qBAA2C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnG,CAAC"}

package/dist/settlement-mode.d.ts

@@ -7,8 +7,102 @@
 /** 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.
+ * The narrow subset of `SettlementMode` that the relay is permitted to
+ * write for **new** worker-settlement rows after Arc 3 of the off-ramp
+ * arc. Reads accept the full `SettlementMode` union (legacy `"relay"`
+ * rows must remain readable for audit, verifier, and federation
+ * compat); writes are structurally restricted to `"p2p"`.
+ *
+ * This is the asymmetric-typing enforcement shape from
+ * [`architecture_disjointness_by_construction`](../../../../.claude/projects/-Users-daniel-src-motebit/memory/architecture_disjointness_by_construction.md)
+ * — the surface stays open for reads but closed for writes; legacy
+ * data remains verifiable but no new code can re-introduce the
+ * relay-custody worker-settlement path. The doctrine: *the relay does
+ * not accept delegator-paid funds on behalf of a worker*. The type:
+ * `WritableSettlementMode = Extract<SettlementMode, "p2p">`. The
+ * structural enforcement: a compile error at every site that tries to
+ * write `"relay"` for a worker settlement.
+ *
+ * Composes with the prior arcs' Layer 1 enforcement shapes:
+ *   - Surface deletion (`BridgeSettlementRail.withdraw`) — Arc 1
+ *   - Marker interface (`WithdrawableGuestRail`) — Arc 1
+ *   - Asymmetric typing (this) — Arc 3
+ *
+ * Doctrine: [`docs/doctrine/off-ramp-as-user-action.md`](../../../docs/doctrine/off-ramp-as-user-action.md) § "Arc 3 close".
+ */
+export type WritableSettlementMode = Extract<SettlementMode, "p2p">;
+/**
+ * Canonical iteration order over `SettlementMode`, frozen. The single
+ * source of truth for "every settlement mode" — drift gates, exhaustive
+ * switches, settlement-eligibility evaluators, and the protocol's
+ * registry-coverage gate (`check-settlement-mode-canonical`) all
+ * enumerate through this array.
+ *
+ * Promoted to a registered registry per
+ * [`docs/doctrine/registry-pattern-canonical.md`](../../../docs/doctrine/registry-pattern-canonical.md)
+ * on 2026-05-15 — the seventh instance after `SuiteId`, `TokenAudience`,
+ * `ContentArtifactType`, `TaskShape`, `SensitivityLevel`, and
+ * `EventType`. The four criteria are met: interop law (cross-
+ * implementation agreement required for settlement to clear), multi-
+ * consumer (relay, agents, discovery, settlement-rails, eligibility
+ * evaluator), wire-format presence (`SettlementEligibility.mode`,
+ * `AgentDiscovery.settlement_modes[]`), anticipated drift (the closed
+ * union will grow when a third mode lands — escrow / hybrid / batched —
+ * and silently breaking peers without the structural lock would
+ * fail interoperability).
+ *
+ * Same shape as `ALL_SUITE_IDS`, `ALL_TOKEN_AUDIENCES`,
+ * `ALL_CONTENT_ARTIFACT_TYPES`, `ALL_TASK_SHAPES`,
+ * `ALL_SENSITIVITY_LEVELS`, `ALL_EVENT_TYPES`. Adding a settlement
+ * mode is intentional protocol-level work: new union entry + new
+ * entry here + gate reference update + spec update if wire-format-
+ * relevant.
+ */
+export declare const ALL_SETTLEMENT_MODES: readonly SettlementMode[];
+/**
+ * Type guard — narrows `unknown` to `SettlementMode`. Consumers that
+ * derive settlement-mode values from external sources (peer
+ * negotiation, discovery responses, relay routing decisions) call
+ * this before dispatching so an unchecked cast is a fail-open path
+ * the type system can't catch.
+ *
+ * Same shape as `isSuiteId`, `isTokenAudience`,
+ * `isContentArtifactType`, `isTaskShape`, `isSensitivityLevel`,
+ * `isEventType`.
+ */
+export declare function isSettlementMode(value: unknown): value is SettlementMode;
+/**
+ * Proof of direct onchain payment for a P2P-settled task. After Arc 2
+ * of the off-ramp arc, the delegator's single signed Solana
+ * transaction composes TWO atomic SPL Transfer instructions:
+ *
+ *   1. **Worker leg** — delegator → worker, amount = `amount_micro`
+ *      (the worker's listing unit_cost, what they earn net).
+ *   2. **Fee leg** — delegator → relay treasury, amount =
+ *      `fee_amount_micro` (the platform fee, derived from the gross
+ *      via `platform_fee_rate`).
+ *
+ * Both legs land atomically (either the whole tx succeeds or it
+ * doesn't); the `p2p-verifier` walks the on-chain `transfers[]` to
+ * confirm both legs match the declared addresses + amounts. The relay
+ * treasury address is the relay's identity-derived Solana wallet
+ * (`deriveSolanaAddress(relay.publicKey)`) — same address that funds
+ * `SolanaMemoSubmitter` for anchoring and that `OperatorSolanaTransfer`
+ * uses for Path 0 withdrawals. Delegators discover it via the published
+ * relay public key on `/.well-known/motebit.json` or
+ * `/.well-known/motebit-transparency.json`.
+ *
+ * Doctrine: `docs/doctrine/off-ramp-as-user-action.md` — Arc 2 closes
+ * the sibling-doc contradiction between the top-level `CLAUDE.md`
+ * Economic Loop "5% applies through both lanes" claim and
+ * `services/relay/CLAUDE.md` rule 8's pre-Arc-2 "Fee: zero on P2P"
+ * policy. The fee is now structurally present on every P2P settlement
+ * as a direct delegator→treasury leg.
+ *
+ * **Breaking change from pre-Arc-2 P2pPaymentProof shape**: the new
+ * `fee_to_address` + `fee_amount_micro` fields are required. The
+ * worker-leg fields (`to_address`, `amount_micro`) keep their existing
+ * semantics — they describe only the worker leg, not the gross.
  */
 export interface P2pPaymentProof {
     /** Onchain transaction signature (Solana base58, 87-88 chars). */
@@ -19,8 +113,27 @@ export interface P2pPaymentProof {
     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. */
+    /**
+     * Worker leg amount in micro-units (USDC 6 decimals). Equals the
+     * worker's listing unit_cost — what the worker earns net.
+     */
     amount_micro: number;
+    /**
+     * Relay treasury Solana address (base58). Derivable from the relay's
+     * published Ed25519 public key via `deriveSolanaAddress(publicKey)`
+     * (see `@motebit/wallet-solana`). Delegators MUST fetch the relay's
+     * public key from a verified source (transparency declaration or
+     * pinned config) — passing a wrong address sends the fee leg to a
+     * non-relay address and verification fails-closed.
+     */
+    fee_to_address: string;
+    /**
+     * Fee leg amount in micro-units. The platform fee, computed as
+     * `gross - amount_micro` where `gross = amount_micro / (1 - platformFeeRate)`.
+     * The verifier validates this matches the relay's recorded
+     * `platform_fee_rate` against the declared `amount_micro`.
+     */
+    fee_amount_micro: number;
 }
 /** Verification status of an onchain payment proof. */
 export type PaymentVerificationStatus = "pending" | "verified" | "failed";
@@ -52,17 +165,35 @@ export interface SolvencyProof {
     signature: string;
 }
 /**
- * Result of policy-based settlement mode evaluation.
+ * Result of policy-based settlement-eligibility evaluation. After Arc 3
+ * of the off-ramp arc, the eligibility check no longer routes between
+ * relay-custody and P2P — P2P is the only worker-settlement path. The
+ * gate now answers a binary question: "can this delegator-worker pair
+ * transact at all?"
+ *
+ * Disjunctive eligibility per [`docs/doctrine/off-ramp-as-user-action.md`](../../../docs/doctrine/off-ramp-as-user-action.md):
+ *   - **Established-pair branch**: trust ≥ 0.6 AND interactions ≥ 5
+ *     AND no_active_disputes AND worker_has_settlement_address.
+ *   - **New-pair branch**: `delegator_acknowledges_no_history_risk`
+ *     AND no_active_disputes AND worker_not_blocked AND
+ *     worker_has_settlement_address.
+ *
+ * The disjunctive type encodes "allowed implies p2p" structurally —
+ * the `mode` field uses `WritableSettlementMode` so consumers that
+ * destructure `{ mode }` on an allowed result get the narrow type;
+ * the disallowed case has no `mode` field because there's no
+ * fallback rail to route to.
  *
- * The eligibility check considers: mutual opt-in, trust level,
- * interaction history, active disputes, and declared settlement capabilities.
+ * Composes with [[trust_as_economic_membrane]] — the established-pair
+ * branch is the trust-as-fast-path; the new-pair branch is the
+ * cold-start unlock with explicit consent.
  */
-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. */
+export type SettlementEligibility = {
+    allowed: true;
+    mode: WritableSettlementMode;
     reason: string;
-}
+} | {
+    allowed: false;
+    reason: string;
+};
 //# sourceMappingURL=settlement-mode.d.ts.map

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

@@ -1 +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"}
+{"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;AAE7C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,cAAc,EAGpC,CAAC;AAEvB;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,sBAAsB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/settlement-mode.js

@@ -4,5 +4,49 @@
  * Permissive floor (Apache-2.0): these types define the interoperable format
  * for settlement mode selection and payment proof verification.
  */
-export {};
+/**
+ * Canonical iteration order over `SettlementMode`, frozen. The single
+ * source of truth for "every settlement mode" — drift gates, exhaustive
+ * switches, settlement-eligibility evaluators, and the protocol's
+ * registry-coverage gate (`check-settlement-mode-canonical`) all
+ * enumerate through this array.
+ *
+ * Promoted to a registered registry per
+ * [`docs/doctrine/registry-pattern-canonical.md`](../../../docs/doctrine/registry-pattern-canonical.md)
+ * on 2026-05-15 — the seventh instance after `SuiteId`, `TokenAudience`,
+ * `ContentArtifactType`, `TaskShape`, `SensitivityLevel`, and
+ * `EventType`. The four criteria are met: interop law (cross-
+ * implementation agreement required for settlement to clear), multi-
+ * consumer (relay, agents, discovery, settlement-rails, eligibility
+ * evaluator), wire-format presence (`SettlementEligibility.mode`,
+ * `AgentDiscovery.settlement_modes[]`), anticipated drift (the closed
+ * union will grow when a third mode lands — escrow / hybrid / batched —
+ * and silently breaking peers without the structural lock would
+ * fail interoperability).
+ *
+ * Same shape as `ALL_SUITE_IDS`, `ALL_TOKEN_AUDIENCES`,
+ * `ALL_CONTENT_ARTIFACT_TYPES`, `ALL_TASK_SHAPES`,
+ * `ALL_SENSITIVITY_LEVELS`, `ALL_EVENT_TYPES`. Adding a settlement
+ * mode is intentional protocol-level work: new union entry + new
+ * entry here + gate reference update + spec update if wire-format-
+ * relevant.
+ */
+export const ALL_SETTLEMENT_MODES = Object.freeze([
+    "relay",
+    "p2p",
+]);
+/**
+ * Type guard — narrows `unknown` to `SettlementMode`. Consumers that
+ * derive settlement-mode values from external sources (peer
+ * negotiation, discovery responses, relay routing decisions) call
+ * this before dispatching so an unchecked cast is a fail-open path
+ * the type system can't catch.
+ *
+ * Same shape as `isSuiteId`, `isTokenAudience`,
+ * `isContentArtifactType`, `isTaskShape`, `isSensitivityLevel`,
+ * `isEventType`.
+ */
+export function isSettlementMode(value) {
+    return typeof value === "string" && ALL_SETTLEMENT_MODES.includes(value);
+}
 //# sourceMappingURL=settlement-mode.js.map

package/dist/settlement-mode.js.map

@@ -1 +1 @@
-{"version":3,"file":"settlement-mode.js","sourceRoot":"","sources":["../src/settlement-mode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"settlement-mode.js","sourceRoot":"","sources":["../src/settlement-mode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiCH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA8B,MAAM,CAAC,MAAM,CAAC;IAC3E,OAAO;IACP,KAAK;CACc,CAAC,CAAC;AAEvB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,oBAA0C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAClG,CAAC"}

package/dist/transparency.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Operator-transparency declaration — the trust-anchor primitive.
+ *
+ * The motebit relay publishes a signed declaration of its observability
+ * posture at `/.well-known/motebit-transparency.json`. The declaration
+ * commits the operator to one Ed25519 public key (`relay_public_key`)
+ * and to the operator-defined `content` payload. Verifiers pin that
+ * key as the trust anchor for every other relay-asserted artifact:
+ * content-artifact manifests on state-export endpoints, settlement
+ * receipts the operator counter-signs, federation handshakes.
+ *
+ * This module exports the binding wire types per
+ * `spec/relay-transparency-v1.md` (2b-i, the trust-anchor primitive).
+ * The operator-comparison vocabulary (Stage 2b-ii — retention/processor
+ * field standardization) is deferred until a second motebit-compatible
+ * operator forces field standardization; the `content` field stays
+ * operator-defined here and verifiers MUST NOT reject declarations on
+ * unknown `content` fields.
+ *
+ * Doctrine: `docs/doctrine/operator-transparency.md`,
+ * `docs/doctrine/nist-alignment.md` §8 "savant gap closure",
+ * `docs/doctrine/self-attesting-system.md`.
+ *
+ * Permissive floor (Apache-2.0), type-only, zero runtime deps.
+ */
+import type { SuiteId } from "./crypto-suite.js";
+/**
+ * The pinned cryptosuite for transparency declarations. JCS
+ * canonicalization (RFC 8785) + Ed25519 + hex signature encoding.
+ * Matches the identity-file + credential-anchor + content-artifact
+ * family. See `SUITE_REGISTRY` in `./crypto-suite.ts`.
+ */
+export declare const TRANSPARENCY_SUITE: SuiteId;
+/**
+ * Canonical memo prefix the relay emits when anchoring the
+ * declaration hash to Solana via the Memo program. Full memo shape:
+ * `motebit:transparency:v1:{hash_hex}`. Verifiers scan for this
+ * prefix at the relay's pinned anchor address. See
+ * `spec/relay-transparency-v1.md` §5.2.
+ */
+export declare const TRANSPARENCY_ANCHOR_MEMO_PREFIX: "motebit:transparency:v1:";
+/**
+ * Current spec identifier. Bumps require explicit doctrine alignment
+ * + a new wire-format spec doc — the verifier MUST reject declarations
+ * with unrecognized `spec` values.
+ */
+export declare const TRANSPARENCY_SPEC_ID: "motebit-transparency/draft-2026-04-14";
+/**
+ * Operator-transparency declaration — the trust-anchor envelope.
+ *
+ * Wire format (foundation law) — see `spec/relay-transparency-v1.md` §3.1
+ * for the binding shape. Field names, types, and the canonical-JSON
+ * ordering of the signed payload are protocol law. The `content` field
+ * is operator-extensible — the protocol commits to the envelope, not
+ * to the posture vocabulary inside `content`.
+ *
+ * Hash derivation: `sha256(utf8(canonicalJson({spec, declared_at,
+ * relay_id, relay_public_key, content})))` — the post-sign fields
+ * `hash`, `suite`, `signature` are NOT included in the canonical bytes.
+ * Two implementations that hash the same payload MUST produce the same
+ * hex string byte-for-byte. Per `spec/relay-transparency-v1.md` §4.
+ */
+export interface SignedTransparencyDeclaration {
+    /** Spec identifier — e.g. `"motebit-transparency/draft-2026-04-14"`. Bump on breaking schema changes. */
+    readonly spec: string;
+    /** Epoch milliseconds when the declaration was minted. */
+    readonly declared_at: number;
+    /** Relay's identity — same MotebitId space as agent identities. */
+    readonly relay_id: string;
+    /** Hex-encoded Ed25519 public key (32 bytes / 64 chars). */
+    readonly relay_public_key: string;
+    /**
+     * Operator-defined posture payload — retention, processors,
+     * jurisdiction, honest gaps. Opaque to the protocol. Verifiers MUST
+     * NOT reject declarations on unknown `content` fields. Cross-operator
+     * comparison vocabulary is deferred to Stage 2b-ii.
+     */
+    readonly content: unknown;
+    /** Hex-encoded SHA-256 of the canonical-JSON of the signed payload. */
+    readonly hash: string;
+    /** Cryptosuite identifier — `motebit-jcs-ed25519-hex-v1` today. */
+    readonly suite: SuiteId;
+    /** Hex-encoded Ed25519 signature over the canonical-JSON of the signed payload. */
+    readonly signature: string;
+}
+/**
+ * The five-field signed payload — what `hash` and `signature` cover.
+ * Exposed as a type so producers can construct + canonicalize the
+ * exact bytes the verifier checks against. The post-sign fields
+ * (`hash`, `suite`, `signature`) are appended AFTER signing and are
+ * NOT part of this payload.
+ */
+export type TransparencySignedPayload = Pick<SignedTransparencyDeclaration, "spec" | "declared_at" | "relay_id" | "relay_public_key" | "content">;
+/**
+ * Onchain anchor record — the verifier's view of a memo found at the
+ * relay's pinned anchor address. Returned by
+ * `@motebit/state-export-client::lookupTransparencyAnchor` on success.
+ * Per `spec/relay-transparency-v1.md` §5.
+ */
+export interface TransparencyAnchorRecord {
+    /** Solana transaction signature containing the anchor memo. */
+    readonly tx_hash: string;
+    /** Anchored hash (the declaration's `hash` field at time of anchoring), lowercase hex. */
+    readonly anchored_hash_hex: string;
+    /** Solana address (base58 pubkey) where the anchor lives. Pinned out-of-band by the verifier. */
+    readonly anchor_address: string;
+}
+/**
+ * Type guard — narrows `unknown` to `SignedTransparencyDeclaration`.
+ * Structural shape only; does NOT verify the signature, anchor, or
+ * succession chain. Verifiers call this before parsing then proceed
+ * through the verification algorithm in `spec/relay-transparency-v1.md`
+ * §4.1.
+ */
+export declare function isSignedTransparencyDeclaration(value: unknown): value is SignedTransparencyDeclaration;
+//# sourceMappingURL=transparency.d.ts.map

package/dist/transparency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transparency.d.ts","sourceRoot":"","sources":["../src/transparency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAsC,CAAC;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,EAAG,0BAAmC,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAG,uCAAgD,CAAC;AAErF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,6BAA6B;IAC5C,yGAAyG;IACzG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,6BAA6B,EAC7B,MAAM,GAAG,aAAa,GAAG,UAAU,GAAG,kBAAkB,GAAG,SAAS,CACrE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,iGAAiG;IACjG,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,6BAA6B,CAaxC"}

package/dist/transparency.js

@@ -0,0 +1,67 @@
+/**
+ * Operator-transparency declaration — the trust-anchor primitive.
+ *
+ * The motebit relay publishes a signed declaration of its observability
+ * posture at `/.well-known/motebit-transparency.json`. The declaration
+ * commits the operator to one Ed25519 public key (`relay_public_key`)
+ * and to the operator-defined `content` payload. Verifiers pin that
+ * key as the trust anchor for every other relay-asserted artifact:
+ * content-artifact manifests on state-export endpoints, settlement
+ * receipts the operator counter-signs, federation handshakes.
+ *
+ * This module exports the binding wire types per
+ * `spec/relay-transparency-v1.md` (2b-i, the trust-anchor primitive).
+ * The operator-comparison vocabulary (Stage 2b-ii — retention/processor
+ * field standardization) is deferred until a second motebit-compatible
+ * operator forces field standardization; the `content` field stays
+ * operator-defined here and verifiers MUST NOT reject declarations on
+ * unknown `content` fields.
+ *
+ * Doctrine: `docs/doctrine/operator-transparency.md`,
+ * `docs/doctrine/nist-alignment.md` §8 "savant gap closure",
+ * `docs/doctrine/self-attesting-system.md`.
+ *
+ * Permissive floor (Apache-2.0), type-only, zero runtime deps.
+ */
+/**
+ * The pinned cryptosuite for transparency declarations. JCS
+ * canonicalization (RFC 8785) + Ed25519 + hex signature encoding.
+ * Matches the identity-file + credential-anchor + content-artifact
+ * family. See `SUITE_REGISTRY` in `./crypto-suite.ts`.
+ */
+export const TRANSPARENCY_SUITE = "motebit-jcs-ed25519-hex-v1";
+/**
+ * Canonical memo prefix the relay emits when anchoring the
+ * declaration hash to Solana via the Memo program. Full memo shape:
+ * `motebit:transparency:v1:{hash_hex}`. Verifiers scan for this
+ * prefix at the relay's pinned anchor address. See
+ * `spec/relay-transparency-v1.md` §5.2.
+ */
+export const TRANSPARENCY_ANCHOR_MEMO_PREFIX = "motebit:transparency:v1:";
+/**
+ * Current spec identifier. Bumps require explicit doctrine alignment
+ * + a new wire-format spec doc — the verifier MUST reject declarations
+ * with unrecognized `spec` values.
+ */
+export const TRANSPARENCY_SPEC_ID = "motebit-transparency/draft-2026-04-14";
+/**
+ * Type guard — narrows `unknown` to `SignedTransparencyDeclaration`.
+ * Structural shape only; does NOT verify the signature, anchor, or
+ * succession chain. Verifiers call this before parsing then proceed
+ * through the verification algorithm in `spec/relay-transparency-v1.md`
+ * §4.1.
+ */
+export function isSignedTransparencyDeclaration(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const o = value;
+    return (typeof o.spec === "string" &&
+        typeof o.declared_at === "number" &&
+        typeof o.relay_id === "string" &&
+        typeof o.relay_public_key === "string" &&
+        "content" in o &&
+        typeof o.hash === "string" &&
+        typeof o.suite === "string" &&
+        typeof o.signature === "string");
+}
+//# sourceMappingURL=transparency.js.map

package/dist/transparency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transparency.js","sourceRoot":"","sources":["../src/transparency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAY,4BAA4B,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,0BAAmC,CAAC;AAEnF;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,uCAAgD,CAAC;AAoErF;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B,CAC7C,KAAc;IAEd,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;QACjC,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;QAC9B,OAAO,CAAC,CAAC,gBAAgB,KAAK,QAAQ;QACtC,SAAS,IAAI,CAAC;QACd,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAC3B,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAChC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motebit/protocol",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Motebit protocol — identity, receipts, credentials, delegation, settlement, and trust algebra for sovereign AI agents. Types, semirings, routing primitives. Apache-2.0, zero dependencies.",
   "type": "module",
   "main": "./dist/index.js",