@nwire/forge 0.9.1 → 0.10.0

package/dist/{cli-runner.js → helpers/cli-runner.js}

@@ -12,7 +12,7 @@
  *
  *   #!/usr/bin/env node
  *   import { runCli } from '@nwire/forge'
- *   import { boot } from './app/boot.js'
+ *   import { boot } from './app/boot'
  *
  *   const app = await boot()           // returns { learnflow: App }
  *   const exitCode = await runCli(app.learnflow, process.argv.slice(2))
@@ -43,14 +43,14 @@ export async function runCli(app, argv, options = {}) {
     }
     const targetName = argv[0];
     const rest = argv.slice(1);
-    // Try action first — actions write through the runtime's dispatch.
-    const action = findAction(app, targetName);
+    const dispatcher = app.dispatcher();
+    const action = dispatcher.findActionByName(targetName);
     if (action) {
         const { tenant, parsed } = parseFlags(rest);
         try {
             const validated = action.schema.parse(parsed);
             const envelope = tenant ? seedEnvelope({ tenant }) : undefined;
-            await app.runtime.dispatch(action, validated, envelope);
+            await app.dispatch(action, validated, envelope);
             stdout("OK");
             return 0;
         }
@@ -60,10 +60,10 @@ export async function runCli(app, argv, options = {}) {
         }
     }
     // Fall back to query.
-    if (app.runtime.listQueries().includes(targetName)) {
+    if (dispatcher.listQueries().includes(targetName)) {
         const { tenant, parsed } = parseFlags(rest);
         try {
-            const result = await app.runtime.query(targetName, parsed, tenant);
+            const result = await app.query(targetName, parsed, tenant);
             stdout(JSON.stringify(result, null, 2));
             return 0;
         }
@@ -75,32 +75,17 @@ export async function runCli(app, argv, options = {}) {
     stderr(`unknown action or query: "${targetName}". Run with --help for the list.`);
     return 1;
 }
-function findAction(app, name) {
-    return toActionMap(app)[name];
-}
-function toActionMap(app) {
-    const map = {};
-    for (const module of app.modules) {
-        for (const action of module.manifest.actions ?? []) {
-            map[action.name] = action;
-        }
-    }
-    return map;
-}
 function printHelp(app, stdout) {
+    const dispatcher = app.dispatcher();
     stdout("nwire — action CLI runner\n");
     stdout("Usage: amit <action-or-query-name> [--field value ...] [--tenant <id>]\n");
     stdout("Actions:");
-    for (const module of app.modules) {
-        for (const action of module.manifest.actions ?? []) {
-            stdout(`  ${action.name}${action.description ? "   — " + action.description.slice(0, 60) : ""}`);
-        }
+    for (const name of dispatcher.listHandlers()) {
+        stdout(`  ${name}`);
     }
     stdout("Queries:");
-    for (const module of app.modules) {
-        for (const query of module.manifest.queries ?? []) {
-            stdout(`  ${query.name}${query.description ? "   — " + query.description.slice(0, 60) : ""}`);
-        }
+    for (const name of dispatcher.listQueries()) {
+        stdout(`  ${name}`);
     }
 }
 function parseFlags(argv) {
@@ -161,4 +146,3 @@ function coerce(value) {
         return Number(value);
     return value;
 }
-//# sourceMappingURL=cli-runner.js.map

package/dist/{public-marker.d.ts → helpers/public-marker.d.ts}

@@ -32,4 +32,3 @@ export declare function isPublic(def: {
  * re-installed so the clone remains markable (idempotent).
  */
 export declare function markable<T extends object>(def: T): T & PublicMarker;
-//# sourceMappingURL=public-marker.d.ts.map

package/dist/{public-marker.js → helpers/public-marker.js}

@@ -42,4 +42,3 @@ export function markable(def) {
     });
     return enriched;
 }
-//# sourceMappingURL=public-marker.js.map

package/dist/{response.d.ts → helpers/response.d.ts}

@@ -5,4 +5,3 @@
  * the same export names so existing call sites compile unchanged.
  */
 export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, type ResponseSpec, type ListResponseSpec, type ResponseInstance, type ResponseSpecBase, type ResponseKind, } from "@nwire/handler";
-//# sourceMappingURL=response.d.ts.map

package/dist/{response.js → helpers/response.js}

@@ -5,4 +5,3 @@
  * the same export names so existing call sites compile unchanged.
  */
 export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, } from "@nwire/handler";
-//# sourceMappingURL=response.js.map

package/dist/helpers/retry-helpers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Retry-loop helpers shared between forge's dispatch path and the
+ * external-call execution path. Lives in its own file so both
+ * `runtime.ts` and `forge-dispatcher.ts` can import without circles.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Compute the delay before attempt `attemptIndex` (1-indexed) given a
+ * retry config. Returns 0 when no retry is configured. Exponential by
+ * default with `2^(attemptIndex-1) * baseDelayMs`, capped at `maxDelayMs`;
+ * `backoff: "fixed"` uses `baseDelayMs` flat.
+ */
+export declare function computeBackoff(retry: {
+    backoff?: "exponential" | "fixed";
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+} | undefined, attemptIndex: number): number;
+/**
+ * Parse a delay string like '3d', '90s', '4h' into milliseconds.
+ * Supports: ms, s, m, h, d. Numbers without units treated as ms.
+ */
+export declare function parseDelay(value: string): number;

package/dist/helpers/retry-helpers.js

@@ -0,0 +1,43 @@
+/**
+ * Retry-loop helpers shared between forge's dispatch path and the
+ * external-call execution path. Lives in its own file so both
+ * `runtime.ts` and `forge-dispatcher.ts` can import without circles.
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Compute the delay before attempt `attemptIndex` (1-indexed) given a
+ * retry config. Returns 0 when no retry is configured. Exponential by
+ * default with `2^(attemptIndex-1) * baseDelayMs`, capped at `maxDelayMs`;
+ * `backoff: "fixed"` uses `baseDelayMs` flat.
+ */
+export function computeBackoff(retry, attemptIndex) {
+    if (!retry)
+        return 0;
+    const base = retry.baseDelayMs ?? 100;
+    const cap = retry.maxDelayMs ?? 30_000;
+    if (retry.backoff === "fixed")
+        return Math.min(base, cap);
+    return Math.min(Math.floor(Math.pow(2, attemptIndex - 1) * base), cap);
+}
+/**
+ * Parse a delay string like '3d', '90s', '4h' into milliseconds.
+ * Supports: ms, s, m, h, d. Numbers without units treated as ms.
+ */
+export function parseDelay(value) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)?$/.exec(value);
+    if (!match) {
+        throw new Error(`Runtime: cannot parse delay "${value}". Expected '3d', '90s', '4h', '500ms'.`);
+    }
+    const n = Number(match[1]);
+    const unit = match[2] ?? "ms";
+    const multipliers = {
+        ms: 1,
+        s: 1000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+    };
+    return n * (multipliers[unit] ?? 1);
+}

package/dist/{validate.d.ts → helpers/validate.d.ts}

@@ -30,4 +30,3 @@ export type Invariant<TInput, TState = unknown> = (input: TInput, state: TState)
 export declare function validate<TInput, TState = unknown>(input: TInput, predicates: ReadonlyArray<Invariant<TInput, TState>>, state?: TState): void;
 /** Type-narrowing predicate. */
 export declare function isInvariantError(x: unknown): x is InvariantError;
-//# sourceMappingURL=validate.d.ts.map

package/dist/{validate.js → helpers/validate.js}

@@ -45,4 +45,3 @@ export function validate(input, predicates, state) {
 export function isInvariantError(x) {
     return x instanceof InvariantError;
 }
-//# sourceMappingURL=validate.js.map

package/dist/index.d.ts

@@ -1,55 +1,49 @@
 /**
- * `@nwire/forge` — the framework's public surface.
+ * `@nwire/forge` — CQRS engine delivered as an app plugin.
  *
- * The center of gravity is the action as intent. Resolvers wrap actions for
- * transport; workflows wire events to effects (reactions, translators, sagas
- * — one primitive). Actors carry state when entities need identity over time.
- * Projections + queries are the read side.
+ *   import { createApp } from "@nwire/app";
+ *   import { forgePlugin } from "@nwire/forge";
  *
- * Surface at a glance:
- *   - defineAction, defineEvent  (events re-exported from @nwire/messages)
- *   - defineHandler, defineActor, defineWorkflow
- *   - defineProjection, defineQuery
- *   - defineResource, defineError
- *   - defineModule, defineApp, createApp
- *   - ctx verbs (in handlers + resolvers): request, send, use, query
- *   - .public() marks an item exposed across module boundaries
+ *   const app = createApp({ appName: "orders", plugins: [forgePlugin, …] });
+ *
+ * Or via the convenience wrapper that auto-installs forgePlugin and adds
+ * the dispatch/publish/query/… verbs as methods on the app handle:
+ *
+ *   import { createForgeApp } from "@nwire/forge";
+ *
+ *   const app = createForgeApp({ name: "orders", handlers, actors, … });
  */
-export { defineAction, isCommandMessage, resolveDispatch, type ActionDefinition, type CallableActionDefinition, type CommandMessage, type ActionMeta, type ActionInput, type ActionResult, type ActionPolicy, type NwireActionRegistry, } from "./define-action.js";
-export { defineActor, eventKey, type ActorDefinition, type ActorOptions, type ActorOptionsBound, type ActorReaction, type ActorStateConfig, type ActorTimerSpec, type ActorMethod, type ActorInstanceView, } from "./define-actor.js";
-export { defineSchema, isSchemaDefinition, type SchemaDefinition, type SchemaOptions, type SchemaStateSpec, type SchemaStorageHints, } from "./define-schema.js";
-export { validate, isInvariantError, InvariantError, type Invariant } from "./validate.js";
-export { defineHandler, type HandlerContext, type HandlerDefinition, type HandlerReturn, } from "./define-handler.js";
-export { eventFactory, isEventMessage, normalizeEventReturn, type EventMessage, type EventFactory, } from "./event-message.js";
-export { assertModuleSurface, type ExpectedSurface } from "./module-surface.js";
-export { InMemoryWorkflowTimerStore, timerEventName, type WorkflowTimer, type WorkflowTimerStore, } from "./workflow-timer-store.js";
-export { isPublic, type PublicMarker } from "./public-marker.js";
-export { defineWorkflow, COMPLETE_EVENT_NAME, type WorkflowDefinition, type WorkflowContext, type StatelessWorkflowContext, type StatefulWorkflowContext, type WorkflowEffects, type WorkflowOptions, type StatelessWorkflowOptions, type StatefulWorkflowOptions, type WorkflowOnOptions, type WorkflowRetryPolicy, type WorkflowStateSpec, type WorkflowInstance, type WorkflowCorrelateMap, type FireContext, type CompleteEvent, type StateCallable, type TimerDefinition, } from "./define-workflow.js";
-export { defineExternalCall, type ExternalCallDefinition, type ExternalCallMeta, type ExternalCallTarget, type ExternalCallSlo, type ExternalCallRetry, type ExternalCallExecutor, } from "./define-external-call.js";
-export { defineInboundWebhook, type InboundWebhookDefinition, type InboundWebhookMeta, type WebhookSignatureVerifier, type WebhookDedupe, } from "./define-inbound-webhook.js";
-export { defineOutbox, type OutboxDefinition, type OutboxMeta } from "./define-outbox.js";
-export { defineInbox, type InboxDefinition, type InboxMeta } from "./define-inbox.js";
-export { defineCron, type CronDefinition, type CronMeta } from "./define-cron.js";
-export { Runtime, parseDelay, type RuntimeOptions, type RuntimeContract, type DispatchMiddleware, type Telemetry, type TelemetryRecord, type TelemetryEventKind, type TelemetryListener, type SerializedError, } from "./runtime.js";
-export { defineFrameworkEvent, AppRegistering, AppBooting, AppBooted, AppReady, AppShuttingDown, AppShutdown, ActionDispatching, ActionCompleted, ActionFailed, EventRecording, EventRecorded, builtInFrameworkEvents, type FrameworkEventDefinition, type FrameworkEventMode, } from "./framework-events.js";
-export { FrameworkEventBus, type FrameworkEventHandler } from "./framework-event-bus.js";
-export { InMemoryActorStore, createInitialInstance, ActorVersionConflictError, type ActorStore, type ActorInstance, type ActorSaveOptions, type ActorTimerHandle, } from "./actor-store.js";
-export { runCli, type RunCliOptions } from "./cli-runner.js";
+export { forgePlugin, createForgePlugin, FORGE_DISPATCHER_BINDING, } from "./runtime/forge-plugin.js";
+export { ForgeDispatcher, type ForgeDispatcherOptions } from "./runtime/forge-dispatcher.js";
+export type { ForgeTelemetry, DispatchOptions, ActionBeforeHookCtx, ActionAfterHookCtx, ActorTransitionHookCtx, WorkflowFireHookCtx, } from "./runtime/forge-types.js";
+export { createForgeApp, type ForgeApp, type ForgeAppOptions, } from "./runtime/create-forge-app.js";
+export { defineAction, isCommandMessage, resolveDispatch, type ActionDefinition, type CallableActionDefinition, type CommandMessage, type ActionMeta, type ActionInput, type ActionResult, type ActionPolicy, type NwireActionRegistry, type RetryPolicy, } from "./primitives/define-action.js";
+export { defineActor, eventKey, type ActorDefinition, type ActorOptions, type ActorOptionsBound, type ActorReaction, type ActorStateConfig, type ActorTimerSpec, type ActorMethod, type ActorInstanceView, } from "./primitives/define-actor.js";
+export { defineSchema, isSchemaDefinition, type SchemaDefinition, type SchemaOptions, type SchemaStateSpec, type SchemaStorageHints, } from "./primitives/define-schema.js";
+export { validate, isInvariantError, InvariantError, type Invariant } from "./helpers/validate.js";
+export { defineHandler, type HandlerContext, type HandlerDefinition, type HandlerReturn, } from "./primitives/define-handler.js";
+export { eventFactory, isEventMessage, normalizeEventReturn, type EventMessage, type EventFactory, } from "./messages/event-message.js";
+export { defineWorkflow, COMPLETE_EVENT_NAME, type WorkflowDefinition, type WorkflowContext, type StatelessWorkflowContext, type StatefulWorkflowContext, type WorkflowEffects, type WorkflowOptions, type StatelessWorkflowOptions, type StatefulWorkflowOptions, type WorkflowOnOptions, type WorkflowRetryPolicy, type WorkflowStateSpec, type WorkflowInstance, type WorkflowCorrelateMap, type FireContext, type CompleteEvent, type StateCallable, type TimerDefinition, } from "./primitives/define-workflow.js";
+export { defineProjection, type ProjectionDefinition, type ProjectionOptions, type ProjectionReducer, } from "./primitives/define-projection.js";
+export { defineQuery, type QueryDefinition, type QueryOptions } from "./primitives/define-query.js";
+export { defineUpcaster, applyUpcasters, type UpcasterDefinition } from "./primitives/define-upcaster.js";
+export { defineExternalCall, type ExternalCallDefinition, type ExternalCallMeta, type ExternalCallTarget, type ExternalCallSlo, type ExternalCallRetry, type ExternalCallExecutor, } from "./primitives/define-external-call.js";
+export { defineInboundWebhook, type InboundWebhookDefinition, type InboundWebhookMeta, type WebhookSignatureVerifier, type WebhookDedupe, } from "./primitives/define-inbound-webhook.js";
+export { defineOutbox, type OutboxDefinition, type OutboxMeta } from "./primitives/define-outbox.js";
+export { defineInbox, type InboxDefinition, type InboxMeta } from "./primitives/define-inbox.js";
+export { defineCron, type CronDefinition, type CronMeta } from "./primitives/define-cron.js";
+export { defineError, isNwireError, NwireError, Unauthorized, Forbidden, NotFound, Gone, BadRequest, Conflict, type ErrorDefinition, type ErrorMeta, } from "./primitives/define-error.js";
+export { InMemoryActorStore, createInitialInstance, ActorVersionConflictError, type ActorStore, type ActorInstance, type ActorSaveOptions, type ActorTimerHandle, } from "./stores/actor-store.js";
+export { InMemoryProjectionStore, type ProjectionStore } from "./stores/projection-store.js";
+export { InMemoryIdempotencyStore, type IdempotencyStore } from "./stores/idempotency-store.js";
+export { InMemoryWorkflowTimerStore, timerEventName, type WorkflowTimer, type WorkflowTimerStore, } from "./stores/workflow-timer-store.js";
+export { parseDelay } from "./helpers/retry-helpers.js";
+export { isPublic, type PublicMarker } from "./helpers/public-marker.js";
+export { attachDevLogger, formatTelemetry, type DevLoggerOptions } from "./observability/dev-logger.js";
+export { runCli, type RunCliOptions } from "./helpers/cli-runner.js";
 export { NoopLogger, ConsoleLogger, loggerForEnvelope, type Logger } from "@nwire/logger";
 export { InMemoryDeadLetterSink, buildDeadLetterEntry, type DeadLetterSink, type DeadLetterEntry, } from "@nwire/dead-letter";
-export type { RetryPolicy } from "./define-action.js";
-export type { DispatchOptions } from "./runtime.js";
-export { defineProjection, type ProjectionDefinition, type ProjectionOptions, type ProjectionReducer, } from "./define-projection.js";
-export { InMemoryProjectionStore, type ProjectionStore } from "./projection-store.js";
-export { InMemoryIdempotencyStore, type IdempotencyStore } from "./idempotency-store.js";
-export { defineQuery, type QueryDefinition, type QueryOptions } from "./define-query.js";
-export { defineUpcaster, applyUpcasters, type UpcasterDefinition } from "./define-upcaster.js";
-export { defineModule, type ModuleDefinition, type ModuleManifest, type ModuleNeeds, } from "./define-module.js";
-export { createApp, type App, type CreateAppOptions, type TimerSchedulerOptions, } from "./create-app.js";
-export { attachDevLogger, formatTelemetry, type DevLoggerOptions } from "./dev-logger.js";
-export { defineApp, type AppDefinition, type DefineAppOptions, type EndpointDefinition, type TenantModel, } from "./define-app.js";
-export { definePlugin, type PluginDefinition, type PluginOptions, type PluginContext, type PluginSetup, type PluginActorHooks, type ActorTransitionHook, } from "./define-plugin.js";
 export { defineResource, isResourceDefinition, type ResourceDefinition, type DefineResourceOptions, } from "@nwire/handler";
-export { defineError, isNwireError, NwireError, Unauthorized, Forbidden, NotFound, Gone, BadRequest, Conflict, type ErrorDefinition, type ErrorMeta, } from "./define-error.js";
-export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, type ResponseSpec, type ListResponseSpec, type ResponseInstance, type ResponseKind, } from "./response.js";
-//# sourceMappingURL=index.d.ts.map
+export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, type ResponseSpec, type ListResponseSpec, type ResponseInstance, type ResponseKind, } from "./helpers/response.js";
+import "./framework-events";
+export type { FrameworkHooks, PluginKind } from "@nwire/app";

package/dist/index.js

@@ -1,62 +1,54 @@
 /**
- * `@nwire/forge` — the framework's public surface.
+ * `@nwire/forge` — CQRS engine delivered as an app plugin.
  *
- * The center of gravity is the action as intent. Resolvers wrap actions for
- * transport; workflows wire events to effects (reactions, translators, sagas
- * — one primitive). Actors carry state when entities need identity over time.
- * Projections + queries are the read side.
+ *   import { createApp } from "@nwire/app";
+ *   import { forgePlugin } from "@nwire/forge";
  *
- * Surface at a glance:
- *   - defineAction, defineEvent  (events re-exported from @nwire/messages)
- *   - defineHandler, defineActor, defineWorkflow
- *   - defineProjection, defineQuery
- *   - defineResource, defineError
- *   - defineModule, defineApp, createApp
- *   - ctx verbs (in handlers + resolvers): request, send, use, query
- *   - .public() marks an item exposed across module boundaries
+ *   const app = createApp({ appName: "orders", plugins: [forgePlugin, …] });
+ *
+ * Or via the convenience wrapper that auto-installs forgePlugin and adds
+ * the dispatch/publish/query/… verbs as methods on the app handle:
+ *
+ *   import { createForgeApp } from "@nwire/forge";
+ *
+ *   const app = createForgeApp({ name: "orders", handlers, actors, … });
  */
-export { defineAction, isCommandMessage, resolveDispatch, } from "./define-action.js";
-export { defineActor, eventKey, } from "./define-actor.js";
-export { defineSchema, isSchemaDefinition, } from "./define-schema.js";
-export { validate, isInvariantError, InvariantError } from "./validate.js";
-export { defineHandler, } from "./define-handler.js";
-export { eventFactory, isEventMessage, normalizeEventReturn, } from "./event-message.js";
-export { assertModuleSurface } from "./module-surface.js";
-export { InMemoryWorkflowTimerStore, timerEventName, } from "./workflow-timer-store.js";
-export { isPublic } from "./public-marker.js";
-export { defineWorkflow, COMPLETE_EVENT_NAME, } from "./define-workflow.js";
-// ─── Orchestrator primitives ──────────────────────────
-export { defineExternalCall, } from "./define-external-call.js";
-export { defineInboundWebhook, } from "./define-inbound-webhook.js";
-export { defineOutbox } from "./define-outbox.js";
-export { defineInbox } from "./define-inbox.js";
-export { defineCron } from "./define-cron.js";
-export { Runtime, parseDelay, } from "./runtime.js";
-// ─── Framework events ───────────────────────────────────────────
-export { defineFrameworkEvent, AppRegistering, AppBooting, AppBooted, AppReady, AppShuttingDown, AppShutdown, ActionDispatching, ActionCompleted, ActionFailed, EventRecording, EventRecorded, builtInFrameworkEvents, } from "./framework-events.js";
-export { FrameworkEventBus } from "./framework-event-bus.js";
-export { InMemoryActorStore, createInitialInstance, ActorVersionConflictError, } from "./actor-store.js";
-// File-snapshot store extracted to `@nwire/store-file`.
-// Mongo stores extracted to `@nwire/store-mongo`.
-// Forge ships only interfaces + InMemory defaults; persistent adapters
-// are separate packages consumers add as needed.
-// Queue transport + createQueueWorker live in `@nwire/queue` (consumers
-// import from there directly to avoid a forge ↔ queue dep cycle).
-export { runCli } from "./cli-runner.js";
+// ─── Plugin + composition ──────────────────────────────────────────
+export { forgePlugin, createForgePlugin, FORGE_DISPATCHER_BINDING, } from "./runtime/forge-plugin.js";
+export { ForgeDispatcher } from "./runtime/forge-dispatcher.js";
+export { createForgeApp, } from "./runtime/create-forge-app.js";
+// ─── Domain primitives ─────────────────────────────────────────────
+export { defineAction, isCommandMessage, resolveDispatch, } from "./primitives/define-action.js";
+export { defineActor, eventKey, } from "./primitives/define-actor.js";
+export { defineSchema, isSchemaDefinition, } from "./primitives/define-schema.js";
+export { validate, isInvariantError, InvariantError } from "./helpers/validate.js";
+export { defineHandler, } from "./primitives/define-handler.js";
+export { eventFactory, isEventMessage, normalizeEventReturn, } from "./messages/event-message.js";
+export { defineWorkflow, COMPLETE_EVENT_NAME, } from "./primitives/define-workflow.js";
+export { defineProjection, } from "./primitives/define-projection.js";
+export { defineQuery } from "./primitives/define-query.js";
+export { defineUpcaster, applyUpcasters } from "./primitives/define-upcaster.js";
+export { defineExternalCall, } from "./primitives/define-external-call.js";
+export { defineInboundWebhook, } from "./primitives/define-inbound-webhook.js";
+export { defineOutbox } from "./primitives/define-outbox.js";
+export { defineInbox } from "./primitives/define-inbox.js";
+export { defineCron } from "./primitives/define-cron.js";
+export { defineError, isNwireError, NwireError, Unauthorized, Forbidden, NotFound, Gone, BadRequest, Conflict, } from "./primitives/define-error.js";
+// ─── Stores ────────────────────────────────────────────────────────
+export { InMemoryActorStore, createInitialInstance, ActorVersionConflictError, } from "./stores/actor-store.js";
+export { InMemoryProjectionStore } from "./stores/projection-store.js";
+export { InMemoryIdempotencyStore } from "./stores/idempotency-store.js";
+export { InMemoryWorkflowTimerStore, timerEventName, } from "./stores/workflow-timer-store.js";
+// ─── Helpers ───────────────────────────────────────────────────────
+export { parseDelay } from "./helpers/retry-helpers.js";
+export { isPublic } from "./helpers/public-marker.js";
+export { attachDevLogger, formatTelemetry } from "./observability/dev-logger.js";
+export { runCli } from "./helpers/cli-runner.js";
+// ─── Re-exports from neighbours ────────────────────────────────────
 export { NoopLogger, ConsoleLogger, loggerForEnvelope } from "@nwire/logger";
 export { InMemoryDeadLetterSink, buildDeadLetterEntry, } from "@nwire/dead-letter";
-export { defineProjection, } from "./define-projection.js";
-export { InMemoryProjectionStore } from "./projection-store.js";
-export { InMemoryIdempotencyStore } from "./idempotency-store.js";
-export { defineQuery } from "./define-query.js";
-export { defineUpcaster, applyUpcasters } from "./define-upcaster.js";
-export { defineModule, } from "./define-module.js";
-export { createApp, } from "./create-app.js";
-export { attachDevLogger, formatTelemetry } from "./dev-logger.js";
-export { defineApp, } from "./define-app.js";
-export { definePlugin, } from "./define-plugin.js";
-// ─── Interface / app layer primitives ────────────────────────────
 export { defineResource, isResourceDefinition, } from "@nwire/handler";
-export { defineError, isNwireError, NwireError, Unauthorized, Forbidden, NotFound, Gone, BadRequest, Conflict, } from "./define-error.js";
-export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, } from "./response.js";
-//# sourceMappingURL=index.js.map
+export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, } from "./helpers/response.js";
+// Module augmentation side effect — adds Action* / Event* slots to
+// FrameworkHooks on @nwire/app's runtime.
+import "./framework-events";

package/dist/{event-message.d.ts → messages/event-message.d.ts}

@@ -41,4 +41,3 @@ export declare function isEventMessage(value: unknown): value is EventMessage;
  * via `runtime.dispatch`'s return + the `ActionCompleted` event.
  */
 export declare function normalizeEventReturn(value: void | EventMessage | EventMessage[] | Record<string, unknown> | null | undefined): EventMessage[];
-//# sourceMappingURL=event-message.d.ts.map

package/dist/{event-message.js → messages/event-message.js}

@@ -55,4 +55,3 @@ export function normalizeEventReturn(value) {
         return value.filter(isEventMessage);
     return isEventMessage(value) ? [value] : [];
 }
-//# sourceMappingURL=event-message.js.map

package/dist/{dev-logger.d.ts → observability/dev-logger.d.ts}

@@ -15,7 +15,8 @@
  * Orchestrator + queue/cron records are suppressed by default to keep
  * the firehose readable.
  */
-import type { Runtime, Telemetry } from "./runtime.js";
+import type { Runtime } from "@nwire/app";
+import type { ForgeTelemetry as Telemetry } from "../runtime/forge-types.js";
 export interface DevLoggerOptions {
     /**
      * Filter — only records whose `kind` matches one of these is printed.
@@ -38,4 +39,3 @@ export declare function formatTelemetry(rec: Telemetry): string;
  * stores the unsubscribe and calls it in stop().
  */
 export declare function attachDevLogger(runtime: Runtime, options?: DevLoggerOptions): () => void;
-//# sourceMappingURL=dev-logger.d.ts.map

package/dist/{dev-logger.js → observability/dev-logger.js}

@@ -24,7 +24,6 @@ const DEFAULT_KINDS = [
     "reaction.failed",
     "dlq.recorded",
     "query.executed",
-    "lifecycle",
     "hook.step",
 ];
 /**
@@ -104,34 +103,6 @@ export function formatTelemetry(rec) {
             const err = rec.error ? ` ${color(rec.error.message, RED)}` : "";
             return `${dim(t)} ${phaseGlyph} ${tag}${padded} ${rec.hookName}:${stepLabel}${dur}${err}`;
         }
-        case "lifecycle": {
-            // Namespaced lifecycle log: render `nwire:<ns>` colored by phase
-            // (app / plugin / wire / hook) so the eye groups events by axis.
-            // Pad the visible tag width to 14 chars so subsequent columns
-            // line up regardless of which namespace.
-            const visibleTag = `nwire:${rec.namespace}`;
-            const padded = visibleTag.padEnd(14, " ");
-            const tag = namespaceTag(rec.namespace) + padded.slice(visibleTag.length);
-            const marker = rec.phase === "prevented" ? color("✗", RED) : color("•", DIM);
-            // Strip the leading `nwire.` from the event name — every event has
-            // it; printing it once via the colored tag is enough.
-            const shortName = rec.event.replace(/^nwire\./, "");
-            // Pull the most useful 1-2 fields out of the payload for context.
-            const p = rec.payload;
-            const ctx = [];
-            if (p) {
-                if (typeof p["pluginName"] === "string")
-                    ctx.push(p["pluginName"]);
-                if (typeof p["transport"] === "string")
-                    ctx.push(p["transport"]);
-                if (typeof p["reason"] === "string")
-                    ctx.push(p["reason"]);
-                if (typeof p["durationMs"] === "number")
-                    ctx.push(`${p["durationMs"]}ms`);
-            }
-            const ctxLine = ctx.length > 0 ? ` ${dim(ctx.join(" · "))}` : "";
-            return `${dim(t)} ${marker} ${tag} ${shortName}${ctxLine}`;
-        }
         default:
             return `${dim(t)} ${rec.kind}`;
     }
@@ -153,4 +124,3 @@ export function attachDevLogger(runtime, options) {
             write(line);
     });
 }
-//# sourceMappingURL=dev-logger.js.map

package/dist/{define-action.d.ts → primitives/define-action.d.ts}

@@ -223,4 +223,3 @@ export declare function resolveDispatch(actionOrCmd: ActionDefinition | CommandM
     action: ActionDefinition;
     input: unknown;
 };
-//# sourceMappingURL=define-action.d.ts.map

package/dist/{define-action.js → primitives/define-action.js}

@@ -126,4 +126,3 @@ export function resolveDispatch(actionOrCmd, input, lookup) {
     }
     return { action: actionOrCmd, input };
 }
-//# sourceMappingURL=define-action.js.map

package/dist/{define-actor.d.ts → primitives/define-actor.d.ts}

@@ -301,4 +301,3 @@ export declare function defineActor<TFields extends Readonly<Record<string, ZodT
  * call sites where the import is shorter.
  */
 export declare function eventKey(event: EventDefinition): string;
-//# sourceMappingURL=define-actor.d.ts.map

package/dist/{define-actor.js → primitives/define-actor.js}

@@ -298,4 +298,3 @@ function buildEventIndex(states) {
 export function eventKey(event) {
     return event.name;
 }
-//# sourceMappingURL=define-actor.js.map

package/dist/{define-cron.d.ts → primitives/define-cron.d.ts}

@@ -47,4 +47,3 @@ export interface CronDefinition {
     readonly tags?: readonly string[];
 }
 export declare function defineCron(meta: CronMeta): CronDefinition;
-//# sourceMappingURL=define-cron.d.ts.map

package/dist/{define-cron.js → primitives/define-cron.js}

@@ -31,4 +31,3 @@ export function defineCron(meta) {
         tags: meta.tags,
     };
 }
-//# sourceMappingURL=define-cron.js.map

package/dist/{define-error.d.ts → primitives/define-error.d.ts}

@@ -7,4 +7,3 @@
  * import line.
  */
 export { defineError, isNwireError, NwireError, Unauthorized, Forbidden, NotFound, Gone, BadRequest, Conflict, type ErrorDefinition, type ErrorMeta, } from "@nwire/handler";
-//# sourceMappingURL=define-error.d.ts.map

package/dist/{define-error.js → primitives/define-error.js}

@@ -7,4 +7,3 @@
  * import line.
  */
 export { defineError, isNwireError, NwireError, Unauthorized, Forbidden, NotFound, Gone, BadRequest, Conflict, } from "@nwire/handler";
-//# sourceMappingURL=define-error.js.map

package/dist/{define-external-call.d.ts → primitives/define-external-call.d.ts}

@@ -82,4 +82,3 @@ export type ExternalCallExecutor<TRequest extends ZodTypeAny = ZodTypeAny, TResp
     readonly idempotencyKey?: string;
     readonly attempt: number;
 }) => Promise<z.output<TResponse>>;
-//# sourceMappingURL=define-external-call.d.ts.map

package/dist/{define-external-call.js → primitives/define-external-call.js}

@@ -35,4 +35,3 @@ export function defineExternalCall(meta) {
         tags: meta.tags,
     };
 }
-//# sourceMappingURL=define-external-call.js.map

package/dist/{define-handler.d.ts → primitives/define-handler.d.ts}

@@ -30,7 +30,7 @@ import type { z } from "zod";
 import type { ZodTypeAny, SourceLocation } from "@nwire/messages";
 import type { Container } from "@nwire/container";
 import type { MessageEnvelope } from "@nwire/envelope";
-import type { EventMessage } from "./event-message.js";
+import type { EventMessage } from "../messages/event-message.js";
 import type { ActionDefinition, ActionInput, ActionResult } from "./define-action.js";
 import type { ActorDefinition, ActorInstanceView } from "./define-actor.js";
 import type { QueryDefinition } from "./define-query.js";
@@ -123,12 +123,39 @@ export interface HandlerContext {
  *   at runtime by the missing `eventName` + `payload` shape.
  */
 export type HandlerReturn = void | EventMessage | EventMessage[] | Record<string, unknown> | null;
+/**
+ * Outer-ctx shape `HandlerDefinition.run` consumes. Matches what
+ * `@nwire/app`'s `Runtime.execute` builds: `input`, `envelope`, and a
+ * `resolve` looking up bindings on the per-request scope. Forge's `.run`
+ * implementation pulls the forge dispatcher off the container and
+ * delegates so the full dispatcher pipeline (validation, action.before/
+ * after hooks, retry, telemetry, persistence, …) fires.
+ */
+export interface HandlerRunCtx<TSchema extends ZodTypeAny = ZodTypeAny> {
+    readonly input: z.output<TSchema>;
+    readonly envelope?: MessageEnvelope;
+    resolve<T = unknown>(name: string): T;
+}
+export interface HandlerRunOptions {
+    readonly signal?: AbortSignal;
+}
 export interface HandlerDefinition<TSchema extends ZodTypeAny = ZodTypeAny> {
     readonly $kind: "handler";
     readonly action: ActionDefinition<TSchema>;
     readonly handler: (input: z.output<TSchema>, ctx: HandlerContext) => Promise<HandlerReturn> | HandlerReturn;
     /** Where the handler was declared. Studio uses this for IDE-open links. */
     readonly $source?: SourceLocation;
+    /**
+     * Forge handlers satisfy the `@nwire/handler.HandlerDefinition` shape
+     * structurally so `Runtime.execute(handler, input, envelope)` works
+     * directly without the adopter knowing about forge. The fields below
+     * expose the metadata `Runtime` reads + the canonical `run()` entry
+     * point that routes through the forge dispatcher.
+     */
+    readonly name: string;
+    readonly input: TSchema;
+    run(ctx: HandlerRunCtx<TSchema>, opts?: HandlerRunOptions): Promise<{
+        result: ActionResult<ActionDefinition<TSchema>>;
+    }>;
 }
 export declare function defineHandler<TSchema extends ZodTypeAny>(action: ActionDefinition<TSchema>, handler: HandlerDefinition<TSchema>["handler"]): HandlerDefinition<TSchema>;
-//# sourceMappingURL=define-handler.d.ts.map