@amalgm/shell 0.1.164-preview.36814066164 → 0.1.164-preview.36824980905

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.
@@ -58,6 +58,19 @@ function sealContentEnvelope(resourceId, data) {
58
58
  ]);
59
59
  }
60
60
 
61
+ /** A refusal the authority types: the code, status and retry posture the
62
+ * gateway answers on the wire. Any other failure is the authority's own. */
63
+ class AuthorityRefusal extends Error {
64
+ constructor(code, message, status, retryable) {
65
+ super(message);
66
+ this.code = code;
67
+ this.status = status;
68
+ this.retryable = retryable;
69
+ }
70
+ }
71
+
72
+ const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
73
+
61
74
  /** Shared test authority for the exact private-resource/content/mutation
62
75
  * frames used by the production host. It also serves the direct content
63
76
  * plane: refs answer where each sealed envelope lives — a byte range of an
@@ -155,7 +168,34 @@ export function createPrivateWireAuthority({
155
168
  response.end();
156
169
  });
157
170
  const sockets = new WebSocketServer({ server });
158
- let current = null;
171
+ // Every private resource, by its id. The id is derived from the registry
172
+ // contract, so a runtime on another contract finds nothing until it ensures
173
+ // its own resource, exactly as the gateway's lookup answers it.
174
+ const resources = new Map();
175
+ let latestResourceId = null;
176
+ const latestResource = () => resources.get(latestResourceId) ?? null;
177
+ // Each authority's delivery prefix: positions are assigned per authority,
178
+ // behind that authority's own commit gate.
179
+ const deliveryPrefixes = new Map();
180
+ const deliveryPrefix = (authorityId) => deliveryPrefixes.get(authorityId) ?? 0;
181
+ // The gateway law: every frame is answered. A failure the authority did not
182
+ // type is its own fault, 503 and retryable, and is never thrown into the
183
+ // process hosting it. This ledger keeps every refusal for diagnosis.
184
+ const refusals = [];
185
+ const refuse = (socket, frame, cause) => {
186
+ const typed = cause instanceof AuthorityRefusal;
187
+ const failure = {
188
+ code: typed ? cause.code
189
+ : String(frame?.type).startsWith("entity.record.") ? "entity_record_realtime_internal_error"
190
+ : "shared_realtime_internal_error",
191
+ message: cause instanceof Error ? cause.message : String(cause),
192
+ status: typed ? cause.status : 503,
193
+ retryable: typed ? cause.retryable : true,
194
+ };
195
+ refusals.push({ type: frame?.type ?? null, ...failure });
196
+ if (socket.readyState !== WebSocket.OPEN) return;
197
+ socket.send(JSON.stringify({ type: "shared.error", request_id: frame?.request_id, ...failure }));
198
+ };
159
199
  const content = new Map();
160
200
  // The pack law: each cargo segment is durable as ONE immutable byte string
161
201
  // (chunk envelopes in artifact order, manifest envelopes at the tail) and
@@ -164,6 +204,17 @@ export function createPrivateWireAuthority({
164
204
  const packLocations = new Map();
165
205
  let contentPutsInFlight = 0;
166
206
  let maxContentPutsInFlight = 0;
207
+ /** One content put, in flight from its admission until it is answered:
208
+ * stored, or refused on the wire. */
209
+ const storeContent = (socket, frame, store) => {
210
+ contentPutsInFlight += 1;
211
+ maxContentPutsInFlight = Math.max(maxContentPutsInFlight, contentPutsInFlight);
212
+ void (contentPutGate ? contentPutGate() : Promise.resolve())
213
+ .then(() => (contentPutDelayMs > 0 ? delay(contentPutDelayMs) : undefined))
214
+ .then(store)
215
+ .catch((cause) => refuse(socket, frame, cause))
216
+ .finally(() => { contentPutsInFlight -= 1; });
217
+ };
167
218
  let contentPutAttempts = 0;
168
219
  // Every put attempt's content hash, and the hashes the committed graph
169
220
  // claims as pages. Pages ride the same content plane as file cargo, so
@@ -232,7 +283,6 @@ export function createPrivateWireAuthority({
232
283
  // the refusal code.
233
284
  const graphAnswers = [];
234
285
  const committedMutationAcks = new Map();
235
- let deliverySequence = 0;
236
286
  const entityRecords = [];
237
287
  const entityHeads = new Map();
238
288
  const entityDedup = new Map();
@@ -347,12 +397,20 @@ export function createPrivateWireAuthority({
347
397
  grantWatchers.delete(socket);
348
398
  });
349
399
  const receive = (data, isBinary) => {
350
- const frame = isBinary
351
- ? (() => {
352
- const decoded = decodeBinaryFrame(data);
353
- return { ...decoded.frame, data_bin: decoded.bytes };
354
- })()
355
- : JSON.parse(data.toString("utf8"));
400
+ let frame = null;
401
+ try {
402
+ frame = isBinary
403
+ ? (() => {
404
+ const decoded = decodeBinaryFrame(data);
405
+ return { ...decoded.frame, data_bin: decoded.bytes };
406
+ })()
407
+ : JSON.parse(data.toString("utf8"));
408
+ dispatch(frame, data, isBinary);
409
+ } catch (cause) {
410
+ refuse(socket, frame, cause);
411
+ }
412
+ };
413
+ const dispatch = (frame, data, isBinary) => {
356
414
  if (holdGraphSubmits && frame.type === "shared.mutation.submit"
357
415
  && frame.envelope?.operationKind === GRAPH_HEAD_OPERATION_KIND) {
358
416
  const { mutationId, deviceId, baseVersion, deliveryWatermark } = frame.envelope;
@@ -380,26 +438,31 @@ export function createPrivateWireAuthority({
380
438
  if (frame.type === "hello") {
381
439
  socket.send(JSON.stringify({ type: "hello_ack", protocol_version: protocolVersion }));
382
440
  } else if (frame.type === "private.resource.lookup") {
383
- socket.send(JSON.stringify(current ? ready(frame.request_id, current, true) : {
441
+ const resource = resources.get(frame.resource_id);
442
+ socket.send(JSON.stringify(resource ? ready(frame.request_id, resource, true) : {
384
443
  type: "private.resource.missing",
385
444
  request_id: frame.request_id,
386
445
  resource_id: frame.resource_id,
387
446
  contract: frame.contract,
388
447
  }));
389
448
  } else if (frame.type === "private.resource.ensure") {
390
- const duplicate = current !== null;
391
- if (!current) current = {
392
- resourceId: frame.resource_id,
393
- checksum: frame.snapshot_checksum,
394
- snapshotB64: frame.snapshot_b64,
395
- rootRecords: recordsByRoot(JSON.parse(
396
- Buffer.from(frame.snapshot_b64, "base64").toString("utf8"),
397
- ).records),
398
- version: 0,
399
- deliveryWatermark: 0,
400
- authorityEpoch: 1,
401
- };
402
- socket.send(JSON.stringify(ready(frame.request_id, current, duplicate)));
449
+ const duplicate = resources.has(frame.resource_id);
450
+ if (!duplicate) {
451
+ resources.set(frame.resource_id, {
452
+ resourceId: frame.resource_id,
453
+ contract: frame.contract,
454
+ checksum: frame.snapshot_checksum,
455
+ snapshotB64: frame.snapshot_b64,
456
+ rootRecords: recordsByRoot(JSON.parse(
457
+ Buffer.from(frame.snapshot_b64, "base64").toString("utf8"),
458
+ ).records),
459
+ version: 0,
460
+ deliveryWatermark: 0,
461
+ authorityEpoch: 1,
462
+ });
463
+ latestResourceId = frame.resource_id;
464
+ }
465
+ socket.send(JSON.stringify(ready(frame.request_id, resources.get(frame.resource_id), duplicate)));
403
466
  } else if (frame.type === "private.entity-content.inventory") {
404
467
  contentInventories.push({ ...frame });
405
468
  const manifestKey = contentKey({
@@ -438,9 +501,7 @@ export function createPrivateWireAuthority({
438
501
  }));
439
502
  return;
440
503
  }
441
- contentPutsInFlight += 1;
442
- maxContentPutsInFlight = Math.max(maxContentPutsInFlight, contentPutsInFlight);
443
- const store = () => {
504
+ storeContent(socket, frame, () => {
444
505
  const data = Buffer.from(frame.data_bin);
445
506
  assert.equal(sha256(data), frame.sha256, "a manifest seal proves its own digest");
446
507
  const manifest = JSON.parse(data.toString("utf8"));
@@ -451,16 +512,8 @@ export function createPrivateWireAuthority({
451
512
  sha256: chunk.sha256,
452
513
  }));
453
514
  if (absent) {
454
- socket.send(JSON.stringify({
455
- type: "shared.error",
456
- request_id: frame.request_id,
457
- code: "entity_content_incomplete",
458
- message: `manifest names absent block ${absent.sha256}`,
459
- status: 409,
460
- retryable: true,
461
- }));
462
- contentPutsInFlight -= 1;
463
- return;
515
+ throw new AuthorityRefusal("entity_content_incomplete",
516
+ `manifest names absent block ${absent.sha256}`, 409, true);
464
517
  }
465
518
  content.set(contentKey(frame), {
466
519
  sha256: frame.sha256,
@@ -476,12 +529,6 @@ export function createPrivateWireAuthority({
476
529
  store_ms: 3,
477
530
  seal_ms: 4,
478
531
  }));
479
- contentPutsInFlight -= 1;
480
- };
481
- const admitted = contentPutGate ? contentPutGate() : Promise.resolve();
482
- void admitted.then(() => {
483
- if (contentPutDelayMs > 0) setTimeout(store, contentPutDelayMs);
484
- else store();
485
532
  });
486
533
  } else if (frame.type === "private.entity-content.put-blocks") {
487
534
  // Provisional blocks addressed by their own digests: durable at
@@ -504,10 +551,8 @@ export function createPrivateWireAuthority({
504
551
  }));
505
552
  return;
506
553
  }
507
- contentPutsInFlight += 1;
508
- maxContentPutsInFlight = Math.max(maxContentPutsInFlight, contentPutsInFlight);
509
554
  const decodedBatch = decodeWireBatch(frame);
510
- const store = () => {
555
+ storeContent(socket, frame, () => {
511
556
  let offset = 0;
512
557
  for (const block of frame.blocks) {
513
558
  const bytes = Buffer.from(decodedBatch.subarray(offset, offset + block.bytes));
@@ -528,12 +573,6 @@ export function createPrivateWireAuthority({
528
573
  verify_ms: 2,
529
574
  store_ms: 3,
530
575
  }));
531
- contentPutsInFlight -= 1;
532
- };
533
- const admitted = contentPutGate ? contentPutGate() : Promise.resolve();
534
- void admitted.then(() => {
535
- if (contentPutDelayMs > 0) setTimeout(store, contentPutDelayMs);
536
- else store();
537
576
  });
538
577
  } else if (frame.type === "private.entity-content.put-cargo") {
539
578
  assert.equal(isBinary, true, "cargo segments use the binary WebSocket rail");
@@ -560,10 +599,8 @@ export function createPrivateWireAuthority({
560
599
  }));
561
600
  return;
562
601
  }
563
- contentPutsInFlight += 1;
564
- maxContentPutsInFlight = Math.max(maxContentPutsInFlight, contentPutsInFlight);
565
602
  const decodedCargo = decodeWireBatch(frame);
566
- const store = () => {
603
+ storeContent(socket, frame, () => {
567
604
  const packEntries = [];
568
605
  let offset = 0;
569
606
  for (const artifact of frame.artifacts) {
@@ -623,12 +660,6 @@ export function createPrivateWireAuthority({
623
660
  store_ms: 3,
624
661
  seal_ms: 4,
625
662
  }));
626
- contentPutsInFlight -= 1;
627
- };
628
- const admitted = contentPutGate ? contentPutGate() : Promise.resolve();
629
- void admitted.then(() => {
630
- if (contentPutDelayMs > 0) setTimeout(store, contentPutDelayMs);
631
- else store();
632
663
  });
633
664
  } else if (frame.type === "private.entity-content.sealed") {
634
665
  // Seal evidence under the current contract: a manifest in this
@@ -708,7 +739,8 @@ export function createPrivateWireAuthority({
708
739
  }));
709
740
  } else if (frame.type === "shared.mutation.submit") {
710
741
  const answer = (value) => graphAnswers.push({ mutationId: frame.envelope?.mutationId,
711
- deviceId: frame.envelope?.deviceId, answer: value, version: current?.version ?? null, at: epochNow() });
742
+ deviceId: frame.envelope?.deviceId, answer: value,
743
+ version: resources.get(frame.envelope?.resourceId)?.version ?? null, at: epochNow() });
712
744
  if (rejectMutationSubmits) {
713
745
  answer("shared_realtime_internal_error");
714
746
  socket.send(JSON.stringify({
@@ -754,12 +786,19 @@ export function createPrivateWireAuthority({
754
786
  }));
755
787
  return;
756
788
  }
789
+ const current = resources.get(envelope.resourceId);
790
+ if (!current) {
791
+ answer("shared_resource_not_found");
792
+ throw new AuthorityRefusal("shared_resource_not_found",
793
+ "no private resource exists at that id", 404, false);
794
+ }
757
795
  assert.equal(envelope.authorityEpoch, current.authorityEpoch);
758
796
  // The production commit refuses a publication whose delivery prefix
759
797
  // or graph head moved on, in that order; the gateway maps either
760
798
  // refusal to its leading token, 400 and not retryable. The head
761
799
  // comparison is the proposed strict CAS.
762
- const moved = envelope.deliveryWatermark !== deliverySequence ? "entity_delivery_watermark_changed"
800
+ const moved = envelope.deliveryWatermark !== deliveryPrefix(current.resourceId)
801
+ ? "entity_delivery_watermark_changed"
763
802
  : envelope.baseVersion !== current.version ? "entity_graph_head_changed" : null;
764
803
  if (moved) {
765
804
  answer(moved);
@@ -816,7 +855,7 @@ export function createPrivateWireAuthority({
816
855
  } else {
817
856
  assert.fail(`unsupported fake entity graph operation ${envelope.operationKind}`);
818
857
  }
819
- current = {
858
+ const next = {
820
859
  ...current,
821
860
  snapshotB64: snapshotBytes.toString("base64"),
822
861
  checksum: sha256(snapshotBytes),
@@ -824,15 +863,16 @@ export function createPrivateWireAuthority({
824
863
  version: current.version + 1,
825
864
  deliveryWatermark: envelope.deliveryWatermark,
826
865
  };
866
+ resources.set(next.resourceId, next);
827
867
  const ack = {
828
868
  type: "shared.mutation.ack",
829
869
  request_id: frame.request_id,
830
- resource_id: current.resourceId,
870
+ resource_id: next.resourceId,
831
871
  mutation_id: envelope.mutationId,
832
- version: current.version,
833
- authority_epoch: current.authorityEpoch,
872
+ version: next.version,
873
+ authority_epoch: next.authorityEpoch,
834
874
  committed_at: new Date().toISOString(),
835
- delivery_watermark: current.deliveryWatermark,
875
+ delivery_watermark: next.deliveryWatermark,
836
876
  duplicate: false,
837
877
  };
838
878
  committedMutationAcks.set(envelope.mutationId, ack);
@@ -857,8 +897,13 @@ export function createPrivateWireAuthority({
857
897
  status: retryEntityRecordSubmits ? 503 : 404, retryable: retryEntityRecordSubmits }));
858
898
  return;
859
899
  }
900
+ // A record on a superseded contract fails this decode and is refused,
901
+ // exactly as the production authority's own decode refuses it.
860
902
  const submitted = decodeLocalEntityRecord(frame.record_json);
861
- assert.equal(submitted.authorityId, current.resourceId);
903
+ if (!resources.has(submitted.authorityId)) {
904
+ throw new AuthorityRefusal("entity_record_authority_not_found",
905
+ "no entity authority exists at that id", 404, false);
906
+ }
862
907
  if (frame.cargo !== undefined) {
863
908
  inlineCargoSubmits += 1;
864
909
  const cargo = decodeInlineCargo(
@@ -919,7 +964,8 @@ export function createPrivateWireAuthority({
919
964
  acceptedAt: Date.now(),
920
965
  });
921
966
  if (decision.kind === "append") {
922
- deliverySequence += 1;
967
+ const deliverySequence = deliveryPrefix(submitted.authorityId) + 1;
968
+ deliveryPrefixes.set(submitted.authorityId, deliverySequence);
923
969
  entityHeads.set(submitted.entityId, decision.record.globalSequence);
924
970
  entityDedup.set(key, decision.record);
925
971
  entityRecords.push({ delivery_sequence: deliverySequence, record: decision.record });
@@ -1035,7 +1081,12 @@ export function createPrivateWireAuthority({
1035
1081
  return {
1036
1082
  server,
1037
1083
  sockets,
1038
- get current() { return current; },
1084
+ /** The most recently ensured resource: the one a single-contract test
1085
+ * reads. Every resource remains in `resources`. */
1086
+ get current() { return latestResource(); },
1087
+ get resources() { return new Map(resources); },
1088
+ /** Every frame the authority refused, with the answer it sent. */
1089
+ get refusals() { return refusals.map((row) => ({ ...row })); },
1039
1090
  /** The live access tables, in the gateway's own wire row shapes. */
1040
1091
  get entityGrants() { return [...entityGrants.values()]; },
1041
1092
  get accessRequests() { return [...accessRequests.values()]; },
@@ -1050,6 +1101,7 @@ export function createPrivateWireAuthority({
1050
1101
  return [...content.values()].reduce((total, value) => total + value.data.length, 0);
1051
1102
  },
1052
1103
  contentArtifact(contentHash) {
1104
+ const current = latestResource();
1053
1105
  if (!current) return null;
1054
1106
  const manifest = findContent(content, {
1055
1107
  resource_id: current.resourceId,
@@ -1141,6 +1193,7 @@ export function createPrivateWireAuthority({
1141
1193
  * and inline Send cargo left behind. Small artifacts are single-chunk
1142
1194
  * by construction (one chunk holds anything up to the chunk cap). */
1143
1195
  adoptStandaloneArtifact(bytes) {
1196
+ const current = latestResource();
1144
1197
  if (!current) throw new Error("no resource is registered yet");
1145
1198
  const data = Buffer.from(bytes);
1146
1199
  const contentHash = sha256(data);
@@ -1165,6 +1218,7 @@ export function createPrivateWireAuthority({
1165
1218
  /** Remove only physical location rows for one sealed artifact. Its
1166
1219
  * immutable manifest and blocks remain readable as standalone objects. */
1167
1220
  makeArtifactStandalone(contentHash) {
1221
+ const current = latestResource();
1168
1222
  if (!current) throw new Error("no resource is registered yet");
1169
1223
  const manifest = findContent(content, {
1170
1224
  resource_id: current.resourceId,
@@ -1182,6 +1236,7 @@ export function createPrivateWireAuthority({
1182
1236
  * This models a legal standalone-to-pack placement convergence while a
1183
1237
  * reader still holds refs from the earlier physical plan. */
1184
1238
  moveArtifactToPack(contentHash) {
1239
+ const current = latestResource();
1185
1240
  if (!current) throw new Error("no resource is registered yet");
1186
1241
  const manifest = findContent(content, {
1187
1242
  resource_id: current.resourceId,
@@ -1278,6 +1333,7 @@ export function createPrivateWireAuthority({
1278
1333
  * after assembling them — the honest replacement for reading records out
1279
1334
  * of an operation that no longer carries any. */
1280
1335
  get graphRecords() {
1336
+ const current = latestResource();
1281
1337
  return current ? [...current.rootRecords.values()].flat() : [];
1282
1338
  },
1283
1339
  };
@@ -1294,7 +1350,7 @@ function ready(requestId, current, duplicate) {
1294
1350
  snapshot_checksum: current.checksum,
1295
1351
  delivery_watermark: current.deliveryWatermark,
1296
1352
  snapshot_b64: current.snapshotB64,
1297
- contract: "amalgm-entity-registry@3",
1353
+ contract: current.contract,
1298
1354
  schema_version: 1,
1299
1355
  duplicate,
1300
1356
  };
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "@amalgm/shell",
3
- "version": "0.1.164-preview.36814066164",
3
+ "version": "0.1.164-preview.36824980905",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "@amalgm/shell",
9
- "version": "0.1.164-preview.36814066164",
9
+ "version": "0.1.164-preview.36824980905",
10
10
  "license": "UNLICENSED",
11
11
  "dependencies": {
12
12
  "@amalgm/agents": "0.2.3-preview.35795493380",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amalgm/shell",
3
- "version": "0.1.164-preview.36814066164",
3
+ "version": "0.1.164-preview.36824980905",
4
4
  "description": "The Amalgm runtime host assembled from the published @amalgm SDK capabilities.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -172,11 +172,11 @@
172
172
  }
173
173
  ]
174
174
  },
175
- "gitHead": "e8e8d3f21416ee5c338423161062b4754049ddfd",
175
+ "gitHead": "969ef46a2e4d39faa924e5c57e38821f95e9288a",
176
176
  "amalgmSource": {
177
177
  "repository": "amalgm-inc/amalgm-shell",
178
178
  "branch": "preview",
179
- "commit": "e8e8d3f21416ee5c338423161062b4754049ddfd",
180
- "occurrence": "36814066164"
179
+ "commit": "969ef46a2e4d39faa924e5c57e38821f95e9288a",
180
+ "occurrence": "36824980905"
181
181
  }
182
182
  }