@amalgm/shell 0.1.111 → 0.1.113

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/runtime-command-host.js

@@ -53,7 +53,13 @@ export async function callRuntimeCommand(input, path, body) {
         const message = payload && typeof payload === "object" && "error" in payload
             ? String(payload.error)
             : `runtime responded ${response.statusCode}`;
-        throw new Error(message);
+        const failure = new Error(message);
+        const stages = payload && typeof payload === "object" && "stages" in payload
+            ? payload.stages
+            : undefined;
+        if (Array.isArray(stages))
+            Object.assign(failure, { stages });
+        throw failure;
     }
     if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
         throw new Error("Files runtime returned an invalid response");

package/dist/runtime-command-host.js.map

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

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

@@ -38,6 +38,28 @@ export interface DetectScanEvidence {
     readonly plannedRows?: number;
     readonly records?: number;
     readonly recordBytes?: number;
+    /** Wall time inside readdir/lstat — the traversal's own cost. */
+    readonly walkMs?: number;
+    /** Wall time from the first content capture scheduled to the last settled. */
+    readonly captureMs?: number;
+    /** Summed capture task time. Divided by captureMs it is pool occupancy: at
+     * or near 1 the pool is idle-serial, near its width it is saturated. */
+    readonly captureBusyMs?: number;
+    /** Bytes read and hashed by content capture during this scan. */
+    readonly captureBytes?: number;
+    /** Wall time inside Git index inspection during the walk. */
+    readonly gitMs?: number;
+    /** Wall time proving repository identity through Git, across every
+     * repository. Repositories are sealed one at a time, so this is serial. */
+    readonly repositoryIdentityMs?: number;
+    /** Wall time packing repository transport bytes, across every repository. */
+    readonly repositoryCaptureMs?: number;
+    /** Wall time sealing and re-inspecting repository transport artifacts. */
+    readonly repositorySealMs?: number;
+    /** Wall time resolving stored UUIDs against what the walk found. */
+    readonly reconcileMs?: number;
+    /** Wall time planning and persisting rows once identity is settled. */
+    readonly persistMs?: number;
 }
 export interface UserGroundHostOptions {
     readonly amalgmRoot: string;
@@ -67,6 +89,13 @@ export interface UserGroundHostOptions {
     }) => Promise<void> | void;
     /** Transient, opt-in evidence for exact stage measurement. */
     readonly onFilesStage?: FilesStageObserver;
+    /**
+     * Is stage evidence being read right now? An observer may be permanently
+     * installed while nothing is listening, so the host asks rather than
+     * assumes: counters that cost real work on the critical path are computed
+     * only when the answer is yes.
+     */
+    readonly filesTraceActive?: () => boolean;
 }
 export type WorkspaceAddStage = "intent-recorded" | "materialization-verified" | "rows-committed" | "ground-revealed" | "binding-created" | "watching";
 export interface UserGroundCloseOptions {
@@ -102,6 +131,8 @@ export declare class UserGroundHost {
     readonly port: UserGroundPort;
     constructor(options: UserGroundHostOptions);
     private stage;
+    /** Whether a counter worth real time on the critical path may be computed. */
+    private measuring;
     private reportDetectScan;
     databasePath(identity: UserGroundIdentity): string;
     rows(identity: UserGroundIdentity): GroundRow[];
@@ -151,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
@@ -180,11 +219,19 @@ export declare class UserGroundHost {
      * resource snapshot. */
     private prepareSnapshotPublication;
     private publishMaterializedSnapshot;
+    /** Close the graph-preparation stage with every leg it spent, so a slow
+     * preparation names the slow part instead of one opaque number. */
+    private finishPreparation;
     /** Which of these heads does the authority hold sealed under the current
      * content contract? Batched so a whole workspace costs a handful of
      * 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.