@relkit/providers-local 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rel-kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @relkit/providers-local
+
+Local generations own `.relkit/state/buckets` and `.relkit/state/cache` (or the
+configured state root). Bucket objects and cache snapshots use atomic commits;
+malformed records are moved into a provider-owned `.relkit-quarantine` directory
+and do not prevent the rest of the generation from starting.
+
+The local cache remains bounded and generation-local. Direct construction
+without `stateRoot` is memory-only; generation startup supplies a profile root,
+enables restart recovery, and reports `persistence: "restart-recovery"`.
+Canonical cache keys, deterministic clock expiry, LRU bounds, and the
+metadata-only `onSnapshot` hook remain unchanged. Provider objects expose typed
+bucket/cache operations only; application code does not receive file readers.
+
+Durable job queue entries retain validated idempotency keys for their configured
+retention. A duplicate enqueue returns the retained instance and acceptance
+metadata; delivery remains at-least-once after the record expires or an
+acknowledgement gap.
+
+Ephemeral event delivery is memory-only and has no restart recovery. Each
+trigger admits at most 100 simultaneous deliveries by default; the router can
+configure the capacity, drops newest overflow, and reports the capacity/drop
+policy instead of creating a hidden backlog or recovery claim.
+
+Durable event delivery reuses the job store/queue/retry seams for one trigger
+ledger. Accepted envelopes are available only after durable append, handler
+success is acknowledged through a completed transition, expired leases recover
+after restart, and retries become delayed or dead-lettered with safe failure
+metadata. Delivery is at-least-once, exactly-once is false, and per-key
+ordering is explicitly unsupported.
+
+The local event admin contract is versioned and inspector-safe: queries expose
+event contracts, selector expansions, publication metadata, delivery state,
+dead letters, and honest capability flags without payload projection. Only a
+validated local dead-letter retry is mutating; it is disabled in production and
+records an audit action.
+
+Agent tests use the `ai/test` `MockLanguageModelV3` surface with a finite script
+of validated tool-call, final, error, or cancelled turns. Its recorded calls
+make merge-blocking tests deterministic without model network calls.

package/dist/buckets/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./keys.js";
+export * from "./pagination.js";
+export * from "./provider.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/buckets/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/buckets/index.js

@@ -0,0 +1,5 @@
+export * from "./keys.js";
+export * from "./pagination.js";
+export * from "./provider.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/buckets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/buckets/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/buckets/keys.d.ts

@@ -0,0 +1,7 @@
+/** Validates an object key without normalizing away an attempted escape. */
+export declare function normalizeBucketKey(value: unknown): string;
+/** Validates a list prefix while allowing the conventional trailing slash. */
+export declare function normalizeBucketPrefix(value: unknown): string;
+export declare function encodeBucketKey(key: string): string;
+export declare function assertContainedPath(root: string, candidate: string): void;
+//# sourceMappingURL=keys.d.ts.map

package/dist/buckets/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/buckets/keys.ts"],"names":[],"mappings":"AAMA,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAmBzD;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAwB5D;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAGzE"}

package/dist/buckets/keys.js

@@ -0,0 +1,60 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { LOCAL_BUCKET_RESERVED_PREFIXES, LocalBucketKeyError } from "./types.js";
+const WINDOWS_DRIVE = /^[A-Za-z]:/;
+const MAX_KEY_BYTES = 4_096;
+/** Validates an object key without normalizing away an attempted escape. */
+export function normalizeBucketKey(value) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new LocalBucketKeyError();
+    if (value.includes("\0") ||
+        value.includes("\\") ||
+        isAbsolute(value) ||
+        WINDOWS_DRIVE.test(value)) {
+        throw new LocalBucketKeyError();
+    }
+    if (new TextEncoder().encode(value).byteLength > MAX_KEY_BYTES) {
+        throw new LocalBucketKeyError();
+    }
+    const segments = value.split("/");
+    if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+        throw new LocalBucketKeyError();
+    }
+    if (isReserved(segments[0]))
+        throw new LocalBucketKeyError();
+    return value;
+}
+/** Validates a list prefix while allowing the conventional trailing slash. */
+export function normalizeBucketPrefix(value) {
+    if (value === undefined || value === "")
+        return "";
+    if (typeof value !== "string")
+        throw new LocalBucketKeyError();
+    if (value.includes("\0") ||
+        value.includes("\\") ||
+        isAbsolute(value) ||
+        WINDOWS_DRIVE.test(value)) {
+        throw new LocalBucketKeyError();
+    }
+    const segments = value.split("/");
+    if (segments.some((segment, index) => (segment.length === 0 && index !== segments.length - 1) ||
+        segment === "." ||
+        segment === "..")) {
+        throw new LocalBucketKeyError();
+    }
+    if (isReserved(segments[0]))
+        throw new LocalBucketKeyError();
+    return value;
+}
+export function encodeBucketKey(key) {
+    return Buffer.from(key, "utf8").toString("base64url");
+}
+export function assertContainedPath(root, candidate) {
+    const path = relative(resolve(root), resolve(candidate));
+    if (path === "" || path.startsWith("..") || isAbsolute(path))
+        throw new LocalBucketKeyError();
+}
+function isReserved(segment) {
+    return (segment !== undefined &&
+        LOCAL_BUCKET_RESERVED_PREFIXES.some((prefix) => segment.startsWith(prefix)));
+}
+//# sourceMappingURL=keys.js.map

package/dist/buckets/keys.js.map

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

package/dist/buckets/operations.d.ts

@@ -0,0 +1,11 @@
+import { type BucketOperationContext, type BucketPutOptions } from "@relkit/buckets";
+import type { LocalBucketStorage } from "./storage.js";
+import { type LocalBucketObjectMetadata, type LocalBucketPolicy } from "./types.js";
+export declare function putObject(storage: LocalBucketStorage, policy: Readonly<LocalBucketPolicy>, key: string, bytes: Uint8Array, options: BucketPutOptions | undefined, context: BucketOperationContext | undefined, open: () => void): Promise<void>;
+export declare function getObject(storage: LocalBucketStorage, key: string, context: BucketOperationContext | undefined, open: () => void): Promise<Uint8Array | undefined>;
+export declare function headObject(storage: LocalBucketStorage, key: string, context: BucketOperationContext | undefined, open: () => void): Promise<LocalBucketObjectMetadata | undefined>;
+export declare function deleteObject(storage: LocalBucketStorage, key: string, context: BucketOperationContext | undefined, open: () => void): Promise<void>;
+export declare function existsObject(storage: LocalBucketStorage, key: string, context: BucketOperationContext | undefined, open: () => void): Promise<boolean>;
+export declare function listKeys(storage: LocalBucketStorage, prefix: string): Promise<string[]>;
+export declare function assertActive(context?: BucketOperationContext): void;
+//# sourceMappingURL=operations.d.ts.map

package/dist/buckets/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/buckets/operations.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AAEpB,wBAAsB,SAAS,CAC7B,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,QAAQ,CAAC,iBAAiB,CAAC,EACnC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,OAAO,EAAE,sBAAsB,GAAG,SAAS,EAC3C,IAAI,EAAE,MAAM,IAAI,GACf,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED,wBAAsB,SAAS,CAC7B,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,sBAAsB,GAAG,SAAS,EAC3C,IAAI,EAAE,MAAM,IAAI,GACf,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAGjC;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,sBAAsB,GAAG,SAAS,EAC3C,IAAI,EAAE,MAAM,IAAI,GACf,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAWhD;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,sBAAsB,GAAG,SAAS,EAC3C,IAAI,EAAE,MAAM,IAAI,GACf,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,sBAAsB,GAAG,SAAS,EAC3C,IAAI,EAAE,MAAM,IAAI,GACf,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAsB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAS7F;AAED,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAKnE"}

package/dist/buckets/operations.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { BucketOperationCancelledError, BucketOperationTimeoutError, } from "@relkit/buckets";
+import { normalizeBucketKey } from "./keys.js";
+import { validatePut } from "./policy.js";
+import { LocalBucketStateError, } from "./types.js";
+export async function putObject(storage, policy, key, bytes, options, context, open) {
+    open();
+    const normalizedKey = normalizeBucketKey(key);
+    assertActive(context);
+    if (!(bytes instanceof Uint8Array))
+        throw new TypeError("Bucket bytes must be a Uint8Array");
+    const copy = new Uint8Array(bytes);
+    const prepared = validatePut(copy, options, policy);
+    const contentHash = hash(copy);
+    await storage.write({
+        version: 1,
+        key: normalizedKey,
+        size: copy.byteLength,
+        contentHash,
+        etag: contentHash,
+        ...prepared,
+        data: Buffer.from(copy).toString("base64"),
+    });
+}
+export async function getObject(storage, key, context, open) {
+    const object = await loadObject(storage, key, context, open);
+    return object === undefined ? undefined : decode(object);
+}
+export async function headObject(storage, key, context, open) {
+    const object = await loadObject(storage, key, context, open);
+    if (object === undefined)
+        return undefined;
+    decode(object);
+    return Object.freeze({
+        etag: object.etag,
+        contentHash: object.contentHash,
+        size: object.size,
+        ...(object.contentType === undefined ? {} : { contentType: object.contentType }),
+        ...(Object.keys(object.metadata).length === 0 ? {} : { metadata: object.metadata }),
+    });
+}
+export async function deleteObject(storage, key, context, open) {
+    open();
+    const normalizedKey = normalizeBucketKey(key);
+    assertActive(context);
+    await storage.remove(normalizedKey);
+}
+export async function existsObject(storage, key, context, open) {
+    return (await headObject(storage, key, context, open)) !== undefined;
+}
+export async function listKeys(storage, prefix) {
+    const objects = await storage.list();
+    return objects
+        .filter((object) => object.key.startsWith(prefix))
+        .map((object) => {
+        decode(object);
+        return object.key;
+    })
+        .sort((left, right) => left.localeCompare(right));
+}
+export function assertActive(context) {
+    if (context?.signal.aborted)
+        throw new BucketOperationCancelledError();
+    if (context?.deadlineMs !== undefined && context.deadlineMs <= Date.now()) {
+        throw new BucketOperationTimeoutError();
+    }
+}
+async function loadObject(storage, key, context, open) {
+    open();
+    const normalizedKey = normalizeBucketKey(key);
+    assertActive(context);
+    const object = await storage.read(normalizedKey);
+    if (object !== undefined)
+        decode(object);
+    return object;
+}
+function decode(object) {
+    const bytes = new Uint8Array(Buffer.from(object.data, "base64"));
+    if (bytes.byteLength !== object.size ||
+        hash(bytes) !== object.contentHash ||
+        object.etag !== object.contentHash) {
+        throw new LocalBucketStateError("Bucket object integrity check failed");
+    }
+    return bytes;
+}
+function hash(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+//# sourceMappingURL=operations.js.map

package/dist/buckets/operations.js.map

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

package/dist/buckets/pagination.d.ts

@@ -0,0 +1,5 @@
+import { type LocalBucketListPage, type LocalBucketListOptions } from "./types.js";
+export declare const DEFAULT_BUCKET_PAGE_SIZE = 100;
+export declare const MAX_BUCKET_PAGE_SIZE = 1000;
+export declare function paginateKeys(keys: readonly string[], prefix: string, options: LocalBucketListOptions | undefined): LocalBucketListPage;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/buckets/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/buckets/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC5B,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,sBAAsB,GAAG,SAAS,GAC1C,mBAAmB,CAYrB"}

package/dist/buckets/pagination.js

@@ -0,0 +1,34 @@
+import { LocalBucketPaginationError, } from "./types.js";
+export const DEFAULT_BUCKET_PAGE_SIZE = 100;
+export const MAX_BUCKET_PAGE_SIZE = 1_000;
+export function paginateKeys(keys, prefix, options) {
+    const limit = options?.limit ?? DEFAULT_BUCKET_PAGE_SIZE;
+    if (!Number.isSafeInteger(limit) || limit <= 0 || limit > MAX_BUCKET_PAGE_SIZE) {
+        throw new LocalBucketPaginationError();
+    }
+    const start = options?.cursor === undefined ? 0 : decodeCursor(options.cursor, prefix);
+    const items = keys.slice(start, start + limit);
+    const nextIndex = start + items.length;
+    return Object.freeze({
+        items: Object.freeze(items),
+        ...(nextIndex < keys.length ? { nextCursor: encodeCursor(prefix, nextIndex) } : {}),
+    });
+}
+function encodeCursor(prefix, index) {
+    return Buffer.from(JSON.stringify({ prefix, index }), "utf8").toString("base64url");
+}
+function decodeCursor(cursor, prefix) {
+    try {
+        const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (value.prefix !== prefix ||
+            !Number.isSafeInteger(value.index) ||
+            value.index < 0) {
+            throw new Error();
+        }
+        return value.index;
+    }
+    catch {
+        throw new LocalBucketPaginationError();
+    }
+}
+//# sourceMappingURL=pagination.js.map

package/dist/buckets/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/buckets/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,GAG3B,MAAM,YAAY,CAAC;AAEpB,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAC5C,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAE1C,MAAM,UAAU,YAAY,CAC1B,IAAuB,EACvB,MAAc,EACd,OAA2C;IAE3C,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,wBAAwB,CAAC;IACzD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,oBAAoB,EAAE,CAAC;QAC/E,MAAM,IAAI,0BAA0B,EAAE,CAAC;IACzC,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IACvC,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;QAC3B,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpF,CAAC,CAAC;AACL,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,KAAa;IACjD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,MAAc;IAClD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAGzE,CAAC;QACF,IACE,KAAK,CAAC,MAAM,KAAK,MAAM;YACvB,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC;YACjC,KAAK,CAAC,KAAgB,GAAG,CAAC,EAC3B,CAAC;YACD,MAAM,IAAI,KAAK,EAAE,CAAC;QACpB,CAAC;QACD,OAAO,KAAK,CAAC,KAAe,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,0BAA0B,EAAE,CAAC;IACzC,CAAC;AACH,CAAC"}

package/dist/buckets/policy.d.ts

@@ -0,0 +1,8 @@
+import type { BucketPutOptions } from "@relkit/buckets";
+import { type LocalBucketPolicy, type LocalBucketProviderOptions } from "./types.js";
+export declare function normalizePolicy(options: LocalBucketProviderOptions): Readonly<LocalBucketPolicy>;
+export declare function validatePut(bytes: Uint8Array, options: BucketPutOptions | undefined, policy: Readonly<LocalBucketPolicy>): {
+    readonly contentType?: string;
+    readonly metadata: Readonly<Record<string, string>>;
+};
+//# sourceMappingURL=policy.d.ts.map

package/dist/buckets/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/buckets/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAChC,MAAM,YAAY,CAAC;AAIpB,wBAAgB,eAAe,CAAC,OAAO,EAAE,0BAA0B,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAgBhG;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,MAAM,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GAClC;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,CAgBxF"}

package/dist/buckets/policy.js

@@ -0,0 +1,74 @@
+import { LocalBucketPolicyError, } from "./types.js";
+const CONTENT_TYPE = /^(?:[A-Za-z0-9!#$&^_.+-]+|\*)\/(?:[A-Za-z0-9!#$&^_.+-]+|\*)$/;
+export function normalizePolicy(options) {
+    const source = options.policy ?? {};
+    const maxObjectBytes = options.maxObjectBytes ?? source.maxObjectBytes;
+    if (maxObjectBytes !== undefined &&
+        (!Number.isSafeInteger(maxObjectBytes) || maxObjectBytes <= 0)) {
+        throw new LocalBucketPolicyError("maxObjectBytes must be a positive safe integer");
+    }
+    const sourceTypes = options.allowedContentTypes ?? source.allowedContentTypes;
+    const allowedContentTypes = sourceTypes === undefined ? undefined : normalizeContentTypes(sourceTypes);
+    return Object.freeze({
+        ...(maxObjectBytes === undefined ? {} : { maxObjectBytes }),
+        ...(allowedContentTypes === undefined ? {} : { allowedContentTypes }),
+    });
+}
+export function validatePut(bytes, options, policy) {
+    const contentType = normalizeContentType(options?.contentType);
+    if (policy.maxObjectBytes !== undefined && bytes.byteLength > policy.maxObjectBytes) {
+        throw new LocalBucketPolicyError("Bucket object exceeds maxObjectBytes");
+    }
+    if (policy.allowedContentTypes !== undefined &&
+        (contentType === undefined ||
+            !policy.allowedContentTypes.some((allowed) => matchesContentType(contentType, allowed)))) {
+        throw new LocalBucketPolicyError("Bucket content type is not allowed");
+    }
+    return {
+        ...(contentType === undefined ? {} : { contentType }),
+        metadata: normalizeMetadata(options?.metadata),
+    };
+}
+function normalizeContentTypes(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new LocalBucketPolicyError("allowedContentTypes must not be empty");
+    }
+    const result = value.map((entry) => {
+        if (typeof entry !== "string" || !CONTENT_TYPE.test(entry.trim())) {
+            throw new LocalBucketPolicyError("allowedContentTypes contains an invalid MIME type");
+        }
+        return entry.trim().toLowerCase();
+    });
+    if (new Set(result).size !== result.length) {
+        throw new LocalBucketPolicyError("allowedContentTypes must be unique");
+    }
+    return Object.freeze(result);
+}
+function normalizeContentType(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !CONTENT_TYPE.test(value.trim())) {
+        throw new LocalBucketPolicyError("contentType must be a valid MIME type");
+    }
+    return value.trim().toLowerCase();
+}
+function normalizeMetadata(value) {
+    if (value === undefined)
+        return Object.freeze({});
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new LocalBucketPolicyError("metadata must be a string record");
+    }
+    const entries = Object.entries(value).map(([key, entry]) => {
+        if (key.length === 0 || key.includes("\0") || typeof entry !== "string") {
+            throw new LocalBucketPolicyError("metadata must contain non-empty string entries");
+        }
+        return [key, entry];
+    });
+    return Object.freeze(Object.fromEntries(entries.sort(([a], [b]) => a.localeCompare(b))));
+}
+function matchesContentType(value, allowed) {
+    return (allowed === "*/*" ||
+        allowed === value ||
+        (allowed.endsWith("/*") && value.startsWith(`${allowed.slice(0, -1)}`)));
+}
+//# sourceMappingURL=policy.js.map

package/dist/buckets/policy.js.map

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

package/dist/buckets/provider.d.ts

@@ -0,0 +1,4 @@
+import { type LocalBucketPolicy, type LocalBucketProvider, type LocalBucketProviderOptions } from "./types.js";
+export declare function createLocalBucketProvider(optionsOrRoot: LocalBucketProviderOptions | string, policy?: LocalBucketPolicy): LocalBucketProvider;
+export declare const createLocalBucketProviderForTest: typeof createLocalBucketProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/buckets/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/buckets/provider.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAChC,MAAM,YAAY,CAAC;AAWpB,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,0BAA0B,GAAG,MAAM,EAClD,MAAM,CAAC,EAAE,iBAAiB,GACzB,mBAAmB,CAmHrB;AAED,eAAO,MAAM,gCAAgC,kCAA4B,CAAC"}

package/dist/buckets/provider.js

@@ -0,0 +1,119 @@
+import { BucketCapabilityError, } from "@relkit/buckets";
+import { normalizeBucketKey, normalizeBucketPrefix } from "./keys.js";
+import { paginateKeys } from "./pagination.js";
+import { normalizePolicy } from "./policy.js";
+import { createBucketStorage } from "./storage.js";
+import { LOCAL_BUCKET_CAPABILITIES, LocalBucketStateError, } from "./types.js";
+import { deleteObject, existsObject, getObject, headObject, listKeys, putObject, assertActive, } from "./operations.js";
+export function createLocalBucketProvider(optionsOrRoot, policy) {
+    const options = typeof optionsOrRoot === "string"
+        ? { root: optionsOrRoot, ...(policy === undefined ? {} : { policy }) }
+        : optionsOrRoot;
+    const root = options.root ?? options.stateRoot;
+    if (root === undefined || root.trim() === "") {
+        throw new LocalBucketStateError("Bucket root is required");
+    }
+    const normalizedPolicy = normalizePolicy(options);
+    const defaultPageSize = options.pageSize;
+    if (defaultPageSize !== undefined &&
+        (!Number.isSafeInteger(defaultPageSize) || defaultPageSize <= 0)) {
+        throw new LocalBucketStateError("Bucket pageSize must be a positive safe integer");
+    }
+    const storage = createBucketStorage(root);
+    let closed = false;
+    const listPage = async (prefix, options) => {
+        ensureOpen(closed);
+        const normalizedPrefix = normalizeBucketPrefix(prefix);
+        const keys = await listKeys(storage, normalizedPrefix);
+        const pageOptions = pageOptionsFor(options, defaultPageSize);
+        return paginateKeys(keys, normalizedPrefix, pageOptions);
+    };
+    const list = (async (prefix, options) => {
+        if (isOperationContext(options)) {
+            ensureOpen(closed);
+            const normalizedPrefix = normalizeBucketPrefix(prefix);
+            assertActive(options);
+            return Object.freeze(await listKeys(storage, normalizedPrefix));
+        }
+        if (options !== undefined)
+            return listPage(prefix, options);
+        ensureOpen(closed);
+        const normalizedPrefix = normalizeBucketPrefix(prefix);
+        return Object.freeze(await listKeys(storage, normalizedPrefix));
+    });
+    const close = async () => {
+        closed = true;
+    };
+    const ready = async () => {
+        ensureOpen(closed);
+        await storage.ready();
+    };
+    const open = () => ensureOpen(closed);
+    const inspector = Object.freeze({
+        list: async (request) => {
+            if (request.signal.aborted)
+                throw request.signal.reason;
+            const page = await listPage(request.prefix, {
+                limit: request.limit,
+                ...(request.cursor === undefined ? {} : { cursor: request.cursor }),
+            });
+            const items = await Promise.all(page.items.map(async (key) => {
+                const metadata = await headObject(storage, key, undefined, open);
+                return { key, ...(metadata === undefined ? {} : { metadata }) };
+            }));
+            return { ...page, items };
+        },
+        preview: async (request) => {
+            if (request.signal.aborted)
+                throw request.signal.reason;
+            const [metadata, bytes] = await Promise.all([
+                headObject(storage, request.key, undefined, open),
+                getObject(storage, request.key, undefined, open),
+            ]);
+            if (metadata === undefined || bytes === undefined)
+                return undefined;
+            return {
+                bytes: bytes.slice(request.offset, request.offset + request.limit),
+                metadata,
+                totalBytes: bytes.byteLength,
+            };
+        },
+    });
+    return Object.freeze({
+        capabilities: LOCAL_BUCKET_CAPABILITIES,
+        root: storage.root,
+        policy: normalizedPolicy,
+        put: (key, bytes, options, context) => putObject(storage, normalizedPolicy, key, bytes, options, context, open),
+        get: (key, context) => getObject(storage, key, context, open),
+        head: (key, context) => headObject(storage, key, context, open),
+        delete: (key, context) => deleteObject(storage, key, context, open),
+        exists: (key, context) => existsObject(storage, key, context, open),
+        list,
+        listPage,
+        createReadUrl: (key, context) => unsupported("signedReadUrl", "createReadUrl", key, context, open),
+        createWriteUrl: (key, context) => unsupported("signedWriteUrl", "createWriteUrl", key, context, open),
+        ready,
+        close,
+        inspector,
+    });
+}
+export const createLocalBucketProviderForTest = createLocalBucketProvider;
+function pageOptionsFor(options, defaultPageSize) {
+    if (options !== undefined || defaultPageSize === undefined)
+        return options;
+    return { limit: defaultPageSize };
+}
+function unsupported(capability, operation, key, context, open) {
+    open();
+    normalizeBucketKey(key);
+    assertActive(context);
+    return Promise.reject(new BucketCapabilityError(capability, operation));
+}
+function ensureOpen(closed) {
+    if (closed)
+        throw new LocalBucketStateError("Bucket provider is closed");
+}
+function isOperationContext(value) {
+    return value !== null && typeof value === "object" && "operation" in value && "signal" in value;
+}
+//# sourceMappingURL=provider.js.map

package/dist/buckets/provider.js.map

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

package/dist/buckets/storage.d.ts

@@ -0,0 +1,12 @@
+import { type StoredLocalBucketObject } from "./types.js";
+export interface LocalBucketStorage {
+    readonly root: string;
+    readonly objectRoot: string;
+    readonly read: (key: string) => Promise<StoredLocalBucketObject | undefined>;
+    readonly write: (value: StoredLocalBucketObject) => Promise<void>;
+    readonly remove: (key: string) => Promise<void>;
+    readonly list: () => Promise<readonly StoredLocalBucketObject[]>;
+    readonly ready: () => Promise<void>;
+}
+export declare function createBucketStorage(requestedRoot: string): LocalBucketStorage;
+//# sourceMappingURL=storage.d.ts.map

package/dist/buckets/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/buckets/storage.ts"],"names":[],"mappings":"AAMA,OAAO,EAAyB,KAAK,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAKjF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC,CAAC;IAC7E,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAAC;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,kBAAkB,CAmB7E"}