@origintrail-official/dkg-agent 10.0.19 → 10.0.21

package/dist/sync/responder/exact-graph-reader.d.ts

@@ -0,0 +1,95 @@
+import type { SessionPlanMemo } from './session-plan-memo.js';
+import { StoreResponseTooLargeError, type TripleStore } from '@origintrail-official/dkg-storage';
+import type { ExactGraphReadMode } from './durable-data-request-policy.js';
+import { type SyncRow } from './snapshot-cache.js';
+import { SyncRowSnapshotBudgetError } from './snapshot-budget.js';
+import { type RowListCache } from './responder-row-page.js';
+interface ExactGraphPagePlanEntry {
+    graph: string;
+    rowCount: number;
+}
+/**
+ * The last row consumed from one exact graph.  The responder wire still uses
+ * numeric offsets, so this is an internal session cursor: the next sequential
+ * page can seek from the last row without asking the store to walk every
+ * preceding row again.
+ *
+ * `graphOffset` is retained only for the plan/count invariant.  It lets the
+ * seek query request one sentinel row when it reaches the committed graph
+ * boundary, just like the legacy OFFSET path does.
+ */
+interface ExactGraphPageCursor {
+    graph: string;
+    graphOffset: number;
+    s: string;
+    p: string;
+    o: string;
+}
+interface ConfirmedGraphScopedVmManifestEntry extends ExactGraphPagePlanEntry {
+    ual: string;
+}
+export interface GraphScopedVmManifest {
+    confirmedEntries: readonly ConfirmedGraphScopedVmManifestEntry[];
+    confirmedGraphs: ReadonlySet<string>;
+    /** Complete V2 descriptors in any lifecycle state, used to reject tentative VM payloads. */
+    knownGraphs: ReadonlySet<string>;
+}
+export interface ExactGraphPagePlan {
+    entries: readonly ExactGraphPagePlanEntry[];
+    totalRows: number;
+    /** At most one exact graph is retained while an oversized phase is framed. */
+    activeGraphRows?: {
+        graph: string;
+        rows: readonly SyncRow[];
+    };
+    activeGraphRowsLoad?: {
+        graph: string;
+        promise: Promise<readonly SyncRow[] | null>;
+    };
+    /** Graphs that exceeded the bounded local snapshot and require ordered paging. */
+    pagedGraphs: Set<string>;
+    /**
+     * Session-bound page boundaries.  The map is deliberately bounded: a
+     * requester may probe arbitrary offsets, and those probes must not turn a
+     * pagination session into an unbounded control-plane cache.
+     */
+    cursors: Map<number, ExactGraphPageCursor | null>;
+    cursorBytesEstimate?: number;
+}
+export type ExactGraphPagePlanMemo = SessionPlanMemo<ExactGraphPagePlan>;
+/**
+ * Read the constant-size V2 control rows that already form a per-KA manifest.
+ *
+ * The payload graph and its row count are authenticated again by the requester,
+ * but deriving the responder plan from these rows removes three store-wide or
+ * per-graph discovery operations from the normal rootless path: graph-family
+ * enumeration as authority, child-prefix probing after the reserved VM segment,
+ * and COUNT(*)/countQuads for every KA. The query is deliberately one exact
+ * metadata graph, standard SPARQL 1.1, unordered, row/response bounded, and
+ * backend-neutral.
+ */
+export declare function readGraphScopedVmManifest(store: TripleStore, contextGraphId: string, signal?: AbortSignal, assetUals?: readonly string[]): Promise<GraphScopedVmManifest>;
+export declare function buildExactGraphPagePlan(store: TripleStore, graphs: readonly string[], isAdmitted: (graph: string) => Promise<boolean>, signal?: AbortSignal, knownRowCounts?: ReadonlyMap<string, number>, exactGraphReadMode?: ExactGraphReadMode): Promise<ExactGraphPagePlan>;
+export interface ExactGraphSnapshotLimits {
+    maxRows: number;
+    maxBytesEstimate: number;
+    maxPageResponseBytes?: number;
+}
+export declare const EXACT_GRAPH_CURSOR_CACHE_MAX_BYTES_ESTIMATE: number;
+export declare const EXACT_GRAPH_PLAN_MAX_BYTES_ESTIMATE: number;
+export declare function exactGraphPlanScalarBytes(plan: ExactGraphPagePlan): number;
+export declare function snapshotResponseByteLimit(maxBytesEstimate: number): number;
+/** Clamp a store response-cap overshoot (possibly bigint) into a safe number. */
+export declare function storeResponseActualBytes(error: StoreResponseTooLargeError): number;
+export declare function snapshotBudgetError(params: {
+    key: string;
+    reason: 'snapshot_rows' | 'snapshot_bytes';
+    rows: number;
+    bytesEstimate: number;
+    limit: number;
+}): SyncRowSnapshotBudgetError;
+export declare function readExactGraphPlanSnapshot(store: TripleStore, plan: ExactGraphPagePlan, cache: RowListCache, limits: ExactGraphSnapshotLimits): Promise<readonly SyncRow[]>;
+export declare function rememberExactGraphReturnedPrefix(plan: ExactGraphPagePlan, offset: number, rows: readonly SyncRow[]): void;
+export declare function readRowsPageFromExactGraphPlan(store: TripleStore, plan: ExactGraphPagePlan, offset: number, limit: number, snapshotLimits: ExactGraphSnapshotLimits, signal?: AbortSignal): Promise<SyncRow[]>;
+export {};
+//# sourceMappingURL=exact-graph-reader.d.ts.map

package/dist/sync/responder/exact-graph-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-graph-reader.d.ts","sourceRoot":"","sources":["../../../src/sync/responder/exact-graph-reader.ts"],"names":[],"mappings":"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"}