@usesigil/kit 0.16.0 → 0.17.0

package/dist/protocol-registry/index.js

@@ -1,76 +0,0 @@
-/**
- * `@usesigil/kit/protocol-registry` — Sigil's hand-curated Verified-tier
- * annotation registry.
- *
- * Migrated from `sigil-dashboard/src/lib/protocol-registry/` per the v2.2
- * FE↔BE contract commitment C6. Now consumed by the dashboard, the future
- * React Native mobile app, the future `@usesigil/mcp` server, the emergency
- * CLI — and any third-party partner that needs tier classification without
- * a round-trip to `sigil.trade`.
- *
- * Format choice: JSON, not YAML. Every annotation file declares ONE
- * verified protocol (hand-curated, audited programId + display metadata).
- * New protocols require adding one JSON file + one import line below.
- *
- * ## JSON import attribute
- *
- * Every annotation import uses `with { type: "json" }`. Without it, raw
- * Node ESM loaders (Node ≥ 20.10) reject the module at consume time with
- * `ERR_IMPORT_ATTRIBUTE_MISSING`. Vitest / ts-mocha / Webpack / Vite mask
- * the error via their transform pipelines, so forgetting the attribute
- * passes local tests but ships a broken package — the exact bug caught
- * during sigil-constraints 0.3.0-beta.1 pre-flight.
- *
- * ## What "Verified" means
- *
- * The Sigil team has hand-confirmed the programId is correct AND provides
- * convenience metadata (name, category, notes). The CONSTRAINT PARSER runs
- * the SAME PATH on Verified and Unverified programs — this registry is a
- * convenience + trust-signaling layer, not a safety gate. Non-constrainable
- * is a PARSER verdict (missing IDL / binary-only / dynamic layout), NOT a
- * registry property. See `Sigil.resolveProtocolTier()` in `./protocol-tier.ts`.
- */
-import jupiter from "./annotations/jupiter.json" with { type: "json" };
-import flashTrade from "./annotations/flash-trade.json" with { type: "json" };
-import jupiterLend from "./annotations/jupiter-lend.json" with { type: "json" };
-import jupiterEarn from "./annotations/jupiter-earn.json" with { type: "json" };
-import jupiterBorrow from "./annotations/jupiter-borrow.json" with { type: "json" };
-import drift from "./annotations/drift.json" with { type: "json" };
-import kamino from "./annotations/kamino.json" with { type: "json" };
-/**
- * All registered annotations in display order (most-used first). Consumers
- * should NOT mutate — the array is `readonly` at the type level; the
- * underlying data is also `as const` below to guard against runtime edits.
- */
-export const PROTOCOL_ANNOTATIONS = [
-    jupiter,
-    flashTrade,
-    jupiterLend,
-    jupiterEarn,
-    jupiterBorrow,
-    drift,
-    kamino,
-];
-/**
- * The set of programIds in the Verified tier. Computed once at module
- * load. `VERIFIED_PROGRAMS.has(programId)` is the canonical synchronous
- * check for "does Sigil have hand-curated metadata for this program."
- *
- * Consumers (dashboard `/api/resolve-protocol`, mobile tier UI, MCP)
- * should query this set — NOT filter PROTOCOL_ANNOTATIONS linearly on the
- * hot path. Use `lookupProtocolAnnotation()` when metadata is also needed.
- */
-export const VERIFIED_PROGRAMS = new Set(PROTOCOL_ANNOTATIONS.filter((a) => a.verified).map((a) => a.programId));
-/**
- * Look up a protocol annotation by programId. Returns `null` if the
- * programId is NOT in the Verified registry.
- *
- * Currently an O(n) linear search across 7 entries — fast enough that a
- * `Map` lookup would be premature optimization. If the registry grows
- * past ~50 entries, swap to a `Map<string, ProtocolAnnotation>` built
- * once at module load.
- */
-export function lookupProtocolAnnotation(programId) {
-    return PROTOCOL_ANNOTATIONS.find((a) => a.programId === programId) ?? null;
-}
-//# sourceMappingURL=index.js.map

package/dist/protocol-registry/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocol-registry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,OAAO,MAAM,4BAA4B,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACvE,OAAO,UAAU,MAAM,gCAAgC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9E,OAAO,WAAW,MAAM,iCAAiC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAChF,OAAO,WAAW,MAAM,iCAAiC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAChF,OAAO,aAAa,MAAM,mCAAmC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACpF,OAAO,KAAK,MAAM,0BAA0B,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACnE,OAAO,MAAM,MAAM,2BAA2B,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAqBrE;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAkC;IACjE,OAAO;IACP,UAAU;IACV,WAAW;IACX,WAAW;IACX,aAAa;IACb,KAAK;IACL,MAAM;CACE,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAC3D,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CACvE,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,SAAiB;IAEjB,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,IAAI,IAAI,CAAC;AAC7E,CAAC"}

package/dist/protocol-tier.d.ts

@@ -1,157 +0,0 @@
-/**
- * `@usesigil/kit/protocol-tier` — Three-tier trust-model primitives.
- *
- * Implements the SDK surface for the FE↔BE contract §5c / commitment C6.
- * Every FE "approve protocol" UI queries `resolveProtocolTier(programId)`
- * and renders the matching friction level — Verified (low), Unverified
- * (medium), Non-constrainable (high). This is a FRICTION gradient, not a
- * permission gradient: all three tiers allow agent delegation.
- *
- * ## Why a factory + caller-injected async check
- *
- * The constraint parser lives in `@sigil-trade/constraints` — a PRIVATE
- * GitHub Packages package. `@usesigil/kit` publishes to public npm and
- * therefore CANNOT depend on the private package (installs break without
- * GH-Packages auth). So the async "is this programId constrainable?"
- * check is **caller-injected**:
- *
- *   - Dashboard API route: wires the `@sigil-trade/constraints` IDL fetch
- *     + `parseIdlDirect` pipeline as the callback.
- *   - MCP server: same wiring, server-side.
- *   - Emergency CLI: same wiring.
- *   - Mobile (React Native): registry-only fallback; never fetches IDLs.
- *
- * Consumers import `resolveProtocolTier` from the kit, pass their own
- * `checkConstrainability` implementation, get tier back. Single tier API,
- * many IDL-fetch backends.
- *
- * ## Why not inline the parser here
- *
- * Three reasons:
- *
- *   1. **Firewall invariant.** kit must never import from `@sigil-trade/constraints`.
- *   2. **Runtime separation.** The IDL fetcher uses `node:zlib` — Node-only.
- *      Bundling it in the kit would break browser / React Native consumers.
- *   3. **Caller choice.** A mobile app may skip the fetch entirely and use
- *      registry-only classification; the MCP server may use a caching HTTP
- *      proxy; the dashboard uses the raw constraints package. All valid
- *      backends for the same abstract "can we constrain this?" question.
- *
- * @see FRONTEND-BACKEND-CONTRACT.md §5c — "Three-tier trust model"
- * @see FRONTEND-BACKEND-CONTRACT.md §5a C6 — commitment text
- */
-/**
- * The three TRUST tiers the FE surfaces to users (FE↔BE contract §5c).
- * This is a UX friction signal — all three tiers ALLOW the agent to
- * trade; the difference is the on-chain constraint enforcement layer
- * and the authorization UX.
- *
- * Named `ProtocolTrustTier` (NOT `ProtocolTier`) to avoid collision with
- * the pre-existing `ProtocolTier` enum at `./protocol-resolver.ts` which
- * serves a different purpose (KNOWN / DEFAULT / NOT_ALLOWED — allow-list
- * enforcement, not trust classification). The two coexist.
- */
-export type ProtocolTrustTier = "verified" | "unverified" | "non-constrainable";
-/**
- * Reason codes surfaced when a protocol is NOT constrainable. Stable
- * string keys — FE may match on these for targeted messaging, but the
- * authoritative display path is `detail` (human-safe).
- */
-export type NonConstrainableReason = "missing_idl" | "binary_only" | "dynamic_layout" | "parser_error";
-/**
- * Which source the IDL came from when the constraint parser succeeded.
- * Stable string keys for telemetry / debug panels.
- */
-export type IdlSource = "registry" | "on_chain_metadata" | "solanafm" | "helius";
-/**
- * Result of the async constrainability check. Discriminated union on
- * `constrainable` — compile-time enforces the "reason iff false /
- * idlSource iff true" invariant. TypeScript will reject invalid
- * combinations like `{ constrainable: true, reason: "missing_idl" }`
- * at construction time; before this was a union the invariant was
- * prose-only.
- *
- * Shape mirrors what the dashboard's `/api/resolve-protocol` route
- * returns today; kit codifies the interface so mobile, MCP, and CLI
- * consumers build against the same contract.
- */
-export type ConstrainabilityResult = {
-    /** Parser produced a usable `ParsedInstruction[]`. */
-    readonly constrainable: true;
-    /** Where the IDL was fetched from. Required when constrainable. */
-    readonly idlSource: IdlSource;
-    /** Optional human-safe context line, safe to render in a toast. */
-    readonly detail?: string;
-} | {
-    /** Parser failed — programId is Non-constrainable in the 3-tier model. */
-    readonly constrainable: false;
-    /** Why the parser couldn't constrain. Required when not constrainable. */
-    readonly reason: NonConstrainableReason;
-    /** Optional human-safe context line, safe to render in a toast. */
-    readonly detail?: string;
-};
-/**
- * The signature every caller MUST provide for the async path. Must be
- * async — the kit calls it with `await` and propagates any thrown error
- * WITHOUT silently catching.
- *
- * Contract for implementers:
- *  - Resolve to a `ConstrainabilityResult`; do NOT reject on "this
- *    protocol is non-constrainable" — that's a successful result with
- *    `constrainable: false`.
- *  - REJECT for transport / network / unexpected errors. Those propagate
- *    to the caller of `resolveProtocolTier()`.
- */
-export type CheckConstrainabilityFn = (programId: string) => Promise<ConstrainabilityResult>;
-/**
- * Resolve a programId to its Sigil trust tier.
- *
- * ## Algorithm
- *
- *  1. **Verified short-circuit (sync).** If `VERIFIED_PROGRAMS.has(programId)`
- *     (via `lookupProtocolAnnotation()`), return `"verified"` WITHOUT
- *     calling `checkConstrainability`. Saves the RPC round-trip for every
- *     known-good protocol.
- *  2. **Unverified vs non-constrainable (async).** For unknown programIds,
- *     call `checkConstrainability(programId)`. If `result.constrainable`,
- *     return `"unverified"`. Otherwise return `"non-constrainable"`.
- *
- * ## Error handling
- *
- * If `checkConstrainability` throws/rejects, the rejection propagates to
- * the caller — **NO silent catch**. This matches §7 of the FE↔BE contract
- * (every SDK async method rejects with DxError or subclass; kit never
- * swallows errors).
- *
- * Design note: the sync path (verified lookup) runs BEFORE the async call
- * so a transient RPC failure doesn't block classifying a known-verified
- * programId. This matters for MCP servers operating in degraded-network
- * conditions — Jupiter, Flash Trade, etc. still classify correctly.
- *
- * @param programId Base58 program address.
- * @param checkConstrainability Caller-provided async probe; see
- *   {@link CheckConstrainabilityFn} for the contract.
- *
- * @example Wire the `@sigil-trade/constraints` parser as the backend:
- * ```ts
- * import { resolveProtocolTier } from "@usesigil/kit";
- * import { fetchIdl } from "@sigil-trade/constraints/idl/fetch";
- * import { parseIdlDirect } from "@sigil-trade/constraints";
- *
- * const tier = await resolveProtocolTier(programId, async (id) => {
- *   try {
- *     const idl = await fetchIdl(rpcUrl, id);
- *     parseIdlDirect(idl, id);
- *     return { constrainable: true, idlSource: idl.source };
- *   } catch (e) {
- *     return {
- *       constrainable: false,
- *       reason: classifyParserError(e),
- *       detail: e.message,
- *     };
- *   }
- * });
- * ```
- */
-export declare function resolveProtocolTier(programId: string, checkConstrainability: CheckConstrainabilityFn): Promise<ProtocolTrustTier>;
-//# sourceMappingURL=protocol-tier.d.ts.map

package/dist/protocol-tier.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"protocol-tier.d.ts","sourceRoot":"","sources":["../src/protocol-tier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAIH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAC9B,aAAa,GACb,aAAa,GACb,gBAAgB,GAChB,cAAc,CAAC;AAEnB;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB,UAAU,GACV,mBAAmB,GACnB,UAAU,GACV,QAAQ,CAAC;AAEb;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IACE,sDAAsD;IACtD,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,GACD;IACE,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,uBAAuB,GAAG,CACpC,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,qBAAqB,EAAE,uBAAuB,GAC7C,OAAO,CAAC,iBAAiB,CAAC,CAU5B"}

package/dist/protocol-tier.js

@@ -1,104 +0,0 @@
-/**
- * `@usesigil/kit/protocol-tier` — Three-tier trust-model primitives.
- *
- * Implements the SDK surface for the FE↔BE contract §5c / commitment C6.
- * Every FE "approve protocol" UI queries `resolveProtocolTier(programId)`
- * and renders the matching friction level — Verified (low), Unverified
- * (medium), Non-constrainable (high). This is a FRICTION gradient, not a
- * permission gradient: all three tiers allow agent delegation.
- *
- * ## Why a factory + caller-injected async check
- *
- * The constraint parser lives in `@sigil-trade/constraints` — a PRIVATE
- * GitHub Packages package. `@usesigil/kit` publishes to public npm and
- * therefore CANNOT depend on the private package (installs break without
- * GH-Packages auth). So the async "is this programId constrainable?"
- * check is **caller-injected**:
- *
- *   - Dashboard API route: wires the `@sigil-trade/constraints` IDL fetch
- *     + `parseIdlDirect` pipeline as the callback.
- *   - MCP server: same wiring, server-side.
- *   - Emergency CLI: same wiring.
- *   - Mobile (React Native): registry-only fallback; never fetches IDLs.
- *
- * Consumers import `resolveProtocolTier` from the kit, pass their own
- * `checkConstrainability` implementation, get tier back. Single tier API,
- * many IDL-fetch backends.
- *
- * ## Why not inline the parser here
- *
- * Three reasons:
- *
- *   1. **Firewall invariant.** kit must never import from `@sigil-trade/constraints`.
- *   2. **Runtime separation.** The IDL fetcher uses `node:zlib` — Node-only.
- *      Bundling it in the kit would break browser / React Native consumers.
- *   3. **Caller choice.** A mobile app may skip the fetch entirely and use
- *      registry-only classification; the MCP server may use a caching HTTP
- *      proxy; the dashboard uses the raw constraints package. All valid
- *      backends for the same abstract "can we constrain this?" question.
- *
- * @see FRONTEND-BACKEND-CONTRACT.md §5c — "Three-tier trust model"
- * @see FRONTEND-BACKEND-CONTRACT.md §5a C6 — commitment text
- */
-import { lookupProtocolAnnotation } from "./protocol-registry/index.js";
-/**
- * Resolve a programId to its Sigil trust tier.
- *
- * ## Algorithm
- *
- *  1. **Verified short-circuit (sync).** If `VERIFIED_PROGRAMS.has(programId)`
- *     (via `lookupProtocolAnnotation()`), return `"verified"` WITHOUT
- *     calling `checkConstrainability`. Saves the RPC round-trip for every
- *     known-good protocol.
- *  2. **Unverified vs non-constrainable (async).** For unknown programIds,
- *     call `checkConstrainability(programId)`. If `result.constrainable`,
- *     return `"unverified"`. Otherwise return `"non-constrainable"`.
- *
- * ## Error handling
- *
- * If `checkConstrainability` throws/rejects, the rejection propagates to
- * the caller — **NO silent catch**. This matches §7 of the FE↔BE contract
- * (every SDK async method rejects with DxError or subclass; kit never
- * swallows errors).
- *
- * Design note: the sync path (verified lookup) runs BEFORE the async call
- * so a transient RPC failure doesn't block classifying a known-verified
- * programId. This matters for MCP servers operating in degraded-network
- * conditions — Jupiter, Flash Trade, etc. still classify correctly.
- *
- * @param programId Base58 program address.
- * @param checkConstrainability Caller-provided async probe; see
- *   {@link CheckConstrainabilityFn} for the contract.
- *
- * @example Wire the `@sigil-trade/constraints` parser as the backend:
- * ```ts
- * import { resolveProtocolTier } from "@usesigil/kit";
- * import { fetchIdl } from "@sigil-trade/constraints/idl/fetch";
- * import { parseIdlDirect } from "@sigil-trade/constraints";
- *
- * const tier = await resolveProtocolTier(programId, async (id) => {
- *   try {
- *     const idl = await fetchIdl(rpcUrl, id);
- *     parseIdlDirect(idl, id);
- *     return { constrainable: true, idlSource: idl.source };
- *   } catch (e) {
- *     return {
- *       constrainable: false,
- *       reason: classifyParserError(e),
- *       detail: e.message,
- *     };
- *   }
- * });
- * ```
- */
-export async function resolveProtocolTier(programId, checkConstrainability) {
-    // Sync verified short-circuit.
-    if (lookupProtocolAnnotation(programId) !== null) {
-        return "verified";
-    }
-    // Async fallthrough — caller's check is the single source of truth for
-    // the unverified/non-constrainable split. Any throw propagates.
-    const result = await checkConstrainability(programId);
-    return result.constrainable ? "unverified" : "non-constrainable";
-}
-//# sourceMappingURL=protocol-tier.js.map

package/dist/protocol-tier.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"protocol-tier.js","sourceRoot":"","sources":["../src/protocol-tier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAkFxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAAiB,EACjB,qBAA8C;IAE9C,+BAA+B;IAC/B,IAAI,wBAAwB,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC;QACjD,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,uEAAuE;IACvE,gEAAgE;IAChE,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,SAAS,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,mBAAmB,CAAC;AACnE,CAAC"}