@cruba/crubal-postgres 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @cruba/crubal-postgres
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The persistent CRUBAL store on Postgres: the log as the truth, every other table a cache rebuilt from it.
+The design is in [docs/design/store.md](../../docs/design/store.md); this package is its first version.
+
+## What it does
+
+- **One owner, one chain, one `PgStore`.** `commit(by, mutate, at?, extra?)` runs an operation on a draft
+  of the owner's state, turns what changed into one entry, applies it with the engine's own `applyEntry`,
+  persists the difference and appends the entry, all in one transaction with the chain row locked. A
+  refusal rolls everything back. `append(entry)` takes an entry made elsewhere and links it the same way.
+- **The schema** (`src/schema.sql`) is the design's tables, every one keyed by owner. The log table's only
+  update is redaction; a trigger refuses every other update and every delete.
+- **`rebuild()`** empties the owner's state tables and applies the log again. **`verify(keys?)`** checks
+  the chain's links and signatures. **`redact(logId, writeIndex?)`** replaces one write by its hash, or
+  an entry by its hash (spec 8.5.2), then rebuilds, so the cache forgets what the log forgot.
+- **Nothing in here decides anything.** Folding, rules, access, lifecycle and views are `@cruba/crubal`'s
+  and run unchanged; this package loads a working set, persists a difference and keeps the chain.
+
+## Proof
+
+`test/pg.test.ts` runs against a real Postgres when `CRUBAL_PG_URL` is set (a local Postgres 17 is
+enough: `CRUBAL_PG_URL=postgres:///postgres npm test`), in a schema of its own that it drops afterwards,
+and is skipped otherwise. It checks that every corpus log rebuilds to the same state in Postgres as in
+memory, that journaled operations (attach, merge, archive with cascade) write the same entries as the
+memory journal and leave the same state, that redacting a write keeps the chain valid and the rebuilt
+state without the value while the trigger refuses any other change, and that owners never see each other.
+
+## The working set
+
+An operation runs over a working set that loads as it is needed (`src/working.ts`). The engine is
+synchronous and pure, so the operation runs on a set that answers what it has and notes what it lacks (a
+record by ID, the records at a level, a record's children, a `for`'s targets, the holders of a key, a
+binding, a run); the store loads what was lacking and runs the operation again on a fresh copy, until a
+run asks for nothing new. Edges, instructions and definitions are loaded whole, being small. The entry's
+application settles the same way, so an attach among sixty records loads the two it touches and their
+neighbours, never the sixty. `store.trace` says what the last operation loaded. An operation passed to
+`commit` MUST therefore be a pure function of the draft it is given: it may be run more than once.
+
+## Projections and the stream
+
+A store given `projecting: { dict, views, perms? }` marks, inside each write's transaction, the rows the
+entry made stale: for every record it changed, in every view, what the engine's `staleAfter` names, worked
+out on the state before the entry (`src/projector.ts`). `project(view?, audience?)` publishes outside any
+write transaction: the first time (and after a new version) it rebuilds every row, afterwards only the
+marked ones, through the engine's `Views` over a working set that loads what the view reads; it compares
+them with the stored projection, appends one stream entry per row that changed or left, numbered per view
+and audience, and clears the marks. `entriesSince(view, seq)` is what an index reads from its cursor.
+With `fresh: "write"` every commit publishes as soon as it returns. The test replays the corpus stream case
+(views/010) and the erasure removal (views/013) and gets the memory `Views.stream` entries byte for byte.
+
+## The border
+
+`PgBorder` runs contracts over the store (`src/border.ts`): each run builds the engine's `Exchange` over
+the commit's draft, with the store's edges, its run count and the keys it has acted on, so a run is one
+entry and never acts twice across restarts. `receive` and `arrive` keep the intake record with its bytes
+and hash in the `intake` table; `send` acts at most once per contract, record and payload; `streamRun`
+reads the projection stream from the store's tables since the index's cursor (or the caller's), refuses a
+view above public to a party without `run`, and logs each batch as a run; `ack` keeps the cursor;
+`tick` runs a scheduled contract's due ticks from the `schedules` table, each keyed by contract and
+tick. `store.erase(record)` redacts every value write to a record across the log and leaves its shell.
+
+## The command
+
+`bin/crubal-pg.ts`, with `CRUBAL_PG_URL` set: `migrate`, `rebuild <owner>`, `verify <owner>`,
+`export <owner>`, `redact <owner> <log> [<write>]`, `erase <owner> <record>`, `project <owner> --defs
+<file>…` and `tick <owner> <contract> --now <moment> --defs <file>…`.
+
+## Installing, and definitions from the store
+
+`store.install(bundle, keys)` takes a published version (docs/design/publishing.md): it refuses an unsigned
+bundle unless the store allows them for development, a bundle whose hash or signature doesn't verify, a
+language version above the store's, and a bundle whose `extends` aren't installed at their pinned
+versions; it checks the definitions that would result with every publish check; then it writes one
+`install` entry, keeps the bundle in `bundles`, and, when an earlier version of the package was installed,
+restamps every record through the bundle's recipes from that version, each write `by: migration`, and
+leaves every view to be rebuilt. `store.define(member)` is the owner's own change: checked with the rest,
+then one `define` write. `store.definitions()` builds what the engine runs with from the installed bundles
+in order and then the define writes, cached per chain head; the projector and `PgBorder.over(store)` take
+their dictionary, views, contracts and permissions from it, so nothing is handed in any more except in
+tests.
+
+## Sends with a real act
+
+A send over the store is two entries with the act between them (docs/design/runs.md): `prepare` logs
+`started` with the idempotency key and the payload's hash, the payload itself kept in `outtake`; the
+contract's adapter (`adapters: { [contract]: (contract, payload, run) => … }`, host code, never a
+package's) acts outside any transaction; then `acted` or `failed` with its attempt. A run still open
+(`started`, or `failed` with attempts left under `retry`) is seeded into every fresh border from the runs
+table, so a restart never acts twice and `retry(run)` acts again from the kept payload without re-mapping.
+After the last attempt a review item `run:<contract>` opens. An answer the adapter brings back closes the
+run as a receive with `via` that run; `undo(run)` runs the reversing contract naming its cause; `erase`
+takes the record's outtake rows with its values.
+
+## Review decisions and replay
+
+`store.review()` lists the open items; `store.decide(decision, by)` makes one as one entry (the review
+write with the define, value or release it causes), then replays every kept intake the decision reaches (a
+facet's new value, a contract's unknown field, a unit's spelling), each its own entry `by: migration:
+replay`, superseding what that intake landed before and leaving the rest to the trust order. A `units`
+define feeds the owner's extension into the units table in force (one owner per process for now). A dead
+run's `retry` releases its key, so a fresh border sends the payload again. An observation run loads the
+observations supporting the record and its parent, and the open split items on them, apart from the draft;
+at the package's `split` threshold the border opens `split:<record>`, and the decision `split` mints the
+version and moves the instances.
+
+## What a commit refuses
+
+Every entry is checked in the same run that applies it (so what the check reads loads too): a person
+owning what the package's `ownership` doesn't allow (14.1), a record wearing a class not for its kind or
+classes whose meet is empty (5.5), `within` forming a cycle or crossing owners (14.2), and every edge
+written (14.12). An emergency edge is the host's to check against its published terms (14.13).
+
+## Hosted persons (14.1)
+
+A record owned `<owner>:<id>` is a hosted person's: the writes to it leave the owner's entry and become
+one entry per person in that person's chain, linked and signed (with the `hostedSigner` the host hands
+the store) in the same transaction; the chains lock in a fixed order. A rebuild applies the owner's chain
+and the hosted chains in the order they were written (`log.ord`); erase redacts in every chain.
+
+`store.drain(rate)` and `crubal-pg drain <owner> [--rate N]` apply pending instructions to at most that
+many records per call, each its own entry `by: migration: drain`.
+
+## Not yet here
+
+The host: authentication, secrets, named adapters, signing, the loops and the HTTP surface
+(docs/design/host.md); forms as data (docs/design/index-and-forms.md).

package/dist/bin/crubal-pg.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/crubal-pg.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// crubal-pg: operate a CRUBAL store on Postgres (docs/design/store.md). CRUBAL_PG_URL names the database.
+//   crubal-pg migrate                               create or update the tables
+//   crubal-pg rebuild <owner>                       empty the owner's state tables and apply the log again
+//   crubal-pg verify <owner> [--keys <file>]        check the chain's links and signatures
+//   crubal-pg export <owner>                        the owner's log, as JSON
+//   crubal-pg redact <owner> <log> [<write>]        redact one write (by index) or the whole entry
+//   crubal-pg erase <owner> <record>                redact every value write to a record
+//   crubal-pg dry-run <owner> <bundle.json>         what installing the version would restamp, without writing
+//   crubal-pg drain <owner> [--rate N]              apply pending instructions to at most N records (default 100)
+//   crubal-pg project <owner> --defs <file>...      publish every view's stale rows
+//   crubal-pg tick <owner> <contract> --now <moment> --defs <file>...   run a scheduled contract's due ticks
+import { readFileSync } from "node:fs";
+import { emptyDictionary, readDefinitions } from "@cruba/crubal";
+import { readContracts } from "@cruba/crubal";
+import { readViews } from "@cruba/crubal";
+import { readAccess } from "@cruba/crubal";
+import { PgBorder } from "../src/border.js";
+import { connect, migrate, transaction } from "../src/db.js";
+import { PgStore } from "../src/store.js";
+const [cmd, owner, ...rest] = process.argv.slice(2);
+const flag = (name) => rest.flatMap((a, i) => (a === name ? [rest[i + 1]] : []));
+const flags = (name) => {
+    const out = [];
+    let on = false;
+    for (const a of rest) {
+        if (a.startsWith("--"))
+            on = a === name;
+        else if (on)
+            out.push(a);
+    }
+    return out;
+};
+function definitions() {
+    const dict = emptyDictionary();
+    const texts = flags("--defs").map((f) => readFileSync(f, "utf8"));
+    for (const t of texts)
+        readDefinitions(t, dict);
+    const all = texts.join("\n");
+    const views = readViews(all);
+    const { perms } = readAccess(all);
+    return { dict, views, perms, contracts: readContracts(all) };
+}
+async function main() {
+    const pool = connect();
+    try {
+        if (cmd === "migrate") {
+            await transaction(pool, (c) => migrate(c));
+            console.log("migrated");
+            return 0;
+        }
+        if (!owner)
+            return usage();
+        if (cmd === "rebuild") {
+            const state = await new PgStore(pool, owner).rebuild();
+            console.log(`rebuilt ${owner}: ${state.records.size} records`);
+            return 0;
+        }
+        if (cmd === "verify") {
+            const keysFile = flag("--keys")[0];
+            const keys = keysFile ? (JSON.parse(readFileSync(keysFile, "utf8")).keys ?? JSON.parse(readFileSync(keysFile, "utf8"))) : undefined;
+            const v = await new PgStore(pool, owner).verify(keys);
+            console.log(JSON.stringify(v));
+            return v.valid ? 0 : 1;
+        }
+        if (cmd === "export") {
+            console.log(JSON.stringify(await new PgStore(pool, owner).entries(), null, 2));
+            return 0;
+        }
+        if (cmd === "redact" && rest[0]) {
+            await new PgStore(pool, owner).redact(rest[0], rest[1] !== undefined && !rest[1].startsWith("--") ? Number(rest[1]) : undefined);
+            console.log(`redacted ${rest[0]}${rest[1] ? ` write ${rest[1]}` : ""}`);
+            return 0;
+        }
+        if (cmd === "drain") {
+            const r = await new PgStore(pool, owner).drain(Number(flag("--rate")[0] ?? 100));
+            console.log(`drained ${owner}: ${r.applied.length} records, ${r.remaining} still waiting`);
+            return 0;
+        }
+        if (cmd === "dry-run" && rest[0]) {
+            const bundle = JSON.parse(readFileSync(rest[0], "utf8"));
+            console.log(JSON.stringify(await new PgStore(pool, owner).dryRun(bundle), null, 2));
+            return 0;
+        }
+        if (cmd === "erase" && rest[0]) {
+            const r = await new PgStore(pool, owner).erase(rest[0]);
+            console.log(`erased ${rest[0]}: ${r.redacted} writes redacted${r.witnessed.length ? `; witnessed entries left as they are: ${r.witnessed.join(", ")}` : ""}`);
+            return 0;
+        }
+        if (cmd === "project") {
+            const d = definitions();
+            const entries = await new PgStore(pool, owner, { projecting: { dict: d.dict, views: d.views, perms: d.perms } }).project();
+            console.log(`published ${entries.length} entries`);
+            return 0;
+        }
+        if (cmd === "tick" && rest[0]) {
+            const d = definitions();
+            const now = flag("--now")[0] ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+            const store = new PgStore(pool, owner, { projecting: { dict: d.dict, views: d.views, perms: d.perms } });
+            const r = await new PgBorder(store, { dict: d.dict, contracts: d.contracts, perms: d.perms }).tick(rest[0], now);
+            console.log(JSON.stringify(r, null, 2));
+            return 0;
+        }
+        return usage();
+    }
+    finally {
+        await pool.end();
+    }
+}
+function usage() {
+    console.log("usage: crubal-pg migrate | rebuild <owner> | verify <owner> [--keys <file>] | export <owner> | redact <owner> <log> [<write>] | erase <owner> <record> | dry-run <owner> <bundle.json> | drain <owner> [--rate N] | project <owner> --defs <file>... | tick <owner> <contract> --now <moment> --defs <file>...");
+    return 2;
+}
+process.exit(await main());
+//# sourceMappingURL=crubal-pg.js.map

package/dist/bin/crubal-pg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crubal-pg.js","sourceRoot":"","sources":["../../bin/crubal-pg.ts"],"names":[],"mappings":"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"}

package/dist/src/border.d.ts

@@ -0,0 +1,122 @@
+import { type Permissions } from "@cruba/crubal";
+import type { Dictionary } from "@cruba/crubal";
+import { Exchange, type Role, type RunResult } from "@cruba/crubal";
+import type { JsonObject, Record } from "@cruba/crubal";
+import type { Rule } from "@cruba/crubal";
+import { type Contract } from "@cruba/crubal";
+import type { Offer } from "@cruba/crubal";
+import type { PgStore } from "./store.ts";
+/** What performs a run's act (7.4 step 4): the host's code for a system; never a package's. */
+export type Adapter = (contract: Contract, payload: JsonObject, run: string) => Promise<{
+    acted: true;
+    body?: string;
+} | {
+    failed: string;
+}>;
+export type BorderOptions = {
+    dict: Dictionary;
+    contracts: Contract[];
+    roles?: Role[];
+    rules?: Rule[];
+    perms?: Permissions;
+    adapters?: {
+        [contract: string]: Adapter;
+    };
+    versions?: JsonObject;
+    thresholds?: {
+        confirm?: number;
+        split?: number;
+    }; /** The id prefix an arrival takes per level (`organization: "Z"`); the level's first letter otherwise. */
+    idPrefixes?: {
+        [level: string]: string;
+    };
+};
+/** The border's options from the store's own definitions (docs/design/publishing.md). */
+export declare function borderOptions(store: PgStore): Promise<BorderOptions>;
+/**
+ * A system acting for a person (14.9): the run's caller is the person, whose access is capped to the items
+ * they chose and gated until they lifted it; the entry names the system as `caller` and the person as
+ * `for`; a write that grants onward, or runs under an emergency edge, is refused.
+ */
+export type Acting = {
+    system: string;
+    person: string;
+    items?: string[];
+    gated?: boolean;
+};
+export declare class PgBorder {
+    readonly store: PgStore;
+    readonly o: BorderOptions;
+    readonly contracts: Map<string, Contract>;
+    /** Set for one request when a system acts for a person (14.9); every run of this border then runs as the person. */
+    acting?: Acting;
+    constructor(store: PgStore, o: BorderOptions);
+    /** The person's access, narrowed as they chose (14.9), laid over the owner's access for this run. */
+    private cap;
+    /** Refuse what a system acting for a person may never do (14.9, 14.12 items 8 and 9). */
+    private refuseActing;
+    /** A border over a store's own definitions. */
+    static over(store: PgStore): Promise<PgBorder>;
+    private get owner();
+    /** Runs so far and the keys acted on, from the runs table, so a fresh Exchange continues where the last left off. */
+    private past;
+    /**
+     * One border run as one entry: the Exchange is built over the draft, with the store's edges, runs and
+     * keys; `fn` runs it; its changes and its run write become the entry. The function MUST be pure over the
+     * draft (it may run more than once while the working set loads).
+     */
+    /** The highest number behind each id prefix the owner has (`P-` → 3050), so an arrival mints the next (9.2a). */
+    private idCounts;
+    run<T extends RunResult>(fn: (ex: Exchange) => T, at?: string, seed?: {
+        observations?: JsonObject[];
+        review?: JsonObject[];
+    }): Promise<T>;
+    /** Keep an intake record with its bytes (9.1), beside the log. */
+    private keepIntake;
+    /** A receive contract's run on a record (7.4 steps 5–6), its intake kept; with `forRun`, a late answer closing that run. */
+    receive(name: string, recordId: string, body: string, callerId?: string, at?: string, forRun?: string): Promise<RunResult>;
+    /** An arrival (9.2a): the payload finds or makes its record; its intake kept. */
+    arrive(name: string, body: string, level: string, callerId?: string, of?: string, at?: string, within?: string): Promise<RunResult>;
+    /**
+     * A send (7.4, docs/design/runs.md): `started` in one entry with the payload kept in outtake, the adapter
+     * outside any transaction, then `acted` or `failed` in another; an answer the adapter brings back closes
+     * the run as a receive. Without an adapter the act is nothing and the run is acted.
+     */
+    send(name: string, recordId: string, callerId?: string, at?: string): Promise<RunResult>;
+    /** The act and what follows it: acted or failed, and the answer landed against the run. */
+    private act;
+    /** Try a failed run again from its kept payload (7.5 `retry`), never re-mapping it. */
+    retry(run: string, callerId?: string, at?: string): Promise<RunResult>;
+    /** What an observation run reads (9.7.3): the observations supporting the record or its parent, and the open split items on them. */
+    private evidenceFor;
+    /** The owner's offer (7.8), with the signed log entries its values came from, for another owner's take. */
+    offer(name: string, only?: string[]): Promise<Offer>;
+    /** A take (7.8) of a presenter's record into one of ours, by the offer's mode; one entry naming the presenter's. */
+    take(takeName: string, offer: Offer, recordId: string, presenter: Record, callerId?: string, at?: string): Promise<RunResult>;
+    /** Taken values past their terms (7.8): removed, one entry per record. */
+    expire(now: string, at?: string): Promise<string[]>;
+    /** A decision on a dead run (runs.md): retry (a new run, the key released) or drop; then the act for a retry. */
+    decideRun(run: string, decision: "retry" | "drop", callerId?: string, at?: string): Promise<RunResult>;
+    /** Run the contract that reverses a run (7.5 `undo`), naming its cause. */
+    undo(run: string, callerId?: string, at?: string): Promise<RunResult>;
+    /** The stored cursor of a stream contract for a view, when it is for the view's current version. */
+    private cursorOf;
+    /**
+     * A stream contract's run (12.6.2): the entries of each view since the cursor, pushed (the stored
+     * cursor) or pulled (the caller's). A view above public goes only to a party holding `run` for the
+     * contract. A batch with entries is logged as a run keyed by the contract, the views and the ranges.
+     */
+    streamRun(name: string, callerId?: string, cursor?: {
+        [view: string]: number;
+    }, at?: string): Promise<RunResult>;
+    /** An index acknowledges the last `seq` it holds per view (12.6.2); the store resumes from the next. */
+    ack(name: string, cursor: {
+        [view: string]: number;
+    }): Promise<RunResult>;
+    /**
+     * A scheduled contract's tick (7.11): every tick due since the last one runs (or the latest, or none,
+     * by `missed`), each keyed by the contract and the tick so a restarted host never runs one twice. The
+     * schedule begins at the first clock reading.
+     */
+    tick(name: string, now: string, callerId?: string): Promise<RunResult>;
+}