@directive-run/core 1.1.2 → 1.4.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { S as SchemaType, D as DefinitionMeta, M as ModuleSchema, F as Facts, T as TypedDerivationsDef, a as TypedEventsDef, E as EffectsDef, b as TypedConstraintsDef, c as TypedResolversDef, d as ModuleHooks, C as CrossModuleDeps, e as CrossModuleDerivationsDef, f as CrossModuleEffectsDef, g as CrossModuleConstraintsDef, h as ModuleDef, i as CreateSystemOptionsSingle, j as SingleModuleSystem, k as ModulesMap, l as CreateSystemOptionsNamed, N as NamespacedSystem, P as Plugin, m as TraceOption, n as ErrorBoundaryConfig, R as RequirementWithId, o as Requirement, p as RequirementKeyFn } from './plugins-2i_wXhw1.cjs';
-export { A as AnySystem, B as BatchConfig, q as DirectiveError, r as DistributableSnapshot, s as DistributableSnapshotOptions, t as DynamicConstraintDef, u as DynamicEffectDef, v as DynamicResolverDef, w as FactsSnapshot, H as HistoryAPI, x as HistoryOption, y as HistoryState, I as InferDerivations, z as InferEvents, G as InferFacts, J as InferRequirementTypes, K as InferRequirements, L as InferSchemaType, O as InferSelectorState, Q as MetaAccessor, U as MetaMatch, V as ObservationEvent, W as RetryPolicy, X as Schema, Y as Snapshot, Z as System, _ as SystemConfig, $ as SystemInspection, a0 as SystemMode, a1 as SystemSnapshot, a2 as TraceEntry, a3 as isNamespacedSystem, a4 as isSingleModuleSystem } from './plugins-2i_wXhw1.cjs';
-export { D as DerivationDefWithMeta, t as typedConstraint, a as typedResolver } from './helpers-mM-gApmO.cjs';
+import { S as SchemaType, D as DefinitionMeta, M as ModuleSchema, F as Facts, T as TypedDerivationsDef, a as TypedEventsDef, E as EffectsDef, b as TypedConstraintsDef, c as TypedResolversDef, d as ModuleHooks, C as CrossModuleDeps, e as CrossModuleDerivationsDef, f as CrossModuleEffectsDef, g as CrossModuleConstraintsDef, h as ModuleDef, i as CreateSystemOptionsSingle, j as SingleModuleSystem, k as ModulesMap, l as CreateSystemOptionsNamed, N as NamespacedSystem, P as Plugin, m as TraceOption, n as ErrorBoundaryConfig, R as RequirementWithId, o as Requirement, p as RequirementKeyFn } from './plugins-Dy1C8GtT.cjs';
+export { A as AnySystem, B as BatchConfig, q as DirectiveError, r as DistributableSnapshot, s as DistributableSnapshotOptions, t as DynamicConstraintDef, u as DynamicEffectDef, v as DynamicResolverDef, w as FactsSnapshot, H as HistoryAPI, x as HistoryOption, y as HistoryState, I as InferDerivations, z as InferEvents, G as InferFacts, J as InferRequirementTypes, K as InferRequirements, L as InferSchemaType, O as InferSelectorState, Q as MetaAccessor, U as MetaMatch, V as ObservationEvent, W as RetryPolicy, X as Schema, Y as Snapshot, Z as System, _ as SystemConfig, $ as SystemInspection, a0 as SystemMode, a1 as SystemSnapshot, a2 as TraceEntry, a3 as isNamespacedSystem, a4 as isSingleModuleSystem } from './plugins-Dy1C8GtT.cjs';
+export { D as DerivationDefWithMeta, t as typedConstraint, a as typedResolver } from './helpers-BUY1lYCX.cjs';
 export { D as DistributableSnapshotLike, S as SignedSnapshot, a as SnapshotDiff, b as SnapshotDiffEntry, d as diffSnapshots, i as isSignedSnapshot, c as isSnapshotExpired, s as shallowEqual, e as signSnapshot, v as validateSnapshot, f as verifySnapshotSignature } from './utils-BnQajqPu.cjs';
 
 /** Brand symbol for branded types */
@@ -36,6 +36,21 @@ interface ChainableSchemaType<T> extends ExtendedSchemaType<T> {
     /** Attach metadata for debugging and devtools. */
     meta(meta: DefinitionMeta): ChainableSchemaType<T>;
 }
+/**
+ * Two-form union schema constructor.
+ *
+ * Hoisted out of the `t` object literal because the overload-cast pattern
+ * (`(impl) as { ovl1; ovl2 }`) inside an object literal triggers a TS
+ * declaration-emit "implicitly has type any" cycle. Annotating the const
+ * with the explicit overload type breaks the cycle so DTS can emit `t`'s
+ * shape without recursing through the runtime expression.
+ *
+ * @internal
+ */
+type UnionFn = {
+    <T = unknown>(): ChainableSchemaType<T>;
+    <T extends SchemaType<unknown>[]>(...types: T): ChainableSchemaType<T[number] extends SchemaType<infer U> ? U : never>;
+};
 /**
  * Schema type builders for defining fact types.
  *
@@ -210,16 +225,38 @@ declare const t: {
     /**
      * Create a union schema type.
      *
+     * **Two forms:**
+     * - `t.union(t.string(), t.number())` — variadic schema args; the runtime
+     *   validator checks that the value matches at least one inner schema.
+     * - `t.union<string | number | boolean>()` — generic-only form with no
+     *   schema args; the runtime validator accepts ANY value (mirrors
+     *   {@link unknown} plus generic narrowing). Use this for polymorphic
+     *   payloads where the union is too dynamic to enumerate as inner schemas
+     *   (e.g. an `UPDATE_FIELD` event whose `value` may be `string | number |
+     *   boolean | Date`).
+     *
+     * Chainable methods (`.validate`, `.transform`, `.default`, `.describe`,
+     * `.refine`, `.optional`, `.nullable`) work the same for both forms.
+     *
      * @example
      * ```typescript
-     * // String or number
+     * // Variadic — runtime validation against inner schemas
      * schema: { value: t.union(t.string(), t.number()) }
      *
-     * // Multiple types
-     * schema: { data: t.union(t.string(), t.number(), t.boolean()) }
+     * // Generic-only — type-only narrowing, runtime accepts any value
+     * schema: {
+     *   payload: t.union<string | number | boolean>(),
+     * }
+     *
+     * // Add a custom predicate via .validate when you still want a runtime check
+     * schema: {
+     *   strict: t.union<string | number>().validate(
+     *     (v) => typeof v === "string" || typeof v === "number",
+     *   ),
+     * }
      * ```
      */
-    union<T extends SchemaType<unknown>[]>(...types: T): ChainableSchemaType<T[number] extends SchemaType<infer U> ? U : never>;
+    union: UnionFn;
     /**
      * Create a record schema type for dynamic key-value maps.
      *
@@ -478,6 +515,15 @@ interface ModuleConfigWithDeps<M extends ModuleSchema, Deps extends CrossModuleD
  *       },
  *     },
  *   },
+ *   hooks: {
+ *     // Optional: observe resolver failures owned by this module.
+ *     // Fires AFTER retries are exhausted and the engine has handled the error
+ *     // (error boundary, plugin emit, retry decision). Use it as a side-channel
+ *     // observer for module-local logging/telemetry — not for recovery.
+ *     onResolverError: (error, requirement, ctx) => {
+ *       console.warn(`[traffic-light] resolver failed for ${requirement.type}`, error);
+ *     },
+ *   },
  * });
  * ```
  *
@@ -921,6 +967,259 @@ declare class RequirementSet {
     };
 }
 
+/**
+ * SignalClock — injectable clock source for declarative timers (RFC 0001).
+ *
+ * The clock interface decouples Directive's timer primitives from any
+ * single time source. Production uses `realClock()`. Tests use
+ * `virtualClock()` which advances synchronously via `clock.advanceBy()`.
+ * Replay / dehydrate scenarios use a clock seeded from the recorded
+ * stream.
+ *
+ * Auto-detection: `defaultClock()` returns `virtualClock()` when running
+ * under Vitest (process.env.VITEST === 'true'), otherwise `realClock()`.
+ * Consumers can pass an explicit clock to `createSystem({ clock })` to
+ * override.
+ *
+ * @see ../../docs/rfcs/0001-t-timer.md
+ */
+/**
+ * Stable interface for any time source.
+ */
+interface SignalClock {
+    /** Current time, in milliseconds since the Unix epoch. */
+    now(): number;
+    /**
+     * Schedule a callback to fire after `ms` milliseconds. Returns a
+     * cancellation function. Implementations may queue callbacks or fire
+     * them on a tick boundary; the only contract is "fires no earlier
+     * than `ms` from now."
+     */
+    setTimeout(cb: () => void, ms: number): () => void;
+    /**
+     * (Test-only.) Synchronously advance the clock by `ms` milliseconds,
+     * firing all scheduled callbacks whose deadlines fall within the
+     * advanced window. Real clocks throw if called.
+     */
+    advanceBy?(ms: number): void;
+}
+/**
+ * Production clock — wraps `Date.now()` and `globalThis.setTimeout`.
+ * No mocking, no virtualization.
+ */
+declare function realClock(): SignalClock;
+/**
+ * Virtual clock — advances only when `advanceBy(ms)` is called. All
+ * scheduled callbacks fire synchronously in order of their deadlines.
+ *
+ * Two scheduled callbacks at the same deadline fire in registration order.
+ * Cancellation is O(1).
+ */
+declare function virtualClock(initialMs?: number): SignalClock;
+/**
+ * Returns `realClock()` always.
+ *
+ * Earlier drafts auto-detected vitest (`process.env.VITEST === 'true'`)
+ * and returned a `virtualClock()` in that environment. AE review
+ * flagged this as a footgun: tests that legitimately need real time
+ * (sleep-based debounce checks, real-`setTimeout`-bound integration
+ * fixtures) silently received a virtual clock that never advanced
+ * unless the test author called `advanceBy()`, producing apparent
+ * deadlocks indistinguishable from genuine bugs. Auto-detection is
+ * therefore opt-in.
+ *
+ * Use {@link virtualClock} explicitly in tests:
+ *
+ * ```ts
+ * const clock = virtualClock(0);
+ * const sys = createSystem({ module, clock });
+ * clock.advanceBy(1_000);
+ * ```
+ */
+declare function defaultClock(): SignalClock;
+
+/**
+ * Timer fact — a runtime container that advances over time on a
+ * SignalClock (RFC 0001 v0.1).
+ *
+ * Produced by `createTimerFact(clock, opts)`. Holds the durable state
+ * (startedAtMs, pausedDurationMs, status) and exposes a control surface
+ * (start, pause, resume, reset) plus reactive reads (elapsedMs,
+ * remainingMs, status).
+ *
+ * v0.1 SCOPE: timer is a "thick fact" — a single object you store in a
+ * regular Directive fact (e.g. `t.object<TimerFactState>()`). The
+ * engine doesn't auto-tick it; the consumer is responsible for calling
+ * `timer.tick()` when they want elapsedMs / remainingMs to update.
+ * Typical wiring: a setInterval in the consumer that calls `timer.tick()`
+ * and dispatches an event when status changes.
+ *
+ * v0.2 (deferred): true `t.timer({ms})` schema integration where the
+ * engine subscribes to the clock and writes the fact deltas itself,
+ * eliminating the consumer-side tick wiring.
+ *
+ * @see ../../docs/rfcs/0001-t-timer.md
+ */
+/**
+ * Persistent timer state — JSON-roundtrippable, suitable for storing
+ * inside a Directive fact.
+ */
+interface TimerFactState {
+    /** Unix-ms when the timer last started or resumed. null = not running. */
+    startedAtMs: number | null;
+    /** Total ms accumulated while paused. */
+    pausedDurationMs: number;
+    /** ms when the timer was paused, if currently paused. null otherwise. */
+    pausedAtMs: number | null;
+    /**
+     * - 'idle': not yet started, or reset.
+     * - 'running': currently counting.
+     * - 'paused': paused; pausedAtMs is set.
+     * - 'completed': hit the deadline (countdown mode only).
+     */
+    status: "idle" | "running" | "paused" | "completed";
+    /** Number of times the timer has fired (repeat mode only). */
+    repeats: number;
+}
+interface TimerFactOpts {
+    /** Duration in ms. Countdown mode counts this down; up mode counts up to ∞. */
+    ms: number;
+    /**
+     * - 'down' (default): counts down from `ms` to 0; status → 'completed' at 0.
+     * - 'up': counts elapsed time; never completes.
+     * - 'repeat': fires every `ms`; increments `repeats`; status stays 'running'.
+     */
+    mode?: "down" | "up" | "repeat";
+}
+/**
+ * Initial state for a newly-created timer. Pass this to your Directive
+ * `init()` to seed the fact.
+ */
+declare function initialTimerState(): TimerFactState;
+/**
+ * Compute elapsed ms for a given timer state at a given clock-now.
+ * Pure function — no side effects, no reads beyond its inputs.
+ *
+ * @example
+ * ```ts
+ * const elapsed = elapsedMs(facts.countdown, clock.now());
+ * if (elapsed >= 60_000) {
+ *   facts.countdown = { ...facts.countdown, status: 'completed' };
+ * }
+ * ```
+ */
+declare function elapsedMs(state: TimerFactState, nowMs: number): number;
+/**
+ * Compute remaining ms for a countdown timer at a given clock-now.
+ * Returns 0 if the timer has hit zero or hasn't started.
+ */
+declare function remainingMs(state: TimerFactState, nowMs: number, totalMs: number): number;
+/**
+ * Transition: start an idle (or reset) timer.
+ *
+ * No-op if already running, paused, or completed (use `reset()` first).
+ */
+declare function startTimer(state: TimerFactState, nowMs: number): TimerFactState;
+/**
+ * Transition: pause a running timer. Records the pause moment so a
+ * later `resumeTimer()` can correctly extend pausedDurationMs.
+ *
+ * No-op if not running.
+ */
+declare function pauseTimer(state: TimerFactState, nowMs: number): TimerFactState;
+/**
+ * Transition: resume a paused timer. Adds the time spent paused into
+ * `pausedDurationMs` so elapsed/remaining math stays correct.
+ *
+ * No-op if not paused.
+ */
+declare function resumeTimer(state: TimerFactState, nowMs: number): TimerFactState;
+/**
+ * Transition: reset a timer to idle. Loses all elapsed time + repeat
+ * count. Equivalent to `initialTimerState()`.
+ */
+declare function resetTimer(): TimerFactState;
+/**
+ * Transition: mark the timer completed. For countdown mode when
+ * elapsed >= ms; for repeat mode when consumer wants to halt.
+ */
+declare function completeTimer(state: TimerFactState): TimerFactState;
+/**
+ * Transition: register a repeat firing. Increments `repeats` and
+ * advances `startedAtMs` by `ms` so the next interval lands at the
+ * intended boundary (drift-free).
+ */
+declare function registerRepeat(state: TimerFactState, ms: number): TimerFactState;
+/**
+ * Higher-level helper: given a timer state, total ms, and the current
+ * clock, return whether the timer should transition to 'completed' (for
+ * countdown mode) or fire a repeat (for repeat mode).
+ *
+ * Pure — does not mutate state. Returns a structured signal the consumer
+ * applies via `completeTimer` / `registerRepeat`.
+ */
+declare function tickTimer(state: TimerFactState, nowMs: number, opts: TimerFactOpts): {
+    kind: "no-op";
+} | {
+    kind: "complete";
+} | {
+    kind: "repeat";
+};
+/**
+ * Bundle of helpers for one timer in one module — convenience for
+ * callers who want a single import. Each method takes the current
+ * state and clock-now, returns the next state. No mutation.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createSystem,
+ *   t,
+ *   realClock,
+ *   timerOps,
+ *   initialTimerState,
+ *   type TimerFactState,
+ * } from '@directive-run/core';
+ *
+ * const clock = realClock();
+ * const ops = timerOps({ ms: 60_000, mode: 'down' });
+ *
+ * createModule('countdown', {
+ *   schema: { facts: { state: t.object<TimerFactState>() }, events: { START: {} } },
+ *   init: (f) => { f.state = initialTimerState(); },
+ *   events: {
+ *     START: (f) => { f.state = ops.start(f.state, clock.now()); },
+ *   },
+ * });
+ *
+ * // In the consumer (React, Node, edge), tick periodically:
+ * setInterval(() => {
+ *   const signal = ops.tick(f.state, clock.now());
+ *   if (signal.kind === 'complete') {
+ *     sys.dispatch({ type: 'TIMEOUT' });
+ *   }
+ * }, 100);
+ * ```
+ */
+declare function timerOps(opts: TimerFactOpts): {
+    initial: typeof initialTimerState;
+    start: typeof startTimer;
+    pause: typeof pauseTimer;
+    resume: typeof resumeTimer;
+    reset: typeof resetTimer;
+    complete: typeof completeTimer;
+    registerRepeat: (state: TimerFactState) => TimerFactState;
+    tick: (state: TimerFactState, nowMs: number) => {
+        kind: "no-op";
+    } | {
+        kind: "complete";
+    } | {
+        kind: "repeat";
+    };
+    elapsedMs: typeof elapsedMs;
+    remainingMs: (state: TimerFactState, nowMs: number) => number;
+};
+
 /**
  * @directive-run/core
  *
@@ -956,4 +1255,4 @@ declare const Backoff: {
     readonly Exponential: "exponential";
 };
 
-export { Backoff, type Branded, type ChainableSchemaType, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleDeps, DefinitionMeta, ErrorBoundaryConfig, type ExtendedSchemaType, Facts, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, Plugin, Requirement, RequirementSet, type RequirementTypeStatus, RequirementWithId, SchemaType, SingleModuleSystem, TraceOption, createModule, createModuleFactory, createRequirementStatusPlugin, createStatusHook, createSystem, createSystemWithStatus, forType, generateRequirementId, isRequirementType, req, t };
+export { Backoff, type Branded, type ChainableSchemaType, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleDeps, DefinitionMeta, ErrorBoundaryConfig, type ExtendedSchemaType, Facts, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, Plugin, Requirement, RequirementSet, type RequirementTypeStatus, RequirementWithId, SchemaType, type SignalClock, SingleModuleSystem, type TimerFactOpts, type TimerFactState, TraceOption, completeTimer, createModule, createModuleFactory, createRequirementStatusPlugin, createStatusHook, createSystem, createSystemWithStatus, defaultClock, elapsedMs, forType, generateRequirementId, initialTimerState, isRequirementType, pauseTimer, realClock, registerRepeat, remainingMs, req, resetTimer, resumeTimer, startTimer, t, tickTimer, timerOps, virtualClock };