botmux 2.33.0 → 2.34.0

package/dist/workflows/events/append.js

@@ -0,0 +1,214 @@
+import { promises as fs, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { INLINE_PAYLOAD_MAX_BYTES, PayloadRefSchema, isPayloadRef, parseEvent, } from './schema.js';
+import { withFileLock } from '../../utils/file-lock.js';
+// ─── Mutex (per-runId append serialization, in-process) ─────────────────────
+/**
+ * Minimal promise-chain mutex.  Single-process serialization layer.
+ */
+class Mutex {
+    tail = Promise.resolve();
+    async run(fn) {
+        const prior = this.tail;
+        let release;
+        this.tail = new Promise((r) => {
+            release = r;
+        });
+        try {
+            await prior;
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+}
+/**
+ * Module-level mutex map keyed by runId.  Codex round 4 fix: a single
+ * instance's mutex doesn't protect against two `new EventLog(runId, base)`
+ * instances inside the same process — they would each hold a fresh mutex
+ * and race on seq assignment.  Sharing the mutex per-runId at module scope
+ * closes that hole.  Cross-process is closed by `withFileLock` (below).
+ */
+const RUN_MUTEXES = new Map();
+function getRunMutex(runId) {
+    let m = RUN_MUTEXES.get(runId);
+    if (!m) {
+        m = new Mutex();
+        RUN_MUTEXES.set(runId, m);
+    }
+    return m;
+}
+// ─── EventLog ───────────────────────────────────────────────────────────────
+export class EventLog {
+    runId;
+    runDir;
+    eventsFile;
+    blobDir;
+    // Cached seq + file metadata for cross-process change detection.
+    seq = 0;
+    seqLoaded = false;
+    cachedMtimeMs = 0;
+    cachedSize = 0;
+    constructor(runId, baseDir) {
+        if (!runId)
+            throw new Error('EventLog: runId required');
+        if (!baseDir)
+            throw new Error('EventLog: baseDir required');
+        this.runId = runId;
+        this.runDir = join(baseDir, runId);
+        this.eventsFile = join(this.runDir, 'events.ndjson');
+        this.blobDir = join(this.runDir, 'blobs');
+        if (!existsSync(this.runDir))
+            mkdirSync(this.runDir, { recursive: true });
+        if (!existsSync(this.blobDir))
+            mkdirSync(this.blobDir, { recursive: true });
+    }
+    /**
+     * Append one event.  Atomic across:
+     *   1. all EventLog instances for the same runId in this process
+     *      (module-level mutex map), and
+     *   2. other OS processes touching the same events file
+     *      (`withFileLock` over `events.ndjson.lock`).
+     *
+     * Codex round 4 finding 1: payload envelope MUST be inline.  Large
+     * business data goes through `OutputRef`-shaped fields (e.g.
+     * `runCreated.inputRef`, `activitySucceeded.outputRef`); the caller is
+     * responsible for writing the blob and passing a fully-formed
+     * `OutputRef` inline.  The append path no longer auto-spills payloads —
+     * doing so silently broke replay for any ref-payload event because the
+     * existing replay projection unconditionally skipped the ref branch.
+     *
+     * Payload-ref payloads (`{ ref, bytes, schemaVersion }`) are still
+     * supported for callers who genuinely need to ref-out the envelope
+     * payload (e.g. a custom dashboard projection), but the caller must
+     * supply both the blob and `payloadHash` upfront; this path is not
+     * exercised by the v0 runtime.
+     */
+    async append(draft) {
+        return getRunMutex(this.runId).run(() => withFileLock(this.eventsFile, () => this.appendLocked(draft)));
+    }
+    async appendLocked(draft) {
+        await this.refreshSeqIfStale();
+        const nextSeq = this.seq + 1;
+        const timestamp = draft.timestamp ?? Date.now();
+        const candidate = {
+            eventId: `${this.runId}-${nextSeq}`,
+            runId: this.runId,
+            timestamp,
+            type: draft.type,
+            schemaVersion: 1,
+            actor: draft.actor,
+            payload: draft.payload,
+        };
+        if ('payloadHash' in draft && draft.payloadHash !== undefined) {
+            candidate.payloadHash = draft.payloadHash;
+        }
+        // Reject inline payloads that exceed the cap.  The runtime should
+        // restructure to use `OutputRef`-shaped fields for large business
+        // data; envelope payloads are metadata + small refs only.
+        if (!isPayloadRef(draft.payload)) {
+            const inlineSize = Buffer.byteLength(JSON.stringify(draft.payload), 'utf-8');
+            if (inlineSize > INLINE_PAYLOAD_MAX_BYTES) {
+                throw new Error(`EventLog(${this.runId}).append: inline payload (${inlineSize} bytes) exceeds ` +
+                    `INLINE_PAYLOAD_MAX_BYTES (${INLINE_PAYLOAD_MAX_BYTES}).  Restructure large fields ` +
+                    `to use OutputRef-shaped fields (events doc v0.1.2 §3.1) instead of stuffing them ` +
+                    `into the envelope payload.`);
+            }
+        }
+        const parsed = parseEvent(candidate);
+        const line = JSON.stringify(parsed) + '\n';
+        await fs.appendFile(this.eventsFile, line, 'utf-8');
+        // Cache update — we just wrote, so size grew.  Stat would also work.
+        const stat = await fs.stat(this.eventsFile);
+        this.seq = nextSeq;
+        this.cachedMtimeMs = stat.mtimeMs;
+        this.cachedSize = stat.size;
+        this.seqLoaded = true;
+        return parsed;
+    }
+    /**
+     * Read all events in append order.  Used by replay (events doc §5.2)
+     * and seq recovery on restart.  Returns [] if the log doesn't exist
+     * yet.
+     *
+     * Throws if any line fails schema validation — events doc treats the
+     * log as authoritative and corruption should fail loud, not silently
+     * skip lines.
+     */
+    async readAll() {
+        if (!existsSync(this.eventsFile))
+            return [];
+        const content = await fs.readFile(this.eventsFile, 'utf-8');
+        const events = [];
+        let lineNo = 0;
+        for (const raw of content.split('\n')) {
+            lineNo++;
+            if (!raw)
+                continue;
+            try {
+                const obj = JSON.parse(raw);
+                events.push(parseEvent(obj));
+            }
+            catch (err) {
+                throw new Error(`EventLog(${this.runId}): corrupt event at line ${lineNo}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return events;
+    }
+    /**
+     * Read the blob referenced by a ref-payload event.  Used when a caller
+     * elected to spill their own OutputRef payload to disk; not used by
+     * envelope-payload paths since v0.1.2 round-4 disallows envelope spill.
+     */
+    async readBlob(ref) {
+        return fs.readFile(ref);
+    }
+    /** Current seq counter — exposed for tests / dashboard. */
+    async currentSeq() {
+        return getRunMutex(this.runId).run(() => withFileLock(this.eventsFile, async () => {
+            await this.refreshSeqIfStale();
+            return this.seq;
+        }));
+    }
+    /**
+     * Refresh `this.seq` if the events file has changed since we last loaded.
+     * Stat is cheap; full re-scan only fires when the cached mtime/size differ
+     * from disk — protects against another process having appended since our
+     * last write.
+     */
+    async refreshSeqIfStale() {
+        if (!existsSync(this.eventsFile)) {
+            this.seq = 0;
+            this.seqLoaded = true;
+            this.cachedMtimeMs = 0;
+            this.cachedSize = 0;
+            return;
+        }
+        const stat = await fs.stat(this.eventsFile);
+        if (this.seqLoaded &&
+            stat.mtimeMs === this.cachedMtimeMs &&
+            stat.size === this.cachedSize) {
+            return;
+        }
+        // Rescan from disk.  Linear in events for v0; future optimization
+        // could read from end-of-file backwards to find the last seq line.
+        const events = await this.readAll();
+        let maxSeq = 0;
+        for (const e of events) {
+            const m = e.eventId.match(/-(\d+)$/);
+            if (m) {
+                const s = parseInt(m[1], 10);
+                if (s > maxSeq)
+                    maxSeq = s;
+            }
+        }
+        this.seq = maxSeq;
+        this.cachedMtimeMs = stat.mtimeMs;
+        this.cachedSize = stat.size;
+        this.seqLoaded = true;
+    }
+}
+// ─── Reexport schemas the EventLog returns, for ergonomic call sites ────────
+export { PayloadRefSchema, INLINE_PAYLOAD_MAX_BYTES };
+//# sourceMappingURL=append.js.map

package/dist/workflows/events/append.js.map

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

package/dist/workflows/events/idempotency.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Serialize `value` to canonical JSON (deterministic across object key order
+ * and identical-content equality).  Used by:
+ *   - `computeInputHash` to derive inputHash for attempt input immutability
+ *     checks (events doc §4.2 + §3.6).
+ *   - any code path that needs hash-stable serialization of structured data.
+ *
+ * Rules:
+ *   - Object keys are sorted ascending (lexicographic on UTF-16 code units,
+ *     matching JS's default Array.sort).
+ *   - `undefined` properties are dropped (matches `JSON.stringify` behaviour
+ *     for plain objects).
+ *   - `null` is preserved as `"null"`.
+ *   - Arrays preserve order — they're ordered data, not bags.
+ *   - Strings, numbers, booleans use `JSON.stringify` (handles escapes).
+ *   - Non-finite numbers (`NaN`, `±Infinity`), BigInt, Function, Symbol,
+ *     Date, and class instances throw.  Dates would need a project-wide
+ *     decision on epoch-ms vs ISO string; v0 throws so the caller is forced
+ *     to normalize upstream.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * The 5-tuple that anchors workflow idempotency (events doc §3.2 / §4.2).
+ * Each attempt is uniquely identified by this combination; the derived
+ * key feeds into provider uuid fields (Feishu IM uuid, schedule-store id).
+ */
+export type IdempotencyKeyTuple = {
+    workflowId: string;
+    revisionId: string;
+    runId: string;
+    nodeId: string;
+    attemptId: string;
+};
+export type DeriveIdempotencyKeyOptions = {
+    /**
+     * String prefix prepended to the truncated hash.  Defaults to `wf_`,
+     * which keeps workflow-generated ids in a separate namespace from
+     * randomUUID-derived ids (events doc §2.2 schedule case).  Pass empty
+     * string to disable.  Must be ≤ `maxLength - 1`.
+     */
+    namespace?: string;
+    /**
+     * Max output length.  Defaults to 50 to match Feishu IM uuid field's
+     * documented upper bound (spike report §1.2).
+     */
+    maxLength?: number;
+};
+/**
+ * Deterministically derive an idempotency key from the 5-tuple.  Same tuple
+ * always produces the same key; collisions are bounded by the truncated
+ * SHA-256 birthday term.  With default namespace `wf_` and maxLength 50:
+ *
+ *   key = "wf_" + sha256(workflowId:revisionId:runId:nodeId:attemptId)[:47]
+ *
+ * 47 hex chars = 188 bits of entropy, ample for collision-free workflow
+ * lifetimes.
+ */
+export declare function deriveIdempotencyKey(tuple: IdempotencyKeyTuple, opts?: DeriveIdempotencyKeyOptions): string;
+/**
+ * Hash an attempt's canonical input.  Returned in `sha256:<hex>` form so
+ * it slots directly into event payloads (`effectAttempted.inputHash` and
+ * resume reconcile evidence).
+ *
+ * The hash is over the **full canonical input** — for send/reply that
+ * includes `receive_id`, `root_message_id?`, `msg_type`, `content`; for
+ * schedule it includes the entire create-task input.  Spike report §1.3
+ * + reply test 3c proved partial hashes leak silent state drift.
+ *
+ * inputHash is **separate** from idempotencyKey by design (codex v0.1.1
+ * round 2): mixing content into the key would convert "input changed" into
+ * "new effect", bypassing attempt-immutability.  inputHash lives as a
+ * post-fact validator: same attemptId must always produce the same
+ * inputHash; mismatches trigger `IdempotencyInputMismatch` (events doc
+ * §4.2).
+ */
+export declare function computeInputHash(input: unknown): string;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/workflows/events/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../../src/workflows/events/idempotency.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAuCD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,mBAAmB,EAC1B,IAAI,GAAE,2BAAgC,GACrC,MAAM,CAuBR;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIvD"}

package/dist/workflows/events/idempotency.js

@@ -0,0 +1,116 @@
+import { createHash } from 'node:crypto';
+// ─── canonical JSON ─────────────────────────────────────────────────────────
+/**
+ * Serialize `value` to canonical JSON (deterministic across object key order
+ * and identical-content equality).  Used by:
+ *   - `computeInputHash` to derive inputHash for attempt input immutability
+ *     checks (events doc §4.2 + §3.6).
+ *   - any code path that needs hash-stable serialization of structured data.
+ *
+ * Rules:
+ *   - Object keys are sorted ascending (lexicographic on UTF-16 code units,
+ *     matching JS's default Array.sort).
+ *   - `undefined` properties are dropped (matches `JSON.stringify` behaviour
+ *     for plain objects).
+ *   - `null` is preserved as `"null"`.
+ *   - Arrays preserve order — they're ordered data, not bags.
+ *   - Strings, numbers, booleans use `JSON.stringify` (handles escapes).
+ *   - Non-finite numbers (`NaN`, `±Infinity`), BigInt, Function, Symbol,
+ *     Date, and class instances throw.  Dates would need a project-wide
+ *     decision on epoch-ms vs ISO string; v0 throws so the caller is forced
+ *     to normalize upstream.
+ */
+export function canonicalJson(value) {
+    return serialize(value);
+}
+function serialize(v) {
+    if (v === null)
+        return 'null';
+    if (typeof v === 'boolean')
+        return v ? 'true' : 'false';
+    if (typeof v === 'number') {
+        if (!Number.isFinite(v)) {
+            throw new Error(`canonicalJson: non-finite number (${String(v)}) not serializable`);
+        }
+        return JSON.stringify(v);
+    }
+    if (typeof v === 'string')
+        return JSON.stringify(v);
+    if (Array.isArray(v)) {
+        return '[' + v.map((x) => serialize(x)).join(',') + ']';
+    }
+    if (typeof v === 'object') {
+        // Reject anything that's not a plain object.  This guards against Date,
+        // Map, Set, Buffer, class instances etc. that would otherwise leak
+        // internal state into the hash.
+        if (Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null) {
+            throw new Error(`canonicalJson: non-plain-object (${v?.constructor?.name ?? 'unknown'}) not serializable — normalize upstream`);
+        }
+        const obj = v;
+        const keys = Object.keys(obj)
+            .filter((k) => obj[k] !== undefined)
+            .sort();
+        return '{' + keys.map((k) => JSON.stringify(k) + ':' + serialize(obj[k])).join(',') + '}';
+    }
+    if (typeof v === 'bigint') {
+        throw new Error('canonicalJson: bigint not serializable — convert to string upstream');
+    }
+    // function, symbol, undefined at the root
+    throw new Error(`canonicalJson: cannot serialize ${typeof v}`);
+}
+/**
+ * Deterministically derive an idempotency key from the 5-tuple.  Same tuple
+ * always produces the same key; collisions are bounded by the truncated
+ * SHA-256 birthday term.  With default namespace `wf_` and maxLength 50:
+ *
+ *   key = "wf_" + sha256(workflowId:revisionId:runId:nodeId:attemptId)[:47]
+ *
+ * 47 hex chars = 188 bits of entropy, ample for collision-free workflow
+ * lifetimes.
+ */
+export function deriveIdempotencyKey(tuple, opts = {}) {
+    const namespace = opts.namespace ?? 'wf_';
+    const maxLength = opts.maxLength ?? 50;
+    if (namespace.length >= maxLength) {
+        throw new Error(`deriveIdempotencyKey: namespace '${namespace}' (${namespace.length} chars) leaves no room for hash in maxLength ${maxLength}`);
+    }
+    for (const [k, v] of Object.entries(tuple)) {
+        if (typeof v !== 'string' || v.length === 0) {
+            throw new Error(`deriveIdempotencyKey: tuple.${k} must be non-empty string, got ${String(v)}`);
+        }
+    }
+    // Codex round 4 minor: original implementation `${a}:${b}:${c}:${d}:${e}`
+    // had a theoretical collision: two distinct tuples whose fields happen
+    // to span `:` boundaries differently can produce the same seed (e.g.
+    // `{a:'x:y', b:'z', ...}` collides with `{a:'x', b:'y:z', ...}`).
+    // Hashing canonicalJson(tuple) — same canonical form used everywhere
+    // else for hash-stable serialization — closes the hole without any
+    // call-site change.
+    const seed = canonicalJson(tuple);
+    const hash = createHash('sha256').update(seed, 'utf-8').digest('hex');
+    return namespace + hash.substring(0, maxLength - namespace.length);
+}
+// ─── input hash (canonical full-field sha256) ───────────────────────────────
+/**
+ * Hash an attempt's canonical input.  Returned in `sha256:<hex>` form so
+ * it slots directly into event payloads (`effectAttempted.inputHash` and
+ * resume reconcile evidence).
+ *
+ * The hash is over the **full canonical input** — for send/reply that
+ * includes `receive_id`, `root_message_id?`, `msg_type`, `content`; for
+ * schedule it includes the entire create-task input.  Spike report §1.3
+ * + reply test 3c proved partial hashes leak silent state drift.
+ *
+ * inputHash is **separate** from idempotencyKey by design (codex v0.1.1
+ * round 2): mixing content into the key would convert "input changed" into
+ * "new effect", bypassing attempt-immutability.  inputHash lives as a
+ * post-fact validator: same attemptId must always produce the same
+ * inputHash; mismatches trigger `IdempotencyInputMismatch` (events doc
+ * §4.2).
+ */
+export function computeInputHash(input) {
+    const canonical = canonicalJson(input);
+    const hex = createHash('sha256').update(canonical, 'utf-8').digest('hex');
+    return `sha256:${hex}`;
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/workflows/events/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../../src/workflows/events/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,SAAS,CAAC,CAAU;IAC3B,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IACxD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,qCAAqC,MAAM,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACpD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,OAAO,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAC1D,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,wEAAwE;QACxE,mEAAmE;QACnE,gCAAgC;QAChC,IAAI,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACvF,MAAM,IAAI,KAAK,CACb,oCAAoC,CAAC,EAAE,WAAW,EAAE,IAAI,IAAI,SAAS,yCAAyC,CAC/G,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,CAA4B,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;aAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;aACnC,IAAI,EAAE,CAAC;QACV,OAAO,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAC5F,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;IACzF,CAAC;IACD,0CAA0C;IAC1C,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,CAAC,EAAE,CAAC,CAAC;AACjE,CAAC;AAgCD;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAA0B,EAC1B,OAAoC,EAAE;IAEtC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;IACvC,IAAI,SAAS,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,oCAAoC,SAAS,MAAM,SAAS,CAAC,MAAM,gDAAgD,SAAS,EAAE,CAC/H,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,kCAAkC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;IACD,0EAA0E;IAC1E,uEAAuE;IACvE,qEAAqE;IACrE,kEAAkE;IAClE,qEAAqE;IACrE,mEAAmE;IACnE,oBAAoB;IACpB,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtE,OAAO,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;AACrE,CAAC;AAED,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1E,OAAO,UAAU,GAAG,EAAE,CAAC;AACzB,CAAC"}

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

@@ -0,0 +1,7 @@
+export * from './payloads.js';
+export * from './schema.js';
+export * from './types.js';
+export * from './append.js';
+export * from './replay.js';
+export * from './idempotency.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/workflows/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC"}

package/dist/workflows/events/index.js

@@ -0,0 +1,7 @@
+export * from './payloads.js';
+export * from './schema.js';
+export * from './types.js';
+export * from './append.js';
+export * from './replay.js';
+export * from './idempotency.js';
+//# sourceMappingURL=index.js.map

package/dist/workflows/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/workflows/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC"}