@amalgm/shell 0.1.88 → 0.1.90

package/dist/user-ground-host.js

@@ -15,6 +15,7 @@ import { ContentCacheDownload, captureContentFile, hashContentFile, sealCaptured
 import { decodeContentWireBytes, encodeContentWireBytes } from "./content-wire-codec.js";
 import { exactTextReplay, planGroundDetection, reconcileGroundUUIDs, } from "./detection/portable.js";
 import { AcceptedInboxResultIndex } from "./detection/accepted-result.js";
+import { sameNotebookBasisRow } from "./detection/notebook-basis.js";
 import { NamedDetectRuntime } from "./detection/runtime.js";
 import { WORKSPACE_UUID as UUID, createFilesRegisterPorts, ensureWorkspaceBinding, ensureWorkspaceReference, pathExists, pathWithin, referenceWorkspaceId, selectKnownRegistrationId, workspaceBindingDir, } from "./files-register-host.js";
 import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile, hasGitMarker, readCachedRepositoryIdentity, } from "./git-repository-host.js";
@@ -227,6 +228,7 @@ export class UserGroundHost {
             findKnownWorkspaceId: ({ absolutePath, deviceNumber, inode }) => findKnownEntityId(this.databasePath(identity), absolutePath, deviceNumber, inode),
         });
         const add = {
+            sha256Hex,
             lookupRegistry: async () => {
                 const started = performance.now();
                 this.stage({
@@ -526,12 +528,16 @@ export class UserGroundHost {
             this.stage({
                 primitive: "register", stage: "entity-sqlite-commit", status: "started", workspaceId,
             });
-            commitDetectedState(this.databasePath(identity), {
+            const committed = commitDetectedState(this.databasePath(identity), {
+                notebookBasis: scanned.notebookBasis,
                 acceptedMaterializedRows: scanned.acceptedMaterializedRows,
                 materializedRemovals: scanned.materializedRemovals,
                 acceptedNotebookRows: scanned.acceptedNotebookRows,
                 notebookRemovals: scanned.notebookRemovals,
             });
+            if (!committed) {
+                throw new Error("verified ground advanced while registration was observing; retry");
+            }
             this.stage({
                 primitive: "register",
                 stage: "entity-sqlite-commit",
@@ -1577,6 +1583,7 @@ export class UserGroundHost {
             return;
         }
         let detection;
+        let notebookBasis;
         let acceptedMaterializedRows;
         let materializedRemovals;
         let acceptedNotebookRows;
@@ -1592,6 +1599,7 @@ export class UserGroundHost {
                 coreScan,
             });
             detection = scanned.detection;
+            notebookBasis = scanned.notebookBasis;
             acceptedMaterializedRows = scanned.acceptedMaterializedRows;
             materializedRemovals = scanned.materializedRemovals;
             acceptedNotebookRows = scanned.acceptedNotebookRows;
@@ -1615,13 +1623,17 @@ export class UserGroundHost {
             }))
             : []);
         const recordCommitStarted = performance.now();
-        commitDetectedState(this.databasePath(identity), {
+        const committed = commitDetectedState(this.databasePath(identity), {
+            notebookBasis,
             acceptedMaterializedRows,
             materializedRemovals,
             acceptedNotebookRows,
             notebookRemovals,
             proposals: detectedRecords,
         });
+        if (!committed) {
+            throw pipelineStageError("detection", new Error("the verified notebook advanced while Detect was observing; retrying fresh truth"));
+        }
         const recordCommitDuration = performance.now() - recordCommitStarted;
         if (detectedRecords.length === 0) {
             this.stage({
@@ -1666,7 +1678,8 @@ export class UserGroundHost {
         }
     }
     async publishPendingSnapshotsBeforeLookup(identity, resourceId) {
-        const pending = readSnapshotPublications(this.databasePath(identity));
+        const pending = readSnapshotPublications(this.databasePath(identity))
+            .filter((entry) => entry.status === "pending");
         if (pending.length === 0)
             return;
         const first = pending[0];
@@ -1680,12 +1693,36 @@ export class UserGroundHost {
             checksum: "",
             records: snapshotFromRecords(JSON.parse(first.snapshotJson).records || []).records,
         };
-        await this.publishPendingSnapshots(identity);
+        try {
+            await this.publishPendingSnapshots(identity);
+        }
+        catch (error) {
+            // A conclusive refusal settles the intent as rejected: the lookup that
+            // follows fetches authoritative state and a later register supersedes
+            // the settled row, so a refused publication never wedges startup. An
+            // unknown outcome must keep blocking — the mutation may have landed.
+            if (!conclusivelyRefused(error))
+                throw error;
+            this.cloudState = null;
+        }
     }
     /** Register is the deliberate cold graph-publication boundary. Ordinary
      * Watch detection stops at a durable exact record and never rebuilds this
      * resource snapshot. */
     async publishMaterializedSnapshot(identity, publicationRootIds, trace) {
+        // Any durable pending intent resolves before a new snapshot derives: an
+        // acknowledged publication advances the head through its original
+        // mutation id (the authority answers a known mutation id idempotently),
+        // and a conclusive refusal marks the row rejected so the snapshot
+        // derived below may supersede it. A transport failure keeps the row
+        // pending — its outcome is unknown, so nothing may replace it.
+        try {
+            await this.publishPendingSnapshots(identity, trace);
+        }
+        catch (error) {
+            if (!conclusivelyRefused(error))
+                throw error;
+        }
         const state = this.cloudState;
         if (!state)
             throw new Error("cloud state is unavailable for graph publication");
@@ -1693,7 +1730,7 @@ export class UserGroundHost {
             .map(portableRecord), readGroundRowsForRoots(this.databasePath(identity), "detection_notebook", publicationRootIds)
             .map(portableRecord));
         const merged = mergeMaterializedRoots(state.records, localRecords);
-        const traveling = travelingRecords(merged);
+        const traveling = travelingRecords(merged, sha256Hex);
         const impossibleGitLeaf = traveling.find((record) => (record.type === "file.text" || record.type === "file.binary" || record.type === "link")
             && record.payloadVersion?.startsWith("git:"));
         if (impossibleGitLeaf) {
@@ -1705,16 +1742,6 @@ export class UserGroundHost {
         const checksum = sha256Hex(snapshotJson);
         if (checksum === state.checksum)
             return;
-        const pending = readSnapshotPublications(this.databasePath(identity));
-        const identical = pending.find((entry) => entry.resourceId === state.resourceId
-            && entry.snapshotChecksum === checksum);
-        if (identical) {
-            await this.publishPendingSnapshots(identity, trace);
-            return;
-        }
-        if (pending.length > 0) {
-            throw new Error("a different graph snapshot is already pending publication");
-        }
         const localIds = new Set(localRecords.map((record) => record.uuid));
         const replacementRootIds = localRecords
             .filter((record) => record.parentUUID === null)
@@ -1736,7 +1763,7 @@ export class UserGroundHost {
             const artifact = artifactForRecord(record);
             return artifact !== null && !publishedArtifacts.has(artifact.contentHash);
         });
-        appendSnapshotJournal(this.databasePath(identity), {
+        supersedeSnapshotJournal(this.databasePath(identity), {
             mutationId: randomUUID(),
             resourceId: state.resourceId,
             authorityEpoch: state.authorityEpoch,
@@ -1746,11 +1773,17 @@ export class UserGroundHost {
             uploadRecords,
             replacementRootIds: replacement.rootIds,
             replacementRecords: replacement.records,
+            status: "pending",
         });
         await this.publishPendingSnapshots(identity, trace);
     }
     async publishPendingSnapshots(identity, trace) {
         for (const pending of readSnapshotPublications(this.databasePath(identity))) {
+            // A rejected row is a settled fact, not an intent: the authority
+            // conclusively refused this exact mutation, and only a newer complete
+            // snapshot superseding it can publish this resource again.
+            if (pending.status === "rejected")
+                continue;
             const snapshot = snapshotFromRecords(JSON.parse(pending.snapshotJson).records || []);
             const replacement = rootReplacementFromRecords(pending.replacementRootIds, pending.replacementRecords);
             try {
@@ -1796,6 +1829,13 @@ export class UserGroundHost {
                         durationMs: performance.now() - graphCommitStarted,
                     });
                 }
+                // A non-retryable error frame is the authority's answer: this exact
+                // mutation is refused forever. Settle the row so it is never
+                // replayed and a newer snapshot may supersede it. Every other
+                // failure leaves the outcome unknown and the row pending.
+                if (error instanceof WireRequestError && error.retryable === false) {
+                    markSnapshotJournalRejected(this.databasePath(identity), pending.mutationId);
+                }
                 throw pipelineStageError("cloud graph commit", error);
             }
             if (trace?.journey === "register") {
@@ -2006,7 +2046,8 @@ function initializeDatabase(file) {
       mutation_id TEXT NOT NULL UNIQUE,
       resource_id TEXT NOT NULL,
       publication_json TEXT NOT NULL,
-      created_at INTEGER NOT NULL
+      created_at INTEGER NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'rejected'))
     );
     CREATE TABLE IF NOT EXISTS workspace_add_intents (
       workspace_uuid TEXT PRIMARY KEY,
@@ -2041,6 +2082,10 @@ function initializeDatabase(file) {
     if (!inboxColumns.has("resolved_at")) {
         database.exec("ALTER TABLE record_inbox ADD COLUMN resolved_at INTEGER");
     }
+    const publicationColumns = new Set(database.prepare("PRAGMA table_info(snapshot_publications)").all().map(({ name }) => name));
+    if (!publicationColumns.has("status")) {
+        database.exec("ALTER TABLE snapshot_publications ADD COLUMN status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'rejected'))");
+    }
     database.exec("DROP INDEX IF EXISTS record_inbox_delivery");
     database.exec("DROP TABLE IF EXISTS mutation_journal");
     migratedDatabases.add(file);
@@ -2414,7 +2459,7 @@ function readSnapshotPublications(file) {
     try {
         return database.prepare(`
       SELECT mutation_id AS mutationId, resource_id AS resourceId,
-             publication_json AS publicationJson
+             publication_json AS publicationJson, status
         FROM snapshot_publications ORDER BY sequence
     `).all().map((row) => {
             const publication = JSON.parse(row.publicationJson);
@@ -2435,6 +2480,7 @@ function readSnapshotPublications(file) {
                 uploadRecords: snapshotFromRecords(publication.uploadRecords).records,
                 replacementRootIds: publication.replacementRootIds.map(String),
                 replacementRecords: snapshotFromRecords(publication.replacementRecords).records,
+                status: row.status === "rejected" ? "rejected" : "pending",
             };
         });
     }
@@ -2461,7 +2507,25 @@ function hasRecordsBeyondSnapshot(file) {
 function commitDetectedState(file, input) {
     const database = initializeDatabase(file);
     try {
-        database.transaction(() => {
+        return database.transaction(() => {
+            const basisRows = input.notebookBasis ?? [];
+            const currentByUuid = new Map();
+            for (let offset = 0; offset < basisRows.length; offset += 500) {
+                const batch = basisRows.slice(offset, offset + 500);
+                const placeholders = batch.map(() => "?").join(", ");
+                const rows = database.prepare(`
+          SELECT ${GROUND_ROW_PROJECTION} FROM detection_notebook
+           WHERE uuid IN (${placeholders})
+        `).all(...batch.map(({ uuid }) => uuid));
+                for (const row of rows)
+                    currentByUuid.set(row.uuid, row);
+            }
+            for (const basis of basisRows) {
+                const current = currentByUuid.get(basis.uuid);
+                if (basis.row ? !sameNotebookBasisRow(basis.row, current) : current !== undefined) {
+                    return false;
+                }
+            }
             const acceptedInbox = new AcceptedInboxResultIndex(database);
             const append = database.prepare(`
         INSERT INTO record_outbox(
@@ -2503,33 +2567,75 @@ function commitDetectedState(file, input) {
             for (const row of input.acceptedNotebookRows) {
                 runGroundUpsert(database, "detection_notebook", upsertNotebook, row);
             }
+            return true;
         })();
     }
     finally {
         database.close();
     }
 }
-function appendSnapshotJournal(file, entry) {
+/** Journal the newest snapshot publication for its resource. A journal row
+ * has exactly two meanings: `pending` — the submit outcome is unknown, so
+ * the same mutation id must retry until the authority answers (the mutation
+ * may already be accepted with only the acknowledgement lost); `rejected` —
+ * the authority conclusively refused it, so it is never replayed. Only a
+ * rejected row may be superseded — last write wins — and supersession and
+ * insertion share one transaction, so a crash leaves exactly one durable
+ * intent. Content uploads are content-addressed and idempotent, so a
+ * superseded row loses no uploaded work. */
+function supersedeSnapshotJournal(file, entry) {
     const database = initializeDatabase(file);
     try {
-        database.prepare(`
-      INSERT INTO snapshot_publications(
-        mutation_id, resource_id, publication_json, created_at
-      ) VALUES (?, ?, ?, ?)
-    `).run(entry.mutationId, entry.resourceId, stableJson({
-            authorityEpoch: entry.authorityEpoch,
-            baseVersion: entry.baseVersion,
-            snapshotChecksum: entry.snapshotChecksum,
-            snapshotJson: entry.snapshotJson,
-            uploadRecords: entry.uploadRecords,
-            replacementRootIds: entry.replacementRootIds,
-            replacementRecords: entry.replacementRecords,
-        }), Date.now());
+        database.transaction(() => {
+            const unresolved = database.prepare(`
+        SELECT 1 AS present FROM snapshot_publications
+          WHERE resource_id = ? AND status = 'pending' LIMIT 1
+      `).get(entry.resourceId);
+            if (unresolved) {
+                throw new Error("a pending publication with an unknown outcome must resolve before supersession");
+            }
+            database.prepare("DELETE FROM snapshot_publications WHERE resource_id = ? AND status = 'rejected'")
+                .run(entry.resourceId);
+            database.prepare(`
+        INSERT INTO snapshot_publications(
+          mutation_id, resource_id, publication_json, created_at
+        ) VALUES (?, ?, ?, ?)
+      `).run(entry.mutationId, entry.resourceId, stableJson({
+                authorityEpoch: entry.authorityEpoch,
+                baseVersion: entry.baseVersion,
+                snapshotChecksum: entry.snapshotChecksum,
+                snapshotJson: entry.snapshotJson,
+                uploadRecords: entry.uploadRecords,
+                replacementRootIds: entry.replacementRootIds,
+                replacementRecords: entry.replacementRecords,
+            }), Date.now());
+        })();
     }
     finally {
         database.close();
     }
 }
+/** Settle a journal row as conclusively refused. It is never replayed again;
+ * a newer complete snapshot supersedes it on the next publication. */
+function markSnapshotJournalRejected(file, mutationId) {
+    const database = initializeDatabase(file);
+    try {
+        database.prepare("UPDATE snapshot_publications SET status = 'rejected' WHERE mutation_id = ?")
+            .run(mutationId);
+    }
+    finally {
+        database.close();
+    }
+}
+/** True when the authority itself answered that this exact mutation is
+ * refused (a non-retryable error frame), as opposed to a transport or
+ * pipeline failure whose outcome is unknown. Stage wrappers carry the wire
+ * error as their cause. */
+function conclusivelyRefused(error) {
+    if (error instanceof WireRequestError)
+        return error.retryable === false;
+    return error instanceof Error && conclusivelyRefused(error.cause);
+}
 function deleteJournalEntry(file, mutationId) {
     const database = initializeDatabase(file);
     try {
@@ -2605,28 +2711,6 @@ function capturedGroundRow(resourceId, rootUUID, row) {
         contentVerifiedAtMs: row.contentVerifiedAtMs,
     };
 }
-function sameGroundRow(left, right) {
-    return right !== undefined
-        && left.resourceId === right.resourceId
-        && left.rootUUID === right.rootUUID
-        && left.uuid === right.uuid
-        && left.type === right.type
-        && left.parentUUID === right.parentUUID
-        && left.name === right.name
-        && left.status === right.status
-        && left.version === right.version
-        && left.payloadVersion === right.payloadVersion
-        && left.transportVersion === right.transportVersion
-        && left.relativePath === right.relativePath
-        && left.absolutePath === right.absolutePath
-        && left.deviceNumber === right.deviceNumber
-        && left.inode === right.inode
-        && left.byteSize === right.byteSize
-        && left.modifiedTimeMs === right.modifiedTimeMs
-        && left.changedTimeMs === right.changedTimeMs
-        && left.filesystemMode === right.filesystemMode
-        && left.contentVerifiedAtMs === right.contentVerifiedAtMs;
-}
 function groundRowValues(row) {
     return [
         row.uuid, row.resourceId, row.rootUUID, row.type, row.parentUUID, row.name, row.status,
@@ -2975,7 +3059,8 @@ async function reconcileGround(input) {
         ? readMaterializedRowsWithoutNotebook(database, selectedRoots ?? undefined)
         : [];
     const existing = suspicions ? [...notebook, ...unverifiedIdentity] : materialized;
-    const notebookByUuid = new Map(notebook.map((row) => [row.uuid, row]));
+    const observedNotebookByUuid = new Map(notebook.map((row) => [row.uuid, row]));
+    const notebookByUuid = new Map(observedNotebookByUuid);
     const materializedBaseline = suspicions
         ? existing.filter((row) => materializedUUIDs.has(row.uuid))
         : materialized;
@@ -3034,11 +3119,11 @@ async function reconcileGround(input) {
         }
         for (const row of result.rows) {
             const captured = capturedGroundRow(parameters.resourceId, parameters.rootUUID, row);
-            if (!sameGroundRow(captured, materializedByUuid.get(captured.uuid))) {
+            if (!sameNotebookBasisRow(captured, materializedByUuid.get(captured.uuid))) {
                 acceptedMaterializedRows.push(captured);
             }
             if (result.transferable) {
-                if (sameGroundRow(captured, notebookByUuid.get(captured.uuid)))
+                if (sameNotebookBasisRow(captured, notebookByUuid.get(captured.uuid)))
                     continue;
                 acceptedNotebookRows.push(captured);
                 notebookByUuid.set(captured.uuid, captured);
@@ -3122,8 +3207,21 @@ async function reconcileGround(input) {
             suspicion: observationFor(rootPath),
         });
     }
+    const changedUUIDs = new Set([
+        ...acceptedMaterializedRows.map((row) => row.uuid),
+        ...materializedRemovals,
+        ...acceptedNotebookRows.map((row) => row.uuid),
+        ...notebookRemovals,
+        ...detection.flatMap((plan) => plan.kind === "ready"
+            ? plan.proposals.map((proposal) => proposal.entityId)
+            : []),
+    ]);
     return {
         detection,
+        notebookBasis: [...changedUUIDs].sort().map((uuid) => ({
+            uuid,
+            row: observedNotebookByUuid.get(uuid) ?? null,
+        })),
         acceptedMaterializedRows,
         materializedRemovals: [...materializedRemovals],
         acceptedNotebookRows,
@@ -4386,7 +4484,7 @@ async function installCloudWorkspace(input) {
         }
         const expectedRecords = pending?.records ?? records;
         const localRecords = existing.map(portableRecord);
-        if (!sameRecords(travelingRecords(localRecords), expectedRecords)) {
+        if (!sameRecords(travelingRecords(localRecords, sha256Hex), expectedRecords)) {
             throw new Error(`local workspace ${workspace.uuid} differs from its cloud graph`);
         }
         if (pending && root.absolutePath !== pending.destinationPath) {