@amalgm/shell 0.1.164-main.41987694940 → 0.1.164-main.42004338907

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/dist/apply-window-cargo.d.ts +10 -7
  2. package/dist/apply-window-cargo.js +27 -19
  3. package/dist/apply-window-cargo.js.map +1 -1
  4. package/dist/apply-window-host.js +44 -7
  5. package/dist/apply-window-host.js.map +1 -1
  6. package/dist/apply-window-verify.js +1 -1
  7. package/dist/apply-window-verify.js.map +1 -1
  8. package/dist/content-cache-retention.js +1 -1
  9. package/dist/content-cache-retention.js.map +1 -1
  10. package/dist/content-capture-pool.d.ts +1 -2
  11. package/dist/content-capture-pool.js +4 -4
  12. package/dist/content-capture-pool.js.map +1 -1
  13. package/dist/content-capture-worker.js +1 -1
  14. package/dist/content-capture-worker.js.map +1 -1
  15. package/dist/declaration-chain.d.ts +4 -19
  16. package/dist/declaration-chain.js +34 -74
  17. package/dist/declaration-chain.js.map +1 -1
  18. package/dist/declaration-commit.d.ts +0 -7
  19. package/dist/declaration-commit.js +10 -23
  20. package/dist/declaration-commit.js.map +1 -1
  21. package/dist/declaration-hold.d.ts +10 -22
  22. package/dist/declaration-hold.js +2 -34
  23. package/dist/declaration-hold.js.map +1 -1
  24. package/dist/declaration-journal.d.ts +17 -6
  25. package/dist/declaration-journal.js +48 -10
  26. package/dist/declaration-journal.js.map +1 -1
  27. package/dist/declaration-save.d.ts +2 -12
  28. package/dist/declaration-save.js +13 -46
  29. package/dist/declaration-save.js.map +1 -1
  30. package/dist/detection/owed-selection.d.ts +2 -4
  31. package/dist/detection/owed-selection.js +3 -18
  32. package/dist/detection/owed-selection.js.map +1 -1
  33. package/dist/detection/policy-owed.d.ts +1 -1
  34. package/dist/detection/policy-owed.js +2 -2
  35. package/dist/detection/policy-owed.js.map +1 -1
  36. package/dist/detection/root-examination.d.ts +0 -4
  37. package/dist/detection/root-examination.js +7 -20
  38. package/dist/detection/root-examination.js.map +1 -1
  39. package/dist/detection/root-walk.js +6 -18
  40. package/dist/detection/root-walk.js.map +1 -1
  41. package/dist/detection/runtime.js +4 -3
  42. package/dist/detection/runtime.js.map +1 -1
  43. package/dist/detection/scope-frame.d.ts +0 -3
  44. package/dist/detection/scope-frame.js +2 -2
  45. package/dist/detection/scope-frame.js.map +1 -1
  46. package/dist/detection/walk-law.d.ts +0 -8
  47. package/dist/detection/walk-law.js +0 -23
  48. package/dist/detection/walk-law.js.map +1 -1
  49. package/dist/entity-access-wire.d.ts +1 -1
  50. package/dist/entity-channel-holdings.d.ts +7 -7
  51. package/dist/entity-channel-holdings.js +49 -8
  52. package/dist/entity-channel-holdings.js.map +1 -1
  53. package/dist/entity-grant-watch.d.ts +6 -4
  54. package/dist/entity-grant-watch.js +13 -17
  55. package/dist/entity-grant-watch.js.map +1 -1
  56. package/dist/files-register-host.d.ts +5 -17
  57. package/dist/files-register-host.js +35 -37
  58. package/dist/files-register-host.js.map +1 -1
  59. package/dist/git/rail.d.ts +1 -1
  60. package/dist/git/rail.js +8 -7
  61. package/dist/git/rail.js.map +1 -1
  62. package/dist/git/read-state.d.ts +4 -2
  63. package/dist/git/read-state.js +20 -8
  64. package/dist/git/read-state.js.map +1 -1
  65. package/dist/git/write-files.js +6 -2
  66. package/dist/git/write-files.js.map +1 -1
  67. package/dist/graph-heads.d.ts +6 -0
  68. package/dist/graph-heads.js +8 -0
  69. package/dist/graph-heads.js.map +1 -1
  70. package/dist/ground-database.js +7 -2
  71. package/dist/ground-database.js.map +1 -1
  72. package/dist/ground-install-saves.d.ts +22 -8
  73. package/dist/ground-install-saves.js +23 -11
  74. package/dist/ground-install-saves.js.map +1 -1
  75. package/dist/ground-save-ops.d.ts +4 -3
  76. package/dist/ground-save-ops.js +4 -3
  77. package/dist/ground-save-ops.js.map +1 -1
  78. package/dist/materialize-records.js +1 -1
  79. package/dist/materialize-records.js.map +1 -1
  80. package/dist/native/cloud-files.node +0 -0
  81. package/dist/reference-placement.d.ts +62 -0
  82. package/dist/reference-placement.js +283 -0
  83. package/dist/reference-placement.js.map +1 -0
  84. package/dist/source-signature.d.ts +16 -3
  85. package/dist/source-signature.js +16 -3
  86. package/dist/source-signature.js.map +1 -1
  87. package/dist/user-ground-host.d.ts +47 -22
  88. package/dist/user-ground-host.js +278 -341
  89. package/dist/user-ground-host.js.map +1 -1
  90. package/dist/wire-client.d.ts +2 -3
  91. package/dist/wire-client.js +18 -13
  92. package/dist/wire-client.js.map +1 -1
  93. package/dist/wire-request-scope.d.ts +0 -1
  94. package/dist/wire-request-scope.js +0 -1
  95. package/dist/wire-request-scope.js.map +1 -1
  96. package/examinations/fixtures/private-wire-authority.js +13 -11
  97. package/npm-shrinkwrap.json +6 -6
  98. package/package.json +5 -5
@@ -16,13 +16,12 @@ import { coreRootsAt, isOnDemandRoot } from "./on-demand-roots.js";
16
16
  import { assertGroundInitialized, initializeGroundDatabase } from "./ground-initialization.js";
17
17
  import { GroundBasisChangedError, readGroundRow, rootRevision } from "./ground-basis.js";
18
18
  import { randomUUID } from "node:crypto";
19
- import { existsSync, lstatSync, mkdirSync, realpathSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync, } from "node:fs";
19
+ import { existsSync, lstatSync, mkdirSync, realpathSync, readFileSync, rmSync, statSync, } from "node:fs";
20
20
  import { open, readFile } from "node:fs/promises";
21
21
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
22
22
  import { setTimeout as sleep } from "node:timers/promises";
23
23
  import { buildUserManifest, LOCAL_DIR_NAME, USER_ROOTS, userLayout, } from "@amalgm/core/identity";
24
24
  import { CHUNK_BYTES, INLINE_CARGO_MAX_BYTES, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, artifactKindForType, computerAddress, computerFolder, FILES_FOLDER, classifyDirectory, classifyRegisteredRoot, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, createWeightedGate, parallelForEach, deriveUploadManifest, isContentPlacementChangedError, isRefusal, refusal, downloadAll as downloadAllArtifacts, proveManifests, EntityApplyRail, EntityRecordRail, materializableRecordsSteps, suspectScope, CONTENT_REFS_BATCH_OBJECTS, privateEntityResourceId, sameRecords, snapshotFromRecords, stableJson, streamCargo, upload as uploadArtifact, userGroundSelection, findUserGroundRoot, normalizeUserGroundIdentity, GRAPH_HEAD_OPERATION_KIND, DEFAULT_AMALGM_IGNORE, } from "@amalgm/live";
25
- import { hasLocalWorkAfter } from "./apply-local-work.js";
26
25
  import { ApplyMap, readDriveTop } from "./apply-map.js";
27
26
  import { readInitialPublication } from "./initial-publication.js";
28
27
  import { openFileDatabase } from "./sqlite.js";
@@ -35,7 +34,8 @@ import { createConstructDoor } from "./construct-door.js";
35
34
  import { EntityRecordSqliteStore } from "./entity-record-store.js";
36
35
  import { observeEntityRecordPorts } from "./entity-record-observability.js";
37
36
  import { createEntityAccessPort } from "./entity-access-wire.js";
38
- import { followGrantedChannels, readGrantedChannels } from "./entity-channel-holdings.js";
37
+ import { ENTITY_RECORD_RETRY_BASE_MS, ENTITY_RECORD_RETRY_MAX_MS } from "@amalgm/live/records";
38
+ import { followGrantedChannels } from "./entity-channel-holdings.js";
39
39
  import { indexRowsByOutermostRootSteps } from "./ground-root-index.js";
40
40
  import { ContentCacheDownload, persistRecordCargo, hasSealedContent, hashContentFile, discardCachedArtifact, readManifestHint, readManifestHints, checkedManifestHint, contentFile, writeManifestHint, } from "./content-cache-host.js";
41
41
  import { cargoNamed, journaledCargo, nameCargo } from "./cargo-journal.js";
@@ -67,8 +67,8 @@ import { readSharingPolicy } from "./detection/sharing-policy.js";
67
67
  import { policyExaminations } from "./detection/policy-owed.js";
68
68
  import { frameScope, outermostNames } from "./detection/scope-frame.js";
69
69
  import { readWalkedRoots } from "./detection/walked-roots.js";
70
- import { physicalKey, retainSighting, sourceFingerprint } from "./source-signature.js";
71
- import { assertQualified, sightingUnder, stampContentClock } from "./content-clock.js";
70
+ import { physicalKey, retainSighting } from "./source-signature.js";
71
+ import { assertQualified, stampContentClock } from "./content-clock.js";
72
72
  import { HeldHeads, ProvenGraphs, ReceivedStateUnavailableError, readReceivedState } from "./received-state.js";
73
73
  import { unitMembers } from "./apply-enter-plan.js";
74
74
  import { shownReferenceTo } from "./apply-showing.js";
@@ -78,22 +78,23 @@ import { GitStorageDependencies, NodeWatchHost, presentDirectory, } from "./watc
78
78
  import { beginGroundWait, GroundCoordinator, GroundEffectCrossedError, GroundFootprintExceededError, PackedPhysicalKeys, PhysicalKeySet } from "./ground-coordination.js";
79
79
  import { physicalPath } from "./sync-address.js";
80
80
  import { readAcceptedTail } from "./accepted-tail.js";
81
- import { readDeliveryReceipt, readGraphBasis } from "./graph-heads.js";
81
+ import { readDeliveryReceipt, readGraphBasis, readNewestGraphHead } from "./graph-heads.js";
82
82
  import { AcceptedFold } from "./accepted-fold.js";
83
- import { readDeclarationJournal } from "./declaration-journal.js";
83
+ import { journaledDeclaration, readDeclarationJournal } from "./declaration-journal.js";
84
84
  import { acceptedView, derivePublication } from "./graph-publication.js";
85
- import { addressMinter, deriveDeclarationChain } from "./declaration-chain.js";
86
- import { commitDeclaration, DeclarationChainMoved } from "./declaration-commit.js";
87
- import { DeclarationHeld, heldDeclarations, referenceHold } from "./declaration-hold.js";
85
+ import { deriveDeclarationChain } from "./declaration-chain.js";
86
+ import { placeAcceptedReferences, placeDeclaredWay } from "./reference-placement.js";
87
+ import { commitDeclaration } from "./declaration-commit.js";
88
+ import { DeclarationHeld, heldDeclarations } from "./declaration-hold.js";
88
89
  import { absorbedRoots, absorbingDeclaration, enclosedWorkspaces, } from "./declaration-absorption.js";
89
90
  import { WireClient, WireRequestError } from "./wire-client.js";
90
91
  import { readLinkTarget } from "./link-target.js";
91
92
  import { WireRequestScope } from './wire-request-scope.js';
92
93
  import { sha256Hex } from "./sha256.js";
93
94
  import { DETECT_RETRY_MS, RACY_READINGS, STALE_CAPTURE_ATTEMPTS, movementOf, moving, committed, settlesAfter, firstSettling, DetectResidual, DetectUnavailable, unsettledGround, unavailableOf, unavailableRoots, StaleCaptureError, moved } from "./detection/withheld.js";
94
- import { groundApplyOwnership, readGroundRootAtPath, readRows, hasGroundRows, countGroundRows, hasRootRows, readRootMembers, readRowsRootedAt, countRootRows, readGroundClosureRows, readGroundRowsByUUIDs, findKnownEntityId, entityPathsAtPhysical, coreGroundRecords } from "./ground-reads.js";
95
+ import { groundApplyOwnership, readRows, hasGroundRows, countGroundRows, hasRootRows, readRootMembers, readRowsRootedAt, countRootRows, readGroundClosureRows, readGroundRowsByUUIDs, findKnownEntityId, entityPathsAtPhysical, coreGroundRecords } from "./ground-reads.js";
95
96
  import { workspaceAddCones, workspaceAddStagingPath, workspaceAddSelection, readWorkspaceAddIntent, hasWorkspaceAddIntent, readWorkspaceAddIntents, persistWorkspaceAddIntent, deleteWorkspaceAddIntent } from "./workspace-add-intent.js";
96
- import { capturedGroundRow, persistRows, groundOwner } from "./captured-rows.js";
97
+ import { capturedGroundRow, persistRows } from "./captured-rows.js";
97
98
  import { RootOffDevice, RootUnreachable, RootRecreated, observeRoot } from "./detection/root-walk.js";
98
99
  /** One cargo segment loads its ground bytes across this many concurrent
99
100
  * reads. Reading and hashing overlap the wire without letting a
@@ -209,8 +210,12 @@ export class UserGroundHost {
209
210
  /** Roots whose repository Git itself will not open, with the reason. Every
210
211
  * examination re-derives the answer, so restart finds each one again. */
211
212
  rootRefusals = new Map();
212
- /** The committed head this machine last read or published. */
213
- cloudState = null;
213
+ /** The authority this ground follows, bound before convergence reads
214
+ * anything (bindGroundAuthority). */
215
+ authorityId = null;
216
+ /** One declaration resolution at a time: a lookup's and the one starting
217
+ * leaves in the background (resolveDeclarations). */
218
+ declarationTurn = Promise.resolve();
214
219
  converged = false;
215
220
  /** keptComputerFolder's answer, once read or chosen. */
216
221
  computer;
@@ -251,6 +256,9 @@ export class UserGroundHost {
251
256
  releaseGrantWatch = null;
252
257
  applyRail = null;
253
258
  applyHost = null;
259
+ /** The last placement of accepted declarations (reference-placement.ts);
260
+ * the next one starts after it. */
261
+ placing = Promise.resolve();
254
262
  /** Pays the placement notes every notebook writer leaves (placement-tidy.ts). */
255
263
  placementTidy = null;
256
264
  /** The maps of the roots this computer serves on demand (apply-map.ts),
@@ -460,7 +468,7 @@ export class UserGroundHost {
460
468
  watcherRoots: watchHealth.contentHandles,
461
469
  watching: true,
462
470
  };
463
- // An install's lookup already started Receive; nothing else did.
471
+ // An install's lookup started Receive; on any other ground it starts here.
464
472
  if (!this.recordRail)
465
473
  await this.startRecordRail(this.activeIdentity);
466
474
  this.wire.signal.throwIfAborted();
@@ -468,6 +476,11 @@ export class UserGroundHost {
468
476
  this.wire.signal.throwIfAborted();
469
477
  this.converged = true;
470
478
  this.maintenance.start();
479
+ // Declarations a stop left behind finish in the background, so ready
480
+ // waits on no network: an unanswered one resolves, and one accepted
481
+ // before the stop still owes its way in core, which it holds W until
482
+ // placed.
483
+ this.resolveLeftDeclarations(this.activeIdentity, this.authorityId);
471
484
  // Native rings collected while convergence was establishing Watch
472
485
  // coverage are ordinary evidence, not a startup exception. They get
473
486
  // one Detect generation now that Apply recovery is authoritative.
@@ -588,13 +601,13 @@ export class UserGroundHost {
588
601
  * such root: the map loads nothing, so the host keeps no map for it and the
589
602
  * drive treats the reference that asked as an ordinary entity. */
590
603
  async driveMap(rootUUID) {
591
- if (!this.cloudState || !this.driveGraphs)
604
+ if (!this.authorityId || !this.driveGraphs)
592
605
  throw new Error("the drive needs the entity Apply rail running");
593
606
  let map = this.driveMaps.get(rootUUID);
594
607
  if (!map) {
595
608
  map = new ApplyMap({
596
609
  database: groundDatabase(this.databasePath()),
597
- authorityId: this.cloudState.resourceId,
610
+ authorityId: this.authorityId,
598
611
  rootUUID,
599
612
  graphs: this.driveGraphs,
600
613
  onChange: (touched) => { for (const listener of this.driveListeners)
@@ -634,9 +647,9 @@ export class UserGroundHost {
634
647
  * on. A size that cannot be measured now is null, and the drive asks
635
648
  * again on its next listing (drive/operations.ts). */
636
649
  async driveSizes(files) {
637
- if (!this.cloudState)
650
+ if (!this.authorityId)
638
651
  throw new Error("the drive needs the entity Apply rail running");
639
- const resourceId = this.cloudState.resourceId;
652
+ const resourceId = this.authorityId;
640
653
  const cacheDir = this.cacheDir();
641
654
  const artifacts = files.map((entry) => {
642
655
  const kind = artifactKindForType(entry.type);
@@ -675,11 +688,11 @@ export class UserGroundHost {
675
688
  * asked for a root the drive has not entered. Null exactly when `driveMap`
676
689
  * would be. */
677
690
  async driveTop(rootUUID) {
678
- if (!this.cloudState || !this.driveTops)
691
+ if (!this.authorityId || !this.driveTops)
679
692
  throw new Error("the drive needs the entity Apply rail running");
680
693
  return readDriveTop({
681
694
  database: groundDatabase(this.databasePath()),
682
- authorityId: this.cloudState.resourceId,
695
+ authorityId: this.authorityId,
683
696
  rootUUID,
684
697
  heads: this.driveTops,
685
698
  });
@@ -1000,7 +1013,7 @@ export class UserGroundHost {
1000
1013
  async beginRootEnter(rootUUID, through) {
1001
1014
  const shelf = this.driveShelf;
1002
1015
  const graphs = this.driveGraphs;
1003
- if (!shelf || !graphs || !this.cloudState) {
1016
+ if (!shelf || !graphs || !this.authorityId) {
1004
1017
  throw new Error(`${rootUUID} enters only onto the shelf of a drive placing here`);
1005
1018
  }
1006
1019
  const database = this.databasePath();
@@ -1010,7 +1023,7 @@ export class UserGroundHost {
1010
1023
  : readGroundRowsByUUIDs(database, "entities", new Set([referenceUUID]))[0];
1011
1024
  if (!reference)
1012
1025
  throw new Error(`no reference this computer shows leads to ${rootUUID}`);
1013
- const authorityId = this.cloudState.resourceId;
1026
+ const authorityId = this.authorityId;
1014
1027
  const head = readGraphBasis(db, authorityId, through);
1015
1028
  if (!head)
1016
1029
  throw new ReceivedStateUnavailableError(authorityId, through);
@@ -1096,7 +1109,7 @@ export class UserGroundHost {
1096
1109
  });
1097
1110
  if (!intent.onDemand) {
1098
1111
  const selection = workspaceAddSelection(intent);
1099
- await installCloudWorkspaceReferences({
1112
+ await placeAcceptedReferences({
1100
1113
  identity,
1101
1114
  userRoot,
1102
1115
  database,
@@ -1130,22 +1143,26 @@ export class UserGroundHost {
1130
1143
  await deleteWorkspaceAddIntent(database, intent.workspaceId);
1131
1144
  }
1132
1145
  /** Register W: publish its declaration D, W's walked subtree and the core
1133
- * records that reach it, in one graph head. Locally Register admits D and
1134
- * the bookkeeping that installs it, and nothing else: every other
1135
- * observation stays owed to ordinary Detect, and W stays held from it until
1136
- * the authority accepts D. Live's binding and reference stay durable if a
1137
- * later stage fails, so a retry declares the same W again. */
1146
+ * records that reach it, in one graph head. Locally Register admits W's
1147
+ * ground beside D's journal row, and nothing else: core gains D's folders
1148
+ * and reference only once the authority accepts D, placed as the accepted
1149
+ * view holds them, and W stays held from ordinary Detect until then. A
1150
+ * declaration an earlier Register left accepted but unplaced is placed
1151
+ * first. Live's binding stays durable if a later stage fails, so a retry
1152
+ * declares the same W again. */
1138
1153
  async completeWorkspaceRegistration(workspaceId) {
1139
1154
  const identity = this.activeIdentity;
1140
- if (!identity || !this.converged || !this.cloudState) {
1155
+ if (!identity || !this.converged || !this.authorityId) {
1141
1156
  throw new Error("Files register requires a converged authenticated machine");
1142
1157
  }
1143
1158
  const file = this.databasePath();
1144
- const resourceId = this.cloudState.resourceId;
1159
+ const resourceId = this.authorityId;
1160
+ let cloudHead;
1145
1161
  let watch = this.registrationCoverage(identity, workspaceId, "register-coverage");
1146
1162
  try {
1147
1163
  const view = await this.freshAcceptedView(identity, resourceId, 0);
1148
1164
  const coreRootId = await this.declarationCoreRoot(identity, view);
1165
+ await this.placeAcceptedDeclarations(identity, view);
1149
1166
  if (await this.acceptedWorkspace(view, workspaceId)) {
1150
1167
  // Whatever W or its reference holds beyond the accepted declaration
1151
1168
  // is ordinary work, syncing through its own Records.
@@ -1154,7 +1171,7 @@ export class UserGroundHost {
1154
1171
  registered: true,
1155
1172
  alreadyRegistered: true,
1156
1173
  entityCount: countRootRows(file, resourceId, workspaceId),
1157
- cloudHead: this.cloudState.checksum,
1174
+ cloudHead: view.head.checksum,
1158
1175
  watch,
1159
1176
  };
1160
1177
  }
@@ -1164,6 +1181,8 @@ export class UserGroundHost {
1164
1181
  if (!await this.acceptedWorkspace(accepted, workspaceId) || !core.some((record) => record.type === "reference" && record.status === "active" && record.payloadVersion === workspaceId)) {
1165
1182
  throw failedDuring("pipeline", "cloud graph commit", new Error(`workspace ${workspaceId} or its durable reference is absent from the committed head`));
1166
1183
  }
1184
+ await this.placeAcceptedDeclarations(identity, accepted);
1185
+ cloudHead = accepted.head.checksum;
1167
1186
  }
1168
1187
  catch (error) {
1169
1188
  const failedStage = filesPipelineStage(error);
@@ -1178,7 +1197,7 @@ export class UserGroundHost {
1178
1197
  return {
1179
1198
  registered: true,
1180
1199
  entityCount: countRootRows(file, resourceId, workspaceId),
1181
- cloudHead: this.cloudState.checksum,
1200
+ cloudHead,
1182
1201
  watch,
1183
1202
  };
1184
1203
  }
@@ -1336,9 +1355,10 @@ export class UserGroundHost {
1336
1355
  }
1337
1356
  }
1338
1357
  /** Fold D onto a fresh accepted view and admit it beside a new journal
1339
- * row. The commit reads the chain's addresses again, so core Detect working
1340
- * beside Register is never overwritten; a chain that moved folds again. */
1341
- declarationFold(identity, resourceId, coreRootId, workspaceId, { bindingDir, directory, enclosed }) {
1358
+ * row. D's core records are records alone: nothing of them stands on disk
1359
+ * until the authority accepts them, so core Detect working beside Register
1360
+ * has nothing of D's to see or overwrite. */
1361
+ declarationFold(identity, resourceId, coreRootId, workspaceId, { directory, enclosed }) {
1342
1362
  const file = this.databasePath();
1343
1363
  const database = groundDatabase(file);
1344
1364
  const userRoot = this.userRoot();
@@ -1347,52 +1367,43 @@ export class UserGroundHost {
1347
1367
  throw new Error(`workspace ${workspaceId} was declared before this computer chose its folder`);
1348
1368
  const address = computerAddress(computer, directory);
1349
1369
  const enclosedIds = enclosed.map((entry) => entry.workspaceId);
1350
- // One UUID per new chain address for the whole Register.
1351
- const mint = addressMinter(randomUUID);
1352
1370
  return async (records, walk, beyond) => {
1353
1371
  const view = await this.freshAcceptedView(identity, resourceId, beyond);
1354
1372
  const accepted = new Map((await view.fold.root(coreRootId)).map((record) => [record.uuid, record]));
1355
1373
  const absorbed = await absorbedRoots(view, workspaceId, enclosed, heldDeclarations(database, enclosedIds));
1356
1374
  const declared = await absorbingDeclaration(view, workspaceId, records, absorbed, sha256Hex);
1357
- for (let attempt = 1;; attempt++) {
1358
- const { boundary: clock } = await stampContentClock(file, userRoot);
1359
- // Derived and kept in one step, so every Register on this computer
1360
- // names the same folder as its own.
1361
- const chain = deriveDeclarationChain({
1362
- database, resourceId, userRoot, bindingDir, address, coreRootId, workspaceId, accepted,
1363
- computerFolder: this.keptComputerFolderId(), clock, mint, sha256Hex,
1364
- });
1365
- this.keepComputerFolderId(chain.computerFolder);
1366
- const derived = chain.records;
1367
- const { rebuild, operationBlob, fresh } = await derivePublication(view, { root: workspaceId, records: declared, core: derived, absorbed }, sha256Hex);
1368
- const journal = {
1369
- mutationId: randomUUID(),
1370
- resourceId,
1371
- declarationRoot: workspaceId,
1372
- declaredIds: derived.map((record) => record.uuid),
1373
- authorityEpoch: view.head.authorityEpoch,
1374
- baseVersion: view.head.headVersion,
1375
- snapshotChecksum: view.head.checksum,
1376
- deliveryWatermark: view.tail.through,
1377
- operationKind: GRAPH_HEAD_OPERATION_KIND,
1378
- replacementRootIds: rebuild.operation.replacedRootIds,
1379
- operationBlob,
1380
- pages: fresh.map((page) => ({ sha256: page.ref.sha256, bytes: Buffer.from(page.bytes) })),
1381
- status: "pending",
1382
- submitted: false,
1383
- };
1384
- // Semantic answers come last before the commit, which closes the
1385
- // walk's physical witnesses.
1386
- await walk?.source.semantic();
1387
- try {
1388
- await commitDeclaration(file, { resourceId, coreRootId, walk, absorbed, enclosed: enclosedIds, chain, journal });
1389
- return journal;
1390
- }
1391
- catch (error) {
1392
- if (!(error instanceof DeclarationChainMoved) || attempt >= STALE_CAPTURE_ATTEMPTS)
1393
- throw error;
1394
- }
1395
- }
1375
+ // Derived and kept in one step, so every Register on this computer
1376
+ // names the same folder as its own.
1377
+ const chain = deriveDeclarationChain({
1378
+ database, resourceId, userRoot, address, coreRootId, workspaceId, accepted,
1379
+ computerFolder: this.keptComputerFolderId(),
1380
+ journaled: journaledDeclaration(database, workspaceId, coreRootId, sha256Hex),
1381
+ mint: randomUUID, sha256Hex,
1382
+ });
1383
+ this.keepComputerFolderId(chain.computerFolder);
1384
+ const core = chain.records;
1385
+ const { rebuild, operationBlob, fresh } = await derivePublication(view, { root: workspaceId, records: declared, core, absorbed }, sha256Hex);
1386
+ const journal = {
1387
+ mutationId: randomUUID(),
1388
+ resourceId,
1389
+ declarationRoot: workspaceId,
1390
+ declaredIds: core.map((record) => record.uuid),
1391
+ authorityEpoch: view.head.authorityEpoch,
1392
+ baseVersion: view.head.headVersion,
1393
+ snapshotChecksum: view.head.checksum,
1394
+ deliveryWatermark: view.tail.through,
1395
+ operationKind: GRAPH_HEAD_OPERATION_KIND,
1396
+ replacementRootIds: rebuild.operation.replacedRootIds,
1397
+ operationBlob,
1398
+ pages: fresh.map((page) => ({ sha256: page.ref.sha256, bytes: Buffer.from(page.bytes) })),
1399
+ status: "pending",
1400
+ submitted: false,
1401
+ };
1402
+ // Semantic answers come last before the commit, which closes the
1403
+ // walk's physical witnesses.
1404
+ await walk?.source.semantic();
1405
+ await commitDeclaration(file, { resourceId, walk, absorbed, enclosed: enclosedIds, journal });
1406
+ return journal;
1396
1407
  };
1397
1408
  }
1398
1409
  /** W's ground on this machine: its binding, and every bound workspace it
@@ -1540,7 +1551,7 @@ export class UserGroundHost {
1540
1551
  * refused at that boundary are named: their local rows are current, and
1541
1552
  * their last complete result remains the official one. */
1542
1553
  async flush() {
1543
- if (!this.converged || !this.activeIdentity || !this.cloudState)
1554
+ if (!this.converged || !this.activeIdentity || !this.authorityId)
1544
1555
  throw new GroundNotConverged();
1545
1556
  const identity = this.activeIdentity;
1546
1557
  this.watchHost.suspectAll();
@@ -1952,9 +1963,9 @@ export class UserGroundHost {
1952
1963
  const file = this.databasePath();
1953
1964
  groundDatabase(file);
1954
1965
  const started = performance.now();
1955
- const { value: retired } = await save(file, "ground.bindAuthority", {
1956
- authorityId: privateEntityResourceId(identity.userId, sha256Hex),
1957
- });
1966
+ const authorityId = privateEntityResourceId(identity.userId, sha256Hex);
1967
+ const { value: retired } = await save(file, "ground.bindAuthority", { authorityId });
1968
+ this.authorityId = authorityId;
1958
1969
  this.stage({ primitive: "detect", stage: "authority-binding", status: "completed",
1959
1970
  durationMs: performance.now() - started, measurements: { ...retired } });
1960
1971
  }
@@ -1970,17 +1981,10 @@ export class UserGroundHost {
1970
1981
  this.wakeDriveMaps();
1971
1982
  }
1972
1983
  async startRecordRail(identity) {
1973
- if (!this.cloudState)
1984
+ if (!this.authorityId)
1974
1985
  throw new Error("entity Record rail requires cloud authority");
1975
1986
  if (this.recordRail || this.recordStore)
1976
1987
  throw new Error("entity Record rail already started");
1977
- await this.wire.open();
1978
- // One floor, no per-feature gates: this shell and its gateway release
1979
- // together, and the gateway ships first. 18 = batch Send; an older
1980
- // gateway reads only one record per submit and cannot answer a batch.
1981
- if (this.wire.protocolVersion < 18) {
1982
- throw new Error("gateway speaks an older wire protocol than this shell");
1983
- }
1984
1988
  const recordDatabase = openGroundConnection(this.databasePath());
1985
1989
  const store = new EntityRecordSqliteStore(recordDatabase, this.cacheDir());
1986
1990
  const ledger = new ConstructLedger(recordDatabase, () => this.options.now?.().getTime() ?? Date.now());
@@ -2012,10 +2016,6 @@ export class UserGroundHost {
2012
2016
  onFrame: (listener) => this.wire.onEvent(listener),
2013
2017
  onDisconnect: (listener) => this.wire.onDisconnect(listener),
2014
2018
  });
2015
- // Every construct channel this user may read, before the rail subscribes:
2016
- // a held channel starts at its own Inbox cursor, so start is the only
2017
- // place the complete set can be proven without a second catch-up pass.
2018
- const channels = await readGrantedChannels(access, identity.userId);
2019
2019
  const ports = observeEntityRecordPorts({
2020
2020
  store,
2021
2021
  authority: wireAuthority,
@@ -2035,7 +2035,7 @@ export class UserGroundHost {
2035
2035
  onStage: this.options.onFilesStage,
2036
2036
  });
2037
2037
  const rail = new EntityRecordRail({
2038
- authorityId: this.cloudState.resourceId,
2038
+ authorityId: this.authorityId,
2039
2039
  store: ports.store,
2040
2040
  // Send and Receive resume from each network answer in a dispatcher
2041
2041
  // turn, taking turns with Detect and Apply instead of stacking on them.
@@ -2059,7 +2059,6 @@ export class UserGroundHost {
2059
2059
  },
2060
2060
  random: Math.random,
2061
2061
  },
2062
- channels,
2063
2062
  onInboxCommitted: () => {
2064
2063
  this.applyRail?.recordsAvailable();
2065
2064
  this.wakeDriveMaps();
@@ -2101,16 +2100,19 @@ export class UserGroundHost {
2101
2100
  this.constructDoor = null;
2102
2101
  throw failedDuring("pipeline", "entity record subscribe", error);
2103
2102
  }
2104
- this.releaseGrantWatch = await followGrantedChannels({
2103
+ // The construct channels this user may read join the rail when the
2104
+ // grant watch first answers, in the background, so starting asks the
2105
+ // authority nothing.
2106
+ this.releaseGrantWatch = followGrantedChannels({
2105
2107
  access,
2106
2108
  rail,
2107
2109
  userId: identity.userId,
2108
- held: channels,
2109
2110
  onError: (error) => this.options.onBackgroundError?.(error instanceof Error ? error : new Error(String(error))),
2110
2111
  });
2111
2112
  }
2112
2113
  async startApplyRail() {
2113
- if (!this.cloudState)
2114
+ const authorityId = this.authorityId;
2115
+ if (!authorityId)
2114
2116
  throw new Error("entity Apply rail requires cloud authority");
2115
2117
  if (this.applyRail || this.applyHost)
2116
2118
  throw new Error("entity Apply rail already started");
@@ -2125,7 +2127,7 @@ export class UserGroundHost {
2125
2127
  // A container Enter reads the authority's state at its own position
2126
2128
  // through the pages Add and login read; a drive map holds the same
2127
2129
  // proven graphs.
2128
- const graphs = new ProvenGraphs(resumeInTurn((ref) => untilAborted(this.applyWaits.signal, () => this.readGraphPage(this.cloudState.resourceId, ref))));
2130
+ const graphs = new ProvenGraphs(resumeInTurn((ref) => untilAborted(this.applyWaits.signal, () => this.readGraphPage(authorityId, ref))));
2129
2131
  this.driveGraphs = graphs;
2130
2132
  this.driveTops = new HeldHeads(graphs);
2131
2133
  let host = null;
@@ -2155,10 +2157,10 @@ export class UserGroundHost {
2155
2157
  // A construct's cargo lives under its own UUID, never the home's.
2156
2158
  const owned = wants.filter(want => want.artifact.kind === "construct");
2157
2159
  if (owned.length === 0)
2158
- return download(this.cloudState.resourceId, wants);
2160
+ return download(authorityId, wants);
2159
2161
  const home = wants.filter(want => want.artifact.kind !== "construct");
2160
2162
  const sets = await Promise.all([
2161
- ...(home.length > 0 ? [download(this.cloudState.resourceId, home)] : []),
2163
+ ...(home.length > 0 ? [download(authorityId, home)] : []),
2162
2164
  ...owned.map(want => download(want.artifact.entityId, [want])),
2163
2165
  ]);
2164
2166
  return new Map(sets.flatMap(set => [...set]));
@@ -2714,7 +2716,7 @@ export class UserGroundHost {
2714
2716
  const kept = this.keptComputerFolder();
2715
2717
  if (kept !== null)
2716
2718
  return kept;
2717
- const view = await this.freshAcceptedView(identity, this.cloudState.resourceId, 0);
2719
+ const view = await this.freshAcceptedView(identity, this.authorityId, 0);
2718
2720
  const coreRootId = await this.declarationCoreRoot(identity, view);
2719
2721
  const core = await view.fold.root(coreRootId);
2720
2722
  const folder = core.find((record) => record.parentUUID === coreRootId && record.name === FILES_FOLDER
@@ -2759,19 +2761,8 @@ export class UserGroundHost {
2759
2761
  cloudPort(identity, scope) {
2760
2762
  return {
2761
2763
  lookup: async (resourceId) => {
2762
- await this.resolveDeclarationsBeforeLookup(identity, resourceId);
2763
- const frame = await this.wire.request({
2764
- type: "private.resource.lookup",
2765
- resource_id: resourceId,
2766
- contract: ENTITY_CLOUD_CONTRACT,
2767
- }, ["private.resource.ready", "private.resource.missing"]);
2768
- if (frame.type === "private.resource.missing")
2769
- return null;
2770
- const graph = this.materializeRegistry(frame);
2771
- const ready = readyFromFrame(frame, graph, await this.selectScope(identity, graph, scope));
2772
- await this.keepGraphHead(frame, ready.state);
2773
- this.cloudState = ready.state;
2774
- return this.installableGround(identity, scope, ready);
2764
+ const ready = await this.readHead(identity, resourceId, scope);
2765
+ return ready && this.installableGround(identity, scope, ready);
2775
2766
  },
2776
2767
  publishInitial: async (input) => {
2777
2768
  const bytes = Buffer.from(stableJson(input.snapshot), "utf8");
@@ -2787,7 +2778,6 @@ export class UserGroundHost {
2787
2778
  const graph = this.materializeRegistry(frame);
2788
2779
  const ready = readyFromFrame(frame, graph, await this.selectScope(identity, graph, scope));
2789
2780
  await this.keepGraphHead(frame, ready.state);
2790
- this.cloudState = ready.state;
2791
2781
  // The authority keeps its first graph's checksum: that graph's
2792
2782
  // creation and every retry of it are not duplicates. A created graph
2793
2783
  // is this ground's own at the line's origin; another one is installed.
@@ -2796,6 +2786,23 @@ export class UserGroundHost {
2796
2786
  },
2797
2787
  };
2798
2788
  }
2789
+ /** The authority's head as it stands, selected to the scope and kept, read
2790
+ * once every declaration whose outcome this process never learned has
2791
+ * resolved; null when the authority holds no graph for this person. */
2792
+ async readHead(identity, resourceId, scope) {
2793
+ await this.resolveDeclarations(identity, resourceId);
2794
+ const frame = await this.wire.request({
2795
+ type: "private.resource.lookup",
2796
+ resource_id: resourceId,
2797
+ contract: ENTITY_CLOUD_CONTRACT,
2798
+ }, ["private.resource.ready", "private.resource.missing"]);
2799
+ if (frame.type === "private.resource.missing")
2800
+ return null;
2801
+ const graph = this.materializeRegistry(frame);
2802
+ const ready = readyFromFrame(frame, graph, await this.selectScope(identity, graph, scope));
2803
+ await this.keepGraphHead(frame, ready.state);
2804
+ return ready;
2805
+ }
2799
2806
  /** The graph an install reads (AGENTS.md §5): the head at N plus the
2800
2807
  * complete accepted tail the Inbox holds after N, folded by the one reducer
2801
2808
  * and selected to the operation's roots, at the tail's watermark T. Login
@@ -3882,14 +3889,11 @@ export class UserGroundHost {
3882
3889
  * These are ambiguous recovery facts, so each affected root is wholly
3883
3890
  * suspect; unrelated roots remain untouched. */
3884
3891
  repairRegistrationGround(identity) {
3885
- const userRoot = this.userRoot();
3886
- const repair = registrationRepairGround(this.databasePath(), userRoot, this.bindingDir());
3887
- if (!repair.core && repair.emptyRoots.length === 0)
3892
+ const emptyRoots = emptyBoundRoots(this.databasePath(), this.bindingDir());
3893
+ if (emptyRoots.length === 0)
3888
3894
  return;
3889
3895
  this.ensureWatchers(identity);
3890
- if (repair.core)
3891
- this.watchHost.suspect(userRoot);
3892
- for (const root of repair.emptyRoots)
3896
+ for (const root of emptyRoots)
3893
3897
  this.watchHost.suspect(root);
3894
3898
  }
3895
3899
  /** A prepared lane holds its slot across one boundary, then activates.
@@ -4164,7 +4168,7 @@ export class UserGroundHost {
4164
4168
  const result = await maintainRootContent({
4165
4169
  purpose: "maintenance", database: this.databasePath(), cacheDir: this.cacheDir(),
4166
4170
  resourceId: privateEntityResourceId(identity.userId, sha256Hex), rootPath: directory,
4167
- bindingDir: this.bindingDir(), core: directory === userRoot ? { name: identity.userEmail } : null,
4171
+ core: directory === userRoot ? { name: identity.userEmail } : null,
4168
4172
  });
4169
4173
  if (result.rootUUID !== null && result.gaps.length === 0 && !result.findings.some(finding => finding.path === "")) {
4170
4174
  this.warmDiscovery(result.rootUUID, directory);
@@ -4363,7 +4367,7 @@ export class UserGroundHost {
4363
4367
  // A fault here costs only this shortcut; the main walk answers for it.
4364
4368
  try {
4365
4369
  result = await examineRootContent({ purpose: "admission", database, cacheDir: this.cacheDir(), resourceId,
4366
- rootPath: directory, bindingDir: this.bindingDir(), core, clock });
4370
+ rootPath: directory, core, clock });
4367
4371
  }
4368
4372
  catch (error) {
4369
4373
  fallbacks.set(directory, `fault:${error instanceof Error ? error.message : String(error)}`);
@@ -4481,7 +4485,7 @@ export class UserGroundHost {
4481
4485
  } } };
4482
4486
  }
4483
4487
  async syncLocalChangesUnlocked(identity, pending, pass, lease, lane = "complete") {
4484
- if (!this.cloudState)
4488
+ if (!this.authorityId)
4485
4489
  throw new Error("cloud state is unavailable for user-ground Watch");
4486
4490
  // A repository lane proves one root's cut; its passes pair by that root.
4487
4491
  const laneRootId = lane === "repository" ? { rootId: pending[0].rootId } : {};
@@ -4537,7 +4541,6 @@ export class UserGroundHost {
4537
4541
  checkpoint,
4538
4542
  ...(completeDomain ? { domain: reconcileObservations } : {}),
4539
4543
  ground: reconcileLease,
4540
- coreScan: walkedSuspicions.has(userRoot),
4541
4544
  selectionFallbacks: fallbacks,
4542
4545
  units: true,
4543
4546
  rootScopes: new Map([...scoped].map(([directory, root]) => [directory, root.request])),
@@ -4709,7 +4712,7 @@ export class UserGroundHost {
4709
4712
  await persistRecordCargo(this.cacheDir(), ready.flatMap(unit => unit.writes.proposals.flatMap(proposal => proposal.cargo.map(artifact => artifact.contentHash))));
4710
4713
  // Last scheduling handoff precedes each unit's final validation and admission.
4711
4714
  checkpoint();
4712
- const authorityId = this.cloudState.resourceId;
4715
+ const authorityId = this.authorityId;
4713
4716
  const cursors = this.recordStore?.readEntityCursors(authorityId, ready.flatMap(unit => unit.writes.proposals.map(proposal => proposal.entityId))) ?? new Map();
4714
4717
  const physicalReads = new PhysicalKeySet(...scanned.roots.map(root => root.units.physicalReads));
4715
4718
  // A unit consumes each discovery that answered for one of its members:
@@ -4831,7 +4834,7 @@ export class UserGroundHost {
4831
4834
  for (const path of owed)
4832
4835
  this.watchHost.suspect(path);
4833
4836
  // A committed policy change owes its selection (policy-owed.ts).
4834
- for (const path of await policyExaminations(database.name, this.bindingDir(), committedNames, rootUUID => {
4837
+ for (const path of await policyExaminations(database.name, committedNames, rootUUID => {
4835
4838
  const root = scanned.roots.find(root => root.rootUUID === rootUUID);
4836
4839
  return { directory: root.directory, policy: root.units.policy };
4837
4840
  }))
@@ -5044,27 +5047,69 @@ export class UserGroundHost {
5044
5047
  });
5045
5048
  }
5046
5049
  /** Declarations whose outcome this process never learned resolve before a
5047
- * lookup reads the head. A submitted row may already be accepted: its exact
5048
- * mutation recovers the receipt. A conclusive refusal settles the row as
5049
- * rejected, and its ground stays held until Register declares it again. */
5050
- async resolveDeclarationsBeforeLookup(identity, resourceId) {
5051
- const file = this.databasePath();
5052
- if (!existsSync(file))
5053
- return;
5054
- for (const entry of readDeclarationJournal(groundDatabase(file))) {
5055
- if (entry.status === "rejected")
5056
- continue;
5057
- if (entry.resourceId !== resourceId) {
5058
- throw new Error("local declaration publication belongs to a different user-ground resource");
5059
- }
5060
- try {
5061
- await this.submitDeclaration(identity, entry);
5050
+ * lookup reads the head, one resolution at a time. A submitted row may
5051
+ * already be accepted: its exact mutation recovers the receipt, and its way
5052
+ * in core is placed once the lookup is done. A conclusive refusal settles
5053
+ * the row as rejected, and its ground stays held until Register declares it
5054
+ * again. `only` limits it to those rows. */
5055
+ resolveDeclarations(identity, resourceId, only) {
5056
+ const turn = this.declarationTurn.then(async () => {
5057
+ const file = this.databasePath();
5058
+ if (!existsSync(file))
5059
+ return;
5060
+ let accepted = false;
5061
+ for (const entry of readDeclarationJournal(groundDatabase(file))) {
5062
+ if (entry.status !== "pending" || (only && !only.has(entry.mutationId)))
5063
+ continue;
5064
+ if (entry.resourceId !== resourceId) {
5065
+ throw new Error("local declaration publication belongs to a different user-ground resource");
5066
+ }
5067
+ try {
5068
+ await this.submitDeclaration(identity, entry);
5069
+ accepted = true;
5070
+ }
5071
+ catch (error) {
5072
+ if (!conclusivelyRefused(error))
5073
+ throw error;
5074
+ }
5062
5075
  }
5063
- catch (error) {
5064
- if (!conclusivelyRefused(error))
5065
- throw error;
5076
+ // Before convergence, its end places every accepted declaration.
5077
+ if (accepted && this.converged) {
5078
+ void this.placeAcceptedDeclarations(identity)
5079
+ .catch((error) => this.options.onBackgroundError?.(error));
5066
5080
  }
5067
- }
5081
+ });
5082
+ this.declarationTurn = turn.catch(() => undefined);
5083
+ return turn;
5084
+ }
5085
+ /** Declarations a stop left behind finish in the background once the
5086
+ * authority answers, so starting waits on no network: an unanswered one
5087
+ * resolves, and every accepted one is placed. An attempt that fails is
5088
+ * reported, waits its backoff and tries again, until shutdown. Only the
5089
+ * rows standing now: a later one is its Register's, which submits and
5090
+ * places it itself. */
5091
+ resolveLeftDeclarations(identity, resourceId) {
5092
+ const left = readDeclarationJournal(groundDatabase(this.databasePath()))
5093
+ .filter((entry) => entry.status !== "rejected");
5094
+ if (left.length === 0)
5095
+ return;
5096
+ const pending = new Set(left.filter((entry) => entry.status === "pending").map((entry) => entry.mutationId));
5097
+ let delay = ENTITY_RECORD_RETRY_BASE_MS;
5098
+ const attempt = () => {
5099
+ if (this.closing || this.wire.signal.aborted)
5100
+ return;
5101
+ this.operation(async () => {
5102
+ await this.resolveDeclarations(identity, resourceId, pending);
5103
+ await this.placeAcceptedDeclarations(identity);
5104
+ }).catch((error) => {
5105
+ if (this.closing || this.wire.signal.aborted)
5106
+ return;
5107
+ this.options.onBackgroundError?.(error instanceof Error ? error : new Error(String(error)));
5108
+ setTimeout(attempt, delay).unref();
5109
+ delay = Math.min(delay * 2, ENTITY_RECORD_RETRY_MAX_MS);
5110
+ });
5111
+ };
5112
+ attempt();
5068
5113
  }
5069
5114
  /** AV: the authority's current head H plus every accepted result Receive
5070
5115
  * has delivered after its watermark M. The head is read fresh, because a
@@ -5074,8 +5119,7 @@ export class UserGroundHost {
5074
5119
  * state is what the authority has accepted, whatever this machine has
5075
5120
  * physically applied or still owes. */
5076
5121
  async freshAcceptedView(identity, resourceId, beyond) {
5077
- await this.cloudPort(identity, { kind: "none" }).lookup(resourceId);
5078
- const head = this.cloudState;
5122
+ const head = (await this.readHead(identity, resourceId, { kind: "none" }))?.state;
5079
5123
  if (!head || head.resourceId !== resourceId) {
5080
5124
  throw new Error("the authority holds no entity registry for this user");
5081
5125
  }
@@ -5158,13 +5202,12 @@ export class UserGroundHost {
5158
5202
  }
5159
5203
  /** Seal a journaled declaration's pages and submit its exact head commit.
5160
5204
  * Its content sealed before the row was journaled, so only pages move here.
5161
- * Acceptance clears the row and wakes the ground it held: acceptance is not
5162
- * an entity delivery, so no delivery would wake it. A non-retryable answer
5163
- * settles the row as rejected; every other failure leaves it pending with
5164
- * its outcome unknown. */
5205
+ * Acceptance keeps the committed head and leaves the row owing placement:
5206
+ * W stays held until the folders on its way and its reference stand
5207
+ * (`placeAcceptedDeclarations`). A non-retryable answer settles the row as rejected;
5208
+ * every other failure leaves it pending with its outcome unknown. */
5165
5209
  async submitDeclaration(identity, entry, trace) {
5166
5210
  const file = this.databasePath();
5167
- const database = groundDatabase(file);
5168
5211
  try {
5169
5212
  await this.uploadGraphPages(entry.resourceId, entry.pages, trace);
5170
5213
  }
@@ -5232,7 +5275,7 @@ export class UserGroundHost {
5232
5275
  // The authority stores exactly the head this commit names, so its
5233
5276
  // canonical bytes are the head this machine keeps.
5234
5277
  const committed = Buffer.from(stableJson(JSON.parse(entry.operationBlob.toString("utf8")).head), "utf8");
5235
- await local("clearJournal", () => save(file, "register.cleared", {
5278
+ await local("markAccepted", () => save(file, "register.accepted", {
5236
5279
  mutationId: entry.mutationId,
5237
5280
  head: {
5238
5281
  authorityId: entry.resourceId,
@@ -5242,7 +5285,6 @@ export class UserGroundHost {
5242
5285
  checksum: sha256Hex(committed),
5243
5286
  },
5244
5287
  }));
5245
- this.wakeDeclaration(database, entry);
5246
5288
  if (trace?.journey === "register") {
5247
5289
  // The authority reports where its side of the commit went; carrying
5248
5290
  // its legs here gives one ledger line the whole story: local journal
@@ -5275,22 +5317,64 @@ export class UserGroundHost {
5275
5317
  deliveryWatermark: Number(frame.delivery_watermark),
5276
5318
  };
5277
5319
  }
5278
- /** The accepted declaration no longer holds its ground. Acceptance is not
5279
- * an entity delivery and rings no filesystem event, so it wakes what the
5280
- * declaration held itself: the core records it added are suspected, and
5281
- * every lane parked on its root reruns with whatever W owes. */
5282
- wakeDeclaration(database, entry) {
5283
- const ids = entry.declaredIds;
5284
- const paths = ids.length === 0 ? [] : database.prepare(`
5285
- SELECT absolute_path FROM entities WHERE uuid IN (${ids.map(() => "?").join(", ")})
5286
- `).pluck().all(...ids);
5287
- for (const path of paths)
5288
- this.watchHost.suspect(path);
5289
- for (const [lane, park] of [...this.parkedDetect]) {
5290
- if (park.error instanceof DeclarationHeld && park.error.roots.includes(entry.declarationRoot))
5291
- this.unpark(lane);
5320
+ /** Place what every accepted declaration added in core, one placement at a
5321
+ * time: each holds core ground, so two never wait on each other. `given` is
5322
+ * a view the caller just read. A declaration it does not show may have been
5323
+ * accepted after that read, so it is placed again on a fresh view; a fresh
5324
+ * view read after its acceptance that still does not show it proves it gone. */
5325
+ placeAcceptedDeclarations(identity, given) {
5326
+ const placed = this.placing.then(() => this.placeDeclarations(identity, given));
5327
+ this.placing = placed.catch(() => undefined);
5328
+ return placed;
5329
+ }
5330
+ async placeDeclarations(identity, given) {
5331
+ const file = this.databasePath();
5332
+ if (!existsSync(file) || !this.authorityId)
5333
+ return;
5334
+ const resourceId = this.authorityId;
5335
+ const accepted = () => readDeclarationJournal(groundDatabase(file))
5336
+ .filter((entry) => entry.status === "accepted" && entry.resourceId === resourceId);
5337
+ const acceptedBefore = new Set(accepted().map((entry) => entry.mutationId));
5338
+ if (acceptedBefore.size === 0)
5339
+ return;
5340
+ const view = given ?? await this.freshAcceptedView(identity, resourceId, 0);
5341
+ const coreRootId = await this.declarationCoreRoot(identity, view);
5342
+ const userRoot = this.userRoot();
5343
+ const placements = [];
5344
+ const release = await this.acquireGroundScope([userRoot]);
5345
+ try {
5346
+ for (const entry of accepted()) {
5347
+ placements.push({ root: entry.declarationRoot, placement: await placeDeclaredWay({
5348
+ identity, database: file, userRoot, bindingDir: this.bindingDir(), resourceId, coreRootId, entry, view,
5349
+ unseenIsGone: given === undefined && acceptedBefore.has(entry.mutationId),
5350
+ }) });
5351
+ }
5352
+ }
5353
+ finally {
5354
+ release();
5355
+ }
5356
+ let unseen = false;
5357
+ for (const { root, placement } of placements) {
5358
+ if (placement.kind === "unseen") {
5359
+ unseen = true;
5360
+ continue;
5361
+ }
5362
+ // Its row is gone, so W is held no longer: every lane parked on it
5363
+ // reruns with whatever W owes.
5364
+ for (const [lane, park] of [...this.parkedDetect]) {
5365
+ if (park.error instanceof DeclarationHeld && park.error.roots.includes(root))
5366
+ this.unpark(lane);
5367
+ }
5368
+ this.applyRail?.localStateChanged(placement.uuids);
5369
+ this.wakeDriveMaps(placement.uuids);
5292
5370
  }
5293
5371
  this.wakeDetect();
5372
+ if (unseen)
5373
+ await this.placeDeclarations(identity, undefined);
5374
+ const conflict = placements.find(({ placement }) => placement.kind === "conflict")?.placement;
5375
+ if (conflict?.kind === "conflict") {
5376
+ throw failedDuring("pipeline", "reference placement", refusal(conflict.reason));
5377
+ }
5294
5378
  }
5295
5379
  }
5296
5380
  /** Graph pages are immutable and content-addressed, so they cache exactly like
@@ -5417,42 +5501,25 @@ function coversTicket(cuts, ticket) {
5417
5501
  && (cut.suspicion.paths === null || (wanted.suspicion.paths !== null
5418
5502
  && wanted.suspicion.paths.every(suspectScope(cut.suspicion.paths).covers)))));
5419
5503
  }
5420
- /** Recovery facts created before Watch could prove registration: a binding
5421
- * whose portable reference is absent from the notebook, or a bound root that
5422
- * has never produced a local entity row. They pull only those exact roots
5423
- * into the next Detect pass. */
5424
- function registrationRepairGround(file, userRoot, bindingDir) {
5504
+ /** A recovery fact created before Watch could prove registration: a bound
5505
+ * root that has never produced a local entity row. It pulls only that exact
5506
+ * root into the next Detect pass. A held declaration's root never counts: its
5507
+ * ground is Register's until the placement that ends its row wakes it. */
5508
+ function emptyBoundRoots(file, bindingDir) {
5425
5509
  const bindings = materializedWorkspaceBindings(bindingDir);
5426
- if (bindings.length === 0)
5427
- return { core: false, emptyRoots: [] };
5428
- if (!existsSync(file)) {
5429
- return { core: true, emptyRoots: bindings.map(({ directory }) => directory) };
5430
- }
5431
- const core = readGroundRootAtPath(file, "detection_notebook", userRoot);
5432
- if (!core) {
5433
- return { core: true, emptyRoots: bindings.map(({ directory }) => directory) };
5434
- }
5510
+ if (bindings.length === 0 || !existsSync(file))
5511
+ return bindings.map(({ directory }) => directory);
5435
5512
  const database = groundDatabase(file);
5436
- // A held declaration's reference and ground are Register's until the
5437
- // authority accepts it; its publication outcome wakes them, never repair.
5438
5513
  const held = heldDeclarations(database, bindings.map(({ workspaceId }) => workspaceId));
5439
- const unheld = bindings.filter(({ workspaceId }) => !held.has(workspaceId));
5440
- const referenced = new Set(database.prepare(`
5441
- SELECT payload_version AS payloadVersion FROM detection_notebook
5442
- WHERE root_uuid = ? AND type = 'reference' AND status = 'active'
5443
- AND payload_version IS NOT NULL
5444
- `).all(core.uuid).map((row) => row.payloadVersion));
5445
5514
  const hasRows = database.prepare(`
5446
5515
  SELECT 1 AS present FROM entities WHERE root_uuid = ? LIMIT 1
5447
5516
  `);
5448
- return {
5449
- core: unheld.some(({ workspaceId }) => !referenced.has(workspaceId)),
5450
- emptyRoots: unheld.filter(({ workspaceId }) => !hasRows.get(workspaceId))
5451
- .map(({ directory }) => directory),
5452
- };
5517
+ return bindings.filter(({ workspaceId }) => !held.has(workspaceId) && !hasRows.get(workspaceId))
5518
+ .map(({ directory }) => directory);
5453
5519
  }
5454
5520
  /** Where ground stands on its authority's line: the place its verified
5455
5521
  * install or created publication named (never how far Receive has heard),
5522
+ * the newest graph head it keeps, which login reports instead of asking,
5456
5523
  * Send work the authority has not accepted, the first publication it
5457
5524
  * journaled and has not learned the answer to, and the graph a placement
5458
5525
  * committed with its place whose reveal Watch does not yet cover. */
@@ -5461,6 +5528,7 @@ function groundPlace(file, authorityId) {
5461
5528
  const place = database.prepare(`
5462
5529
  SELECT delivery_sequence FROM authority_snapshot_baselines WHERE authority_id = ?
5463
5530
  `).pluck().get(authorityId);
5531
+ const head = readNewestGraphHead(database, authorityId);
5464
5532
  const pending = database.prepare(`
5465
5533
  SELECT 1 FROM record_outbox WHERE status = 'pending' AND authority_id = ? LIMIT 1
5466
5534
  `).get(authorityId) !== undefined;
@@ -5470,6 +5538,7 @@ function groundPlace(file, authorityId) {
5470
5538
  `).pluck().get(authorityId);
5471
5539
  return {
5472
5540
  ...(place !== undefined ? { place } : {}),
5541
+ ...(head ? { head } : {}),
5473
5542
  ...(pending ? { pendingRecords: true } : {}),
5474
5543
  // The journaled bytes exactly as sent; Live proves them by their checksum.
5475
5544
  ...(publication ? { publication: {
@@ -5788,7 +5857,7 @@ function scopeGround(directory, tops) {
5788
5857
  });
5789
5858
  }
5790
5859
  async function reconcileGround(input) {
5791
- const { identity, userRoot, database, cacheDir, bindingDir, coreScan, onScan, onDiscovery, measuring = false, } = input;
5860
+ const { identity, userRoot, database, cacheDir, bindingDir, onScan, onDiscovery, measuring = false, } = input;
5792
5861
  // A scoped root that cannot stand alone joins the walked roots.
5793
5862
  const suspicions = input.suspicions && new Map(input.suspicions);
5794
5863
  const selectionFallbacks = new Map(input.selectionFallbacks);
@@ -5816,8 +5885,6 @@ async function reconcileGround(input) {
5816
5885
  const examinedDomainRoots = new Set([...domainBindings]
5817
5886
  .filter(([, directory]) => input.quietRoots?.has(directory)).map(([rootId]) => rootId));
5818
5887
  const heldRoots = new Set();
5819
- const boundRoots = new Map(boundRootEntries
5820
- .map(({ workspaceId, directory }) => [workspaceId, directory]));
5821
5888
  const outerBoundRoots = boundRootEntries.filter((candidate) => !boundRootEntries.some((other) => other.workspaceId !== candidate.workspaceId
5822
5889
  && pathWithin(other.directory, candidate.directory)));
5823
5890
  const registeredBoundaries = new Map(boundRootEntries
@@ -5888,9 +5955,7 @@ async function reconcileGround(input) {
5888
5955
  return [...selected];
5889
5956
  };
5890
5957
  // A declaration is published once, by Register's graph head: until the
5891
- // authority accepts it, its root is held, and so is its reference wherever
5892
- // a selection judges it.
5893
- const heldReference = referenceHold(connection, bindingDir);
5958
+ // authority accepts it, its root is held.
5894
5959
  const { held, coreUUID: observedCore, revisions } = observation.read(reader => {
5895
5960
  const held = heldDeclarations(connection, boundRootEntries.map(({ workspaceId }) => workspaceId));
5896
5961
  if (!suspicions)
@@ -5911,7 +5976,7 @@ async function reconcileGround(input) {
5911
5976
  // of the root stands on it only while no row of its O or B moved.
5912
5977
  const frame = request.revision !== null && revisions.get(directory) !== request.revision ? "revision"
5913
5978
  : directory === userRoot && request.rootUUID !== observedCore ? "core"
5914
- : await finishStepsInTurns(frameScope({ observation, directory, resourceId, request, policy, rootMarker, heldReference }));
5979
+ : await finishStepsInTurns(frameScope({ observation, directory, resourceId, request, policy, rootMarker }));
5915
5980
  if (typeof frame === "string")
5916
5981
  fallBack(directory, frame);
5917
5982
  // The frame reads what O holds, which the gate's index may not have:
@@ -5988,14 +6053,7 @@ async function reconcileGround(input) {
5988
6053
  const observationFor = (root) => suspicions?.get(root);
5989
6054
  const coreUUID = existingCore?.uuid || observedCore || randomUUID();
5990
6055
  const existingCoreRows = existingByRoot.get(coreUUID) ?? [];
5991
- const existingReferenceIds = new Set();
5992
- await eachInTurns(existingCoreRows, row => {
5993
- if (row.type === "reference" && row.payloadVersion)
5994
- existingReferenceIds.add(row.payloadVersion);
5995
- });
5996
6056
  const coreSuspicion = suspicionFor(userRoot);
5997
- const missingPortableReference = [...boundRoots.keys()]
5998
- .some((workspaceId) => !existingReferenceIds.has(workspaceId));
5999
6057
  const acceptedMaterializedRows = [];
6000
6058
  const materializedRemovals = new Set();
6001
6059
  const tops = new Set();
@@ -6197,13 +6255,12 @@ async function reconcileGround(input) {
6197
6255
  };
6198
6256
  // A Watch pass names exactly the roots it observed. A root outside that
6199
6257
  // observation has nothing to prove and is not scanned, planned, or
6200
- // inspected; its rows stay as they are. Only two facts can still pull an
6201
- // unobserved root in: core ground missing a portable reference for a
6202
- // binding, and a bound root that has never produced a row.
6203
- // Register owns a declaration's first publication: its root, that root's
6204
- // reference in core and the folders on the reference's way travel in one
6205
- // graph head. Detect holds them all until the authority accepts it.
6206
- if (observedRoot(userRoot) || (missingPortableReference && coreScan !== false)) {
6258
+ // inspected; its rows stay as they are. Only one fact can still pull an
6259
+ // unobserved root in: a bound root that has never produced a row. Core
6260
+ // ground gains a declaration's reference and the folders on its way only
6261
+ // when the authority has accepted it, with their rows
6262
+ // (reference-placement.ts), so core has nothing of it to discover.
6263
+ if (observedRoot(userRoot)) {
6207
6264
  await scan({
6208
6265
  identity,
6209
6266
  resourceId,
@@ -6215,9 +6272,7 @@ async function reconcileGround(input) {
6215
6272
  cacheDir,
6216
6273
  bindingDir,
6217
6274
  stamp: await stampOf(resolve(userRoot)),
6218
- suspects: missingPortableReference && coreSuspicion !== null
6219
- ? [...new Set([...coreSuspicion, FILES_FOLDER])]
6220
- : coreSuspicion,
6275
+ suspects: coreSuspicion,
6221
6276
  existingRows: existingCoreRows,
6222
6277
  sharingRows: notebookByRoot.get(coreUUID) ?? [],
6223
6278
  suspicion: observationFor(userRoot),
@@ -6492,124 +6547,6 @@ async function reconcileGround(input) {
6492
6547
  };
6493
6548
  }
6494
6549
  const deleteRootRows = (file, resourceId, rootUUID) => save(file, "install.clearRoot", { resourceId, rootUUID });
6495
- /** Install the accepted portable references this machine has never
6496
- * materialized. Paths and bindings are local; UUIDs, parents, names, and
6497
- * versions are the same cloud entities on every machine. A reference this
6498
- * machine already knows is on its rails: Apply owns accepted transitions and
6499
- * Detect owns local ones. A new reference whose placement carries newer local
6500
- * work, or whose address is occupied by unsettled local ground, is likewise
6501
- * left alone. Add never writes an older accepted state over local ground or
6502
- * its notebook; every reference it leaves is reported as still syncing. Under
6503
- * a home this computer's drive serves, a new reference whose parent this
6504
- * computer does not show stands in folders the drive only lists: it is
6505
- * reported as listed, and the drive places it when something opens it. */
6506
- async function installCloudWorkspaceReferences(input) {
6507
- const { identity, userRoot, database, bindingDir, resourceId, workspace, references, deliveryWatermark, } = input;
6508
- // A reference rendered after this stamp stays racy until it is next read.
6509
- // It precedes every read below, so nothing it waits on can move them.
6510
- const { boundary: clock } = await stampContentClock(database, userRoot);
6511
- const involved = new Set(references.flatMap(({ uuid, parentUUID }) => parentUUID ? [uuid, parentUUID] : [uuid]));
6512
- const observed = new Map(readGroundRowsByUUIDs(database, "entities", involved).map((row) => [row.uuid, row]));
6513
- const noted = new Map(readGroundRowsByUUIDs(database, "detection_notebook", involved).map((row) => [row.uuid, row]));
6514
- const localWork = entitiesWithLocalWorkAfter(database, resourceId, involved, deliveryWatermark);
6515
- const ground = groundDatabase(database);
6516
- const onDemand = coreRootsAt(ground, userRoot).some((root) => isOnDemandRoot(ground, root));
6517
- const renders = (path, workspaceId) => {
6518
- try {
6519
- return lstatSync(path).isSymbolicLink()
6520
- && readlinkSync(path) === relative(dirname(path), join(bindingDir, workspaceId));
6521
- }
6522
- catch {
6523
- return false;
6524
- }
6525
- };
6526
- const installed = [];
6527
- const syncingReferences = [];
6528
- const listedReferences = [];
6529
- const rendered = [];
6530
- try {
6531
- for (const reference of references) {
6532
- if (reference.type !== "reference"
6533
- || reference.status !== "active"
6534
- || !reference.payloadVersion
6535
- || reference.parentUUID === null) {
6536
- throw new Error("cloud registry has an invalid durable reference");
6537
- }
6538
- const known = [observed.get(reference.uuid), noted.get(reference.uuid)];
6539
- if (known.some(Boolean)) {
6540
- const current = known.every((row) => row && sameRecords([portableRecord(row)], [reference]))
6541
- && renders(known[0].absolutePath, reference.payloadVersion);
6542
- if (current)
6543
- installed.push(reference);
6544
- else
6545
- syncingReferences.push(reference.uuid);
6546
- continue;
6547
- }
6548
- const parent = observed.get(reference.parentUUID);
6549
- if (!parent && onDemand && !localWork.has(reference.uuid) && !localWork.has(reference.parentUUID)) {
6550
- listedReferences.push(reference.uuid);
6551
- continue;
6552
- }
6553
- const placeable = parent && [parent, noted.get(reference.parentUUID)].every((row) => row
6554
- && row.status === "active" && (row.type === "workspace" || row.type === "folder"));
6555
- if (!placeable || localWork.has(reference.uuid) || localWork.has(reference.parentUUID)) {
6556
- syncingReferences.push(reference.uuid);
6557
- continue;
6558
- }
6559
- const target = join(parent.absolutePath, reference.name);
6560
- const binding = join(bindingDir, reference.payloadVersion);
6561
- const created = !pathExists(target);
6562
- if (created) {
6563
- if (reference.payloadVersion === workspace.uuid && !pathExists(binding)) {
6564
- throw new Error(`workspace ${workspace.uuid} has no machine binding`);
6565
- }
6566
- symlinkSync(relative(dirname(target), binding), target);
6567
- }
6568
- else if (!renders(target, reference.payloadVersion)) {
6569
- syncingReferences.push(reference.uuid);
6570
- continue;
6571
- }
6572
- const stats = lstatSync(target, { bigint: true });
6573
- rendered.push({
6574
- created,
6575
- parent,
6576
- row: {
6577
- record: reference,
6578
- relativePath: slashPath(relative(userRoot, target)),
6579
- absolutePath: target,
6580
- sighting: sightingUnder(clock, stats),
6581
- ...sourceFingerprint(stats),
6582
- },
6583
- });
6584
- installed.push(reference);
6585
- }
6586
- if (rendered.length > 0)
6587
- await persistInstalledReferences(database, identity, resourceId, rendered);
6588
- }
6589
- catch (error) {
6590
- for (const entry of rendered) {
6591
- if (entry.created && pathExists(entry.row.absolutePath)) {
6592
- rmSync(entry.row.absolutePath, { force: true });
6593
- }
6594
- }
6595
- throw error;
6596
- }
6597
- return { references: installed, syncingReferences, listedReferences };
6598
- }
6599
- /** Entities with local work on their own channel after the watermark: still
6600
- * pending, or accepted after that prefix. */
6601
- function entitiesWithLocalWorkAfter(file, authorityId, uuids, deliveryWatermark) {
6602
- const database = groundDatabase(file);
6603
- return new Set([...uuids].filter((uuid) => hasLocalWorkAfter(database, authorityId, uuid, deliveryWatermark)));
6604
- }
6605
- /** New references and their parents' derived membership
6606
- * (`install.references`). */
6607
- async function persistInstalledReferences(file, identity, resourceId, rendered) {
6608
- await save(file, "install.references", {
6609
- owner: groundOwner(identity),
6610
- rows: rendered.map(({ parent, row }) => capturedGroundRow(resourceId, parent.rootUUID, row)),
6611
- });
6612
- }
6613
6550
  /** Files Add's own part: its destination's checks, its intent, the shared
6614
6551
  * install, then the references it places in the home. */
6615
6552
  async function installCloudWorkspace(input) {
@@ -6623,7 +6560,7 @@ async function installCloudWorkspace(input) {
6623
6560
  throw new Error(`local workspace ${workspace.uuid} has unresolved placement`);
6624
6561
  }
6625
6562
  ensureWorkspaceBinding({ bindingDir, workspaceId: workspace.uuid, absolutePath: root.absolutePath });
6626
- const installedReferences = await installCloudWorkspaceReferences({
6563
+ const installedReferences = await placeAcceptedReferences({
6627
6564
  identity, userRoot, database, bindingDir, resourceId, workspace, references, deliveryWatermark,
6628
6565
  });
6629
6566
  return {
@@ -6680,7 +6617,7 @@ async function installCloudWorkspace(input) {
6680
6617
  }
6681
6618
  const installed = await installWorkspaceIntent({ ...input, intent: intent });
6682
6619
  const selection = workspaceAddSelection(intent);
6683
- const installedReferences = await installCloudWorkspaceReferences({
6620
+ const installedReferences = await placeAcceptedReferences({
6684
6621
  identity,
6685
6622
  userRoot,
6686
6623
  database,