@volter/world-core 2.0.0

package/dist/src/log.d.ts

@@ -0,0 +1,254 @@
+import { type HistoryLayout } from './history.js';
+import type { SubjectFields } from './hash.js';
+import type { WorldServiceEvent } from './types.js';
+import type { TwinResource } from './serve.js';
+/** The vendor's answer to one entry, on the entry itself. `landed` = on the parent, waiting;
+ *  `deployed` = performed against the vendor; `refused` = a check said no; `failed` = the vendor
+ *  said no; `skipped` = after a failure. */
+export type Receipt = {
+    status: 'landed' | 'deployed' | 'refused' | 'failed' | 'skipped';
+    at: string;
+    /** the id the vendor minted, when it differs from the local one */
+    externalId?: string;
+    url?: string;
+    /** the check that refused, or the vendor's words */
+    reason?: string;
+    data?: Record<string, unknown>;
+};
+export type EntryOp = 'set' | 'revert';
+/** One line of a log. `TwinAction` in actions.ts is this type by another name; every field a
+ *  write records lives here. */
+export type Entry = {
+    /** where the entry came from when not this branch's own write: the placeholder origin (the default data) */
+    provenance?: 'placeholder';
+    /** the observation this entry was folded in (a refresh): one id per look; no position falls inside one */
+    batch?: string;
+    id: string;
+    service: string;
+    op: EntryOp;
+    subject: {
+        type: string;
+        id: string;
+    };
+    occurredAt: string;
+    operation?: string;
+    actor?: {
+        kind: 'agent' | 'human' | 'bot' | 'system';
+        id?: string;
+    };
+    fields?: SubjectFields;
+    projection?: {
+        creates?: Array<{
+            type: string;
+            id: string;
+            fields: SubjectFields;
+        }>;
+        updates?: Array<{
+            type: string;
+            id: string;
+            fields: SubjectFields;
+        }>;
+        deletes?: Array<{
+            type: string;
+            id: string;
+        }>;
+        emits?: Array<{
+            kind: 'webhook' | 'event' | 'notification';
+            target: string;
+            payload: Record<string, unknown>;
+        }>;
+    };
+    revertsActionId?: string;
+    /** a landed copy: the local entry id this row lands (its subject may carry the vendor's id) */
+    landsId?: string;
+    /** a landed copy under the vendor's id: the local subject id it stands for */
+    aliasOf?: string;
+    receipt?: Receipt;
+    /** a v1 observed row kept verbatim for `listEvents`; folds nothing unless `fields` was derived */
+    event?: WorldServiceEvent;
+    [extra: string]: unknown;
+};
+/** A BRANCH IS A POINTER (contract "Just like Neon", 1): its parent — a world at a path, or an origin at
+ *  a URL — and the POSITION in the parent's whole log this branch starts from. A path parent is read
+ *  through its immutable view, never its mutable current pointer; a URL parent uses a retained
+ *  cache view. Only rebase or acknowledged push moves the selected view and position. */
+export type BranchMeta = {
+    parent?: {
+        at: string;
+        position: number;
+        view?: string;
+        remoteView?: string;
+        generation?: string;
+        directory?: string;
+        viewDirectory?: string;
+    };
+    branchedAt?: string;
+    origin?: import('./history.js').HistoryOrigin;
+    fetchedOrigin?: import('./history.js').HistoryOrigin;
+    previousParents?: Array<{
+        directory: string;
+        generation: string;
+    }>;
+};
+export declare const CHECKPOINT_EVERY = 100;
+export declare const DELTA_SUFFIX = ".delta";
+export declare function parentLogPath(service: string, root?: string): string;
+export declare function branchLogPath(service: string, root?: string): string;
+export declare function branchMetaPath(service: string, root?: string): string;
+/** The fetched cache of a URL parent's whole log — what `fetch` extends and a read folds up to the position. */
+export declare function originLogPath(service: string, root?: string): string;
+/** A parent is at a URL when it is not a path on this machine. */
+export declare function isUrlParent(at: string): boolean;
+export declare function checkpointPath(service: string, root?: string): string;
+export declare function readBranchMeta(service: string, root?: string): BranchMeta | null;
+export declare function writeBranchMeta(service: string, meta: BranchMeta, root?: string): void;
+/** A v1 observed row as an entry: a delta event folds its `changed.*.after`; anything else folds
+ *  nothing and rides along for `listEvents`. An entry row is itself. */
+export declare function toEntry(row: Record<string, unknown>): Entry;
+/** An entry as a v1 observed row: its own row when it came from one, else a delta event. */
+export declare function toEvent(entry: Entry): WorldServiceEvent;
+/** This root's own branch-log rows. */
+export declare function branchEntries(service: string, root?: string): Entry[];
+/** The parent as this branch sees it: the base world's view at the branch position (its parent
+ *  log to `parentCount`, its branch log to `branchCount`), then everything this root's own parent
+ *  log holds (fetched, refreshed or landed since). An unbranched root is just its own parent log. */
+export declare function parentEntries(service: string, root?: string, seen?: Set<string>): Entry[];
+/** The fetched cache of a URL parent's whole log (every entry fetched so far, past the position too). */
+export declare function originEntries(service: string, root?: string): Entry[];
+/** Extend the cache with one of the parent's entries; deduplicated by id. */
+export declare function appendOriginEntry(entry: Entry, root?: string): {
+    appended: boolean;
+};
+/** Where the parent stands now: the length of its whole log (live at a path, the cache for a URL). */
+export declare function parentPosition(service: string, root?: string): number | null;
+/** Ids the parent holds, including the local ids its landed copies stand for. */
+export declare function landedIds(parent: Entry[]): Set<string>;
+/** The vendor-minted id per local subject: every landed copy that carries `aliasOf`. A local id the
+ *  vendor itself holds names the vendor's subject, never the alias: a World that minted a local id
+ *  before it had observed the vendor's own subject under that id (its tree was behind) must not fold
+ *  the vendor's subject onto the landed one, nor send a caller who addresses the vendor's id there. */
+export declare function aliasesFrom(parent: Entry[]): Map<string, string>;
+type Subject = {
+    type: string;
+    id: string;
+    updatedAt: string;
+    fields: SubjectFields;
+};
+export type Tree = Map<string, Subject>;
+/** Fold entries onto a tree, in order: `set` overlays its fields and applies its projection; a
+ *  reverted entry folds nothing; a `confirm` row (v1) folds nothing. `skip` names entries the
+ *  parent already holds. */
+export declare function foldEntries(tree: Tree, entries: Entry[], skip?: Set<string>): void;
+/** Fold aliases: whatever still sits under a local id (a later local update against the id the
+ *  caller holds) folds onto the vendor's row. */
+export declare function foldAliases(tree: Tree, aliases: Map<string, string>, service?: string, only?: Set<string>): void;
+export declare function treeResources(tree: Tree): TwinResource[];
+/** A copy of a resource a reader may change: its fields, and the vendor's own id/type/updatedAt it keeps beside them. */
+export declare function copyResource(r: TwinResource): TwinResource;
+/** A resource's own fields, the vendor's way: the subject's address stripped, its own `id`/`type`/`updatedAt` restored when it had them. */
+export declare function ownFields(r: TwinResource): Record<string, unknown>;
+export declare function dropCheckpoint(service: string, root?: string): void;
+/** Preserve each ancestor's observed-then-local overlay, including landed IDs and aliases. */
+export declare function foldHistory(entries: Entry[], layout: HistoryLayout, service?: string): Tree;
+export declare function readTree(service: string, root?: string, opts?: {
+    until?: string;
+    at?: number;
+    view?: string;
+}): TwinResource[];
+/** The upstream view for observation diffing, without this root's local overlay. Inherited
+ *  history keeps its own layout: an ancestor's local writes are part of our pinned base. */
+export declare function readParentTreeMap(service: string, root?: string): Tree;
+/** What a service's PARENT side at `root` is folded from (its parent log, branch.json and inherited history), as one
+ *  string: while it stands, its aliases and landed ids are the same, whatever the branch's own log does. */
+export declare function parentStamp(service: string, root?: string): string;
+/** What a service's tree (and every subject's history) at `root` is folded from, as one string: while it
+ *  stands, nothing was written. A pack that projects the tree into its own state memoizes on it. */
+export declare function treeStamp(service: string, root?: string): string;
+export declare function readTreeMap(service: string, root?: string, opts?: {
+    until?: string;
+    at?: number;
+    view?: string;
+}): Tree;
+/** What changed in a service's tree since `since` (a `treeStamp` an earlier read was made at): the subjects
+ *  written since, as resources; the keys (`type:id`) of those no longer in the tree; and, of the changed, the keys
+ *  now at the tree's end in the order they stand there (new to the tree, or deleted and made again), which a
+ *  projection kept in the tree's order moves to its end in that order, updating the rest where they stand.
+ *  `undefined` when this process cannot say (no memo, the parent moved, a revert, or `since` older than the memo
+ *  remembers): the caller refolds. `stamp` is the state the answer brings the caller to. */
+export declare function treeChangesSince(service: string, root: string | undefined, since: string): {
+    stamp: string;
+    changed: TwinResource[];
+    removed: string[];
+    appended: string[];
+} | undefined;
+export declare function cutCheckpoint(service: string, root?: string): void;
+/** The branch's entries the parent does not hold: `set` rows, not reverted, not landed. */
+export declare function unpushedEntries(service: string, root?: string): Entry[];
+/** The position a branch is cut at: how far the parent view and the branch log reach right now. */
+/** THE POSITION (contract "Just like Neon", 2): where this twin's whole log stands — one number, the
+ *  count of entries, parent view then branch. Durable cuts pair it with an immutable view ID. */
+export declare function position(service: string, root?: string): number;
+/** The position of a twin's log at an instant: the entries that had occurred by then. */
+export declare function positionAt(service: string, instant: string, root?: string, view?: string): number;
+/** The batch a position would split, if any: `position` entries taken, and the next entry belongs to the
+ *  same observation as the last one taken. Answers the boundaries a caller may use instead. */
+export declare function splitsBatch(service: string, position: number, root?: string): {
+    batch: string;
+    from: number;
+    to: number;
+} | null;
+/** Refuse a position inside an observation, naming the boundaries. */
+export declare function assertBatchBoundary(service: string, position: number, root?: string): void;
+/** A landed copy of `entry` for the parent log: the receipt on it, the vendor's id as its subject
+ *  when one was minted. Deterministic id, so landing twice is the same row. */
+export declare function landedCopy(entry: Entry, receipt: Receipt, opts?: {
+    vendorSubjectId?: string;
+    fields?: SubjectFields;
+    subject?: {
+        type: string;
+        id: string;
+    };
+}): Entry;
+export declare function appendParentEntry(entry: Entry, root?: string): {
+    appended: boolean;
+};
+/** The whole log of a twin as a served world hands it out: the parent view, then the branch's own
+ *  entries, one sequence with a position. A clone's parent is exactly this. */
+export declare function wholeLog(service: string, root?: string): Entry[];
+/**
+ * REBASE a branch onto its base's current position (contract: "rebase replays the branch's
+ * entries over a newer base, conflicts per subject and field"). A branch is a pointer, so the
+ * base moving is invisible until this: the pointer advances to the base's present position, the
+ * branch's own entries stay in place and now fold over the moved base, and every entry whose
+ * preconditions no longer hold against the new parent tree is named as a conflict — data on the
+ * result, never a stop. An unbranched world (no pointer) has nothing to rebase.
+ */
+export declare function rebaseBranch(service: string, root?: string, opts?: {
+    origin?: boolean;
+}): {
+    moved: boolean;
+    from: number;
+    to: number;
+    conflicts: Array<{
+        entryId: string;
+        subject: {
+            type: string;
+            id: string;
+        };
+        field: string;
+        op: string;
+        expected?: unknown;
+        actual?: unknown;
+    }>;
+};
+/**
+ * HISTORY through the kernel: every entry that touched a subject (or every subject of a type), parent
+ * log then branch log, in order, with reverted entries dropped and landed copies shown once. A pack
+ * that serves a changelog (Jira's), or must never reuse an id it once minted, reads this — never a
+ * log file. Each entry's `fields` is what it set; the fold is the reader's.
+ */
+export declare function subjectHistory(service: string, subject: {
+    type: string;
+    id?: string;
+}, root?: string): Entry[];
+export {};