@blokjs/runner 0.6.21 → 0.7.0

package/dist/scheduling/RedisDebounceBackend.js

@@ -1,356 +0,0 @@
-/**
- * Tier C #1 · Redis-backed debounce backend.
- *
- * Coordinates per-(workflow, debounceKey) window state across processes
- * via a single Redis string key per bucket. Atomicity comes from
- * server-side **Lua scripts** — `registerPing` / `finalize` /
- * `cancel` / `purgeExpired` each run as a single `EVAL` with no OCC
- * retry loop (Lua runs single-threaded against the keyspace).
- *
- * Storage shape: one JSON document per `(workflowName, debounceKey)`
- * bucket. Owner identity is encoded in the doc itself as
- * `(activeRunId, ownerProcessId, ownerLeaseExpiresAt)`; lease handoff
- * happens atomically when a ping arrives after the lease expired.
- *
- * **Owner-local payload**: this backend tracks `pingCount`,
- * `lastPingAt`, and `scheduledAt` only — payloads do NOT travel across
- * processes. The owning process's local `onFire` closure fires when
- * its timer elapses.
- */
-const DEFAULT_KEY_PREFIX = "blok-debounce";
-/**
- * Atomic registerPing. Reads the current doc (if any), decides
- * ownership, writes back the next state, and returns
- * `{outcome, activeRunId, scheduledAt, pingCount}`.
- *
- * KEYS[1] = bucket key
- * ARGV[1] = mode ("leading" | "trailing")
- * ARGV[2] = delayMs
- * ARGV[3] = maxDelayMs ("-1" when unset)
- * ARGV[4] = runId
- * ARGV[5] = processId
- * ARGV[6] = ownerLeaseMs
- * ARGV[7] = now
- *
- * Returns: { outcome ("owner-new" | "owner-extend" | "coalesce"),
- *            activeRunId, scheduledAt, pingCount }
- */
-const REGISTER_PING_LUA = `
-local raw = redis.call('GET', KEYS[1])
-local existing = nil
-if raw and raw ~= '' then
-  local ok, parsed = pcall(cjson.decode, raw)
-  if ok and type(parsed) == 'table' then
-    existing = parsed
-  end
-end
-
-local mode = ARGV[1]
-local delayMs = tonumber(ARGV[2])
-local maxDelayMsRaw = tonumber(ARGV[3])
-local maxDelayMs
-if maxDelayMsRaw and maxDelayMsRaw >= 0 then maxDelayMs = maxDelayMsRaw end
-local runId = ARGV[4]
-local processId = ARGV[5]
-local ownerLeaseMs = tonumber(ARGV[6])
-local now = tonumber(ARGV[7])
-
-local function compute_scheduled_at(existing_doc, now_)
-  local naive = now_ + delayMs
-  local deadline
-  if existing_doc and existing_doc.maxDelayDeadline then
-    deadline = tonumber(existing_doc.maxDelayDeadline)
-  elseif maxDelayMs then
-    deadline = now_ + maxDelayMs
-  end
-  if deadline and deadline < naive then return deadline end
-  return naive
-end
-
-local ownerActive = existing ~= nil and tonumber(existing.ownerLeaseExpiresAt) and tonumber(existing.ownerLeaseExpiresAt) > now
-
-if not existing or not ownerActive then
-  local first_ping_at = (existing and existing.firstPingAt) and tonumber(existing.firstPingAt) or now
-  local max_delay_deadline
-  if existing and existing.maxDelayDeadline then
-    max_delay_deadline = tonumber(existing.maxDelayDeadline)
-  elseif maxDelayMs then
-    max_delay_deadline = now + maxDelayMs
-  end
-  local prev_count = (existing and existing.pingCount) and tonumber(existing.pingCount) or 0
-  local doc = {
-    mode = mode,
-    delayMs = delayMs,
-    maxDelayMs = maxDelayMs,
-    maxDelayDeadline = max_delay_deadline,
-    firstPingAt = first_ping_at,
-    lastPingAt = now,
-    pingCount = prev_count + 1,
-    activeRunId = runId,
-    ownerProcessId = processId,
-    ownerLeaseExpiresAt = now + ownerLeaseMs,
-    scheduledAt = compute_scheduled_at(existing, now),
-  }
-  redis.call('SET', KEYS[1], cjson.encode(doc))
-  return { "owner-new", doc.activeRunId, tostring(doc.scheduledAt), tostring(doc.pingCount) }
-end
-
-if tostring(existing.ownerProcessId) == processId then
-  -- We still own — extend window.
-  existing.lastPingAt = now
-  existing.pingCount = (tonumber(existing.pingCount) or 0) + 1
-  existing.ownerLeaseExpiresAt = now + ownerLeaseMs
-  existing.scheduledAt = compute_scheduled_at(existing, now)
-  redis.call('SET', KEYS[1], cjson.encode(existing))
-  return { "owner-extend", tostring(existing.activeRunId), tostring(existing.scheduledAt), tostring(existing.pingCount) }
-end
-
--- Different process owns — coalesce.
-existing.lastPingAt = now
-existing.pingCount = (tonumber(existing.pingCount) or 0) + 1
-existing.scheduledAt = compute_scheduled_at(existing, now)
-redis.call('SET', KEYS[1], cjson.encode(existing))
-return { "coalesce", tostring(existing.activeRunId), tostring(existing.scheduledAt), tostring(existing.pingCount) }
-`;
-/**
- * Atomic finalize. The owning process calls this on local timer fire.
- *
- * KEYS[1] = bucket key
- * ARGV[1] = runId (the OWNING runId from the caller's perspective)
- * ARGV[2] = now
- *
- * Returns:
- *   { "fire" }                          — caller still owns AND silence elapsed; DELETE done.
- *   { "reschedule", "<scheduledAt>" }   — coalesce pings pushed scheduledAt forward.
- *   { "abandoned" }                     — caller no longer owns OR bucket gone.
- */
-const FINALIZE_LUA = `
-local raw = redis.call('GET', KEYS[1])
-if not raw or raw == '' then return { "abandoned" } end
-
-local ok, doc = pcall(cjson.decode, raw)
-if not ok or type(doc) ~= 'table' then return { "abandoned" } end
-
-if tostring(doc.activeRunId) ~= ARGV[1] then return { "abandoned" } end
-
-local now = tonumber(ARGV[2])
-local scheduled = tonumber(doc.scheduledAt) or 0
-if now < scheduled then
-  return { "reschedule", tostring(scheduled) }
-end
-
-redis.call('DEL', KEYS[1])
-return { "fire" }
-`;
-export function readRedisDebounceConfigFromEnv() {
-    const url = process.env.BLOK_DEBOUNCE_REDIS_URL?.trim() || undefined;
-    const host = process.env.BLOK_DEBOUNCE_REDIS_HOST?.trim() || undefined;
-    const portRaw = process.env.BLOK_DEBOUNCE_REDIS_PORT?.trim();
-    const port = portRaw && /^\d+$/.test(portRaw) ? Number(portRaw) : undefined;
-    const dbRaw = process.env.BLOK_DEBOUNCE_REDIS_DB?.trim();
-    const db = dbRaw && /^\d+$/.test(dbRaw) ? Number(dbRaw) : undefined;
-    const tls = process.env.BLOK_DEBOUNCE_REDIS_TLS === "1" || process.env.BLOK_DEBOUNCE_REDIS_TLS === "true";
-    return {
-        url,
-        host,
-        port,
-        password: process.env.BLOK_DEBOUNCE_REDIS_PASSWORD,
-        username: process.env.BLOK_DEBOUNCE_REDIS_USERNAME,
-        db,
-        tls,
-        keyPrefix: process.env.BLOK_DEBOUNCE_REDIS_KEY_PREFIX?.trim() || DEFAULT_KEY_PREFIX,
-    };
-}
-export class RedisDebounceBackend {
-    name = "redis";
-    client = null;
-    config;
-    connected = false;
-    constructor(config) {
-        const env = readRedisDebounceConfigFromEnv();
-        this.config = {
-            url: config?.url ?? env.url,
-            host: config?.host ?? env.host,
-            port: config?.port ?? env.port,
-            password: config?.password ?? env.password,
-            username: config?.username ?? env.username,
-            db: config?.db ?? env.db,
-            tls: config?.tls ?? env.tls,
-            keyPrefix: config?.keyPrefix ?? env.keyPrefix,
-        };
-    }
-    async connect() {
-        if (this.connected)
-            return;
-        const blokEnv = process.env.BLOK_ENV;
-        const nodeEnv = process.env.NODE_ENV;
-        const isProd = blokEnv === "production" || nodeEnv === "production";
-        if (isProd && this.config.keyPrefix === DEFAULT_KEY_PREFIX) {
-            throw new Error(`[blok] Redis debounce backend refuses to start in production with the default key prefix ('${DEFAULT_KEY_PREFIX}'). Set BLOK_DEBOUNCE_REDIS_KEY_PREFIX to a deployment-unique value (e.g. 'blok-debounce-acme-prod') to prevent cross-deployment collision on a shared Redis instance.`);
-        }
-        let ioredisModule;
-        try {
-            ioredisModule = (await import("ioredis"));
-        }
-        catch (err) {
-            throw new Error(`RedisDebounceBackend requires the 'ioredis' package. Install it: \`bun add ioredis\` or \`npm install ioredis\`. Underlying error: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        const IORedisCtor = ioredisModule.default ?? ioredisModule.Redis;
-        if (!IORedisCtor) {
-            throw new Error("RedisDebounceBackend could not locate the ioredis constructor on the imported module. Reinstall ioredis or report this issue.");
-        }
-        // Same fail-fast posture as RedisConcurrencyBackend.
-        const failFastDefaults = {
-            connectTimeout: 5_000,
-            maxRetriesPerRequest: 0,
-            enableOfflineQueue: false,
-            lazyConnect: true,
-        };
-        if (this.config.url) {
-            this.client = new IORedisCtor(this.config.url);
-        }
-        else {
-            const opts = { ...failFastDefaults };
-            if (this.config.host)
-                opts.host = this.config.host;
-            if (this.config.port)
-                opts.port = this.config.port;
-            if (this.config.username)
-                opts.username = this.config.username;
-            if (this.config.password)
-                opts.password = this.config.password;
-            if (typeof this.config.db === "number")
-                opts.db = this.config.db;
-            if (this.config.tls)
-                opts.tls = {};
-            this.client = new IORedisCtor(opts);
-        }
-        this.client.on("error", (err) => {
-            console.warn(`[blok][debounce][redis] client error: ${err.message}`);
-        });
-        await this.client.ping();
-        this.connected = true;
-    }
-    async disconnect() {
-        if (!this.connected)
-            return;
-        try {
-            await this.client?.quit();
-        }
-        catch {
-            // best-effort
-        }
-        finally {
-            this.client = null;
-            this.connected = false;
-        }
-    }
-    bucketKey(workflowName, debounceKey) {
-        return `${this.config.keyPrefix}:${this.encodeSegment(workflowName)}__${this.encodeSegment(debounceKey)}`;
-    }
-    encodeSegment(s) {
-        return s.replace(/[^-_=.a-zA-Z0-9]/g, (ch) => `_${ch.codePointAt(0)?.toString(16)}_`);
-    }
-    requireClient() {
-        if (!this.client) {
-            throw new Error("RedisDebounceBackend not connected — call connect() first.");
-        }
-        return this.client;
-    }
-    async registerPing(opts) {
-        const client = this.requireClient();
-        const key = this.bucketKey(opts.workflowName, opts.debounceKey);
-        const raw = await client.eval(REGISTER_PING_LUA, 1, key, opts.mode, String(opts.delayMs), opts.maxDelayMs !== undefined ? String(opts.maxDelayMs) : "-1", opts.runId, opts.processId, String(opts.ownerLeaseMs), String(opts.now));
-        return this.parseRegisterResult(raw);
-    }
-    async finalize(workflowName, debounceKey, runId, now) {
-        const client = this.requireClient();
-        const key = this.bucketKey(workflowName, debounceKey);
-        const raw = await client.eval(FINALIZE_LUA, 1, key, runId, String(now));
-        return this.parseFinalizeResult(raw);
-    }
-    async cancel(workflowName, debounceKey) {
-        const client = this.requireClient();
-        const key = this.bucketKey(workflowName, debounceKey);
-        const deleted = await client.del(key);
-        return deleted > 0;
-    }
-    async purgeExpired(now) {
-        const client = this.requireClient();
-        const pattern = `${this.config.keyPrefix}:*`;
-        let cursor = "0";
-        let purged = 0;
-        do {
-            let res;
-            try {
-                res = await client.scan(cursor, "MATCH", pattern, "COUNT", 100);
-            }
-            catch {
-                return purged;
-            }
-            const [nextCursor, keys] = res;
-            cursor = nextCursor;
-            for (const key of keys) {
-                try {
-                    const raw = await client.eval(PURGE_EXPIRED_BUCKET_LUA, 1, key, String(now));
-                    const count = typeof raw === "number" ? raw : Number(raw);
-                    if (!Number.isNaN(count))
-                        purged += count;
-                }
-                catch {
-                    // best-effort
-                }
-            }
-        } while (cursor !== "0");
-        return purged;
-    }
-    parseRegisterResult(raw) {
-        if (!Array.isArray(raw) || raw.length < 4) {
-            throw new Error(`Unexpected Lua result shape for registerPing: ${JSON.stringify(raw)}`);
-        }
-        const outcome = String(raw[0]);
-        if (outcome !== "owner-new" && outcome !== "owner-extend" && outcome !== "coalesce") {
-            throw new Error(`Unexpected outcome in Lua result: ${outcome}`);
-        }
-        return {
-            outcome,
-            activeRunId: String(raw[1]),
-            scheduledAt: Number(raw[2]),
-            pingCount: Number(raw[3]),
-        };
-    }
-    parseFinalizeResult(raw) {
-        if (!Array.isArray(raw) || raw.length < 1)
-            return { finalize: "abandoned" };
-        const tag = String(raw[0]);
-        if (tag === "fire")
-            return { finalize: "fire" };
-        if (tag === "reschedule")
-            return { finalize: "reschedule", scheduledAt: Number(raw[1]) };
-        return { finalize: "abandoned" };
-    }
-}
-/**
- * Per-bucket purge. Deletes the bucket iff the owner-lease has expired
- * AND scheduledAt has elapsed (no active owner with a pending fire).
- *
- * KEYS[1] = bucket key
- * ARGV[1] = now
- *
- * Returns: 1 if deleted, 0 otherwise.
- */
-const PURGE_EXPIRED_BUCKET_LUA = `
-local raw = redis.call('GET', KEYS[1])
-if not raw or raw == '' then return 0 end
-local ok, doc = pcall(cjson.decode, raw)
-if not ok or type(doc) ~= 'table' then return 0 end
-local now = tonumber(ARGV[1])
-local lease = tonumber(doc.ownerLeaseExpiresAt) or 0
-local sched = tonumber(doc.scheduledAt) or 0
-if lease <= now and sched <= now then
-  redis.call('DEL', KEYS[1])
-  return 1
-end
-return 0
-`;
-//# sourceMappingURL=RedisDebounceBackend.js.map

package/dist/scheduling/RedisDebounceBackend.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"RedisDebounceBackend.js","sourceRoot":"","sources":["../../src/scheduling/RedisDebounceBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAoBH,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAgB3C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EzB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;CAiBpB,CAAC;AAEF,MAAM,UAAU,8BAA8B;IAC7C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IACrE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IACvE,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,IAAI,EAAE,CAAC;IAC7D,MAAM,IAAI,GAAG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,IAAI,EAAE,CAAC;IACzD,MAAM,EAAE,GAAG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,MAAM,CAAC;IAC1G,OAAO;QACN,GAAG;QACH,IAAI;QACJ,IAAI;QACJ,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,4BAA4B;QAClD,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,4BAA4B;QAClD,EAAE;QACF,GAAG;QACH,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,8BAA8B,EAAE,IAAI,EAAE,IAAI,kBAAkB;KACnF,CAAC;AACH,CAAC;AAED,MAAM,OAAO,oBAAoB;IACvB,IAAI,GAAG,OAAO,CAAC;IAEhB,MAAM,GAAuB,IAAI,CAAC;IACzB,MAAM,CAAsB;IACrC,SAAS,GAAG,KAAK,CAAC;IAE1B,YAAY,MAAqC;QAChD,MAAM,GAAG,GAAG,8BAA8B,EAAE,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG;YACb,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,GAAG;YAC3B,IAAI,EAAE,MAAM,EAAE,IAAI,IAAI,GAAG,CAAC,IAAI;YAC9B,IAAI,EAAE,MAAM,EAAE,IAAI,IAAI,GAAG,CAAC,IAAI;YAC9B,QAAQ,EAAE,MAAM,EAAE,QAAQ,IAAI,GAAG,CAAC,QAAQ;YAC1C,QAAQ,EAAE,MAAM,EAAE,QAAQ,IAAI,GAAG,CAAC,QAAQ;YAC1C,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,GAAG,CAAC,EAAE;YACxB,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,GAAG;YAC3B,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,GAAG,CAAC,SAAS;SAC7C,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACZ,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAE3B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;QACrC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;QACrC,MAAM,MAAM,GAAG,OAAO,KAAK,YAAY,IAAI,OAAO,KAAK,YAAY,CAAC;QACpE,IAAI,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,KAAK,kBAAkB,EAAE,CAAC;YAC5D,MAAM,IAAI,KAAK,CACd,8FAA8F,kBAAkB,wKAAwK,CACxR,CAAC;QACH,CAAC;QAED,IAAI,aAA4B,CAAC;QACjC,IAAI,CAAC;YACJ,aAAa,GAAG,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAA6B,CAAC;QACvE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACd,sIAAsI,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACxL,CAAC;QACH,CAAC;QAED,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,IAAI,aAAa,CAAC,KAAK,CAAC;QACjE,IAAI,CAAC,WAAW,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACd,+HAA+H,CAC/H,CAAC;QACH,CAAC;QAED,qDAAqD;QACrD,MAAM,gBAAgB,GAA4B;YACjD,cAAc,EAAE,KAAK;YACrB,oBAAoB,EAAE,CAAC;YACvB,kBAAkB,EAAE,KAAK;YACzB,WAAW,EAAE,IAAI;SACjB,CAAC;QAEF,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACP,MAAM,IAAI,GAA4B,EAAE,GAAG,gBAAgB,EAAE,CAAC;YAC9D,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI;gBAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACnD,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI;gBAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACnD,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ;gBAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;YAC/D,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ;gBAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;YAC/D,IAAI,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,QAAQ;gBAAE,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACjE,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG;gBAAE,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YACtC,OAAO,CAAC,IAAI,CAAC,yCAAyC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACtE,CAAC,CAAC,CAAC;QAEH,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,UAAU;QACf,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5B,IAAI,CAAC;YACJ,MAAM,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACR,cAAc;QACf,CAAC;gBAAS,CAAC;YACV,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACxB,CAAC;IACF,CAAC;IAEO,SAAS,CAAC,YAAoB,EAAE,WAAmB;QAC1D,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,CAAC;IAC3G,CAAC;IAEO,aAAa,CAAC,CAAS;QAC9B,OAAO,CAAC,CAAC,OAAO,CAAC,mBAAmB,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACvF,CAAC;IAEO,aAAa;QACpB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,IAAiC;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAEhE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAC5B,iBAAiB,EACjB,CAAC,EACD,GAAG,EACH,IAAI,CAAC,IAAI,EACT,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EACpB,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,EAC9D,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,SAAS,EACd,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,EACzB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAChB,CAAC;QACF,OAAO,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,QAAQ,CACb,YAAoB,EACpB,WAAmB,EACnB,KAAa,EACb,GAAW;QAEX,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACxE,OAAO,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,YAAoB,EAAE,WAAmB;QACrD,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QACtD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,OAAO,OAAO,GAAG,CAAC,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,GAAW;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC;QAC7C,IAAI,MAAM,GAAG,GAAG,CAAC;QACjB,IAAI,MAAM,GAAG,CAAC,CAAC;QAEf,GAAG,CAAC;YACH,IAAI,GAAuB,CAAC;YAC5B,IAAI,CAAC;gBACJ,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;YACjE,CAAC;YAAC,MAAM,CAAC;gBACR,OAAO,MAAM,CAAC;YACf,CAAC;YACD,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC;YAC/B,MAAM,GAAG,UAAU,CAAC;YACpB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACxB,IAAI,CAAC;oBACJ,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,wBAAwB,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;oBAC7E,MAAM,KAAK,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC1D,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;wBAAE,MAAM,IAAI,KAAK,CAAC;gBAC3C,CAAC;gBAAC,MAAM,CAAC;oBACR,cAAc;gBACf,CAAC;YACF,CAAC;QACF,CAAC,QAAQ,MAAM,KAAK,GAAG,EAAE;QAEzB,OAAO,MAAM,CAAC;IACf,CAAC;IAEO,mBAAmB,CAAC,GAAY;QACvC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,iDAAiD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzF,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,OAAO,KAAK,WAAW,IAAI,OAAO,KAAK,cAAc,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;YACrF,MAAM,IAAI,KAAK,CAAC,qCAAqC,OAAO,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,OAAO;YACN,OAAO;YACP,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC3B,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC3B,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACzB,CAAC;IACH,CAAC;IAEO,mBAAmB,CAAC,GAAY;QACvC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAC5E,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,GAAG,KAAK,MAAM;YAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAChD,IAAI,GAAG,KAAK,YAAY;YAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACzF,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAClC,CAAC;CACD;AAED;;;;;;;;GAQG;AACH,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;CAahC,CAAC"}

package/dist/scheduling/createDebounceBackend.d.ts

@@ -1,25 +0,0 @@
-/**
- * Tier C #1 · Debounce backend factory.
- *
- * Reads `BLOK_DEBOUNCE_BACKEND` and returns the matching backend
- * instance, or `null` when the operator wants the default in-process
- * coordinator (no cross-process coordination).
- *
- * Trigger packages call this in `listen()` and pass the result to
- * `DebounceCoordinator.getInstance().setBackend(backend)`.
- */
-import type { DebounceBackend } from "./DebounceBackend";
-/**
- * Returns a configured `DebounceBackend` based on
- * `BLOK_DEBOUNCE_BACKEND`, or `null` for the default in-memory coordinator.
- *
- * Recognized values:
- * - unset / `""` / `"memory"` / `"in-process"` — null (use default in-memory)
- * - `"nats-kv"` — NATS KV backend (requires `nats` package + reachable NATS server)
- * - `"redis"` — Redis backend (requires `ioredis` package + reachable Redis server)
- *
- * Unknown values throw at startup with a clear error message — silently
- * falling back would be dangerous (operator thinks they configured
- * cross-process debounce but they didn't).
- */
-export declare function createDebounceBackend(): DebounceBackend | null;

package/dist/scheduling/createDebounceBackend.js

@@ -1,39 +0,0 @@
-/**
- * Tier C #1 · Debounce backend factory.
- *
- * Reads `BLOK_DEBOUNCE_BACKEND` and returns the matching backend
- * instance, or `null` when the operator wants the default in-process
- * coordinator (no cross-process coordination).
- *
- * Trigger packages call this in `listen()` and pass the result to
- * `DebounceCoordinator.getInstance().setBackend(backend)`.
- */
-import { NatsKvDebounceBackend } from "./NatsKvDebounceBackend";
-import { RedisDebounceBackend } from "./RedisDebounceBackend";
-/**
- * Returns a configured `DebounceBackend` based on
- * `BLOK_DEBOUNCE_BACKEND`, or `null` for the default in-memory coordinator.
- *
- * Recognized values:
- * - unset / `""` / `"memory"` / `"in-process"` — null (use default in-memory)
- * - `"nats-kv"` — NATS KV backend (requires `nats` package + reachable NATS server)
- * - `"redis"` — Redis backend (requires `ioredis` package + reachable Redis server)
- *
- * Unknown values throw at startup with a clear error message — silently
- * falling back would be dangerous (operator thinks they configured
- * cross-process debounce but they didn't).
- */
-export function createDebounceBackend() {
-    const kind = (process.env.BLOK_DEBOUNCE_BACKEND ?? "").trim().toLowerCase();
-    if (!kind || kind === "memory" || kind === "in-process")
-        return null;
-    switch (kind) {
-        case "nats-kv":
-            return new NatsKvDebounceBackend();
-        case "redis":
-            return new RedisDebounceBackend();
-        default:
-            throw new Error(`Unknown BLOK_DEBOUNCE_BACKEND='${kind}'. Expected one of: 'memory' (default), 'nats-kv', 'redis'.`);
-    }
-}
-//# sourceMappingURL=createDebounceBackend.js.map

package/dist/scheduling/createDebounceBackend.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"createDebounceBackend.js","sourceRoot":"","sources":["../../src/scheduling/createDebounceBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB;IACpC,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5E,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IAErE,QAAQ,IAAI,EAAE,CAAC;QACd,KAAK,SAAS;YACb,OAAO,IAAI,qBAAqB,EAAE,CAAC;QACpC,KAAK,OAAO;YACX,OAAO,IAAI,oBAAoB,EAAE,CAAC;QACnC;YACC,MAAM,IAAI,KAAK,CACd,kCAAkC,IAAI,6DAA6D,CACnG,CAAC;IACJ,CAAC;AACF,CAAC"}

package/dist/security/ABAC.d.ts

@@ -1,224 +0,0 @@
-/**
- * Attribute-Based Access Control (ABAC) for Blok
- *
- * Provides fine-grained, attribute-driven access control that complements RBAC:
- * - Policies evaluate attributes of subject, resource, action, and environment
- * - Supports logical operators (AND, OR, NOT) for complex conditions
- * - Supports comparison operators (equals, not_equals, in, not_in, contains, matches, gt, lt, gte, lte, between)
- * - Supports attribute-to-attribute comparison via `valueRef` (e.g., resource.owner == subject.sub)
- * - Integrates with AuthIdentity claims and RBAC roles
- * - JSON-serializable policies for persistence and external management
- *
- * @example
- * ```typescript
- * const engine = new ABACEngine();
- *
- * engine.addPolicy({
- *   id: "work-hours-only",
- *   description: "Allow workflow execution only during business hours",
- *   effect: "allow",
- *   target: {
- *     resource: "workflow",
- *     actions: ["execute"],
- *   },
- *   conditions: {
- *     all: [
- *       { attribute: "environment.hour", operator: "gte", value: 9 },
- *       { attribute: "environment.hour", operator: "lt", value: 17 },
- *       { attribute: "subject.department", operator: "equals", value: "engineering" },
- *     ],
- *   },
- * });
- *
- * const result = engine.evaluate({
- *   subject: { sub: "user-1", roles: ["developer"], department: "engineering" },
- *   resource: { type: "workflow", id: "/api/users" },
- *   action: "execute",
- *   environment: { hour: 14, ip: "10.0.0.1" },
- * });
- * ```
- */
-export type ABACOperator = "equals" | "not_equals" | "in" | "not_in" | "contains" | "not_contains" | "matches" | "gt" | "lt" | "gte" | "lte" | "between" | "exists" | "not_exists";
-export type ABACEffect = "allow" | "deny";
-/**
- * A single attribute condition that compares an attribute path against a value.
- *
- * Attribute paths use dot notation to access nested properties:
- * - `subject.department` — the subject's department attribute
- * - `resource.owner` — the resource's owner attribute
- * - `environment.ip` — the environment's IP address
- * - `environment.hour` — the current hour (0-23)
- */
-export interface ABACCondition {
-    /** Dot-separated path to the attribute (e.g., "subject.department") */
-    attribute: string;
-    /** Comparison operator */
-    operator: ABACOperator;
-    /** Static value to compare against (ignored for exists/not_exists operators) */
-    value?: unknown;
-    /** Attribute path to resolve as the comparison value (attribute-to-attribute comparison).
-     *  When set, `value` is ignored and the comparison value is resolved from the request. */
-    valueRef?: string;
-}
-/**
- * Logical grouping of conditions.
- *
- * - `all`: Every condition must be true (AND)
- * - `any`: At least one condition must be true (OR)
- * - `none`: No condition may be true (NOT / NOR)
- *
- * Groups can be nested for complex logic.
- */
-export interface ABACConditionGroup {
-    /** All conditions must be true (AND) */
-    all?: Array<ABACCondition | ABACConditionGroup>;
-    /** At least one condition must be true (OR) */
-    any?: Array<ABACCondition | ABACConditionGroup>;
-    /** No condition may be true (NOR) */
-    none?: Array<ABACCondition | ABACConditionGroup>;
-}
-/**
- * Policy target restricts which requests the policy applies to.
- */
-export interface ABACPolicyTarget {
-    /** Resource type (e.g., "workflow", "node", "*") */
-    resource?: string;
-    /** Resource ID pattern (supports * wildcards) */
-    resourcePattern?: string;
-    /** Actions this policy applies to */
-    actions?: string[];
-}
-/**
- * An ABAC policy defines conditions under which access is allowed or denied.
- */
-export interface ABACPolicy {
-    /** Unique policy identifier */
-    id: string;
-    /** Human-readable description */
-    description?: string;
-    /** Whether this policy grants or denies access */
-    effect: ABACEffect;
-    /** Target resource/action scope — if omitted, applies to all requests */
-    target?: ABACPolicyTarget;
-    /** Conditions that must be satisfied for the policy to apply */
-    conditions: ABACConditionGroup;
-    /** Priority (higher = evaluated first). Default: 0 */
-    priority?: number;
-    /** Whether the policy is active. Default: true */
-    enabled?: boolean;
-}
-/**
- * Attributes about the requesting subject (user or service).
- */
-export interface SubjectAttributes {
-    /** Unique identifier */
-    sub: string;
-    /** Assigned roles */
-    roles?: string[];
-    /** Additional attributes (department, clearance, team, etc.) */
-    [key: string]: unknown;
-}
-/**
- * Attributes about the target resource.
- */
-export interface ResourceAttributes {
-    /** Resource type (workflow, node, trigger, etc.) */
-    type: string;
-    /** Resource identifier */
-    id: string;
-    /** Additional attributes (owner, classification, sensitivity, etc.) */
-    [key: string]: unknown;
-}
-/**
- * Attributes about the environment / context.
- */
-export interface EnvironmentAttributes {
-    /** Additional attributes (ip, hour, dayOfWeek, location, etc.) */
-    [key: string]: unknown;
-}
-/**
- * A complete ABAC evaluation request context.
- */
-export interface ABACRequest {
-    subject: SubjectAttributes;
-    resource: ResourceAttributes;
-    action: string;
-    environment?: EnvironmentAttributes;
-}
-/**
- * Result of an ABAC evaluation.
- */
-export interface ABACResult {
-    /** Whether access is allowed */
-    allowed: boolean;
-    /** The policy that determined the decision (if any) */
-    matchedPolicy?: ABACPolicy;
-    /** All policies that were evaluated */
-    evaluatedPolicies: Array<{
-        policyId: string;
-        effect: ABACEffect;
-        matched: boolean;
-    }>;
-    /** Reason for the decision */
-    reason: string;
-}
-export declare class ABACEngine {
-    private policies;
-    private defaultEffect;
-    constructor(options?: {
-        defaultEffect?: ABACEffect;
-    });
-    /**
-     * Add or update a policy.
-     */
-    addPolicy(policy: ABACPolicy): void;
-    /**
-     * Remove a policy by ID.
-     */
-    removePolicy(id: string): void;
-    /**
-     * Get a policy by ID.
-     */
-    getPolicy(id: string): ABACPolicy | undefined;
-    /**
-     * Get all policies, sorted by priority (highest first).
-     */
-    getPolicies(): ABACPolicy[];
-    /**
-     * Evaluate an access request against all policies.
-     *
-     * Policy evaluation order:
-     * 1. Policies are sorted by priority (highest first)
-     * 2. Only enabled policies are considered
-     * 3. Only policies whose target matches the request are considered
-     * 4. The first matching "deny" policy short-circuits with denial
-     * 5. Otherwise, at least one matching "allow" policy is required
-     * 6. If no policy matches, the default effect applies
-     */
-    evaluate(request: ABACRequest): ABACResult;
-    /**
-     * Export all policies as JSON.
-     */
-    toJSON(): {
-        policies: ABACPolicy[];
-        defaultEffect: ABACEffect;
-    };
-    /**
-     * Load policies from JSON (replaces all existing policies).
-     */
-    fromJSON(config: {
-        policies: ABACPolicy[];
-        defaultEffect?: ABACEffect;
-    }): void;
-    private matchesTarget;
-    private evaluateConditionGroup;
-    private evaluateItem;
-    private evaluateCondition;
-    private resolveAttribute;
-    private compare;
-    private matchesPattern;
-}
-/**
- * Create a preconfigured ABAC engine with common policies.
- */
-export declare function createDefaultABAC(): ABACEngine;