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

package/dist/storage/legacy-scope-view.d.ts

@@ -0,0 +1,154 @@
+import type { DataFileEnvelope } from "@opendatalabs/vana-sdk/browser";
+import { type LegacyCoverageVerdict } from "./legacy-scope-coverage.js";
+export type { LegacyCoverageVerdict } from "./legacy-scope-coverage.js";
+import { type CanonicalConnectionBinding, type CanonicalLegacyReadFailure, type CanonicalLegacyReadStore, type ReadCanonicalLegacyScopeInput } from "./canonical-legacy-projection.js";
+/**
+ * Registry facts and takeover diagnostics from the same SQLite database as
+ * the rows. Facts must work when the record server is not mounted (its tables
+ * may then be absent: no connection, no evidence).
+ */
+export interface LegacyScopeAuthority {
+    /** Connections registered with one of `methods`, deleted ones included. */
+    listMethodConnections(methods: readonly string[]): CanonicalConnectionBinding[];
+    /**
+     * True when the instance has held a row (live or tombstoned) of one of
+     * `streams`, or holds a completion receipt for one. Null `streams`: any.
+     */
+    hasHeldData(instance: string, streams: readonly string[] | null): boolean;
+    /** See `CanonicalLegacyReadStore.readSnapshot`. Same database connection. */
+    readSnapshot<T>(read: () => T): T;
+    writeClock(): number;
+    /** Monotonic arrival revision, independent of record content writes. */
+    arrivalRevision(): number;
+    /** Whether a complete canonical read has already superseded the legacy head. */
+    hasTakeover(scope: string, instance?: string, generation?: number): boolean;
+    hasCoveredHead(scope: string, head: LegacyScopeHead, instance?: string): boolean;
+    isReset(scope: string): boolean;
+    cachedVerdict(scope: string, instance: string, generation: number, legacyVersionId: number, canonicalCursor: string): LegacyCoverageVerdict | null;
+    verdictFor(scope: string): LegacyScopeVerdictRecord[];
+    resetTakeover(scope: string): void;
+    /** Identity of the latest index entry not owned by a known projector. */
+    eligibleLegacyHead(scope: string): LegacyScopeHead | null;
+    /**
+     * Revalidates the head and connection selection under a write lock, then
+     * records the eligible legacy versions. A null head confirms a read that
+     * did not observe legacy data and records no takeover.
+     */
+    confirmRead(scope: string, expectedHead: LegacyScopeHead | null, selectionIsCurrent: () => boolean, verdict?: {
+        instance: string;
+        generation: number;
+        writeClock: number;
+        arrivalRevision: number;
+        canonicalCursor: string;
+        coverage: LegacyCoverageVerdict;
+        cached: boolean;
+    }): boolean;
+}
+export interface LegacyScopeVerdictRecord {
+    scope: string;
+    instance: string;
+    generation: number;
+    legacyVersionId: number;
+    canonicalCursor: string;
+    verdict: "covered" | "not_covered";
+    comparisonCase: "same_time" | "canonical_newer";
+    reasonCounts: Record<string, number>;
+    appliedExceptions: LegacyCoverageVerdict["appliedExceptions"];
+    reason: {
+        reason: string;
+        missingEntityCount: number;
+        mismatchedFieldPaths: string[];
+    } | null;
+    legacyBytes: number;
+    canonicalBytes: number;
+    byteDelta: number;
+    evaluatedAt: string;
+}
+export interface LegacyScopeHead {
+    id: number;
+    path: string;
+    version: number;
+    casRevision: number;
+    collectedAt: string;
+}
+export type LegacyScopeRefusal = CanonicalLegacyReadFailure | {
+    status: "unavailable";
+    reason: "no_connection" | "ambiguous_connection";
+    candidates: number;
+} | {
+    /** The record server is not mounted, or does not configure the pair. */
+    status: "unavailable";
+    reason: "connection_unavailable";
+    detail: "method_not_configured";
+} | {
+    status: "incomplete";
+    reason: "canonical_view_incomplete";
+    diagnostics: {
+        stream: string;
+        kind: "omitted" | "partial" | "unproven";
+        detail: string;
+    }[];
+};
+export type LegacyScopeLatest = 
+/** Not canonical: the existing storage answers, exactly as before. */
+{
+    kind: "file";
+} | {
+    kind: "canonical";
+    envelope: DataFileEnvelope;
+    /** Opaque, stable while the rows and receipts do not change. */
+    revision: string;
+} | {
+    kind: "refused";
+    refusal: LegacyScopeRefusal;
+};
+export type LegacyScopeListing = {
+    kind: "file";
+} | {
+    kind: "canonical";
+    collectedAt: string;
+} | {
+    kind: "refused";
+};
+export interface LegacyScopeViewPort {
+    /** The latest body of a scope. Never used for an explicit version. */
+    readLatest(scope: string): Promise<LegacyScopeLatest>;
+    /**
+     * Listing metadata from counts and receipts only, without reading rows.
+     * A refusal here is also a refusal on read; a read can still refuse what
+     * this lists (for example a projection rejection).
+     */
+    listingFor(scope: string): LegacyScopeListing;
+    /** Bound scopes under `scopePrefix` that `listingFor` lists as canonical. */
+    listCanonicalScopes(scopePrefix: string | undefined): {
+        scope: string;
+        collectedAt: string;
+    }[];
+    /** True when canonical history makes a legacy-only deletion unsafe. */
+    ownsScope(scope: string): boolean;
+    verdictFor(scope: string): LegacyScopeVerdictRecord[];
+    resetTakeover(scope: string): void;
+    isReset(scope: string): boolean;
+}
+export interface CreateLegacyScopeViewInput {
+    authority: LegacyScopeAuthority;
+    /**
+     * The mounted record store, over the authority's database connection.
+     * Absent when the record server is not mounted: canonical-owned scopes
+     * are then refused.
+     */
+    records?: CanonicalLegacyReadStore;
+    /** Current trusted declarations; pass the same registry used by canonical ingest. */
+    declarations?: ReadCanonicalLegacyScopeInput["declarations"];
+    /** Methods this boot configures for a store source id. */
+    configuredMethods(sourceId: string): readonly string[];
+    /** Read the exact latest indexed legacy file; omitted by in-memory adapters. */
+    readLegacyHead?(head: LegacyScopeHead): Promise<DataFileEnvelope>;
+    /** Optional payload growth limits for the takeover check. */
+    coverageThresholds?: {
+        maxPayloadRatio?: number;
+        maxExtraBytes?: number;
+    };
+}
+export declare function createLegacyScopeView(input: CreateLegacyScopeViewInput): LegacyScopeViewPort;
+//# sourceMappingURL=legacy-scope-view.d.ts.map

package/dist/storage/legacy-scope-view.d.ts.map

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