@oxdeai/sdk 1.0.1

package/README.md

@@ -0,0 +1,71 @@
+# @oxdeai/sdk
+
+Developer-facing integration layer on top of `@oxdeai/core`.
+
+## What It Adds
+
+- Intent/state builder helpers
+- Typed client wrapper for common flow: evaluate + persist + verify
+- Runtime adapters (in-memory and file-based)
+
+## Quick Example
+
+```ts
+import { PolicyEngine } from "@oxdeai/core";
+import {
+  OxDeAIClient,
+  buildState,
+  buildIntent,
+  InMemoryStateAdapter,
+  InMemoryAuditAdapter
+} from "@oxdeai/sdk";
+
+const engine = new PolicyEngine({
+  policy_version: "v1",
+  engine_secret: "dev-secret",
+  authorization_ttl_seconds: 120
+});
+
+const stateAdapter = new InMemoryStateAdapter(
+  buildState({
+    policy_version: "v1",
+    agent_id: "agent-1",
+    allow_action_types: ["PROVISION"],
+    allow_targets: ["us-east-1"]
+  })
+);
+
+const auditAdapter = new InMemoryAuditAdapter();
+
+const client = new OxDeAIClient({
+  engine,
+  stateAdapter,
+  auditAdapter,
+  clock: { now: () => 1770000000 }
+});
+
+const intent = buildIntent({
+  intent_id: "intent-1",
+  agent_id: "agent-1",
+  action_type: "PROVISION",
+  amount: 320n,
+  target: "us-east-1",
+  nonce: 1n
+});
+
+const result = await client.evaluateAndCommit(intent);
+```
+
+## Main Exports
+
+- `buildIntent`, `buildState`
+- `OxDeAIClient`
+- `InMemoryStateAdapter`, `InMemoryAuditAdapter`
+- `JsonFileStateAdapter`, `NdjsonFileAuditAdapter`
+
+## Scripts
+
+```bash
+pnpm -C packages/sdk build
+pnpm -C packages/sdk test
+```

package/dist/adapters.d.ts

@@ -0,0 +1,24 @@
+import type { State } from "@oxdeai/core";
+import type { AuditAdapter, StateAdapter } from "./types.js";
+export declare class InMemoryStateAdapter implements StateAdapter {
+    private state;
+    constructor(initial: State);
+    load(): State;
+    save(state: State): void;
+}
+export declare class InMemoryAuditAdapter implements AuditAdapter {
+    private readonly events;
+    append(events: readonly unknown[]): void;
+    snapshot(): unknown[];
+}
+export declare class JsonFileStateAdapter implements StateAdapter {
+    private readonly path;
+    constructor(path: string);
+    load(): Promise<State>;
+    save(state: State): Promise<void>;
+}
+export declare class NdjsonFileAuditAdapter implements AuditAdapter {
+    private readonly path;
+    constructor(path: string);
+    append(events: readonly unknown[]): Promise<void>;
+}

package/dist/adapters.js

@@ -0,0 +1,104 @@
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+function canonicalize(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string")
+        return value;
+    if (typeof value === "bigint")
+        return `${value.toString()}n`;
+    if (Array.isArray(value))
+        return value.map((v) => canonicalize(v));
+    if (typeof value === "object") {
+        const obj = value;
+        const out = {};
+        for (const key of Object.keys(obj).sort())
+            out[key] = canonicalize(obj[key]);
+        return out;
+    }
+    return String(value);
+}
+function stringifyCanonical(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function parseBigIntLike(value) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number")
+        return BigInt(value);
+    if (typeof value === "string") {
+        const s = value.endsWith("n") ? value.slice(0, -1) : value;
+        return BigInt(s);
+    }
+    throw new Error("invalid bigint-like value");
+}
+function mapRecordBigInt(input) {
+    const rec = (input ?? {});
+    const out = {};
+    for (const key of Object.keys(rec))
+        out[key] = parseBigIntLike(rec[key]);
+    return out;
+}
+function normalizeStateBigInts(raw) {
+    const s = raw;
+    return {
+        ...s,
+        budget: {
+            ...s.budget,
+            budget_limit: mapRecordBigInt(s.budget?.budget_limit),
+            spent_in_period: mapRecordBigInt(s.budget?.spent_in_period)
+        },
+        max_amount_per_action: mapRecordBigInt(s.max_amount_per_action)
+    };
+}
+export class InMemoryStateAdapter {
+    state;
+    constructor(initial) {
+        this.state = structuredClone(initial);
+    }
+    load() {
+        return structuredClone(this.state);
+    }
+    save(state) {
+        this.state = structuredClone(state);
+    }
+}
+export class InMemoryAuditAdapter {
+    events = [];
+    append(events) {
+        for (const event of events)
+            this.events.push(structuredClone(event));
+    }
+    snapshot() {
+        return structuredClone(this.events);
+    }
+}
+export class JsonFileStateAdapter {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async load() {
+        const txt = await readFile(this.path, "utf8");
+        return normalizeStateBigInts(JSON.parse(txt));
+    }
+    async save(state) {
+        await mkdir(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.tmp-${randomUUID()}`;
+        await writeFile(tmp, `${stringifyCanonical(state)}\n`, "utf8");
+        await rename(tmp, this.path);
+    }
+}
+export class NdjsonFileAuditAdapter {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async append(events) {
+        if (events.length === 0)
+            return;
+        await mkdir(dirname(this.path), { recursive: true });
+        const body = events.map((e) => stringifyCanonical(e)).join("\n") + "\n";
+        await appendFile(this.path, body, "utf8");
+    }
+}
+//# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

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

package/dist/builders.d.ts

@@ -0,0 +1,4 @@
+import type { Intent, State } from "@oxdeai/core";
+import type { IntentBuilderInput, StateBuilderInput } from "./types.js";
+export declare function buildIntent(input: IntentBuilderInput): Intent;
+export declare function buildState(input: StateBuilderInput): State;

package/dist/builders.js

@@ -0,0 +1,76 @@
+export function buildIntent(input) {
+    const base = {
+        intent_id: input.intent_id,
+        agent_id: input.agent_id,
+        action_type: input.action_type,
+        amount: input.amount,
+        asset: input.asset,
+        target: input.target,
+        timestamp: input.timestamp ?? 0,
+        metadata_hash: input.metadata_hash ?? "0x" + "0".repeat(64),
+        nonce: input.nonce,
+        signature: input.signature ?? "sdk-signature-placeholder",
+        depth: input.depth,
+        tool: input.tool,
+        tool_call: input.tool_call
+    };
+    if (input.type === "RELEASE") {
+        if (!input.authorization_id)
+            throw new Error("authorization_id is required for RELEASE intent");
+        return {
+            ...base,
+            type: "RELEASE",
+            authorization_id: input.authorization_id
+        };
+    }
+    return {
+        ...base,
+        type: "EXECUTE",
+        authorization_id: input.authorization_id
+    };
+}
+export function buildState(input) {
+    const agent = input.agent_id;
+    return {
+        policy_version: input.policy_version ?? "v1",
+        period_id: input.period_id ?? "default-period",
+        kill_switch: { global: false, agents: {} },
+        allowlists: {
+            action_types: input.allow_action_types ?? ["PROVISION"],
+            assets: input.allow_assets ?? [],
+            targets: input.allow_targets ?? []
+        },
+        budget: {
+            budget_limit: { [agent]: input.budget_limit ?? 1000000n },
+            spent_in_period: { [agent]: input.spent_in_period ?? 0n }
+        },
+        max_amount_per_action: { [agent]: input.max_amount_per_action ?? 1000000n },
+        velocity: {
+            config: {
+                window_seconds: input.velocity_window_seconds ?? 60,
+                max_actions: input.velocity_max_actions ?? 1000
+            },
+            counters: {}
+        },
+        replay: {
+            window_seconds: input.replay_window_seconds ?? 3600,
+            max_nonces_per_agent: input.replay_max_nonces_per_agent ?? 256,
+            nonces: {}
+        },
+        concurrency: {
+            max_concurrent: { [agent]: input.max_concurrent ?? 16 },
+            active: {},
+            active_auths: {}
+        },
+        recursion: {
+            max_depth: { [agent]: input.max_depth ?? 8 }
+        },
+        tool_limits: {
+            window_seconds: input.tool_window_seconds ?? 60,
+            max_calls: { [agent]: input.tool_max_calls ?? 1000 },
+            max_calls_by_tool: {},
+            calls: {}
+        }
+    };
+}
+//# sourceMappingURL=builders.js.map

package/dist/builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.js","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,WAAW,CAAC,KAAyB;IACnD,MAAM,IAAI,GAAG;QACX,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,CAAC;QAC/B,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3D,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,2BAA2B;QACzD,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS;KAC3B,CAAC;IAEF,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,gBAAgB;YAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QAChG,OAAO;YACL,GAAG,IAAI;YACP,IAAI,EAAE,SAAS;YACf,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;SACzC,CAAC;IACJ,CAAC;IAED,OAAO;QACL,GAAG,IAAI;QACP,IAAI,EAAE,SAAS;QACf,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;KACzC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAwB;IACjD,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC;IAC7B,OAAO;QACL,cAAc,EAAE,KAAK,CAAC,cAAc,IAAI,IAAI;QAC5C,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,gBAAgB;QAC9C,WAAW,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE;QAC1C,UAAU,EAAE;YACV,YAAY,EAAE,KAAK,CAAC,kBAAkB,IAAI,CAAC,WAAW,CAAC;YACvD,MAAM,EAAE,KAAK,CAAC,YAAY,IAAI,EAAE;YAChC,OAAO,EAAE,KAAK,CAAC,aAAa,IAAI,EAAE;SACnC;QACD,MAAM,EAAE;YACN,YAAY,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,YAAY,IAAI,QAAU,EAAE;YAC3D,eAAe,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,eAAe,IAAI,EAAE,EAAE;SAC1D;QACD,qBAAqB,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,qBAAqB,IAAI,QAAU,EAAE;QAC7E,QAAQ,EAAE;YACR,MAAM,EAAE;gBACN,cAAc,EAAE,KAAK,CAAC,uBAAuB,IAAI,EAAE;gBACnD,WAAW,EAAE,KAAK,CAAC,oBAAoB,IAAI,IAAI;aAChD;YACD,QAAQ,EAAE,EAAE;SACb;QACD,MAAM,EAAE;YACN,cAAc,EAAE,KAAK,CAAC,qBAAqB,IAAI,IAAI;YACnD,oBAAoB,EAAE,KAAK,CAAC,2BAA2B,IAAI,GAAG;YAC9D,MAAM,EAAE,EAAE;SACX;QACD,WAAW,EAAE;YACX,cAAc,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,cAAc,IAAI,EAAE,EAAE;YACvD,MAAM,EAAE,EAAE;YACV,YAAY,EAAE,EAAE;SACjB;QACD,SAAS,EAAE;YACT,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,IAAI,CAAC,EAAE;SAC7C;QACD,WAAW,EAAE;YACX,cAAc,EAAE,KAAK,CAAC,mBAAmB,IAAI,EAAE;YAC/C,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,cAAc,IAAI,IAAI,EAAE;YACpD,iBAAiB,EAAE,EAAE;YACrB,KAAK,EAAE,EAAE;SACV;KACF,CAAC;AACJ,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+import { PolicyEngine } from "@oxdeai/core";
+import type { Authorization, Intent } from "@oxdeai/core";
+import type { AuditAdapter, ClockAdapter, EvaluateAndCommitResult, StateAdapter, VerifyBundleResult } from "./types.js";
+type ClientOptions = {
+    engine: PolicyEngine;
+    stateAdapter: StateAdapter;
+    auditAdapter?: AuditAdapter;
+    clock?: ClockAdapter;
+};
+type EvaluateInput = Omit<Intent, "timestamp"> & {
+    timestamp?: number;
+};
+export declare class OxDeAIClient {
+    private readonly engine;
+    private readonly stateAdapter;
+    private readonly auditAdapter?;
+    private readonly clock;
+    private auditCursor;
+    constructor(opts: ClientOptions);
+    evaluateAndCommit(input: EvaluateInput): Promise<EvaluateAndCommitResult>;
+    verifyAuthorization(intent: Intent, authorization: Authorization): Promise<{
+        valid: boolean;
+        reason?: string;
+    }>;
+    verifyCurrentArtifacts(opts?: {
+        mode?: "strict" | "best-effort";
+    }): Promise<VerifyBundleResult>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,70 @@
+import { encodeCanonicalState, encodeEnvelope, verifyAuditEvents, verifyEnvelope, verifySnapshot } from "@oxdeai/core";
+function collectNewEvents(engine, cursor) {
+    const all = engine.audit.snapshot();
+    const events = all.slice(cursor);
+    return { nextCursor: all.length, events };
+}
+export class OxDeAIClient {
+    engine;
+    stateAdapter;
+    auditAdapter;
+    clock;
+    auditCursor = 0;
+    constructor(opts) {
+        this.engine = opts.engine;
+        this.stateAdapter = opts.stateAdapter;
+        this.auditAdapter = opts.auditAdapter;
+        this.clock = opts.clock ?? { now: () => Math.floor(Date.now() / 1000) };
+    }
+    async evaluateAndCommit(input) {
+        const state = await this.stateAdapter.load();
+        const resolvedTimestamp = input.timestamp === undefined || input.timestamp === 0
+            ? this.clock.now()
+            : input.timestamp;
+        const intent = {
+            ...input,
+            timestamp: resolvedTimestamp
+        };
+        const out = this.engine.evaluatePure(intent, state, { mode: "fail-fast" });
+        const emitted = collectNewEvents(this.engine, this.auditCursor);
+        this.auditCursor = emitted.nextCursor;
+        if (this.auditAdapter)
+            await this.auditAdapter.append(emitted.events);
+        if (out.decision === "ALLOW") {
+            await this.stateAdapter.save(out.nextState);
+            const output = {
+                decision: "ALLOW",
+                reasons: [],
+                authorization: out.authorization
+            };
+            return { output, state: out.nextState, auditEvents: emitted.events };
+        }
+        const output = {
+            decision: "DENY",
+            reasons: out.reasons
+        };
+        return { output, state, auditEvents: emitted.events };
+    }
+    async verifyAuthorization(intent, authorization) {
+        const state = await this.stateAdapter.load();
+        const result = this.engine.verifyAuthorization(intent, authorization, state, intent.timestamp);
+        return result.valid ? { valid: true } : { valid: false, reason: result.reason };
+    }
+    async verifyCurrentArtifacts(opts) {
+        const state = await this.stateAdapter.load();
+        const snapshotBytes = encodeCanonicalState(this.engine.exportState(state));
+        const snapshot = verifySnapshot(snapshotBytes);
+        const allEvents = this.engine.audit.snapshot();
+        const audit = verifyAuditEvents(allEvents, {
+            mode: opts?.mode ?? "best-effort"
+        });
+        const envelopeBytes = encodeEnvelope({
+            formatVersion: 1,
+            snapshot: snapshotBytes,
+            events: allEvents
+        });
+        const envelope = verifyEnvelope(envelopeBytes, { mode: opts?.mode ?? "best-effort" });
+        return { snapshot, audit, envelope };
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/** OxDeAI SDK — integration layer on top of @oxdeai/core. */
+export * from "@oxdeai/core";
+export * from "./types.js";
+export * from "./builders.js";
+export * from "./adapters.js";
+export * from "./client.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+/** OxDeAI SDK — integration layer on top of @oxdeai/core. */
+export * from "@oxdeai/core";
+export * from "./types.js";
+export * from "./builders.js";
+export * from "./adapters.js";
+export * from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/sdk.test.d.ts

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

package/dist/sdk.test.js

@@ -0,0 +1,71 @@
+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 { OxDeAIClient } from "./client.js";
+test("builder helpers create engine-compatible intent/state", () => {
+    const state = buildState({
+        policy_version: "v1",
+        agent_id: "agent-1",
+        allow_action_types: ["PROVISION"],
+        allow_targets: ["us-east-1"]
+    });
+    const intent = buildIntent({
+        intent_id: "intent-1",
+        agent_id: "agent-1",
+        action_type: "PROVISION",
+        amount: 100n,
+        target: "us-east-1",
+        nonce: 1n,
+        timestamp: 1_770_000_000
+    });
+    const engine = new PolicyEngine({
+        policy_version: "v1",
+        engine_secret: "dev-secret",
+        authorization_ttl_seconds: 60
+    });
+    const out = engine.evaluatePure(intent, state, { mode: "fail-fast" });
+    assert.equal(out.decision, "ALLOW");
+});
+test("OxDeAIClient evaluate+persist+verify flow", async () => {
+    const engine = new PolicyEngine({
+        policy_version: "v1",
+        engine_secret: "dev-secret",
+        authorization_ttl_seconds: 60
+    });
+    const stateAdapter = new InMemoryStateAdapter(buildState({
+        policy_version: "v1",
+        agent_id: "agent-1",
+        allow_action_types: ["PROVISION"],
+        allow_targets: ["us-east-1"]
+    }));
+    const auditAdapter = new InMemoryAuditAdapter();
+    const client = new OxDeAIClient({
+        engine,
+        stateAdapter,
+        auditAdapter,
+        clock: { now: () => 1_770_000_000 }
+    });
+    const intent = buildIntent({
+        intent_id: "intent-2",
+        agent_id: "agent-1",
+        action_type: "PROVISION",
+        amount: 320n,
+        target: "us-east-1",
+        nonce: 2n
+    });
+    const res = await client.evaluateAndCommit(intent);
+    assert.equal(res.output.decision, "ALLOW");
+    if (res.output.decision !== "ALLOW")
+        return;
+    assert.ok(res.auditEvents.length >= 3);
+    assert.equal(auditAdapter.snapshot().length, res.auditEvents.length);
+    const auth = await client.verifyAuthorization({ ...intent, timestamp: 1_770_000_000 }, res.output.authorization);
+    assert.equal(auth.valid, true);
+    const verify = await client.verifyCurrentArtifacts({ mode: "best-effort" });
+    assert.equal(verify.snapshot.status, "ok");
+    assert.equal(verify.audit.status, "ok");
+    assert.equal(verify.envelope.status, "ok");
+});
+//# sourceMappingURL=sdk.test.js.map

package/dist/sdk.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.test.js","sourceRoot":"","sources":["../src/sdk.test.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AAExC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,IAAI,CAAC,uDAAuD,EAAE,GAAG,EAAE;IACjE,MAAM,KAAK,GAAG,UAAU,CAAC;QACvB,cAAc,EAAE,IAAI;QACpB,QAAQ,EAAE,SAAS;QACnB,kBAAkB,EAAE,CAAC,WAAW,CAAC;QACjC,aAAa,EAAE,CAAC,WAAW,CAAC;KAC7B,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,WAAW,CAAC;QACzB,SAAS,EAAE,UAAU;QACrB,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,WAAW;QACxB,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE,WAAW;QACnB,KAAK,EAAE,EAAE;QACT,SAAS,EAAE,aAAa;KACzB,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC;QAC9B,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,YAAY;QAC3B,yBAAyB,EAAE,EAAE;KAC9B,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IACtE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;IAC3D,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC;QAC9B,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,YAAY;QAC3B,yBAAyB,EAAE,EAAE;KAC9B,CAAC,CAAC;IACH,MAAM,YAAY,GAAG,IAAI,oBAAoB,CAC3C,UAAU,CAAC;QACT,cAAc,EAAE,IAAI;QACpB,QAAQ,EAAE,SAAS;QACnB,kBAAkB,EAAE,CAAC,WAAW,CAAC;QACjC,aAAa,EAAE,CAAC,WAAW,CAAC;KAC7B,CAAC,CACH,CAAC;IACF,MAAM,YAAY,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC;QAC9B,MAAM;QACN,YAAY;QACZ,YAAY;QACZ,KAAK,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,aAAa,EAAE;KACpC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,WAAW,CAAC;QACzB,SAAS,EAAE,UAAU;QACrB,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,WAAW;QACxB,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE,WAAW;QACnB,KAAK,EAAE,EAAE;KACV,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAEnD,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO;IAC5C,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;IACvC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAErE,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAC3C,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,EACvC,GAAG,CAAC,MAAM,CAAC,aAAa,CACzB,CAAC;IACF,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAE/B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;IAC5E,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC3C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACxC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+import type { Authorization, Intent, State, VerificationResult } from "@oxdeai/core";
+export type MaybePromise<T> = T | Promise<T>;
+export type EvaluateDecision = {
+    decision: "ALLOW";
+    reasons: [];
+    authorization: Authorization;
+} | {
+    decision: "DENY";
+    reasons: string[];
+};
+export type EvaluateAndCommitResult = {
+    output: EvaluateDecision;
+    state: State;
+    auditEvents: unknown[];
+};
+export type VerifyBundleResult = {
+    snapshot: VerificationResult;
+    audit: VerificationResult;
+    envelope: VerificationResult;
+};
+export interface StateAdapter {
+    load(): MaybePromise<State>;
+    save(state: State): MaybePromise<void>;
+}
+export interface AuditAdapter {
+    append(events: readonly unknown[]): MaybePromise<void>;
+}
+export interface ClockAdapter {
+    now(): number;
+}
+export type IntentBuilderInput = {
+    intent_id: string;
+    agent_id: string;
+    action_type: Intent["action_type"];
+    amount: bigint;
+    target: string;
+    nonce: bigint;
+    timestamp?: number;
+    type?: "EXECUTE" | "RELEASE";
+    authorization_id?: string;
+    asset?: string;
+    metadata_hash?: string;
+    signature?: string;
+    depth?: number;
+    tool?: string;
+    tool_call?: boolean;
+};
+export type StateBuilderInput = {
+    policy_version?: string;
+    period_id?: string;
+    agent_id: string;
+    allow_action_types?: Intent["action_type"][];
+    allow_assets?: string[];
+    allow_targets?: string[];
+    budget_limit?: bigint;
+    spent_in_period?: bigint;
+    max_amount_per_action?: bigint;
+    velocity_window_seconds?: number;
+    velocity_max_actions?: number;
+    replay_window_seconds?: number;
+    replay_max_nonces_per_agent?: number;
+    max_concurrent?: number;
+    max_depth?: number;
+    tool_window_seconds?: number;
+    tool_max_calls?: number;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@oxdeai/sdk",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@oxdeai/core": "^1.0.1"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "pnpm build && node --test \"dist/**/*.test.js\""
+  }
+}

package/src/adapters.ts

@@ -0,0 +1,109 @@
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import type { State } from "@oxdeai/core";
+
+import type { AuditAdapter, StateAdapter } from "./types.js";
+
+function canonicalize(value: unknown): unknown {
+  if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") return value;
+  if (typeof value === "bigint") return `${value.toString()}n`;
+  if (Array.isArray(value)) return value.map((v) => canonicalize(v));
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).sort()) out[key] = canonicalize(obj[key]);
+    return out;
+  }
+  return String(value);
+}
+
+function stringifyCanonical(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+function parseBigIntLike(value: unknown): bigint {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number") return BigInt(value);
+  if (typeof value === "string") {
+    const s = value.endsWith("n") ? value.slice(0, -1) : value;
+    return BigInt(s);
+  }
+  throw new Error("invalid bigint-like value");
+}
+
+function mapRecordBigInt(input: unknown): Record<string, bigint> {
+  const rec = (input ?? {}) as Record<string, unknown>;
+  const out: Record<string, bigint> = {};
+  for (const key of Object.keys(rec)) out[key] = parseBigIntLike(rec[key]);
+  return out;
+}
+
+function normalizeStateBigInts(raw: unknown): State {
+  const s = raw as State;
+  return {
+    ...s,
+    budget: {
+      ...s.budget,
+      budget_limit: mapRecordBigInt((s as any).budget?.budget_limit),
+      spent_in_period: mapRecordBigInt((s as any).budget?.spent_in_period)
+    },
+    max_amount_per_action: mapRecordBigInt((s as any).max_amount_per_action)
+  };
+}
+
+export class InMemoryStateAdapter implements StateAdapter {
+  private state: State;
+
+  constructor(initial: State) {
+    this.state = structuredClone(initial);
+  }
+
+  load(): State {
+    return structuredClone(this.state);
+  }
+
+  save(state: State): void {
+    this.state = structuredClone(state);
+  }
+}
+
+export class InMemoryAuditAdapter implements AuditAdapter {
+  private readonly events: unknown[] = [];
+
+  append(events: readonly unknown[]): void {
+    for (const event of events) this.events.push(structuredClone(event));
+  }
+
+  snapshot(): unknown[] {
+    return structuredClone(this.events);
+  }
+}
+
+export class JsonFileStateAdapter implements StateAdapter {
+  constructor(private readonly path: string) {}
+
+  async load(): Promise<State> {
+    const txt = await readFile(this.path, "utf8");
+    return normalizeStateBigInts(JSON.parse(txt));
+  }
+
+  async save(state: State): Promise<void> {
+    await mkdir(dirname(this.path), { recursive: true });
+    const tmp = `${this.path}.tmp-${randomUUID()}`;
+    await writeFile(tmp, `${stringifyCanonical(state)}\n`, "utf8");
+    await rename(tmp, this.path);
+  }
+}
+
+export class NdjsonFileAuditAdapter implements AuditAdapter {
+  constructor(private readonly path: string) {}
+
+  async append(events: readonly unknown[]): Promise<void> {
+    if (events.length === 0) return;
+    await mkdir(dirname(this.path), { recursive: true });
+    const body = events.map((e) => stringifyCanonical(e)).join("\n") + "\n";
+    await appendFile(this.path, body, "utf8");
+  }
+}

package/src/builders.ts

@@ -0,0 +1,80 @@
+import type { Intent, State } from "@oxdeai/core";
+import type { IntentBuilderInput, StateBuilderInput } from "./types.js";
+
+export function buildIntent(input: IntentBuilderInput): Intent {
+  const base = {
+    intent_id: input.intent_id,
+    agent_id: input.agent_id,
+    action_type: input.action_type,
+    amount: input.amount,
+    asset: input.asset,
+    target: input.target,
+    timestamp: input.timestamp ?? 0,
+    metadata_hash: input.metadata_hash ?? "0x" + "0".repeat(64),
+    nonce: input.nonce,
+    signature: input.signature ?? "sdk-signature-placeholder",
+    depth: input.depth,
+    tool: input.tool,
+    tool_call: input.tool_call
+  };
+
+  if (input.type === "RELEASE") {
+    if (!input.authorization_id) throw new Error("authorization_id is required for RELEASE intent");
+    return {
+      ...base,
+      type: "RELEASE",
+      authorization_id: input.authorization_id
+    };
+  }
+
+  return {
+    ...base,
+    type: "EXECUTE",
+    authorization_id: input.authorization_id
+  };
+}
+
+export function buildState(input: StateBuilderInput): State {
+  const agent = input.agent_id;
+  return {
+    policy_version: input.policy_version ?? "v1",
+    period_id: input.period_id ?? "default-period",
+    kill_switch: { global: false, agents: {} },
+    allowlists: {
+      action_types: input.allow_action_types ?? ["PROVISION"],
+      assets: input.allow_assets ?? [],
+      targets: input.allow_targets ?? []
+    },
+    budget: {
+      budget_limit: { [agent]: input.budget_limit ?? 1_000_000n },
+      spent_in_period: { [agent]: input.spent_in_period ?? 0n }
+    },
+    max_amount_per_action: { [agent]: input.max_amount_per_action ?? 1_000_000n },
+    velocity: {
+      config: {
+        window_seconds: input.velocity_window_seconds ?? 60,
+        max_actions: input.velocity_max_actions ?? 1000
+      },
+      counters: {}
+    },
+    replay: {
+      window_seconds: input.replay_window_seconds ?? 3600,
+      max_nonces_per_agent: input.replay_max_nonces_per_agent ?? 256,
+      nonces: {}
+    },
+    concurrency: {
+      max_concurrent: { [agent]: input.max_concurrent ?? 16 },
+      active: {},
+      active_auths: {}
+    },
+    recursion: {
+      max_depth: { [agent]: input.max_depth ?? 8 }
+    },
+    tool_limits: {
+      window_seconds: input.tool_window_seconds ?? 60,
+      max_calls: { [agent]: input.tool_max_calls ?? 1000 },
+      max_calls_by_tool: {},
+      calls: {}
+    }
+  };
+}

package/src/client.ts

@@ -0,0 +1,106 @@
+import {
+  PolicyEngine,
+  encodeCanonicalState,
+  encodeEnvelope,
+  verifyAuditEvents,
+  verifyEnvelope,
+  verifySnapshot
+} from "@oxdeai/core";
+import type { Authorization, Intent } from "@oxdeai/core";
+
+import type {
+  AuditAdapter,
+  ClockAdapter,
+  EvaluateAndCommitResult,
+  EvaluateDecision,
+  StateAdapter,
+  VerifyBundleResult
+} from "./types.js";
+
+type ClientOptions = {
+  engine: PolicyEngine;
+  stateAdapter: StateAdapter;
+  auditAdapter?: AuditAdapter;
+  clock?: ClockAdapter;
+};
+
+type EvaluateInput = Omit<Intent, "timestamp"> & { timestamp?: number };
+
+function collectNewEvents(engine: PolicyEngine, cursor: number): { nextCursor: number; events: unknown[] } {
+  const all = engine.audit.snapshot() as unknown[];
+  const events = all.slice(cursor);
+  return { nextCursor: all.length, events };
+}
+
+export class OxDeAIClient {
+  private readonly engine: PolicyEngine;
+  private readonly stateAdapter: StateAdapter;
+  private readonly auditAdapter?: AuditAdapter;
+  private readonly clock: ClockAdapter;
+  private auditCursor = 0;
+
+  constructor(opts: ClientOptions) {
+    this.engine = opts.engine;
+    this.stateAdapter = opts.stateAdapter;
+    this.auditAdapter = opts.auditAdapter;
+    this.clock = opts.clock ?? { now: () => Math.floor(Date.now() / 1000) };
+  }
+
+  async evaluateAndCommit(input: EvaluateInput): Promise<EvaluateAndCommitResult> {
+    const state = await this.stateAdapter.load();
+    const resolvedTimestamp = input.timestamp === undefined || input.timestamp === 0
+      ? this.clock.now()
+      : input.timestamp;
+    const intent: Intent = {
+      ...input,
+      timestamp: resolvedTimestamp
+    } as Intent;
+
+    const out = this.engine.evaluatePure(intent, state, { mode: "fail-fast" });
+    const emitted = collectNewEvents(this.engine, this.auditCursor);
+    this.auditCursor = emitted.nextCursor;
+
+    if (this.auditAdapter) await this.auditAdapter.append(emitted.events);
+
+    if (out.decision === "ALLOW") {
+      await this.stateAdapter.save(out.nextState);
+      const output: EvaluateDecision = {
+        decision: "ALLOW",
+        reasons: [],
+        authorization: out.authorization
+      };
+      return { output, state: out.nextState, auditEvents: emitted.events };
+    }
+
+    const output: EvaluateDecision = {
+      decision: "DENY",
+      reasons: out.reasons
+    };
+    return { output, state, auditEvents: emitted.events };
+  }
+
+  async verifyAuthorization(intent: Intent, authorization: Authorization): Promise<{ valid: boolean; reason?: string }> {
+    const state = await this.stateAdapter.load();
+    const result = this.engine.verifyAuthorization(intent, authorization, state, intent.timestamp);
+    return result.valid ? { valid: true } : { valid: false, reason: result.reason };
+  }
+
+  async verifyCurrentArtifacts(opts?: { mode?: "strict" | "best-effort" }): Promise<VerifyBundleResult> {
+    const state = await this.stateAdapter.load();
+    const snapshotBytes = encodeCanonicalState(this.engine.exportState(state));
+    const snapshot = verifySnapshot(snapshotBytes);
+
+    const allEvents = this.engine.audit.snapshot();
+    const audit = verifyAuditEvents(allEvents as Parameters<typeof verifyAuditEvents>[0], {
+      mode: opts?.mode ?? "best-effort"
+    });
+
+    const envelopeBytes = encodeEnvelope({
+      formatVersion: 1,
+      snapshot: snapshotBytes,
+      events: allEvents as any
+    });
+    const envelope = verifyEnvelope(envelopeBytes, { mode: opts?.mode ?? "best-effort" });
+    return { snapshot, audit, envelope };
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+/** OxDeAI SDK — integration layer on top of @oxdeai/core. */
+export * from "@oxdeai/core";
+export * from "./types.js";
+export * from "./builders.js";
+export * from "./adapters.js";
+export * from "./client.js";

package/src/sdk.test.ts

@@ -0,0 +1,83 @@
+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 { OxDeAIClient } from "./client.js";
+
+test("builder helpers create engine-compatible intent/state", () => {
+  const state = buildState({
+    policy_version: "v1",
+    agent_id: "agent-1",
+    allow_action_types: ["PROVISION"],
+    allow_targets: ["us-east-1"]
+  });
+  const intent = buildIntent({
+    intent_id: "intent-1",
+    agent_id: "agent-1",
+    action_type: "PROVISION",
+    amount: 100n,
+    target: "us-east-1",
+    nonce: 1n,
+    timestamp: 1_770_000_000
+  });
+
+  const engine = new PolicyEngine({
+    policy_version: "v1",
+    engine_secret: "dev-secret",
+    authorization_ttl_seconds: 60
+  });
+  const out = engine.evaluatePure(intent, state, { mode: "fail-fast" });
+  assert.equal(out.decision, "ALLOW");
+});
+
+test("OxDeAIClient evaluate+persist+verify flow", async () => {
+  const engine = new PolicyEngine({
+    policy_version: "v1",
+    engine_secret: "dev-secret",
+    authorization_ttl_seconds: 60
+  });
+  const stateAdapter = new InMemoryStateAdapter(
+    buildState({
+      policy_version: "v1",
+      agent_id: "agent-1",
+      allow_action_types: ["PROVISION"],
+      allow_targets: ["us-east-1"]
+    })
+  );
+  const auditAdapter = new InMemoryAuditAdapter();
+  const client = new OxDeAIClient({
+    engine,
+    stateAdapter,
+    auditAdapter,
+    clock: { now: () => 1_770_000_000 }
+  });
+
+  const intent = buildIntent({
+    intent_id: "intent-2",
+    agent_id: "agent-1",
+    action_type: "PROVISION",
+    amount: 320n,
+    target: "us-east-1",
+    nonce: 2n
+  });
+  const res = await client.evaluateAndCommit(intent);
+
+  assert.equal(res.output.decision, "ALLOW");
+  if (res.output.decision !== "ALLOW") return;
+  assert.ok(res.auditEvents.length >= 3);
+  assert.equal(auditAdapter.snapshot().length, res.auditEvents.length);
+
+  const auth = await client.verifyAuthorization(
+    { ...intent, timestamp: 1_770_000_000 },
+    res.output.authorization
+  );
+  assert.equal(auth.valid, true);
+
+  const verify = await client.verifyCurrentArtifacts({ mode: "best-effort" });
+  assert.equal(verify.snapshot.status, "ok");
+  assert.equal(verify.audit.status, "ok");
+  assert.equal(verify.envelope.status, "ok");
+});

package/src/types.ts

@@ -0,0 +1,70 @@
+import type { Authorization, Intent, State, VerificationResult } from "@oxdeai/core";
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type EvaluateDecision =
+  | { decision: "ALLOW"; reasons: []; authorization: Authorization }
+  | { decision: "DENY"; reasons: string[] };
+
+export type EvaluateAndCommitResult = {
+  output: EvaluateDecision;
+  state: State;
+  auditEvents: unknown[];
+};
+
+export type VerifyBundleResult = {
+  snapshot: VerificationResult;
+  audit: VerificationResult;
+  envelope: VerificationResult;
+};
+
+export interface StateAdapter {
+  load(): MaybePromise<State>;
+  save(state: State): MaybePromise<void>;
+}
+
+export interface AuditAdapter {
+  append(events: readonly unknown[]): MaybePromise<void>;
+}
+
+export interface ClockAdapter {
+  now(): number;
+}
+
+export type IntentBuilderInput = {
+  intent_id: string;
+  agent_id: string;
+  action_type: Intent["action_type"];
+  amount: bigint;
+  target: string;
+  nonce: bigint;
+  timestamp?: number;
+  type?: "EXECUTE" | "RELEASE";
+  authorization_id?: string;
+  asset?: string;
+  metadata_hash?: string;
+  signature?: string;
+  depth?: number;
+  tool?: string;
+  tool_call?: boolean;
+};
+
+export type StateBuilderInput = {
+  policy_version?: string;
+  period_id?: string;
+  agent_id: string;
+  allow_action_types?: Intent["action_type"][];
+  allow_assets?: string[];
+  allow_targets?: string[];
+  budget_limit?: bigint;
+  spent_in_period?: bigint;
+  max_amount_per_action?: bigint;
+  velocity_window_seconds?: number;
+  velocity_max_actions?: number;
+  replay_window_seconds?: number;
+  replay_max_nonces_per_agent?: number;
+  max_concurrent?: number;
+  max_depth?: number;
+  tool_window_seconds?: number;
+  tool_max_calls?: number;
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}