@gaganref/confect-test 10.3.1-fork.92 → 10.3.1-fork.93

package/dist/internal/Snapshot.d.ts

@@ -0,0 +1,298 @@
+import { type JSONValue } from "convex/values";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import type * as Kernel from "./Kernel.js";
+import * as KernelRefusal from "./KernelRefusal.js";
+import { type DocumentId, type FunctionPath } from "./KernelValues.js";
+/**
+ * The counters the kernel allocates identities from: the next document ID, the
+ * latest creation time handed out, the next held attempt's ID, and the identity
+ * epoch, which every subscriber's `authenticate` advances. A restored world
+ * continues each where its source stopped, so the same calls mint the same
+ * identities and the same identity versions.
+ */
+export interface Identity {
+    readonly nextDocumentId: number;
+    readonly lastCreationTime: number;
+    readonly nextAttemptId: number;
+    readonly identityEpoch: number;
+}
+/**
+ * What the kernel keeps beside a job's row, with the job's test world named
+ * rather than held. `null` is a job scheduled with no invocation bound.
+ */
+export interface JobTarget {
+    readonly functionPath: FunctionPath;
+    readonly standing: boolean;
+    readonly world: string | null;
+}
+/**
+ * The kernel state a snapshot carries: committed rows of every component with
+ * the version that wrote each, the write log, the latest commit timestamp,
+ * every job's target, the clock's floor and the identity counters.
+ */
+export interface Image {
+    readonly components: ReadonlyArray<string>;
+    readonly state: Kernel.State;
+    /**
+     * The latest deadline the clock was advanced to. `-Infinity` before any.
+     */
+    readonly floor: number;
+    readonly identity: Identity;
+    /**
+     * The target of every job whose row is committed, by job ID.
+     */
+    readonly jobs: ReadonlyMap<DocumentId, JobTarget>;
+}
+/**
+ * Whether a piece of kernel state is in a snapshot. `exported` names the
+ * snapshot field that carries it. `excluded` says why a restore starts without
+ * it.
+ */
+export type Participation = {
+    readonly exported: string;
+} | {
+    readonly excluded: string;
+};
+/**
+ * The snapshot's contract with the kernel's state. Every field of the committed
+ * state, of a job's target and of a `World` is listed here as exported or
+ * excluded with its reason. The first two are checked by type: a field added to
+ * `Kernel.State` or `Scheduling.Target` without an entry fails to compile. A
+ * `World`'s fields are private, which no type can enumerate, so
+ * `Snapshot.test.ts` compares a fresh world's own fields with `world` below,
+ * and a field added without an entry fails that test.
+ *
+ * That test sees only the own fields a fresh world has. It cannot see state
+ * created lazily after construction, held under a symbol or a `#private` name,
+ * or kept in a closure or another object, as subscribers are. So every live
+ * registry, state that exists only while something runs or a client is
+ * attached, is also listed in `live`. `World.liveCounts` reports each one,
+ * typed against `live`, and a restore refuses while any of them is non-empty,
+ * so a piece of live state the snapshot does not carry fails loudly rather than
+ * surviving a restore silently. A new live registry adds itself there.
+ *
+ * Owed by later rows, which add their state here when they land on `main`: cron
+ * state (#133), stored file bytes, storage ID mappings, `nextFile` and
+ * upload-token counters (#138), and component init markers. A restore never
+ * redeclares a cron and never draws a fresh random value: it installs the
+ * declared state as the snapshot holds it, so a row whose state comes from a
+ * declaration or a random draw exports what was declared or drawn.
+ */
+export declare const contract: {
+    readonly state: {
+        tables: {
+            exported: string;
+        };
+        version: {
+            exported: string;
+        };
+        commitTs: {
+            exported: string;
+        };
+        log: {
+            exported: string;
+        };
+    };
+    readonly target: {
+        functionPath: {
+            exported: string;
+        };
+        standing: {
+            exported: string;
+        };
+        world: {
+            exported: string;
+        };
+    };
+    readonly world: {
+        components: {
+            excluded: string;
+        };
+        state: {
+            exported: string;
+        };
+        opened: {
+            excluded: string;
+        };
+        nextDocId: {
+            exported: string;
+        };
+        lastCreationTime: {
+            exported: string;
+        };
+        nextQueryId: {
+            excluded: string;
+        };
+        queries: {
+            excluded: string;
+        };
+        holding: {
+            excluded: string;
+        };
+        nextAttemptId: {
+            exported: string;
+        };
+        floor: {
+            exported: string;
+        };
+        targets: {
+            exported: string;
+        };
+        live: {
+            excluded: string;
+        };
+        identityEpoch: {
+            exported: string;
+        };
+        runtime: {
+            excluded: string;
+        };
+        redaction: {
+            excluded: string;
+        };
+        secrets: {
+            excluded: string;
+        };
+    };
+    /**
+     * Live registries: what blocks a snapshot while it is non-empty, and why.
+     */
+    readonly live: {
+        running: {
+            blocks: "export and restore";
+            reason: string;
+        };
+        walks: {
+            blocks: "export and restore";
+            reason: string;
+        };
+        functions: {
+            blocks: "export and restore";
+            reason: string;
+        };
+        held: {
+            blocks: "export and restore";
+            reason: string;
+        };
+        subscribers: {
+            blocks: "restore";
+            reason: string;
+        };
+    };
+    /**
+     * State outside the kernel's world, live per client or per process.
+     */
+    readonly outside: {
+        subscriptions: {
+            excluded: string;
+        };
+        requestIds: {
+            excluded: string;
+        };
+    };
+};
+declare const Body: Schema.Struct<{
+    readonly components: Schema.$Array<Schema.String>;
+    readonly version: Schema.Int;
+    readonly commitTs: Schema.String;
+    readonly floor: Schema.NullOr<Schema.Finite>;
+    readonly identity: Schema.Struct<{
+        readonly nextDocumentId: Schema.Int;
+        readonly lastCreationTime: Schema.Finite;
+        readonly nextAttemptId: Schema.Int;
+        readonly identityEpoch: Schema.Int;
+    }>;
+    readonly tables: Schema.$Array<Schema.Struct<{
+        readonly componentPath: Schema.String;
+        readonly table: Schema.String;
+        readonly rows: Schema.$Array<Schema.Struct<{
+            readonly version: Schema.Int;
+            readonly doc: Schema.Unknown;
+        }>>;
+    }>>;
+    readonly jobs: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly target: Schema.Struct<{
+            readonly componentPath: Schema.String;
+            readonly udfPath: Schema.String;
+        }>;
+        readonly standing: Schema.Boolean;
+        readonly world: Schema.NullOr<Schema.String>;
+    }>>;
+    readonly log: Schema.$Array<Schema.Struct<{
+        readonly version: Schema.Int;
+        readonly commitTs: Schema.String;
+        readonly changes: Schema.$Array<Schema.Struct<{
+            readonly componentPath: Schema.String;
+            readonly id: Schema.String;
+            readonly before: Schema.Unknown;
+            readonly after: Schema.Unknown;
+        }>>;
+    }>>;
+}>;
+type Body = typeof Body.Type;
+/**
+ * What an export writes for one document, before it reaches the bytes: the
+ * kernel marks secrets here. `table` is the document's table.
+ */
+export type Redact = (componentPath: string, table: string, json: JSONValue) => JSONValue;
+/**
+ * What a restore reads back for one document before decoding it: the kernel
+ * puts marked secrets back here.
+ */
+export type Unredact = (json: JSONValue) => Result.Result<JSONValue, KernelRefusal.SnapshotSecretMissing>;
+/**
+ * Encode `image` as snapshot bytes: a header line naming the format and the
+ * SHA-256 digest of the body, then the body as JSON. Components, tables, rows
+ * and jobs are sorted, and every document keeps its own field order, so the
+ * same state always encodes to the same bytes.
+ */
+export declare const encode: (image: Image, redact?: Redact) => Uint8Array;
+/**
+ * Check the decoded body before any map is built from it, so its order cannot
+ * change the result: components, tables, rows and jobs each appear once, and
+ * every document carries the system fields the kernel writes.
+ */
+export declare const checkBody: (body: Body) => Result.Result<void, KernelRefusal.SnapshotMalformed | KernelRefusal.SnapshotRowInconsistent | KernelRefusal.SnapshotJobInconsistent>;
+/**
+ * Why a decoded snapshot is not state the kernel could have reached.
+ */
+export type Inconsistency = KernelRefusal.SnapshotAllocatorBehind | KernelRefusal.SnapshotRowInconsistent | KernelRefusal.SnapshotTimestampInconsistent | KernelRefusal.SnapshotJobInconsistent;
+/**
+ * Rows match the write log: replaying every commit from the empty world, each
+ * change replacing the value the log last published, gives exactly the
+ * snapshot's rows, each at the version that last wrote it, in a registered
+ * component and under its ID's table.
+ */
+export declare const checkRows: (image: Image) => Result.Result<void, KernelRefusal.SnapshotRowInconsistent>;
+/**
+ * Identity counters run ahead of every identity the state holds: the next
+ * document ID past every ID's counter, the latest creation time at or past
+ * every document's, a positive next attempt ID and a non-negative epoch.
+ */
+export declare const checkAllocators: (image: Image) => Result.Result<void, KernelRefusal.SnapshotAllocatorBehind>;
+/**
+ * Commit timestamps strictly increase through the write log, and the latest
+ * commit timestamp is the log's last, or zero before any commit.
+ */
+export declare const checkTimestamps: (image: Image) => Result.Result<void, KernelRefusal.SnapshotTimestampInconsistent>;
+/**
+ * Every job names a committed job row and a registered component, every job row
+ * has its job, and no job is left running: a snapshot is never taken while a
+ * job runs.
+ */
+export declare const checkJobs: (image: Image, table: string) => Result.Result<void, KernelRefusal.SnapshotJobInconsistent>;
+/**
+ * Check a decoded image against every rule the kernel's own exports keep,
+ * before any of it is installed.
+ */
+export declare const check: (image: Image, jobTable: string) => Result.Result<void, Inconsistency>;
+/**
+ * Read snapshot bytes back into the state they encode. Bytes whose body no
+ * longer hashes to their header's digest refuse with `SnapshotDigestMismatch`
+ * before any of the body is read.
+ */
+export declare const decode: (bytes: Uint8Array, unredact?: Unredact) => Result.Result<Image, KernelRefusal.SnapshotMalformed | KernelRefusal.SnapshotDigestMismatch | KernelRefusal.SnapshotSecretMissing | KernelRefusal.SnapshotRowInconsistent | KernelRefusal.SnapshotJobInconsistent>;
+export {};
+//# sourceMappingURL=Snapshot.d.ts.map

package/dist/internal/Snapshot.d.ts.map

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