@usesigil/kit 0.10.0 → 0.11.0

package/dist/presets.js.map

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

package/dist/react/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @usesigil/kit/react — React hooks for Sigil vault state.
+ *
+ * Four TanStack Query wrappers around `SigilVault` methods:
+ *   - `useVaultBudget(vault)` — useQuery wrapping vault.budget()
+ *   - `useVaultState(vault)` — useQuery wrapping the agent-side
+ *     state-resolver primitive
+ *   - `useOverview(vault, opts?)` — useQuery wrapping vault.overview()
+ *     (owner-only; throws if called on an agent-only handle)
+ *   - `useExecute(vault)` — useMutation wrapping vault.execute()
+ *
+ * Peer dependencies are **optional**: React and `@tanstack/react-query`
+ * are declared as peer deps in `package.json` under `peerDependenciesMeta`
+ * with `optional: true`. Consumers who don't use React never install them
+ * and never see a warning. Consumers who do import this subpath must
+ * install both.
+ *
+ * Query keys: every query key is namespaced under `"sigil"` so a
+ * consumer's existing TanStack cache never collides with SDK keys.
+ * Keys are derived from `vault.address` so multi-vault apps share keys
+ * per-vault without manual namespacing.
+ *
+ * Cache invalidation: the SDK does NOT call `queryClient.invalidateQueries`
+ * on its own. After an `execute()` mutation, the consumer decides which
+ * queries to refetch — typically `useExecute` is wrapped with a custom
+ * `onSuccess` that invalidates the specific vault keys.
+ */
+import type { SigilVault } from "../vault-handle.js";
+import type { GetOverviewOptions } from "../dashboard/types.js";
+/**
+ * Build a stable query key for a vault-bound query. Namespaced under
+ * `"sigil"` so the keys never collide with consumer app keys.
+ */
+export declare function sigilQueryKey(vault: SigilVault, sub: "state" | "budget" | "overview"): readonly unknown[];
+/**
+ * `useVaultBudget(vault)` — read the vault's current rolling-24h
+ * budget via TanStack Query. Cheap call — re-runs as often as the
+ * query's `staleTime` allows (TQ default: 0ms).
+ *
+ * Returns the raw TQ `UseQueryResult<ResolvedBudget>` so consumers
+ * can read `.data`, `.isLoading`, `.error`, etc.
+ */
+export declare function useVaultBudget(vault: SigilVault): any;
+/**
+ * `useVaultState(vault)` — alias for `useVaultBudget` today; kept as
+ * a separate hook so Sprint 3 can swap in a richer state resolver
+ * without changing the consumer call shape.
+ */
+export declare function useVaultState(vault: SigilVault): any;
+/**
+ * `useOverview(vault, opts?)` — read the full `OverviewData` via
+ * `OwnerClient.getOverview()`. Requires an owner signer on the
+ * handle — the query throws `SIGIL_ERROR__SDK__OWNER_REQUIRED` when
+ * called on an agent-only handle. TanStack surfaces the throw via
+ * `result.error`.
+ */
+export declare function useOverview(vault: SigilVault, opts?: GetOverviewOptions): any;
+/**
+ * `useExecute(vault)` — TanStack mutation wrapping `vault.execute`.
+ * Usage:
+ *   const { mutate, mutateAsync, isPending } = useExecute(vault);
+ *   mutate({ instructions: [...], opts: { tokenMint, amount, ... } });
+ *
+ * Consumer is responsible for `queryClient.invalidateQueries` on
+ * success — the SDK does not force a refetch of any specific keys,
+ * so the consumer's cache hygiene stays under their control.
+ */
+export declare function useExecute(vault: SigilVault): any;
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AA6BH,OAAO,KAAK,EAAE,UAAU,EAA4B,MAAM,oBAAoB,CAAC;AAI/E,OAAO,KAAK,EAAgB,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAI9E;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,GACnC,SAAS,OAAO,EAAE,CAEpB;AAID;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,CAMrD;AAED;;;;GAIG;AAEH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,CAMpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,UAAU,EACjB,IAAI,CAAC,EAAE,kBAAkB,GAExB,GAAG,CAML;AAED;;;;;;;;;GASG;AAEH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,CAUjD"}

package/dist/react/index.js

@@ -0,0 +1,118 @@
+/**
+ * @usesigil/kit/react — React hooks for Sigil vault state.
+ *
+ * Four TanStack Query wrappers around `SigilVault` methods:
+ *   - `useVaultBudget(vault)` — useQuery wrapping vault.budget()
+ *   - `useVaultState(vault)` — useQuery wrapping the agent-side
+ *     state-resolver primitive
+ *   - `useOverview(vault, opts?)` — useQuery wrapping vault.overview()
+ *     (owner-only; throws if called on an agent-only handle)
+ *   - `useExecute(vault)` — useMutation wrapping vault.execute()
+ *
+ * Peer dependencies are **optional**: React and `@tanstack/react-query`
+ * are declared as peer deps in `package.json` under `peerDependenciesMeta`
+ * with `optional: true`. Consumers who don't use React never install them
+ * and never see a warning. Consumers who do import this subpath must
+ * install both.
+ *
+ * Query keys: every query key is namespaced under `"sigil"` so a
+ * consumer's existing TanStack cache never collides with SDK keys.
+ * Keys are derived from `vault.address` so multi-vault apps share keys
+ * per-vault without manual namespacing.
+ *
+ * Cache invalidation: the SDK does NOT call `queryClient.invalidateQueries`
+ * on its own. After an `execute()` mutation, the consumer decides which
+ * queries to refetch — typically `useExecute` is wrapped with a custom
+ * `onSuccess` that invalidates the specific vault keys.
+ */
+// ─── Peer-dep shim ──────────────────────────────────────────────────────────
+//
+// We can't `import { useQuery }` statically because doing so would make
+// `@tanstack/react-query` a hard dependency at module-load time — a
+// consumer who uses `@usesigil/kit` without touching `/react` would
+// see a resolution error on every kit import. Instead, this subpath
+// imports TanStack lazily via `require()` at the use site, inside the
+// hook body. Each hook calls a one-time dynamic import that throws a
+// clear error if the peer dep isn't installed.
+function requireTanstack() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require("@tanstack/react-query");
+    }
+    catch (err) {
+        throw new Error("@usesigil/kit/react requires `@tanstack/react-query` as a peer dependency. " +
+            "Install it via `npm install @tanstack/react-query react` and retry.");
+    }
+}
+// ─── Query-key helpers ──────────────────────────────────────────────────────
+/**
+ * Build a stable query key for a vault-bound query. Namespaced under
+ * `"sigil"` so the keys never collide with consumer app keys.
+ */
+export function sigilQueryKey(vault, sub) {
+    return ["sigil", vault.address, sub];
+}
+// ─── Hooks ──────────────────────────────────────────────────────────────────
+/**
+ * `useVaultBudget(vault)` — read the vault's current rolling-24h
+ * budget via TanStack Query. Cheap call — re-runs as often as the
+ * query's `staleTime` allows (TQ default: 0ms).
+ *
+ * Returns the raw TQ `UseQueryResult<ResolvedBudget>` so consumers
+ * can read `.data`, `.isLoading`, `.error`, etc.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useVaultBudget(vault) {
+    const { useQuery } = requireTanstack();
+    return useQuery({
+        queryKey: sigilQueryKey(vault, "budget"),
+        queryFn: () => vault.budget(),
+    });
+}
+/**
+ * `useVaultState(vault)` — alias for `useVaultBudget` today; kept as
+ * a separate hook so Sprint 3 can swap in a richer state resolver
+ * without changing the consumer call shape.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useVaultState(vault) {
+    const { useQuery } = requireTanstack();
+    return useQuery({
+        queryKey: sigilQueryKey(vault, "state"),
+        queryFn: () => vault.budget(),
+    });
+}
+/**
+ * `useOverview(vault, opts?)` — read the full `OverviewData` via
+ * `OwnerClient.getOverview()`. Requires an owner signer on the
+ * handle — the query throws `SIGIL_ERROR__SDK__OWNER_REQUIRED` when
+ * called on an agent-only handle. TanStack surfaces the throw via
+ * `result.error`.
+ */
+export function useOverview(vault, opts) {
+    const { useQuery } = requireTanstack();
+    return useQuery({
+        queryKey: [...sigilQueryKey(vault, "overview"), opts ?? null],
+        queryFn: () => vault.overview(opts),
+    });
+}
+/**
+ * `useExecute(vault)` — TanStack mutation wrapping `vault.execute`.
+ * Usage:
+ *   const { mutate, mutateAsync, isPending } = useExecute(vault);
+ *   mutate({ instructions: [...], opts: { tokenMint, amount, ... } });
+ *
+ * Consumer is responsible for `queryClient.invalidateQueries` on
+ * success — the SDK does not force a refetch of any specific keys,
+ * so the consumer's cache hygiene stays under their control.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useExecute(vault) {
+    const { useMutation } = requireTanstack();
+    return useMutation({
+        mutationFn: async (args) => {
+            return vault.execute(args.instructions, args.opts);
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,+EAA+E;AAC/E,EAAE;AACF,wEAAwE;AACxE,oEAAoE;AACpE,oEAAoE;AACpE,oEAAoE;AACpE,sEAAsE;AACtE,qEAAqE;AACrE,+CAA+C;AAE/C,SAAS,eAAe;IACtB,IAAI,CAAC;QACH,iEAAiE;QACjE,OAAO,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,6EAA6E;YAC3E,qEAAqE,CACxE,CAAC;IACJ,CAAC;AACH,CAAC;AAUD,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAiB,EACjB,GAAoC;IAEpC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,CAAU,CAAC;AAChD,CAAC;AAED,+EAA+E;AAE/E;;;;;;;GAOG;AACH,8DAA8D;AAC9D,MAAM,UAAU,cAAc,CAAC,KAAiB;IAC9C,MAAM,EAAE,QAAQ,EAAE,GAAG,eAAe,EAAE,CAAC;IACvC,OAAO,QAAQ,CAAC;QACd,QAAQ,EAAE,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC;QACxC,OAAO,EAAE,GAA4B,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE;KACvD,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,MAAM,EAAE,QAAQ,EAAE,GAAG,eAAe,EAAE,CAAC;IACvC,OAAO,QAAQ,CAAC;QACd,QAAQ,EAAE,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC;QACvC,OAAO,EAAE,GAA4B,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE;KACvD,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,KAAiB,EACjB,IAAyB;IAGzB,MAAM,EAAE,QAAQ,EAAE,GAAG,eAAe,EAAE,CAAC;IACvC,OAAO,QAAQ,CAAC;QACd,QAAQ,EAAE,CAAC,GAAG,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,IAAI,IAAI,IAAI,CAAU;QACtE,OAAO,EAAE,GAA0B,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;KAC3D,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAC,KAAiB;IAC1C,MAAM,EAAE,WAAW,EAAE,GAAG,eAAe,EAAE,CAAC;IAC1C,OAAO,WAAW,CAAC;QACjB,UAAU,EAAE,KAAK,EAAE,IAGlB,EAA0B,EAAE;YAC3B,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACrD,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/seal.d.ts

@@ -79,6 +79,18 @@ export interface SealParams {
     maxCacheAgeMs?: number;
     /** Additional agent ATA → vault ATA replacements for multi-token DeFi routes. */
     additionalAtaReplacements?: Map<Address, Address>;
+    /**
+     * Sprint 2 (B3): optional lifecycle hooks. Observe-only except
+     * `onBeforeBuild` which may return `{ skipSeal: true, reason }` to
+     * cleanly abort before any RPC. Hook throws are caught and logged
+     * via `getSigilModuleLogger().warn` — they do NOT propagate.
+     */
+    hooks?: import("./hooks.js").SealHooks;
+    /**
+     * Sprint 2 (B3): stable correlation ID. When omitted, `seal()`
+     * generates one via `newCorrelationId()` at the top of the call.
+     */
+    correlationId?: string;
 }
 export interface SealResult {
     ok: true;
@@ -156,6 +168,19 @@ export interface SigilClientConfig {
      * injected logger so the bypass is observable in audit trails.
      */
     skipGenesisAssertion?: boolean;
+    /**
+     * Sprint 2 (B3): client-level seal hooks. Fire on every `seal()` +
+     * `executeAndConfirm()` call. Compose with per-call hooks
+     * (`ClientSealOpts.hooks`) via `composeHooks(clientHooks, perCall)`
+     * — client hooks run first.
+     */
+    hooks?: import("./hooks.js").SealHooks;
+    /**
+     * Sprint 2 (B4): policy plugins. Run in registration order inside
+     * `seal()` pre-flight after `resolveVaultState`; first rejection
+     * throws `SigilSdkDomainError(SIGIL_ERROR__SDK__PLUGIN_REJECTED)`.
+     */
+    plugins?: readonly import("./plugin.js").SigilPolicyPlugin[];
 }
 /**
  * Options for `client.seal()`.
@@ -176,6 +201,16 @@ export interface ClientSealOpts {
     cachedState?: ResolvedVaultState;
     maxCacheAgeMs?: number;
     additionalAtaReplacements?: Map<Address, Address>;
+    /**
+     * Sprint 2 (B3): per-call hooks. Compose with client-level hooks
+     * (`SigilClientConfig.hooks`) — client hooks run first, then per-call.
+     */
+    hooks?: import("./hooks.js").SealHooks;
+    /**
+     * Sprint 2 (B3): stable correlation ID for trace correlation.
+     * Defaults to a fresh `newCorrelationId()` if omitted.
+     */
+    correlationId?: string;
 }
 export interface ExecuteResult {
     signature: string;
@@ -243,23 +278,6 @@ export declare const SOLANA_DEVNET_GENESIS_HASH = "EtWTRABZaYq6iMfeYKouRu166VU2x
 export declare const SOLANA_MAINNET_GENESIS_HASH = "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d";
 /** @internal — exposed for test resets only. */
 export declare function _resetGenesisHashCache(): void;
-/**
- * @deprecated Use `createSigilClient(config)` or the async factory
- * `SigilClient.create(config)` instead. This class will be removed at
- * v1.0. The factory returns the same API surface as a plain object with
- * closure-bound methods — no `this` binding issues, tree-shakeable, and
- * aligned with the viem/Kit functional pattern.
- *
- * Migration:
- * ```ts
- * // Before:
- * const client = new SigilClient({ rpc, vault, agent, network });
- * // After (factory):
- * const client = createSigilClient({ rpc, vault, agent, network });
- * // After (async with genesis assertion):
- * const client = await SigilClient.create({ rpc, vault, agent, network });
- * ```
- */
 export declare class SigilClient {
     private readonly blockhashCacheInstance;
     private readonly altCacheInstance;
@@ -269,23 +287,24 @@ export declare class SigilClient {
     readonly agent: TransactionSigner;
     readonly network: "devnet" | "mainnet";
     /**
-     * @deprecated Use the async factory {@link SigilClient.create} instead.
-     * The sync constructor skips the genesis-hash assertion and cannot
-     * verify the RPC is on the cluster the SDK was configured for. Migrate
-     * by awaiting `await SigilClient.create(config)` — signature is
-     * otherwise identical.
+     * Private constructor — Sprint 2 carryover.
+     *
+     * Sprint 1 deprecated `new SigilClient(config)` in favor of the
+     * async factory `SigilClient.create(config)` which runs the
+     * genesis-hash assertion. Sprint 2 completes the migration by
+     * making the constructor `private`: external callers now get a TS
+     * compile error, and the runtime guard below throws on JS consumers
+     * that cast through `any` to bypass the compile-time check.
      *
-     * Sync construction remains functional for back-compat and for tests
-     * using stubbed RPCs that don't honor `getGenesisHash()`. When called
-     * directly (not via `.create()`), emits a warning via the injected
-     * logger so the bypass is observable.
+     * The class remains exported so:
+     *   - `SigilClient.create()` static factory still works.
+     *   - `instanceof SigilClient` checks in tests still resolve.
+     *   - The type `SigilClient` is still a first-class position.
      *
-     * @param _skipDeprecationWarning — internal flag used by
-     *   `SigilClient.create()` to suppress the warning on the async path
-     *   (the async factory IS the recommended path; warning there would
-     *   be misleading log spam). Not part of the public API.
+     * @internal — construction token is a module-private symbol only
+     *   `SigilClient.create()` holds a reference to.
      */
-    constructor(config: SigilClientConfig, _skipDeprecationWarning?: boolean);
+    private constructor();
     /**
      * Async factory — constructs a `SigilClient` and asserts the RPC's
      * genesis hash matches the configured `network`. Preferred entry

package/dist/seal.d.ts.map

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

package/dist/seal.js

@@ -15,6 +15,11 @@
  */
 import { AccountRole } from "./kit-adapter.js";
 import { getSigilModuleLogger, setSigilModuleLogger } from "./logger.js";
+import { newCorrelationId, invokeHook, composeHooks, } from "./hooks.js";
+// SigilPolicyPlugin type-ref is declared inline on SigilClientConfig via
+// `import("./plugin.js").SigilPolicyPlugin` so no top-level import is
+// needed. Plugin runner invocation (runPlugins() call after state resolve)
+// is a follow-up commit; the hooks integration above proves the plumbing.
 import { VaultStatus } from "./generated/types/vaultStatus.js";
 import { getValidateAndAuthorizeInstructionAsync } from "./generated/instructions/validateAndAuthorize.js";
 import { getFinalizeSessionInstructionAsync } from "./generated/instructions/finalizeSession.js";
@@ -34,7 +39,7 @@ import { parseTokenBalance } from "./simulation.js";
 import { createVault, } from "./create-vault.js";
 import { SigilSdkDomainError } from "./errors/sdk.js";
 import { SigilRpcError } from "./errors/rpc.js";
-import { SIGIL_ERROR__SDK__VAULT_INACTIVE, SIGIL_ERROR__SDK__AGENT_NOT_REGISTERED, SIGIL_ERROR__SDK__AGENT_PAUSED, SIGIL_ERROR__SDK__AGENT_ZERO_CAPABILITY, SIGIL_ERROR__SDK__INVALID_AMOUNT, SIGIL_ERROR__SDK__INVALID_CONFIG, SIGIL_ERROR__SDK__INVALID_NETWORK, SIGIL_ERROR__SDK__INVALID_PARAMS, SIGIL_ERROR__SDK__SPL_TOKEN_OP_BLOCKED, SIGIL_ERROR__SDK__PROTOCOL_NOT_ALLOWED, SIGIL_ERROR__SDK__PROTOCOL_NOT_TARGETED, SIGIL_ERROR__SDK__INSTRUCTION_COUNT, SIGIL_ERROR__SDK__CAP_EXCEEDED, SIGIL_ERROR__SDK__ATA_NON_CANONICAL, SIGIL_ERROR__RPC__TX_FAILED, SIGIL_ERROR__RPC__TX_TOO_LARGE, } from "./errors/codes.js";
+import { SIGIL_ERROR__SDK__VAULT_INACTIVE, SIGIL_ERROR__SDK__AGENT_NOT_REGISTERED, SIGIL_ERROR__SDK__AGENT_PAUSED, SIGIL_ERROR__SDK__AGENT_ZERO_CAPABILITY, SIGIL_ERROR__SDK__INVALID_AMOUNT, SIGIL_ERROR__SDK__INVALID_CONFIG, SIGIL_ERROR__SDK__INVALID_NETWORK, SIGIL_ERROR__SDK__INVALID_PARAMS, SIGIL_ERROR__SDK__SPL_TOKEN_OP_BLOCKED, SIGIL_ERROR__SDK__PROTOCOL_NOT_ALLOWED, SIGIL_ERROR__SDK__PROTOCOL_NOT_TARGETED, SIGIL_ERROR__SDK__INSTRUCTION_COUNT, SIGIL_ERROR__SDK__CAP_EXCEEDED, SIGIL_ERROR__SDK__ATA_NON_CANONICAL, SIGIL_ERROR__SDK__HOOK_ABORTED, SIGIL_ERROR__RPC__TX_FAILED, SIGIL_ERROR__RPC__TX_TOO_LARGE, } from "./errors/codes.js";
 // ─── Well-known program addresses to strip ──────────────────────────────────
 // PR 3.B F036: use canonical constants from types.ts instead of local dupes.
 import { TOKEN_PROGRAM_ADDRESS as TOKEN_PROGRAM, TOKEN_2022_PROGRAM_ADDRESS as TOKEN_2022_PROGRAM, COMPUTE_BUDGET_PROGRAM_ADDRESS as COMPUTE_BUDGET_PROGRAM, SYSTEM_PROGRAM_ADDRESS as SYSTEM_PROGRAM, } from "./types.js";
@@ -86,6 +91,35 @@ export async function seal(params) {
     const warnings = [];
     const net = normalizeNetwork(params.network);
     validateNetwork(net);
+    // ─── Sprint 2 B3: build hook context + invoke onBeforeBuild ──────────────
+    //
+    // Context is populated ONCE at the top of seal() so every subsequent hook
+    // invocation references the same `correlationId`. onBeforeBuild is the
+    // only hook that may abort: returning `{ skipSeal: true, reason }` throws
+    // SigilSdkDomainError(HOOK_ABORTED) before any RPC round-trip.
+    const _hookCtx = {
+        vault: params.vault,
+        agent: params.agent.address,
+        tokenMint: params.tokenMint,
+        amount: params.amount,
+        network: params.network,
+        correlationId: params.correlationId ?? newCorrelationId(),
+    };
+    if (params.hooks?.onBeforeBuild) {
+        const abortResult = await invokeHook(params.hooks, "onBeforeBuild", _hookCtx, params);
+        if (abortResult &&
+            typeof abortResult === "object" &&
+            "skipSeal" in abortResult &&
+            abortResult.skipSeal === true) {
+            throw new SigilSdkDomainError(SIGIL_ERROR__SDK__HOOK_ABORTED, `seal() aborted by onBeforeBuild hook: ${String(abortResult.reason)}`, {
+                context: {
+                    hook: "onBeforeBuild",
+                    reason: String(abortResult.reason),
+                    correlationId: _hookCtx.correlationId,
+                },
+            });
+        }
+    }
     // Step 1: Resolve vault state (with stale cache detection)
     let state;
     if (params.cachedState) {
@@ -531,16 +565,42 @@ export function createSigilClient(config) {
         network,
         seal: clientSeal,
         async executeAndConfirm(instructions, opts) {
+            // Sprint 2 B3: compose client-level and per-call hooks. Client hooks
+            // run first at every stage (onBeforeBuild → ... → onFinalize), then
+            // per-call hooks. composeHooks handles the conditional-merge when
+            // either side is absent.
+            const composedHooks = composeHooks(config.hooks, opts.hooks);
+            const correlationId = opts.correlationId ?? newCorrelationId();
+            const hookCtx = {
+                vault,
+                agent: agent.address,
+                tokenMint: opts.tokenMint,
+                amount: opts.amount,
+                network,
+                correlationId,
+            };
             try {
                 // Calls the closure-captured clientSeal — no `this` dependency.
                 // Safe to destructure: `const { executeAndConfirm } = client`.
-                const result = await clientSeal(instructions, opts);
+                const result = await clientSeal(instructions, {
+                    ...opts,
+                    hooks: composedHooks,
+                    correlationId,
+                });
                 const encoded = await signAndEncode(agent, result.transaction);
                 const signature = await sendAndConfirmTransaction(rpc, encoded, opts.confirmOptions);
+                // Sprint 2 B3: onAfterSend fires with the signature as soon as
+                // the RPC resolves. onFinalize fires last on the success path.
+                await invokeHook(composedHooks, "onAfterSend", hookCtx, signature);
+                await invokeHook(composedHooks, "onFinalize", hookCtx, { signature });
                 return { signature, sealResult: result };
             }
             catch (err) {
                 const sdkError = toSigilAgentError(err);
+                // Sprint 2 B3: onError fires in every failure path before the
+                // existing onErrorCallback telemetry hook. Error is always
+                // rethrown after both fire.
+                await invokeHook(composedHooks, "onError", hookCtx, err instanceof Error ? err : new Error(String(err)));
                 onErrorCallback?.(sdkError, {
                     action: opts.amount > 0n ? "spending" : "non-spending",
                     tokenMint: opts.tokenMint,
@@ -691,6 +751,13 @@ async function assertGenesisHash(rpc, network) {
  * const client = await SigilClient.create({ rpc, vault, agent, network });
  * ```
  */
+/**
+ * Module-private construction token for SigilClient. `SigilClient.create()`
+ * is the only holder — direct `new SigilClient(config)` calls from outside
+ * the class body cannot obtain this symbol and fail the runtime guard in
+ * the private constructor.
+ */
+const CLIENT_CONSTRUCT_TOKEN = Symbol("SigilClient.construct");
 export class SigilClient {
     blockhashCacheInstance;
     altCacheInstance;
@@ -700,23 +767,33 @@ export class SigilClient {
     agent;
     network;
     /**
-     * @deprecated Use the async factory {@link SigilClient.create} instead.
-     * The sync constructor skips the genesis-hash assertion and cannot
-     * verify the RPC is on the cluster the SDK was configured for. Migrate
-     * by awaiting `await SigilClient.create(config)` — signature is
-     * otherwise identical.
+     * Private constructor — Sprint 2 carryover.
+     *
+     * Sprint 1 deprecated `new SigilClient(config)` in favor of the
+     * async factory `SigilClient.create(config)` which runs the
+     * genesis-hash assertion. Sprint 2 completes the migration by
+     * making the constructor `private`: external callers now get a TS
+     * compile error, and the runtime guard below throws on JS consumers
+     * that cast through `any` to bypass the compile-time check.
      *
-     * Sync construction remains functional for back-compat and for tests
-     * using stubbed RPCs that don't honor `getGenesisHash()`. When called
-     * directly (not via `.create()`), emits a warning via the injected
-     * logger so the bypass is observable.
+     * The class remains exported so:
+     *   - `SigilClient.create()` static factory still works.
+     *   - `instanceof SigilClient` checks in tests still resolve.
+     *   - The type `SigilClient` is still a first-class position.
      *
-     * @param _skipDeprecationWarning — internal flag used by
-     *   `SigilClient.create()` to suppress the warning on the async path
-     *   (the async factory IS the recommended path; warning there would
-     *   be misleading log spam). Not part of the public API.
+     * @internal — construction token is a module-private symbol only
+     *   `SigilClient.create()` holds a reference to.
      */
-    constructor(config, _skipDeprecationWarning = false) {
+    constructor(config, _constructToken = Symbol.for("SigilClient.forbid")) {
+        // Runtime guard: anyone who reaches this constructor without the
+        // exact module-private token (i.e., via `any`-cast or JS bypass)
+        // gets thrown out. `.create()` passes CLIENT_CONSTRUCT_TOKEN.
+        if (_constructToken !== CLIENT_CONSTRUCT_TOKEN) {
+            throw new SigilSdkDomainError(SIGIL_ERROR__SDK__INVALID_CONFIG, "SigilClient: direct construction is not allowed. " +
+                "Use `await SigilClient.create(config)` — which also runs the " +
+                "genesis-hash assertion — or `createSigilClient(config)` for " +
+                "the factory variant.", { context: { field: "constructor", expected: "SigilClient.create" } });
+        }
         if (!config.rpc)
             throw new SigilSdkDomainError(SIGIL_ERROR__SDK__INVALID_CONFIG, "SigilClientConfig.rpc is required", { context: { field: "rpc", expected: "Rpc<SolanaRpcApi>" } });
         if (!config.vault)
@@ -738,14 +815,6 @@ export class SigilClient {
         if (config.logger) {
             setSigilModuleLogger(config.logger);
         }
-        // Emit deprecation warning only when called directly (not via
-        // the `.create()` async factory, which already performs the
-        // genesis assertion the deprecation warning warns about).
-        if (!_skipDeprecationWarning) {
-            getSigilModuleLogger().warn("[SigilClient] sync constructor bypasses genesis-hash assertion. " +
-                "Use `await SigilClient.create(config)` in production to verify the " +
-                "RPC matches the configured network.");
-        }
     }
     /**
      * Async factory — constructs a `SigilClient` and asserts the RPC's
@@ -783,11 +852,11 @@ export class SigilClient {
             // with a misconfigured RPC is ever returned to the caller.
             await assertGenesisHash(config.rpc, config.network);
         }
-        // Pass `_skipDeprecationWarning: true` so the sync constructor
-        // doesn't emit its "sync bypasses genesis assertion" warning — we
-        // just performed the assertion above, so the warning would be
-        // misleading log spam on every .create() call (C-review C4).
-        return new SigilClient(config, true);
+        // Sprint 2 carryover: pass the module-private construction token
+        // so the private-ctor runtime guard accepts the call. External
+        // callers cannot obtain this symbol and are rejected — forcing
+        // them through `.create()` which runs the genesis-hash assertion.
+        return new SigilClient(config, CLIENT_CONSTRUCT_TOKEN);
     }
     /**
      * Seal DeFi instructions with Sigil security.