@oxdeai/sdk 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ This project follows Semantic Versioning.
 
 ---
 
+## [1.3.0] - 2026-03-08
+
+### Added
+
+- Stable public guard API for callback-boundary enforcement (`createGuard`).
+- Guard-focused test coverage for allow/deny execution behavior and authorization enforcement.
+
+### Changed
+
+- SDK integration documentation updated for the v1.3 adoption layer.
+- Protocol-stack version alignment with:
+  - `@oxdeai/core@1.3.0`
+  - `@oxdeai/conformance@1.3.0`
+
+### Notes
+
+- `@oxdeai/cli` remains on a separate tooling version line.
+- No intentional protocol semantic break from `1.2.x`.
+
+---
+
 ## [1.2.0] - 2026-03-08
 
 ### Added

package/README.md

@@ -2,18 +2,47 @@
 
 Developer-facing integration layer on top of `@oxdeai/core`.
 
+## Status
+
+Current protocol stack line: **v1.3.x** (`@oxdeai/core`, `@oxdeai/sdk`, `@oxdeai/conformance`).
+
+The SDK is an integration surface and does not redefine protocol semantics.
+
 ## What It Adds
 
 - Intent/state builder helpers
 - Typed client wrapper for common flow: evaluate + persist + verify
+- Public guard API for callback-boundary enforcement (`createGuard`)
 - Runtime adapters (in-memory and file-based)
 
+## Guard API (v1.3 adoption layer)
+
+The SDK exposes a framework-agnostic guard boundary:
+
+```ts
+const guard = createGuard({ engine, stateAdapter, auditAdapter, clock });
+const result = await guard(intent, async ({ authorization }) => {
+  return executeTool(authorization);
+});
+```
+
+The callback runs only when OxDeAI returns `ALLOW` and authorization enforcement passes.
+On `DENY` (or failed auth verification), the callback is not executed.
+
+This keeps PDP/PEP separation explicit:
+
+- PDP: `PolicyEngine.evaluatePure(...)` decides
+- PEP: guard callback boundary enforces execute-or-refuse
+
+OxDeAI sits below agent frameworks (OpenAI tools, LangGraph, others) as the deterministic authorization boundary.
+
 ## Quick Example
 
 ```ts
 import { PolicyEngine } from "@oxdeai/core";
 import {
   OxDeAIClient,
+  createGuard,
   buildState,
   buildIntent,
   InMemoryStateAdapter,
@@ -54,6 +83,18 @@ const intent = buildIntent({
 });
 
 const result = await client.evaluateAndCommit(intent);
+
+const guard = createGuard({
+  engine,
+  stateAdapter,
+  auditAdapter,
+  clock: { now: () => 1770000000 }
+});
+
+await guard(intent, async () => {
+  // execute side effect only when ALLOW + auth checks pass
+  return { ok: true };
+});
 ```
 
 ## Main Exports

package/dist/guard.d.ts

@@ -0,0 +1,50 @@
+import type { Intent, PolicyEngine, State, Authorization } from "@oxdeai/core";
+import type { AuditAdapter, ClockAdapter, MaybePromise, StateAdapter, IntentBuilderInput } from "./types.js";
+export type GuardDecision = {
+    decision: "ALLOW";
+    reasons: [];
+    authorization: Authorization;
+} | {
+    decision: "DENY";
+    reasons: string[];
+};
+export type GuardAllowResult<T> = {
+    output: GuardDecision & {
+        decision: "ALLOW";
+        reasons: [];
+        authorization: Authorization;
+    };
+    intent: Intent;
+    state: State;
+    auditEvents: unknown[];
+    executed: true;
+    executionResult: T;
+};
+export type GuardDenyResult = {
+    output: GuardDecision & {
+        decision: "DENY";
+        reasons: string[];
+    };
+    intent: Intent;
+    state: State;
+    auditEvents: unknown[];
+    executed: false;
+};
+export type GuardResult<T> = GuardAllowResult<T> | GuardDenyResult;
+export type GuardInputIntent = Intent | IntentBuilderInput;
+export type GuardOptions = {
+    engine: PolicyEngine;
+    stateAdapter: StateAdapter;
+    auditAdapter?: AuditAdapter;
+    clock?: ClockAdapter;
+    mode?: "fail-fast" | "collect-all";
+    verifyAuthorization?: boolean;
+};
+type GuardExecuteContext = {
+    intent: Intent;
+    authorization: Authorization;
+    state: State;
+};
+export type GuardFn = <T>(input: GuardInputIntent, execute: (ctx: GuardExecuteContext) => MaybePromise<T>) => Promise<GuardResult<T>>;
+export declare function createGuard(opts: GuardOptions): GuardFn;
+export {};

package/dist/guard.js

@@ -0,0 +1,77 @@
+import { buildIntent } from "./builders.js";
+function collectNewEvents(engine, cursor) {
+    const all = engine.audit.snapshot();
+    return { nextCursor: all.length, events: all.slice(cursor) };
+}
+function isIntent(value) {
+    return (typeof value.intent_id === "string" &&
+        typeof value.agent_id === "string" &&
+        typeof value.action_type === "string" &&
+        typeof value.signature === "string");
+}
+export function createGuard(opts) {
+    const clock = opts.clock ?? { now: () => Math.floor(Date.now() / 1000) };
+    let auditCursor = 0;
+    return async function guard(input, execute) {
+        const state = await opts.stateAdapter.load();
+        const intent = isIntent(input)
+            ? {
+                ...input,
+                timestamp: input.timestamp === 0 ? clock.now() : input.timestamp,
+            }
+            : buildIntent({
+                ...input,
+                timestamp: input.timestamp ?? clock.now(),
+            });
+        const out = opts.engine.evaluatePure(intent, state, { mode: opts.mode ?? "fail-fast" });
+        const emitted = collectNewEvents(opts.engine, auditCursor);
+        auditCursor = emitted.nextCursor;
+        if (opts.auditAdapter)
+            await opts.auditAdapter.append(emitted.events);
+        if (out.decision === "DENY") {
+            return {
+                output: { decision: "DENY", reasons: out.reasons },
+                intent,
+                state,
+                auditEvents: emitted.events,
+                executed: false,
+            };
+        }
+        if (!out.authorization || !out.nextState) {
+            return {
+                output: { decision: "DENY", reasons: ["PEP_INVARIANT_VIOLATION"] },
+                intent,
+                state,
+                auditEvents: emitted.events,
+                executed: false,
+            };
+        }
+        if (opts.verifyAuthorization !== false) {
+            const authCheck = opts.engine.verifyAuthorization(intent, out.authorization, out.nextState, intent.timestamp);
+            if (!authCheck.valid) {
+                return {
+                    output: { decision: "DENY", reasons: [`AUTH_INVALID:${authCheck.reason ?? "unknown"}`] },
+                    intent,
+                    state,
+                    auditEvents: emitted.events,
+                    executed: false,
+                };
+            }
+        }
+        const executionResult = await execute({
+            intent,
+            authorization: out.authorization,
+            state: out.nextState,
+        });
+        await opts.stateAdapter.save(out.nextState);
+        return {
+            output: { decision: "ALLOW", reasons: [], authorization: out.authorization },
+            intent,
+            state: out.nextState,
+            auditEvents: emitted.events,
+            executed: true,
+            executionResult,
+        };
+    };
+}
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

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

package/dist/guard.test.d.ts

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

package/dist/guard.test.js

@@ -0,0 +1,139 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { PolicyEngine } from "@oxdeai/core";
+import { InMemoryAuditAdapter, InMemoryStateAdapter } from "./adapters.js";
+import { buildIntent, buildState } from "./builders.js";
+import { createGuard } from "./guard.js";
+function makeEngine() {
+    return new PolicyEngine({
+        policy_version: "v1",
+        engine_secret: "dev-secret",
+        authorization_ttl_seconds: 60,
+        authorization_issuer: "issuer-A",
+        authorization_audience: "rp-A",
+        policyId: "a".repeat(64),
+    });
+}
+function makeAllowState() {
+    return buildState({
+        policy_version: "v1",
+        agent_id: "agent-1",
+        allow_action_types: ["PROVISION"],
+        allow_targets: ["us-east-1"],
+        budget_limit: 1000n,
+        spent_in_period: 0n,
+        max_amount_per_action: 500n,
+    });
+}
+test("guard executes callback on ALLOW", async () => {
+    const engine = makeEngine();
+    const stateAdapter = new InMemoryStateAdapter(makeAllowState());
+    const auditAdapter = new InMemoryAuditAdapter();
+    const guard = createGuard({
+        engine,
+        stateAdapter,
+        auditAdapter,
+        clock: { now: () => 1_770_000_000 },
+    });
+    let called = 0;
+    const result = await guard(buildIntent({
+        intent_id: "intent-allow-1",
+        agent_id: "agent-1",
+        action_type: "PROVISION",
+        amount: 500n,
+        target: "us-east-1",
+        nonce: 1n,
+    }), async () => {
+        called++;
+        return "ok";
+    });
+    assert.equal(called, 1);
+    assert.equal(result.executed, true);
+    assert.equal(result.output.decision, "ALLOW");
+    if (result.executed)
+        assert.equal(result.executionResult, "ok");
+    assert.ok(auditAdapter.snapshot().length > 0);
+});
+test("guard does not execute callback on DENY", async () => {
+    const engine = makeEngine();
+    const stateAdapter = new InMemoryStateAdapter(makeAllowState());
+    const guard = createGuard({
+        engine,
+        stateAdapter,
+        clock: { now: () => 1_770_000_000 },
+    });
+    let called = 0;
+    const result = await guard(buildIntent({
+        intent_id: "intent-deny-1",
+        agent_id: "agent-1",
+        action_type: "PROVISION",
+        amount: 900n,
+        target: "us-east-1",
+        nonce: 2n,
+    }), async () => {
+        called++;
+        return "should-not-run";
+    });
+    assert.equal(called, 0);
+    assert.equal(result.executed, false);
+    assert.equal(result.output.decision, "DENY");
+});
+test("guard enforces authorization verification at callback boundary", async () => {
+    const engine = makeEngine();
+    const original = engine.verifyAuthorization.bind(engine);
+    engine.verifyAuthorization = () => ({ valid: false, reason: "forced-test-failure" });
+    const stateAdapter = new InMemoryStateAdapter(makeAllowState());
+    const guard = createGuard({
+        engine,
+        stateAdapter,
+        clock: { now: () => 1_770_000_000 },
+    });
+    let called = 0;
+    const result = await guard(buildIntent({
+        intent_id: "intent-allow-auth-check",
+        agent_id: "agent-1",
+        action_type: "PROVISION",
+        amount: 500n,
+        target: "us-east-1",
+        nonce: 3n,
+    }), async () => {
+        called++;
+        return "should-not-run";
+    });
+    assert.equal(called, 0);
+    assert.equal(result.executed, false);
+    assert.equal(result.output.decision, "DENY");
+    assert.ok(result.output.reasons.some((r) => r.startsWith("AUTH_INVALID:")));
+    engine.verifyAuthorization = original;
+});
+test("guard output is deterministic for equivalent inputs", async () => {
+    const intent = buildIntent({
+        intent_id: "intent-deterministic-1",
+        agent_id: "agent-1",
+        action_type: "PROVISION",
+        amount: 500n,
+        target: "us-east-1",
+        nonce: 10n,
+        timestamp: 1_770_000_000,
+    });
+    const g1 = createGuard({
+        engine: makeEngine(),
+        stateAdapter: new InMemoryStateAdapter(makeAllowState()),
+        clock: { now: () => 1_770_000_000 },
+    });
+    const g2 = createGuard({
+        engine: makeEngine(),
+        stateAdapter: new InMemoryStateAdapter(makeAllowState()),
+        clock: { now: () => 1_770_000_000 },
+    });
+    const r1 = await g1(intent, async () => "ok");
+    const r2 = await g2(intent, async () => "ok");
+    assert.equal(r1.output.decision, "ALLOW");
+    assert.equal(r2.output.decision, "ALLOW");
+    if (r1.output.decision === "ALLOW" && r2.output.decision === "ALLOW") {
+        assert.equal(r1.output.authorization.auth_id, r2.output.authorization.auth_id);
+        assert.equal(r1.output.authorization.state_hash, r2.output.authorization.state_hash);
+        assert.equal(r1.output.authorization.intent_hash, r2.output.authorization.intent_hash);
+    }
+});
+//# sourceMappingURL=guard.test.js.map

package/dist/guard.test.js.map

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

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export * from "./types.js";
 export * from "./builders.js";
 export * from "./adapters.js";
 export * from "./client.js";
+export * from "./guard.js";

package/dist/index.js

@@ -4,4 +4,5 @@ export * from "./types.js";
 export * from "./builders.js";
 export * from "./adapters.js";
 export * from "./client.js";
+export * from "./guard.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxdeai/sdk",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,7 @@
   },
   "publishConfig": {
     "dependencies": {
-      "@oxdeai/core": "^1.2.0"
+      "@oxdeai/core": "^1.3.0"
     }
   }
 }

package/src/guard.test.ts

@@ -0,0 +1,165 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { PolicyEngine } from "@oxdeai/core";
+
+import { InMemoryAuditAdapter, InMemoryStateAdapter } from "./adapters.js";
+import { buildIntent, buildState } from "./builders.js";
+import { createGuard } from "./guard.js";
+
+function makeEngine() {
+  return new PolicyEngine({
+    policy_version: "v1",
+    engine_secret: "dev-secret",
+    authorization_ttl_seconds: 60,
+    authorization_issuer: "issuer-A",
+    authorization_audience: "rp-A",
+    policyId: "a".repeat(64),
+  });
+}
+
+function makeAllowState() {
+  return buildState({
+    policy_version: "v1",
+    agent_id: "agent-1",
+    allow_action_types: ["PROVISION"],
+    allow_targets: ["us-east-1"],
+    budget_limit: 1_000n,
+    spent_in_period: 0n,
+    max_amount_per_action: 500n,
+  });
+}
+
+test("guard executes callback on ALLOW", async () => {
+  const engine = makeEngine();
+  const stateAdapter = new InMemoryStateAdapter(makeAllowState());
+  const auditAdapter = new InMemoryAuditAdapter();
+  const guard = createGuard({
+    engine,
+    stateAdapter,
+    auditAdapter,
+    clock: { now: () => 1_770_000_000 },
+  });
+
+  let called = 0;
+  const result = await guard(
+    buildIntent({
+      intent_id: "intent-allow-1",
+      agent_id: "agent-1",
+      action_type: "PROVISION",
+      amount: 500n,
+      target: "us-east-1",
+      nonce: 1n,
+    }),
+    async () => {
+      called++;
+      return "ok";
+    }
+  );
+
+  assert.equal(called, 1);
+  assert.equal(result.executed, true);
+  assert.equal(result.output.decision, "ALLOW");
+  if (result.executed) assert.equal(result.executionResult, "ok");
+  assert.ok(auditAdapter.snapshot().length > 0);
+});
+
+test("guard does not execute callback on DENY", async () => {
+  const engine = makeEngine();
+  const stateAdapter = new InMemoryStateAdapter(makeAllowState());
+  const guard = createGuard({
+    engine,
+    stateAdapter,
+    clock: { now: () => 1_770_000_000 },
+  });
+
+  let called = 0;
+  const result = await guard(
+    buildIntent({
+      intent_id: "intent-deny-1",
+      agent_id: "agent-1",
+      action_type: "PROVISION",
+      amount: 900n,
+      target: "us-east-1",
+      nonce: 2n,
+    }),
+    async () => {
+      called++;
+      return "should-not-run";
+    }
+  );
+
+  assert.equal(called, 0);
+  assert.equal(result.executed, false);
+  assert.equal(result.output.decision, "DENY");
+});
+
+test("guard enforces authorization verification at callback boundary", async () => {
+  const engine = makeEngine();
+  const original = engine.verifyAuthorization.bind(engine);
+  (engine as any).verifyAuthorization = () => ({ valid: false, reason: "forced-test-failure" });
+
+  const stateAdapter = new InMemoryStateAdapter(makeAllowState());
+  const guard = createGuard({
+    engine,
+    stateAdapter,
+    clock: { now: () => 1_770_000_000 },
+  });
+
+  let called = 0;
+  const result = await guard(
+    buildIntent({
+      intent_id: "intent-allow-auth-check",
+      agent_id: "agent-1",
+      action_type: "PROVISION",
+      amount: 500n,
+      target: "us-east-1",
+      nonce: 3n,
+    }),
+    async () => {
+      called++;
+      return "should-not-run";
+    }
+  );
+
+  assert.equal(called, 0);
+  assert.equal(result.executed, false);
+  assert.equal(result.output.decision, "DENY");
+  assert.ok(result.output.reasons.some((r) => r.startsWith("AUTH_INVALID:")));
+
+  (engine as any).verifyAuthorization = original;
+});
+
+test("guard output is deterministic for equivalent inputs", async () => {
+  const intent = buildIntent({
+    intent_id: "intent-deterministic-1",
+    agent_id: "agent-1",
+    action_type: "PROVISION",
+    amount: 500n,
+    target: "us-east-1",
+    nonce: 10n,
+    timestamp: 1_770_000_000,
+  });
+
+  const g1 = createGuard({
+    engine: makeEngine(),
+    stateAdapter: new InMemoryStateAdapter(makeAllowState()),
+    clock: { now: () => 1_770_000_000 },
+  });
+  const g2 = createGuard({
+    engine: makeEngine(),
+    stateAdapter: new InMemoryStateAdapter(makeAllowState()),
+    clock: { now: () => 1_770_000_000 },
+  });
+
+  const r1 = await g1(intent, async () => "ok");
+  const r2 = await g2(intent, async () => "ok");
+
+  assert.equal(r1.output.decision, "ALLOW");
+  assert.equal(r2.output.decision, "ALLOW");
+  if (r1.output.decision === "ALLOW" && r2.output.decision === "ALLOW") {
+    assert.equal(r1.output.authorization.auth_id, r2.output.authorization.auth_id);
+    assert.equal(r1.output.authorization.state_hash, r2.output.authorization.state_hash);
+    assert.equal(r1.output.authorization.intent_hash, r2.output.authorization.intent_hash);
+  }
+});

package/src/guard.ts

@@ -0,0 +1,138 @@
+import type { Intent, PolicyEngine, State, Authorization } from "@oxdeai/core";
+import type { AuditAdapter, ClockAdapter, MaybePromise, StateAdapter, IntentBuilderInput } from "./types.js";
+import { buildIntent } from "./builders.js";
+
+export type GuardDecision =
+  | { decision: "ALLOW"; reasons: []; authorization: Authorization }
+  | { decision: "DENY"; reasons: string[] };
+
+export type GuardAllowResult<T> = {
+  output: GuardDecision & { decision: "ALLOW"; reasons: []; authorization: Authorization };
+  intent: Intent;
+  state: State;
+  auditEvents: unknown[];
+  executed: true;
+  executionResult: T;
+};
+
+export type GuardDenyResult = {
+  output: GuardDecision & { decision: "DENY"; reasons: string[] };
+  intent: Intent;
+  state: State;
+  auditEvents: unknown[];
+  executed: false;
+};
+
+export type GuardResult<T> = GuardAllowResult<T> | GuardDenyResult;
+
+export type GuardInputIntent = Intent | IntentBuilderInput;
+
+export type GuardOptions = {
+  engine: PolicyEngine;
+  stateAdapter: StateAdapter;
+  auditAdapter?: AuditAdapter;
+  clock?: ClockAdapter;
+  mode?: "fail-fast" | "collect-all";
+  verifyAuthorization?: boolean;
+};
+
+type GuardExecuteContext = {
+  intent: Intent;
+  authorization: Authorization;
+  state: State;
+};
+
+function collectNewEvents(engine: PolicyEngine, cursor: number): { nextCursor: number; events: unknown[] } {
+  const all = engine.audit.snapshot() as unknown[];
+  return { nextCursor: all.length, events: all.slice(cursor) };
+}
+
+function isIntent(value: GuardInputIntent): value is Intent {
+  return (
+    typeof (value as Intent).intent_id === "string" &&
+    typeof (value as Intent).agent_id === "string" &&
+    typeof (value as Intent).action_type === "string" &&
+    typeof (value as Intent).signature === "string"
+  );
+}
+
+export type GuardFn = <T>(
+  input: GuardInputIntent,
+  execute: (ctx: GuardExecuteContext) => MaybePromise<T>
+) => Promise<GuardResult<T>>;
+
+export function createGuard(opts: GuardOptions): GuardFn {
+  const clock = opts.clock ?? { now: () => Math.floor(Date.now() / 1000) };
+  let auditCursor = 0;
+
+  return async function guard<T>(
+    input: GuardInputIntent,
+    execute: (ctx: GuardExecuteContext) => MaybePromise<T>
+  ): Promise<GuardResult<T>> {
+    const state = await opts.stateAdapter.load();
+    const intent: Intent = isIntent(input)
+      ? ({
+          ...input,
+          timestamp: input.timestamp === 0 ? clock.now() : input.timestamp,
+        } as Intent)
+      : buildIntent({
+          ...input,
+          timestamp: input.timestamp ?? clock.now(),
+        });
+
+    const out = opts.engine.evaluatePure(intent, state, { mode: opts.mode ?? "fail-fast" });
+    const emitted = collectNewEvents(opts.engine, auditCursor);
+    auditCursor = emitted.nextCursor;
+
+    if (opts.auditAdapter) await opts.auditAdapter.append(emitted.events);
+
+    if (out.decision === "DENY") {
+      return {
+        output: { decision: "DENY", reasons: out.reasons },
+        intent,
+        state,
+        auditEvents: emitted.events,
+        executed: false,
+      };
+    }
+
+    if (!out.authorization || !out.nextState) {
+      return {
+        output: { decision: "DENY", reasons: ["PEP_INVARIANT_VIOLATION"] },
+        intent,
+        state,
+        auditEvents: emitted.events,
+        executed: false,
+      };
+    }
+
+    if (opts.verifyAuthorization !== false) {
+      const authCheck = opts.engine.verifyAuthorization(intent, out.authorization, out.nextState, intent.timestamp);
+      if (!authCheck.valid) {
+        return {
+          output: { decision: "DENY", reasons: [`AUTH_INVALID:${authCheck.reason ?? "unknown"}`] },
+          intent,
+          state,
+          auditEvents: emitted.events,
+          executed: false,
+        };
+      }
+    }
+
+    const executionResult = await execute({
+      intent,
+      authorization: out.authorization,
+      state: out.nextState,
+    });
+    await opts.stateAdapter.save(out.nextState);
+
+    return {
+      output: { decision: "ALLOW", reasons: [], authorization: out.authorization },
+      intent,
+      state: out.nextState,
+      auditEvents: emitted.events,
+      executed: true,
+      executionResult,
+    };
+  };
+}

package/src/index.ts

@@ -4,3 +4,4 @@ export * from "./types.js";
 export * from "./builders.js";
 export * from "./adapters.js";
 export * from "./client.js";
+export * from "./guard.js";