@directive-run/core 0.8.9 → 1.0.0

package/dist/{plugins-Bg_oq2sO.d.cts → plugins-O-3VHejK.d.cts}

@@ -186,6 +186,46 @@ interface FactChange {
     type: "set" | "delete";
 }
 
+/**
+ * Definition Metadata - Optional annotations for debugging and devtools
+ */
+/**
+ * Optional metadata for module, fact, event, constraint, resolver, effect, and derivation definitions.
+ *
+ * Meta is purely informational — it is never read during the reconciliation
+ * hot path. It surfaces in `system.inspect()`, `system.explain()`, and the
+ * devtools plugin to provide human-readable context for debugging.
+ *
+ * **Note:** Meta values are string literals that survive minification and ship
+ * in production bundles. Avoid putting internal API paths or sensitive business
+ * logic in meta fields.
+ *
+ * @example
+ * ```typescript
+ * constraints: {
+ *   needsLogin: {
+ *     when: (facts) => !facts.user,
+ *     require: { type: "LOGIN" },
+ *     meta: { label: "Requires Auth", category: "auth" },
+ *   },
+ * },
+ * ```
+ */
+interface DefinitionMeta {
+    /** Human-readable name shown in inspect(), explain(), and devtools. */
+    label?: string;
+    /** Longer explanation. Shown in explain() causal chains and devtools tooltips. */
+    description?: string;
+    /** Grouping key for devtools filtering. Suggested: "auth", "data", "ui", "logging", "lifecycle". */
+    category?: string;
+    /** CSS hex color for devtools visualization (e.g., "#f59e0b"). */
+    color?: string;
+    /** Multi-dimensional labels for filtering. Use alongside category for fine-grained grouping. */
+    tags?: string[];
+    /** Extensible — plugins can read custom keys without core releases. */
+    [key: string]: unknown;
+}
+
 /**
  * Requirement Types - Type definitions for requirements and constraints
  */
@@ -260,6 +300,8 @@ interface ConstraintDef<S extends Schema, R extends Requirement = Requirement> {
      * bypass auto-tracking overhead.
      */
     deps?: string[];
+    /** Optional metadata for debugging and devtools (never read on hot path). */
+    meta?: DefinitionMeta;
 }
 /** Map of constraint definitions (generic) */
 type ConstraintsDef<S extends Schema> = Record<string, ConstraintDef<S, Requirement>>;
@@ -344,6 +386,8 @@ interface EffectDef<S extends Schema> {
     run(facts: Facts<S>, prev: InferSchema<S> | null): void | EffectCleanup | Promise<void | EffectCleanup>;
     /** Optional explicit dependencies for optimization */
     deps?: Array<keyof InferSchema<S>>;
+    /** Optional metadata for debugging and devtools (never read on hot path). */
+    meta?: DefinitionMeta;
 }
 /** Map of effect definitions */
 type EffectsDef<S extends Schema> = Record<string, EffectDef<S>>;
@@ -491,6 +535,8 @@ interface ResolverDef<S extends Schema, R extends Requirement = Requirement> {
      * ```
      */
     resolveBatchWithResults?: (reqs: R[], ctx: ResolverContext<S>) => Promise<BatchResolveResults>;
+    /** Optional metadata for debugging and devtools (never read on hot path). */
+    meta?: DefinitionMeta;
 }
 /** Map of resolver definitions */
 type ResolversDef<S extends Schema> = Record<string, ResolverDef<S, Requirement>>;
@@ -747,6 +793,8 @@ interface NamespacedSystem<Modules extends ModulesMap> {
     readonly effects: EffectsControl;
     /** Runtime control for resolvers (dynamic CRUD) */
     readonly resolvers: ResolversControl;
+    /** O(1) metadata queries for constraints, resolvers, effects, derivations. */
+    readonly meta: MetaAccessor;
     /** Per-run trace entries (null if trace is not enabled) */
     readonly trace: TraceEntry[] | null;
     /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
@@ -984,6 +1032,8 @@ interface SingleModuleSystem<S extends ModuleSchema> {
     readonly effects: EffectsControl<S>;
     /** Runtime control for resolvers (register/assign/unregister/call) */
     readonly resolvers: ResolversControl<S>;
+    /** O(1) metadata queries for constraints, resolvers, effects, derivations. */
+    readonly meta: MetaAccessor;
     /** Per-run trace entries (null if trace is not enabled) */
     readonly trace: TraceEntry[] | null;
     /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
@@ -1191,7 +1241,10 @@ type TypedDerivationFn<M extends ModuleSchema, K extends keyof GetDerivationsSch
  * Each derivation key must match schema.derivations and return the declared type.
  */
 type TypedDerivationsDef<M extends ModuleSchema> = {
-    [K in keyof GetDerivationsSchema<M>]: TypedDerivationFn<M, K>;
+    [K in keyof GetDerivationsSchema<M>]: TypedDerivationFn<M, K> | {
+        compute: TypedDerivationFn<M, K>;
+        meta?: DefinitionMeta;
+    };
 };
 /**
  * Event handler function with typed facts and payload.
@@ -1203,7 +1256,10 @@ type TypedEventHandlerFn<M extends ModuleSchema, K extends keyof GetEventsSchema
  * Each event key must match schema.events with the correct payload type.
  */
 type TypedEventsDef<M extends ModuleSchema> = {
-    [K in keyof GetEventsSchema<M>]: TypedEventHandlerFn<M, K>;
+    [K in keyof GetEventsSchema<M>]: TypedEventHandlerFn<M, K> | {
+        handler: TypedEventHandlerFn<M, K>;
+        meta?: DefinitionMeta;
+    };
 };
 /**
  * Requirement output from a constraint.
@@ -1237,6 +1293,8 @@ interface TypedConstraintDef<M extends ModuleSchema> {
      * Required for async constraints to enable dependency tracking.
      */
     deps?: string[];
+    /** Optional metadata for debugging and devtools (never read on hot path). */
+    meta?: DefinitionMeta;
 }
 /**
  * Typed constraints definition using the module schema.
@@ -1275,6 +1333,8 @@ interface CrossModuleConstraintDef<M extends ModuleSchema, Deps extends CrossMod
      * Required for async constraints to enable dependency tracking.
      */
     deps?: string[];
+    /** Optional metadata for debugging and devtools (never read on hot path). */
+    meta?: DefinitionMeta;
 }
 /**
  * Cross-module constraints definition.
@@ -1293,6 +1353,8 @@ interface CrossModuleEffectDef<M extends ModuleSchema, Deps extends CrossModuleD
     run: (facts: CrossModuleFactsWithSelf<M, Deps>, prev: CrossModuleFactsWithSelf<M, Deps> | undefined) => void | EffectCleanup | Promise<void | EffectCleanup>;
     /** Optional dependency keys to filter when effect runs */
     deps?: string[];
+    /** Optional metadata for debugging and devtools (never read on hot path). */
+    meta?: DefinitionMeta;
 }
 /**
  * Cross-module effects definition.
@@ -1311,7 +1373,10 @@ type CrossModuleDerivationFn<M extends ModuleSchema, Deps extends CrossModuleDep
  * Cross-module derivations definition.
  */
 type CrossModuleDerivationsDef<M extends ModuleSchema, Deps extends CrossModuleDeps> = {
-    [K in keyof GetDerivationsSchema<M>]: CrossModuleDerivationFn<M, Deps, K>;
+    [K in keyof GetDerivationsSchema<M>]: CrossModuleDerivationFn<M, Deps, K> | {
+        compute: CrossModuleDerivationFn<M, Deps, K>;
+        meta?: DefinitionMeta;
+    };
 };
 /**
  * Resolver context with typed facts.
@@ -1348,6 +1413,8 @@ interface TypedResolverDef<M extends ModuleSchema, T extends keyof GetRequiremen
     resolveBatch?: (reqs: ExtractRequirement<M, T>[], ctx: TypedResolverContext<M>) => Promise<void>;
     /** Resolve batched requirements with per-item success/failure results. Return a `BatchResolveResults` array in the same order as the input. Failed items can be individually retried. */
     resolveBatchWithResults?: (reqs: ExtractRequirement<M, T>[], ctx: TypedResolverContext<M>) => Promise<BatchResolveResults>;
+    /** Optional metadata for debugging and devtools (never read on hot path). */
+    meta?: DefinitionMeta;
 }
 /**
  * Union of all typed resolver definitions for all requirement types.
@@ -1375,6 +1442,8 @@ interface ModuleDef<M extends ModuleSchema = ModuleSchema> {
     constraints?: TypedConstraintsDef<M>;
     resolvers?: TypedResolversDef<M>;
     hooks?: ModuleHooks<M>;
+    /** Optional metadata for debugging and devtools (never read on hot path). */
+    meta?: DefinitionMeta;
     /**
      * History configuration for this module.
      * Controls which events create snapshots for undo/redo.
@@ -1500,6 +1569,7 @@ interface TraceEntry {
         key: string;
         oldValue: unknown;
         newValue: unknown;
+        meta?: DefinitionMeta;
     }>;
     /** Derivations recomputed during this run, with tracked dependencies and values */
     derivationsRecomputed: Array<{
@@ -1507,12 +1577,14 @@ interface TraceEntry {
         deps: string[];
         oldValue: unknown;
         newValue: unknown;
+        meta?: DefinitionMeta;
     }>;
     /** Constraints that evaluated to active, with tracked dependencies */
     constraintsHit: Array<{
         id: string;
         priority: number;
         deps: string[];
+        meta?: DefinitionMeta;
     }>;
     /** Requirements added from constraint diff */
     requirementsAdded: Array<{
@@ -1530,28 +1602,33 @@ interface TraceEntry {
     resolversStarted: Array<{
         resolver: string;
         requirementId: string;
+        meta?: DefinitionMeta;
     }>;
     /** Resolvers that completed (async — populated after reconcile) */
     resolversCompleted: Array<{
         resolver: string;
         requirementId: string;
         duration: number;
+        meta?: DefinitionMeta;
     }>;
     /** Resolvers that errored (async — populated after reconcile) */
     resolversErrored: Array<{
         resolver: string;
         requirementId: string;
         error: string;
+        meta?: DefinitionMeta;
     }>;
     /** Effects that ran, with their triggering fact keys */
     effectsRun: Array<{
         id: string;
         triggeredBy: string[];
+        meta?: DefinitionMeta;
     }>;
     /** Effect errors */
     effectErrors: Array<{
         id: string;
         error: string;
+        meta?: DefinitionMeta;
     }>;
     /** Human-readable causal chain summary (populated when run settles) */
     causalChain?: string;
@@ -1566,6 +1643,16 @@ interface SystemInspection {
         resolverId: string;
         startedAt: number;
     }>;
+    /** All fact/schema field keys with optional metadata */
+    facts: Array<{
+        key: string;
+        meta?: DefinitionMeta;
+    }>;
+    /** All event names with optional metadata */
+    events: Array<{
+        name: string;
+        meta?: DefinitionMeta;
+    }>;
     constraints: Array<{
         id: string;
         active: boolean;
@@ -1573,12 +1660,29 @@ interface SystemInspection {
         priority: number;
         hitCount: number;
         lastActiveAt: number | null;
+        meta?: DefinitionMeta;
     }>;
     resolvers: Record<string, ResolverStatus>;
     /** All defined resolver names and their requirement types */
     resolverDefs: Array<{
         id: string;
         requirement: string;
+        meta?: DefinitionMeta;
+    }>;
+    /** All defined effect names with optional metadata */
+    effects: Array<{
+        id: string;
+        meta?: DefinitionMeta;
+    }>;
+    /** All defined derivation names with optional metadata */
+    derivations: Array<{
+        id: string;
+        meta?: DefinitionMeta;
+    }>;
+    /** All registered modules with optional metadata */
+    modules: Array<{
+        id: string;
+        meta?: DefinitionMeta;
     }>;
     /** Whether trace is enabled on this system */
     traceEnabled: boolean;
@@ -1739,13 +1843,19 @@ interface DerivationsControl<M extends ModuleSchema = ModuleSchema> {
      * @throws If a derivation with this ID already exists (use `assign` to override)
      * @remarks During reconciliation, the registration is deferred and applied after the current cycle completes.
      */
-    register(id: string, fn: (facts: Readonly<InferSchema<M["facts"]>>, derived: Readonly<InferDerivations<M>>) => unknown): void;
+    register(id: string, fn: ((facts: Readonly<InferSchema<M["facts"]>>, derived: Readonly<InferDerivations<M>>) => unknown) | {
+        compute: (facts: Readonly<InferSchema<M["facts"]>>, derived: Readonly<InferDerivations<M>>) => unknown;
+        meta?: DefinitionMeta;
+    }): void;
     /**
      * Override an existing derivation (static or dynamic).
      * @throws If no derivation with this ID exists (use `register` to create)
      * @remarks During reconciliation, the assignment is deferred and applied after the current cycle completes.
      */
-    assign(id: string, fn: (facts: Readonly<InferSchema<M["facts"]>>, derived: Readonly<InferDerivations<M>>) => unknown): void;
+    assign(id: string, fn: ((facts: Readonly<InferSchema<M["facts"]>>, derived: Readonly<InferDerivations<M>>) => unknown) | {
+        compute: (facts: Readonly<InferSchema<M["facts"]>>, derived: Readonly<InferDerivations<M>>) => unknown;
+        meta?: DefinitionMeta;
+    }): void;
     /**
      * Remove a dynamically registered derivation.
      * Static (module-defined) derivations cannot be unregistered — logs a dev warning and no-ops.
@@ -1818,11 +1928,13 @@ interface DynamicConstraintDef<M extends ModuleSchema = ModuleSchema> {
     timeout?: number;
     after?: string[];
     deps?: string[];
+    meta?: DefinitionMeta;
 }
 /** Effect definition for dynamic registration — typed facts */
 interface DynamicEffectDef<M extends ModuleSchema = ModuleSchema> {
     run: (facts: Readonly<InferSchema<M["facts"]>>, prev: InferSchema<M["facts"]> | null) => void | (() => void) | Promise<void | (() => void)>;
     deps?: Array<string & keyof InferSchema<M["facts"]>>;
+    meta?: DefinitionMeta;
 }
 /** Resolver definition for dynamic registration — typed context.facts, relaxed requirement */
 interface DynamicResolverDef<M extends ModuleSchema = ModuleSchema> {
@@ -1850,6 +1962,34 @@ interface DynamicResolverDef<M extends ModuleSchema = ModuleSchema> {
         signal: AbortSignal;
         snapshot: () => InferSchema<M["facts"]>;
     }) => Promise<void>;
+    meta?: DefinitionMeta;
+}
+/** Result from bulk meta queries (byCategory, byTag). */
+interface MetaMatch {
+    type: "module" | "fact" | "event" | "constraint" | "resolver" | "effect" | "derivation";
+    id: string;
+    meta: DefinitionMeta;
+}
+/** O(1) accessor for definition metadata. */
+interface MetaAccessor {
+    /** Get metadata for a module by ID. */
+    module(id: string): DefinitionMeta | undefined;
+    /** Get metadata for a fact/schema field by key. */
+    fact(key: string): DefinitionMeta | undefined;
+    /** Get metadata for an event by name. */
+    event(name: string): DefinitionMeta | undefined;
+    /** Get metadata for a constraint by ID. */
+    constraint(id: string): DefinitionMeta | undefined;
+    /** Get metadata for a resolver by ID. */
+    resolver(id: string): DefinitionMeta | undefined;
+    /** Get metadata for an effect by ID. */
+    effect(id: string): DefinitionMeta | undefined;
+    /** Get metadata for a derivation by ID. */
+    derivation(id: string): DefinitionMeta | undefined;
+    /** Find all definitions matching a category across all types. */
+    byCategory(category: string): MetaMatch[];
+    /** Find all definitions matching a tag across all types. */
+    byTag(tag: string): MetaMatch[];
 }
 interface System<M extends ModuleSchema = ModuleSchema> {
     readonly facts: Facts<M["facts"]>;
@@ -1859,6 +1999,8 @@ interface System<M extends ModuleSchema = ModuleSchema> {
     readonly constraints: ConstraintsControl<M>;
     readonly effects: EffectsControl<M>;
     readonly resolvers: ResolversControl<M>;
+    /** O(1) metadata queries for constraints, resolvers, effects, derivations. */
+    readonly meta: MetaAccessor;
     /** Per-run trace entries (null if trace is not enabled) */
     readonly trace: TraceEntry[] | null;
     /** Initialize facts and derivations without starting reconciliation. Safe for SSR. */
@@ -2238,4 +2380,4 @@ interface Plugin<M extends ModuleSchema = ModuleSchema> {
     onTraceComplete?: (entry: TraceEntry) => void;
 }
 
-export { isNamespacedSystem as $, type AnySystem as A, type BatchConfig as B, type CrossModuleDeps as C, DirectiveError as D, type EffectsDef as E, type Facts as F, type InferRequirementTypes as G, type HistoryAPI as H, type InferDerivations as I, type InferRequirements as J, type InferSchemaType as K, type InferSelectorState as L, type ModuleSchema as M, type NamespacedSystem as N, type RetryPolicy as O, type Plugin as P, type Schema as Q, type RequirementWithId as R, type SchemaType as S, type TypedDerivationsDef as T, type Snapshot as U, type System as V, type SystemConfig as W, type SystemInspection as X, type SystemMode as Y, type SystemSnapshot as Z, type TraceEntry as _, type TypedEventsDef as a, isSingleModuleSystem as a0, type FactsStore as a1, type ConstraintsDef as a2, type ConstraintState as a3, type ResolversDef as a4, type ResolverStatus as a5, type FactChange as a6, type ReconcileResult as a7, type RecoveryStrategy as a8, type ErrorSource as a9, type InferRequirementPayloadFromSchema as aA, type InferSchema as aB, type MutableNamespacedFacts as aC, type NamespacedDerivations as aD, type NamespacedEventsAccessor as aE, type NamespacedFacts as aF, type ObservableKeys as aG, type RequirementExplanation as aH, type RequirementOutput as aI, type RequirementPayloadSchema$1 as aJ, type RequirementsSchema as aK, type ResolverContext as aL, type ResolversControl as aM, type SnapshotMeta as aN, type SystemEvent as aO, type TraceConfig as aP, type TypedConstraintDef as aQ, type TypedResolverContext as aR, type TypedResolverDef as aS, type UnionEvents as aT, type RequirementOutput$1 as aU, type RetryLaterConfig as aa, type BatchItemResult as ab, type BatchResolveResults as ac, type ConstraintsControl as ad, type CrossModuleConstraintDef as ae, type CrossModuleDerivationFn as af, type CrossModuleEffectDef as ag, type CrossModuleFactsWithSelf as ah, type DerivationKeys as ai, type DerivationReturnType as aj, type DerivationsControl as ak, type DerivationsSchema as al, type DeriveAccessor as am, type DispatchEventsFromSchema as an, type EffectCleanup as ao, type EffectsControl as ap, type EventPayloadSchema as aq, type EventsAccessor as ar, type EventsAccessorFromSchema as as, type EventsDef as at, type EventsSchema as au, type FactKeys as av, type FactReturnType as aw, type FlexibleEventHandler as ax, type HistoryConfig as ay, type InferEventPayloadFromSchema as az, type TypedConstraintsDef as b, type TypedResolversDef as c, type ModuleHooks as d, type CrossModuleDerivationsDef as e, type CrossModuleEffectsDef as f, type CrossModuleConstraintsDef as g, type ModuleDef as h, type CreateSystemOptionsSingle as i, type SingleModuleSystem as j, type ModulesMap as k, type CreateSystemOptionsNamed as l, type TraceOption as m, type ErrorBoundaryConfig as n, type Requirement as o, type RequirementKeyFn as p, type DistributableSnapshot as q, type DistributableSnapshotOptions as r, type DynamicConstraintDef as s, type DynamicEffectDef as t, type DynamicResolverDef as u, type FactsSnapshot as v, type HistoryOption as w, type HistoryState as x, type InferEvents as y, type InferFacts as z };
+export { type SystemMode as $, type AnySystem as A, type BatchConfig as B, type CrossModuleDeps as C, type DefinitionMeta as D, type EffectsDef as E, type Facts as F, type InferFacts as G, type HistoryAPI as H, type InferDerivations as I, type InferRequirementTypes as J, type InferRequirements as K, type InferSchemaType as L, type ModuleSchema as M, type NamespacedSystem as N, type InferSelectorState as O, type Plugin as P, type MetaAccessor as Q, type RequirementWithId as R, type SchemaType as S, type TypedDerivationsDef as T, type MetaMatch as U, type RetryPolicy as V, type Schema as W, type Snapshot as X, type System as Y, type SystemConfig as Z, type SystemInspection as _, type TypedEventsDef as a, type SystemSnapshot as a0, type TraceEntry as a1, isNamespacedSystem as a2, isSingleModuleSystem as a3, type FactsStore as a4, type ConstraintsDef as a5, type ConstraintState as a6, type ResolversDef as a7, type ResolverStatus as a8, type FactChange as a9, type FlexibleEventHandler as aA, type HistoryConfig as aB, type InferEventPayloadFromSchema as aC, type InferRequirementPayloadFromSchema as aD, type InferSchema as aE, type MutableNamespacedFacts as aF, type NamespacedDerivations as aG, type NamespacedEventsAccessor as aH, type NamespacedFacts as aI, type ObservableKeys as aJ, type RequirementExplanation as aK, type RequirementOutput as aL, type RequirementPayloadSchema$1 as aM, type RequirementsSchema as aN, type ResolverContext as aO, type ResolversControl as aP, type SnapshotMeta as aQ, type SystemEvent as aR, type TraceConfig as aS, type TypedConstraintDef as aT, type TypedResolverContext as aU, type TypedResolverDef as aV, type UnionEvents as aW, type RequirementOutput$1 as aX, type ReconcileResult as aa, type RecoveryStrategy as ab, type ErrorSource as ac, type RetryLaterConfig as ad, type BatchItemResult as ae, type BatchResolveResults as af, type ConstraintsControl as ag, type CrossModuleConstraintDef as ah, type CrossModuleDerivationFn as ai, type CrossModuleEffectDef as aj, type CrossModuleFactsWithSelf as ak, type DerivationKeys as al, type DerivationReturnType as am, type DerivationsControl as an, type DerivationsSchema as ao, type DeriveAccessor as ap, type DispatchEventsFromSchema as aq, type EffectCleanup as ar, type EffectsControl as as, type EventPayloadSchema as at, type EventsAccessor as au, type EventsAccessorFromSchema as av, type EventsDef as aw, type EventsSchema as ax, type FactKeys as ay, type FactReturnType as az, type TypedConstraintsDef as b, type TypedResolversDef as c, type ModuleHooks as d, type CrossModuleDerivationsDef as e, type CrossModuleEffectsDef as f, type CrossModuleConstraintsDef as g, type ModuleDef as h, type CreateSystemOptionsSingle as i, type SingleModuleSystem as j, type ModulesMap as k, type CreateSystemOptionsNamed as l, type TraceOption as m, type ErrorBoundaryConfig as n, type Requirement as o, type RequirementKeyFn as p, DirectiveError as q, type DistributableSnapshot as r, type DistributableSnapshotOptions as s, type DynamicConstraintDef as t, type DynamicEffectDef as u, type DynamicResolverDef as v, type FactsSnapshot as w, type HistoryOption as x, type HistoryState as y, type InferEvents as z };