@spine-event-engine/server 2.0.0-snapshot.2

package/dist/delivery/parked-delivery-obligations.js

@@ -0,0 +1,390 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+/**
+ * Tracks finite unresolved delivery obligations for one package.
+ * @internal
+ */
+export class ParkedDeliveryObligations {
+    #configured = new Map();
+    #records = new Map();
+    #shared;
+    /**
+     * Creates a table from the bounded generation and registration obligations.
+     *
+     * @param options Supplies the configured obligation domains.
+     */
+    constructor(options) {
+        for (const registration of options.registrations) {
+            for (const obligation of registration.obligations) {
+                this.#addConfigured({
+                    key: ParkedObligationValues.recordKey(ParkedObligationValues.registrationOwner(registration.token), obligation.key),
+                    owner: ParkedObligationValues.registrationOwner(registration.token),
+                    obligation: obligation.key,
+                    units: obligation.units,
+                });
+            }
+        }
+        for (const obligation of options.generation) {
+            this.#addConfigured({
+                key: ParkedObligationValues.recordKey(generationOwner, obligation.key),
+                owner: generationOwner,
+                obligation: obligation.key,
+                units: obligation.units,
+            });
+        }
+        const units = Array.from(new Set(options.generation.flatMap((obligation) => obligation.units)));
+        if (units.length === 0) {
+            throw new Error("Parked delivery obligations require a generation obligation.");
+        }
+        this.#shared = Object.freeze({
+            key: ParkedObligationValues.recordKey(sharedOwner, "shared"),
+            owner: sharedOwner,
+            obligation: "shared",
+            units: Object.freeze(units),
+        });
+    }
+    /**
+     * Records one unresolved obligation with its current failure cause.
+     *
+     * @param owner Identifies the obligation owner.
+     * @param obligation Names the configured obligation.
+     * @param units Selects the unresolved units.
+     * @param cause Captures the representative failure.
+     * @param occurrences Adds the number of observed failures.
+     */
+    park(owner, obligation, units, cause, occurrences = 1) {
+        ParkedObligationValues.requireOccurrences(occurrences);
+        const configured = this.#configuredObligation(owner, obligation, units);
+        const record = this.#record(configured, units);
+        record.occurrences = ParkedObligationValues.saturatingAdd(record.occurrences, occurrences);
+        ParkedObligationValues.recordCauses(record, cause, units, configured.units);
+    }
+    /**
+     * Records a failed fulfillment after resolving the selected units.
+     *
+     * @param owner Identifies the obligation owner.
+     * @param obligation Names the configured obligation.
+     * @param units Selects the resolved units.
+     */
+    parkFulfilledFailed(owner, obligation, units) {
+        const configured = this.#configuredObligation(owner, obligation, units);
+        this.#fulfill(configured, units);
+        this.#record(configured, units);
+    }
+    /**
+     * Records a shared unresolved obligation.
+     *
+     * @param units Selects the unresolved units.
+     * @param cause Captures the representative failure.
+     * @param occurrences Adds the number of observed failures.
+     */
+    parkShared(units, cause, occurrences = 1) {
+        ParkedObligationValues.requireOccurrences(occurrences);
+        const configured = this.#configuredObligation(sharedOwner, "shared", units);
+        const record = this.#record(configured, units);
+        record.occurrences = ParkedObligationValues.saturatingAdd(record.occurrences, occurrences);
+        ParkedObligationValues.recordCauses(record, cause, units, configured.units);
+    }
+    /**
+     * Updates one live registration's configured unit domain in stable order.
+     * @internal
+     * @param token Identifies the registration to extend.
+     * @param obligation Names the configured obligation.
+     * @param units Supplies the new units.
+     */
+    extendRegistration(token, obligation, units) {
+        this.#extendConfigured(ParkedObligationValues.registrationOwner(token), obligation, units);
+        this.#extendConfigured(generationOwner, "generation", units);
+        this.#shared = Object.freeze({
+            ...this.#shared,
+            units: Object.freeze(ParkedObligationValues.appendUnits(this.#shared.units, units)),
+        });
+    }
+    /**
+     * Returns one unreported representative cause for each selected obligation.
+     *
+     * @param selections Select the obligation units to report.
+     * @returns The representative causes that were newly reported.
+     */
+    report(selections) {
+        const selected = this.#selectedUnits(selections);
+        const causes = [];
+        for (const configured of this.#configured.values()) {
+            this.#reportRecord(configured, selected.get(configured.key), causes);
+        }
+        this.#reportRecord(this.#shared, selected.get(this.#shared.key), causes);
+        return Object.freeze(causes);
+    }
+    /**
+     * Updates selected obligation units as fulfilled.
+     *
+     * @param owner Identifies the obligation owner.
+     * @param obligation Names the configured obligation.
+     * @param units Selects the fulfilled units.
+     */
+    fulfilled(owner, obligation, units) {
+        const configured = this.#configuredObligation(owner, obligation, units);
+        this.#fulfill(configured, units);
+    }
+    /**
+     * Removes a registration and reclassifies its parked obligations.
+     *
+     * @param token Identifies the removed registration.
+     */
+    removeRegistration(token) {
+        const plan = this.#reclassificationPlan(token);
+        for (const { sourceKey } of plan) {
+            this.#records.delete(sourceKey);
+        }
+        for (const { destinations } of plan) {
+            for (const { configured, source } of destinations) {
+                this.#coalesce(configured, source);
+            }
+        }
+        for (const [key, configured] of this.#configured) {
+            if (configured.owner.kind === "registration" && configured.owner.token === token) {
+                this.#configured.delete(key);
+            }
+        }
+    }
+    /**
+     * Returns immutable snapshots of all parked obligations.
+     *
+     * @returns The current parked obligation records.
+     */
+    records() {
+        return Object.freeze(Array.from(this.#records.values(), ParkedObligationValues.snapshot));
+    }
+    #addConfigured(configured) {
+        const key = configured.key;
+        if (this.#configured.has(key) || configured.units.length === 0) {
+            throw new Error("Parked delivery obligations require unique non-empty configured obligations.");
+        }
+        this.#configured.set(key, Object.freeze({ ...configured, units: Object.freeze([...configured.units]) }));
+    }
+    #extendConfigured(owner, obligation, units) {
+        if (units.length === 0) {
+            return;
+        }
+        const key = ParkedObligationValues.recordKey(owner, obligation);
+        const existing = this.#configured.get(key);
+        if (existing === undefined) {
+            this.#addConfigured({ key, owner, obligation, units });
+            return;
+        }
+        this.#configured.set(key, Object.freeze({
+            ...existing,
+            units: Object.freeze(ParkedObligationValues.appendUnits(existing.units, units)),
+        }));
+    }
+    #configuredObligation(owner, obligation, units) {
+        if (owner.kind === "shared" &&
+            obligation === "shared" &&
+            ParkedObligationValues.isConfiguredSubset(units, this.#shared.units)) {
+            return this.#shared;
+        }
+        const configured = this.#configured.get(ParkedObligationValues.recordKey(owner, obligation));
+        if (configured === undefined ||
+            !ParkedObligationValues.isConfiguredSubset(units, configured.units)) {
+            throw new Error("Parked delivery obligation is not configured.");
+        }
+        return configured;
+    }
+    #record(configured, units) {
+        const existing = this.#records.get(configured.key);
+        if (existing !== undefined) {
+            existing.units = ParkedObligationValues.orderUnits([...existing.units, ...units], configured.units);
+            return existing;
+        }
+        const record = {
+            key: configured.key,
+            owner: configured.owner,
+            obligation: configured.obligation,
+            units: ParkedObligationValues.orderUnits(units, configured.units),
+            occurrences: 0,
+            causes: new Map(),
+            reportedSinceResolution: false,
+        };
+        this.#records.set(configured.key, record);
+        return record;
+    }
+    #fulfill(configured, units) {
+        const record = this.#records.get(configured.key);
+        if (record === undefined) {
+            return;
+        }
+        const resolved = new Set(units);
+        record.units = record.units.filter((unit) => !resolved.has(unit));
+        for (const unit of resolved) {
+            record.causes.delete(unit);
+        }
+        if (record.units.length === 0) {
+            this.#records.delete(configured.key);
+        }
+    }
+    #selectedUnits(selections) {
+        const selected = new Map();
+        for (const selection of selections) {
+            const configured = this.#configuredObligation(selection.owner, selection.obligation, selection.units);
+            const units = selected.get(configured.key) ?? new Set();
+            for (const unit of selection.units) {
+                units.add(unit);
+            }
+            selected.set(configured.key, units);
+        }
+        return selected;
+    }
+    #reportRecord(configured, selected, causes) {
+        const record = this.#records.get(configured.key);
+        if (record === undefined || selected === undefined) {
+            return;
+        }
+        const representative = ParkedObligationValues.reportableCause(record, configured.units, selected);
+        if (representative === undefined) {
+            return;
+        }
+        causes.push(representative.evidence.cause);
+        representative.evidence.reported = true;
+        record.reportedSinceResolution = true;
+    }
+    #reclassificationPlan(token) {
+        const plan = [];
+        for (const [sourceKey, source] of this.#records) {
+            if (source.owner.kind !== "registration" || source.owner.token !== token) {
+                continue;
+            }
+            plan.push({ sourceKey, destinations: this.#generationDestinations(source) });
+        }
+        return plan;
+    }
+    #generationDestinations(source) {
+        const generation = Array.from(this.#configured.values()).filter((configured) => configured.owner.kind === "generation");
+        const grouped = new Map();
+        for (const unit of source.units) {
+            const destination = generation.find((configured) => configured.units.includes(unit));
+            if (destination === undefined) {
+                throw new Error("Removed registration obligation has no configured generation destination.");
+            }
+            const units = grouped.get(destination.key) ?? [];
+            units.push(unit);
+            grouped.set(destination.key, units);
+        }
+        return generation.flatMap((configured) => {
+            const units = grouped.get(configured.key);
+            return units === undefined
+                ? []
+                : [{ configured, source: ParkedObligationValues.reclassifiedSource(source, units) }];
+        });
+    }
+    #coalesce(destination, source) {
+        const target = this.#record(destination, source.units);
+        target.occurrences = ParkedObligationValues.saturatingAdd(target.occurrences, source.occurrences);
+        target.reportedSinceResolution ||= source.reportedSinceResolution;
+        for (const [unit, evidence] of source.causes) {
+            const existing = target.causes.get(unit);
+            if (existing === undefined || (existing.reported && !evidence.reported)) {
+                target.causes.set(unit, { ...evidence });
+            }
+        }
+    }
+}
+const generationOwner = Object.freeze({ kind: "generation" });
+const sharedOwner = Object.freeze({ kind: "shared" });
+const ParkedObligationValues = Object.freeze({
+    registrationOwner(token) {
+        return Object.freeze({ kind: "registration", token });
+    },
+    recordKey(owner, obligation) {
+        return JSON.stringify([
+            owner.kind,
+            owner.kind === "registration" ? owner.token : null,
+            obligation,
+        ]);
+    },
+    isConfiguredSubset(units, configured) {
+        return units.length > 0 && units.every((unit) => configured.includes(unit));
+    },
+    orderUnits(units, configured) {
+        const selected = new Set(units);
+        return configured.filter((unit) => selected.has(unit));
+    },
+    appendUnits(existing, added) {
+        return Array.from(new Set([...existing, ...added]));
+    },
+    recordCauses(record, cause, units, configured) {
+        for (const unit of ParkedObligationValues.orderUnits(units, configured)) {
+            const existing = record.causes.get(unit);
+            if (existing === undefined || existing.reported) {
+                record.causes.set(unit, { cause, reported: false });
+            }
+        }
+    },
+    representativeCause(record, configured) {
+        for (const unit of configured) {
+            if (!record.units.includes(unit)) {
+                continue;
+            }
+            const evidence = record.causes.get(unit);
+            if (evidence !== undefined) {
+                return { unit, evidence };
+            }
+        }
+        return undefined;
+    },
+    reportableCause(record, configured, selected) {
+        for (const unit of configured) {
+            const evidence = record.causes.get(unit);
+            if (record.units.includes(unit) &&
+                selected.has(unit) &&
+                evidence !== undefined &&
+                !evidence.reported) {
+                return { unit, evidence };
+            }
+        }
+        return undefined;
+    },
+    reclassifiedSource(source, units) {
+        const selected = new Set(units);
+        return {
+            ...source,
+            units: [...units],
+            causes: new Map(Array.from(source.causes)
+                .filter(([unit]) => selected.has(unit))
+                .map(([unit, evidence]) => [unit, { ...evidence }])),
+        };
+    },
+    requireOccurrences(increment) {
+        if (!Number.isSafeInteger(increment) || increment <= 0) {
+            throw new Error("Parked delivery occurrence increment must be a positive safe integer.");
+        }
+    },
+    saturatingAdd(current, increment) {
+        return current >= Number.MAX_SAFE_INTEGER - increment
+            ? Number.MAX_SAFE_INTEGER
+            : current + increment;
+    },
+    snapshot(record) {
+        const representative = ParkedObligationValues.representativeCause(record, record.units);
+        return Object.freeze({
+            owner: record.owner,
+            obligation: record.obligation,
+            units: Object.freeze([...record.units]),
+            cause: representative?.evidence.cause,
+            hasCause: representative !== undefined,
+            occurrences: record.occurrences,
+            reportedSinceResolution: record.reportedSinceResolution,
+        });
+    },
+});
+//# sourceMappingURL=parked-delivery-obligations.js.map

package/dist/delivery/parked-delivery-obligations.js.map

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

package/dist/delivery/shard-index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Zero-based shard index with a stable shard count.
+ */
+export declare class ShardIndex {
+    /**
+     * Zero-based position of this shard.
+     */
+    readonly index: number;
+    /**
+     * Total number of shards in the same shard set.
+     */
+    readonly ofTotal: number;
+    /**
+     * Creates a shard index.
+     *
+     * @param index Identifies the zero-based shard position.
+     * @param ofTotal States the total shards in the shard set.
+     */
+    constructor(
+    /**
+     * Zero-based position of this shard.
+     */
+    index: number, 
+    /**
+     * Total number of shards in the same shard set.
+     */
+    ofTotal: number);
+    /**
+     * Creates the single local shard.
+     *
+     * @returns The only shard in a one-shard set.
+     */
+    static single(): ShardIndex;
+    /**
+     * Returns the deterministic storage key for this shard.
+     *
+     * @returns The shard position and total encoded as a storage key.
+     */
+    key(): string;
+}
+//# sourceMappingURL=shard-index.d.ts.map

package/dist/delivery/shard-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-index.d.ts","sourceRoot":"","sources":["../../src/delivery/shard-index.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,qBAAa,UAAU;IAYnB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM;IAjB1B;;;;;OAKG;;IAID;;OAEG;IACM,KAAK,EAAE,MAAM;IAEtB;;OAEG;IACM,OAAO,EAAE,MAAM;IAc1B;;;;OAIG;IACH,MAAM,CAAC,MAAM,IAAI,UAAU;IAI3B;;;;OAIG;IACH,GAAG,IAAI,MAAM;CAGd"}

package/dist/delivery/shard-index.js

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+/**
+ * Zero-based shard index with a stable shard count.
+ */
+export class ShardIndex {
+    index;
+    ofTotal;
+    // prettier-ignore
+    /**
+     * Creates a shard index.
+     *
+     * @param index Identifies the zero-based shard position.
+     * @param ofTotal States the total shards in the shard set.
+     */
+    constructor(
+    // prettier-ignore
+    /**
+     * Zero-based position of this shard.
+     */
+    index, 
+    /**
+     * Total number of shards in the same shard set.
+     */
+    ofTotal) {
+        this.index = index;
+        this.ofTotal = ofTotal;
+        if (!Number.isInteger(index) || index < 0) {
+            throw new Error("ShardIndex.index must be a non-negative integer.");
+        }
+        if (!Number.isInteger(ofTotal) || ofTotal <= 0) {
+            throw new Error("ShardIndex.ofTotal must be a positive integer.");
+        }
+        if (index >= ofTotal) {
+            throw new Error("ShardIndex.index must be smaller than ShardIndex.ofTotal.");
+        }
+        Object.freeze(this);
+    }
+    /**
+     * Creates the single local shard.
+     *
+     * @returns The only shard in a one-shard set.
+     */
+    static single() {
+        return new ShardIndex(0, 1);
+    }
+    /**
+     * Returns the deterministic storage key for this shard.
+     *
+     * @returns The shard position and total encoded as a storage key.
+     */
+    key() {
+        return `${String(this.index)}/${String(this.ofTotal)}`;
+    }
+}
+//# sourceMappingURL=shard-index.js.map

package/dist/delivery/shard-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-index.js","sourceRoot":"","sources":["../../src/delivery/shard-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,OAAO,UAAU;IAeV;IAKA;IAnBX,kBAAkB;IAElB;;;;;OAKG;IACH;IACE,kBAAkB;IAElB;;OAEG;IACM,KAAa;IAEtB;;OAEG;IACM,OAAe;QALf,UAAK,GAAL,KAAK,CAAQ;QAKb,YAAO,GAAP,OAAO,CAAQ;QAExB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACtE,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,KAAK,IAAI,OAAO,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC/E,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,GAAG;QACD,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;IACzD,CAAC;CACF"}

package/dist/delivery/sharded-work-registry.d.ts

@@ -0,0 +1,114 @@
+import { type ShardIndex as WireShardIndex, type ShardSessionRecord, type WorkerId } from "@spine-event-engine/proto/delivery";
+import { RecordSpec, type StorageContext, type StorageFactory } from "@spine-event-engine/storage";
+import { ShardIndex } from "./shard-index.js";
+/**
+ * Defines direct durable shard-session records keyed by their generated shard index.
+ */
+export declare const shardSessionRecordSpec: RecordSpec<WireShardIndex, ShardSessionRecord>;
+/**
+ * Coordinates durable exclusive ownership of delivery shards.
+ */
+export declare class ShardedWorkRegistry {
+    #private;
+    /**
+     * Identifies the renewable leased session model.
+     */
+    readonly sessionKind: "LEASED";
+    /**
+     * Opens a registry over direct shard-session storage.
+     *
+     * @param options Configures durable storage, lease duration, and clock.
+     */
+    constructor(options: ShardedWorkRegistryOptions);
+    /**
+     * Acquires a shard for one complete durable worker identity.
+     *
+     * @param shard Identifies the shard to acquire.
+     * @param worker Identifies the worker requesting ownership.
+     * @returns The live owned session, or `undefined` when another worker owns it.
+     */
+    pickUp(shard: ShardIndex, worker: WorkerId): Promise<ShardSession | undefined>;
+    /**
+     * Returns one renewed exact live shard-session snapshot.
+     *
+     * @param expected Supplies the previously observed session.
+     * @returns The renewed session, or `undefined` when ownership was lost.
+     */
+    renew(expected: ShardSession): Promise<ShardSession | undefined>;
+    /**
+     * Returns the renewed exact ownership session.
+     *
+     * @param expected Supplies the previously observed session.
+     * @returns The renewed session, or `undefined` when ownership was lost.
+     */
+    validateOwnership(expected: ShardSession): Promise<ShardSession | undefined>;
+    /**
+     * Returns whether one exact live shard-session snapshot became unowned.
+     *
+     * @param expected Supplies the session to release.
+     * @returns Whether the session is or became unowned.
+     */
+    release(expected: ShardSession): Promise<boolean>;
+    /**
+     * Returns after draining one exclusively owned shard until a full rescan is empty.
+     *
+     * @param shard Identifies the shard to drain.
+     * @param worker Identifies the worker retaining ownership.
+     * @param read Reads the next pending shard contents.
+     * @param deliver Delivers one pending value under the current session.
+     * @returns A promise that settles after release or ownership loss.
+     */
+    drainUntilEmpty<T>(shard: ShardIndex, worker: WorkerId, read: () => Promise<readonly T[]>, deliver: (value: T, session: ShardSession) => Promise<void>): Promise<void>;
+}
+/**
+ * Represents one exact durable shard ownership snapshot.
+ */
+export declare class ShardSession {
+    readonly shard: ShardIndex;
+    readonly worker: WorkerId | undefined;
+    readonly pickedUpAt: Date;
+    readonly expiresAt: Date;
+    /**
+     * Identifies the leased session model.
+     */
+    readonly kind: "LEASED";
+    /**
+     * Creates an immutable shard ownership snapshot.
+     *
+     * @param shard Identifies the owned shard.
+     * @param worker Identifies the owner, or `undefined` for an unowned row.
+     * @param pickedUpAt Records the durable pickup time.
+     * @param expiresAt Records the derived lease-expiry time.
+     */
+    constructor(shard: ShardIndex, worker: WorkerId | undefined, pickedUpAt: Date, expiresAt: Date);
+}
+/**
+ * Configures direct durable shard-session coordination.
+ */
+export interface ShardedWorkRegistryOptions {
+    /**
+     * Storage context that owns the shard-session family.
+     */
+    readonly context: StorageContext;
+    /**
+     * Factory that opens direct shard-session storage.
+     */
+    readonly storageFactory: StorageFactory;
+    /**
+     * Optional lease duration in milliseconds.
+     */
+    readonly leaseMs?: number;
+    /**
+     * Returns the current time used to derive ownership expiry.
+     *
+     * @returns The current time.
+     */
+    readonly now?: () => Date;
+}
+/**
+ * Exposes package-internal registry construction observations for integrations.
+ */
+export declare const shardedWorkRegistryAccess: Readonly<{
+    matches(registry: ShardedWorkRegistry, contextValue: StorageContext, storageFactory: StorageFactory): boolean;
+}>;
+//# sourceMappingURL=sharded-work-registry.d.ts.map

package/dist/delivery/sharded-work-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharded-work-registry.d.ts","sourceRoot":"","sources":["../../src/delivery/sharded-work-registry.ts"],"names":[],"mappings":"AAgBA,OAAO,EAIL,KAAK,UAAU,IAAI,cAAc,EACjC,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,UAAU,EAGV,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAK9C;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,UAAU,CAAC,cAAc,EAAE,kBAAkB,CAU9E,CAAC;AAEL;;GAEG;AACH,qBAAa,mBAAmB;;IAG9B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAG,QAAQ,CAAU;IAMzC;;;;OAIG;gBACS,OAAO,EAAE,0BAA0B;IAc/C;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAuBpF;;;;;OAKG;IACG,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAItE;;;;;OAKG;IACH,iBAAiB,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAI5E;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBvD;;;;;;;;OAQG;IACG,eAAe,CAAC,CAAC,EACrB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,EACjC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,GAC1D,OAAO,CAAC,IAAI,CAAC;CAiDjB;AAED;;GAEG;AACH,qBAAa,YAAY;IAiBrB,QAAQ,CAAC,KAAK,EAAE,UAAU;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS;IACrC,QAAQ,CAAC,UAAU,EAAE,IAAI;IACzB,QAAQ,CAAC,SAAS,EAAE,IAAI;IAjB1B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAElC;;;;;;;OAOG;gBAEQ,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,QAAQ,GAAG,SAAS,EAC5B,UAAU,EAAE,IAAI,EAChB,SAAS,EAAE,IAAI;CAI3B;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAGzC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAMD;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC;IAC/C,OAAO,CACL,QAAQ,EAAE,mBAAmB,EAC7B,YAAY,EAAE,cAAc,EAC5B,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC;CACZ,CAcC,CAAC"}