@cruba/crubal-postgres 0.0.0-stage → 0.3.0

package/dist/src/state.js

@@ -0,0 +1,138 @@
+// state.ts: an owner's state in the tables, read into the engine's State and written back as the diff of
+// two states. The engine's applyEntry is the one meaning of a write; this file only persists its result,
+// so the Postgres store can never apply an entry differently from the memory one.
+import { serialize } from "@cruba/crubal";
+import { emptyState } from "@cruba/crubal";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** A record as the engine holds it, from its row. Absent members stay absent. */
+export function recordOf(row) {
+    const doc = (row.doc ?? {});
+    // The row's owner is the store's; the record's own owner (a hosted person's, another owner's) is in doc.
+    const r = { id: String(row.id), kind: String(row.kind), level: String(row.level), owner: String(doc.owner ?? row.owner), values: (doc.values ?? {}) };
+    if (row.of)
+        r.of = String(row.of);
+    if (row.within)
+        r.within = String(row.within);
+    if (row.status)
+        r.status = row.status;
+    if (row.applied)
+        r.applied = row.applied;
+    if (Array.isArray(row.wears) && row.wears.length)
+        r.wears = row.wears.map(String);
+    if (row.created)
+        r.created = String(row.created);
+    if (row.updated)
+        r.updated = String(row.updated);
+    const extra = r;
+    for (const m of ["parts", "sources", "alternatives", "suggestions", "held"])
+        if (doc[m] !== undefined)
+            extra[m] = doc[m];
+    return r;
+}
+/** The members of a record that live in `doc`, not in a column. */
+function docOf(r) {
+    const x = r;
+    const doc = { owner: r.owner, values: r.values };
+    for (const m of ["parts", "sources", "alternatives", "suggestions", "held"])
+        if (x[m] !== undefined)
+            doc[m] = x[m];
+    return doc;
+}
+/** Every record up a record's `within` chain (14.2), nearest first. */
+function ancestorsOf(records, r) {
+    const out = [];
+    const seen = new Set([r.id]);
+    let cur = r.within;
+    while (cur && !seen.has(cur)) {
+        out.push(cur);
+        seen.add(cur);
+        cur = records.get(cur)?.within;
+    }
+    return out;
+}
+/** Read an owner's whole state. Order is the order the log made things, by `ord`. */
+export async function loadState(client, owner) {
+    const state = emptyState();
+    const q = async (sql) => (await client.query(sql, [owner])).rows;
+    for (const row of await q("select * from records where owner = $1 order by ord"))
+        state.records.set(String(row.id), recordOf(row));
+    for (const row of await q("select edge, json from edges where owner = $1 order by ord"))
+        state.edges.set(String(row.edge), row.json);
+    for (const row of await q("select key, record from bindings where owner = $1 order by ord"))
+        state.bindings.set(String(row.key), String(row.record));
+    for (const row of await q("select issuer, json from instructions where owner = $1 order by issuer, n")) {
+        const issuer = String(row.issuer);
+        state.instructions.set(issuer, [...(state.instructions.get(issuer) ?? []), row.json]);
+    }
+    for (const row of await q("select json from observations where owner = $1 order by ord"))
+        state.observations.push(row.json);
+    for (const row of await q("select json from review where owner = $1 order by ord"))
+        state.reviews.push(row.json);
+    for (const row of await q("select run, json from runs where owner = $1 order by ord"))
+        state.runs.set(String(row.run), row.json);
+    for (const row of await q("select json from installed where owner = $1 order by ord"))
+        state.installed.push(row.json);
+    for (const row of await q("select json from reads where owner = $1 order by ord"))
+        state.reads.push(row.json);
+    for (const row of await q("select key, json from definitions where owner = $1 order by ord"))
+        state.definitions.set(String(row.key), row.json);
+    return state;
+}
+/** Write what changed between two states of one owner: upserts, deletes, and appends to the lists. */
+export async function persist(client, owner, before, after) {
+    const changed = (a, b) => serialize((a ?? null)) !== serialize((b ?? null));
+    const beforeRecords = new Map(Map.prototype.entries.call(before.records));
+    for (const [id, r] of Map.prototype.entries.call(after.records)) {
+        const was = beforeRecords.get(id);
+        const ancestors = ancestorsOf(after.records, r);
+        const wasAncestors = was ? ancestorsOf(beforeRecords, was) : undefined;
+        if (was && !changed(was, r) && !changed(wasAncestors, ancestors))
+            continue;
+        await client.query(`insert into records (owner, id, kind, level, "of", within, ancestors, status, applied, wears, created, updated, doc)
+       values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+       on conflict (owner, id) do update set kind = excluded.kind, level = excluded.level, "of" = excluded."of", within = excluded.within,
+         ancestors = excluded.ancestors, status = excluded.status, applied = excluded.applied, wears = excluded.wears,
+         created = excluded.created, updated = excluded.updated, doc = excluded.doc`, [owner, id, r.kind, r.level, r.of ?? null, r.within ?? null, ancestors, r.status ?? null, r.applied ?? null, r.wears ?? [], r.created ?? null, r.updated ?? null, docOf(r)]);
+    }
+    // Plain copies: a working map notes every walk and miss, and persisting is neither.
+    const plain = (m) => new Map(Map.prototype.entries.call(m));
+    const upsertMap = async (table, keyCol, valCol, wasMap, nowMap, asJson = true) => {
+        const was = plain(wasMap);
+        const now = plain(nowMap);
+        for (const [k, v] of now) {
+            if (was.has(k) && !changed(was.get(k), v))
+                continue;
+            await client.query(`insert into ${table} (owner, ${keyCol}, ${valCol}) values ($1, $2, $3) on conflict (owner, ${keyCol}) do update set ${valCol} = excluded.${valCol}`, [owner, k, asJson ? v : String(v)]);
+        }
+        for (const k of was.keys())
+            if (!now.has(k))
+                await client.query(`delete from ${table} where owner = $1 and ${keyCol} = $2`, [owner, k]);
+    };
+    await upsertMap("edges", "edge", "json", before.edges, after.edges);
+    await upsertMap("bindings", "key", "record", before.bindings, after.bindings, false);
+    await upsertMap("runs", "run", "json", before.runs, after.runs);
+    await upsertMap("definitions", "key", "json", before.definitions, after.definitions);
+    for (const [issuer, list] of after.instructions) {
+        const have = before.instructions.get(issuer)?.length ?? 0;
+        for (let i = have; i < list.length; i++) {
+            const ins = list[i];
+            await client.query("insert into instructions (owner, issuer, n, json) values ($1, $2, $3, $4) on conflict do nothing", [owner, issuer, Number(ins.n ?? i + 1), ins]);
+        }
+    }
+    const appendList = async (table, was, now) => {
+        for (const item of now.slice(was.length))
+            await client.query(`insert into ${table} (owner, json) values ($1, $2)`, [owner, item]);
+    };
+    await appendList("observations", before.observations, after.observations);
+    await appendList("review", before.reviews, after.reviews);
+    await appendList("installed", before.installed, after.installed);
+    await appendList("reads", before.reads, after.reads);
+}
+/** Forget an owner's state tables (not its log), before a rebuild. */
+export async function wipeState(client, owner) {
+    for (const t of ["records", "edges", "bindings", "instructions", "review", "runs", "observations", "installed", "reads", "definitions"]) {
+        await client.query(`delete from ${t} where owner = $1`, [owner]);
+    }
+}
+export { isObj };
+//# sourceMappingURL=state.js.map

package/dist/src/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/state.ts"],"names":[],"mappings":"AACA,yGAAyG;AACzG,yGAAyG;AACzG,kFAAkF;AAElF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAc,MAAM,eAAe,CAAC;AAIvD,MAAM,KAAK,GAAG,CAAC,CAAU,EAAmB,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAIxG,iFAAiF;AACjF,MAAM,UAAU,QAAQ,CAAC,GAAQ;IAC/B,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAe,CAAC;IAC1C,yGAAyG;IACzG,MAAM,CAAC,GAAW,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAe,EAAE,CAAC;IAC5K,IAAI,GAAG,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClC,IAAI,GAAG,CAAC,MAAM;QAAE,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,GAAG,CAAC,MAAM;QAAE,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,MAA0B,CAAC;IAC1D,IAAI,GAAG,CAAC,OAAO;QAAE,CAAC,CAAC,OAAO,GAAG,GAAG,CAAC,OAA4B,CAAC;IAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM;QAAE,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClF,IAAI,GAAG,CAAC,OAAO;QAAE,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACjD,IAAI,GAAG,CAAC,OAAO;QAAE,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,CAA0B,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,CAAC;QAAE,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS;YAAE,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAS,CAAC;IACjI,OAAO,CAAC,CAAC;AACX,CAAC;AAED,mEAAmE;AACnE,SAAS,KAAK,CAAC,CAAS;IACtB,MAAM,CAAC,GAAG,CAA0B,CAAC;IACrC,MAAM,GAAG,GAAe,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC7D,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,CAAC;QAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAS,CAAC;IAC3H,OAAO,GAAG,CAAC;AACb,CAAC;AAED,uEAAuE;AACvE,SAAS,WAAW,CAAC,OAA4B,EAAE,CAAS;IAC1D,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrC,IAAI,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC;IACnB,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAc,EAAE,KAAa;IAC3D,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;IAC3B,MAAM,CAAC,GAAG,KAAK,EAAE,GAAW,EAAE,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAa,CAAC;IAClF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,qDAAqD,CAAC;QAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACnI,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,4DAA4D,CAAC;QAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,IAAuB,CAAC,CAAC;IACxJ,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,gEAAgE,CAAC;QAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACrJ,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,2EAA2E,CAAC,EAAE,CAAC;QACvG,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAClC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,IAAkB,CAAC,CAAC,CAAC;IACtG,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,6DAA6D,CAAC;QAAE,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAkB,CAAC,CAAC;IAC1I,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,uDAAuD,CAAC;QAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAkB,CAAC,CAAC;IAC/H,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,0DAA0D,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,IAAkB,CAAC,CAAC;IAC/I,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,0DAA0D,CAAC;QAAE,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,IAAkB,CAAC,CAAC;IACpI,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,sDAAsD,CAAC;QAAE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAkB,CAAC,CAAC;IAC5H,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,iEAAiE,CAAC;QAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,IAAkB,CAAC,CAAC;IAC7J,OAAO,KAAK,CAAC;AACf,CAAC;AAED,sGAAsG;AACtG,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAc,EAAE,KAAa,EAAE,MAAa,EAAE,KAAY;IACtF,MAAM,OAAO,GAAG,CAAC,CAAU,EAAE,CAAU,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAS,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAS,CAAC,CAAC;IAC9G,MAAM,aAAa,GAAG,IAAI,GAAG,CAAiB,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAA+B,CAAC,CAAC;IACxH,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAA+B,EAAE,CAAC;QAC9F,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAChD,MAAM,YAAY,GAAG,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACvE,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,SAAS,CAAC;YAAE,SAAS;QAC3E,MAAM,MAAM,CAAC,KAAK,CAChB;;;;oFAI8E,EAC9E,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAC5K,CAAC;IACJ,CAAC;IACD,oFAAoF;IACpF,MAAM,KAAK,GAAG,CAAI,CAAiB,EAAE,EAAE,CAAC,IAAI,GAAG,CAAY,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAA0B,CAAC,CAAC;IACnH,MAAM,SAAS,GAAG,KAAK,EAAE,KAAa,EAAE,MAAc,EAAE,MAAc,EAAE,MAA4B,EAAE,MAA4B,EAAE,MAAM,GAAG,IAAI,EAAE,EAAE;QACnJ,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QAC1B,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;YACzB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBAAE,SAAS;YACpD,MAAM,MAAM,CAAC,KAAK,CAAC,eAAe,KAAK,YAAY,MAAM,KAAK,MAAM,6CAA6C,MAAM,mBAAmB,MAAM,eAAe,MAAM,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/M,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,MAAM,MAAM,CAAC,KAAK,CAAC,eAAe,KAAK,yBAAyB,MAAM,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1I,CAAC,CAAC;IACF,MAAM,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACpE,MAAM,SAAS,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACrF,MAAM,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAChE,MAAM,SAAS,CAAC,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACrF,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;QAC1D,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAe,CAAC;YAClC,MAAM,MAAM,CAAC,KAAK,CAAC,kGAAkG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACvK,CAAC;IACH,CAAC;IACD,MAAM,UAAU,GAAG,KAAK,EAAE,KAAa,EAAE,GAAiB,EAAE,GAAiB,EAAE,EAAE;QAC/E,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,MAAM,MAAM,CAAC,KAAK,CAAC,eAAe,KAAK,gCAAgC,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IACpI,CAAC,CAAC;IACF,MAAM,UAAU,CAAC,cAAc,EAAE,MAAM,CAAC,YAAY,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IAC1E,MAAM,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC1D,MAAM,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IACjE,MAAM,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAc,EAAE,KAAa;IAC3D,KAAK,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,CAAC;QACxI,MAAM,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,mBAAmB,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/dist/src/store.d.ts

@@ -0,0 +1,269 @@
+import { type Draft, type Entry, type State } from "@cruba/crubal";
+import { type Edge } from "@cruba/crubal";
+import type { View } from "@cruba/crubal";
+import type { Json, JsonObject, Record } from "@cruba/crubal";
+import { verifyChain, type Keys } from "@cruba/crubal";
+import { type Pool } from "./db.ts";
+import { type Parsed } from "@cruba/crubal";
+import { type StepStats } from "@cruba/crubal";
+import { type Decision } from "@cruba/crubal";
+import { type Projecting } from "./projector.ts";
+import { Needs } from "./working.ts";
+import type { StreamEntry } from "@cruba/crubal";
+export type StoreOptions = {
+    /**
+     * Whether `state()` and `records.all()` may load an owner's whole state. `refuse` is for a host serving
+     * requests: nothing on a request path may be proportional to the catalog (brief 18, the scale rule);
+     * rebuild, erase and an install's restamp read whole regardless, since they are what they are.
+     */
+    wholeState?: "allow" | "refuse";
+    chain?: string;
+    /** Definitions handed in instead of read from the store's installed bundles and define writes (tests). */
+    projecting?: Projecting;
+    /** Install an unsigned bundle (development only; refused by default, docs/design/publishing.md). */
+    allowUnsigned?: boolean;
+    /** Sign each entry's hash with the owner's key (8.5): the host holds the key, the store never sees it. */
+    signer?: (hash: string) => string;
+    /** Publish every view right after each write commits (`fresh: write`); else the host calls `project`. */
+    fresh?: "write" | "asked";
+    /** The signer for a person this owner hosts (14.1), made on their first write; the host holds the key. */
+    hostedSigner?: (owner: string) => Promise<((hash: string) => string) | undefined>;
+};
+export declare class PgStore {
+    readonly pool: Pool;
+    readonly owner: string;
+    readonly chain: string;
+    readonly options: StoreOptions;
+    constructor(pool: Pool, owner: string, options?: StoreOptions | string);
+    /**
+     * Publish the views whose rows a write made stale (12.6): every view, or the named one, for its own
+     * audience or the one given. Runs outside any write transaction. Returns the stream entries published.
+     */
+    project(view?: string, audience?: string, only?: (v: View) => boolean): Promise<StreamEntry[]>;
+    /**
+     * Publish every view whole next time, with a reset on each stream (12.6.2): an index that lost rows, or
+     * kept rows nothing removed, is brought back to what the store holds. The named view alone when given.
+     */
+    republish(view?: string): Promise<void>;
+    /** The head of a view's stream for an audience (12.6.2): the last sequence number published, 0 when none. */
+    streamHead(view: string, audience?: string): Promise<number>;
+    /** The entries of a view's stream after `seq` (12.6.2). */
+    entriesSince(view: string, seq: number, audience?: string, limit?: number): Promise<StreamEntry[]>;
+    /** After a persist: mark what the entry made stale, inside the same transaction. */
+    private afterPersist;
+    private freshen;
+    /** Set while a bulk load runs: the per-commit publish waits for the one publish at the end. */
+    private quiet;
+    /** A bulk load that republishes at the end marks nothing stale per batch (load, `stale: false`). */
+    private skipStale;
+    /**
+     * Load many records as the owner's own, in batches: one entry per batch, each record set whole with its
+     * `sources` (or the `origin` given), the checks, rules and stale marks of a commit applying to every one;
+     * the views publish once at the end. For a conversion or a migration (brief 18 step 1): a million rows
+     * in an afternoon, not a day per hundred thousand through arrivals.
+     */
+    load(records: Record[], by: JsonObject, opts?: {
+        batch?: number;
+        at?: string;
+        origin?: string;
+        publish?: boolean;
+        stale?: boolean;
+    }): Promise<{
+        entries: string[];
+        records: number;
+        published: number;
+    }>;
+    private defsCache;
+    /** The definitions in force: installed bundles in order, then the owner's define writes. Cached per chain head. */
+    definitions(fresh?: boolean): Promise<Parsed>;
+    /** `fresh` builds a copy to try a change on (a trial reads onto it and must not touch the cache). */
+    private definitionsFrom;
+    /** What the store projects with: handed in, else built from its definitions. */
+    projecting(): Promise<Projecting | undefined>;
+    private projectingFrom;
+    /**
+     * Install a published version (docs/design/publishing.md): verify the hash and signature, require the
+     * language version at or below ours and every extended package installed at its pinned version, write
+     * the install entry and keep the bundle, restamp through the recipes when an earlier version was
+     * installed, and check the definitions that result. Refused whole on any failure.
+     */
+    install(bundle: JsonObject, keys?: Keys, at?: string): Promise<Entry>;
+    /**
+     * Mark every row of every view stale: after a reinstall or a rebuild the next publish rebuilds and
+     * compares every row and announces what left, and the stream keeps its numbering. (Wiping the stored
+     * rows instead, as before 0.1.16, made the next publish a first one, which announces no removals, so an
+     * index kept rows nothing ever removed: ME's index held three versions of its shop.)
+     */
+    private staleAll;
+    /** Well-formed access (14.12) on what an entry changed: ownership, wearing, within, and every edge written. */
+    /**
+     * What the rules produce for the records an operation changed, and for their ancestors (6.4): a plain
+     * write runs the productions as a border run does, so a rollup over units follows a unit written by the
+     * owner's own commit. Derived values land in the draft with their rule as source, so the entry's writes
+     * carry them like any other value; a person's value is never overwritten.
+     */
+    /** Records a `rederive` asks for, derived whether or not the operation changed them. */
+    private alsoDerive?;
+    /**
+     * Run the productions over records as they stand (6.4), for records written before a rule existed: one
+     * entry per call, holding only the derived values that changed. The ids are loaded into the working set
+     * and derived with their ancestors; nothing else is written.
+     */
+    rederive(ids: string[], by?: JsonObject, at?: string): Promise<Entry | null>;
+    private derive;
+    private checkWrites;
+    /** One record by id, from its row alone (no whole state): undefined when there is none. */
+    get(id: string): Promise<Record | undefined>;
+    /** The review items still open (9.5). */
+    review(): Promise<JsonObject[]>;
+    /**
+     * A review decision (9.5, 11.9, 14.7, runs.md): one entry holding the review write and what it causes;
+     * then the intakes the decision affects are replayed (9.6), each its own entry.
+     */
+    decide(d: Decision, by?: JsonObject, at?: string): Promise<{
+        entry: Entry | null;
+        replayed: string[];
+    }>;
+    /** Replay the kept intakes a decision reaches: by facet, by contract field, or by unit spelling (9.6). */
+    private replayFor;
+    /**
+     * Drain (docs/design/store.md, completion.md P): apply pending instructions to the records that have
+     * them, at most `rate` records per call, each its own entry `by: migration: drain`; the ids done and
+     * how many still wait.
+     */
+    drain(rate?: number, at?: string): Promise<{
+        applied: string[];
+        remaining: number;
+    }>;
+    /** What installing a version would restamp (10.4): per recipe and step, how many values change and how many go to review. */
+    dryRun(bundle: JsonObject): Promise<{
+        recipes: {
+            from: string;
+            to: string;
+            steps: StepStats[];
+            review: number;
+        }[];
+        records: number;
+    }>;
+    /** A define write (8.5, 11.4): one member of the working package as it now stands, checked with the rest first. */
+    define(member: JsonObject, by?: JsonObject, at?: string): Promise<Entry | null>;
+    /**
+     * The owner's state as the tables hold it, kept per chain head: the same head answers from memory; a
+     * head a little further on replays the entries since onto a copy (the engine's own replay), so a write
+     * never costs a reload of every record; a gap over 200 entries, or an entry the replay can't take,
+     * reads the tables whole. A commit works on a copy of the loaded state, so a kept state is never shared
+     * with a draft. (G6: Cashierfu carried this around the store until 0.1.15.)
+     */
+    state(): Promise<State>;
+    /**
+     * The whole state regardless of the option: for a rebuild, an erase, an install's restamp, an export and a
+     * test's assertions. Never on a request path: `state()` is the guarded door, this one says what it is.
+     */
+    wholeState(): Promise<State>;
+    /**
+     * A read on a working set: `fn` runs on a state whose records, bindings and runs load as it asks for them
+     * (by id, level, parent, target or key), and runs again until it asked for nothing new; edges,
+     * instructions and the working package are loaded whole (they are small). The lists (reviews,
+     * observations, installed, reads) are not loaded here: the readers below serve them. `fn` MUST be pure.
+     */
+    read<T>(fn: (s: State) => T, opts?: {
+        allowAll?: boolean;
+    }): Promise<T>;
+    /** Records by level, kind, parent, placement or one key's value, in log order; paged by `ord`. */
+    records(where?: {
+        level?: string;
+        kind?: string;
+        of?: string;
+        within?: string;
+        key?: [string, Json];
+    }, opts?: {
+        limit?: number;
+        after?: number;
+        archived?: boolean;
+    }): Promise<Record[]>;
+    /** Every edge of the owner (small: people and their grants). */
+    edges(): Promise<Edge[]>;
+    /** The install log: every version taken, in order. */
+    installed(): Promise<JsonObject[]>;
+    /** The record a binding (`contract|ref`) names, if any. */
+    binding(key: string): Promise<string | undefined>;
+    /** The owner's working package (11.4): `<member>:<name>` → the definition as it now stands. */
+    defines(): Promise<Map<string, JsonObject>>;
+    /** Every review item ever written, decided or not, in order (9.5); `review()` is the open ones. */
+    reviews(): Promise<JsonObject[]>;
+    /** The records several bindings name, by key: one query for an import's references. */
+    bindings(keys: string[]): Promise<Map<string, string>>;
+    /** The log of reads under an emergency edge (14.13), in order. */
+    emergencyReads(): Promise<JsonObject[]>;
+    /** The observations on one record, or on or supporting any of several (9.7). */
+    observationsOn(id: string | string[]): Promise<JsonObject[]>;
+    /** Observations by what they are on or support, their evidence type and their address (9.7); never all of them unasked. */
+    observations(where: {
+        on?: string | string[];
+        evidenceType?: string;
+        address?: string;
+    }): Promise<JsonObject[]>;
+    private keptState;
+    /** Forget the kept state: after a rewrite of history that moves no head (an erase, a rebuild). */
+    forgetState(): void;
+    /** The owner's entries, in chain order. */
+    entries(): Promise<Entry[]>;
+    /** Lock the chain for this transaction and return its head. Writers to one chain serialize here. */
+    private lockChain;
+    /** Link an entry to the chain's head, insert it, and move the head. The entry gets its `prev`. */
+    private link;
+    /**
+     * A hosted person's records live in their own chain (14.1): the writes to records owned `<owner>:<id>`
+     * leave the owner's entry and become one entry per person, linked and signed in the same transaction.
+     * The chains lock in a fixed order (the owner's first, then the persons' by name).
+     */
+    private linkSplit;
+    /**
+     * Append an entry made elsewhere (a rebuilt log, a hosted person's chain the host carries): it is
+     * linked to this chain's head, applied with the engine's applyEntry, and its effects persisted.
+     */
+    append(entry: Entry): Promise<Entry>;
+    /** An empty working state with the whole small tables in it; records, bindings and runs load as needed. */
+    private base;
+    /** What the last operation loaded, for tests and for watching a store's cost. */
+    trace: Needs | undefined;
+    /** Set while an install restamps: its commit walks the package's records by design, whatever `wholeState` says. */
+    private walking;
+    /**
+     * One operation, one entry (8.5): the engine runs on a draft of the state, what it changed becomes the
+     * entry's writes (plus `extra` writes the diff can't see), and the entry is applied and persisted in the
+     * same transaction. Nothing happens when nothing changed; a throw inside `mutate` rolls everything back.
+     */
+    commit(by: JsonObject, mutate: (draft: Draft) => void, at?: string, extra?: JsonObject[]): Promise<Entry | null>;
+    /**
+     * The same, for an operation that decides its own cause and extra writes as it runs (a border run): it
+     * returns `by`, `extra` and an outcome, and the outcome comes back beside the entry.
+     */
+    commitFrom<T>(run: (draft: Draft) => {
+        by: JsonObject;
+        extra?: JsonObject[];
+        out: T;
+    }, at?: string, mark?: {
+        witnessed?: true;
+    }): Promise<{
+        entry: Entry | null;
+        out: T;
+    }>;
+    /**
+     * Erase a record's values from the log (8.5.2): every value write to it, and every observation on it, in
+     * every entry, is redacted in place; creations, envelopes and everything else stay. The state is rebuilt.
+     */
+    erase(recordId: string): Promise<{
+        redacted: number;
+        witnessed: string[];
+    }>;
+    /** Check the chain's links and, with the owner's key, its signatures (8.5). */
+    verify(keys?: Keys): Promise<ReturnType<typeof verifyChain>>;
+    /** Empty the owner's state tables and apply the log again, in order (8.5.3). */
+    rebuild(): Promise<State>;
+    /**
+     * Redact one write of an entry, or the whole entry (8.5.2): the log's one update, which the trigger
+     * admits and nothing else. The state is then rebuilt, so the cache forgets what the log forgot.
+     */
+    redact(logId: string, writeIndex?: number): Promise<void>;
+}