@amalgm/shell 0.1.164-preview.36072132286 → 0.1.164-preview.36809057014

package/dist/ground-basis.d.ts

@@ -0,0 +1,242 @@
+import type Database from "better-sqlite3";
+import type { DetectBasisDescriptor } from "@amalgm/live";
+import { type GroundRow, type SharingGroundRow } from "./ground-row.js";
+import { TerritoryHandle } from "./ground-territory.js";
+export type GroundInventory = "entities" | "detection_notebook";
+export declare class GroundBasisChangedError extends Error {
+}
+/** The same phase owner applies to both the store and direct snapshot entry. */
+export declare function assertGroundWriteAllowed(database: Database.Database): void;
+/** A process's first open of the ground file. No basis or revision string of
+ * an earlier process can reach this one, so the stamps restart empty under a
+ * new incarnation; a basis read before this commit, by any connection, fails
+ * its incarnation check instead of reading a missing stamp as unchanged. The
+ * counter stays monotonic, so no S0 or sequence string repeats. */
+export declare function beginGroundEpoch(database: Database.Database): void;
+/** One row by UUID, outside any basis: a read that proves nothing. */
+export declare const readGroundRow: (database: Database.Database, inventory: GroundInventory, uuid: string) => GroundRow | undefined;
+/** The database incarnation that retires every basis read before a reset. */
+export declare const groundIncarnation: (database: Database.Database) => string;
+/** The last stamp any committed write issued: S0 for a read made with it. */
+export declare const currentSequence: (database: Database.Database) => bigint;
+/** The facts stamped after an open observation's S0, as of its latest read.
+ * Within an epoch a stamp only rises, so a fact once stamped after S0 stays
+ * so, and each late read adds only what was stamped since the read before.
+ * A late read then costs one range read over the writes since, however many
+ * facts it consumes, instead of a lookup per fact. */
+declare class LaterStamps {
+    #private;
+    constructor(sequence: bigint);
+    /** Bring the set to the snapshot of the read transaction in progress. */
+    refresh(database: Database.Database): void;
+    has(id: string): boolean;
+}
+/** An open observation after its first read: the basis its reads extend,
+ * and the facts stamped after its S0. */
+interface LateRead {
+    readonly basis: GroundBasis;
+    readonly stamps: LaterStamps;
+}
+/** One root's committed O/B state: equal exactly while no row of that root,
+ * in either inventory, has been written. */
+export declare function rootRevision(database: Database.Database, rootUUID: string): string;
+/** An enrolled repository's identity and address, without its state. */
+export interface GroundRepositoryMember {
+    readonly uuid: string;
+    readonly rootUUID: string;
+    readonly absolutePath: string;
+}
+export interface GroundSnapshotReader {
+    /** Membership only: the answer depends on which active repositories exist,
+     * never on their rows' state. Effective activity (no trashed or deleted
+     * ancestor) narrows the candidates but is not a consumed fact: a consumer
+     * whose ancestry changes is reconciled through its own rows. */
+    repositoryMembers(): readonly GroundRepositoryMember[];
+    physical(uuid: string): GroundRow | undefined;
+    sharing(uuid: string): SharingGroundRow | undefined;
+    atPath(inventory: GroundInventory, rootUUID: string, relativePath: string): readonly GroundRow[];
+    /** One root's rows at one filesystem object: its identity candidates. */
+    physicalCandidates(inventory: GroundInventory, rootUUID: string, physicalKey: string): readonly GroundRow[];
+    /** Every row naming one filesystem object, in any root: its aliases. */
+    objectRows(inventory: GroundInventory, physicalKey: string): readonly GroundRow[];
+    subtree(inventory: GroundInventory, uuid: string): readonly GroundRow[];
+    /** An active repository's subtree with its placement; undefined for any
+     * other top. The same facts as its subtree. The handle answers after the
+     * snapshot while its view has not moved, and each row it returns is a row
+     * this observation read. */
+    territory(inventory: GroundInventory, uuid: string): TerritoryHandle | undefined;
+    rootsAtPath(inventory: GroundInventory, absolutePath: string): readonly GroundStructure[];
+    structure(inventory: GroundInventory, uuid: string): GroundStructure | undefined;
+    children(inventory: GroundInventory, parentUUID: string): readonly GroundNamespaceEntry[];
+    /** The children holding one portable name: a slot of the child relation,
+     * read by one probe however large the container. */
+    slot(inventory: GroundInventory, parentUUID: string, name: string): readonly GroundNamespaceEntry[];
+    /** A container's complete child relation, each member's whole row. */
+    members(inventory: GroundInventory, parentUUID: string): readonly GroundRow[];
+    /** null means this entire inventory, used only by a complete reconciliation. */
+    inventory(inventory: GroundInventory, rootUUID: string | null): readonly GroundRow[];
+}
+/** The first read fixes S0. Each later read is a late query: it answers with
+ * S0's facts only when every fact it consumed is unchanged since S0, else the
+ * whole observation fails. A later answer never replaces an original one. */
+export interface GroundObservation {
+    read<T>(operation: (reader: GroundSnapshotReader) => T): T;
+    finish(): GroundBasis;
+}
+export type GroundNamespaceEntry = Readonly<Pick<GroundRow, "uuid" | "resourceId" | "rootUUID" | "parentUUID" | "name" | "type" | "status" | "relativePath" | "absolutePath">>;
+export type GroundStructure = GroundNamespaceEntry & {
+    readonly association: {
+        readonly physicalKey: string;
+        readonly kind: number;
+    } | null;
+};
+/** A database incarnation, the sequence S0 it was read at, and the facts it
+ * consumed. Only an open observation can accumulate facts; admission receives
+ * a closed basis. */
+export declare class GroundBasis {
+    #private;
+    private constructor();
+    /** How many facts admission must check; the cost of this basis. */
+    get size(): number;
+    /** Plain evidence of this basis. It lists the facts of a basis small
+     * enough to check one by one and counts a larger one. */
+    describe(): DetectBasisDescriptor;
+    /** What a saver thread needs to accept this basis: its facts, and every
+     * row it may protect. */
+    toData(): GroundBasisData;
+    static fromData(data: GroundBasisData): GroundBasis;
+    /** One basis consuming every part's facts and protecting every part's
+     * rows; all parts were read at one incarnation and S0. */
+    static union(parts: readonly GroundBasis[]): GroundBasis;
+    static observe(database: Database.Database): GroundObservation;
+    static capture<T>(database: Database.Database, operation: (reader: GroundSnapshotReader) => T, late?: LateRead): {
+        value: T;
+        basis: GroundBasis;
+    };
+    /** Same incarnation, and no consumed fact stamped after S0. Never compares
+     * the global counter with S0: unrelated writes do not invalidate. A small
+     * basis looks up each fact; a large one intersects the few facts stamped
+     * since S0, so the check is bounded by the smaller side. */
+    unchanged(database: Database.Database): boolean;
+    /** Every fact of this basis is a fact of one of these, read against the
+     * same incarnation and S0, so their unchanged answers are its answer. No
+     * expectation is merged: all of them are S0. */
+    within(parts: readonly GroundBasis[]): boolean;
+    /** Entities of one inventory written by anyone after S0, and roots whose
+     * visible generation changed after S0, each with the sequence that last
+     * stamped it. Each such root is a responsibility of its own: its rows can
+     * change without their own stamps. */
+    changedSince(database: Database.Database, inventory: GroundInventory): {
+        readonly entities: readonly (readonly [string, bigint])[];
+        readonly roots: readonly (readonly [string, bigint])[];
+    };
+    /** One admission unit's basis: the same incarnation and S0, over only the
+     * facts that unit consumed. Its answers derive from the S0 snapshot, so a
+     * fact unchanged since S0 is exactly the validity condition. An entity is
+     * protected only when the original observation could protect it; a
+     * scoped basis never widens allocation authority. */
+    scope(build: (keys: GroundScope) => void): GroundBasis;
+    /** A scoped inventory protects its existing rows. A proposed destination
+     * cannot prove that a missing UUID was originally absent everywhere. */
+    protects(inventory: GroundInventory, uuid: string, before: GroundRow | undefined): boolean;
+    includesInventory(inventory: GroundInventory, rootUUID: string): boolean;
+    /** May place a row this inventory never held: its root inventory, or its
+     * exact destination slot, was observed free. Identity history remains a
+     * separate proof; revision <= S0 never authorizes resurrection. */
+    allocates(inventory: GroundInventory, after: GroundRow): boolean;
+}
+/** A closed basis as plain data: facts by key, and each inventory's
+ * protected rows. */
+export interface GroundBasisData {
+    readonly incarnation: string;
+    readonly sequence: bigint;
+    readonly facts: readonly string[];
+    readonly protected: Readonly<Record<GroundInventory, readonly string[]>>;
+    readonly inventories: readonly string[];
+}
+/** The facts one admission unit consumed, named by the query arguments that
+ * produced them. */
+export interface GroundScope {
+    entity(inventory: GroundInventory, uuid: string, before: GroundRow | undefined): void;
+    structure(inventory: GroundInventory, uuid: string): void;
+    namespace(inventory: GroundInventory, uuid: string): void;
+    path(inventory: GroundInventory, rootUUID: string, relativePath: string): void;
+    physical(inventory: GroundInventory, rootUUID: string, physicalKey: string): void;
+    roots(inventory: GroundInventory, absolutePath: string): void;
+    repositories(): void;
+    /** Every row this repository owns: the package its Record carries. */
+    territory(inventory: GroundInventory, uuid: string): void;
+}
+export interface GroundTransition {
+    readonly inventory: GroundInventory;
+    readonly before: GroundRow | undefined;
+    readonly after: GroundRow | undefined;
+}
+type Placement = Pick<GroundRow, "parentUUID" | "type" | "status">;
+/** The write changed an active repository's own head only; its placement in
+ * its owner's package, and so that territory, is unchanged. */
+export declare const repositoryHeadOnly: (before: GroundRow | undefined, after: GroundRow | undefined) => boolean;
+/** The nearest active repository strictly above each identity in one graph,
+ * memoized and safe on cycles: the owner whose territory the identity is. */
+export declare function repositoryOwners(lookup: (uuid: string) => Placement | undefined): (uuid: string) => string | null;
+/** Every warm view of one file stops: its receipts may be missing, or the
+ * file closed. */
+export declare function retireGroundViews(file: string): void;
+/** One committed saver write, as the main thread's warm views consume it. */
+export interface GroundReceipt {
+    readonly incarnation: string;
+    readonly sequence: bigint;
+    /** The facts it stamped that a warm view can consume, by key. */
+    readonly stamped: readonly string[];
+    /** Per inventory, v8-serialized `[uuid, row | null, children | null][]`:
+     * each written row a territory can hold, as stored, with a present row's
+     * children whenever the write created or moved a row there, since only
+     * then can a row enter a territory. */
+    readonly written: Partial<Record<GroundInventory, Uint8Array>>;
+}
+export declare function saveGroundReceipts(database: Database.Database, sink: (receipt: GroundReceipt) => void): void;
+export declare function registerReceiptSource(file: string, drain: (() => void) | null): void;
+/** Receipts arrive in sequence order, and the main thread's own writes carry
+ * its views synchronously, so a view exact at an earlier sequence is exact
+ * just before this one. A view this write touches is carried from the rows
+ * it stored; one it cannot carry is dropped. */
+export declare function carryGroundReceipt(file: string, receipt: GroundReceipt): void;
+/** One repository's subtrees as a content thread read them: every inventory
+ * asked, in one read transaction, with the incarnation and sequence that
+ * transaction read, so each is exact at that sequence by construction. */
+export interface TerritoryRead {
+    readonly incarnation: string;
+    readonly sequence: bigint;
+    /** Per inventory asked, in order: its subtree's pages (`subtreePages`), or
+     * none when its top is no active repository. */
+    readonly subtrees: readonly (readonly Uint8Array[] | null)[];
+}
+/** On a content thread's read-only connection. */
+export declare function readTerritories(database: Database.Database, uuid: string, inventories: readonly GroundInventory[]): TerritoryRead;
+/** Outside every snapshot, before one reads these repositories: the views no
+ * snapshot would find exact are read off this thread (`read`), built a page
+ * per step, and kept once a short read finds them exact now; each pair's
+ * agreement is compared a few rows per step. A view some write moved after
+ * its read is read again, a few times at most; one still moving is left to
+ * the snapshot, which reads it inside itself. */
+export declare function prepareTerritories(database: Database.Database, repositories: Iterable<string>, read: (uuid: string, inventories: readonly GroundInventory[]) => Promise<TerritoryRead>): Promise<void>;
+/** Stamps every fact these committed transitions change, and the activation
+ * vector of each root whose visible generation this transaction changed,
+ * with one new sequence, inside the caller's write transaction. Returns the
+ * stamp count and the step the caller runs after its outermost commit.
+ *
+ * A row placed where none stood, in a root whose first generation this
+ * transaction installs, beneath a parent placed the same way or none, is
+ * stamped by that vector alone. Every earlier answer it could join was
+ * empty of it and consumed that root's activation or `*`: an answer keyed
+ * inside the root names the root, one keyed by an absent identity or an
+ * object names `*`, and the aggregates and the root rows' namespaces
+ * are the vector's. A child list of a parent that stood consumed its own
+ * root's activation, so a row placed beneath one is stamped as usual. An
+ * installation therefore stamps a few facts however many rows it places,
+ * and no territory can hold its rows unless its activation is stamped. */
+export declare function advanceGroundBasis(database: Database.Database, transitions: Iterable<GroundTransition>, activated: Iterable<string>, outermost: boolean): {
+    readonly writes: number;
+    readonly committed: () => void;
+};
+export {};