@voyantjs/workflows 0.37.1 → 0.38.0

package/README.md

@@ -35,6 +35,12 @@ export const sendBookingReminders = workflow({
   `X-Voyant-Dispatch-Auth` header. Wires into the orchestrator's
   `sign` hook and the handler's `verifyRequest` hook with a shared
   secret.
+- `@voyantjs/workflows/bindings` — runtime binding types and `env`
+  shim for workflow code that reads platform bindings.
+- `@voyantjs/workflows/config` — `defineConfig` and `voyant.config.ts`
+  types.
+- `@voyantjs/workflows/errors` — typed user/runtime errors
+  (`FatalError`, `RetryableError`, `TimeoutError`, and related classes).
 - `@voyantjs/workflows/protocol` — wire-protocol types shared with the
   orchestrator.
 
@@ -43,4 +49,3 @@ export const sendBookingReminders = workflow({
 - [`docs/sdk-surface.md`](../../docs/sdk-surface.md) — locked API surface.
 - [`docs/design.md`](../../docs/design.md) — architecture and rationale.
 - [`docs/runtime-protocol.md`](../../docs/runtime-protocol.md) — wire protocol.
-

package/dist/bindings.d.ts

@@ -0,0 +1,119 @@
+export interface Env {
+    [key: string]: Binding;
+}
+export type Binding = D1Database | R2Bucket | KVNamespace | Queue<unknown> | string;
+export interface D1Database {
+    prepare(sql: string): D1PreparedStatement;
+    batch(statements: D1PreparedStatement[]): Promise<D1Result[]>;
+    exec(sql: string): Promise<D1ExecResult>;
+}
+export interface D1PreparedStatement {
+    bind(...values: unknown[]): D1PreparedStatement;
+    first<T = unknown>(column?: string): Promise<T | null>;
+    run(): Promise<D1Result>;
+    all<T = unknown>(): Promise<{
+        results: T[];
+        meta: D1Meta;
+    }>;
+    /** Per-step-invocation read cache. */
+    memoize(): D1PreparedStatement;
+}
+export interface D1Result {
+    success: boolean;
+    meta: D1Meta;
+    results?: unknown[];
+}
+export interface D1ExecResult {
+    count: number;
+    duration: number;
+}
+export interface D1Meta {
+    duration: number;
+    rows_read: number;
+    rows_written: number;
+}
+export interface R2Bucket {
+    get(key: string, opts?: R2GetOptions): Promise<R2Object | null>;
+    put(key: string, value: R2PutBody, opts?: R2PutOptions): Promise<R2Object>;
+    delete(keys: string | string[]): Promise<void>;
+    list(opts?: R2ListOptions): Promise<R2Objects>;
+    head(key: string): Promise<R2Object | null>;
+}
+export interface R2GetOptions {
+    range?: {
+        offset?: number;
+        length?: number;
+    };
+    onlyIf?: {
+        etagMatches?: string;
+    };
+}
+export interface R2PutOptions {
+    httpMetadata?: Record<string, string>;
+    customMetadata?: Record<string, string>;
+}
+export type R2PutBody = ReadableStream | ArrayBuffer | string;
+export interface R2Object {
+    key: string;
+    size: number;
+    etag: string;
+    httpMetadata?: Record<string, string>;
+    customMetadata?: Record<string, string>;
+    body?: ReadableStream;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+}
+export interface R2ListOptions {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface R2Objects {
+    objects: R2Object[];
+    truncated: boolean;
+    cursor?: string;
+}
+export interface KVNamespace {
+    get<T = string>(key: string, opts?: KVGetOptions<T>): Promise<T | null>;
+    put(key: string, value: string | ArrayBuffer, opts?: KVPutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(opts?: KVListOptions): Promise<KVList>;
+}
+export interface KVGetOptions<T> {
+    type?: T extends string ? "text" : "json" | "arrayBuffer" | "stream";
+}
+export interface KVPutOptions {
+    expiration?: number;
+    expirationTtl?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface KVListOptions {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface KVList {
+    keys: {
+        name: string;
+        expiration?: number;
+        metadata?: unknown;
+    }[];
+    list_complete: boolean;
+    cursor?: string;
+}
+export interface Queue<T> {
+    send(message: T, opts?: {
+        delaySeconds?: number;
+    }): Promise<void>;
+    sendBatch(messages: readonly T[]): Promise<void>;
+}
+/**
+ * The environment object tenant code reads bindings from.
+ *
+ * On the edge runtime, this is a pass-through to the tenant worker's
+ * `env` parameter (CF Workers). On the container runtime, the
+ * platform injects HTTP-based clients that mimic the shapes above.
+ */
+export declare const env: Env;
+//# sourceMappingURL=bindings.d.ts.map

package/dist/bindings.d.ts.map

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

package/dist/bindings.js

@@ -0,0 +1,19 @@
+// @voyantjs/workflows/bindings
+//
+// Runtime binding shim. Edge runtime passes through to native CF bindings;
+// container runtime makes authenticated HTTPS calls to CF's per-binding APIs.
+//
+// Contract defined in docs/sdk-surface.md §9 and docs/design.md §5.2.
+/**
+ * The environment object tenant code reads bindings from.
+ *
+ * On the edge runtime, this is a pass-through to the tenant worker's
+ * `env` parameter (CF Workers). On the container runtime, the
+ * platform injects HTTP-based clients that mimic the shapes above.
+ */
+export const env = new Proxy({}, {
+    get(_, key) {
+        throw new Error(`@voyantjs/workflows/bindings: env.${key} was accessed outside a workflow / step body. ` +
+            `Bindings are injected by the runtime — see docs/sdk-surface.md §9.`);
+    },
+});

package/dist/config.d.ts

@@ -0,0 +1,93 @@
+export type Duration = number | `${number}${"ms" | "s" | "m" | "h" | "d" | "w"}`;
+/** Cloudflare Container instance types — see `@voyantjs/workflows` for the size table. */
+export type MachineType = "lite" | "basic" | "standard-1" | "standard-2" | "standard-3" | "standard-4" | (string & {});
+export type EnvironmentName = "production" | "preview" | "development";
+export type MeterKey = "edgeCpuMs" | "containerSeconds" | "warmSlotHours" | "runCount" | "activeScheduleHours" | "payloadStorageGbHour" | "retentionRunMonths";
+export type BindingDeclaration = {
+    type: "d1";
+    name: string;
+} | {
+    type: "r2";
+    name: string;
+} | {
+    type: "kv";
+    name: string;
+} | {
+    type: "queue";
+    name: string;
+};
+export interface EnvironmentConfig {
+    customDomain?: string;
+}
+export interface RetryPolicy {
+    max?: number;
+    backoff?: "exponential" | "linear" | "fixed";
+    initial?: Duration;
+    maxDelay?: Duration;
+}
+export interface BuildExtension {
+    name: string;
+    /** Open-ended hook surface; each extension defines its own contract. */
+    [key: string]: unknown;
+}
+export interface Instrumentation {
+    name: string;
+    [key: string]: unknown;
+}
+export interface WorkflowsConfig {
+    dirs?: string[];
+    defaults?: {
+        retries?: RetryPolicy;
+        timeout?: Duration;
+        timezone?: string;
+        machine?: MachineType;
+        concurrency?: {
+            strategy?: "queue" | "cancel-in-progress" | "cancel-newest" | "round-robin";
+        };
+    };
+    containerPool?: {
+        defaultMachine?: MachineType;
+        maxConcurrency?: number;
+        warmPoolSize?: Partial<Record<EnvironmentName, number>>;
+        evictionTtl?: Duration;
+        perPodConcurrency?: number;
+        scaleOutPolicy?: "none" | "onDemand";
+        preWarmStrategy?: "onFirstRequest" | "onDeploy";
+    };
+    build?: {
+        extensions?: BuildExtension[];
+        defineEnv?: Record<string, string>;
+    };
+    instrumentations?: Instrumentation[];
+    dev?: {
+        port?: number;
+        preservation?: "smart" | "always" | "never";
+        simulateEnvironment?: EnvironmentName;
+    };
+    billing?: {
+        caps?: {
+            monthly?: Partial<Record<MeterKey, number>>;
+            action?: "hard-stop" | "soft-notify";
+            perEnvironment?: Partial<Record<EnvironmentName, {
+                monthly?: Partial<Record<MeterKey, number>>;
+            }>>;
+        };
+    };
+    versioning?: {
+        retireAfter?: Duration;
+        onSunset?: "cancel" | "migrate" | "extend";
+        sunsetNoticePeriod?: Duration;
+    };
+}
+export interface VoyantConfig {
+    projectId: string;
+    entry: {
+        worker: string;
+        container?: string;
+    };
+    environments: Record<EnvironmentName, EnvironmentConfig>;
+    bindings: Record<string, BindingDeclaration>;
+    workflows?: WorkflowsConfig;
+}
+export declare function defineConfig(config: VoyantConfig): VoyantConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

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

package/dist/config.js

@@ -0,0 +1,7 @@
+// @voyantjs/workflows/config
+//
+// Types and `defineConfig` helper for `voyant.config.ts`.
+// Contract defined in docs/sdk-surface.md §10 and docs/design.md §5.4.3.
+export function defineConfig(config) {
+    return config;
+}

package/dist/errors.d.ts

@@ -0,0 +1,58 @@
+export type ErrorCategory = "USER_ERROR" | "RUNTIME_ERROR";
+export declare abstract class VoyantError extends Error {
+    readonly code: string;
+    readonly category: ErrorCategory;
+    constructor(message: string, opts: {
+        code: string;
+        category: ErrorCategory;
+        cause?: unknown;
+    });
+}
+export declare class FatalError extends VoyantError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+        code?: string;
+    });
+}
+export type RetryAfter = string | number | Date;
+export declare class RetryableError extends VoyantError {
+    readonly retryAfter?: RetryAfter;
+    constructor(message: string, opts?: {
+        retryAfter?: RetryAfter;
+        cause?: unknown;
+        code?: string;
+    });
+}
+export declare class TimeoutError extends VoyantError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class HookConflictError extends VoyantError {
+    readonly tokenId: string;
+    constructor(tokenId: string, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class QuotaExceededError extends VoyantError {
+    readonly meter: string;
+    readonly limit: number;
+    readonly environment: "production" | "preview" | "development";
+    constructor(opts: {
+        meter: string;
+        limit: number;
+        environment: "production" | "preview" | "development";
+        cause?: unknown;
+    });
+}
+export interface ValidationIssue {
+    path: string[];
+    message: string;
+}
+export declare class ValidationError extends VoyantError {
+    readonly issues: ValidationIssue[];
+    constructor(issues: ValidationIssue[], opts?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,eAAe,CAAA;AAE1D,8BAAsB,WAAY,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;gBAG9B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,aAAa,CAAA;QACvB,KAAK,CAAC,EAAE,OAAO,CAAA;KAChB;CAOJ;AAED,qBAAa,UAAW,SAAQ,WAAW;gBAC7B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;CAOvE;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;AAE/C,qBAAa,cAAe,SAAQ,WAAW;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;gBAEpB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;CAQhG;AAED,qBAAa,YAAa,SAAQ,WAAW;gBAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAGxD;AAED,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQxD;AAED,qBAAa,kBAAmB,SAAQ,WAAW;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,aAAa,CAAA;gBAElD,IAAI,EAAE;QAChB,KAAK,EAAE,MAAM,CAAA;QACb,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,aAAa,CAAA;QACrD,KAAK,CAAC,EAAE,OAAO,CAAA;KAChB;CAUF;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,QAAQ,CAAC,MAAM,EAAE,eAAe,EAAE,CAAA;gBAEtB,MAAM,EAAE,eAAe,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQlE"}

package/dist/errors.js

@@ -0,0 +1,76 @@
+// @voyantjs/workflows/errors
+//
+// Typed error classes used across the Voyant Workflows SDK.
+// Contract defined in docs/sdk-surface.md §7.
+export class VoyantError extends Error {
+    code;
+    category;
+    constructor(message, opts) {
+        super(message, { cause: opts.cause });
+        this.name = new.target.name;
+        this.code = opts.code;
+        this.category = opts.category;
+    }
+}
+export class FatalError extends VoyantError {
+    constructor(message, opts) {
+        super(message, {
+            code: opts?.code ?? "FATAL",
+            category: "USER_ERROR",
+            cause: opts?.cause,
+        });
+    }
+}
+export class RetryableError extends VoyantError {
+    retryAfter;
+    constructor(message, opts) {
+        super(message, {
+            code: opts?.code ?? "RETRYABLE",
+            category: "USER_ERROR",
+            cause: opts?.cause,
+        });
+        this.retryAfter = opts?.retryAfter;
+    }
+}
+export class TimeoutError extends VoyantError {
+    constructor(message, opts) {
+        super(message, { code: "TIMEOUT", category: "RUNTIME_ERROR", cause: opts?.cause });
+    }
+}
+export class HookConflictError extends VoyantError {
+    tokenId;
+    constructor(tokenId, opts) {
+        super(`hook token already resolved: ${tokenId}`, {
+            code: "HOOK_CONFLICT",
+            category: "RUNTIME_ERROR",
+            cause: opts?.cause,
+        });
+        this.tokenId = tokenId;
+    }
+}
+export class QuotaExceededError extends VoyantError {
+    meter;
+    limit;
+    environment;
+    constructor(opts) {
+        super(`quota exceeded for ${opts.meter} (limit ${opts.limit}) in ${opts.environment}`, {
+            code: "QUOTA_EXCEEDED",
+            category: "RUNTIME_ERROR",
+            cause: opts.cause,
+        });
+        this.meter = opts.meter;
+        this.limit = opts.limit;
+        this.environment = opts.environment;
+    }
+}
+export class ValidationError extends VoyantError {
+    issues;
+    constructor(issues, opts) {
+        super(`validation failed with ${issues.length} issue${issues.length === 1 ? "" : "s"}`, {
+            code: "VALIDATION",
+            category: "USER_ERROR",
+            cause: opts?.cause,
+        });
+        this.issues = issues;
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { FatalError, HookConflictError, QuotaExceededError, RetryableError, TimeoutError, ValidationError, } from "@voyantjs/workflows-errors";
 export * from "./conditions.js";
+export { FatalError, HookConflictError, QuotaExceededError, RetryableError, TimeoutError, ValidationError, } from "./errors.js";
 export * from "./trigger.js";
 export * from "./types.js";
 export * from "./workflow.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,MAAM,4BAA4B,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,iBAAiB,CAAA;AAC/B,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,MAAM,aAAa,CAAA;AACpB,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -3,8 +3,8 @@
 // Authoring SDK for Voyant Workflows. Full contract in:
 //   docs/sdk-surface.md §2–§8
 //   docs/design.md §3–§4
-export { FatalError, HookConflictError, QuotaExceededError, RetryableError, TimeoutError, ValidationError, } from "@voyantjs/workflows-errors";
 export * from "./conditions.js";
+export { FatalError, HookConflictError, QuotaExceededError, RetryableError, TimeoutError, ValidationError, } from "./errors.js";
 export * from "./trigger.js";
 export * from "./types.js";
 export * from "./workflow.js";

package/dist/runtime/errors.js

@@ -1,4 +1,4 @@
-// Internal runtime signal errors. Distinct from user-facing `@voyantjs/workflows-errors`:
+// Internal runtime signal errors. Distinct from user-facing `@voyantjs/workflows/errors`:
 // these are thrown inside the executor to unwind the workflow body on
 // waitpoint yield or run cancellation. They must not be caught by user
 // code (the executor re-throws if it observes one being swallowed).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/workflows",
-  "version": "0.37.1",
+  "version": "0.38.0",
   "description": "Authoring SDK for Voyant Workflows — durable, step-based orchestrations for Voyant Cloud.",
   "license": "Apache-2.0",
   "repository": {
@@ -31,6 +31,18 @@
       "types": "./dist/auth/index.d.ts",
       "import": "./dist/auth/index.js"
     },
+    "./bindings": {
+      "types": "./dist/bindings.d.ts",
+      "import": "./dist/bindings.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
     "./rate-limit": {
       "types": "./dist/rate-limit/index.d.ts",
       "import": "./dist/rate-limit/index.js"
@@ -58,8 +70,7 @@
     "NOTICE"
   ],
   "dependencies": {
-    "zod": "^3.23.8",
-    "@voyantjs/workflows-errors": "0.37.1"
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^20.12.0",

package/src/bindings.ts

@@ -0,0 +1,135 @@
+// @voyantjs/workflows/bindings
+//
+// Runtime binding shim. Edge runtime passes through to native CF bindings;
+// container runtime makes authenticated HTTPS calls to CF's per-binding APIs.
+//
+// Contract defined in docs/sdk-surface.md §9 and docs/design.md §5.2.
+
+// Types intentionally mirror Cloudflare's native binding shapes so the
+// same code runs on edge and container runtimes. Runtime behavior is
+// provided by the platform (native bindings on Workers; an HTTPS shim
+// on the container runtime) — this package is the shared type surface.
+
+export interface Env {
+  [key: string]: Binding
+}
+
+export type Binding = D1Database | R2Bucket | KVNamespace | Queue<unknown> | string // secrets
+
+export interface D1Database {
+  prepare(sql: string): D1PreparedStatement
+  batch(statements: D1PreparedStatement[]): Promise<D1Result[]>
+  exec(sql: string): Promise<D1ExecResult>
+}
+
+export interface D1PreparedStatement {
+  bind(...values: unknown[]): D1PreparedStatement
+  first<T = unknown>(column?: string): Promise<T | null>
+  run(): Promise<D1Result>
+  all<T = unknown>(): Promise<{ results: T[]; meta: D1Meta }>
+  /** Per-step-invocation read cache. */
+  memoize(): D1PreparedStatement
+}
+
+export interface D1Result {
+  success: boolean
+  meta: D1Meta
+  results?: unknown[]
+}
+
+export interface D1ExecResult {
+  count: number
+  duration: number
+}
+
+export interface D1Meta {
+  duration: number
+  rows_read: number
+  rows_written: number
+}
+
+export interface R2Bucket {
+  get(key: string, opts?: R2GetOptions): Promise<R2Object | null>
+  put(key: string, value: R2PutBody, opts?: R2PutOptions): Promise<R2Object>
+  delete(keys: string | string[]): Promise<void>
+  list(opts?: R2ListOptions): Promise<R2Objects>
+  head(key: string): Promise<R2Object | null>
+}
+
+export interface R2GetOptions {
+  range?: { offset?: number; length?: number }
+  onlyIf?: { etagMatches?: string }
+}
+export interface R2PutOptions {
+  httpMetadata?: Record<string, string>
+  customMetadata?: Record<string, string>
+}
+export type R2PutBody = ReadableStream | ArrayBuffer | string
+export interface R2Object {
+  key: string
+  size: number
+  etag: string
+  httpMetadata?: Record<string, string>
+  customMetadata?: Record<string, string>
+  body?: ReadableStream
+  arrayBuffer(): Promise<ArrayBuffer>
+  text(): Promise<string>
+  json<T = unknown>(): Promise<T>
+}
+export interface R2ListOptions {
+  prefix?: string
+  cursor?: string
+  limit?: number
+}
+export interface R2Objects {
+  objects: R2Object[]
+  truncated: boolean
+  cursor?: string
+}
+
+export interface KVNamespace {
+  get<T = string>(key: string, opts?: KVGetOptions<T>): Promise<T | null>
+  put(key: string, value: string | ArrayBuffer, opts?: KVPutOptions): Promise<void>
+  delete(key: string): Promise<void>
+  list(opts?: KVListOptions): Promise<KVList>
+}
+
+export interface KVGetOptions<T> {
+  type?: T extends string ? "text" : "json" | "arrayBuffer" | "stream"
+}
+export interface KVPutOptions {
+  expiration?: number
+  expirationTtl?: number
+  metadata?: Record<string, unknown>
+}
+export interface KVListOptions {
+  prefix?: string
+  cursor?: string
+  limit?: number
+}
+export interface KVList {
+  keys: { name: string; expiration?: number; metadata?: unknown }[]
+  list_complete: boolean
+  cursor?: string
+}
+
+export interface Queue<T> {
+  send(message: T, opts?: { delaySeconds?: number }): Promise<void>
+  sendBatch(messages: readonly T[]): Promise<void>
+}
+
+/**
+ * The environment object tenant code reads bindings from.
+ *
+ * On the edge runtime, this is a pass-through to the tenant worker's
+ * `env` parameter (CF Workers). On the container runtime, the
+ * platform injects HTTP-based clients that mimic the shapes above.
+ */
+export const env: Env = new Proxy({} as Env, {
+  get(_, key: string): Binding {
+    throw new Error(
+      `@voyantjs/workflows/bindings: env.${key} was accessed outside a workflow / step body. ` +
+        `Bindings are injected by the runtime — see docs/sdk-surface.md §9.`,
+    )
+  },
+})

package/src/config.ts

@@ -0,0 +1,114 @@
+// @voyantjs/workflows/config
+//
+// Types and `defineConfig` helper for `voyant.config.ts`.
+// Contract defined in docs/sdk-surface.md §10 and docs/design.md §5.4.3.
+
+export type Duration = number | `${number}${"ms" | "s" | "m" | "h" | "d" | "w"}`
+
+/** Cloudflare Container instance types — see `@voyantjs/workflows` for the size table. */
+export type MachineType =
+  | "lite"
+  | "basic"
+  | "standard-1"
+  | "standard-2"
+  | "standard-3"
+  | "standard-4"
+  | (string & {})
+
+export type EnvironmentName = "production" | "preview" | "development"
+
+export type MeterKey =
+  | "edgeCpuMs"
+  | "containerSeconds"
+  | "warmSlotHours"
+  | "runCount"
+  | "activeScheduleHours"
+  | "payloadStorageGbHour"
+  | "retentionRunMonths"
+
+export type BindingDeclaration =
+  | { type: "d1"; name: string }
+  | { type: "r2"; name: string }
+  | { type: "kv"; name: string }
+  | { type: "queue"; name: string }
+
+export interface EnvironmentConfig {
+  customDomain?: string
+}
+
+export interface RetryPolicy {
+  max?: number
+  backoff?: "exponential" | "linear" | "fixed"
+  initial?: Duration
+  maxDelay?: Duration
+}
+
+export interface BuildExtension {
+  name: string
+  /** Open-ended hook surface; each extension defines its own contract. */
+  [key: string]: unknown
+}
+
+export interface Instrumentation {
+  name: string
+  [key: string]: unknown
+}
+
+export interface WorkflowsConfig {
+  dirs?: string[]
+  defaults?: {
+    retries?: RetryPolicy
+    timeout?: Duration
+    timezone?: string
+    machine?: MachineType
+    concurrency?: { strategy?: "queue" | "cancel-in-progress" | "cancel-newest" | "round-robin" }
+  }
+  containerPool?: {
+    defaultMachine?: MachineType
+    maxConcurrency?: number
+    warmPoolSize?: Partial<Record<EnvironmentName, number>>
+    evictionTtl?: Duration
+    perPodConcurrency?: number
+    scaleOutPolicy?: "none" | "onDemand"
+    preWarmStrategy?: "onFirstRequest" | "onDeploy"
+  }
+  build?: {
+    extensions?: BuildExtension[]
+    defineEnv?: Record<string, string>
+  }
+  instrumentations?: Instrumentation[]
+  dev?: {
+    port?: number
+    preservation?: "smart" | "always" | "never"
+    simulateEnvironment?: EnvironmentName
+  }
+  billing?: {
+    caps?: {
+      monthly?: Partial<Record<MeterKey, number>>
+      action?: "hard-stop" | "soft-notify"
+      perEnvironment?: Partial<
+        Record<EnvironmentName, { monthly?: Partial<Record<MeterKey, number>> }>
+      >
+    }
+  }
+  versioning?: {
+    retireAfter?: Duration
+    onSunset?: "cancel" | "migrate" | "extend"
+    sunsetNoticePeriod?: Duration
+  }
+}
+
+export interface VoyantConfig {
+  projectId: string
+  entry: {
+    worker: string
+    container?: string
+  }
+  environments: Record<EnvironmentName, EnvironmentConfig>
+  bindings: Record<string, BindingDeclaration>
+  workflows?: WorkflowsConfig
+}
+
+export function defineConfig(config: VoyantConfig): VoyantConfig {
+  return config
+}

package/src/errors.ts

@@ -0,0 +1,109 @@
+// @voyantjs/workflows/errors
+//
+// Typed error classes used across the Voyant Workflows SDK.
+// Contract defined in docs/sdk-surface.md §7.
+
+export type ErrorCategory = "USER_ERROR" | "RUNTIME_ERROR"
+
+export abstract class VoyantError extends Error {
+  readonly code: string
+  readonly category: ErrorCategory
+
+  constructor(
+    message: string,
+    opts: {
+      code: string
+      category: ErrorCategory
+      cause?: unknown
+    },
+  ) {
+    super(message, { cause: opts.cause })
+    this.name = new.target.name
+    this.code = opts.code
+    this.category = opts.category
+  }
+}
+
+export class FatalError extends VoyantError {
+  constructor(message: string, opts?: { cause?: unknown; code?: string }) {
+    super(message, {
+      code: opts?.code ?? "FATAL",
+      category: "USER_ERROR",
+      cause: opts?.cause,
+    })
+  }
+}
+
+export type RetryAfter = string | number | Date
+
+export class RetryableError extends VoyantError {
+  readonly retryAfter?: RetryAfter
+
+  constructor(message: string, opts?: { retryAfter?: RetryAfter; cause?: unknown; code?: string }) {
+    super(message, {
+      code: opts?.code ?? "RETRYABLE",
+      category: "USER_ERROR",
+      cause: opts?.cause,
+    })
+    this.retryAfter = opts?.retryAfter
+  }
+}
+
+export class TimeoutError extends VoyantError {
+  constructor(message: string, opts?: { cause?: unknown }) {
+    super(message, { code: "TIMEOUT", category: "RUNTIME_ERROR", cause: opts?.cause })
+  }
+}
+
+export class HookConflictError extends VoyantError {
+  readonly tokenId: string
+
+  constructor(tokenId: string, opts?: { cause?: unknown }) {
+    super(`hook token already resolved: ${tokenId}`, {
+      code: "HOOK_CONFLICT",
+      category: "RUNTIME_ERROR",
+      cause: opts?.cause,
+    })
+    this.tokenId = tokenId
+  }
+}
+
+export class QuotaExceededError extends VoyantError {
+  readonly meter: string
+  readonly limit: number
+  readonly environment: "production" | "preview" | "development"
+
+  constructor(opts: {
+    meter: string
+    limit: number
+    environment: "production" | "preview" | "development"
+    cause?: unknown
+  }) {
+    super(`quota exceeded for ${opts.meter} (limit ${opts.limit}) in ${opts.environment}`, {
+      code: "QUOTA_EXCEEDED",
+      category: "RUNTIME_ERROR",
+      cause: opts.cause,
+    })
+    this.meter = opts.meter
+    this.limit = opts.limit
+    this.environment = opts.environment
+  }
+}
+
+export interface ValidationIssue {
+  path: string[]
+  message: string
+}
+
+export class ValidationError extends VoyantError {
+  readonly issues: ValidationIssue[]
+
+  constructor(issues: ValidationIssue[], opts?: { cause?: unknown }) {
+    super(`validation failed with ${issues.length} issue${issues.length === 1 ? "" : "s"}`, {
+      code: "VALIDATION",
+      category: "USER_ERROR",
+      cause: opts?.cause,
+    })
+    this.issues = issues
+  }
+}

package/src/index.ts

@@ -4,6 +4,7 @@
 //   docs/sdk-surface.md §2–§8
 //   docs/design.md §3–§4
 
+export * from "./conditions.js"
 export {
   FatalError,
   HookConflictError,
@@ -11,8 +12,7 @@ export {
   RetryableError,
   TimeoutError,
   ValidationError,
-} from "@voyantjs/workflows-errors"
-export * from "./conditions.js"
+} from "./errors.js"
 export * from "./trigger.js"
 export * from "./types.js"
 export * from "./workflow.js"

package/src/runtime/errors.ts

@@ -1,4 +1,4 @@
-// Internal runtime signal errors. Distinct from user-facing `@voyantjs/workflows-errors`:
+// Internal runtime signal errors. Distinct from user-facing `@voyantjs/workflows/errors`:
 // these are thrown inside the executor to unwind the workflow body on
 // waitpoint yield or run cancellation. They must not be caught by user
 // code (the executor re-throws if it observes one being swallowed).