@directive-run/core 1.17.2 → 1.18.0

package/dist/internals.cjs

@@ -1,2 +1,2 @@
-'use strict';var chunkQ5UTBMX2_cjs=require('./chunk-Q5UTBMX2.cjs'),chunkRWFKUNF7_cjs=require('./chunk-RWFKUNF7.cjs'),chunkJGPPJV5P_cjs=require('./chunk-JGPPJV5P.cjs'),chunk4MNQDXH7_cjs=require('./chunk-4MNQDXH7.cjs');Object.defineProperty(exports,"createConstraintFactory",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.c}});Object.defineProperty(exports,"createConstraintsManager",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.p}});Object.defineProperty(exports,"createDerivationsManager",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.q}});Object.defineProperty(exports,"createDisabledHistory",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.j}});Object.defineProperty(exports,"createEffectsManager",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.r}});Object.defineProperty(exports,"createEngine",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.z}});Object.defineProperty(exports,"createErrorBoundaryManager",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.t}});Object.defineProperty(exports,"createFacts",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.w}});Object.defineProperty(exports,"createFactsProxy",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.v}});Object.defineProperty(exports,"createFactsStore",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.u}});Object.defineProperty(exports,"createHistoryManager",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.i}});Object.defineProperty(exports,"createPluginManager",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.x}});Object.defineProperty(exports,"createResolverFactory",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.d}});Object.defineProperty(exports,"createResolversManager",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.y}});Object.defineProperty(exports,"createRetryLaterManager",{enumerable:true,get:function(){return chunkQ5UTBMX2_cjs.s}});Object.defineProperty(exports,"dangerousRegex",{enumerable:true,get:function(){return chunkRWFKUNF7_cjs.m}});Object.defineProperty(exports,"getCurrentDeps",{enumerable:true,get:function(){return chunkJGPPJV5P_cjs.f}});Object.defineProperty(exports,"isTracking",{enumerable:true,get:function(){return chunkJGPPJV5P_cjs.g}});Object.defineProperty(exports,"trackAccess",{enumerable:true,get:function(){return chunkJGPPJV5P_cjs.j}});Object.defineProperty(exports,"withTracking",{enumerable:true,get:function(){return chunkJGPPJV5P_cjs.h}});Object.defineProperty(exports,"withoutTracking",{enumerable:true,get:function(){return chunkJGPPJV5P_cjs.i}});Object.defineProperty(exports,"hashObject",{enumerable:true,get:function(){return chunk4MNQDXH7_cjs.h}});Object.defineProperty(exports,"isPrototypeSafe",{enumerable:true,get:function(){return chunk4MNQDXH7_cjs.f}});Object.defineProperty(exports,"safeStringify",{enumerable:true,get:function(){return chunk4MNQDXH7_cjs.o}});Object.defineProperty(exports,"stableStringify",{enumerable:true,get:function(){return chunk4MNQDXH7_cjs.e}});//# sourceMappingURL=internals.cjs.map
+'use strict';var chunk3LBPXJO2_cjs=require('./chunk-3LBPXJO2.cjs'),chunkRWFKUNF7_cjs=require('./chunk-RWFKUNF7.cjs'),chunkJGPPJV5P_cjs=require('./chunk-JGPPJV5P.cjs'),chunk4MNQDXH7_cjs=require('./chunk-4MNQDXH7.cjs');Object.defineProperty(exports,"createConstraintFactory",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.c}});Object.defineProperty(exports,"createConstraintsManager",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.p}});Object.defineProperty(exports,"createDerivationsManager",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.q}});Object.defineProperty(exports,"createDisabledHistory",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.j}});Object.defineProperty(exports,"createEffectsManager",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.r}});Object.defineProperty(exports,"createEngine",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.A}});Object.defineProperty(exports,"createErrorBoundaryManager",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.t}});Object.defineProperty(exports,"createFacts",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.w}});Object.defineProperty(exports,"createFactsProxy",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.v}});Object.defineProperty(exports,"createFactsStore",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.u}});Object.defineProperty(exports,"createHistoryManager",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.i}});Object.defineProperty(exports,"createPluginManager",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.x}});Object.defineProperty(exports,"createResolverFactory",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.d}});Object.defineProperty(exports,"createResolversManager",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.y}});Object.defineProperty(exports,"createRetryLaterManager",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.s}});Object.defineProperty(exports,"createSourcesManager",{enumerable:true,get:function(){return chunk3LBPXJO2_cjs.z}});Object.defineProperty(exports,"dangerousRegex",{enumerable:true,get:function(){return chunkRWFKUNF7_cjs.m}});Object.defineProperty(exports,"getCurrentDeps",{enumerable:true,get:function(){return chunkJGPPJV5P_cjs.f}});Object.defineProperty(exports,"isTracking",{enumerable:true,get:function(){return chunkJGPPJV5P_cjs.g}});Object.defineProperty(exports,"trackAccess",{enumerable:true,get:function(){return chunkJGPPJV5P_cjs.j}});Object.defineProperty(exports,"withTracking",{enumerable:true,get:function(){return chunkJGPPJV5P_cjs.h}});Object.defineProperty(exports,"withoutTracking",{enumerable:true,get:function(){return chunkJGPPJV5P_cjs.i}});Object.defineProperty(exports,"hashObject",{enumerable:true,get:function(){return chunk4MNQDXH7_cjs.h}});Object.defineProperty(exports,"isPrototypeSafe",{enumerable:true,get:function(){return chunk4MNQDXH7_cjs.f}});Object.defineProperty(exports,"safeStringify",{enumerable:true,get:function(){return chunk4MNQDXH7_cjs.o}});Object.defineProperty(exports,"stableStringify",{enumerable:true,get:function(){return chunk4MNQDXH7_cjs.e}});//# sourceMappingURL=internals.cjs.map
 //# sourceMappingURL=internals.cjs.map

package/dist/internals.d.cts

@@ -1,7 +1,7 @@
-import { a8 as Schema, ak as FactsStore, a as Facts, D as DefinitionMeta, E as EffectsDef, al as ConstraintsDef, r as RequirementKeyFn, R as RequirementWithId, am as ConstraintState, F as FactPredicate, C as ClauseResult, an as ResolversDef, ao as ResolverStatus, q as Requirement, P as Plugin, aa as System, ap as FactChange, z as FactsSnapshot, aq as ReconcileResult, a9 as Snapshot, s as DirectiveError, ar as RecoveryStrategy, ah as TraceEntry, as as ErrorSource, p as ErrorBoundaryConfig, at as RetryLaterConfig, H as HistoryAPI, G as HistoryOption, ab as SystemConfig } from './plugins-BpNMkJRw.cjs';
-export { au as BatchItemResult, av as BatchResolveResults, aw as ConstraintsControl, ax as CrossModuleConstraintDef, i as CrossModuleConstraintsDef, ay as CrossModuleDerivationFn, g as CrossModuleDerivationsDef, az as CrossModuleEffectDef, h as CrossModuleEffectsDef, aA as CrossModuleFactsWithSelf, aB as DerivationKeys, aC as DerivationReturnType, aD as DerivationsControl, aE as DerivationsSchema, aF as DeriveAccessor, aG as DispatchEventsFromSchema, t as DistributableSnapshot, u as DistributableSnapshotOptions, aH as EffectCleanup, aI as EffectsControl, aJ as EventPayloadSchema, aK as EventsAccessor, aL as EventsAccessorFromSchema, aM as EventsDef, aN as EventsSchema, aO as FactKeys, aP as FactReturnType, aQ as FlexibleEventHandler, aR as HistoryConfig, aS as InferEventPayloadFromSchema, aT as InferRequirementPayloadFromSchema, aU as InferSchema, aV as MutableNamespacedFacts, aW as NamespacedDerivations, aX as NamespacedEventsAccessor, aY as NamespacedFacts, aZ as ObservableKeys, a_ as RequirementExplanation, a$ as RequirementOutput, b0 as RequirementPayloadSchema, b1 as RequirementsSchema, b2 as ResolverContext, b3 as ResolversControl, b4 as SnapshotMeta, b5 as SystemEvent, b6 as TraceConfig, b7 as TypedConstraintDef, c as TypedConstraintsDef, T as TypedDerivationsDef, b as TypedEventsDef, b8 as TypedResolverContext, b9 as TypedResolverDef, d as TypedResolversDef, ba as UnionEvents } from './plugins-BpNMkJRw.cjs';
-import { w as DerivationsDef, x as DerivedValues } from './predicate-DN1MnDbi.cjs';
-export { y as DerivationState, T as TypedConstraint, z as TypedResolver, A as createConstraintFactory, B as createResolverFactory, C as dangerousRegex } from './predicate-DN1MnDbi.cjs';
+import { ah as Schema, aA as FactsStore, a as Facts, D as DefinitionMeta, E as EffectsDef, u as ConstraintsDef, s as RequirementKeyFn, R as RequirementWithId, aB as ConstraintState, F as FactPredicate, C as ClauseResult, af as ResolversDef, aC as ResolverStatus, r as Requirement, ak as SourceDef, P as Plugin, ao as System, aD as FactChange, O as FactsSnapshot, aE as ReconcileResult, aj as Snapshot, x as DirectiveError, aF as RecoveryStrategy, av as TraceEntry, aG as ErrorSource, q as ErrorBoundaryConfig, aH as RetryLaterConfig, Q as HistoryAPI, U as HistoryOption, ap as SystemConfig } from './plugins-xpm4B7Nt.cjs';
+export { aI as BatchItemResult, aJ as BatchResolveResults, aK as ConstraintsControl, v as CrossModuleConstraintDef, j as CrossModuleConstraintsDef, aL as CrossModuleDerivationFn, h as CrossModuleDerivationsDef, w as CrossModuleEffectDef, i as CrossModuleEffectsDef, aM as CrossModuleFactsWithSelf, aN as DerivationKeys, aO as DerivationReturnType, aP as DerivationsControl, aQ as DerivationsSchema, aR as DeriveAccessor, aS as DispatchEventsFromSchema, y as DistributableSnapshot, z as DistributableSnapshotOptions, aT as EffectCleanup, aU as EffectsControl, aV as EventPayloadSchema, aW as EventsAccessor, aX as EventsAccessorFromSchema, K as EventsDef, aY as EventsSchema, aZ as FactKeys, a_ as FactReturnType, a$ as FlexibleEventHandler, b0 as HistoryConfig, b1 as InferEventPayloadFromSchema, b2 as InferRequirementPayloadFromSchema, b3 as InferSchema, b4 as MutableNamespacedFacts, b5 as NamespacedDerivations, b6 as NamespacedEventsAccessor, b7 as NamespacedFacts, b8 as ObservableKeys, b9 as RequirementExplanation, ba as RequirementOutput, bb as RequirementPayloadSchema, bc as RequirementsSchema, bd as ResolverContext, be as ResolversControl, bf as SnapshotMeta, bg as SystemEvent, bh as TraceConfig, aw as TypedConstraintDef, d as TypedConstraintsDef, T as TypedDerivationsDef, b as TypedEventsDef, bi as TypedResolverContext, ax as TypedResolverDef, e as TypedResolversDef, bj as UnionEvents } from './plugins-xpm4B7Nt.cjs';
+import { b as DerivationsDef, y as DerivedValues } from './predicate-CMGFjIeu.cjs';
+export { z as DerivationState, T as TypedConstraint, A as TypedResolver, B as createConstraintFactory, C as createResolverFactory, E as dangerousRegex } from './predicate-CMGFjIeu.cjs';
 export { h as hashObject, g as isPrototypeSafe, j as safeStringify, k as stableStringify } from './utils-BZBBwS5A.cjs';
 
 /**
@@ -810,6 +810,201 @@ interface CreateResolversOptions<S extends Schema> {
  */
 declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
 
+/**
+ * Sources Manager — lifecycle owner for typed external event sources.
+ *
+ * Sources attach at {@link System.start} and tear down at {@link System.stop}.
+ * The manager supports the full start → stop → start → stop re-entry cycle:
+ * each `attachAll` re-arms the manager, each `cleanupAll` is idempotent until
+ * the next `attachAll`. Failures inside attach or unsubscribe are isolated so
+ * a single misbehaving source cannot prevent other sources (or the system
+ * itself) from completing their lifecycle.
+ *
+ * The manager also supports {@link SourcesManager.registerDefinitions} for
+ * dynamic module registration via {@link System.registerModule}: sources
+ * declared on a module registered AFTER the system has started attach
+ * immediately; sources declared before the next `start` queue up and attach
+ * with the rest.
+ *
+ * The manager invokes per-source lifecycle callbacks (`onAttach`,
+ * `onPublish`, `onDetach`, `onError`) so the engine can emit accurate plugin
+ * observation events — including correct per-source attribution even when
+ * two sources publish the same event name.
+ *
+ * See {@link SourceDef} for the primitive's full semantics + rationale.
+ */
+
+/**
+ * Engine-side dispatcher invoked when a source publishes an event. The
+ * manager wraps each source's publish callback in a closure that closes
+ * over the source id + moduleId so the engine cannot mis-attribute
+ * publishes (a naive "look up the source by event name" approach fails
+ * when multiple sources publish the same event).
+ *
+ * Returns a {@link SourceDispatchResult} indicating whether the engine
+ * accepted the publish. The manager uses the result to gate counter bumps
+ * + `onPublish` plugin emission: an accepted publish bumps `publishCount`
+ * and fires `onPublish`; a rejected publish bumps `dropCount` /
+ * `lastDropReason` and stays out of the plugin hook (otherwise observers
+ * would see "publish happened" for events the engine swallowed).
+ */
+type SourceDispatch = (sourceId: string, moduleId: string, eventName: string, payload: unknown) => SourceDispatchResult;
+/**
+ * Outcome of a single source publish handed back to the manager. `"accepted"`
+ * means the engine dispatched into the event handler chain. Rejection
+ * reasons name the specific drop path so per-source telemetry can attribute
+ * the drop precisely:
+ *
+ * - `"post-destroy"` — publish arrived after `system.destroy()`.
+ * - `"post-stop"` — publish arrived between `system.stop()` and the next
+ *   `system.start()`.
+ * - `"blocked-event-name"` — event name was `__proto__` / `constructor` /
+ *   `prototype` (BLOCKED_PROPS guard, parity with `system.dispatch`).
+ * - `"invalid-event-name"` — event name was non-string or empty string.
+ */
+type SourceDispatchResult = {
+    accepted: true;
+} | {
+    accepted: false;
+    reason: "post-destroy" | "post-stop" | "blocked-event-name" | "invalid-event-name" | "coalesced";
+};
+/**
+ * Per-source lifecycle callbacks the engine wires into the plugin manager.
+ * All are optional — manager-only consumers can omit them. The manager
+ * GUARANTEES:
+ *
+ * - `onAttach(id, moduleId)` runs ONLY when `attach()` returned a function
+ *   (i.e. the source successfully attached). Sources that threw or returned
+ *   non-functions invoke `onError` instead.
+ * - `onPublish(id, moduleId, eventName)` runs BEFORE the engine's dispatch,
+ *   per publish call, with correct per-source attribution.
+ * - `onDetach(id, moduleId)` runs BEFORE the source's unsubscribe is called
+ *   so observers see the detach intent before any teardown side effects.
+ *   (If unsubscribe throws, `onError` fires afterward.)
+ * - `onError(id, moduleId, phase, error)` runs on attach OR cleanup failures.
+ *   Always logged via `console.error` regardless of whether this callback
+ *   is supplied.
+ */
+interface SourcesManagerCallbacks {
+    readonly onAttach?: (id: string, moduleId: string) => void;
+    readonly onPublish?: (id: string, moduleId: string, eventName: string) => void;
+    readonly onDetach?: (id: string, moduleId: string) => void;
+    readonly onError?: (id: string, moduleId: string, phase: "attach" | "cleanup" | "runtime", error: Error) => void;
+}
+interface SourcesManager {
+    registerDefinitions(moduleId: string, definitions: Record<string, SourceDef>): void;
+    /**
+     * Attach every registered source against the supplied dispatcher. Runs at
+     * `system.start()`. On a re-start, this re-arms the manager: the previous
+     * cycle's `attached` array is dropped and every source attaches afresh.
+     *
+     * The manager wraps each source's publish callback with a closure that
+     * forwards to `dispatch(sourceId, moduleId, eventName, payload)`. Sources
+     * that successfully attach also trigger the `onAttach` callback; failures
+     * trigger `onError`.
+     */
+    attachAll(dispatch: SourceDispatch): void;
+    /**
+     * Invoke every recorded unsubscribe, in reverse-registration order. Runs at
+     * `system.stop()`. Idempotent within a single attach cycle — calling twice
+     * is a no-op on the second call. The flag clears at the next `attachAll`.
+     *
+     * `onDetach` fires BEFORE each unsubscribe runs. `onError` fires AFTER if
+     * the unsubscribe throws.
+     *
+     * Sync variant kept for back-compat: async unsubscribes are kicked off
+     * (the Promise is captured but not awaited). Use {@link cleanupAllAsync}
+     * when you need to await the actual transport teardown (e.g. Supabase
+     * `channel.unsubscribe()` returns a Promise that must complete before
+     * the broker drops the subscription).
+     */
+    cleanupAll(): void;
+    /**
+     * RFC 0009: async-aware cleanup. Awaits each source's unsubscribe in
+     * reverse-registration order. Errors are caught + reported as
+     * `phase: "cleanup"` so a single failing unsubscribe cannot block the
+     * rest of the teardown.
+     *
+     * The host runtime calls this from `System.stopAsync()` /
+     * `System.destroyAsync()`. For sync `system.stop()` callers, the sync
+     * `cleanupAll` is still used (Promises from async unsubscribes are
+     * fire-and-forget).
+     */
+    cleanupAllAsync(): Promise<void>;
+    /**
+     * RFC 0009: signal eviction to every source whose definition declares
+     * `onEvict`. Runs in registration order so sources with downstream
+     * dependencies close in the right order. Errors are caught + reported
+     * as `phase: "runtime"`. After `evictAll`, the host runtime calls
+     * `cleanupAllAsync`.
+     */
+    evictAll(): Promise<void>;
+    /** Number of sources currently attached. Used by `system.inspect()`. */
+    attachedCount(): number;
+    /**
+     * List the declared source definitions for `system.inspect()`. Returns
+     * `{ id, moduleId, meta, attached, publishCount, lastPublishAt,
+     * dropCount, lastDropReason, lastDropAt, errorCount, lastError,
+     * attachedAt, detachedAt }` rows in registration order. Mirrors how
+     * effects are surfaced, with per-source telemetry an operator can read
+     * without registering a custom plugin.
+     */
+    listDefinitions(): SourceInspectionRow[];
+}
+/**
+ * Public per-source telemetry row returned by
+ * `SourcesManager.listDefinitions()` and surfaced unchanged on
+ * `SystemInspection.sources[i]`. Exported so consumers can name the type
+ * when writing helpers over the inspect output.
+ */
+interface SourceInspectionRow {
+    id: string;
+    moduleId: string;
+    meta?: unknown;
+    attached: boolean;
+    publishCount: number;
+    lastPublishAt: number | null;
+    /**
+     * Publishes the engine's dispatch guard rejected OR the manager
+     * coalesced this cycle. Operators monitor this to spot misconfigured
+     * sources (wrong event names) and to verify the coalesce strategy is
+     * actually debouncing the high-frequency sources it was meant to.
+     */
+    dropCount: number;
+    /**
+     * Reason for the most recent rejected publish, or `null`.
+     * - `"post-destroy"` / `"post-stop"` — leaked transport
+     * - `"blocked-event-name"` / `"invalid-event-name"` — guard probe
+     * - `"coalesced"` — manager debounced a same-event-name publish
+     *   ahead of the microtask flush (only when `SourceDef.coalesce`
+     *   is `"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;
+    errorCount: number;
+    lastError: SourceLastError | null;
+    attachedAt: number | null;
+    detachedAt: number | null;
+}
+/**
+ * The most recent attach or cleanup error a source has recorded this cycle.
+ * `message` is truncated to a fixed length so a source that throws with a
+ * payload-embedded message does not write unbounded data into inspect
+ * output (and downstream into the audit ledger).
+ */
+interface SourceLastError {
+    phase: "attach" | "cleanup" | "runtime";
+    message: string;
+    at: number;
+}
+/**
+ * Create a sources manager bound to a (mutable) catalogue of source
+ * definitions. The catalogue grows when modules are registered dynamically;
+ * the static modules at `createSystem` time seed it via the engine.
+ */
+declare function createSourcesManager(initialDefinitions?: Record<string, SourceDef>, initialModuleIds?: Record<string, string>, callbacks?: SourcesManagerCallbacks): SourcesManager;
+
 /**
  * Internal manager that broadcasts lifecycle events to registered {@link Plugin} instances.
  *
@@ -884,6 +1079,10 @@ interface PluginManager<_S extends Schema = any> {
     }): void;
     emitEffectRun(id: string): void;
     emitEffectError(id: string, error: unknown): void;
+    emitSourceAttach(id: string, moduleId: string): void;
+    emitSourcePublish(id: string, moduleId: string, eventName: string): void;
+    emitSourceDetach(id: string, moduleId: string): void;
+    emitSourceError(id: string, moduleId: string, phase: "attach" | "cleanup" | "runtime", error: unknown): void;
     emitSnapshot(snapshot: Snapshot): void;
     emitHistoryNavigate(from: number, to: number): void;
     emitError(error: DirectiveError): void;
@@ -1249,4 +1448,4 @@ declare function withoutTracking<T>(fn: () => T): T;
  */
 declare function trackAccess(key: string): void;
 
-export { ConstraintState, ConstraintsDef, DerivationsDef, DerivedValues, EffectsDef, ErrorSource, FactChange, FactsStore, type InflightInfo, type PendingRetry, ReconcileResult, RecoveryStrategy, RequirementKeyFn, ResolverStatus, ResolversDef, RetryLaterConfig, createConstraintsManager, createDerivationsManager, createDisabledHistory, createEffectsManager, createEngine, createErrorBoundaryManager, createFacts, createFactsProxy, createFactsStore, createHistoryManager, createPluginManager, createResolversManager, createRetryLaterManager, getCurrentDeps, isTracking, trackAccess, withTracking, withoutTracking };
+export { ConstraintState, ConstraintsDef, DerivationsDef, DerivedValues, EffectsDef, ErrorSource, FactChange, FactsStore, type InflightInfo, type PendingRetry, ReconcileResult, RecoveryStrategy, RequirementKeyFn, ResolverStatus, ResolversDef, RetryLaterConfig, type SourceDispatch, type SourceDispatchResult, type SourceInspectionRow, type SourceLastError, type SourcesManager, type SourcesManagerCallbacks, createConstraintsManager, createDerivationsManager, createDisabledHistory, createEffectsManager, createEngine, createErrorBoundaryManager, createFacts, createFactsProxy, createFactsStore, createHistoryManager, createPluginManager, createResolversManager, createRetryLaterManager, createSourcesManager, getCurrentDeps, isTracking, trackAccess, withTracking, withoutTracking };

package/dist/internals.d.ts

@@ -1,7 +1,7 @@
-import { a8 as Schema, ak as FactsStore, a as Facts, D as DefinitionMeta, E as EffectsDef, al as ConstraintsDef, r as RequirementKeyFn, R as RequirementWithId, am as ConstraintState, F as FactPredicate, C as ClauseResult, an as ResolversDef, ao as ResolverStatus, q as Requirement, P as Plugin, aa as System, ap as FactChange, z as FactsSnapshot, aq as ReconcileResult, a9 as Snapshot, s as DirectiveError, ar as RecoveryStrategy, ah as TraceEntry, as as ErrorSource, p as ErrorBoundaryConfig, at as RetryLaterConfig, H as HistoryAPI, G as HistoryOption, ab as SystemConfig } from './plugins-BpNMkJRw.js';
-export { au as BatchItemResult, av as BatchResolveResults, aw as ConstraintsControl, ax as CrossModuleConstraintDef, i as CrossModuleConstraintsDef, ay as CrossModuleDerivationFn, g as CrossModuleDerivationsDef, az as CrossModuleEffectDef, h as CrossModuleEffectsDef, aA as CrossModuleFactsWithSelf, aB as DerivationKeys, aC as DerivationReturnType, aD as DerivationsControl, aE as DerivationsSchema, aF as DeriveAccessor, aG as DispatchEventsFromSchema, t as DistributableSnapshot, u as DistributableSnapshotOptions, aH as EffectCleanup, aI as EffectsControl, aJ as EventPayloadSchema, aK as EventsAccessor, aL as EventsAccessorFromSchema, aM as EventsDef, aN as EventsSchema, aO as FactKeys, aP as FactReturnType, aQ as FlexibleEventHandler, aR as HistoryConfig, aS as InferEventPayloadFromSchema, aT as InferRequirementPayloadFromSchema, aU as InferSchema, aV as MutableNamespacedFacts, aW as NamespacedDerivations, aX as NamespacedEventsAccessor, aY as NamespacedFacts, aZ as ObservableKeys, a_ as RequirementExplanation, a$ as RequirementOutput, b0 as RequirementPayloadSchema, b1 as RequirementsSchema, b2 as ResolverContext, b3 as ResolversControl, b4 as SnapshotMeta, b5 as SystemEvent, b6 as TraceConfig, b7 as TypedConstraintDef, c as TypedConstraintsDef, T as TypedDerivationsDef, b as TypedEventsDef, b8 as TypedResolverContext, b9 as TypedResolverDef, d as TypedResolversDef, ba as UnionEvents } from './plugins-BpNMkJRw.js';
-import { w as DerivationsDef, x as DerivedValues } from './predicate-BinuVL33.js';
-export { y as DerivationState, T as TypedConstraint, z as TypedResolver, A as createConstraintFactory, B as createResolverFactory, C as dangerousRegex } from './predicate-BinuVL33.js';
+import { ah as Schema, aA as FactsStore, a as Facts, D as DefinitionMeta, E as EffectsDef, u as ConstraintsDef, s as RequirementKeyFn, R as RequirementWithId, aB as ConstraintState, F as FactPredicate, C as ClauseResult, af as ResolversDef, aC as ResolverStatus, r as Requirement, ak as SourceDef, P as Plugin, ao as System, aD as FactChange, O as FactsSnapshot, aE as ReconcileResult, aj as Snapshot, x as DirectiveError, aF as RecoveryStrategy, av as TraceEntry, aG as ErrorSource, q as ErrorBoundaryConfig, aH as RetryLaterConfig, Q as HistoryAPI, U as HistoryOption, ap as SystemConfig } from './plugins-xpm4B7Nt.js';
+export { aI as BatchItemResult, aJ as BatchResolveResults, aK as ConstraintsControl, v as CrossModuleConstraintDef, j as CrossModuleConstraintsDef, aL as CrossModuleDerivationFn, h as CrossModuleDerivationsDef, w as CrossModuleEffectDef, i as CrossModuleEffectsDef, aM as CrossModuleFactsWithSelf, aN as DerivationKeys, aO as DerivationReturnType, aP as DerivationsControl, aQ as DerivationsSchema, aR as DeriveAccessor, aS as DispatchEventsFromSchema, y as DistributableSnapshot, z as DistributableSnapshotOptions, aT as EffectCleanup, aU as EffectsControl, aV as EventPayloadSchema, aW as EventsAccessor, aX as EventsAccessorFromSchema, K as EventsDef, aY as EventsSchema, aZ as FactKeys, a_ as FactReturnType, a$ as FlexibleEventHandler, b0 as HistoryConfig, b1 as InferEventPayloadFromSchema, b2 as InferRequirementPayloadFromSchema, b3 as InferSchema, b4 as MutableNamespacedFacts, b5 as NamespacedDerivations, b6 as NamespacedEventsAccessor, b7 as NamespacedFacts, b8 as ObservableKeys, b9 as RequirementExplanation, ba as RequirementOutput, bb as RequirementPayloadSchema, bc as RequirementsSchema, bd as ResolverContext, be as ResolversControl, bf as SnapshotMeta, bg as SystemEvent, bh as TraceConfig, aw as TypedConstraintDef, d as TypedConstraintsDef, T as TypedDerivationsDef, b as TypedEventsDef, bi as TypedResolverContext, ax as TypedResolverDef, e as TypedResolversDef, bj as UnionEvents } from './plugins-xpm4B7Nt.js';
+import { b as DerivationsDef, y as DerivedValues } from './predicate-fpUoy77T.js';
+export { z as DerivationState, T as TypedConstraint, A as TypedResolver, B as createConstraintFactory, C as createResolverFactory, E as dangerousRegex } from './predicate-fpUoy77T.js';
 export { h as hashObject, g as isPrototypeSafe, j as safeStringify, k as stableStringify } from './utils-BZBBwS5A.js';
 
 /**
@@ -810,6 +810,201 @@ interface CreateResolversOptions<S extends Schema> {
  */
 declare function createResolversManager<S extends Schema>(options: CreateResolversOptions<S>): ResolversManager<S>;
 
+/**
+ * Sources Manager — lifecycle owner for typed external event sources.
+ *
+ * Sources attach at {@link System.start} and tear down at {@link System.stop}.
+ * The manager supports the full start → stop → start → stop re-entry cycle:
+ * each `attachAll` re-arms the manager, each `cleanupAll` is idempotent until
+ * the next `attachAll`. Failures inside attach or unsubscribe are isolated so
+ * a single misbehaving source cannot prevent other sources (or the system
+ * itself) from completing their lifecycle.
+ *
+ * The manager also supports {@link SourcesManager.registerDefinitions} for
+ * dynamic module registration via {@link System.registerModule}: sources
+ * declared on a module registered AFTER the system has started attach
+ * immediately; sources declared before the next `start` queue up and attach
+ * with the rest.
+ *
+ * The manager invokes per-source lifecycle callbacks (`onAttach`,
+ * `onPublish`, `onDetach`, `onError`) so the engine can emit accurate plugin
+ * observation events — including correct per-source attribution even when
+ * two sources publish the same event name.
+ *
+ * See {@link SourceDef} for the primitive's full semantics + rationale.
+ */
+
+/**
+ * Engine-side dispatcher invoked when a source publishes an event. The
+ * manager wraps each source's publish callback in a closure that closes
+ * over the source id + moduleId so the engine cannot mis-attribute
+ * publishes (a naive "look up the source by event name" approach fails
+ * when multiple sources publish the same event).
+ *
+ * Returns a {@link SourceDispatchResult} indicating whether the engine
+ * accepted the publish. The manager uses the result to gate counter bumps
+ * + `onPublish` plugin emission: an accepted publish bumps `publishCount`
+ * and fires `onPublish`; a rejected publish bumps `dropCount` /
+ * `lastDropReason` and stays out of the plugin hook (otherwise observers
+ * would see "publish happened" for events the engine swallowed).
+ */
+type SourceDispatch = (sourceId: string, moduleId: string, eventName: string, payload: unknown) => SourceDispatchResult;
+/**
+ * Outcome of a single source publish handed back to the manager. `"accepted"`
+ * means the engine dispatched into the event handler chain. Rejection
+ * reasons name the specific drop path so per-source telemetry can attribute
+ * the drop precisely:
+ *
+ * - `"post-destroy"` — publish arrived after `system.destroy()`.
+ * - `"post-stop"` — publish arrived between `system.stop()` and the next
+ *   `system.start()`.
+ * - `"blocked-event-name"` — event name was `__proto__` / `constructor` /
+ *   `prototype` (BLOCKED_PROPS guard, parity with `system.dispatch`).
+ * - `"invalid-event-name"` — event name was non-string or empty string.
+ */
+type SourceDispatchResult = {
+    accepted: true;
+} | {
+    accepted: false;
+    reason: "post-destroy" | "post-stop" | "blocked-event-name" | "invalid-event-name" | "coalesced";
+};
+/**
+ * Per-source lifecycle callbacks the engine wires into the plugin manager.
+ * All are optional — manager-only consumers can omit them. The manager
+ * GUARANTEES:
+ *
+ * - `onAttach(id, moduleId)` runs ONLY when `attach()` returned a function
+ *   (i.e. the source successfully attached). Sources that threw or returned
+ *   non-functions invoke `onError` instead.
+ * - `onPublish(id, moduleId, eventName)` runs BEFORE the engine's dispatch,
+ *   per publish call, with correct per-source attribution.
+ * - `onDetach(id, moduleId)` runs BEFORE the source's unsubscribe is called
+ *   so observers see the detach intent before any teardown side effects.
+ *   (If unsubscribe throws, `onError` fires afterward.)
+ * - `onError(id, moduleId, phase, error)` runs on attach OR cleanup failures.
+ *   Always logged via `console.error` regardless of whether this callback
+ *   is supplied.
+ */
+interface SourcesManagerCallbacks {
+    readonly onAttach?: (id: string, moduleId: string) => void;
+    readonly onPublish?: (id: string, moduleId: string, eventName: string) => void;
+    readonly onDetach?: (id: string, moduleId: string) => void;
+    readonly onError?: (id: string, moduleId: string, phase: "attach" | "cleanup" | "runtime", error: Error) => void;
+}
+interface SourcesManager {
+    registerDefinitions(moduleId: string, definitions: Record<string, SourceDef>): void;
+    /**
+     * Attach every registered source against the supplied dispatcher. Runs at
+     * `system.start()`. On a re-start, this re-arms the manager: the previous
+     * cycle's `attached` array is dropped and every source attaches afresh.
+     *
+     * The manager wraps each source's publish callback with a closure that
+     * forwards to `dispatch(sourceId, moduleId, eventName, payload)`. Sources
+     * that successfully attach also trigger the `onAttach` callback; failures
+     * trigger `onError`.
+     */
+    attachAll(dispatch: SourceDispatch): void;
+    /**
+     * Invoke every recorded unsubscribe, in reverse-registration order. Runs at
+     * `system.stop()`. Idempotent within a single attach cycle — calling twice
+     * is a no-op on the second call. The flag clears at the next `attachAll`.
+     *
+     * `onDetach` fires BEFORE each unsubscribe runs. `onError` fires AFTER if
+     * the unsubscribe throws.
+     *
+     * Sync variant kept for back-compat: async unsubscribes are kicked off
+     * (the Promise is captured but not awaited). Use {@link cleanupAllAsync}
+     * when you need to await the actual transport teardown (e.g. Supabase
+     * `channel.unsubscribe()` returns a Promise that must complete before
+     * the broker drops the subscription).
+     */
+    cleanupAll(): void;
+    /**
+     * RFC 0009: async-aware cleanup. Awaits each source's unsubscribe in
+     * reverse-registration order. Errors are caught + reported as
+     * `phase: "cleanup"` so a single failing unsubscribe cannot block the
+     * rest of the teardown.
+     *
+     * The host runtime calls this from `System.stopAsync()` /
+     * `System.destroyAsync()`. For sync `system.stop()` callers, the sync
+     * `cleanupAll` is still used (Promises from async unsubscribes are
+     * fire-and-forget).
+     */
+    cleanupAllAsync(): Promise<void>;
+    /**
+     * RFC 0009: signal eviction to every source whose definition declares
+     * `onEvict`. Runs in registration order so sources with downstream
+     * dependencies close in the right order. Errors are caught + reported
+     * as `phase: "runtime"`. After `evictAll`, the host runtime calls
+     * `cleanupAllAsync`.
+     */
+    evictAll(): Promise<void>;
+    /** Number of sources currently attached. Used by `system.inspect()`. */
+    attachedCount(): number;
+    /**
+     * List the declared source definitions for `system.inspect()`. Returns
+     * `{ id, moduleId, meta, attached, publishCount, lastPublishAt,
+     * dropCount, lastDropReason, lastDropAt, errorCount, lastError,
+     * attachedAt, detachedAt }` rows in registration order. Mirrors how
+     * effects are surfaced, with per-source telemetry an operator can read
+     * without registering a custom plugin.
+     */
+    listDefinitions(): SourceInspectionRow[];
+}
+/**
+ * Public per-source telemetry row returned by
+ * `SourcesManager.listDefinitions()` and surfaced unchanged on
+ * `SystemInspection.sources[i]`. Exported so consumers can name the type
+ * when writing helpers over the inspect output.
+ */
+interface SourceInspectionRow {
+    id: string;
+    moduleId: string;
+    meta?: unknown;
+    attached: boolean;
+    publishCount: number;
+    lastPublishAt: number | null;
+    /**
+     * Publishes the engine's dispatch guard rejected OR the manager
+     * coalesced this cycle. Operators monitor this to spot misconfigured
+     * sources (wrong event names) and to verify the coalesce strategy is
+     * actually debouncing the high-frequency sources it was meant to.
+     */
+    dropCount: number;
+    /**
+     * Reason for the most recent rejected publish, or `null`.
+     * - `"post-destroy"` / `"post-stop"` — leaked transport
+     * - `"blocked-event-name"` / `"invalid-event-name"` — guard probe
+     * - `"coalesced"` — manager debounced a same-event-name publish
+     *   ahead of the microtask flush (only when `SourceDef.coalesce`
+     *   is `"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;
+    errorCount: number;
+    lastError: SourceLastError | null;
+    attachedAt: number | null;
+    detachedAt: number | null;
+}
+/**
+ * The most recent attach or cleanup error a source has recorded this cycle.
+ * `message` is truncated to a fixed length so a source that throws with a
+ * payload-embedded message does not write unbounded data into inspect
+ * output (and downstream into the audit ledger).
+ */
+interface SourceLastError {
+    phase: "attach" | "cleanup" | "runtime";
+    message: string;
+    at: number;
+}
+/**
+ * Create a sources manager bound to a (mutable) catalogue of source
+ * definitions. The catalogue grows when modules are registered dynamically;
+ * the static modules at `createSystem` time seed it via the engine.
+ */
+declare function createSourcesManager(initialDefinitions?: Record<string, SourceDef>, initialModuleIds?: Record<string, string>, callbacks?: SourcesManagerCallbacks): SourcesManager;
+
 /**
  * Internal manager that broadcasts lifecycle events to registered {@link Plugin} instances.
  *
@@ -884,6 +1079,10 @@ interface PluginManager<_S extends Schema = any> {
     }): void;
     emitEffectRun(id: string): void;
     emitEffectError(id: string, error: unknown): void;
+    emitSourceAttach(id: string, moduleId: string): void;
+    emitSourcePublish(id: string, moduleId: string, eventName: string): void;
+    emitSourceDetach(id: string, moduleId: string): void;
+    emitSourceError(id: string, moduleId: string, phase: "attach" | "cleanup" | "runtime", error: unknown): void;
     emitSnapshot(snapshot: Snapshot): void;
     emitHistoryNavigate(from: number, to: number): void;
     emitError(error: DirectiveError): void;
@@ -1249,4 +1448,4 @@ declare function withoutTracking<T>(fn: () => T): T;
  */
 declare function trackAccess(key: string): void;
 
-export { ConstraintState, ConstraintsDef, DerivationsDef, DerivedValues, EffectsDef, ErrorSource, FactChange, FactsStore, type InflightInfo, type PendingRetry, ReconcileResult, RecoveryStrategy, RequirementKeyFn, ResolverStatus, ResolversDef, RetryLaterConfig, createConstraintsManager, createDerivationsManager, createDisabledHistory, createEffectsManager, createEngine, createErrorBoundaryManager, createFacts, createFactsProxy, createFactsStore, createHistoryManager, createPluginManager, createResolversManager, createRetryLaterManager, getCurrentDeps, isTracking, trackAccess, withTracking, withoutTracking };
+export { ConstraintState, ConstraintsDef, DerivationsDef, DerivedValues, EffectsDef, ErrorSource, FactChange, FactsStore, type InflightInfo, type PendingRetry, ReconcileResult, RecoveryStrategy, RequirementKeyFn, ResolverStatus, ResolversDef, RetryLaterConfig, type SourceDispatch, type SourceDispatchResult, type SourceInspectionRow, type SourceLastError, type SourcesManager, type SourcesManagerCallbacks, createConstraintsManager, createDerivationsManager, createDisabledHistory, createEffectsManager, createEngine, createErrorBoundaryManager, createFacts, createFactsProxy, createFactsStore, createHistoryManager, createPluginManager, createResolversManager, createRetryLaterManager, createSourcesManager, getCurrentDeps, isTracking, trackAccess, withTracking, withoutTracking };

package/dist/internals.js

@@ -1,2 +1,2 @@
-export{c as createConstraintFactory,p as createConstraintsManager,q as createDerivationsManager,j as createDisabledHistory,r as createEffectsManager,z as createEngine,t as createErrorBoundaryManager,w as createFacts,v as createFactsProxy,u as createFactsStore,i as createHistoryManager,x as createPluginManager,d as createResolverFactory,y as createResolversManager,s as createRetryLaterManager}from'./chunk-RWJV7QLM.js';export{m as dangerousRegex}from'./chunk-O4GQEV4G.js';export{f as getCurrentDeps,g as isTracking,j as trackAccess,h as withTracking,i as withoutTracking}from'./chunk-3ETCZLAY.js';export{h as hashObject,f as isPrototypeSafe,o as safeStringify,e as stableStringify}from'./chunk-PXRV64PA.js';//# sourceMappingURL=internals.js.map
+export{c as createConstraintFactory,p as createConstraintsManager,q as createDerivationsManager,j as createDisabledHistory,r as createEffectsManager,A as createEngine,t as createErrorBoundaryManager,w as createFacts,v as createFactsProxy,u as createFactsStore,i as createHistoryManager,x as createPluginManager,d as createResolverFactory,y as createResolversManager,s as createRetryLaterManager,z as createSourcesManager}from'./chunk-NPKUAG3Q.js';export{m as dangerousRegex}from'./chunk-O4GQEV4G.js';export{f as getCurrentDeps,g as isTracking,j as trackAccess,h as withTracking,i as withoutTracking}from'./chunk-3ETCZLAY.js';export{h as hashObject,f as isPrototypeSafe,o as safeStringify,e as stableStringify}from'./chunk-PXRV64PA.js';//# sourceMappingURL=internals.js.map
 //# sourceMappingURL=internals.js.map