@smthrs/engine-store 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/StepSandbox.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Injectable, scope-safe step sandboxing over the workspace transaction.
+ *
+ * @since 0.1.0
+ */
+import type * as ArtifactStore from "@smthrs/artifacts/ArtifactStore";
+import type * as KernelWorkspace from "@smthrs/kernel/Workspace";
+import * as Context from "effect/Context";
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import type * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as StepBoundary from "./StepBoundary.ts";
+import * as WorkspaceSandbox from "./WorkspaceSandbox.ts";
+declare const UndeclaredRead_base: Schema.Class<UndeclaredRead, Schema.TaggedStruct<"@smthrs/engine-store/UndeclaredRead", {
+    readonly code: Schema.Literal<"undeclared_read">;
+    readonly paths: Schema.$Array<Schema.String>;
+    readonly diffIdentity: Schema.NonEmptyString;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A hermetic body attempted to read a path outside its declared read set.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class UndeclaredRead extends UndeclaredRead_base {
+}
+/**
+ * A sandbox that can acquire an isolated workspace for one step.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly open: Effect.Effect<WorkspaceSandbox.Service, StepBoundary.UnsupportedBoundary>;
+}
+/**
+ * Injectable step-sandbox service.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare const StepSandbox: Context.Service<Service, Service>;
+/**
+ * Constructs a step sandbox around a workspace transaction backend.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (workspace: WorkspaceSandbox.Service) => Service;
+/**
+ * Filesystem-backed sandbox layer. The workspace transaction seeds only the
+ * declared reads, exposes its scoped FileSystem to the body, observes every
+ * mutation, and performs atomic copy-back on release. Built from
+ * `WorkspaceSandbox.layerFileSystem`, so it refuses a path-based host the same way.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<Service, WorkspaceSandbox.WorkspaceError, FileSystem.FileSystem | Path.Path | ArtifactStore.ArtifactStore | KernelWorkspace.Workspace>;
+/**
+ * Deterministic in-memory sandbox layer for tests.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerTest: (initialFiles?: WorkspaceSandbox.InitialFiles) => Layer.Layer<Service, WorkspaceSandbox.WorkspaceError, Crypto.Crypto>;
+/**
+ * Fail-closed host layer for environments that cannot sandbox (for example browsers).
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<Service>;
+export {};
+//# sourceMappingURL=StepSandbox.d.ts.map

package/dist/esm/StepSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StepSandbox.d.ts","sourceRoot":"","sources":["../../src/StepSandbox.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,KAAK,aAAa,MAAM,iCAAiC,CAAA;AACrE,OAAO,KAAK,KAAK,eAAe,MAAM,0BAA0B,CAAA;AAChE,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,KAAK,IAAI,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;;;;;;AAEzD;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,mBAOnC;CAAG;AAEJ;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,mBAAmB,CAAC,CAAA;CACzF;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAEzD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,WAAW,gBAAgB,CAAC,OAAO,KAAG,OAGvD,CAAA;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAC7B,OAAO,EACP,gBAAgB,CAAC,cAAc,EAC/B,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,aAAa,GAAG,eAAe,CAAC,SAAS,CAIpC,CAAA;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GACpB,eAAc,gBAAgB,CAAC,YAAiB,KAC/C,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,gBAAgB,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,CACgD,CAAA;AAOtH;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAK1C,CAAA"}

package/dist/esm/StepSandbox.js

@@ -0,0 +1,70 @@
+/**
+ * Injectable, scope-safe step sandboxing over the workspace transaction.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as StepBoundary from "./StepBoundary.js";
+import * as WorkspaceSandbox from "./WorkspaceSandbox.js";
+/**
+ * A hermetic body attempted to read a path outside its declared read set.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class UndeclaredRead extends Schema.TaggedError()("@smthrs/engine-store/UndeclaredRead", {
+    code: Schema.Literal("undeclared_read"),
+    paths: Schema.Array(Schema.String),
+    diffIdentity: Schema.NonEmptyString
+}) {
+}
+/**
+ * Injectable step-sandbox service.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export const StepSandbox = Context.Service("@smthrs/engine-store/StepSandbox");
+/**
+ * Constructs a step sandbox around a workspace transaction backend.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (workspace) => StepSandbox.of({
+    open: Effect.succeed(workspace)
+});
+/**
+ * Filesystem-backed sandbox layer. The workspace transaction seeds only the
+ * declared reads, exposes its scoped FileSystem to the body, observes every
+ * mutation, and performs atomic copy-back on release. Built from
+ * `WorkspaceSandbox.layerFileSystem`, so it refuses a path-based host the same way.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = Layer.effect(StepSandbox, Effect.map(WorkspaceSandbox.WorkspaceSandbox, make)).pipe(Layer.provide(WorkspaceSandbox.layerFileSystem()));
+/**
+ * Deterministic in-memory sandbox layer for tests.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerTest = (initialFiles = {}) => Layer.effect(StepSandbox, Effect.map(WorkspaceSandbox.makeMemory(initialFiles), (sandbox) => make(sandbox.service)));
+const unsupported = new StepBoundary.UnsupportedBoundary({
+    code: "unsupported_boundary",
+    message: "this host cannot provide a hermetic step sandbox"
+});
+/**
+ * Fail-closed host layer for environments that cannot sandbox (for example browsers).
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = Layer.succeed(StepSandbox, StepSandbox.of({
+    open: Effect.fail(unsupported)
+}));
+//# sourceMappingURL=StepSandbox.js.map

package/dist/esm/StepSandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StepSandbox.js","sourceRoot":"","sources":["../../src/StepSandbox.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,MAAM,CAAC,WAAW,EAAkB,CACtE,qCAAqC,EACrC;IACE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IAClC,YAAY,EAAE,MAAM,CAAC,cAAc;CACpC,CACF;CAAG;AAYJ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAsC,OAAO,CAAC,OAAO,CAC3E,kCAAkC,CACnC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,SAAmC,EAAW,EAAE,CACnE,WAAW,CAAC,EAAE,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC;CAChC,CAAC,CAAA;AAEJ;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,KAAK,GAId,KAAK,CAAC,MAAM,CACd,WAAW,EACX,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,IAAI,CAAC,CACpD,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,eAAe,EAAE,CAAC,CAAC,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,eAA8C,EAAE,EACsB,EAAE,CACxE,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAEtH,MAAM,WAAW,GAAG,IAAI,YAAY,CAAC,mBAAmB,CAAC;IACvD,IAAI,EAAE,sBAAsB;IAC5B,OAAO,EAAE,kDAAkD;CAC5D,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAyB,KAAK,CAAC,OAAO,CAC1D,WAAW,EACX,WAAW,CAAC,EAAE,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;CAC/B,CAAC,CACH,CAAA","sourcesContent":["/**\n * Injectable, scope-safe step sandboxing over the workspace transaction.\n *\n * @since 0.1.0\n */\n\nimport type * as ArtifactStore from \"@smthrs/artifacts/ArtifactStore\"\nimport type * as KernelWorkspace from \"@smthrs/kernel/Workspace\"\nimport * as Context from \"effect/Context\"\nimport type * as Crypto from \"effect/Crypto\"\nimport * as Effect from \"effect/Effect\"\nimport type * as FileSystem from \"effect/FileSystem\"\nimport * as Layer from \"effect/Layer\"\nimport type * as Path from \"effect/Path\"\nimport * as Schema from \"effect/Schema\"\nimport * as StepBoundary from \"./StepBoundary.ts\"\nimport * as WorkspaceSandbox from \"./WorkspaceSandbox.ts\"\n\n/**\n * A hermetic body attempted to read a path outside its declared read set.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class UndeclaredRead extends Schema.TaggedError<UndeclaredRead>()(\n  \"@smthrs/engine-store/UndeclaredRead\",\n  {\n    code: Schema.Literal(\"undeclared_read\"),\n    paths: Schema.Array(Schema.String),\n    diffIdentity: Schema.NonEmptyString\n  }\n) {}\n\n/**\n * A sandbox that can acquire an isolated workspace for one step.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  readonly open: Effect.Effect<WorkspaceSandbox.Service, StepBoundary.UnsupportedBoundary>\n}\n\n/**\n * Injectable step-sandbox service.\n *\n * @category services\n * @since 0.1.0\n */\nexport const StepSandbox: Context.Service<Service, Service> = Context.Service<Service>(\n  \"@smthrs/engine-store/StepSandbox\"\n)\n\n/**\n * Constructs a step sandbox around a workspace transaction backend.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = (workspace: WorkspaceSandbox.Service): Service =>\n  StepSandbox.of({\n    open: Effect.succeed(workspace)\n  })\n\n/**\n * Filesystem-backed sandbox layer. The workspace transaction seeds only the\n * declared reads, exposes its scoped FileSystem to the body, observes every\n * mutation, and performs atomic copy-back on release. Built from\n * `WorkspaceSandbox.layerFileSystem`, so it refuses a path-based host the same way.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer: Layer.Layer<\n  Service,\n  WorkspaceSandbox.WorkspaceError,\n  FileSystem.FileSystem | Path.Path | ArtifactStore.ArtifactStore | KernelWorkspace.Workspace\n> = Layer.effect(\n  StepSandbox,\n  Effect.map(WorkspaceSandbox.WorkspaceSandbox, make)\n).pipe(Layer.provide(WorkspaceSandbox.layerFileSystem()))\n\n/**\n * Deterministic in-memory sandbox layer for tests.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerTest = (\n  initialFiles: WorkspaceSandbox.InitialFiles = {}\n): Layer.Layer<Service, WorkspaceSandbox.WorkspaceError, Crypto.Crypto> =>\n  Layer.effect(StepSandbox, Effect.map(WorkspaceSandbox.makeMemory(initialFiles), (sandbox) => make(sandbox.service)))\n\nconst unsupported = new StepBoundary.UnsupportedBoundary({\n  code: \"unsupported_boundary\",\n  message: \"this host cannot provide a hermetic step sandbox\"\n})\n\n/**\n * Fail-closed host layer for environments that cannot sandbox (for example browsers).\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop: Layer.Layer<Service> = Layer.succeed(\n  StepSandbox,\n  StepSandbox.of({\n    open: Effect.fail(unsupported)\n  })\n)\n"]}

package/dist/esm/WakeBus.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The in-process wake bus: durable writes that make a run runnable — a
+ * deferred completed, a durable clock fired, an operator resume — announce
+ * the run id here, and in-process waiters parked on that run resume
+ * immediately instead of waiting out a poll tick.
+ *
+ * The bus is EDGE-TRIGGERED and MISS-TOLERANT by design. A wake published
+ * while nobody waits is dropped, not queued: durable state already records
+ * that the run is runnable, and the engine's suspension polling schedule
+ * (`suspendedRetryPolicy`) remains the bounded fallback that re-drives any
+ * run whose wake the bus missed. Temporal's scheduled task queue takes the
+ * same position — `NotifyNewTasks` is a coalesced, non-blocking channel send
+ * and `MaxPollInterval` bounds the polling fallback (`reference/temporal`
+ * `service/history/queues/queue_scheduled.go`) — because a lossless bus
+ * would have to be durable, and the durable record already exists. Waiter
+ * registration follows opencode's in-process job registry: one `Deferred`
+ * per waiter, succeeded on completion, removed when the waiter's own scope
+ * closes (`reference/opencode` `packages/smithers/flows/core/src/background-job.ts`).
+ *
+ * Cross-process wakes never reach this bus: another process's deferred
+ * completion is observed through the store, on the polling schedule and the
+ * heartbeat sweeps. That split is deliberate v1 scope — an event-driven
+ * cross-process wake needs a committed journal subscription, which is a
+ * separate seam.
+ *
+ * The bus holds no host access at all — a `Map` of `Deferred`s — so it is
+ * browser-safe without a platform layer.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+/**
+ * Wake bus operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    /**
+     * Announces that a durable write made the run runnable. Every waiter
+     * currently parked on `executionId` resumes; with no waiters the wake is
+     * dropped and the polling fallback covers the run.
+     */
+    readonly wake: (executionId: string) => Effect.Effect<void>;
+    /**
+     * Parks until the next {@link wake} for `executionId`. Registration is
+     * removed when the waiting fiber is interrupted — including scope closure
+     * and losing a race against the polling sleep — so an abandoned wait
+     * leaks nothing.
+     *
+     * The wait is keyed by execution id alone: execution ids are unique
+     * across flows, so the flow tag adds no discrimination.
+     */
+    readonly awaitWake: (executionId: string) => Effect.Effect<void>;
+    /**
+     * How many waiters are currently parked on `executionId`. This is
+     * observability for tests and diagnostics, not a coordination primitive:
+     * a count observed now says nothing about a moment later.
+     */
+    readonly waiters: (executionId: string) => Effect.Effect<number>;
+}
+declare const WakeBus_base: Context.ServiceClass<WakeBus, "@smthrs/engine-store/WakeBus", Service>;
+/**
+ * Service tag for the in-process wake bus.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class WakeBus extends WakeBus_base {
+}
+/**
+ * Constructs a wake bus. Registration and delivery are plain in-memory
+ * operations on the constructing process; nothing is durable.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeUnsafe: () => Service;
+/**
+ * Constructs a wake bus effectfully. Prefer this in compositions;
+ * {@link makeUnsafe} exists for construction outside a fiber.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: Effect.Effect<Service>;
+/**
+ * A bus that never delivers: wakes are dropped and waiters park forever.
+ * With it in place every resume travels the polling fallback — which is
+ * exactly what a test asserting the fallback provides it for.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides a fresh wake bus. An engine composition resolves the bus
+ * optionally, so providing this layer is how a host shares one bus between
+ * the engine and its own wake sources; a composition given none builds a
+ * private bus.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<WakeBus>;
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: (overrides?: Partial<Service>) => Layer.Layer<WakeBus>;
+export {};
+//# sourceMappingURL=WakeBus.d.ts.map

package/dist/esm/WakeBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WakeBus.d.ts","sourceRoot":"","sources":["../../src/WakeBus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC3D;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAChE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;CACjE;;AAED;;;;;GAKG;AACH,qBAAa,OAAQ,SAAQ,YAAmE;CAAG;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAAO,OAuC7B,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAA2B,CAAA;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,YAAY,OAAO,CAAC,OAAO,CAAC,KAAG,OAMpD,CAAA;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAmC,CAAA;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,YAAY,OAAO,CAAC,OAAO,CAAC,KAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAC5B,CAAA"}

package/dist/esm/WakeBus.js

@@ -0,0 +1,121 @@
+/**
+ * The in-process wake bus: durable writes that make a run runnable — a
+ * deferred completed, a durable clock fired, an operator resume — announce
+ * the run id here, and in-process waiters parked on that run resume
+ * immediately instead of waiting out a poll tick.
+ *
+ * The bus is EDGE-TRIGGERED and MISS-TOLERANT by design. A wake published
+ * while nobody waits is dropped, not queued: durable state already records
+ * that the run is runnable, and the engine's suspension polling schedule
+ * (`suspendedRetryPolicy`) remains the bounded fallback that re-drives any
+ * run whose wake the bus missed. Temporal's scheduled task queue takes the
+ * same position — `NotifyNewTasks` is a coalesced, non-blocking channel send
+ * and `MaxPollInterval` bounds the polling fallback (`reference/temporal`
+ * `service/history/queues/queue_scheduled.go`) — because a lossless bus
+ * would have to be durable, and the durable record already exists. Waiter
+ * registration follows opencode's in-process job registry: one `Deferred`
+ * per waiter, succeeded on completion, removed when the waiter's own scope
+ * closes (`reference/opencode` `packages/smithers/flows/core/src/background-job.ts`).
+ *
+ * Cross-process wakes never reach this bus: another process's deferred
+ * completion is observed through the store, on the polling schedule and the
+ * heartbeat sweeps. That split is deliberate v1 scope — an event-driven
+ * cross-process wake needs a committed journal subscription, which is a
+ * separate seam.
+ *
+ * The bus holds no host access at all — a `Map` of `Deferred`s — so it is
+ * browser-safe without a platform layer.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+/**
+ * Service tag for the in-process wake bus.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class WakeBus extends Context.Service()("@smthrs/engine-store/WakeBus") {
+}
+/**
+ * Constructs a wake bus. Registration and delivery are plain in-memory
+ * operations on the constructing process; nothing is durable.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeUnsafe = () => {
+    const parked = new Map();
+    return WakeBus.of({
+        wake: (executionId) => Effect.suspend(() => {
+            const waiters = parked.get(executionId);
+            if (waiters === undefined)
+                return Effect.void;
+            // Snapshot before succeeding: each woken waiter's release removes it
+            // from the live set, and delivery must not observe that mutation.
+            return Effect.forEach(Array.from(waiters), (waiter) => Deferred.succeed(waiter, undefined), { discard: true });
+        }),
+        awaitWake: (executionId) => Effect.acquireUseRelease(Effect.sync(() => {
+            const waiter = Deferred.makeUnsafe();
+            let waiters = parked.get(executionId);
+            if (waiters === undefined) {
+                waiters = new Set();
+                parked.set(executionId, waiters);
+            }
+            waiters.add(waiter);
+            return { waiter, waiters };
+        }), ({ waiter }) => Deferred.await(waiter), 
+        // The registration's own set is closed over rather than re-fetched:
+        // the map entry can only be deleted by the release that empties it,
+        // so the set this waiter joined is the set it must leave.
+        ({ waiter, waiters }) => Effect.sync(() => {
+            waiters.delete(waiter);
+            if (waiters.size === 0)
+                parked.delete(executionId);
+        })),
+        waiters: (executionId) => Effect.sync(() => parked.get(executionId)?.size ?? 0)
+    });
+};
+/**
+ * Constructs a wake bus effectfully. Prefer this in compositions;
+ * {@link makeUnsafe} exists for construction outside a fiber.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = Effect.sync(makeUnsafe);
+/**
+ * A bus that never delivers: wakes are dropped and waiters park forever.
+ * With it in place every resume travels the polling fallback — which is
+ * exactly what a test asserting the fallback provides it for.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeNoop = (overrides) => WakeBus.of({
+    wake: () => Effect.void,
+    awaitWake: () => Effect.never,
+    waiters: () => Effect.succeed(0),
+    ...overrides
+});
+/**
+ * Provides a fresh wake bus. An engine composition resolves the bus
+ * optionally, so providing this layer is how a host shares one bus between
+ * the engine and its own wake sources; a composition given none builds a
+ * private bus.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = Layer.sync(WakeBus)(makeUnsafe);
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = (overrides) => Layer.sync(WakeBus)(() => makeNoop(overrides));
+//# sourceMappingURL=WakeBus.js.map

package/dist/esm/WakeBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WakeBus.js","sourceRoot":"","sources":["../../src/WakeBus.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The in-process wake bus: durable writes that make a run runnable — a\n * deferred completed, a durable clock fired, an operator resume — announce\n * the run id here, and in-process waiters parked on that run resume\n * immediately instead of waiting out a poll tick.\n *\n * The bus is EDGE-TRIGGERED and MISS-TOLERANT by design. A wake published\n * while nobody waits is dropped, not queued: durable state already records\n * that the run is runnable, and the engine's suspension polling schedule\n * (`suspendedRetryPolicy`) remains the bounded fallback that re-drives any\n * run whose wake the bus missed. Temporal's scheduled task queue takes the\n * same position — `NotifyNewTasks` is a coalesced, non-blocking channel send\n * and `MaxPollInterval` bounds the polling fallback (`reference/temporal`\n * `service/history/queues/queue_scheduled.go`) — because a lossless bus\n * would have to be durable, and the durable record already exists. Waiter\n * registration follows opencode's in-process job registry: one `Deferred`\n * per waiter, succeeded on completion, removed when the waiter's own scope\n * closes (`reference/opencode` `packages/smithers/flows/core/src/background-job.ts`).\n *\n * Cross-process wakes never reach this bus: another process's deferred\n * completion is observed through the store, on the polling schedule and the\n * heartbeat sweeps. That split is deliberate v1 scope — an event-driven\n * cross-process wake needs a committed journal subscription, which is a\n * separate seam.\n *\n * The bus holds no host access at all — a `Map` of `Deferred`s — so it is\n * browser-safe without a platform layer.\n *\n * @since 0.1.0\n */\n\nimport * as Context from \"effect/Context\"\nimport * as Deferred from \"effect/Deferred\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\n\n/**\n * Wake bus operations.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  /**\n   * Announces that a durable write made the run runnable. Every waiter\n   * currently parked on `executionId` resumes; with no waiters the wake is\n   * dropped and the polling fallback covers the run.\n   */\n  readonly wake: (executionId: string) => Effect.Effect<void>\n  /**\n   * Parks until the next {@link wake} for `executionId`. Registration is\n   * removed when the waiting fiber is interrupted — including scope closure\n   * and losing a race against the polling sleep — so an abandoned wait\n   * leaks nothing.\n   *\n   * The wait is keyed by execution id alone: execution ids are unique\n   * across flows, so the flow tag adds no discrimination.\n   */\n  readonly awaitWake: (executionId: string) => Effect.Effect<void>\n  /**\n   * How many waiters are currently parked on `executionId`. This is\n   * observability for tests and diagnostics, not a coordination primitive:\n   * a count observed now says nothing about a moment later.\n   */\n  readonly waiters: (executionId: string) => Effect.Effect<number>\n}\n\n/**\n * Service tag for the in-process wake bus.\n *\n * @category services\n * @since 0.1.0\n */\nexport class WakeBus extends Context.Service<WakeBus, Service>()(\"@smthrs/engine-store/WakeBus\") {}\n\n/**\n * Constructs a wake bus. Registration and delivery are plain in-memory\n * operations on the constructing process; nothing is durable.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeUnsafe = (): Service => {\n  const parked = new Map<string, Set<Deferred.Deferred<void>>>()\n  return WakeBus.of({\n    wake: (executionId) =>\n      Effect.suspend(() => {\n        const waiters = parked.get(executionId)\n        if (waiters === undefined) return Effect.void\n        // Snapshot before succeeding: each woken waiter's release removes it\n        // from the live set, and delivery must not observe that mutation.\n        return Effect.forEach(\n          Array.from(waiters),\n          (waiter) => Deferred.succeed(waiter, undefined),\n          { discard: true }\n        )\n      }),\n    awaitWake: (executionId) =>\n      Effect.acquireUseRelease(\n        Effect.sync(() => {\n          const waiter = Deferred.makeUnsafe<void>()\n          let waiters = parked.get(executionId)\n          if (waiters === undefined) {\n            waiters = new Set()\n            parked.set(executionId, waiters)\n          }\n          waiters.add(waiter)\n          return { waiter, waiters }\n        }),\n        ({ waiter }) => Deferred.await(waiter),\n        // The registration's own set is closed over rather than re-fetched:\n        // the map entry can only be deleted by the release that empties it,\n        // so the set this waiter joined is the set it must leave.\n        ({ waiter, waiters }) =>\n          Effect.sync(() => {\n            waiters.delete(waiter)\n            if (waiters.size === 0) parked.delete(executionId)\n          })\n      ),\n    waiters: (executionId) => Effect.sync(() => parked.get(executionId)?.size ?? 0)\n  })\n}\n\n/**\n * Constructs a wake bus effectfully. Prefer this in compositions;\n * {@link makeUnsafe} exists for construction outside a fiber.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make: Effect.Effect<Service> = Effect.sync(makeUnsafe)\n\n/**\n * A bus that never delivers: wakes are dropped and waiters park forever.\n * With it in place every resume travels the polling fallback — which is\n * exactly what a test asserting the fallback provides it for.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeNoop = (overrides?: Partial<Service>): Service =>\n  WakeBus.of({\n    wake: () => Effect.void,\n    awaitWake: () => Effect.never,\n    waiters: () => Effect.succeed(0),\n    ...overrides\n  })\n\n/**\n * Provides a fresh wake bus. An engine composition resolves the bus\n * optionally, so providing this layer is how a host shares one bus between\n * the engine and its own wake sources; a composition given none builds a\n * private bus.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer: Layer.Layer<WakeBus> = Layer.sync(WakeBus)(makeUnsafe)\n\n/**\n * Provides {@link makeNoop}.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop = (overrides?: Partial<Service>): Layer.Layer<WakeBus> =>\n  Layer.sync(WakeBus)(() => makeNoop(overrides))\n"]}