@opendatalabs/personal-server-ts-core 1.33.7 → 1.34.0

package/dist/storage/canonical-legacy-projection.d.ts

@@ -0,0 +1,262 @@
+import type { DataFileEnvelope } from "@opendatalabs/vana-sdk/browser";
+import { type LegacyScopeLookupError, type ProjectionError } from "../legacy-projection/index.js";
+import type { ProjectionOmission } from "../legacy-projection/types.js";
+import type { StreamDeclarationRegistry } from "./pdpp-records/stream-declaration.js";
+import { type PdppRecordStore } from "./pdpp-records/portable.js";
+/**
+ * Read-time legacy view over canonical PDPP records.
+ *
+ * Reads ONE legacy scope from exactly one selected connection and returns the
+ * legacy `DataFileEnvelope`. Nothing is stored: every call recomputes the body
+ * from the live rows, so a repaired source is visible on the next read. The
+ * reader only calls read methods on the store.
+ *
+ * Out of scope here: manual/unbound scope files (no binding => `unbound_scope`),
+ * auth/grants, and the sync `DataStoragePort` listing surface.
+ */
+/** Bump when a change to this module (or the pure projector) can change bytes. */
+export declare const CANONICAL_LEGACY_VIEW_CONTRACT = "canonical-legacy-view/7";
+export interface CanonicalConnectionBinding {
+    instance: string;
+    sourceId: string | null;
+    method: string | null;
+    deletedAt: string | null;
+    generation: number;
+    resetClock: number;
+}
+/**
+ * Evidence that one full replace delivered the stream's current live set.
+ * The store writes it only inside a successful P7 replace that named
+ * `sourceCollectedAt`, and deletes it on any other write to the stream and on
+ * reset or delete of the connection.
+ */
+export interface CanonicalStreamCompletion {
+    stream: string;
+    method: string;
+    generation: number;
+    /** Producer collection time (RFC 3339), never the store clock. */
+    sourceCollectedAt: string;
+    /** Store write sequence when the replace committed. */
+    writeSeq: number;
+    /** Live rows the replace left. */
+    liveCount: number;
+}
+/**
+ * The slice of the SQLite record store this reader needs. Read methods only.
+ * The calls are synchronous.
+ */
+export interface CanonicalLegacyReadStore extends Pick<PdppRecordStore, "listRecords" | "listStreams"> {
+    /** Optional for non-blob stores. Byte reads are synchronous inside readSnapshot. */
+    getBlobMeta?: PdppRecordStore["getBlobMeta"];
+    getBlobBytes?: PdppRecordStore["getBlobBytes"];
+    getInstanceBinding(instance: string): CanonicalConnectionBinding;
+    listConnections(sourceId: string): CanonicalConnectionBinding[];
+    /** Completion receipts stored for one instance. */
+    listStreamCompletions(instance: string): CanonicalStreamCompletion[];
+    /**
+     * Live record keys of one stream in the order each last arrived in the
+     * connection's current generation. A key the store holds no arrival for
+     * is absent. Read only for a binding with `rowOrder: "arrival"`.
+     */
+    listArrivalOrder(instance: string, stream: string): string[];
+    /**
+     * Run `read` against one point-in-time snapshot of the store: a write that
+     * commits meanwhile, from any connection, is invisible to every call made
+     * inside it. The reader relies on this instead of guessing from counts or
+     * timestamps, which an update at an older `emittedAt` does not move.
+     */
+    readSnapshot<T>(read: () => T): T;
+}
+/**
+ * The one connection a read may use. It must come from a trusted resolver
+ * (`resolveCanonicalConnection`, or a grant/bridge that already named the
+ * instance); the reader re-checks it against the store binding.
+ */
+export interface CanonicalConnectionSelection {
+    instance: string;
+    /** Store source id, e.g. `https://registry.pdpp.dev/sources/oura`. */
+    sourceId: string;
+    method: string;
+}
+export interface CanonicalReadDiagnostics {
+    /** Live source rows read per bound stream. Counts only, no row content. */
+    sourceRowCounts: Record<string, number>;
+    /**
+     * Source rows the projector left out of a still-deliverable payload, one
+     * entry per (stream, reason) the projector reported. Counts are distinct
+     * source rows.
+     */
+    omissions: {
+        stream: string;
+        count: number;
+        reasons: string[];
+    }[];
+    /** Rows delivered although their source says detail is missing. */
+    partialRows: {
+        stream: string;
+        count: number;
+        reasons: string[];
+    }[];
+    /**
+     * Properties of the legacy body the canonical rows cannot show. Today one:
+     * a stream of two or more rows served in arrival order whose rows the
+     * store holds no arrival for (rows stored before it kept one). Those rows
+     * are all delivered, in primary-key order. Present only when not empty,
+     * so no other scope's result changes shape.
+     */
+    unproven?: {
+        stream: string;
+        aspect: "record_order";
+        reason: string;
+    }[];
+}
+export interface CanonicalLegacyReadOk {
+    ok: true;
+    envelope: DataFileEnvelope;
+    projectionOmissions?: ProjectionOmission[];
+    /** Conservative collection horizon for each input stream in this snapshot. */
+    streamCollectionTimes?: Record<string, string | null>;
+    /** Current accepted P7 completion time for each input stream, if any. */
+    streamCompletionTimes?: Record<string, string | null>;
+    /**
+     * Opaque view revision: a hash of the contract version, connection,
+     * method, generation, declaration, per-stream row horizons in served
+     * order, order gaps, and the completion receipts the read used. It does
+     * not depend on the wall clock or on writes to other connections, so an
+     * unchanged source reads back the same value.
+     */
+    revision: string;
+    /**
+     * False when `diagnostics.omissions`, `diagnostics.partialRows` or
+     * `diagnostics.unproven` is not empty.
+     */
+    complete: boolean;
+    diagnostics: CanonicalReadDiagnostics;
+}
+export type CanonicalLegacyReadFailure = {
+    status: "unavailable";
+    reason: "unbound_scope";
+    lookup: LegacyScopeLookupError;
+} | {
+    status: "unavailable";
+    reason: "scope_source_mismatch";
+    scope: string;
+} | {
+    status: "unavailable";
+    reason: "connection_unavailable";
+    detail: "not_registered" | "deleted" | "source_mismatch" | "method_mismatch";
+} | {
+    status: "unavailable";
+    reason: "no_synced_data";
+} | {
+    /**
+     * A bound stream has no live rows and no completion receipt from the
+     * connection's current method and generation, so it cannot be told
+     * apart from a stream never collected. Another stream having data, or
+     * another stream's receipt, is not evidence.
+     */
+    status: "unavailable";
+    reason: "stream_completion_unknown";
+    streams: string[];
+} | {
+    status: "unavailable";
+    reason: "invalid_collected_at";
+} | {
+    status: "unavailable";
+    reason: "store_inconsistent_read";
+    detail: string;
+} | {
+    status: "unavailable";
+    reason: "blob_backed_records_unsupported";
+    stream: string;
+    recordCount: number;
+    blocker: string;
+} | {
+    status: "unavailable";
+    reason: "blob_read_budget_exceeded";
+    requiredBytes?: number;
+    maxBytes: number;
+} | {
+    status: "unavailable";
+    reason: "blob_backed_record_invalid";
+    detail: string;
+} | {
+    status: "unavailable";
+    reason: "missing_raw_blob";
+    recordCount: number;
+} | {
+    status: "incomplete";
+    reason: "projection_rejected";
+    error: ProjectionError;
+    sourceRowCounts: Record<string, number>;
+} | {
+    status: "incomplete";
+    reason: "all_rows_rejected";
+    stream: string;
+    sourceRows: number;
+    dropped: number;
+    reasons: string[];
+    sourceRowCounts: Record<string, number>;
+};
+export type CanonicalLegacyReadResult = CanonicalLegacyReadOk | ({
+    ok: false;
+} & CanonicalLegacyReadFailure);
+export interface ReadCanonicalLegacyScopeInput {
+    store: CanonicalLegacyReadStore;
+    /** Trusted declarations governing this instance, read inside the record snapshot. */
+    declarations?: Pick<StreamDeclarationRegistry, "forInstance">;
+    scope: string;
+    selection: CanonicalConnectionSelection;
+    /**
+     * How the selected connection's declaration profile is found.
+     * `"source"` (default): from the last segment of the source id.
+     * `"method"`: the method id is the profile key, as in Desktop's trusted
+     * method configuration, where one public source has several methods
+     * (`oura` and `oura-browser` both collect `sources/oura`). The binding
+     * must then belong to that method; the source id is not derived from it.
+     */
+    profileBy?: "source" | "method";
+    /**
+     * Runs first inside the read snapshot. False means the caller's selection
+     * no longer holds in the state the rows come from, and the read is
+     * refused as `store_inconsistent_read`.
+     */
+    confirmSelection?: () => boolean;
+    /** Require a matching completion receipt for every stream in the row snapshot. */
+    requireCompletionReceipts?: boolean;
+    /** A parity caller can compare an unproven empty stream with the actual legacy body. */
+    allowUnprovenEmptyStreams?: boolean;
+    /** Include the per-stream time evidence used by the parity takeover caller. */
+    includeStreamTimes?: boolean;
+    /** Require raw Claude envelopes when deciding whether a legacy head is covered. */
+    requireClaudeRawBlobs?: boolean;
+    /** Rows per store page. Tests lower it to force several pages. */
+    pageSize?: number;
+    /** @internal Tests may lower the blob budget; never raises the 64 MiB limit. */
+    blobByteBudget?: number;
+}
+export type ResolveCanonicalConnectionResult = {
+    ok: true;
+    selection: CanonicalConnectionSelection;
+} | {
+    ok: false;
+    status: "unavailable";
+    reason: "no_connection" | "ambiguous_connection";
+    candidates: number;
+};
+/**
+ * Pick the single connection for a source. Several matches is an error, never
+ * a union: a legacy body is one account's data.
+ */
+export declare function resolveCanonicalConnection(store: Pick<CanonicalLegacyReadStore, "listConnections">, query: {
+    sourceId: string;
+    method?: string;
+    instance?: string;
+}): ResolveCanonicalConnectionResult;
+export declare function readCanonicalLegacyScope(input: ReadCanonicalLegacyScopeInput): Promise<CanonicalLegacyReadResult>;
+/**
+ * The connector key a binding was reviewed for: the last segment of its
+ * `pdppSource`. It is a profile name, not a store source id.
+ */
+export declare function legacyConnectorKey(pdppSource: string): string;
+//# sourceMappingURL=canonical-legacy-projection.d.ts.map

package/dist/storage/canonical-legacy-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-legacy-projection.d.ts","sourceRoot":"","sources":["../../src/storage/canonical-legacy-projection.ts"],"names":[],"mappings":"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"}