@voyantjs/workflows 0.28.3 → 0.29.0

package/dist/driver.d.ts

@@ -0,0 +1,237 @@
+import type { WorkflowManifest } from "./protocol/index.js";
+import type { ListRunsOptions, Run, RunDetail, RunSummary, TriggerOptions } from "./trigger.js";
+import type { EnvironmentName, WaitpointKind } from "./types.js";
+import type { WorkflowDefinition } from "./workflow.js";
+/**
+ * Read-only view of a service container. Step bodies resolve services via
+ * `ctx.services.resolve(...)`. The framework's `ModuleContainer`
+ * (in `@voyantjs/core`) satisfies this shape structurally; we don't import
+ * it directly to keep `@voyantjs/workflows` a leaf package.
+ */
+export interface ServiceResolver {
+    resolve<T>(name: string): T;
+    has(name: string): boolean;
+}
+/**
+ * Structural shape of an event envelope as ingested by a driver. Matches
+ * `EventEnvelope` from `@voyantjs/core` (`name`, `data`, `metadata?`, `emittedAt`),
+ * declared structurally so the SDK package doesn't import core.
+ */
+export interface IngestEventEnvelope<TData = unknown> {
+    /** Event name in `<resource>.<pastTenseAction>` form. */
+    name: string;
+    /** Business payload. */
+    data: TData;
+    /** Optional metadata. `metadata.eventId` is the canonical idempotency seed
+     *  (a fresh ULID, stamped by the framework's EventBus forwarder). External
+     *  callers may supply their own. See architecture doc §15.2. */
+    metadata?: Record<string, unknown> & {
+        eventId?: string;
+    };
+    /** ISO timestamp string. */
+    emittedAt: string;
+}
+/**
+ * Minimal logger contract drivers can rely on. Matches the framework logger's
+ * call signature without taking a hard dependency on it.
+ */
+export type DriverLogger = (level: "debug" | "info" | "warn" | "error", msg: string, data?: object) => void;
+/**
+ * Deps the framework injects into a `DriverFactory` at boot. Driver factories
+ * close over their environment-specific options (DO bindings, DB pool, etc.)
+ * and read framework deps from this argument.
+ */
+export interface DriverFactoryDeps {
+    /** Read-only view of the framework's `ModuleContainer`. */
+    services: ServiceResolver;
+    /** Framework logger. */
+    logger: DriverLogger;
+    /** Injectable clock — defaults to `() => Date.now()`. */
+    now?: () => number;
+}
+/**
+ * Concrete driver factories return this. `createApp()` calls it once, after
+ * the container is built, to obtain the `WorkflowDriver`.
+ */
+export type DriverFactory = (deps: DriverFactoryDeps) => WorkflowDriver;
+/**
+ * Argument to `driver.ingestEvent(...)`. The framework's EventBus forwarder
+ * builds this from the core `EventEnvelope`; external HTTP callers (the
+ * optional ingest adapter, voyant-cloud) build it from a wire payload.
+ */
+export interface IngestEventArgs {
+    environment: EnvironmentName;
+    envelope: IngestEventEnvelope;
+    /** Optional caller-supplied idempotency override. When absent, the driver
+     *  derives a key per match from `metadata.eventId` (or a content hash
+     *  fallback). See architecture doc §15.2. */
+    idempotencyKey?: string;
+}
+/** Per-filter outcome from a single `ingestEvent` call. */
+export type IngestMatch = {
+    filterId: string;
+    targetWorkflowId: string;
+    runId: string;
+    idempotencyKey: string;
+    status: "queued";
+} | {
+    filterId: string;
+    status: "skipped";
+    reason: "where_eval_error" | "input_projection_error" | "input_schema_violation";
+    details?: string;
+} | {
+    filterId: string;
+    targetWorkflowId: string;
+    status: "error";
+    reason: string;
+};
+export type IngestEventResponse = {
+    ok: true;
+    eventId: string;
+    matches: IngestMatch[];
+} | {
+    ok: false;
+    reason: "manifest_not_registered" | "environment_mismatch" | "payload_too_large" | "trigger_failed_for_all_matches";
+    message?: string;
+};
+/**
+ * The mandatory driver contract. Every concrete driver — InMemory, Mode 2
+ * (Postgres), Mode 1 (CF edge) — implements all five methods. The compliance
+ * test suite (`driver-compliance.test.ts`) is the contract.
+ */
+export interface WorkflowDriver {
+    /**
+     * Idempotent. Same manifest body returns the same `versionId` across calls.
+     * Failures are NOT swallowed — `createApp()`'s bootstrap surfaces rejections
+     * (see architecture doc §21.22).
+     */
+    registerManifest(args: {
+        environment: EnvironmentName;
+        manifest: WorkflowManifest;
+    }): Promise<{
+        versionId: string;
+    }>;
+    /**
+     * Trigger a workflow run by id or definition handle. Honors
+     * `opts.idempotencyKey` for dedup (returns the existing run on conflict).
+     */
+    trigger<TIn, TOut>(workflow: WorkflowDefinition<TIn, TOut> | string, input: TIn, opts?: TriggerOptions): Promise<Run<TOut>>;
+    /**
+     * Ingest one event. Synchronously (from the caller's POV) loads the
+     * registered manifest, evaluates `where`, projects `input`, and triggers
+     * one run per match. See architecture doc §15.
+     */
+    ingestEvent(args: IngestEventArgs): Promise<IngestEventResponse>;
+    /**
+     * Read the registered manifest. Used at boot for version-mismatch detection
+     * and by the dashboard for filter inspection.
+     */
+    getManifest(args: {
+        environment: EnvironmentName;
+    }): Promise<WorkflowManifest | null>;
+    /**
+     * Optional. Drains in-flight steps, refuses new triggers, awaits time-wheel
+     * exit. Default `gracefulMs` is 30_000.
+     */
+    shutdown?(opts?: {
+        gracefulMs?: number;
+    }): Promise<void>;
+    /**
+     * Optional read-side surface. Drivers that can support listings, run detail,
+     * and journal streams declare this; consumers (the dashboard) duck-type on
+     * `driver.admin`. See architecture doc §6.2.
+     */
+    admin?: WorkflowAdmin | Partial<WorkflowAdmin>;
+}
+/**
+ * Read-side operations. Implemented natively by the Mode 2 driver against
+ * Postgres, partially by Mode 1 (single-run reads only — `listRuns` is not
+ * implemented in self-host Mode 1; voyant-cloud provides an index layer).
+ * See architecture doc §6.2 + §8.3.
+ */
+export interface WorkflowAdmin {
+    listRuns(opts?: ListRunsOptions): Promise<{
+        runs: RunSummary[];
+        nextCursor?: string;
+    }>;
+    getRun(runId: string): Promise<RunDetail | null>;
+    cancelRun(runId: string, opts?: {
+        reason?: string;
+        compensate?: boolean;
+    }): Promise<void>;
+    /**
+     * Subscribe to journal events for a run. The async-iterable shape lets
+     * dashboards stream live without polling.
+     */
+    streamRun(runId: string): AsyncIterable<AdminStreamEvent>;
+}
+/**
+ * The admin streaming surface re-uses the protocol's `StreamEvent` for
+ * step/waitpoint/log events; this type is its alias to keep the import
+ * surface narrow.
+ */
+export type AdminStreamEvent = {
+    kind: "run.snapshot";
+    at: number;
+    status: string;
+    metadata: Record<string, unknown>;
+} | {
+    kind: "step.started";
+    at: number;
+    stepId: string;
+    runtime: "edge" | "node";
+} | {
+    kind: "step.ok";
+    at: number;
+    stepId: string;
+    durationMs: number;
+} | {
+    kind: "step.err";
+    at: number;
+    stepId: string;
+    error: {
+        code: string;
+        message: string;
+    };
+} | {
+    kind: "waitpoint.registered";
+    at: number;
+    waitpointId: string;
+    waitpointKind: WaitpointKind;
+} | {
+    kind: "waitpoint.resolved";
+    at: number;
+    waitpointId: string;
+} | {
+    kind: "log";
+    at: number;
+    level: "info" | "warn" | "error";
+    message: string;
+} | {
+    kind: "run.finished";
+    at: number;
+    status: string;
+};
+/**
+ * Base class for typed driver errors. Concrete subclasses below; consumers
+ * `instanceof` to handle specific cases.
+ */
+export declare class WorkflowDriverError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class ManifestNotRegisteredError extends WorkflowDriverError {
+    constructor(environment: EnvironmentName);
+}
+export declare class EventTooLargeError extends WorkflowDriverError {
+    readonly bytes: number;
+    readonly limit: number;
+    constructor(bytes: number, limit?: number);
+}
+export declare class EnvironmentMismatchError extends WorkflowDriverError {
+    constructor(eventEnv: EnvironmentName, manifestEnv: EnvironmentName);
+}
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}

package/dist/driver.js

@@ -0,0 +1,53 @@
+// The WorkflowDriver contract.
+//
+// A driver is the runtime-side object that backs `createApp({ workflows })`:
+// it owns manifest registration, run triggering, event ingest, and (optionally)
+// admin reads. Concrete drivers live in downstream packages
+// (`@voyantjs/workflows-orchestrator` for InMemory, `-node` for Mode 2 / Postgres,
+// `-cloudflare` for Mode 1 / DO+KV).
+//
+// Drivers are constructed via *factories* — `DriverFactory` is a function the
+// framework invokes after `createApp()` has assembled its `ModuleContainer`.
+// This lets concrete factories accept their environment-specific options
+// (DO namespaces, DB pool, etc.) at user-call time and receive framework
+// deps (services, logger, …) at boot time, without a setter API.
+//
+// Authoritative architecture: docs/architecture/workflows-runtime-architecture.md §6.
+// ---- Errors ----
+/**
+ * Base class for typed driver errors. Concrete subclasses below; consumers
+ * `instanceof` to handle specific cases.
+ */
+export class WorkflowDriverError extends Error {
+    code;
+    cause;
+    constructor(code, message, opts) {
+        super(message);
+        this.name = "WorkflowDriverError";
+        this.code = code;
+        this.cause = opts?.cause;
+    }
+}
+export class ManifestNotRegisteredError extends WorkflowDriverError {
+    constructor(environment) {
+        super("manifest_not_registered", `No manifest is registered for environment "${environment}". ` +
+            `createApp() must complete its bootstrap before driver.ingestEvent(...) can fire.`);
+        this.name = "ManifestNotRegisteredError";
+    }
+}
+export class EventTooLargeError extends WorkflowDriverError {
+    bytes;
+    limit;
+    constructor(bytes, limit = 256 * 1024) {
+        super("payload_too_large", `Event payload is ${bytes} bytes, exceeding the ${limit}-byte cap.`);
+        this.name = "EventTooLargeError";
+        this.bytes = bytes;
+        this.limit = limit;
+    }
+}
+export class EnvironmentMismatchError extends WorkflowDriverError {
+    constructor(eventEnv, manifestEnv) {
+        super("environment_mismatch", `Event environment "${eventEnv}" does not match the registered manifest's environment "${manifestEnv}".`);
+        this.name = "EnvironmentMismatchError";
+    }
+}

package/dist/events/compile.d.ts

@@ -0,0 +1,34 @@
+import type { EventFilterDeclaration } from "../trigger.js";
+import { type EventFilterRuntimeEntry } from "./registry.js";
+export declare class EventFilterCompileError extends Error {
+    readonly errors: string[];
+    constructor(message: string, errors?: string[]);
+}
+/**
+ * Compile an authored declaration into a runtime entry. Throws
+ * `EventFilterCompileError` on shape errors so authoring problems fail
+ * at module-load time.
+ */
+export declare function compileEventFilter<T>(eventType: string, declaration: EventFilterDeclaration<T>): Promise<EventFilterRuntimeEntry>;
+/**
+ * Compile + register in one step. The synchronous wrapper for `trigger.on()`
+ * that user code calls — validates the declaration, computes the
+ * content-derived id, registers the entry, and returns it.
+ *
+ * Returning the full {@link EventFilterRuntimeEntry} is what makes the
+ * authoring shape from the architecture doc work directly — modules can
+ * write `eventFilters: [trigger.on(...)]` without a registry round-trip:
+ * the entry already structurally satisfies `EventFilterDescriptor`
+ * (matching `id` + `eventType` fields) and carries the `manifest` payload
+ * `createApp()`'s wireWorkflowRuntime needs to register with the driver.
+ */
+export declare function compileAndRegister<T>(eventType: string, declaration: EventFilterDeclaration<T>): EventFilterRuntimeEntry;
+/**
+ * Synchronous compile — uses a deterministic but non-cryptographic hash
+ * over the canonical JSON. Suitable for the registry id (we just need
+ * stable + collision-resistant-enough across realistic registration
+ * counts). The crypto-grade `sha256(...)` is used at *manifest build*
+ * time when async is fine.
+ */
+export declare function compileEventFilterSync<T>(eventType: string, declaration: EventFilterDeclaration<T>): EventFilterRuntimeEntry;
+//# sourceMappingURL=compile.d.ts.map

package/dist/events/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/events/compile.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAI3D,OAAO,EAAE,KAAK,uBAAuB,EAA0B,MAAM,eAAe,CAAA;AAEpF,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;gBAEb,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,EAAO;CAKnD;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,uBAAuB,CAAC,CAyFlC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACrC,uBAAuB,CAOzB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACrC,uBAAuB,CAqFzB"}

package/dist/events/compile.js

@@ -0,0 +1,204 @@
+// Compile an `EventFilterDeclaration` (authored in user code) into an
+// `EventFilterRuntimeEntry`. Validates the predicate + mapper at
+// registration time so authoring errors fail fast; computes the
+// content-derived `id` / `payloadHash` so the manifest is deterministic.
+//
+// Called from `trigger.on(...)` in `../trigger.js`.
+import { validateInputMapper } from "./input-mapper.js";
+import { canonicalJson, sha256 } from "./payload-hash.js";
+import { validatePredicate } from "./predicate.js";
+import { getEventFilterRegistry } from "./registry.js";
+export class EventFilterCompileError extends Error {
+    errors;
+    constructor(message, errors = []) {
+        super(message);
+        this.name = "EventFilterCompileError";
+        this.errors = errors;
+    }
+}
+/**
+ * Compile an authored declaration into a runtime entry. Throws
+ * `EventFilterCompileError` on shape errors so authoring problems fail
+ * at module-load time.
+ */
+export async function compileEventFilter(eventType, declaration) {
+    if (typeof eventType !== "string" || eventType.length === 0) {
+        throw new EventFilterCompileError(`trigger.on(eventType, ...): eventType must be a non-empty string`);
+    }
+    if (typeof declaration !== "object" || declaration === null) {
+        throw new EventFilterCompileError(`trigger.on("${eventType}", ...): declaration must be an object`);
+    }
+    if (!declaration.target || typeof declaration.target !== "object") {
+        throw new EventFilterCompileError(`trigger.on("${eventType}", ...): "target" must be a workflow definition (got ${typeof declaration.target})`);
+    }
+    const targetWorkflowId = typeof declaration.target.id === "string"
+        ? declaration.target.id
+        : "";
+    if (targetWorkflowId.length === 0) {
+        throw new EventFilterCompileError(`trigger.on("${eventType}", ...): "target.id" must be a non-empty string`);
+    }
+    // Validate `where` if supplied.
+    const where = declaration.where;
+    if (where !== undefined) {
+        const result = validatePredicate(where);
+        if (!result.ok) {
+            throw new EventFilterCompileError(`trigger.on("${eventType}", target=${targetWorkflowId}): invalid where clause`, result.errors);
+        }
+    }
+    // Validate `input` if supplied.
+    const input = declaration.input;
+    if (input !== undefined) {
+        const result = validateInputMapper(input);
+        if (!result.ok) {
+            throw new EventFilterCompileError(`trigger.on("${eventType}", target=${targetWorkflowId}): invalid input mapper`, result.errors);
+        }
+    }
+    // Reject the legacy `match` callback explicitly so authoring errors are obvious.
+    if (typeof declaration.match === "function") {
+        throw new EventFilterCompileError(`trigger.on("${eventType}"): the "match" callback is no longer supported. ` +
+            `Use the structured "where" predicate instead. See architecture doc §12.`);
+    }
+    // Canonical content-derived id. Stable across re-deploys because the
+    // canonicalized JSON of the declaration is identical for byte-equivalent
+    // sources.
+    const canonicalDeclaration = {
+        eventType,
+        where: where ?? null,
+        input: input ?? null,
+        targetWorkflowId,
+    };
+    const fullHash = await sha256(canonicalDeclaration);
+    const payloadHash = fullHash;
+    // Filter id seeds from the same hash but stays human-friendly in logs.
+    const id = `ef_${fullHash.slice(0, 16)}`;
+    const manifest = {
+        id,
+        eventType,
+        payloadHash,
+        targetWorkflowId,
+        ...(where !== undefined ? { where } : {}),
+        ...(input !== undefined ? { input } : {}),
+    };
+    const entry = {
+        id,
+        eventType,
+        manifest,
+        declaration: declaration,
+        targetWorkflowId,
+    };
+    return entry;
+}
+/**
+ * Compile + register in one step. The synchronous wrapper for `trigger.on()`
+ * that user code calls — validates the declaration, computes the
+ * content-derived id, registers the entry, and returns it.
+ *
+ * Returning the full {@link EventFilterRuntimeEntry} is what makes the
+ * authoring shape from the architecture doc work directly — modules can
+ * write `eventFilters: [trigger.on(...)]` without a registry round-trip:
+ * the entry already structurally satisfies `EventFilterDescriptor`
+ * (matching `id` + `eventType` fields) and carries the `manifest` payload
+ * `createApp()`'s wireWorkflowRuntime needs to register with the driver.
+ */
+export function compileAndRegister(eventType, declaration) {
+    // Run validation + compile synchronously where possible. The async
+    // boundary is the SHA-256 digest from Web Crypto; we bridge via a
+    // synchronous canonical-JSON hash so trigger.on() can stay sync.
+    const entry = compileEventFilterSync(eventType, declaration);
+    getEventFilterRegistry().add(entry);
+    return entry;
+}
+/**
+ * Synchronous compile — uses a deterministic but non-cryptographic hash
+ * over the canonical JSON. Suitable for the registry id (we just need
+ * stable + collision-resistant-enough across realistic registration
+ * counts). The crypto-grade `sha256(...)` is used at *manifest build*
+ * time when async is fine.
+ */
+export function compileEventFilterSync(eventType, declaration) {
+    if (typeof eventType !== "string" || eventType.length === 0) {
+        throw new EventFilterCompileError(`trigger.on(eventType, ...): eventType must be a non-empty string`);
+    }
+    if (typeof declaration !== "object" || declaration === null) {
+        throw new EventFilterCompileError(`trigger.on("${eventType}", ...): declaration must be an object`);
+    }
+    if (!declaration.target || typeof declaration.target !== "object") {
+        throw new EventFilterCompileError(`trigger.on("${eventType}", ...): "target" must be a workflow definition (got ${typeof declaration.target})`);
+    }
+    const targetWorkflowId = typeof declaration.target.id === "string"
+        ? declaration.target.id
+        : "";
+    if (targetWorkflowId.length === 0) {
+        throw new EventFilterCompileError(`trigger.on("${eventType}", ...): "target.id" must be a non-empty string`);
+    }
+    const where = declaration.where;
+    if (where !== undefined) {
+        const result = validatePredicate(where);
+        if (!result.ok) {
+            throw new EventFilterCompileError(`trigger.on("${eventType}", target=${targetWorkflowId}): invalid where clause`, result.errors);
+        }
+    }
+    const input = declaration.input;
+    if (input !== undefined) {
+        const result = validateInputMapper(input);
+        if (!result.ok) {
+            throw new EventFilterCompileError(`trigger.on("${eventType}", target=${targetWorkflowId}): invalid input mapper`, result.errors);
+        }
+    }
+    if (typeof declaration.match === "function") {
+        throw new EventFilterCompileError(`trigger.on("${eventType}"): the "match" callback is no longer supported. ` +
+            `Use the structured "where" predicate instead. See architecture doc §12.`);
+    }
+    const canonicalDeclaration = {
+        eventType,
+        where: where ?? null,
+        input: input ?? null,
+        targetWorkflowId,
+    };
+    const json = canonicalJson(canonicalDeclaration);
+    const shortId = nonCryptoHash16(json);
+    const id = `ef_${shortId}`;
+    const manifest = {
+        id,
+        eventType,
+        // payloadHash on the manifest is stable (same canonical JSON) but
+        // upgraded to the crypto-grade sha256 at manifest-build time. Until
+        // then it carries the same short hash so consumers that read it pre-
+        // build (e.g. dashboards in dev mode) still see something sensible.
+        payloadHash: shortId,
+        targetWorkflowId,
+        ...(where !== undefined ? { where } : {}),
+        ...(input !== undefined ? { input } : {}),
+    };
+    return {
+        id,
+        eventType,
+        manifest,
+        declaration: declaration,
+        targetWorkflowId,
+    };
+}
+/**
+ * Deterministic 16-hex-char hash for synchronous registration. Uses FNV-1a
+ * 64-bit folded into hex — collision-resistant enough at the cardinality of
+ * "filters per project" (low thousands at most). The cryptographic SHA-256
+ * is the source of truth for manifest-level identity; this is just enough
+ * to be a stable id for the in-process registry.
+ */
+function nonCryptoHash16(text) {
+    // FNV-1a 64-bit, computed as two 32-bit halves to avoid bigint overhead
+    // in tight loops. Output: 16 hex chars (concatenation of the two halves).
+    let h1 = 0xcbf29ce4;
+    let h2 = 0x84222325;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        h1 = (h1 ^ c) >>> 0;
+        h2 = (h2 ^ c) >>> 0;
+        // Multiply by 0x100000001b3 split into the two halves.
+        const lo = h2 * 0x01b3;
+        const hi = h1 * 0x01b3 + Math.floor(lo / 0x100000000);
+        h2 = (lo & 0xffffffff) >>> 0;
+        h1 = hi >>> 0;
+    }
+    return h1.toString(16).padStart(8, "0") + h2.toString(16).padStart(8, "0");
+}

package/dist/events/index.d.ts

@@ -0,0 +1,8 @@
+export { compileAndRegister, compileEventFilterSync, EventFilterCompileError, } from "./compile.js";
+export type { InputMapper } from "./input-mapper.js";
+export { type InputMapperValidationResult, projectInput, validateInputMapper, } from "./input-mapper.js";
+export { type BuildManifestArgs, buildManifest, } from "./manifest-builder.js";
+export { canonicalize, canonicalJson, deriveStableEventId, sha256, shortHash, } from "./payload-hash.js";
+export { evaluatePredicate, type PathOrLit, type PredicateEnvelope, type PredicateExpr, type PredicateValidationResult, resolvePath, validatePredicate, } from "./predicate.js";
+export { __resetEventFilterRegistry, type EventFilterRuntimeEntry, getEventFilterRegistry, } from "./registry.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,EACL,KAAK,2BAA2B,EAChC,YAAY,EACZ,mBAAmB,GACpB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,KAAK,iBAAiB,EACtB,aAAa,GACd,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,MAAM,EACN,SAAS,GACV,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,iBAAiB,EACjB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,yBAAyB,EAC9B,WAAW,EACX,iBAAiB,GAClB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,0BAA0B,EAC1B,KAAK,uBAAuB,EAC5B,sBAAsB,GACvB,MAAM,eAAe,CAAA"}

package/dist/events/index.js

@@ -0,0 +1,11 @@
+// `@voyantjs/workflows/events` — the events runtime: structured `where`
+// predicate + `input` mapper, event-filter registry, manifest builder.
+//
+// Authoritative architecture: docs/architecture/workflows-runtime-architecture.md
+// §12 (trigger.on runtime), §13 (DSLs), §14 (manifest lifecycle).
+export { compileAndRegister, compileEventFilterSync, EventFilterCompileError, } from "./compile.js";
+export { projectInput, validateInputMapper, } from "./input-mapper.js";
+export { buildManifest, } from "./manifest-builder.js";
+export { canonicalize, canonicalJson, deriveStableEventId, sha256, shortHash, } from "./payload-hash.js";
+export { evaluatePredicate, resolvePath, validatePredicate, } from "./predicate.js";
+export { __resetEventFilterRegistry, getEventFilterRegistry, } from "./registry.js";

package/dist/events/input-mapper.d.ts

@@ -0,0 +1,24 @@
+import { type PathOrLit, type PredicateEnvelope } from "./predicate.js";
+export type InputMapper = undefined | {
+    passthrough: true;
+} | {
+    path: string;
+} | {
+    object: Record<string, InputMapper | PathOrLit>;
+};
+/**
+ * Project a workflow input from an event envelope. Mirrors the predicate
+ * evaluator's no-throw contract — missing paths produce `undefined` in the
+ * output, registration-time linting catches structural errors.
+ *
+ * Throws `InputMapperError` only on unexpected shape errors (the mapper
+ * itself was constructed wrong). Drivers catch and surface this as
+ * `IngestMatch.status === "skipped"` with reason `"input_projection_error"`.
+ */
+export declare function projectInput(mapper: InputMapper, envelope: PredicateEnvelope): unknown;
+export interface InputMapperValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+export declare function validateInputMapper(mapper: InputMapper): InputMapperValidationResult;
+//# sourceMappingURL=input-mapper.d.ts.map

package/dist/events/input-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-mapper.d.ts","sourceRoot":"","sources":["../../src/events/input-mapper.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,iBAAiB,EAAe,MAAM,gBAAgB,CAAA;AAIpF,MAAM,MAAM,WAAW,GACnB,SAAS,GACT;IAAE,WAAW,EAAE,IAAI,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC,CAAA;CAAE,CAAA;AAIvD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAgCtF;AAID,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,2BAA2B,CAIpF"}