@directive-run/core 1.17.2 → 1.19.0

package/dist/{plugins-BpNMkJRw.d.cts → plugins-yuRFvXJD.d.ts}

@@ -519,6 +519,20 @@ type RequirementPayloadSchema = Record<string, SchemaType<unknown>>;
  * ```
  */
 type RequirementsSchema = Record<string, RequirementPayloadSchema>;
+/**
+ * Infer the requirement payload type from a requirement payload schema.
+ */
+type InferRequirementPayload<P extends RequirementPayloadSchema> = {
+    [K in keyof P]: P[K] extends SchemaType<infer T> ? T : never;
+};
+/**
+ * Infer all requirements from a requirements schema as a discriminated union.
+ */
+type InferRequirementsFromSchema<R extends RequirementsSchema> = {
+    [K in keyof R]: {
+        type: K;
+    } & InferRequirementPayload<R[K]>;
+}[keyof R];
 /**
  * Requirement output from a constraint - can be single, array, or null.
  * - Single requirement: `{ type: "RESTOCK", sku: "ABC" }`
@@ -689,6 +703,277 @@ interface EffectDef<S extends Schema> {
 /** Map of effect definitions */
 type EffectsDef<S extends Schema> = Record<string, EffectDef<S>>;
 
+/**
+ * Source Types — typed external event sources.
+ *
+ * A `source` is the inbound dual of an {@link EffectDef effect}:
+ *
+ *   - **Effects** are outbound. They observe fact changes and push to the
+ *     external world (DOM mutation, WebSocket send, logging, analytics).
+ *     Effects cannot dispatch `system.events`.
+ *   - **Sources** are inbound. They subscribe to an external event stream
+ *     (Supabase realtime channel, WebSocket message stream, browser event,
+ *     polling timer) and publish *into* the system's event queue. Sources
+ *     never read facts.
+ *
+ * Sources sit on the same lifecycle plane as effects but mount once per
+ * system instance (not on every fact change). `attach` runs at
+ * `system.start()`; the returned unsubscribe runs at `system.stop()`.
+ *
+ * ## Why this exists
+ *
+ * The "hook-as-bridge" pattern — a `useEffect` that owns an external
+ * subscription, maps incoming payloads, and dispatches `sys.events.X()` —
+ * shows up in 7+ call sites across the Sizls workspace (Minglingo's
+ * `useActiveRoundSystem`, `useBattleRoyaleSystem`, `eventClaims.realtime.ts`,
+ * etc.). Each site re-derives the lifecycle plumbing.
+ *
+ * A `source` declares that plumbing as a first-class module field. The
+ * engine owns the lifecycle; the author owns only the subscribe + publish
+ * logic. The same shape works in non-React consumers (Workers, node, tests).
+ *
+ * @example Supabase realtime channel
+ * ```typescript
+ * sources: {
+ *   gameUpdates: {
+ *     attach: (publish) => {
+ *       const channel = supabase.channel(`game:${gameId}`).on(
+ *         'postgres_changes',
+ *         { event: 'UPDATE', table: 'games', filter: `id=eq.${gameId}` },
+ *         (payload) => publish('REALTIME_GAME_UPDATE', { gameState: map(payload.new) }),
+ *       ).subscribe();
+ *       return () => channel.unsubscribe();
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * @example Polling timer
+ * ```typescript
+ * sources: {
+ *   heartbeat: {
+ *     attach: (publish) => {
+ *       const id = setInterval(() => publish('HEARTBEAT_TICK', undefined), 5000);
+ *       return () => clearInterval(id);
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * @example No-op (test) source — note the `() => () => undefined` shape:
+ * `attach` MUST return a function. Returning `() => undefined` (one level)
+ * would return `undefined`, which the manager logs as "did not return an
+ * unsubscribe function" and skips. Always two levels.
+ * ```typescript
+ * sources: {
+ *   ignored: { attach: () => () => undefined },
+ *   //                  ^^^^^^^^^^^^^^^^^^^
+ *   //                  | the function that's the unsubscribe
+ *   //                  the function that's `attach`'s return value
+ * }
+ * ```
+ *
+ * @example Typed publish — wrap once for compile-time event-name + payload safety
+ * ```typescript
+ * import type { SourcePublish } from '@directive-run/core';
+ *
+ * function createPublisher(publish: SourcePublish) {
+ *   return {
+ *     TICK: (delta: number) => publish('TICK', { delta }),
+ *     HEARTBEAT: () => publish('HEARTBEAT'),
+ *   };
+ * }
+ *
+ * sources: {
+ *   ticker: {
+ *     attach: (publish) => {
+ *       const p = createPublisher(publish);
+ *       const id = setInterval(() => p.TICK(1), 1000); // ← typed
+ *       return () => clearInterval(id);
+ *     },
+ *   },
+ * }
+ * ```
+ */
+
+/**
+ * Cleanup function returned by a source's `attach`.
+ *
+ * Called once at `system.stop()`. On the next `system.start()` (the manager
+ * supports the full start → stop → start lifecycle), the source's `attach`
+ * runs again and returns a FRESH unsubscribe. Implementations SHOULD guard
+ * repeated teardown defensively, but the manager will only invoke the
+ * captured unsubscribe once per attach cycle.
+ *
+ * The name is intentional — sources are typically wrapping a stateful
+ * external subscription (Supabase channel, WebSocket, browser listener), so
+ * "unsubscribe" is the verb authors recognise. Note that effects use
+ * `EffectCleanup` instead; the asymmetric naming captures the asymmetric
+ * concern (an effect cleans up a side effect; a source unsubscribes from
+ * an external stream).
+ */
+type SourceUnsubscribe = () => void | Promise<void>;
+/**
+ * Typed event dispatcher passed to a source's `attach`. Calls into the same
+ * dispatch queue used by `system.events.X(payload)`.
+ *
+ * The string event name is unchecked at this level (kept as `string` to
+ * avoid coupling the source primitive to the consuming module's event
+ * schema). The authoring module typically wraps `publish` in a typed helper
+ * — see the {@link SourceDef} example for the recommended pattern. The
+ * runtime semantics:
+ *
+ * - `publish('KNOWN_EVENT', payload)` — dispatches into the module's event
+ *   handler. The payload is augmented with `{ type: eventName, ...payload }`
+ *   before passing to the handler (same shape as `system.events.X(payload)`).
+ * - `publish('UNKNOWN_EVENT', ...)` — in development, logs a
+ *   `[Directive] Unknown event type` warning and drops the dispatch.
+ *   In production, silently drops. **This is a footgun for sources** —
+ *   strongly prefer wrapping `publish` in a typed factory (per the example).
+ * - `publish(event, undefined)` — dispatches with an empty payload object.
+ * - Calling `publish` after `system.destroy()` — silently no-ops. The
+ *   engine guards against post-destroy dispatch so stale source callbacks
+ *   cannot mutate a torn-down store.
+ */
+/**
+ * Type-wrapped as an interface (rather than a bare function type) so
+ * additive minors can attach optional methods (`error`, `complete` —
+ * see RFC 0008 Observer-protocol posture) without a major bump. The
+ * call signature is unchanged: existing `publish('EVENT', payload)`
+ * call sites keep working.
+ */
+interface SourcePublish {
+    (event: string, payload?: unknown): void;
+}
+/**
+ * A source definition — attaches an external event stream to the system
+ * lifecycle.
+ *
+ * ## Lifecycle
+ *
+ * - `attach(publish)` runs once at `system.start()`. It is sync.
+ * - The returned `SourceUnsubscribe` runs at `system.stop()`.
+ * - Multiple sources per module are supported; ordering is registration
+ *   order at `attach`, reverse-registration order at unsubscribe.
+ *
+ * ## Restrictions
+ *
+ * - `attach` is **synchronous**. Returning a `Promise<Unsubscribe>` does NOT
+ *   work — the engine discards the Promise and treats it as "no cleanup
+ *   function returned" (logs an error + skips the source). Do async setup
+ *   inside the subscription's own internals; `attach` returns immediately
+ *   with the synchronous unsubscribe function.
+ * - Sources cannot subscribe to system facts. Use {@link EffectDef effects}
+ *   for fact-reactive behavior. If you need to re-subscribe when a fact
+ *   changes, use `system.registerModule()` to swap the source's owning
+ *   module, OR drive the subscription via an effect that owns its own
+ *   channel.
+ * - The publish callback dispatches events normally — resolvers, fact
+ *   handlers, and downstream effects all run. Authors SHOULD throttle /
+ *   debounce inside the source if the inbound rate may exceed the system's
+ *   reconciliation budget.
+ * - **Don't subscribe to the same external channel from both a source AND
+ *   an effect.** The effect will re-run on fact changes, the source mounts
+ *   once — you'll get 2× messages with silent duplicates. Pick one.
+ */
+/**
+ * Source-side runtime-error reporter. Optional second argument to
+ * `attach` per RFC 0008. Authors call this when the underlying stream
+ * errors mid-flight (WebSocket disconnect, Supabase channel goes
+ * stale, polling fetch throws) instead of publishing magic event names
+ * like `STREAM_ERROR`. The manager forwards the error through the same
+ * sinks as attach/cleanup failures, with `phase: "runtime"`.
+ *
+ * @example
+ * ```ts
+ * sources: {
+ *   ws: {
+ *     attach: (publish, reportError) => {
+ *       const sock = new WebSocket(url);
+ *       sock.addEventListener('error', () => reportError(new Error('WS error')));
+ *       sock.addEventListener('message', (e) => publish('MSG', JSON.parse(e.data)));
+ *       return () => sock.close();
+ *     },
+ *   },
+ * }
+ * ```
+ */
+type SourceReportError = (error: Error) => void;
+interface SourceDef {
+    /**
+     * Mount the source against the system. Runs once at `system.start()`.
+     *
+     * @param publish - dispatch typed events into the system's event queue.
+     * @param reportError - report a runtime error from the source's
+     *   underlying stream. Fires `source.error` observation events with
+     *   `phase: "runtime"` (distinct from `"attach"` and `"cleanup"`)
+     *   so observers can attribute the failure correctly. Optional —
+     *   sources that never error mid-flight don't need it.
+     * @returns a cleanup function that runs at `system.stop()`.
+     */
+    attach: (publish: SourcePublish, reportError?: SourceReportError) => SourceUnsubscribe;
+    /** Optional metadata for debugging and devtools (never read on hot path). */
+    meta?: DefinitionMeta;
+    /**
+     * How the manager absorbs publishes that would overwhelm the
+     * reconcile loop. Default: `"none"` — every publish dispatches
+     * straight through to the engine.
+     *
+     * Set `"lastWriteWins"` for high-frequency sources (cursor movement,
+     * sensor telemetry, channel storms). The manager coalesces publishes
+     * with the same event name within a single microtask: only the last
+     * payload of the cycle dispatches; earlier ones bump `dropCount` and
+     * record `lastDropReason: "coalesced"` per source so operators can
+     * see the rate of debouncing on `system.inspect().sources`.
+     *
+     * `"all"` is a no-op equivalent to `"none"` — it names the intent
+     * (no coalesce, every publish counts) for readers.
+     *
+     * Choose `"none"` (default) for low-frequency lifecycle sources
+     * (MCP connect, DO alarm, WebSocket open/close). Choose
+     * `"lastWriteWins"` for any source that could publish faster than
+     * the reconcile loop can drain. See `RFC 0007` for throughput
+     * budgets per coalesce strategy and the rationale.
+     *
+     * Coalescing applies per-event-name: two different event names from
+     * the same source coalesce independently, so a `"priceTick"` storm
+     * doesn't drop a one-shot `"connected"` event.
+     *
+     * **Limitation:** the coalesce STRATEGY is uniform across all event
+     * names on a source — you can't mix (e.g. `lastWriteWins` for
+     * `priceTick` and `none` for `connected` from the same source).
+     * Workaround: split into two source declarations on the module if
+     * the strategies must differ. A future RFC may add per-event-name
+     * strategy overrides.
+     */
+    coalesce?: "none" | "lastWriteWins" | "all";
+    /**
+     * Called when the host runtime signals the isolate is about to be
+     * evicted (Cloudflare DO hibernation, Workers memory pressure, etc.).
+     * Use this to actively close external subscriptions BEFORE the
+     * isolate dies, so the broker / remote service doesn't accumulate
+     * ghost subscriptions visible as "phantom presence" bugs at fleet
+     * scale.
+     *
+     * Distinct from `unsubscribe()`: eviction can fire WITHOUT a
+     * `system.stop()` having been called. The host runtime invokes this
+     * via `system.evict()`, which fires every source's `onEvict()` in
+     * registration order, then `destroyAsync()`. The entire call is
+     * awaitable up to a runtime-supplied deadline.
+     *
+     * Optional — sources whose underlying transport is short-lived
+     * (browser WebSocket, in-process EventEmitter) don't need it. RFC
+     * 0009 documents the full DO-eviction recipe.
+     */
+    onEvict?: () => void | Promise<void>;
+}
+/**
+ * Map of source definitions, keyed by source name. Collision rules match
+ * effects/events/constraints: a source name must be unique across all
+ * modules in a system.
+ */
+type SourcesDef = Record<string, SourceDef>;
+
 /**
  * Event Types - Type definitions for events and event handlers
  */
@@ -911,8 +1196,63 @@ interface ResolverDef<S extends Schema, R extends Requirement = Requirement> {
     /** Optional metadata for debugging and devtools (never read on hot path). */
     meta?: DefinitionMeta;
 }
+/**
+ * Inferred requirement type helper.
+ * Constructs a requirement type from a requirements schema entry.
+ *
+ * @typeParam R - The requirements schema
+ * @typeParam T - The requirement type key
+ *
+ * @example
+ * ```typescript
+ * const requirements = {
+ *   FETCH_USER: { userId: t.string() },
+ *   SEND_EMAIL: { to: t.string(), subject: t.string() },
+ * };
+ *
+ * // InferredReq<typeof requirements, "FETCH_USER"> = { type: "FETCH_USER"; userId: string }
+ * ```
+ */
+type InferredReq<R extends RequirementsSchema, T extends keyof R & string> = {
+    type: T;
+} & InferRequirementPayload<R[T]>;
+/**
+ * Typed resolver for a specific requirement type.
+ */
+type TypedResolverForType<S extends Schema, R extends RequirementsSchema, T extends keyof R & string> = {
+    /** Requirement type to handle */
+    requirement: T;
+    /** Custom key function for deduplication */
+    key?: (req: InferredReq<R, T>) => string;
+    /** Retry policy */
+    retry?: RetryPolicy;
+    /** Timeout for resolver execution (ms) */
+    timeout?: number;
+    /** Batch configuration */
+    batch?: BatchConfig;
+    /** Resolve function for single requirement */
+    resolve?: (req: InferredReq<R, T>, ctx: ResolverContext<S>) => Promise<void>;
+    /** Resolve function for batched requirements (all-or-nothing) */
+    resolveBatch?: (reqs: InferredReq<R, T>[], ctx: ResolverContext<S>) => Promise<void>;
+    /** Resolve function for batched requirements with per-item results */
+    resolveBatchWithResults?: (reqs: InferredReq<R, T>[], ctx: ResolverContext<S>) => Promise<BatchResolveResults>;
+};
+/**
+ * Union of all typed resolver configurations for all requirement types.
+ * TypeScript narrows based on the `requirement` literal value.
+ */
+type AnyTypedResolver<S extends Schema, R extends RequirementsSchema> = {
+    [T in keyof R & string]: TypedResolverForType<S, R, T>;
+}[keyof R & string];
 /** Map of resolver definitions */
 type ResolversDef<S extends Schema> = Record<string, ResolverDef<S, Requirement>>;
+/**
+ * Map of typed resolver definitions (schema-based variant).
+ * Each resolver uses `requirement: "TYPE"` with types inferred from the requirements schema.
+ *
+ * @internal Use `TypedResolversDef` from `types/module.ts` for the public module-based API.
+ */
+type SchemaTypedResolversDef<S extends Schema, R extends RequirementsSchema> = Record<string, AnyTypedResolver<S, R> | ResolverDef<S, Requirement & InferRequirementsFromSchema<R>>>;
 /** Resolver status */
 type ResolverStatus = {
     state: "idle";
@@ -1178,8 +1518,30 @@ interface NamespacedSystem<Modules extends ModulesMap> {
     start(): void;
     /** Stop the system (cancel resolvers, stop reconciliation) */
     stop(): void;
+    /**
+     * Async-aware stop (RFC 0009). Awaits source unsubscribes so external
+     * transports (Supabase channel.unsubscribe, DO storage flush) settle
+     * before the caller continues. Use this instead of `stop()` when any
+     * declared source returns a Promise from its unsubscribe.
+     */
+    stopAsync(): Promise<void>;
     /** Destroy the system (stop and cleanup) */
     destroy(): void;
+    /**
+     * Async-aware destroy (RFC 0009). Awaits `stopAsync()` first so source
+     * teardown finishes before facts/derivations/effects are wiped.
+     */
+    destroyAsync(): Promise<void>;
+    /**
+     * Signal that the host runtime is about to evict this system (RFC 0009).
+     * Fires every source's `onEvict` in registration order, then races
+     * teardown against `deadline` (ms epoch). With no deadline the full
+     * teardown is awaited. With `deadline <= now` the eviction is
+     * detached so the caller returns immediately. Use for Cloudflare DO
+     * hibernation, Worker eviction, and any runtime that imposes a hard
+     * shutdown wall clock.
+     */
+    evict(deadline?: number): Promise<void>;
     /** Whether the system is currently running */
     readonly isRunning: boolean;
     /** Whether all resolvers have completed */
@@ -1419,8 +1781,30 @@ interface SingleModuleSystem<S extends ModuleSchema> {
     start(): void;
     /** Stop the system (cancel resolvers, stop reconciliation) */
     stop(): void;
+    /**
+     * Async-aware stop (RFC 0009). Awaits source unsubscribes so external
+     * transports (Supabase channel.unsubscribe, DO storage flush) settle
+     * before the caller continues. Use this instead of `stop()` when any
+     * declared source returns a Promise from its unsubscribe.
+     */
+    stopAsync(): Promise<void>;
     /** Destroy the system (stop and cleanup) */
     destroy(): void;
+    /**
+     * Async-aware destroy (RFC 0009). Awaits `stopAsync()` first so source
+     * teardown finishes before facts/derivations/effects are wiped.
+     */
+    destroyAsync(): Promise<void>;
+    /**
+     * Signal that the host runtime is about to evict this system (RFC 0009).
+     * Fires every source's `onEvict` in registration order, then races
+     * teardown against `deadline` (ms epoch). With no deadline the full
+     * teardown is awaited. With `deadline <= now` the eviction is
+     * detached so the caller returns immediately. Use for Cloudflare DO
+     * hibernation, Worker eviction, and any runtime that imposes a hard
+     * shutdown wall clock.
+     */
+    evict(deadline?: number): Promise<void>;
     /** Whether the system is currently running */
     readonly isRunning: boolean;
     /** Whether all resolvers have completed */
@@ -1557,7 +1941,13 @@ interface AnySystem {
     initialize(): void;
     start(): void;
     stop(): void;
+    /** RFC 0009: async-aware stop — awaits source unsubscribes. */
+    stopAsync(): Promise<void>;
     destroy(): void;
+    /** RFC 0009: async-aware destroy. */
+    destroyAsync(): Promise<void>;
+    /** RFC 0009: runtime-eviction signal with optional deadline. */
+    evict(deadline?: number): Promise<void>;
 }
 /**
  * Check if a system is a single module system.
@@ -1946,6 +2336,15 @@ interface ModuleDef<M extends ModuleSchema = ModuleSchema> {
     derive?: TypedDerivationsDef<M>;
     events?: TypedEventsDef<M>;
     effects?: EffectsDef<M["facts"]>;
+    /**
+     * Typed external event sources. See {@link SourceDef} for the primitive's
+     * lifecycle + rationale. Each source attaches at `system.start()` and
+     * tears down at `system.stop()`. Use for Supabase realtime channels,
+     * WebSocket message streams, polling timers, browser event listeners —
+     * any inbound external event the module needs to map into its own event
+     * dispatch surface.
+     */
+    sources?: SourcesDef;
     constraints?: TypedConstraintsDef<M>;
     resolvers?: TypedResolversDef<M>;
     hooks?: ModuleHooks<M>;
@@ -2200,6 +2599,78 @@ interface SystemInspection {
         id: string;
         meta?: DefinitionMeta;
     }>;
+    /**
+     * All declared source names with the module that owns each, plus per-source
+     * telemetry surfaced for production-debug ("which source is publishing?",
+     * "when did this source last fire?", "is this source errored?", "is the
+     * engine silently dropping publishes from this source?") without requiring
+     * a custom plugin to be installed first.
+     *
+     * Counters reset at every `system.start()` cycle — a stop → start does not
+     * carry "ghost" counts from the previous cycle. Timestamps are wall-clock
+     * milliseconds (Date.now()); `null` means "never happened in this cycle".
+     *
+     * `dropCount` / `lastDropReason` / `lastDropAt` count publishes the
+     * engine's dispatch guard rejected (post-stop, BLOCKED_PROPS event name,
+     * empty / non-string event name). Without these, attackers — or a buggy
+     * source — could probe BLOCKED_PROPS / the isRunning guard invisibly:
+     * telemetry would never advance and no plugin hook would fire.
+     *
+     * `attachedSourceCount` (below) is the aggregate count of `attached: true`
+     * rows; both must stay in lockstep.
+     */
+    sources: Array<{
+        id: string;
+        moduleId: string;
+        meta?: DefinitionMeta;
+        /** True while the source's attach succeeded and its unsubscribe is held. */
+        attached: boolean;
+        /** Wall-clock ms when the source most recently attached, or null. */
+        attachedAt: number | null;
+        /** Wall-clock ms when the source most recently detached, or null. */
+        detachedAt: number | null;
+        /** Total publish() invocations the engine accepted since the last attachAll. */
+        publishCount: number;
+        /** Wall-clock ms of the most recent accepted publish() call, or null. */
+        lastPublishAt: number | null;
+        /**
+         * Total publish() invocations the engine's dispatch guard rejected this
+         * cycle. Operators monitor this to spot misconfigured sources (wrong
+         * event names) or probing of the BLOCKED_PROPS / isRunning guards.
+         */
+        dropCount: number;
+        /**
+         * Reason for the most recent rejected publish, or `null`.
+         * - `"post-destroy"` / `"post-stop"` — leaked transport firing
+         *   outside the running lifecycle window
+         * - `"blocked-event-name"` / `"invalid-event-name"` — engine
+         *   dispatch guard rejected the publish (BLOCKED_PROPS / empty)
+         * - `"coalesced"` — manager debounced a same-event-name publish
+         *   when `SourceDef.coalesce === "lastWriteWins"`
+         */
+        lastDropReason: "post-destroy" | "post-stop" | "blocked-event-name" | "invalid-event-name" | "coalesced" | null;
+        /** Wall-clock ms of the most recent rejected publish, or `null`. */
+        lastDropAt: number | null;
+        /** Total attach + cleanup errors since the last attachAll. */
+        errorCount: number;
+        /**
+         * The most recent error from this source, or `null`. `message` is
+         * truncated to a fixed maximum length so a source whose `attach()`
+         * throws with a payload-embedded message does not write unbounded data
+         * here AND downstream into the audit ledger. `phase: "runtime"`
+         * (RFC 0008) flags errors that the source reported mid-flight via
+         * the `reportError` callback `attach` receives as its second
+         * argument (distinct from lifecycle `"attach"` / `"cleanup"`
+         * failures).
+         */
+        lastError: {
+            phase: "attach" | "cleanup" | "runtime";
+            message: string;
+            at: number;
+        } | null;
+    }>;
+    /** Number of sources currently attached (i.e. system is in the `attached` phase + their attach() succeeded). */
+    attachedSourceCount: number;
     /** All defined derivation names with optional metadata */
     derivations: Array<{
         id: string;
@@ -2627,6 +3098,48 @@ type ObservationEvent = {
     type: "effect.error";
     id: string;
     error: unknown;
+}
+/**
+ * Source attached at `system.start()` (or at registerModule when the
+ * system was already running). Carries the source id + the module that
+ * declared it so plugins can attribute per-module sources.
+ */
+ | {
+    type: "source.attach";
+    id: string;
+    moduleId: string;
+}
+/**
+ * A source published an event into the system's event queue. Fires
+ * BEFORE the event handler runs; pair with `fact.change` events to
+ * trace the downstream effect.
+ */
+ | {
+    type: "source.publish";
+    id: string;
+    moduleId: string;
+    eventName: string;
+}
+/** Source detached at `system.stop()` (reverse-registration order). */
+ | {
+    type: "source.detach";
+    id: string;
+    moduleId: string;
+}
+/**
+ * Source `attach` / unsubscribe threw, OR the source called the
+ * `reportError` callback that `attach` received as its second
+ * argument (RFC 0008) — handled, isolated, observable.
+ * `phase: "runtime"` distinguishes mid-flight stream errors
+ * (WebSocket disconnect, Supabase channel goes stale) from lifecycle
+ * `"attach"` / `"cleanup"` failures so observers attribute correctly.
+ */
+ | {
+    type: "source.error";
+    id: string;
+    moduleId: string;
+    phase: "attach" | "cleanup" | "runtime";
+    error: unknown;
 } | {
     type: "derivation.compute";
     id: string;
@@ -2660,6 +3173,23 @@ interface System<M extends ModuleSchema = ModuleSchema> {
      * Observe all lifecycle events as a typed stream.
      * Returns an unsubscribe function.
      *
+     * ## Timing semantics
+     *
+     * Observers receive events that fire **from the moment they subscribe
+     * onwards**. Past events are NOT replayed. Consequences:
+     *
+     * - An observer registered BEFORE `system.start()` sees the initial
+     *   `system.start`, `source.attach`, etc. events emitted during start.
+     * - An observer registered AFTER `system.start()` does NOT see those
+     *   initial events. To reconstruct the current state, use
+     *   `system.inspect()` (`facts`, `sources`, `constraints`, etc.) at
+     *   subscription time, then layer the live observer stream on top.
+     * - The unsubscribe function is idempotent — calling it more than once
+     *   is safe.
+     *
+     * This mirrors RxJS Subject + DOM EventTarget conventions; there is no
+     * hidden replay buffer.
+     *
      * @example
      * ```typescript
      * const unsub = system.observe((event) => {
@@ -2668,6 +3198,13 @@ interface System<M extends ModuleSchema = ModuleSchema> {
      *   }
      * });
      * ```
+     *
+     * @example Reconstructing state on late subscription
+     * ```typescript
+     * const snapshot = system.inspect();
+     * console.log('active sources:', snapshot.attachedSourceCount);
+     * const unsub = system.observe((event) => { ... }); // forward-only
+     * ```
      */
     observe(observer: (event: ObservationEvent) => void): () => void;
     /** Per-run trace entries (null if trace is not enabled) */
@@ -2677,6 +3214,35 @@ interface System<M extends ModuleSchema = ModuleSchema> {
     start(): void;
     stop(): void;
     destroy(): void;
+    /**
+     * RFC 0009: async-aware variant of `stop()`. Awaits each source's
+     * unsubscribe before resolving. Use when sources have async
+     * unsubscribes (Supabase `channel.unsubscribe()`, Cloudflare DO
+     * storage flushes) and the caller needs to know teardown actually
+     * completed before continuing.
+     */
+    stopAsync(): Promise<void>;
+    /**
+     * RFC 0009: async-aware variant of `destroy()`. Equivalent to
+     * `stopAsync` followed by `destroy`. Use in DO `webSocketClose` /
+     * `alarm` handlers where the caller must let the runtime evict the
+     * isolate cleanly.
+     */
+    destroyAsync(): Promise<void>;
+    /**
+     * RFC 0009: signal the host runtime is about to evict this isolate.
+     * Fires every source's `onEvict()` in registration order (so sources
+     * with downstream dependencies close in the right order), then calls
+     * `destroyAsync()`. Cloudflare DO consumers call this from their
+     * `alarm()` / `webSocketClose()` handlers BEFORE letting the
+     * runtime evict so external brokers don't accumulate ghost
+     * subscriptions.
+     *
+     * @param deadline - Optional wall-clock ms deadline. If supplied,
+     *   evicts that have not resolved by `deadline` are abandoned (the
+     *   isolate will die anyway). Defaults to no deadline.
+     */
+    evict(deadline?: number): Promise<void>;
     readonly isRunning: boolean;
     readonly isSettled: boolean;
     /** Whether all modules have completed initialization */
@@ -3041,6 +3607,39 @@ interface Plugin<M extends ModuleSchema = ModuleSchema> {
      * @param error - The error that was thrown
      */
     onEffectError?: (id: string, error: unknown) => void;
+    /**
+     * Called when a typed external event source attaches at `system.start()`
+     * (or when a dynamically registered module brings new sources to an
+     * already-running system).
+     * @param id - The source ID (key on the module's `sources:` map).
+     * @param moduleId - The owning module's id.
+     */
+    onSourceAttach?: (id: string, moduleId: string) => void;
+    /**
+     * Called when a source publishes an event into the system's event queue.
+     * Fires BEFORE the event handler runs. Pair with `onFactChange` to trace
+     * the downstream state mutation.
+     * @param id - The source ID.
+     * @param moduleId - The owning module's id.
+     * @param eventName - The dispatched event name (the first arg to `publish`).
+     */
+    onSourcePublish?: (id: string, moduleId: string, eventName: string) => void;
+    /**
+     * Called when a source detaches at `system.stop()` (reverse-registration
+     * order across all modules).
+     * @param id - The source ID.
+     * @param moduleId - The owning module's id.
+     */
+    onSourceDetach?: (id: string, moduleId: string) => void;
+    /**
+     * Called when a source's `attach` or unsubscribe throws. Errors are
+     * isolated (one bad source never blocks others) but observable here.
+     * @param id - The source ID.
+     * @param moduleId - The owning module's id.
+     * @param phase - Which lifecycle stage threw.
+     * @param error - The thrown value (normalized to Error inside the manager).
+     */
+    onSourceError?: (id: string, moduleId: string, phase: "attach" | "cleanup" | "runtime", error: unknown) => void;
     /**
      * Called when a history snapshot is taken.
      * @param snapshot - The snapshot that was captured
@@ -3099,4 +3698,4 @@ interface Plugin<M extends ModuleSchema = ModuleSchema> {
     onTraceComplete?: (entry: TraceEntry) => void;
 }
 
-export { type PatchSpec as $, type AnySystem as A, type BatchConfig as B, type ClauseResult as C, type DefinitionMeta as D, type EffectsDef as E, type FactPredicate as F, type HistoryOption as G, type HistoryAPI as H, type HistoryState as I, type InferDerivations as J, type InferEvents as K, type InferFacts as L, type ModuleSchema as M, type NamespacedSystem as N, type InferRequirementTypes as O, type Plugin as P, type InferRequirements as Q, type RequirementWithId as R, type SchemaType as S, type TypedDerivationsDef as T, type InferSchemaType as U, type InferSelectorState as V, type KeySelector as W, type MetaAccessor as X, type MetaMatch as Y, type ObservationEvent as Z, type OperatorObject as _, type Facts as a, type RequirementOutput as a$, type PatchValue as a0, type PayloadRef as a1, type PredicateClause as a2, type PredicateCombinator as a3, type PredicateCombinatorKey as a4, type PredicateObject as a5, type PredicateOp as a6, type RetryPolicy as a7, type Schema as a8, type Snapshot as a9, type CrossModuleFactsWithSelf as aA, type DerivationKeys as aB, type DerivationReturnType as aC, type DerivationsControl as aD, type DerivationsSchema as aE, type DeriveAccessor as aF, type DispatchEventsFromSchema as aG, type EffectCleanup as aH, type EffectsControl as aI, type EventPayloadSchema as aJ, type EventsAccessor as aK, type EventsAccessorFromSchema as aL, type EventsDef as aM, type EventsSchema as aN, type FactKeys as aO, type FactReturnType as aP, type FlexibleEventHandler as aQ, type HistoryConfig as aR, type InferEventPayloadFromSchema as aS, type InferRequirementPayloadFromSchema as aT, type InferSchema as aU, type MutableNamespacedFacts as aV, type NamespacedDerivations as aW, type NamespacedEventsAccessor as aX, type NamespacedFacts as aY, type ObservableKeys as aZ, type RequirementExplanation as a_, type System as aa, type SystemConfig as ab, type SystemDerived as ac, type SystemFacts as ad, type SystemInspection as ae, type SystemMode as af, type SystemSnapshot as ag, type TraceEntry as ah, isNamespacedSystem as ai, isSingleModuleSystem as aj, type FactsStore as ak, type ConstraintsDef as al, type ConstraintState as am, type ResolversDef as an, type ResolverStatus as ao, type FactChange as ap, type ReconcileResult as aq, type RecoveryStrategy as ar, type ErrorSource as as, type RetryLaterConfig as at, type BatchItemResult as au, type BatchResolveResults as av, type ConstraintsControl as aw, type CrossModuleConstraintDef as ax, type CrossModuleDerivationFn as ay, type CrossModuleEffectDef as az, type TypedEventsDef as b, type RequirementPayloadSchema$1 as b0, type RequirementsSchema as b1, type ResolverContext as b2, type ResolversControl as b3, type SnapshotMeta as b4, type SystemEvent as b5, type TraceConfig as b6, type TypedConstraintDef as b7, type TypedResolverContext as b8, type TypedResolverDef as b9, type UnionEvents as ba, type RequirementOutput$1 as bb, type TypedConstraintsDef as c, type TypedResolversDef as d, type ModuleHooks as e, type CrossModuleDeps as f, type CrossModuleDerivationsDef as g, type CrossModuleEffectsDef as h, type CrossModuleConstraintsDef as i, type ModuleDef as j, type CreateSystemOptionsSingle as k, type SingleModuleSystem as l, type ModulesMap as m, type CreateSystemOptionsNamed as n, type TraceOption as o, type ErrorBoundaryConfig as p, type Requirement as q, type RequirementKeyFn as r, DirectiveError as s, type DistributableSnapshot as t, type DistributableSnapshotOptions as u, type DynamicConstraintDef as v, type DynamicEffectDef as w, type DynamicResolverDef as x, type FactTemplate as y, type FactsSnapshot as z };
+export { type InferSchemaType as $, type AnySystem as A, type BatchConfig as B, type ClauseResult as C, type DefinitionMeta as D, type EffectsDef as E, type FactPredicate as F, type DynamicConstraintDef as G, type DynamicEffectDef as H, type DynamicResolverDef as I, type EffectDef as J, type EventsDef as K, type FactTemplate as L, type ModuleSchema as M, type NamespacedSystem as N, type FactsSnapshot as O, type Plugin as P, type HistoryAPI as Q, type RequirementWithId as R, type SchemaType as S, type TypedDerivationsDef as T, type HistoryOption as U, type HistoryState as V, type InferDerivations as W, type InferEvents as X, type InferFacts as Y, type InferRequirementTypes as Z, type InferRequirements as _, type Facts as a, type FlexibleEventHandler as a$, type InferSelectorState as a0, type KeySelector as a1, type MetaAccessor as a2, type MetaMatch as a3, type ObservationEvent as a4, type OperatorObject as a5, type PatchSpec as a6, type PatchValue as a7, type PayloadRef as a8, type PredicateClause as a9, type FactsStore as aA, type ConstraintState as aB, type ResolverStatus as aC, type FactChange as aD, type ReconcileResult as aE, type RecoveryStrategy as aF, type ErrorSource as aG, type RetryLaterConfig as aH, type BatchItemResult as aI, type BatchResolveResults as aJ, type ConstraintsControl as aK, type CrossModuleDerivationFn as aL, type CrossModuleFactsWithSelf as aM, type DerivationKeys as aN, type DerivationReturnType as aO, type DerivationsControl as aP, type DerivationsSchema as aQ, type DeriveAccessor as aR, type DispatchEventsFromSchema as aS, type EffectCleanup as aT, type EffectsControl as aU, type EventPayloadSchema as aV, type EventsAccessor as aW, type EventsAccessorFromSchema as aX, type EventsSchema as aY, type FactKeys as aZ, type FactReturnType as a_, type PredicateCombinator as aa, type PredicateCombinatorKey as ab, type PredicateObject as ac, type PredicateOp as ad, type ResolverDef as ae, type ResolversDef as af, type RetryPolicy as ag, type Schema as ah, type SchemaTypedResolversDef as ai, type Snapshot as aj, type SourceDef as ak, type SourcePublish as al, type SourceReportError as am, type SourceUnsubscribe as an, type System as ao, type SystemConfig as ap, type SystemDerived as aq, type SystemFacts as ar, type SystemInspection as as, type SystemMode as at, type SystemSnapshot as au, type TraceEntry as av, type TypedConstraintDef as aw, type TypedResolverDef as ax, isNamespacedSystem as ay, isSingleModuleSystem as az, type TypedEventsDef as b, type HistoryConfig as b0, type InferEventPayloadFromSchema as b1, type InferRequirementPayloadFromSchema as b2, type InferSchema as b3, type MutableNamespacedFacts as b4, type NamespacedDerivations as b5, type NamespacedEventsAccessor as b6, type NamespacedFacts as b7, type ObservableKeys as b8, type RequirementExplanation as b9, type RequirementOutput as ba, type RequirementPayloadSchema$1 as bb, type RequirementsSchema as bc, type ResolverContext as bd, type ResolversControl as be, type SnapshotMeta as bf, type SystemEvent as bg, type TraceConfig as bh, type TypedResolverContext as bi, type UnionEvents as bj, type RequirementOutput$1 as bk, type SourcesDef as c, type TypedConstraintsDef as d, type TypedResolversDef as e, type ModuleHooks as f, type CrossModuleDeps as g, type CrossModuleDerivationsDef as h, type CrossModuleEffectsDef as i, type CrossModuleConstraintsDef as j, type ModuleDef as k, type CreateSystemOptionsSingle as l, type SingleModuleSystem as m, type ModulesMap as n, type CreateSystemOptionsNamed as o, type TraceOption as p, type ErrorBoundaryConfig as q, type Requirement as r, type RequirementKeyFn as s, type ConstraintDef as t, type ConstraintsDef as u, type CrossModuleConstraintDef as v, type CrossModuleEffectDef as w, DirectiveError as x, type DistributableSnapshot as y, type DistributableSnapshotOptions as z };