@ponraaj/dimple-sdk 0.0.0-alpha.1

package/dist/internal/workflow/registry.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Job registry — maps job types to business handlers.
+ *
+ * The registry holds the *work* for each job type. The executor's workers
+ * resolve the handler by type and run it with the decoded payload; the
+ * handler's result completes the job's `DurableDeferred` (via the
+ * `DurableQueue` worker machinery), which resumes the awaiting workflow and
+ * persists the result.
+ */
+import { Context, Effect, Layer, Schema } from "effect";
+import { RegistryError, UnknownJobType } from "./errors.ts";
+declare const JobFailure_base: Schema.Class<JobFailure, Schema.TaggedStruct<"JobFailure", {
+    readonly jobId: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Handler failure surfaced by registered job handlers.
+ */
+export declare class JobFailure extends JobFailure_base {
+}
+/**
+ * Context passed to registered handlers alongside the decoded payload.
+ */
+export interface JobContext {
+    readonly jobId: string;
+}
+/**
+ * Type-erased job handler — registered per job type. The handler receives the
+ * decoded payload and returns the job's success value (or fails with
+ * `JobFailure`); the runtime owns retries/leases.
+ */
+export type Handler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure>;
+/**
+ * JobRegistry service contract.
+ *
+ * - `register` — idempotency-free: a duplicate type fails `RegistryError`.
+ *   Call at app startup (layer composition), before workers start.
+ * - `resolve`  — fails `UnknownJobType` when no handler is registered.
+ */
+export interface Interface {
+    readonly register: (type: string, handler: Handler) => Effect.Effect<void, RegistryError>;
+    readonly resolve: (type: string) => Effect.Effect<Handler, UnknownJobType>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@dimple/workflow/JobRegistry", Interface>;
+/**
+ * JobRegistry service tag — access via `yield* JobRegistry` (after providing
+ * `registryLayer`).
+ */
+export declare class Service extends Service_base {
+}
+/**
+ * Process-local registry of job type → handler. Registration happens at layer
+ * composition; a duplicate registration fails with `RegistryError`, an
+ * unknown resolve fails with `UnknownJobType`.
+ */
+export declare const layer: Layer.Layer<Service, never, never>;
+export {};

package/dist/internal/workflow/runtime.d.ts

@@ -0,0 +1,161 @@
+/**
+ * JobRuntime facade — the public API of `@dimple/workflow`.
+ *
+ * The facade is the **only** surface application code should touch:
+ *
+ * - {@link Interface.enqueue} — submit a job without waiting. Returns the
+ *   deterministic `jobId` (= executionId). Payload is validated against the
+ *   definition's schema and wrapped in the envelope
+ *   `{ token, payload, traceId }`. Discard-mode workflow execute: returns
+ *   immediately; a worker (or a later `processPending` drain) does the work.
+ * - {@link Interface.wait} — poll a job's persisted `${jobId}/result` until
+ *   it completes. On timeout writes the `${jobId}/timed_out` marker and fails
+ *   `JobTimeout`. Cross-process safe: reads the store, not local state.
+ * - {@link Interface.submit} — `enqueue` + `wait` (blocking convenience).
+ * - {@link Interface.status} — `pending | running | succeeded | failed |
+ *   timed_out | cancelled`.
+ * - {@link Interface.cancel} — marker-only (the SQL store cannot remove queue
+ *   items); `wait` observes the marker and fails `JobCancelled`.
+ * - {@link Interface.processPending} — bounded-window drain of the durable
+ *   resume-signal queue (external/cron mode; cross-process resume trigger).
+ *
+ * ### How a job completes (the happy path)
+ *
+ * ```
+ * enqueue(def, payload)
+ *   → def.workflow.execute(envelope, discard)      (registers + runs one-shot workflow)
+ *   → workflow body: DurableQueue.process(queue, payload)
+ *   → offer {token, payload} to durable queue → suspend (await deferred)
+ * worker (workerLayer/inline/processQueues)
+ *   → queue.take → registry.resolve(def.name) → runHandler(payload)
+ *   → DurableDeferred.done(exit) → engine.deferredDone
+ *   → persist deferred exit + offer resume signal + resume execution
+ * replay: workflow re-runs → deferredResult finds persisted exit
+ *   → workflow completes (success or failure) → result persisted
+ * wait(jobId) → reads `${jobId}/result` → returns success value or JobFailed
+ * ```
+ *
+ * ### Error channel
+ *
+ * `JobsError = JobFailed | JobTimeout | JobCancelled | QueueError`.
+ * `QueueError` wraps infrastructure failures (persistence/queue); the other
+ * three are job-outcome errors.
+ *
+ * ### Layer composition (see also `engine.ts` docs)
+ *
+ * - `layer(defs)` — facade over an externally-provided stack
+ *   (`WorkflowEngine | Persistence | PersistedQueueFactory`).
+ * - `layerLibsql(defs, { url })` — dep-free convenience: facade + durable
+ *   engine + SQL persistence + resume queue over one libSQL instance.
+ *   Pair with `workerLayer(defs)` (executor) + `registryLayer` for a full app.
+ *
+ */
+import { Context, Duration, Effect, Layer, Schema } from "effect";
+import { Workflow, WorkflowEngine } from "effect/unstable/workflow";
+import { PersistedQueue, Persistence as PersistenceNamespace } from "effect/unstable/persistence";
+import { SqlError as SqlErrorNamespace } from "effect/unstable/sql";
+import type { JobDefinition } from "./queue.ts";
+import { type JobsError } from "./errors.ts";
+type SqlError = SqlErrorNamespace.SqlError;
+/**
+ * Lifecycle of a job from the caller's perspective.
+ *
+ * - `pending`    — enqueued, no persisted result yet
+ * - `running`    — reserved (not currently distinguished from pending)
+ * - `succeeded`  — result persisted with a success exit
+ * - `failed`     — result persisted with a failure exit
+ * - `timed_out`  — `wait` exceeded its timeout (marker written)
+ * - `cancelled`  — `cancel` was called (marker written)
+ *
+ * Note: `running` is part of the API for future use; today non-terminal jobs
+ * report `pending`.
+ */
+export type JobStatus = "pending" | "running" | "succeeded" | "failed" | "timed_out" | "cancelled";
+/**
+ * JobRuntime service contract.
+ *
+ * `enqueue`/`submit` are generic over the definition's schemas — the payload
+ * is `P["Type"]` and the schema services appear in `R` (they are `never` for
+ * plain struct schemas). `wait` cannot infer a result schema from a jobId
+ * alone, so it returns `unknown` (the persisted success value).
+ */
+export interface Interface {
+    /** Submit a job without waiting. Returns the deterministic jobId. */
+    readonly enqueue: <P extends Workflow.AnyStructSchema, S extends Schema.Top, E extends Schema.Top>(def: JobDefinition<P, S, E>, payload: P["Type"]) => Effect.Effect<string, JobsError, P["DecodingServices"] | P["EncodingServices"] | S["DecodingServices"] | S["EncodingServices"] | E["DecodingServices"] | E["EncodingServices"]>;
+    /**
+     * Poll a job's persisted result until completion or timeout.
+     *
+     * @param jobId the value returned by `enqueue`/`submit`
+     * @param options.timeout      default 5 minutes
+     * @param options.pollInterval default 250ms
+     * @returns the job's success value; fails `JobTimeout` (marker written),
+     *          `JobCancelled` (if cancelled), or `JobFailed` (handler failure).
+     */
+    readonly wait: (jobId: string, options?: {
+        readonly timeout?: Duration.Input;
+        readonly pollInterval?: Duration.Input;
+    }) => Effect.Effect<unknown, JobsError>;
+    /** `enqueue` + `wait` — blocking convenience for inline/embedded use. */
+    readonly submit: <P extends Workflow.AnyStructSchema, S extends Schema.Top, E extends Schema.Top>(def: JobDefinition<P, S, E>, payload: P["Type"]) => Effect.Effect<unknown, JobsError, P["DecodingServices"] | P["EncodingServices"] | S["DecodingServices"] | S["EncodingServices"] | E["DecodingServices"] | E["EncodingServices"]>;
+    /** Current {@link JobStatus} of a job. */
+    readonly status: (jobId: string) => Effect.Effect<JobStatus, JobsError>;
+    /** Marker-only cancellation; `wait` on the job then fails `JobCancelled`. */
+    readonly cancel: (jobId: string) => Effect.Effect<boolean, JobsError>;
+    /**
+     * Bounded drain of the resume-signal queue — call from a cron/external
+     * trigger to let THIS process resume executions whose deferreds completed
+     * elsewhere. Returns the number of resumed executions.
+     *
+     * @param options.window how long to keep draining (default 30s). Pass a
+     *        short window when you only want to catch up on pending signals.
+     */
+    readonly processPending: (options?: {
+        readonly window?: Duration.Input;
+    }) => Effect.Effect<number, JobsError>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@dimple/workflow/JobRuntime", Interface>;
+/**
+ * JobRuntime service tag — access via `yield* JobRuntime` (after providing
+ * `layer` or `layerLibsql`).
+ */
+export declare class Service extends Service_base {
+}
+/**
+ * JobRuntime live layer.
+ *
+ * Takes the registered queue definitions; **registers their one-shot
+ * workflows at layer construction** (capturing the layer's long-lived scope,
+ * so workflow fibers live as long as the app). Captures a scoped
+ * `PersistenceStore` for result/marker reads and writes.
+ *
+ * Requires `WorkflowEngine` (durable), `Persistence` (store), and
+ * `PersistedQueueFactory` (resume-signal drain + `DurableQueue.process`).
+ *
+ * @see {@link layerLibsql} for the dep-free convenience composition
+ */
+export declare const layer: (defs: readonly JobDefinition.Any[]) => Layer.Layer<Service, never, WorkflowEngine.WorkflowEngine | PersistenceNamespace.Persistence | PersistedQueue.PersistedQueueFactory>;
+/**
+ * Convenience layer — the full JobRuntime stack over one libSQL instance.
+ *
+ * Dep-free (dependencies declared at layer definition, not
+ * usage sites): engine + SQL persistence + resume-queue store are provided
+ * internally. Exposes `Service` plus the underlying `WorkflowEngine`,
+ * `Persistence`, and `PersistedQueueFactory` (via `provideMerge`) so executor
+ * workers can be composed alongside.
+ *
+ * @param defs    job definitions to register + serve
+ * @param options.url libSQL URL (file: or remote Turso)
+ *
+ * @example
+ * ```ts
+ * const App = Layer.mergeAll(
+ *   layerLibsql([TopicSplit, MemoryEmbed], { url: "file:./.dimple/jobs.db" }),
+ *   registryLayer,
+ *   workerLayer([TopicSplit, MemoryEmbed], { concurrency: 2 }),
+ * )
+ * ```
+ */
+export declare const layerLibsql: (defs: readonly JobDefinition.Any[], options: {
+    readonly url: string;
+}) => Layer.Layer<Service | WorkflowEngine.WorkflowEngine | PersistenceNamespace.Persistence | PersistedQueue.PersistedQueueFactory, SqlError>;
+export {};

package/dist/make.d.ts

@@ -0,0 +1,27 @@
+import { type CoreOptions } from "./internal/core/index.js";
+import { type ConfigInput } from "./config.ts";
+import { type Dimple } from "./dimple.ts";
+/**
+ * What `makeDimple` accepts:
+ * - `{ config }` — a `dimple.jsonc` FILE PATH or an inline config OBJECT
+ *   (typed as `DimpleConfig`; validated + defaults filled). The embedding
+ *   section is mandatory (models come from it, embedders are built by
+ *   provider).
+ * - `{ core }` — full `CoreOptions` directly (power users / tests with
+ *   injected embedders).
+ */
+export type MakeDimpleOptions = {
+    readonly config: ConfigInput;
+    readonly migrationFolder?: string;
+} | {
+    readonly core: CoreOptions;
+};
+/**
+ * Create the Dimple facade — resolves once the composed system is fully
+ * booted. One runtime is built from the application layer; `runPromise`
+ * bridges each promise-facing edge, and `dispose` closes the scope.
+ * Boot failures reject with the same closed `DimpleError` surface as the
+ * facade methods (never raw Effect internals) and close the owned
+ * resources (scope + runtime) before rethrowing.
+ */
+export declare const makeDimple: (options: MakeDimpleOptions) => Promise<Dimple>;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ponraaj/dimple-sdk",
+  "version": "0.0.0-alpha.1",
+  "private": false,
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js",
+      "default": "./dist/errors.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --target node --format esm --external effect --external zod --external ai --external \"@ai-sdk/*\" --external @libsql/client --external drizzle-orm --external jsonc-parser --external \"@huggingface/transformers\" --external web-tree-sitter && tsgo -p tsconfig.build.json --outDir dist/.raw && bun scripts/internalize-dts.ts",
+    "prepack": "bun run build",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/openai-compatible": "^1.0.0",
+    "@huggingface/transformers": "^4.2.0",
+    "@libsql/client": "^0.17.4",
+    "ai": "^5.0.0",
+    "drizzle-orm": "^1.0.0-rc.4",
+    "effect": "4.0.0-beta.103",
+    "jsonc-parser": "^3.3.1",
+    "web-tree-sitter": "^0.26.9",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}