@ponraaj/dimple-sdk 0.0.0-alpha.1

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

@@ -0,0 +1,54 @@
+/**
+ * Durable WorkflowEngine — libSQL-backed, replay-based, cross-process
+ * resumable.
+ *
+ * Mirrors Effect's `WorkflowEngine.layerMemory` (in-memory impl) but swaps the
+ * Maps for a `PersistenceStore` over the same libSQL instance as the queue
+ * (jobs.db). Suspended workflows, deferred results, and activity results
+ * survive process restarts and can be resumed by any process.
+ *
+ * Validated semantics:
+ * - result persisted ONLY on Complete (never Suspended)
+ * - interrupted flags NOT persisted
+ * - replay = re-execute workflow from start; activities served from persisted
+ *   results (never re-run); suspend when deferred result absent
+ * - workflow registry + in-flight fibers stay process-local (handlers are
+ *   registered at startup; nothing to persist)
+ *
+ * Cross-process resume:
+ * - `{executionId}/record` persists `{ workflowTag, payload }` on first
+ *   submission — a new process reconstructs execution state from it
+ * - `deferredDone` offers a durable resume signal (`dimple/resume` queue,
+ *   idempotent by executionId) so any process's drainer can resume
+ * - `resume`/`execute` reconstruct from the record when the execution is not
+ *   in this process
+ *
+ * Storage split: deferred/activity/result/payload all
+ * live in one `PersistenceStore` (storeId "dimple/jobs") with
+ * `Schema.Unknown` Persistable keys — see persistence.ts for why.
+ */
+import { Layer } from "effect";
+import { WorkflowEngine } from "effect/unstable/workflow";
+import { Persistence as PersistenceNamespace, PersistedQueue } from "effect/unstable/persistence";
+import { SqlError as SqlErrorNamespace } from "effect/unstable/sql";
+type SqlError = SqlErrorNamespace.SqlError;
+/**
+ * Durable WorkflowEngine layer.
+ *
+ * Requires `Persistence` (deferred/activity/result/payload store) +
+ * `PersistedQueueFactory` (resume-signal queue). Mirrors `layerMemory`'s shape
+ * (same `Encoded` contract into `makeUnsafe`).
+ */
+export declare const layerDurable: Layer.Layer<WorkflowEngine.WorkflowEngine, never, PersistedQueue.PersistedQueueFactory | PersistenceNamespace.Persistence>;
+export declare const libsqlStack: (options: {
+    readonly url: string;
+}) => Layer.Layer<PersistedQueue.PersistedQueueFactory | PersistenceNamespace.Persistence, SqlErrorNamespace.SqlError, never>;
+/**
+ * Convenience layer: durable engine + SQL persistence + resume queue + libSQL
+ * client, all sharing one libSQL instance. Surfaces `SqlError` from the
+ * backing store. Provides `WorkflowEngine` only (deps hidden).
+ */
+export declare const layerDurableLibsql: (options: {
+    readonly url: string;
+}) => Layer.Layer<WorkflowEngine.WorkflowEngine, SqlError>;
+export {};

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

@@ -0,0 +1,77 @@
+/**
+ * Tagged errors for `@dimple/workflow`.
+ *
+ * Two groups:
+ * - **Facade-boundary errors**: `QueueError`, `UnknownJobType`,
+ *   `RegistryError`, `ShutdownError` — infrastructure concerns surfaced by
+ *   the runtime/registry.
+ * - **Job-outcome errors**: `JobFailed`, `JobTimeout`, `JobCancelled` —
+ *   what `wait`/`submit` fail with when a job doesn't succeed.
+ */
+import { Schema } from "effect";
+declare const QueueError_base: Schema.Class<QueueError, Schema.TaggedStruct<"QueueError", {
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Infrastructure failure at the facade boundary — wraps PersistedQueue /
+ * SqlClient / persistence failures surfaced by the runtime.
+ *
+ * Part of `JobsError`: `wait`/`enqueue` fail with this when the underlying
+ * store/queue misbehaves (as opposed to the job itself failing).
+ */
+export declare class QueueError extends QueueError_base {
+}
+declare const UnknownJobType_base: Schema.Class<UnknownJobType, Schema.TaggedStruct<"UnknownJobType", {
+    readonly type: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Registry resolve failed — no handler registered for `type`. */
+export declare class UnknownJobType extends UnknownJobType_base {
+}
+declare const RegistryError_base: Schema.Class<RegistryError, Schema.TaggedStruct<"RegistryError", {
+    readonly type: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Duplicate registration — a handler for `type` already exists. */
+export declare class RegistryError extends RegistryError_base {
+}
+declare const ShutdownError_base: Schema.Class<ShutdownError, Schema.TaggedStruct<"ShutdownError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Operation attempted after runtime shutdown (reserved). */
+export declare class ShutdownError extends ShutdownError_base {
+}
+/**
+ * Base error of the facade boundary hierarchy — the union of every tagged
+ * error the runtime can surface at its boundaries.
+ */
+export type JobRuntimeError = QueueError | UnknownJobType | RegistryError | ShutdownError;
+declare const JobFailed_base: Schema.Class<JobFailed, Schema.TaggedStruct<"JobFailed", {
+    readonly jobId: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The job's workflow completed with a failure exit (handler error). */
+export declare class JobFailed extends JobFailed_base {
+}
+declare const JobTimeout_base: Schema.Class<JobTimeout, Schema.TaggedStruct<"JobTimeout", {
+    readonly jobId: Schema.String;
+    readonly timeout: Schema.Duration;
+}>, import("effect/Cause").YieldableError>;
+/** `wait` exceeded its timeout; the `${jobId}/timed_out` marker was written. */
+export declare class JobTimeout extends JobTimeout_base {
+}
+declare const JobCancelled_base: Schema.Class<JobCancelled, Schema.TaggedStruct<"JobCancelled", {
+    readonly jobId: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The job was cancelled via `cancel` before completing. */
+export declare class JobCancelled extends JobCancelled_base {
+}
+/**
+ * The `JobRuntime` error channel — job outcome errors plus infrastructure
+ * (`QueueError` wraps persistence/queue failures).
+ *
+ * `wait`/`submit` fail with `JobFailed` | `JobTimeout` | `JobCancelled`;
+ * `enqueue` and the other facade methods additionally surface `QueueError`.
+ */
+export type JobsError = JobFailed | JobTimeout | JobCancelled | QueueError;
+export {};

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

@@ -0,0 +1,53 @@
+/**
+ * Execution modes — the executor decides who runs handlers and when.
+ * Same queues, same handlers, same config — only the composition differs.
+ *
+ * - `background`  — `DurableQueue.worker` layers: workers run in-process,
+ *   supervised, replicated by concurrency, shut down with the scope.
+ * - `inline`      — run the worker in the same fiber scope as the submit.
+ * - `external`    — no worker layer; a cron/drainer calls `processPending`
+ *   (bounded window) — cross-process resume via the durable signal queue.
+ *
+ * Worker handlers come from the `JobRegistry` (registered by job type at
+ * layer composition). The worker runs the business handler with the decoded
+ * payload; the `DurableQueue` machinery completes the job's deferred, which
+ * resumes the awaiting workflow (facade `submit`) and persists the result.
+ */
+import { Duration, Effect, Layer } from "effect";
+import { WorkflowEngine } from "effect/unstable/workflow";
+import { PersistedQueue } from "effect/unstable/persistence";
+import { type LogConfig } from "./internal/logger/index.js";
+import type { JobDefinition } from "./queue.ts";
+import { Service as JobRegistry } from "./registry.ts";
+import { Service as JobRuntime } from "./runtime.ts";
+export declare const workerLayer: (defs: readonly JobDefinition.Any[], options?: {
+    readonly concurrency?: number;
+    /** Bounded handler retries (total ~`maxAttempts × 300ms`); 1 = no
+     * retry (the durable retry contract, see runHandler). Clamped to
+     * [1, 100]. */
+    readonly maxAttempts?: number;
+    readonly logging?: LogConfig;
+}) => Layer.Layer<never, never, PersistedQueue.PersistedQueueFactory | JobRegistry | WorkflowEngine.WorkflowEngine> | Layer.Layer<import("./internal/logger/index.js").Logging, never, PersistedQueue.PersistedQueueFactory | import("effect/Scope").Scope | JobRegistry | WorkflowEngine.WorkflowEngine>;
+/**
+ * Inline mode — run the worker in the same fiber scope as the submit.
+ *
+ * Forks the worker, enqueues the job, then **waits for the result** — the
+ * wait keeps the scope alive until the worker completes the deferred and the
+ * workflow resumes, so the process exits cleanly with work done.
+ *
+ * Requires the full stack (JobRuntime + engine + queue + registry); use
+ * `workerLayer` for persistent processes instead.
+ */
+export declare const inline: (def: JobDefinition.Any, payload: unknown, options?: {
+    readonly concurrency?: number;
+    readonly maxAttempts?: number;
+}) => Effect.Effect<unknown, unknown, WorkflowEngine.WorkflowEngine | PersistedQueue.PersistedQueueFactory | JobRegistry | JobRuntime>;
+/**
+ * External mode — bounded drain of pending work for a window. The runtime's
+ * `processPending` (resume signals) is the companion hook for cross-process
+ * resume; this drains the job queues themselves.
+ */
+export declare const processQueues: (defs: readonly JobDefinition.Any[], options?: {
+    readonly window?: Duration.Input;
+    readonly maxAttempts?: number;
+}) => Effect.Effect<number, unknown, WorkflowEngine.WorkflowEngine | PersistedQueue.PersistedQueueFactory | JobRegistry>;

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

@@ -0,0 +1,13 @@
+/**
+ * @dimple/workflow — Effect-native durable job runtime.
+ *
+ * Barrel: named exports with aliases (project convention).
+ */
+export { JobDefinition, Envelope, TopicSplit, MemoryEmbed, TopicMerge, TopicRebalance, ConceptCluster, MemoryDream, GraphRepair, AuditWrite, type AuditRow, queues, type EnvelopeSchema, } from "./queue.ts";
+export { Service as JobRuntime, layer as jobRuntimeLayer, type Interface as JobRuntimeInterface, type JobStatus, } from "./runtime.ts";
+export { layerDurable, layerDurableLibsql } from "./engine.ts";
+export { Service as JobRegistry, layer as jobRegistryLayer, JobFailure, type Handler, type JobContext, } from "./registry.ts";
+export { workerLayer, inline, processQueues } from "./executor.ts";
+export { JobsConfig, JobsConfigDefaults, resolveJobsConfig } from "./config.ts";
+export { QueueError, UnknownJobType, RegistryError, ShutdownError, JobFailed, JobTimeout, JobCancelled, type JobRuntimeError, type JobsError, } from "./errors.ts";
+export { STORE_ID, RESUME_QUEUE, ResumeSignal, ExecutionRecord, encodedKey, resultCodecFor, payloadCodecFor, } from "./persistence.ts";

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

@@ -0,0 +1,122 @@
+/**
+ * Shared persistence layer for the durable engine and the JobRuntime facade.
+ *
+ * One `PersistenceStore` (storeId {@link STORE_ID}) holds ALL durable state in
+ * jobs.db. Keys are `Persistable` instances with `Schema.Unknown` codecs.
+ *
+ * ### Why `Schema.Unknown`?
+ *
+ * Everything stored at this boundary is **already schema-encoded JSON**:
+ * - activity results arrive from `executeEncoded` (JSON-encoded)
+ * - deferred exits arrive from `makeUnsafe.deferredDone` as
+ *   `Schema.encodeEffect(deferred.exitSchema)` output (an Exit instance with
+ *   JSON-serializable fields)
+ * - results are encoded with the per-workflow `resultCodecFor`
+ * - payloads/records are plain objects
+ *
+ * The store's `serializeExit`/`deserializeExit` then performs an identity
+ * JSON round-trip. Typed schemas here would **double-encode** (the value is
+ * already encoded when it reaches this boundary) — verified empirically:
+ * `Schema.Duration`-style transforms fail and the workflow hangs.
+ *
+ * ### Key layout (per executionId)
+ *
+ * ```
+ * {executionId}/record                  — { workflowTag, payload }  (replay source)
+ * {executionId}/{deferredName}          — deferred result Exit (JSON)
+ * {executionId}/{activity.name}/{attempt} — activity result Exit (JSON)
+ * {executionId}/result                  — encoded Workflow.Result (Complete only)
+ * {jobId}/timed_out                     — wait-timeout marker
+ * {jobId}/cancelled                     — cancel marker
+ * ```
+ *
+ */
+import { Effect, Exit, Option, Schema } from "effect";
+import { Persistable, Persistence as PersistenceNamespace } from "effect/unstable/persistence";
+type PersistenceStore = PersistenceNamespace.PersistenceStore;
+import { Workflow } from "effect/unstable/workflow";
+/** Single store id shared by engine + facade (one table partition in jobs.db). */
+export declare const STORE_ID = "dimple/jobs";
+/**
+ * Resume-signal queue name — `deferredDone` offers `{ executionId }` here so
+ * any process's drainer (`JobRuntime.processPending`) can resume a suspended
+ * execution whose deferred completed elsewhere (cross-process wakeup).
+ */
+export declare const RESUME_QUEUE = "dimple/resume";
+/** Payload of a resume signal: just the executionId to replay. */
+export declare const ResumeSignal: Schema.Struct<{
+    readonly executionId: Schema.String;
+}>;
+export interface ResumeSignal extends Schema.Schema.Type<typeof ResumeSignal> {
+}
+/**
+ * Execution record persisted on first submission — a new process reconstructs
+ * execution state from it (cross-process replay source). `payload` is the
+ * envelope object (`{ token, payload, traceId }`).
+ */
+export declare const ExecutionRecord: Schema.Struct<{
+    readonly workflowTag: Schema.String;
+    readonly payload: Schema.$Record<Schema.String, Schema.Unknown>;
+}>;
+export interface ExecutionRecord extends Schema.Schema.Type<typeof ExecutionRecord> {
+}
+/**
+ * A `Persistable` for already-encoded JSON values — a `PrimaryKey` (string
+ * key via `PrimaryKey.symbol`) plus `Schema.Unknown` success/error codecs.
+ *
+ * This is the erased identity codec: `store.set/get` round-trips whatever
+ * JSON-safe value was stored without interpreting it.
+ */
+export type EncodedPersistable = Persistable.Persistable<Schema.Unknown, Schema.Unknown>;
+/**
+ * Builds an {@link EncodedPersistable} for a raw string key.
+ *
+ * The object satisfies `Persistable` structurally (computed symbol keys
+ * resolve) — no cast needed.
+ */
+export declare const encodedKey: (key: string) => EncodedPersistable;
+/** Persisted-key helpers — `${executionId}/…` namespaces. */
+export declare const resultKey: (executionId: string) => string;
+export declare const payloadKey: (executionId: string) => string;
+export declare const recordKey: (executionId: string) => string;
+export declare const deferredKey: (executionId: string, deferredName: string) => string;
+export declare const activityKey: (executionId: string, activityName: string, attempt: number) => string;
+export declare const markerKey: (jobId: string, marker: string) => string;
+/**
+ * Reads a raw persisted Exit (`undefined` when absent). Defects on
+ * persistence/schema errors — callers treat store failures as infrastructure
+ * defects (`Effect.orDie` semantics).
+ */
+export declare const getEncodedExit: (store: PersistenceStore, key: string) => Effect.Effect<Exit.Exit<unknown, unknown> | undefined, never, never>;
+/**
+ * Writes a raw Exit under a key. The store JSON-round-trips it; the read side
+ * (`getEncodedExit`) returns an **Exit instance** (not the raw JSON), which is
+ * what `makeUnsafe`'s `deferredResult` expects (`toJsonExit(exit.value)` maps
+ * over the Option's payload).
+ */
+export declare const setEncodedExit: (store: PersistenceStore, key: string, exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void, never, never>;
+/**
+ * Reads a boolean marker (e.g. `${jobId}/timed_out`, `${jobId}/cancelled`).
+ */
+export declare const readMarker: (store: PersistenceStore, jobId: string, marker: string) => Effect.Effect<boolean, never, never>;
+/**
+ * Writes a boolean marker — the only "cancel" mechanism available (the SQL
+ * store cannot remove queue items).
+ */
+export declare const writeMarker: (store: PersistenceStore, jobId: string, marker: string) => Effect.Effect<void, never, never>;
+/**
+ * Per-workflow result codec (see {@link eraseServices} for the service
+ * erasure rationale). Decoded type is `Workflow.Result<unknown, unknown>`.
+ */
+export declare const resultCodecFor: (workflow: Workflow.Any) => Schema.Codec<Workflow.Result<unknown, unknown>, unknown, never, never>;
+/** Per-workflow payload codec (JSON round-trip of the payload schema). */
+export declare const payloadCodecFor: (workflow: Workflow.Any) => Schema.Codec<unknown, unknown, never, never>;
+/**
+ * Reads a persisted workflow result for an execution.
+ *
+ * Returns `None` while the execution is pending/suspended; `Some(Complete)`
+ * once it finished (success or failure). The workflow argument supplies the
+ * per-workflow result codec.
+ */
+export declare const readWorkflowResult: (store: PersistenceStore, workflow: Workflow.Any, executionId: string) => Effect.Effect<Option.None<Workflow.Result<unknown, unknown>> | Option.Some<Workflow.Result<unknown, unknown>>, never, never>;
+export {};

package/dist/internal/workflow/queue-store.d.ts

@@ -0,0 +1,5 @@
+import { Layer } from "effect";
+import { PersistedQueue } from "effect/unstable/persistence";
+import { SqlClient, SqlError } from "effect/unstable/sql";
+/** Provide the FIXED store to effect's `PersistedQueue.layer`. */
+export declare const storeSqliteLayer: Layer.Layer<PersistedQueue.PersistedQueueStore, SqlError.SqlError, SqlClient.SqlClient>;

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

@@ -0,0 +1,298 @@
+/**
+ * Job definitions — the schema-typed contract for one job type.
+ *
+ * A `JobDefinition` pairs two Effect primitives that share one schema set:
+ *
+ * - **`queue`** — a `DurableQueue.DurableQueue` carrying the *caller's*
+ *   payload schema. Workers take items from this queue (via the executor's
+ *   `workerLayer`/`inline`/`processQueues`), run the registered business
+ *   handler, and complete the job's deferred with the handler's result.
+ * - **`workflow`** — a one-shot `Workflow` (tag `` `JobRuntime/${name}` ``)
+ *   carrying an *envelope* schema `{ token, payload, traceId }`. The facade
+ *   (`JobRuntime.enqueue`) executes this workflow in discard mode; the
+ *   workflow body calls `DurableQueue.process`, which offers the payload to
+ *   the queue and suspends until the worker completes the deferred.
+ *
+ * ### Why two schemas?
+ *
+ * `Workflow.executionId` validates the *envelope*, and the envelope's `token`
+ * is the workflow's idempotency key — so re-enqueueing the same payload
+ * yields the same deterministic `jobId` (executionId) and dedupes queue
+ * offers. The queue itself keeps the raw payload schema so workers receive
+ * the caller's data directly.
+ *
+ * ### Error contract (important)
+ *
+ * The workflow's error schema **is** the queue's error schema. Do NOT wrap
+ * handler errors in a different type here — `JobRuntime.wait` decodes the
+ * persisted result with the workflow's `error` schema, so a mismatched error
+ * object breaks result encoding (see the `resultCodecFor` docs).
+ *
+ */
+import { Effect, Schema, Scope } from "effect";
+import { DurableQueue, Workflow, WorkflowEngine } from "effect/unstable/workflow";
+import { PersistedQueue } from "effect/unstable/persistence";
+/**
+ * Envelope schema factory — wraps a job's payload schema with the runtime
+ * fields the workflow machinery needs.
+ *
+ * - `token`   — the idempotency key (`JobDefinition.idempotencyKey(payload)`);
+ *               the workflow's executionId is derived from the envelope, so
+ *               the same token+payload ⇒ same jobId.
+ * - `payload` — the caller's payload (the definition's `payloadSchema`).
+ * - `traceId` — optional observability correlation id ("" when unset).
+ */
+export declare const Envelope: <Payload extends Workflow.AnyStructSchema>(payload: Payload) => Schema.Struct<{
+    readonly token: Schema.String;
+    readonly payload: Payload;
+    readonly traceId: Schema.optional<Schema.String>;
+}>;
+/** The schema type produced by {@link Envelope} for a given payload schema. */
+export type EnvelopeSchema<Payload extends Workflow.AnyStructSchema> = ReturnType<typeof Envelope<Payload>>;
+/**
+ * A job definition — a schema-typed `DurableQueue` + one-shot `Workflow` pair.
+ *
+ * Create with {@link JobDefinition.make}; the generic parameters track the
+ * concrete payload/success/error schemas so `enqueue`/`submit`/`register`
+ * stay fully typed. For heterogeneous collections (facades, executors) use
+ * the erased {@link JobDefinition.Any} form.
+ */
+export declare class JobDefinition<Payload extends Workflow.AnyStructSchema = Workflow.AnyStructSchema, Success extends Schema.Top = Schema.Void, Error extends Schema.Top = Schema.Never> {
+    /** Job type name (e.g. `"topic.split"`). */
+    readonly name: string;
+    /** The durable queue workers consume; carries the raw payload schema. */
+    readonly queue: DurableQueue.DurableQueue<Payload, Success, Error>;
+    /** The one-shot workflow (tag `` `JobRuntime/${name}` ``) the facade executes. */
+    readonly workflow: Workflow.Workflow<`JobRuntime/${string}`, EnvelopeSchema<Payload>, Success, Error>;
+    /** The caller's payload schema. */
+    readonly payloadSchema: Payload;
+    /** The job's success schema. */
+    readonly successSchema: Success;
+    /** The job's error schema (matches the queue's error schema — do not wrap). */
+    readonly errorSchema: Error;
+    /** Maps a payload to its idempotency token (stable ⇒ dedupe). */
+    readonly idempotencyKey: (payload: Payload["Type"]) => string;
+    /**
+     * Decodes an envelope back to `{ payload }`. Built in `make` where the
+     * schema types are concrete; the erased `Any` form widens the result.
+     */
+    readonly decodeEnvelope: (envelope: unknown) => Effect.Effect<{
+        readonly payload: Payload["Type"];
+    }, never, Payload["DecodingServices"] | Payload["EncodingServices"]>;
+    constructor(args: {
+        readonly name: string;
+        readonly queue: DurableQueue.DurableQueue<Payload, Success, Error>;
+        readonly workflow: Workflow.Workflow<`JobRuntime/${string}`, EnvelopeSchema<Payload>, Success, Error>;
+        readonly payloadSchema: Payload;
+        readonly successSchema: Success;
+        readonly errorSchema: Error;
+        readonly idempotencyKey: (payload: Payload["Type"]) => string;
+        readonly decodeEnvelope: (envelope: unknown) => Effect.Effect<{
+            readonly payload: Payload["Type"];
+        }, never, Payload["DecodingServices"] | Payload["EncodingServices"]>;
+    });
+    /**
+     * Creates a job definition from a schema set.
+     *
+     * @param name    job type name — also prefixes the workflow tag
+     *                (`JobRuntime/<name>`) and the queue name (`DurableQueue/<name>`)
+     * @param options.payload        the caller's payload struct fields
+     * @param options.success        job success schema (default `Schema.Void`)
+     * @param options.error          job error schema (default `Schema.Never`)
+     * @param options.idempotencyKey deterministic payload → token function
+     *
+     * @returns a fully-typed `JobDefinition<Schema.Struct<Payload>, Success, Error>`
+     */
+    static make: <const Name extends string, Payload_1 extends Schema.Struct.Fields, Success_1 extends Schema.Top = Schema.Void, Error_1 extends Schema.Top = Schema.Never>(name: Name, options: {
+        readonly payload: Payload_1;
+        readonly success: Success_1;
+        readonly error: Error_1;
+        readonly idempotencyKey: (payload: Schema.Struct.Type<Payload_1>) => string;
+    }) => JobDefinition<Schema.Struct<Payload_1>, Success_1, Error_1>;
+    /**
+     * Registers this definition's workflow with a `WorkflowEngine`.
+     *
+     * The registered handler decodes the envelope and forwards `env.payload` to
+     * `DurableQueue.process` — a workflow-native primitive that offers the item
+     * to the durable queue and suspends (via `Workflow.suspend`) until a worker
+     * completes the deferred.
+     *
+     * **Do not call per-job.** `JobRuntime.layer` registers all definitions at
+     * layer build (app-lifetime scope); re-registering is idempotent
+     * (`Map.set` overwrites) but wasteful.
+     *
+     * @param engine the (durable) WorkflowEngine service
+     * @returns `Effect<void, never, Scope | PersistedQueueFactory | schema services>`
+     *          — the requirements are satisfied by the engine layer composition.
+     */
+    register(engine: WorkflowEngine.WorkflowEngine["Service"]): Effect.Effect<void, never, Scope.Scope | PersistedQueue.PersistedQueueFactory | Payload["DecodingServices"] | Payload["EncodingServices"] | Success["DecodingServices"] | Success["EncodingServices"] | Error["DecodingServices"] | Error["EncodingServices"]>;
+}
+export declare namespace JobDefinition {
+    /**
+     * Type-erased job definition for generic dispatch over heterogeneous
+     * definitions (runtime facades, executor loops).
+     *
+     * Erasure uses `any` type arguments exactly like the effect library's own
+     * `Workflow.Any` — the concrete schemas live on the value. Typed access
+     * flows through the generic `enqueue`/`submit`/`register` methods instead;
+     * prefer those over reading the erased fields directly.
+     */
+    interface Any {
+        readonly name: string;
+        readonly queue: DurableQueue.DurableQueue<any, any, any>;
+        readonly workflow: Workflow.AnyWithProps;
+        readonly payloadSchema: Schema.Top;
+        readonly successSchema: Schema.Top;
+        readonly errorSchema: Schema.Top;
+        readonly idempotencyKey: (payload: any) => string;
+        readonly decodeEnvelope: (envelope: unknown) => Effect.Effect<{
+            readonly payload: unknown;
+        }, never, unknown>;
+        readonly register: (engine: WorkflowEngine.WorkflowEngine["Service"]) => Effect.Effect<void, never, Scope.Scope | PersistedQueue.PersistedQueueFactory>;
+    }
+}
+/**
+ * Topic-tree split job — `topic.split`. The overflow maintenance path: the
+ * store's `enqueueSplit` seam (or the split handler's `onUnevenSplit`
+ * counterpart) posts it; the worker runs `topicSplitHandler`
+ * (`@dimple/store` topics/jobs.ts).
+ */
+export declare const TopicSplit: JobDefinition<Schema.Struct<{
+    topicId: Schema.String;
+    modelKey: Schema.String;
+}>, Schema.Void, Schema.String>;
+/**
+ * Embedding backfill job — `memory.embed`. The multi-model lifecycle path:
+ * re-embeds one memory with a target model and routes it into that model's
+ * tree; the worker runs `memoryEmbedHandler` (topics/lifecycle.ts).
+ */
+export declare const MemoryEmbed: JobDefinition<Schema.Struct<{
+    memoryId: Schema.String;
+    modelKey: Schema.String;
+}>, Schema.Void, Schema.String>;
+/** Underflow maintenance job — `topic.merge` (borrow-then-merge). */
+export declare const TopicMerge: JobDefinition<Schema.Struct<{
+    topicId: Schema.String;
+    modelKey: Schema.String;
+}>, Schema.Void, Schema.String>;
+/** Sibling-balance maintenance job — `topic.rebalance`. */
+export declare const TopicRebalance: JobDefinition<Schema.Struct<{
+    topicId: Schema.String;
+    modelKey: Schema.String;
+}>, Schema.Void, Schema.String>;
+/**
+ * Inductive concept clustering job — `concept.cluster`. Two modes:
+ * `{ modelKey, topicKey }` clusters ONE topic leaf's members;
+ * `{ modelKey }` (no topicKey) runs the corpus pass over a deterministic
+ * sample of the memory store. The worker runs `conceptClusterHandler`
+ * (`@dimple/store` graph/concepts.ts); the idempotency token is
+ * `concept:<modelKey>:<topicKey|corpus>` so both modes dedupe independently.
+ */
+export declare const ConceptCluster: JobDefinition<Schema.Struct<{
+    modelKey: Schema.String;
+    topicKey: Schema.optional<Schema.String>;
+}>, Schema.Void, Schema.String>;
+/**
+ * Consolidation dream job — `memory.dream`. One run per model key: gather
+ * candidate pairs, judge them with the injected LLM classifier, persist
+ * relations + derived memories, and advance the model's `dream_state`
+ * watermark. The worker runs `graphDreamHandler` (`@dimple/store`
+ * graph/dream.ts). The idempotency token is `dream:<modelKey>[:<runId>]` —
+ * the SDK facade passes a fresh `runId` per call so every dream RUNS
+ * (a permanent token would make the job one-shot per model: later calls
+ * would only replay the first result). Callers that want in-flight
+ * coalescing reuse a runId while a run is pending.
+ */
+export declare const MemoryDream: JobDefinition<Schema.Struct<{
+    modelKey: Schema.String;
+    runId: Schema.optional<Schema.String>;
+}>, Schema.Void, Schema.String>;
+/**
+ * Graph repair job — `graph.repair`. One pass per model key: removes
+ * orphaned `artifact_edges` rows and stale `memory_concepts` annotations
+ * (left-join sweeps over rows whose endpoint is gone), and — only when the
+ * handler was built with `includePurgeExpired` — hard-purges soft-deleted
+ * edges older than the grace window. The worker runs `graphRepairHandler`
+ * (`@dimple/store` graph/repair.ts). The idempotency token is
+ * `repair:<modelKey>[:<runId>]` — same per-run semantics as `memory.dream`.
+ */
+export declare const GraphRepair: JobDefinition<Schema.Struct<{
+    modelKey: Schema.String;
+    runId: Schema.optional<Schema.String>;
+}>, Schema.Void, Schema.String>;
+/**
+ * One retrieval-audit row (the `retrieval_log` shape). Structural mirror
+ * of `@dimple/store`'s `RetrievalAuditRow` — the workflow package cannot
+ * import the store, and the queue schema decodes the store-built row
+ * as-is. The `audit.write` job moves audit writes OFF the query path:
+ * `Store.searchVector` enqueues the row (the store's `enqueueAudit` seam,
+ * wired by the app root) and the worker performs the insert.
+ */
+export declare const AuditRow: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly queryHash: Schema.String;
+    readonly queryText: Schema.String;
+    readonly namespace: Schema.String;
+    readonly mode: Schema.String;
+    readonly queryProfile: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Null]>>;
+    readonly sources: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Null]>>;
+    readonly resultCount: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.Null]>>;
+    readonly latencyMs: Schema.Number;
+    readonly createdAt: Schema.Number;
+}>;
+export type AuditRow = Schema.Schema.Type<typeof AuditRow>;
+/** Retrieval-audit write job — `audit.write`. */
+/** The idempotency key covers the WHOLE batch (all row ids, in payload
+ * order) — a key from `rows[0]` alone would silently dedupe two distinct
+ * batches sharing their first row (the second batch's rows would never be
+ * written). Identical batches still dedupe to one job. */
+export declare const AuditWrite: JobDefinition<Schema.Struct<{
+    rows: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly queryHash: Schema.String;
+        readonly queryText: Schema.String;
+        readonly namespace: Schema.String;
+        readonly mode: Schema.String;
+        readonly queryProfile: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Null]>>;
+        readonly sources: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Null]>>;
+        readonly resultCount: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.Null]>>;
+        readonly latencyMs: Schema.Number;
+        readonly createdAt: Schema.Number;
+    }>>;
+}>, Schema.Void, Schema.String>;
+/** All built-in job definitions, for bulk registration/worker composition. */
+export declare const queues: readonly [JobDefinition<Schema.Struct<{
+    topicId: Schema.String;
+    modelKey: Schema.String;
+}>, Schema.Void, Schema.String>, JobDefinition<Schema.Struct<{
+    memoryId: Schema.String;
+    modelKey: Schema.String;
+}>, Schema.Void, Schema.String>, JobDefinition<Schema.Struct<{
+    topicId: Schema.String;
+    modelKey: Schema.String;
+}>, Schema.Void, Schema.String>, JobDefinition<Schema.Struct<{
+    topicId: Schema.String;
+    modelKey: Schema.String;
+}>, Schema.Void, Schema.String>, JobDefinition<Schema.Struct<{
+    modelKey: Schema.String;
+    topicKey: Schema.optional<Schema.String>;
+}>, Schema.Void, Schema.String>, JobDefinition<Schema.Struct<{
+    modelKey: Schema.String;
+    runId: Schema.optional<Schema.String>;
+}>, Schema.Void, Schema.String>, JobDefinition<Schema.Struct<{
+    modelKey: Schema.String;
+    runId: Schema.optional<Schema.String>;
+}>, Schema.Void, Schema.String>, JobDefinition<Schema.Struct<{
+    rows: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly queryHash: Schema.String;
+        readonly queryText: Schema.String;
+        readonly namespace: Schema.String;
+        readonly mode: Schema.String;
+        readonly queryProfile: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Null]>>;
+        readonly sources: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Null]>>;
+        readonly resultCount: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.Null]>>;
+        readonly latencyMs: Schema.Number;
+        readonly createdAt: Schema.Number;
+    }>>;
+}>, Schema.Void, Schema.String>];