@amalgm/shell 0.1.112 → 0.1.113

package/PURPOSE.md

@@ -687,6 +687,14 @@ shell only assembles.
     and applied prefix, and authority accepts that graph only while `N` is
     still the committed delivery tail under the entity-record ordering gate.
 
+59. **Shell journals graph publication without duplicating the graph.**
+    Live decides the immutable pages and head. Shell stores only the small
+    head operation plus the changed pages needed to replay that publication;
+    it never writes a second whole-registry snapshot into SQLite or rebuilds
+    roots Live did not select. A submitted intent keeps its mutation identity
+    across restart, and all pre-page journal shapes convert atomically without
+    dropping an unknown authority outcome.
+
 ## Relationship to amalgm-engine
 
 Stage 1 cut the bricks out of the engine. Stage 2 proves them here, composed.

package/dist/registry-graph.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The registry graph as this machine holds it.
+ *
+ * The authority stores the graph as a small head naming each root's immutable
+ * pages, so this machine holds the same shape: the head, and the records of
+ * every root that head names, grouped exactly as the head pages them. A
+ * publication rebuilds only the roots it walked — every other root carries its
+ * page list forward untouched, never re-serialized, re-hashed, or re-journaled.
+ *
+ * A resource whose authority snapshot is still records-shaped (a login's
+ * initial publication, before any head has committed) is held with a null
+ * head. Its first head commit must page every root at once, which is exactly
+ * what the authority demands of a commit over a records base.
+ */
+import { type CloudEntityRecord, type CloudSnapshot, type CloudGraphHead, type CloudGraphHeadReplacement, type GraphPage, type GraphPageRef, type Sha256Hex } from "@amalgm/live";
+/** One publication's outcome: the graph it produces, the operation that
+ * commits it, the pages that must be sealed first, and the checksum the
+ * authority will hold once it lands. */
+export interface RegistryGraphRebuild {
+    readonly graph: RegistryGraph;
+    readonly operation: CloudGraphHeadReplacement;
+    readonly pages: readonly GraphPage[];
+    readonly checksum: string;
+}
+export declare class RegistryGraph {
+    /** The committed head, or null while the authority still holds a
+     * records-shaped snapshot. */
+    readonly head: CloudGraphHead | null;
+    private readonly rootRecords;
+    private flat;
+    private rootIndex;
+    constructor(head: CloudGraphHead | null, rootRecords: ReadonlyMap<string, readonly CloudEntityRecord[]>);
+    /** Hold a records-shaped snapshot as the same per-root groups a head would
+     * name, so every reader above this class is shape-blind. */
+    static fromRecords(records: readonly CloudEntityRecord[]): RegistryGraph;
+    rootIds(): readonly string[];
+    recordsFor(rootId: string): readonly CloudEntityRecord[];
+    /** Every record of every root, uuid-sorted. Only whole-graph readers pay
+     * for this — a publication never calls it. */
+    records(): readonly CloudEntityRecord[];
+    /** The whole graph in the records shape the cold install and workspace
+     * selection paths read. Normalization already happened per root, so this
+     * only names the shape. */
+    snapshot(): CloudSnapshot;
+    /** Which root a record descends from, or null when the graph does not hold
+     * it. The index is built once, and only for callers that need it. */
+    rootOf(uuid: string): string | null;
+    /** The checksum the authority holds for this graph right now. */
+    checksum(sha256Hex: Sha256Hex): string;
+    /** Publish a new graph in which `rebuilt` roots carry the given records and
+     * every other root carries its committed pages forward. A root mapped to an
+     * empty record list is dropped from the graph. */
+    rebuild(rebuilt: ReadonlyMap<string, readonly CloudEntityRecord[]>, sha256Hex: Sha256Hex): RegistryGraphRebuild;
+}
+/** Every page identity the head names — the set a publication may skip
+ * uploading because the authority already holds it under this exact graph. */
+export declare function graphPageIdentities(head: CloudGraphHead | null): ReadonlySet<string>;
+/** Materialize the authority's stored snapshot bytes into this machine's
+ * graph. A head is materialized by reading the pages it names; a records-shaped
+ * snapshot is grouped in place. */
+export declare function registryGraphFromSnapshot(bytes: Uint8Array, readPages: (refs: readonly GraphPageRef[]) => Promise<ReadonlyMap<string, Uint8Array>>, sha256Hex: Sha256Hex): Promise<RegistryGraph>;

package/dist/registry-graph.js

@@ -0,0 +1,156 @@
+/**
+ * The registry graph as this machine holds it.
+ *
+ * The authority stores the graph as a small head naming each root's immutable
+ * pages, so this machine holds the same shape: the head, and the records of
+ * every root that head names, grouped exactly as the head pages them. A
+ * publication rebuilds only the roots it walked — every other root carries its
+ * page list forward untouched, never re-serialized, re-hashed, or re-journaled.
+ *
+ * A resource whose authority snapshot is still records-shaped (a login's
+ * initial publication, before any head has committed) is held with a null
+ * head. Its first head commit must page every root at once, which is exactly
+ * what the authority demands of a commit over a records base.
+ */
+import { assembleRootRecords, graphHeadChecksum, graphHeadFromRootPages, graphHeadReplacement, pagesForRoot, parseGraphHead, parseSnapshot, recordsByRoot, snapshotFromRecords, stableJson, ENTITY_CLOUD_SCHEMA_VERSION, GRAPH_HEAD_KIND, } from "@amalgm/live";
+export class RegistryGraph {
+    /** The committed head, or null while the authority still holds a
+     * records-shaped snapshot. */
+    head;
+    rootRecords;
+    flat = null;
+    rootIndex = null;
+    constructor(head, rootRecords) {
+        this.head = head;
+        this.rootRecords = rootRecords;
+    }
+    /** Hold a records-shaped snapshot as the same per-root groups a head would
+     * name, so every reader above this class is shape-blind. */
+    static fromRecords(records) {
+        return new RegistryGraph(null, recordsByRoot(records));
+    }
+    rootIds() {
+        return [...this.rootRecords.keys()];
+    }
+    recordsFor(rootId) {
+        return this.rootRecords.get(rootId.toLowerCase()) ?? [];
+    }
+    /** Every record of every root, uuid-sorted. Only whole-graph readers pay
+     * for this — a publication never calls it. */
+    records() {
+        this.flat ??= snapshotFromRecords([...this.rootRecords.values()].flat()).records;
+        return this.flat;
+    }
+    /** The whole graph in the records shape the cold install and workspace
+     * selection paths read. Normalization already happened per root, so this
+     * only names the shape. */
+    snapshot() {
+        return {
+            schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
+            kind: "amalgm-entity-registry",
+            records: this.records(),
+        };
+    }
+    /** Which root a record descends from, or null when the graph does not hold
+     * it. The index is built once, and only for callers that need it. */
+    rootOf(uuid) {
+        if (!this.rootIndex) {
+            const index = new Map();
+            for (const [rootId, records] of this.rootRecords) {
+                for (const record of records)
+                    index.set(record.uuid, rootId);
+            }
+            this.rootIndex = index;
+        }
+        return this.rootIndex.get(uuid) ?? null;
+    }
+    /** The checksum the authority holds for this graph right now. */
+    checksum(sha256Hex) {
+        return this.head === null
+            ? sha256Hex(stableJson(snapshotFromRecords(this.records())))
+            : graphHeadChecksum(this.head, sha256Hex);
+    }
+    /** Publish a new graph in which `rebuilt` roots carry the given records and
+     * every other root carries its committed pages forward. A root mapped to an
+     * empty record list is dropped from the graph. */
+    rebuild(rebuilt, sha256Hex) {
+        const replaced = new Map([...rebuilt].map(([rootId, records]) => [rootId.toLowerCase(), records]));
+        if (this.head === null) {
+            // The authority's base carries no page identities, so it can prove
+            // nothing about a root this commit leaves alone. Paging every root is
+            // the only lawful first head.
+            for (const rootId of this.rootRecords.keys()) {
+                if (!replaced.has(rootId)) {
+                    throw new Error(`the first graph head must page every root, and ${rootId} is missing`);
+                }
+            }
+        }
+        const carried = (this.head?.roots ?? []).filter((root) => !replaced.has(root.rootId));
+        const pages = [];
+        const paged = [];
+        const nextRecords = new Map(this.rootRecords);
+        for (const [rootId, records] of replaced) {
+            if (records.length === 0) {
+                nextRecords.delete(rootId);
+                continue;
+            }
+            const rootPages = pagesForRoot(rootId, records, sha256Hex);
+            pages.push(...rootPages);
+            paged.push({ rootId, pages: rootPages.map((page) => page.ref) });
+            nextRecords.set(rootId, rootPages.flatMap((page) => page.records));
+        }
+        const head = graphHeadFromRootPages([...carried, ...paged]);
+        return {
+            graph: new RegistryGraph(head, nextRecords),
+            operation: graphHeadReplacement(head, [...replaced.keys()]),
+            pages,
+            checksum: graphHeadChecksum(head, sha256Hex),
+        };
+    }
+}
+/** Every page identity the head names — the set a publication may skip
+ * uploading because the authority already holds it under this exact graph. */
+export function graphPageIdentities(head) {
+    const identities = new Set();
+    for (const root of head?.roots ?? []) {
+        for (const page of root.pages)
+            identities.add(page.sha256);
+    }
+    return identities;
+}
+/** Materialize the authority's stored snapshot bytes into this machine's
+ * graph. A head is materialized by reading the pages it names; a records-shaped
+ * snapshot is grouped in place. */
+export async function registryGraphFromSnapshot(bytes, readPages, sha256Hex) {
+    if (!snapshotIsGraphHead(bytes)) {
+        return RegistryGraph.fromRecords(parseSnapshot(bytes).records);
+    }
+    const head = parseGraphHead(bytes);
+    const read = await readPages(head.roots.flatMap((root) => root.pages));
+    const rootRecords = new Map();
+    for (const root of head.roots) {
+        rootRecords.set(root.rootId, assembleRootRecords(root.rootId, root.pages, root.pages.map((page) => {
+            const found = read.get(page.sha256);
+            if (!found)
+                throw new Error(`cloud graph page ${page.sha256} was not read`);
+            return found;
+        }), sha256Hex));
+    }
+    return new RegistryGraph(head, rootRecords);
+}
+/** Which shape the authority's snapshot bytes carry. Both shapes declare their
+ * kind ahead of their payload, and no record carries a `kind` of its own, so
+ * the first declaration in the opening bytes is the snapshot's — the shape is
+ * decided from a few bytes rather than by parsing a whole graph. */
+function snapshotIsGraphHead(bytes) {
+    const declared = /"kind":"([^"]*)"/
+        .exec(Buffer.from(bytes.subarray(0, SNAPSHOT_KIND_PREFIX_BYTES)).toString("utf8"));
+    if (!declared)
+        throw new Error("cloud registry snapshot declares no kind");
+    return declared[1] === GRAPH_HEAD_KIND;
+}
+/** Enough opening bytes to hold the kind declaration of either shape, whatever
+ * small members precede it. The authority reads the same prefix to decide the
+ * same question. */
+const SNAPSHOT_KIND_PREFIX_BYTES = 128;
+//# sourceMappingURL=registry-graph.js.map

package/dist/registry-graph.js.map

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

package/dist/user-ground-host.d.ts

@@ -182,6 +182,14 @@ export declare class UserGroundHost {
     private userRoot;
     private cacheDir;
     private cloudPort;
+    /** The authority's stored snapshot as this machine's graph. A head names
+     * immutable pages, so every page this machine already cached is a local read
+     * and an unchanged root never crosses the network twice. */
+    private materializeRegistry;
+    /** Read graph pages by identity: cached pages come off local disk, the rest
+     * are fetched straight from content storage and cached on the way in. Every
+     * page is re-proven against its declared identity before it is kept. */
+    private readGraphPages;
     private localPort;
     /** Send's small-cargo fast path: the record's sealed artifact rides the
      * submit frame itself, so one round trip carries record, manifest, and
@@ -219,6 +227,11 @@ export declare class UserGroundHost {
      * frames; the answer is the only permission to skip an upload. */
     private sealedContentHashes;
     private publishPendingSnapshots;
+    /** Seal this publication's graph pages. Pages are immutable, content
+     * addressed, and already in memory, so the authority's seal inventory alone
+     * decides what still has to move and whole pages ride cargo waves. The head
+     * may not commit until every page it newly names is sealed. */
+    private uploadGraphPages;
     private publishLoadedSnapshot;
 }
 /** The single opener and schema-migration entry for a user ground database.