@jini-ai/cms 0.1.0

package/dist/identity/types.js

@@ -0,0 +1,64 @@
+/** Raised on a malformed identity input (blank username, etc.). */
+export class IdentityValidationError extends Error {
+}
+/** Raised when a referenced principal/user/role/policy is not found. */
+export class IdentityNotFoundError extends Error {
+}
+/**
+ * Raised on a unique-constraint clash (duplicate `username` in a workspace, AC-19). Also
+ * raised by `deleteRole`/`deletePolicy` (`admin-crud-service.ts`) when the target still has
+ * live references (INV-09, AC-31) — the same 409 `RESOURCE_CONFLICT` shape, a `details.field`
+ * distinguishes the two cases at the route layer (errors.spec.md §3).
+ */
+export class IdentityConflictError extends Error {
+}
+/** Raised by `login()` on bad credentials, a disabled principal, or a blank field (AC-02). */
+export class AuthInvalidCredentialsError extends Error {
+}
+/**
+ * REQ-11/INV-08 — raised by `disablePrincipal` when the target is the seeded owner
+ * principal, or when disabling would drop the workspace's active owner-`*` count to zero. Maps to
+ * 409 `OWNER_REQUIRED` (errors.spec.md §2) — a pre-existing registered code that had no HTTP
+ * emission site until this amendment gave `DISABLE_PRINCIPAL` a route.
+ */
+export class OwnerRequiredError extends Error {
+}
+/**
+ * REQ-03/INV-07 — raised by `writePolicyPermission` when the permission string is
+ * not in the registered catalog. Maps to 400 `PERMISSION_UNKNOWN` (errors.spec.md §2) — kept
+ * distinct from `IdentityValidationError` (plain `VALIDATION_ERROR`) so the route can emit the
+ * correct typed code without string-matching the message.
+ */
+export class PermissionUnknownError extends Error {
+}
+/**
+ * Raised when a grant-writing transition's caller-permission gate fails
+ * (e.g. `ASSIGN_ROLE` called by a principal without `role.manage`). Maps to
+ * 403 `FORBIDDEN` (errors.spec.md §2) — distinct from `GrantExceedsIssuerError`,
+ * which is the INV-07 clamp on the *grant's contents*, not the base gate.
+ */
+export class IdentityForbiddenError extends Error {
+    permission;
+    reason;
+    constructor(message, permission, reason) {
+        super(message);
+        this.permission = permission;
+        this.reason = reason;
+    }
+}
+/**
+ * Raised when a grant-writing transition (`ASSIGN_ROLE`, `ATTACH_POLICY`, and
+ * future `ISSUE_API_KEY`/`WRITE_POLICY_PERMISSION`) would confer a permission
+ * the caller does not itself hold unconstrained (INV-07 grant-authority
+ * clamp, feature.spec.md). Maps to 403 `GRANT_EXCEEDS_ISSUER`
+ * (errors.spec.md §2/§3) — `offendingPermissions` is the exact `details`
+ * payload shape that error code specifies.
+ */
+export class GrantExceedsIssuerError extends Error {
+    offendingPermissions;
+    constructor(message, offendingPermissions) {
+        super(message);
+        this.offendingPermissions = offendingPermissions;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/identity/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/identity/types.ts"],"names":[],"mappings":"AA6IA,mEAAmE;AACnE,MAAM,OAAO,uBAAwB,SAAQ,KAAK;CAAG;AACrD,wEAAwE;AACxE,MAAM,OAAO,qBAAsB,SAAQ,KAAK;CAAG;AACnD;;;;;GAKG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;CAAG;AACnD,8FAA8F;AAC9F,MAAM,OAAO,2BAA4B,SAAQ,KAAK;CAAG;AAEzD;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;CAAG;AAEhD;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;CAAG;AAEpD;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACtC,UAAU,CAAS;IACnB,MAAM,CAAS;IAExB,YAAY,OAAe,EAAE,UAAkB,EAAE,MAAc;QAC7D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACvC,oBAAoB,CAAW;IAExC,YAAY,OAAe,EAAE,oBAA8B;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,oBAAoB,GAAG,oBAAoB,CAAC;IACnD,CAAC;CACF"}

package/dist/identity/username.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file Username normalization (behavior.spec §5.1).
+ *
+ * A `users` row is a duplicate within a workspace iff its `username` equals an
+ * existing user's after case-insensitive comparison and Unicode NFC
+ * normalization. Normalizing once at every write/lookup site (seed, login,
+ * future CREATE_USER) makes that comparison a direct equality check rather
+ * than a repeated ad hoc string transform.
+ */
+/** NFC-normalize, trim, and lowercase a username for storage/lookup. */
+export declare function normalizeUsername(raw: string): string;
+//# sourceMappingURL=username.d.ts.map

package/dist/identity/username.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"username.d.ts","sourceRoot":"","sources":["../../src/identity/username.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/identity/username.js

@@ -0,0 +1,14 @@
+/**
+ * @file Username normalization (behavior.spec §5.1).
+ *
+ * A `users` row is a duplicate within a workspace iff its `username` equals an
+ * existing user's after case-insensitive comparison and Unicode NFC
+ * normalization. Normalizing once at every write/lookup site (seed, login,
+ * future CREATE_USER) makes that comparison a direct equality check rather
+ * than a repeated ad hoc string transform.
+ */
+/** NFC-normalize, trim, and lowercase a username for storage/lookup. */
+export function normalizeUsername(raw) {
+    return raw.normalize("NFC").trim().toLowerCase();
+}
+//# sourceMappingURL=username.js.map

package/dist/identity/username.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"username.js","sourceRoot":"","sources":["../../src/identity/username.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,wEAAwE;AACxE,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACnD,CAAC"}

package/dist/media/agent-tools.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @file The Media agent-tool catalog — this domain's instance of the per-domain
+ * `agent-tools.ts` convention Forms/Identity already use.
+ *
+ * Purpose:
+ * A static, in-process catalog describing every agent-callable tool this domain exposes and the
+ * permission each carries. Every entry maps 1:1 onto a real exported function of
+ * `media/media-service.ts` — this catalog never names an operation the domain cannot perform.
+ *
+ * Deliberate absences (the point of a catalog, not an oversight):
+ * - There is NO `media_purge_asset`. `purgeMedia` is a HARD delete: it removes the `MediaRecord`
+ *   row permanently and triggers the blob-GC tombstone pass (`tombstoneBlobIfUnreferenced`,
+ *   `blob-gc.ts`) that can eventually reclaim the underlying bytes. It is gated behind
+ *   `media.delete.force` — a separate, narrower permission a human admin UI itself treats as a
+ *   distinct escalation tier from ordinary `media.delete` (mirrors `admin.menus.delete` vs
+ *   `admin.menus.delete.force`). An assistant is reachable by prompt injection through ordinary
+ *   operator content (a comment, a form submission) in a way a human clicking the admin "purge"
+ *   button is not, so an irreversible, storage-reclaiming delete is left human-UI-only — the same
+ *   discipline `identity/agent-tools.ts` applies to `resetUserPassword`.
+ * - There is NO named-transform-registry tool (`registerTransform`, `media/transform-registry.ts`).
+ *   No admin HTTP route needs to expose it at all — it is a core-declared, boot-time/operational
+ *   concept, not a human admin-UI operation. Wrapping it here would invent agent capability beyond
+ *   what a host's admin surface itself exposes, which this catalog's own discipline forbids.
+ *
+ * How it relates to a host:
+ * A host's tool-registration layer maps these entries into `ToolRegistration`s (see
+ * `tool-registrations.ts`). Unlike Forms/Identity, `media-service.ts`'s functions perform NO
+ * internal `authorize()` call of their own (confirmed: none of `UploadMediaDeps`/
+ * `UpdateMediaMetadataDeps`/`TrashMediaDeps` carry an `authorize` field) — a host's admin HTTP
+ * routes check authorization inline, before calling the service function. `tool-registrations.ts`
+ * therefore performs that SAME inline authorize check itself (the identical permission string and
+ * `entityType: "media"` a host route would use) rather than relying on a domain-layer gate that
+ * does not exist for this library — a disclosed, deliberate divergence from the Forms/Identity/
+ * content-types pass-through-`ToolPolicy` reasoning, not an oversight.
+ *
+ * Architectural role:
+ * `media` domain declaration. Imports only the constants its own domain already enforces
+ * (`DEFAULT_MAX_UPLOAD_BYTES`/`DEFAULT_ALLOWED_MIME_TYPES` from `media-service.ts`), so the
+ * published JSON Schemas cannot drift from the validators.
+ */
+export type AgentToolSideEffect = "none" | "mutates-durable-state" | "mints-token";
+export type AgentToolActorClassRule = "confirmer-must-equal-own-delegatedBy" | "user-only" | "none";
+export interface AgentToolDefinition {
+    name: string;
+    description: string;
+    sideEffects: AgentToolSideEffect;
+    authorization: {
+        permission: string;
+    };
+    actorClassRule?: AgentToolActorClassRule;
+    /**
+     * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
+     * (a host's tool-registration layer refuses to wire any tool lacking one).
+     */
+    inputSchema?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The Media domain's fixed agent-tool catalog — the 4 operations a host's admin HTTP surface
+ * exposes that are safe to wrap, out of its 5 total (see file header for why `purge` is excluded).
+ *
+ * Ordered read-first, matching `identity/agent-tools.ts`'s convention: a model needs a `mediaId`
+ * before it can update or trash an asset, and `media_list_assets` is the only way to learn one for
+ * an existing asset (there is no dedicated get-by-id admin route to wrap instead).
+ */
+export declare const mediaAgentToolCatalog: AgentToolDefinition[];
+//# sourceMappingURL=agent-tools.d.ts.map

package/dist/media/agent-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tools.d.ts","sourceRoot":"","sources":["../../src/media/agent-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,uBAAuB,GAAG,aAAa,CAAC;AAEnF,MAAM,MAAM,uBAAuB,GAAG,sCAAsC,GAAG,WAAW,GAAG,MAAM,CAAC;AAEpG,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,mBAAmB,CAAC;IACjC,aAAa,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,cAAc,CAAC,EAAE,uBAAuB,CAAC;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACjD;AAOD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAAmB,EAgFtD,CAAC"}

package/dist/media/agent-tools.js

@@ -0,0 +1,131 @@
+/**
+ * @file The Media agent-tool catalog — this domain's instance of the per-domain
+ * `agent-tools.ts` convention Forms/Identity already use.
+ *
+ * Purpose:
+ * A static, in-process catalog describing every agent-callable tool this domain exposes and the
+ * permission each carries. Every entry maps 1:1 onto a real exported function of
+ * `media/media-service.ts` — this catalog never names an operation the domain cannot perform.
+ *
+ * Deliberate absences (the point of a catalog, not an oversight):
+ * - There is NO `media_purge_asset`. `purgeMedia` is a HARD delete: it removes the `MediaRecord`
+ *   row permanently and triggers the blob-GC tombstone pass (`tombstoneBlobIfUnreferenced`,
+ *   `blob-gc.ts`) that can eventually reclaim the underlying bytes. It is gated behind
+ *   `media.delete.force` — a separate, narrower permission a human admin UI itself treats as a
+ *   distinct escalation tier from ordinary `media.delete` (mirrors `admin.menus.delete` vs
+ *   `admin.menus.delete.force`). An assistant is reachable by prompt injection through ordinary
+ *   operator content (a comment, a form submission) in a way a human clicking the admin "purge"
+ *   button is not, so an irreversible, storage-reclaiming delete is left human-UI-only — the same
+ *   discipline `identity/agent-tools.ts` applies to `resetUserPassword`.
+ * - There is NO named-transform-registry tool (`registerTransform`, `media/transform-registry.ts`).
+ *   No admin HTTP route needs to expose it at all — it is a core-declared, boot-time/operational
+ *   concept, not a human admin-UI operation. Wrapping it here would invent agent capability beyond
+ *   what a host's admin surface itself exposes, which this catalog's own discipline forbids.
+ *
+ * How it relates to a host:
+ * A host's tool-registration layer maps these entries into `ToolRegistration`s (see
+ * `tool-registrations.ts`). Unlike Forms/Identity, `media-service.ts`'s functions perform NO
+ * internal `authorize()` call of their own (confirmed: none of `UploadMediaDeps`/
+ * `UpdateMediaMetadataDeps`/`TrashMediaDeps` carry an `authorize` field) — a host's admin HTTP
+ * routes check authorization inline, before calling the service function. `tool-registrations.ts`
+ * therefore performs that SAME inline authorize check itself (the identical permission string and
+ * `entityType: "media"` a host route would use) rather than relying on a domain-layer gate that
+ * does not exist for this library — a disclosed, deliberate divergence from the Forms/Identity/
+ * content-types pass-through-`ToolPolicy` reasoning, not an oversight.
+ *
+ * Architectural role:
+ * `media` domain declaration. Imports only the constants its own domain already enforces
+ * (`DEFAULT_MAX_UPLOAD_BYTES`/`DEFAULT_ALLOWED_MIME_TYPES` from `media-service.ts`), so the
+ * published JSON Schemas cannot drift from the validators.
+ */
+import { DEFAULT_ALLOWED_MIME_TYPES, DEFAULT_MAX_UPLOAD_BYTES } from "./media-service.js";
+const MEDIA_ID_SCHEMA = {
+    type: "string",
+    description: "The media asset's id, as returned by media_upload_asset or media_list_assets.",
+};
+/**
+ * The Media domain's fixed agent-tool catalog — the 4 operations a host's admin HTTP surface
+ * exposes that are safe to wrap, out of its 5 total (see file header for why `purge` is excluded).
+ *
+ * Ordered read-first, matching `identity/agent-tools.ts`'s convention: a model needs a `mediaId`
+ * before it can update or trash an asset, and `media_list_assets` is the only way to learn one for
+ * an existing asset (there is no dedicated get-by-id admin route to wrap instead).
+ */
+export const mediaAgentToolCatalog = [
+    {
+        name: "media_list_assets",
+        description: "Lists every media asset in the workspace (all statuses — active and trashed), with id, title, alt, caption, credit, sha256, and status. Read-only. Call this to find a mediaId before updating or trashing an asset.",
+        sideEffects: "none",
+        authorization: { permission: "media.read" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: [],
+            properties: {},
+        },
+    },
+    {
+        name: "media_upload_asset",
+        description: `Uploads a new media asset from base64-encoded bytes. Rejects a content type outside the allowed set ` +
+            `(${[...DEFAULT_ALLOWED_MIME_TYPES].join(", ")} — SVG is never accepted, even here: it requires a sanitizer ` +
+            `this build does not have) or a file over ${DEFAULT_MAX_UPLOAD_BYTES} bytes. Uploading the same bytes twice ` +
+            `always creates two separate library entries (the underlying blob is deduplicated, but each upload is its own asset).`,
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "media.upload" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["filename", "contentType", "dataBase64"],
+            properties: {
+                filename: { type: "string", minLength: 1, description: "Original filename. Its extension-stripped stem becomes the asset's initial title." },
+                contentType: {
+                    type: "string",
+                    enum: [...DEFAULT_ALLOWED_MIME_TYPES],
+                    description: "The exact MIME type of the uploaded bytes. Only this fixed set is accepted.",
+                },
+                dataBase64: {
+                    type: "string",
+                    minLength: 1,
+                    description: `The file's bytes, base64-encoded. Decoded size must be over 0 and at most ${DEFAULT_MAX_UPLOAD_BYTES} bytes.`,
+                },
+                alt: { type: "string", description: "Optional accessibility alt text." },
+                caption: { type: "string", description: "Optional display caption." },
+                credit: { type: "string", description: "Optional attribution/credit line." },
+            },
+        },
+    },
+    {
+        name: "media_update_metadata",
+        description: "Updates a media asset's editorial metadata (title/alt/caption/credit only). The asset's underlying bytes " +
+            "(sha256) are write-once and cannot be changed by this or any tool — to replace the file itself, upload a new asset.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "media.update" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["mediaId"],
+            properties: {
+                mediaId: MEDIA_ID_SCHEMA,
+                title: { type: "string", description: "New display title. Omit to leave unchanged; an empty/whitespace value is ignored (the existing title is kept)." },
+                alt: { type: "string", description: "New alt text. Omit to leave unchanged." },
+                caption: { type: "string", description: "New caption. Omit to leave unchanged." },
+                credit: { type: "string", description: "New credit line. Omit to leave unchanged." },
+            },
+        },
+    },
+    {
+        name: "media_trash_asset",
+        description: "Soft-deletes (trashes) a media asset — the first, reversible-in-principle step of the deletion ladder. " +
+            "Idempotent: trashing an already-trashed asset is a no-op. This is the ONLY delete-adjacent tool in this " +
+            "catalog; there is no purge/force-delete tool (see this file's header for why).",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "media.delete" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["mediaId"],
+            properties: { mediaId: MEDIA_ID_SCHEMA },
+        },
+    },
+];
+//# sourceMappingURL=agent-tools.js.map

package/dist/media/agent-tools.js.map

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

package/dist/media/blob-gc-lock.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file In-process, per-sha256 mutex for the blob-GC protocol
+ * (INV-1's "Serialization" clause).
+ *
+ * Purpose:
+ * The real protocol serializes every `asset_blobs` state transition
+ * under `BEGIN IMMEDIATE` (SQLite) / `SELECT … FOR UPDATE` (Postgres) so a
+ * dedup "skip write" decision and a concurrent GC delete can never observe
+ * inconsistent state. This library's media persistence is in-memory only (see
+ * `repo.memory.ts` file headers), so there is no database transaction to
+ * borrow. JS is single-threaded, but `async` functions still interleave at
+ * `await` points — that is exactly where the race the original design describes would
+ * happen: an uploader's dedup lookup and a GC delete-pass's row removal can
+ * both be mid-flight on the same sha256 at the same time. `withSha256Lock`
+ * closes that race for a single process by chaining critical sections keyed
+ * by sha256, so only one runs at a time per hash (different hashes still run
+ * fully concurrently).
+ *
+ * This is a real, if narrower, substitute for `BEGIN IMMEDIATE` — not a
+ * decorative comment. See `blob-gc.ts`'s file header for what this does NOT
+ * cover (cross-process safety, which needs a real DB transaction — a host's
+ * own SQLite adapter would supply that).
+ */
+/**
+ * Runs `criticalSection` exclusively with respect to any other call
+ * currently queued or running for the same `key` — calls for the same key
+ * are strictly ordered (FIFO); calls for different keys run fully
+ * concurrently. A rejection in one critical section does not poison the
+ * lock for later callers on the same key (each waits for its predecessor to
+ * *settle*, not to succeed).
+ *
+ * @complexity O(1) scheduling overhead per call; total wait time is bounded
+ * by the number of other calls currently queued for the same key.
+ * @overallScore 100
+ */
+export declare function withSha256Lock<T>(key: string, criticalSection: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=blob-gc-lock.d.ts.map

package/dist/media/blob-gc-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-gc-lock.d.ts","sourceRoot":"","sources":["../../src/media/blob-gc-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAUH;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAc5F"}

package/dist/media/blob-gc-lock.js

@@ -0,0 +1,55 @@
+/**
+ * @file In-process, per-sha256 mutex for the blob-GC protocol
+ * (INV-1's "Serialization" clause).
+ *
+ * Purpose:
+ * The real protocol serializes every `asset_blobs` state transition
+ * under `BEGIN IMMEDIATE` (SQLite) / `SELECT … FOR UPDATE` (Postgres) so a
+ * dedup "skip write" decision and a concurrent GC delete can never observe
+ * inconsistent state. This library's media persistence is in-memory only (see
+ * `repo.memory.ts` file headers), so there is no database transaction to
+ * borrow. JS is single-threaded, but `async` functions still interleave at
+ * `await` points — that is exactly where the race the original design describes would
+ * happen: an uploader's dedup lookup and a GC delete-pass's row removal can
+ * both be mid-flight on the same sha256 at the same time. `withSha256Lock`
+ * closes that race for a single process by chaining critical sections keyed
+ * by sha256, so only one runs at a time per hash (different hashes still run
+ * fully concurrently).
+ *
+ * This is a real, if narrower, substitute for `BEGIN IMMEDIATE` — not a
+ * decorative comment. See `blob-gc.ts`'s file header for what this does NOT
+ * cover (cross-process safety, which needs a real DB transaction — a host's
+ * own SQLite adapter would supply that).
+ */
+/**
+ * Tracks the tail of the promise chain for each in-flight/queued key. An
+ * entry is removed once its own critical section is the last one queued and
+ * has settled, so the map stays bounded by the number of sha256 values with
+ * work currently in flight — not by the number ever seen.
+ */
+const lockTails = new Map();
+/**
+ * Runs `criticalSection` exclusively with respect to any other call
+ * currently queued or running for the same `key` — calls for the same key
+ * are strictly ordered (FIFO); calls for different keys run fully
+ * concurrently. A rejection in one critical section does not poison the
+ * lock for later callers on the same key (each waits for its predecessor to
+ * *settle*, not to succeed).
+ *
+ * @complexity O(1) scheduling overhead per call; total wait time is bounded
+ * by the number of other calls currently queued for the same key.
+ * @overallScore 100
+ */
+export function withSha256Lock(key, criticalSection) {
+    const priorTail = lockTails.get(key) ?? Promise.resolve();
+    const run = priorTail.then(criticalSection, criticalSection);
+    const settledTail = run.then(() => undefined, () => undefined);
+    lockTails.set(key, settledTail);
+    void settledTail.then(() => {
+        if (lockTails.get(key) === settledTail) {
+            lockTails.delete(key);
+        }
+    });
+    return run;
+}
+//# sourceMappingURL=blob-gc-lock.js.map

package/dist/media/blob-gc-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-gc-lock.js","sourceRoot":"","sources":["../../src/media/blob-gc-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;GAKG;AACH,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAI,GAAW,EAAE,eAAiC;IAC9E,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1D,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;IAC7D,MAAM,WAAW,GAAkB,GAAG,CAAC,IAAI,CACzC,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;IACF,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAChC,KAAK,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE;QACzB,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,WAAW,EAAE,CAAC;YACvC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC"}