@directive-run/core 1.21.0 → 1.23.0

package/dist/plugins/index.d.ts

@@ -1,5 +1,5 @@
-export { A as AuditEntry, a as AuditEntryKind, b as AuditLedger, c as AuditLedgerOptions, d as AuditLedgerSink, Q as QueryFilter, e as createAuditLedger, m as memorySink } from '../index-DUbpbGw8.js';
-import { M as ModuleSchema, P as Plugin, ap as System } from '../plugins-4IfhJV32.js';
+export { A as AuditEntry, a as AuditEntryKind, b as AuditLedger, c as AuditLedgerOptions, d as AuditLedgerSink, Q as QueryFilter, e as createAuditLedger, m as memorySink } from '../index-n8oQmdOZ.js';
+import { M as ModuleSchema, P as Plugin, aA as System, ak as PredicateOverlapProof } from '../plugins-CaPMTICa.js';
 
 /**
  * Logging Plugin - Console logging for Directive events
@@ -845,4 +845,359 @@ declare class CircuitBreakerOpenError extends Error {
  */
 declare function createCircuitBreaker(config?: CircuitBreakerConfig): CircuitBreaker;
 
-export { type AggregatedMetric, type AlertConfig, type AlertEvent, type CircuitBreaker, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitBreakerStats, type CircuitState, type ConstraintMetrics, DEVTOOLS_EVENT_NAME, type DashboardData, type DevtoolsPluginOptions, type EffectMetrics, type HistogramBucket, type LoggingPluginOptions, type MetricDataPoint, type MetricType, type OTLPExporter, type OTLPExporterConfig, type ObservabilityConfig, type ObservabilityInstance, type PerformancePluginOptions, type PerformanceSnapshot, type PersistencePluginOptions, type ReconcileMetrics, type ResolverMetrics, type TraceEvent, type TraceSpan, createAgentMetrics, createCircuitBreaker, createOTLPExporter, createObservability, devtoolsPlugin, emitDevToolsEvent, loggingPlugin, performancePlugin, persistencePlugin };
+/**
+ * Clobber Alert Plugin – default high-severity alerting for
+ * `resolver.write.rejected { reason: "clobbered" }` events landing on
+ * facts tagged irreversible.
+ *
+ * The audit ledger already records every clobber event with full
+ * forensic detail (fact, expected, actual, resolver, requirementId).
+ * But a clobber on a fact tagged `"money"` / `"pii"` / `"irreversible"`
+ * is operationally far more urgent than a clobber on a UI status fact.
+ * Without this plugin, a consumer has to write their own SIEM rule to
+ * separate "noise" from "page an engineer NOW."
+ *
+ * Default behaviour: fire `console.error` on every clobber whose fact's
+ * schema meta carries any tag in `irreversibleTags`. Replace the
+ * `onAlert` callback to route to PagerDuty / Slack / Sentry / your SIEM
+ * of choice.
+ *
+ * @public
+ */
+
+/** Configuration for the {@link clobberAlertPlugin}. */
+interface ClobberAlertPluginOptions {
+    /**
+     * Fact-meta tags that promote a clobber event from "noise" to
+     * "high-severity alert." A clobber whose fact's schema meta carries
+     * ANY of these tags fires `onAlert`.
+     *
+     * **Why tag the fact, not the resolver?** A clobber is detected at
+     * fact-write time. The audit event payload (`fact`, `expected`,
+     * `actual`) names the fact, not the side effect — the fact is the
+     * trigger surface for any irreversible work the resolver is about
+     * to do (a charge, a send, a delete). Tagging `payment.amount` with
+     * `"money"` marks the fact whose race-loss should page someone.
+     *
+     * If your model puts the irreversibility on the resolver rather than
+     * the fact, use `irreversibleResolvers` — both filters OR.
+     *
+     * Default: `["money", "pii", "irreversible"]`.
+     */
+    irreversibleTags?: readonly string[];
+    /**
+     * Resolver IDs whose clobbered writes should always alert, regardless
+     * of fact tags. Use this when irreversibility is modeled on the
+     * resolver (e.g. `stripeCharge`) rather than on the trigger fact.
+     * Defaults to empty — the fact-tag path covers most cases.
+     */
+    irreversibleResolvers?: readonly string[];
+    /**
+     * Callback fired when a clobber lands on a fact whose tags overlap
+     * `irreversibleTags`, or whose resolver is in `irreversibleResolvers`.
+     * Default: `console.error(...)`.
+     */
+    onAlert?: (event: ClobberAlertEvent) => void;
+    /**
+     * Callback fired when the engine's per-resolver rate limit aggregates
+     * multiple per-write clobber events into a single
+     * `kind: "summary"` event (default cap: 10 per-resolver-instance).
+     * The summary names the resolver + dropped count but loses per-fact
+     * attribution — the engine has no way to enumerate every dropped
+     * write inside the cap.
+     *
+     * Only fires when EITHER:
+     * - the resolver is listed in `irreversibleResolvers`, OR
+     * - this plugin has previously fired `onAlert` for the resolver
+     *   (i.e. the resolver has touched an irreversible fact in this
+     *   session, so a follow-on burst is operationally relevant)
+     *
+     * Default: undefined (no summary alerts). Set this to preserve
+     * SIEM telemetry past the engine's rate-limit cap on a hot
+     * resolver fighting an irreversible fact.
+     */
+    onSummary?: (event: ClobberSummaryEvent) => void;
+    /**
+     * Cooldown window keyed by `(fact, resolver)` pair. A second clobber
+     * from the same resolver on the same fact within this window does not
+     * re-fire `onAlert`. A clobber from a *different* resolver on the
+     * same fact still fires — fighting writers are a different
+     * operational incident than a single resolver retrying.
+     *
+     * The audit ledger records every clobber regardless of cooldown.
+     *
+     * Default: `0` (no cooldown — every event alerts).
+     */
+    cooldownMs?: number;
+}
+/** Payload passed to {@link ClobberAlertPluginOptions.onAlert}. */
+interface ClobberAlertEvent {
+    readonly fact: string;
+    /**
+     * Fact-meta tags that matched `irreversibleTags`. Empty when the alert
+     * fired only because the resolver matched `irreversibleResolvers`.
+     * Use {@link matchedBy} to distinguish without checking length.
+     */
+    readonly tags: readonly string[];
+    /**
+     * Which filter triggered the alert:
+     * - `"tag"` — fact-meta tags overlapped `irreversibleTags`
+     * - `"resolver"` — resolver ID matched `irreversibleResolvers`
+     * - `"both"` — both filters matched
+     */
+    readonly matchedBy: "tag" | "resolver" | "both";
+    readonly resolver: string;
+    readonly requirementId: string;
+    readonly expected: unknown;
+    readonly actual: unknown;
+    /** `Date.now()` at the moment the alert fired. */
+    readonly timestamp: number;
+}
+/**
+ * Payload passed to {@link ClobberAlertPluginOptions.onSummary}.
+ *
+ * Fired when the engine's per-resolver clobber rate-limit aggregates
+ * multiple per-write events into one summary. Per-fact attribution is
+ * lost (the engine cannot enumerate every dropped write inside the
+ * cap), but the resolver + dropped count are preserved so SIEM can
+ * page on "this resolver is still fighting an irreversible fact
+ * past the cap."
+ */
+interface ClobberSummaryEvent {
+    readonly resolver: string;
+    readonly requirementId: string;
+    /** Number of per-write clobber events the engine suppressed under the cap. */
+    readonly dropped: number;
+    /**
+     * Why the summary surfaced from this plugin's filter:
+     * - `"resolver-listed"` — the resolver was in `irreversibleResolvers`
+     * - `"prior-irreversible-alert"` — the resolver had already fired
+     *   `onAlert` on an irreversible fact in this session
+     */
+    readonly matchedBy: "resolver-listed" | "prior-irreversible-alert";
+    /** `Date.now()` at the moment the summary fired. */
+    readonly timestamp: number;
+}
+/**
+ * Create a plugin that fires high-severity alerts for clobber events
+ * landing on irreversible-tagged facts.
+ *
+ * @example
+ * ```ts
+ * createSystem({
+ *   module: myModule,
+ *   plugins: [
+ *     clobberAlertPlugin({
+ *       irreversibleTags: ["money", "pii"],
+ *       onAlert: (e) => pagerduty.trigger({
+ *         severity: "critical",
+ *         summary: `Clobber on ${e.fact} (${e.tags.join(", ")})`,
+ *         details: e,
+ *       }),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function clobberAlertPlugin<M extends ModuleSchema>(options?: ClobberAlertPluginOptions): Plugin<M>;
+
+/**
+ * Clobber Loop Detector Plugin – fires a structured warning when the
+ * same set of resolvers clobber the same fact above threshold within a
+ * time window. A single clobber is fine — the `abortOn:` binding caught
+ * the race and the audit ledger recorded it. A *loop* is two or more
+ * resolvers whose `when:` predicates both satisfy a shared state and
+ * keep rewriting the fact every reconcile tick, indefinitely.
+ *
+ * Today the symptom surfaces as a value flapping between two states in
+ * a customer screenshot. The audit ledger holds the forensic evidence
+ * (800 clobbers/sec on `cart.discount`), but nobody looks until a
+ * customer complains. This plugin closes the loop: one structured
+ * warning per detected loop, with a **predicate-overlap proof** built
+ * from the participants' `whenSpec` so the warning points at the
+ * specific clauses that co-fire instead of stopping at "these resolvers
+ * fight."
+ *
+ * @public
+ */
+
+/** Configuration for the {@link clobberLoopPlugin}. */
+interface ClobberLoopPluginOptions {
+    /**
+     * Window over which clobber-rejection events are aggregated. A loop
+     * fires when `threshold` distinct-requirement rejections involving
+     * ≥2 distinct resolvers land on the same fact within `windowMs`.
+     *
+     * Default: 1000ms. Catches the canonical "5 clobbers in <500ms" case
+     * while sitting well outside tick-boundary noise.
+     */
+    windowMs?: number;
+    /**
+     * Minimum distinct-requirement rejection count within `windowMs` to
+     * trigger a loop event. Distinct by `requirement.id`, so a single
+     * resolver's retry storm (which shares one requirement id) counts as
+     * one rejection and never crosses the threshold alone — only true
+     * multi-participant contention does.
+     *
+     * Default: 5.
+     */
+    threshold?: number;
+    /**
+     * After a loop fires on a `(fact, participantSet)`, suppress same-key
+     * re-fire for this duration. Mirrors `clobberAlertPlugin`'s
+     * cooldown precedent.
+     *
+     * Default: 5000ms.
+     */
+    cooldownMs?: number;
+    /**
+     * Quiet window after the last contributing clobber rejection before
+     * the loop is considered closed and a `resolver.clobber.loop.resolved`
+     * event fires. The resolver may have shipped a fix (priority added,
+     * `when:` narrowed), or the surrounding state changed enough that
+     * both participants no longer co-fire.
+     *
+     * Default: 30000ms.
+     */
+    resolvedAfterMs?: number;
+    /**
+     * Global LRU cap on the number of facts the detector tracks. A
+     * hot-then-cold attacker fact key can churn the map, but LRU
+     * eviction ensures the legitimate hot fact stays resident. Memory
+     * bound: ~32 ring-buffer entries × `maxTrackedFacts` slim records.
+     *
+     * Default: 256.
+     */
+    maxTrackedFacts?: number;
+    /**
+     * Per-fact cap on participant resolver tracking. Above this, a single
+     * "N-way contention on fact X" event fires once and detailed
+     * participant tracking pauses for the cooldown window.
+     *
+     * Default: 16.
+     */
+    maxParticipantsPerFact?: number;
+    /**
+     * Global emission cap (loop-events per second across all facts). A
+     * storm where every fact enters a loop simultaneously should not blow
+     * up the observation bus or pager. Above-cap detections increment a
+     * counter and surface in the next emitted event's
+     * `suppressedSinceLastEmit` field.
+     *
+     * Default: 10.
+     */
+    maxEmissionsPerSec?: number;
+    /**
+     * Callback fired when a loop is detected. The payload is the
+     * fully-constructed event including PII-redacted `predicateOverlap`
+     * (when applicable).
+     *
+     * Default in dev mode: `console.warn` with the structured warning
+     * text. Default in production: `console.error` to stderr — NOT noop,
+     * so the signal still lands in CloudWatch/Loki/Datadog log pipelines
+     * even when consumers haven't explicitly wired routing.
+     */
+    onLoop?: (event: ClobberLoopDetectedEvent) => void;
+    /**
+     * Callback fired when a previously-detected loop is considered
+     * resolved (quiet window elapsed, participant unregistered, or
+     * predicate narrowed).
+     *
+     * Default: no-op. Wire when monitoring needs "5 active loops" rather
+     * than "47 historical loops."
+     */
+    onResolved?: (event: ClobberLoopResolvedEvent) => void;
+    /**
+     * Opt-out of PII redaction in the emitted event's `predicateOverlap`
+     * clauses. The default (`false`) routes `whenSpec` operand pointers
+     * through `redactWhenSpec` against `system.meta.byTag("pii")` BEFORE
+     * the event is constructed, so downstream sinks see `[redacted]` in
+     * place of the literal operand.
+     *
+     * Set to `true` only when the deployment has a data-processing
+     * addendum that permits unredacted operand capture.
+     *
+     * Default: `false`.
+     */
+    capturePII?: boolean;
+}
+/**
+ * Emitted payload for {@link ClobberLoopPluginOptions.onLoop}. Identical
+ * shape to the `"resolver.clobber.loop.detected"` ObservationEvent so
+ * consumers can route the same code path through either surface.
+ *
+ * @public
+ */
+interface ClobberLoopDetectedEvent {
+    readonly systemId: string;
+    readonly fact: string;
+    readonly participants: readonly string[];
+    readonly participantModules: readonly string[];
+    readonly count: number;
+    readonly windowMs: number;
+    readonly firstAt: number;
+    readonly lastAt: number;
+    readonly predicateOverlap?: PredicateOverlapProof;
+    readonly severity: "warn" | "error";
+    readonly factTags: readonly string[];
+    readonly suppressedSinceLastEmit: number;
+    readonly rejectionSeqs: readonly number[];
+}
+/**
+ * Emitted payload for {@link ClobberLoopPluginOptions.onResolved}.
+ *
+ * @public
+ */
+interface ClobberLoopResolvedEvent {
+    readonly systemId: string;
+    readonly fact: string;
+    readonly participants: readonly string[];
+    readonly durationMs: number;
+    readonly resolution: "no-recurrence-in-window" | "participant-disabled" | "predicate-narrowed";
+}
+/**
+ * Runtime kill-switch handle returned alongside the plugin. Lets an SRE
+ * flip the detector off during incident response without redeploying.
+ * `disable()` stops emission but preserves buffer state so `enable()`
+ * resumes cleanly without warm-up drift.
+ *
+ * @public
+ */
+interface ClobberLoopPluginHandle<M extends ModuleSchema> {
+    readonly plugin: Plugin<M>;
+    disable(): void;
+    enable(): void;
+    isEnabled(): boolean;
+}
+/**
+ * Create a clobber-loop detector plugin. Returns a {@link
+ * ClobberLoopPluginHandle} so callers can flip the detector off at
+ * runtime without redeploying. The `.plugin` field is the value to
+ * pass into `createSystem({ plugins: [...] })`.
+ *
+ * @example
+ * ```ts
+ * const loopDetector = clobberLoopPlugin({
+ *   threshold: 5,
+ *   windowMs: 1000,
+ *   onLoop: (e) => pagerduty.trigger({
+ *     severity: e.severity,
+ *     summary: `Clobber loop on ${e.fact}: ${e.participants.join(" vs ")}`,
+ *     details: e,
+ *   }),
+ * });
+ *
+ * createSystem({
+ *   module: myModule,
+ *   plugins: [loopDetector.plugin],
+ * });
+ *
+ * // During incident response:
+ * loopDetector.disable();
+ * ```
+ *
+ * @public
+ */
+declare function clobberLoopPlugin<M extends ModuleSchema>(options?: ClobberLoopPluginOptions): ClobberLoopPluginHandle<M>;
+
+export { type AggregatedMetric, type AlertConfig, type AlertEvent, type CircuitBreaker, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitBreakerStats, type CircuitState, type ClobberAlertEvent, type ClobberAlertPluginOptions, type ClobberLoopDetectedEvent, type ClobberLoopPluginHandle, type ClobberLoopPluginOptions, type ClobberLoopResolvedEvent, type ConstraintMetrics, DEVTOOLS_EVENT_NAME, type DashboardData, type DevtoolsPluginOptions, type EffectMetrics, type HistogramBucket, type LoggingPluginOptions, type MetricDataPoint, type MetricType, type OTLPExporter, type OTLPExporterConfig, type ObservabilityConfig, type ObservabilityInstance, type PerformancePluginOptions, type PerformanceSnapshot, type PersistencePluginOptions, type ReconcileMetrics, type ResolverMetrics, type TraceEvent, type TraceSpan, clobberAlertPlugin, clobberLoopPlugin, createAgentMetrics, createCircuitBreaker, createOTLPExporter, createObservability, devtoolsPlugin, emitDevToolsEvent, loggingPlugin, performancePlugin, persistencePlugin };