@opendatalabs/personal-server-ts-core 0.0.1-canary.00328bf

package/dist/storage/blocks/select.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Block-addressed selection: read exactly the blocks a caller names.
+ *
+ * Search returns a `blockRef` per hit and the manifest is a table of contents,
+ * but without this path a client still has to walk `nextCursor` from the start
+ * of the scope to reach a block it already knows the id of. Every storage
+ * implementation pages the manifest identically, so the selection loop lives
+ * here instead of being copied into each of them.
+ */
+import type { DataBlockManifest, DataBlockWarning, DataScopeBlock } from "./types.js";
+/** Upper bound on block ids honoured in a single block-addressed read. */
+export declare const MAX_SELECTED_BLOCK_IDS = 50;
+export interface SelectScopeBlocksResult {
+    blocks: DataScopeBlock[];
+    warnings: DataBlockWarning[];
+}
+/**
+ * Return the requested blocks in the order they were asked for, bounded by
+ * `maxBytes`. Ids that are not in the manifest, ids dropped by the id cap, and
+ * ids left out because the byte budget ran out are reported as warnings rather
+ * than errors — a partially answered selection is still useful.
+ *
+ * No cursor is produced: the selection order is the caller's, not the
+ * manifest's, so a manifest-index cursor could not resume it.
+ */
+export declare function selectScopeBlocksByIds(manifest: DataBlockManifest, blockIds: readonly string[], options: {
+    maxBytes: number;
+}, loadBlock: (blockId: string) => Promise<DataScopeBlock | null>): Promise<SelectScopeBlocksResult>;
+//# sourceMappingURL=select.d.ts.map

package/dist/storage/blocks/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/storage/blocks/select.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,KAAK,CAAC;AASzC,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,iBAAiB,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC7B,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,GAC7D,OAAO,CAAC,uBAAuB,CAAC,CAsElC"}

package/dist/storage/blocks/select.js

@@ -0,0 +1,120 @@
+/**
+ * Block-addressed selection: read exactly the blocks a caller names.
+ *
+ * Search returns a `blockRef` per hit and the manifest is a table of contents,
+ * but without this path a client still has to walk `nextCursor` from the start
+ * of the scope to reach a block it already knows the id of. Every storage
+ * implementation pages the manifest identically, so the selection loop lives
+ * here instead of being copied into each of them.
+ */
+/** Upper bound on block ids honoured in a single block-addressed read. */
+export const MAX_SELECTED_BLOCK_IDS = 50;
+/** Ids listed inline in a warning message before it is summarized by count. */
+const WARNING_ID_SAMPLE = 10;
+const TEXT_PAGE_MEDIA_TYPE = "text/plain; charset=utf-8";
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+/**
+ * Return the requested blocks in the order they were asked for, bounded by
+ * `maxBytes`. Ids that are not in the manifest, ids dropped by the id cap, and
+ * ids left out because the byte budget ran out are reported as warnings rather
+ * than errors — a partially answered selection is still useful.
+ *
+ * No cursor is produced: the selection order is the caller's, not the
+ * manifest's, so a manifest-index cursor could not resume it.
+ */
+export async function selectScopeBlocksByIds(manifest, blockIds, options, loadBlock) {
+    const maxBytes = Math.max(1, options.maxBytes);
+    const refById = new Map(manifest.blocks.map((ref) => [ref.id, ref]));
+    const requested = [];
+    const seen = new Set();
+    let cappedIds = 0;
+    for (const blockId of blockIds) {
+        if (typeof blockId !== "string" || !blockId || seen.has(blockId))
+            continue;
+        seen.add(blockId);
+        if (requested.length >= MAX_SELECTED_BLOCK_IDS) {
+            cappedIds += 1;
+            continue;
+        }
+        requested.push(blockId);
+    }
+    const blocks = [];
+    const missingIds = [];
+    const skippedIds = [];
+    const warnings = [];
+    let bytes = 0;
+    for (let index = 0; index < requested.length; index += 1) {
+        const blockId = requested[index];
+        const ref = refById.get(blockId);
+        if (!ref) {
+            missingIds.push(blockId);
+            continue;
+        }
+        // Mirrors the cursor path: a block that does not fit whole is only sliced
+        // when it is the first one in the page, so a caller always makes progress.
+        if (blocks.length > 0 && bytes + ref.sizeBytes > maxBytes) {
+            skippedIds.push(...requested.slice(index));
+            break;
+        }
+        const block = await loadBlock(blockId);
+        if (!block) {
+            missingIds.push(blockId);
+            continue;
+        }
+        const page = pageBlock(block, maxBytes - bytes);
+        blocks.push(page.block);
+        bytes += page.block.sizeBytes;
+        if (page.truncated) {
+            skippedIds.push(...requested.slice(index + 1));
+            break;
+        }
+    }
+    if (cappedIds > 0) {
+        warnings.push({
+            code: "block_selection_capped",
+            message: `${cappedIds} block ids beyond the ${MAX_SELECTED_BLOCK_IDS} id limit were ignored`,
+        });
+    }
+    if (missingIds.length > 0) {
+        warnings.push({
+            code: "block_not_found",
+            message: `${missingIds.length} requested block ids are not in this scope: ${summarizeIds(missingIds)}`,
+        });
+    }
+    if (skippedIds.length > 0) {
+        warnings.push({
+            code: "block_selection_truncated",
+            message: `maxBytes reached; ${skippedIds.length} requested blocks were not returned: ${summarizeIds(skippedIds)}. Request them in a follow-up read.`,
+        });
+    }
+    return { blocks, warnings };
+}
+function summarizeIds(ids) {
+    const sample = ids.slice(0, WARNING_ID_SAMPLE).join(", ");
+    return ids.length > WARNING_ID_SAMPLE
+        ? `${sample}, ...(${ids.length - WARNING_ID_SAMPLE} more)`
+        : sample;
+}
+function pageBlock(block, maxBytes) {
+    const text = typeof block.value === "string" ? block.value : JSON.stringify(block.value);
+    const bytes = textEncoder.encode(text);
+    if (bytes.length <= maxBytes) {
+        return { block, truncated: false };
+    }
+    const end = Math.max(1, maxBytes);
+    return {
+        block: {
+            ...block,
+            path: `${block.path}[bytes 0:${end}]`,
+            mediaType: block.mediaType.startsWith("text/")
+                ? block.mediaType
+                : TEXT_PAGE_MEDIA_TYPE,
+            value: textDecoder.decode(bytes.slice(0, end)),
+            sizeBytes: end,
+            truncated: true,
+        },
+        truncated: true,
+    };
+}
+//# sourceMappingURL=select.js.map

package/dist/storage/blocks/select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../../src/storage/blocks/select.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC,+EAA+E;AAC/E,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B,MAAM,oBAAoB,GAAG,2BAA2B,CAAC;AACzD,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AACtC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAOtC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,QAA2B,EAC3B,QAA2B,EAC3B,OAA6B,EAC7B,SAA8D;IAE9D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAErE,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,SAAS;QAC3E,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClB,IAAI,SAAS,CAAC,MAAM,IAAI,sBAAsB,EAAE,CAAC;YAC/C,SAAS,IAAI,CAAC,CAAC;YACf,SAAS;QACX,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACzD,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,0EAA0E;QAC1E,2EAA2E;QAC3E,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,GAAG,GAAG,CAAC,SAAS,GAAG,QAAQ,EAAE,CAAC;YAC1D,UAAU,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;YAC3C,MAAM;QACR,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;QAChD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;QAC9B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,UAAU,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;YAC/C,MAAM;QACR,CAAC;IACH,CAAC;IAED,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClB,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EAAE,GAAG,SAAS,yBAAyB,sBAAsB,wBAAwB;SAC7F,CAAC,CAAC;IACL,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,GAAG,UAAU,CAAC,MAAM,+CAA+C,YAAY,CAAC,UAAU,CAAC,EAAE;SACvG,CAAC,CAAC;IACL,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,2BAA2B;YACjC,OAAO,EAAE,qBAAqB,UAAU,CAAC,MAAM,wCAAwC,YAAY,CAAC,UAAU,CAAC,qCAAqC;SACrJ,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC;AAED,SAAS,YAAY,CAAC,GAAsB;IAC1C,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1D,OAAO,GAAG,CAAC,MAAM,GAAG,iBAAiB;QACnC,CAAC,CAAC,GAAG,MAAM,SAAS,GAAG,CAAC,MAAM,GAAG,iBAAiB,QAAQ;QAC1D,CAAC,CAAC,MAAM,CAAC;AACb,CAAC;AAED,SAAS,SAAS,CAChB,KAAqB,EACrB,QAAgB;IAEhB,MAAM,IAAI,GACR,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC7B,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAClC,OAAO;QACL,KAAK,EAAE;YACL,GAAG,KAAK;YACR,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,YAAY,GAAG,GAAG;YACrC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC;gBAC5C,CAAC,CAAC,KAAK,CAAC,SAAS;gBACjB,CAAC,CAAC,oBAAoB;YACxB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YAC9C,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,IAAI;SAChB;QACD,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC"}

package/dist/storage/blocks/types.d.ts

@@ -0,0 +1,56 @@
+export type ContentKind = "vana-envelope" | "json" | "zip" | "text" | "binary" | "unsupported";
+export interface DataBlockManifest {
+    version: 1;
+    scope: string;
+    collectedAt: string;
+    schemaId?: string;
+    contentKind: ContentKind;
+    rawSizeBytes?: number;
+    blocks: DataBlockRef[];
+    warnings: DataBlockWarning[];
+}
+export interface DataBlockRef {
+    id: string;
+    path: string;
+    mediaType: string;
+    sizeBytes: number;
+    itemCount?: number;
+    truncated?: boolean;
+}
+export interface DataBlockWarning {
+    code: string;
+    message: string;
+    fileId?: string;
+    path?: string;
+}
+export interface ReadScopeBlocksRequest {
+    scope: string;
+    collectedAt?: string;
+    cursor?: string;
+    maxBytes?: number;
+    /**
+     * Read only these blocks, in this order, instead of paging the scope from
+     * `cursor`. Ids come from a manifest listing or from a search hit's
+     * `blockRef`. When set, `cursor` is ignored and no `nextCursor` is returned;
+     * `maxBytes` still bounds the response.
+     */
+    blockIds?: string[];
+}
+export interface ReadScopeBlocksResponse {
+    scope: string;
+    collectedAt: string;
+    schemaId?: string;
+    contentKind: ContentKind;
+    blocks: DataScopeBlock[];
+    nextCursor?: string;
+    warnings: DataBlockWarning[];
+}
+export interface DataScopeBlock {
+    id: string;
+    path: string;
+    mediaType: string;
+    value: unknown;
+    sizeBytes: number;
+    truncated?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/blocks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/storage/blocks/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACrB,eAAe,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB"}

package/dist/storage/blocks/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/storage/blocks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/storage/blocks/types.ts"],"names":[],"mappings":""}

package/dist/storage/hierarchy/index.d.ts

@@ -0,0 +1,3 @@
+export { timestampToFilename, filenameToTimestamp, buildDataFilePath, buildScopeDir, generateCollectedAt, } from "./paths.js";
+export type { HierarchyManagerOptions, WriteResult } from "./manager.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/hierarchy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/hierarchy/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/storage/hierarchy/index.js

@@ -0,0 +1,2 @@
+export { timestampToFilename, filenameToTimestamp, buildDataFilePath, buildScopeDir, generateCollectedAt, } from "./paths.js";
+//# sourceMappingURL=index.js.map

package/dist/storage/hierarchy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/hierarchy/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/storage/hierarchy/manager.d.ts

@@ -0,0 +1,9 @@
+export interface HierarchyManagerOptions {
+    dataDir: string;
+}
+export interface WriteResult {
+    path: string;
+    relativePath: string;
+    sizeBytes: number;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/storage/hierarchy/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/storage/hierarchy/manager.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/storage/hierarchy/manager.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=manager.js.map

package/dist/storage/hierarchy/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/storage/hierarchy/manager.ts"],"names":[],"mappings":""}

package/dist/storage/hierarchy/paths.d.ts

@@ -0,0 +1,11 @@
+/** "2026-01-21T10:00:00Z" → "2026-01-21T10-00-00Z" */
+export declare function timestampToFilename(isoTimestamp: string): string;
+/** "2026-01-21T10-00-00Z" → "2026-01-21T10:00:00Z" */
+export declare function filenameToTimestamp(filename: string): string;
+/** Full file path: join(baseDir, ...scopeSegments, timestamp.json) */
+export declare function buildDataFilePath(baseDir: string, scope: string, collectedAt: string): string;
+/** Directory path for a scope */
+export declare function buildScopeDir(baseDir: string, scope: string): string;
+/** Generate current UTC timestamp without milliseconds, ending in Z */
+export declare function generateCollectedAt(): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/storage/hierarchy/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/storage/hierarchy/paths.ts"],"names":[],"mappings":"AAEA,sDAAsD;AACtD,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,sDAAsD;AACtD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAS5D;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR;AAED,iCAAiC;AACjC,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,IAAI,MAAM,CAI5C"}

package/dist/storage/hierarchy/paths.js

@@ -0,0 +1,43 @@
+import { scopeToPathSegments } from "@opendatalabs/vana-sdk/browser";
+/** "2026-01-21T10:00:00Z" → "2026-01-21T10-00-00Z" */
+export function timestampToFilename(isoTimestamp) {
+    return isoTimestamp.replace(/:/g, "-");
+}
+/** "2026-01-21T10-00-00Z" → "2026-01-21T10:00:00Z" */
+export function filenameToTimestamp(filename) {
+    // Replace hyphens that appear in the time portion (after the T) back to colons.
+    // The date portion also has hyphens (2026-01-21) which must stay.
+    // Pattern: after T, every hyphen that separates HH-MM-SS should become a colon.
+    const tIndex = filename.indexOf("T");
+    if (tIndex === -1)
+        return filename;
+    const datePart = filename.slice(0, tIndex);
+    const timePart = filename.slice(tIndex);
+    return datePart + timePart.replace(/-/g, ":");
+}
+/** Full file path: join(baseDir, ...scopeSegments, timestamp.json) */
+export function buildDataFilePath(baseDir, scope, collectedAt) {
+    const segments = scopeToPathSegments(scope);
+    const filename = timestampToFilename(collectedAt) + ".json";
+    return joinPath(baseDir, ...segments, filename);
+}
+/** Directory path for a scope */
+export function buildScopeDir(baseDir, scope) {
+    const segments = scopeToPathSegments(scope);
+    return joinPath(baseDir, ...segments);
+}
+/** Generate current UTC timestamp without milliseconds, ending in Z */
+export function generateCollectedAt() {
+    const now = new Date();
+    now.setMilliseconds(0);
+    return now.toISOString().replace(".000Z", "Z");
+}
+function joinPath(...parts) {
+    const [first = "", ...rest] = parts;
+    const prefix = first.startsWith("/") ? "/" : "";
+    const segments = [first, ...rest]
+        .flatMap((part) => part.split("/"))
+        .filter((part) => part.length > 0);
+    return prefix + segments.join("/");
+}
+//# sourceMappingURL=paths.js.map

package/dist/storage/hierarchy/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/storage/hierarchy/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAErE,sDAAsD;AACtD,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACtD,OAAO,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,gFAAgF;IAChF,kEAAkE;IAClE,gFAAgF;IAChF,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,CAAC,CAAC;QAAE,OAAO,QAAQ,CAAC;IACnC,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACxC,OAAO,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,KAAa,EACb,WAAmB;IAEnB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC;IAC5D,OAAO,QAAQ,CAAC,OAAO,EAAE,GAAG,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAClD,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,KAAa;IAC1D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC5C,OAAO,QAAQ,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,mBAAmB;IACjC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IACvB,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,QAAQ,CAAC,GAAG,KAAe;IAClC,MAAM,CAAC,KAAK,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC;IACpC,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAChD,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC;SAC9B,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;SAClC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrC,OAAO,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrC,CAAC"}

package/dist/storage/index/index.d.ts

@@ -0,0 +1,3 @@
+export type { IndexEntry, IndexListOptions, NewIndexEntry, ScopeSummary, } from "./types.js";
+export type { IndexManager } from "./manager.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/storage/index/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/storage/index/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index/index.ts"],"names":[],"mappings":""}

package/dist/storage/index/manager.d.ts

@@ -0,0 +1,63 @@
+import type { IndexEntry, IndexListOptions, NewIndexEntry, ScopeSummary } from "./types.js";
+export interface IndexManager {
+    insert(entry: NewIndexEntry): IndexEntry;
+    findByPath(path: string): IndexEntry | undefined;
+    findByScope(options: IndexListOptions): IndexEntry[];
+    findLatestByScope(scope: string): IndexEntry | undefined;
+    countByScope(scope: string): number;
+    deleteByPath(path: string): boolean;
+    /**
+     * Delete a row by path ONLY if it is still unsynced (`dataPointId` null).
+     * Atomic guard so a row that raced to synced after selection keeps its
+     * metadata. Returns true only when an unsynced row was actually removed.
+     */
+    deleteUnsyncedByPath(path: string): boolean;
+    listDistinctScopes(options?: {
+        scopePrefix?: string;
+        limit?: number;
+        offset?: number;
+    }): {
+        scopes: ScopeSummary[];
+        total: number;
+    };
+    findClosestByScope(scope: string, at: string): IndexEntry | undefined;
+    findByFileId(fileId: string): IndexEntry | undefined;
+    /** Find an index entry by its DPv2 data-point id (download dedup). */
+    findByDataPointId(dataPointId: string): IndexEntry | undefined;
+    /**
+     * Find all index entries where dataPointId is null (not yet synced /
+     * registered on-chain). Returns entries ordered by created_at ASC (oldest
+     * first).
+     */
+    findUnsynced(options?: {
+        limit?: number;
+    }): IndexEntry[];
+    /**
+     * Update the fileId for an index entry (after successful upload + on-chain registration).
+     * @returns true if row was updated, false if path not found
+     */
+    updateFileId(path: string, fileId: string): boolean;
+    /**
+     * Returns the highest stored `version` for a scope, or 0 if none. Used by
+     * `insert` to derive the next expectedVersion for DPv2 AddData.
+     */
+    findLatestVersionByScope(scope: string): number;
+    /**
+     * Update the dataPointId for an index entry (after successful DPv2
+     * registerDataPoint). Sync-worker step that runs alongside fileId update.
+     * @returns true if row was updated, false if path not found
+     */
+    updateDataPointId(path: string, dataPointId: string): boolean;
+    /**
+     * Update the DPv2 `version` for an index entry. Used by the upload worker
+     * when a registration is rebased onto the registry's live version after a
+     * stale-expectedVersion conflict (the blob key embeds the version, so the
+     * local row must follow).
+     * @returns true if row was updated, false if path not found
+     */
+    updateVersion(path: string, version: number): boolean;
+    /** Deletes all index entries for a scope. Returns count of deleted rows. */
+    deleteByScope(scope: string): number;
+    close(): void;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/storage/index/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/storage/index/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAAC;IACzC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACjD,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,EAAE,CAAC;IACrD,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACzD,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC;;;;OAIG;IACH,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5C,kBAAkB,CAAC,OAAO,CAAC,EAAE;QAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG;QAAE,MAAM,EAAE,YAAY,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACtE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACrD,sEAAsE;IACtE,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAC/D;;;;OAIG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,EAAE,CAAC;IACzD;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACpD;;;OAGG;IACH,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAChD;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9D;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD,4EAA4E;IAC5E,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACrC,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/storage/index/manager.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=manager.js.map

package/dist/storage/index/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/storage/index/manager.ts"],"names":[],"mappings":""}

package/dist/storage/index/schema.d.ts

@@ -0,0 +1,2 @@
+export declare const INDEX_SCHEMA_VERSION = 3;
+//# sourceMappingURL=schema.d.ts.map

package/dist/storage/index/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/storage/index/schema.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,IAAI,CAAC"}

package/dist/storage/index/schema.js

@@ -0,0 +1,2 @@
+export const INDEX_SCHEMA_VERSION = 3;
+//# sourceMappingURL=schema.js.map

package/dist/storage/index/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/storage/index/schema.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC"}

package/dist/storage/index/types.d.ts

@@ -0,0 +1,37 @@
+export interface IndexEntry {
+    id: number;
+    fileId: string | null;
+    schemaId: string | null;
+    path: string;
+    scope: string;
+    collectedAt: string;
+    createdAt: string;
+    sizeBytes: number;
+    version: number;
+    dataPointId: string | null;
+    afterTombstoneVersion?: number | null;
+}
+export type NewIndexEntry = Omit<IndexEntry, "id" | "createdAt" | "schemaId" | "version" | "dataPointId"> & {
+    schemaId?: string | null;
+    version?: number;
+    dataPointId?: string | null;
+};
+export interface IndexListOptions {
+    scope?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ScopeSummary {
+    scope: string;
+    latestCollectedAt: string;
+    versionCount: number;
+    /**
+     * Whether bounded block reads for the latest local version are ready.
+     * Existing data can appear in the index before the block sidecar finishes
+     * indexing; MCP reads require the sidecar.
+     */
+    dataStatus?: "ready" | "indexing";
+    /** Size in bytes of the latest local version. */
+    sizeBytes?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/index/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/storage/index/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAIlB,OAAO,EAAE,MAAM,CAAC;IAGhB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAO3B,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,UAAU,EACV,IAAI,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,CAC5D,GAAG;IACF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAIzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAClC,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/storage/index/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/storage/index/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/storage/index/types.ts"],"names":[],"mappings":""}

package/dist/storage/pdpp-records/cursor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Opaque cursor encoding shared by both store backends. Cursors are base64url
+ * JSON; clients MUST NOT parse or construct them (spec §8), but both
+ * implementations need a shared wire format to stay behaviorally identical.
+ */
+export interface ListCursorPayload {
+    kind: "list";
+    order: "asc" | "desc";
+    sortValue: string | null;
+    recordKey: string;
+}
+export interface ChangesSinceCursorPayload {
+    kind: "changes_since";
+    /** The session horizon every page of this session is anchored to. */
+    horizon: string;
+    /** The previous session's horizon, or null for a first-ever sync. */
+    sinceHorizon: string | null;
+    /** Pagination offset within the horizon-anchored result set. */
+    offset: number;
+}
+export type CursorPayload = ListCursorPayload | ChangesSinceCursorPayload;
+export declare function encodeCursor(payload: CursorPayload): string;
+export declare function decodeCursor(cursor: string): CursorPayload;
+export declare class InvalidCursorSyntaxError extends Error {
+    constructor();
+}
+//# sourceMappingURL=cursor.d.ts.map

package/dist/storage/pdpp-records/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../../src/storage/pdpp-records/cursor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,eAAe,CAAC;IACtB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,yBAAyB,CAAC;AAyB1E,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAE3D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAW1D;AAED,qBAAa,wBAAyB,SAAQ,KAAK;;CAIlD"}

package/dist/storage/pdpp-records/cursor.js

@@ -0,0 +1,49 @@
+/**
+ * Opaque cursor encoding shared by both store backends. Cursors are base64url
+ * JSON; clients MUST NOT parse or construct them (spec §8), but both
+ * implementations need a shared wire format to stay behaviorally identical.
+ */
+// Base64url encode/decode via the universally-available `atob`/`btoa` + Web
+// text codecs rather than Node's Buffer, so this module stays browser-safe
+// (packages/core is consumed by ps-lite as well as the Node server) —
+// matches the convention in packages/core/src/payment/x402.ts.
+function base64urlEncode(input) {
+    const bytes = new TextEncoder().encode(input);
+    let binString = "";
+    for (const b of bytes)
+        binString += String.fromCodePoint(b);
+    return btoa(binString)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+function base64urlDecode(input) {
+    let s = input.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = (4 - (s.length % 4)) % 4;
+    s += "=".repeat(pad);
+    const binString = atob(s);
+    const bytes = Uint8Array.from(binString, (c) => c.codePointAt(0) ?? 0);
+    return new TextDecoder().decode(bytes);
+}
+export function encodeCursor(payload) {
+    return base64urlEncode(JSON.stringify(payload));
+}
+export function decodeCursor(cursor) {
+    try {
+        const json = base64urlDecode(cursor);
+        const parsed = JSON.parse(json);
+        if (parsed && (parsed.kind === "list" || parsed.kind === "changes_since")) {
+            return parsed;
+        }
+        throw new Error("malformed cursor payload");
+    }
+    catch {
+        throw new InvalidCursorSyntaxError();
+    }
+}
+export class InvalidCursorSyntaxError extends Error {
+    constructor() {
+        super("Cursor token is malformed or unrecognized");
+    }
+}
+//# sourceMappingURL=cursor.js.map

package/dist/storage/pdpp-records/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../src/storage/pdpp-records/cursor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqBH,4EAA4E;AAC5E,2EAA2E;AAC3E,sEAAsE;AACtE,+DAA+D;AAC/D,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,SAAS,IAAI,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,SAAS,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACxB,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,IAAI,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACvE,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAsB;IACjD,OAAO,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAC;QACjD,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,eAAe,CAAC,EAAE,CAAC;YAC1E,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,wBAAwB,EAAE,CAAC;IACvC,CAAC;AACH,CAAC;AAED,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD;QACE,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACrD,CAAC;CACF"}

package/dist/storage/pdpp-records/enforcement.d.ts

@@ -0,0 +1,37 @@
+import { PdppError } from "../../errors/pdpp-catalog.js";
+import { type PdppTokenContext, type StreamGrant } from "../../ports/pdpp-auth.js";
+import { type StreamDeclaration } from "./stream-declaration.js";
+/**
+ * Resolves a request-time authorization context to the effective read
+ * parameters this lane's PdppRecordStore calls need — `instanceIds`,
+ * `fields` — and validates the request against the grant/subject scope. This
+ * is the single narrow chokepoint every §8 read endpoint calls through, so
+ * enforcement logic (and any future grant-shape change) lives in one place.
+ *
+ * Throws PdppError for every documented spec §8 failure mode. Never returns
+ * a widened scope: on ambiguity, the narrower (deny) reading wins.
+ */
+export interface ResolvedReadScope {
+    instanceIds: string[];
+    fields?: string[];
+    streamGrant?: StreamGrant;
+}
+export declare function resolveReadScope(context: PdppTokenContext, stream: string, declaration: StreamDeclaration | undefined): ResolvedReadScope;
+/**
+ * Validates that a record's time field satisfies the grant's frozen
+ * time_constraint, if any. Callers filter store results through this before
+ * returning them (the store itself is time_constraint-agnostic).
+ */
+export declare function recordWithinGrantTimeConstraint(data: Record<string, unknown>, streamGrant: StreamGrant | undefined): boolean;
+/** Validates a canonical record_key is within the grant's `resources` allowlist, if constrained. */
+export declare function recordKeyWithinGrantResources(recordKey: string, streamGrant: StreamGrant | undefined): boolean;
+/**
+ * The PdppError an inactive token maps to.
+ *
+ * Exported so every route answers an inactive token with the SAME reason.
+ * `/v1/streams` previously inlined a flat `authentication_error` while record
+ * reads used this mapping, so one revoked grant produced a 401 on one endpoint
+ * and a 403 `grant_revoked` on another.
+ */
+export declare function mapInactiveToError(context: PdppTokenContext): PdppError;
+//# sourceMappingURL=enforcement.d.ts.map

package/dist/storage/pdpp-records/enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforcement.d.ts","sourceRoot":"","sources":["../../../src/storage/pdpp-records/enforcement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,iBAAiB,GAAG,SAAS,GACzC,iBAAiB,CAkDnB;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE,WAAW,GAAG,SAAS,GACnC,OAAO,CAOT;AAED,oGAAoG;AACpG,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,WAAW,GAAG,SAAS,GACnC,OAAO,CAGT;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAevE"}