refactor: le paquet s'appelle polyfill, « SDK » désigne celui de NextGraph

Le nom @ng-eventually/sdk entrait en collision avec le SDK de NextGraph, dont ce paquet est justement un polyfill. Impossible d'écrire « le SDK » sans lever l'ambiguïté à chaque phrase — et le contrat publié, lu par une application, était le pire endroit pour laisser traîner ça. packages/sdk → packages/polyfill, @ng-eventually/sdk → @ng-eventually/polyfill, contract_sdk-surface → contract_polyfill-surface, e2e/sdk-entry.ts → e2e/polyfill-entry.ts, docs/sdk-reference.md → docs/polyfill-reference.md. Les occurrences de « SDK » qui désignent celui de NextGraph restent intactes, y compris les chemins dans nextgraph-rs (sdk/js/orm, sdk/js/web). Le tri s'est fait occurrence par occurrence, pas par substitution. Le contrat énonce désormais son identité en une phrase : « This package is a polyfill of NextGraph's SDK. »
2026-08-10 17:14:25 +02:00
parent 49b046268e
commit 737729c9ce
88 changed files with 122 additions and 106 deletions
@@ -0,0 +1,51 @@
+/**
+ * The reserved-namespace predicate, in isolation.
+ *
+ * It is one `startsWith`, but it is the seam that keeps the polyfill's emulated
+ * branches out of the consumer's data (see `machinery.ts`), so its edges are worth
+ * pinning: get it wrong in one direction and machinery leaks into domain properties;
+ * wrong in the other and real data silently disappears from reads.
+ */
+import { test, expect } from "bun:test";
+import { MACHINERY_NS, isMachinerySubject } from "../src/emulated-verifier/machinery";
+
+test("the emulated branch subjects are all machinery", () => {
+  // The four compartments store-registry emulates, verbatim.
+  for (const s of [
+    "urn:ng-eventually:shim:index",
+    "urn:ng-eventually:shim:storeBranch",
+    "urn:ng-eventually:shim:userBranch",
+    "urn:ng-eventually:shim:headerBranch",
+  ]) {
+    expect(isMachinerySubject(s)).toBe(true);
+  }
+});
+
+test("inbox deposits are machinery too — a second prefix under the same namespace", () => {
+  expect(isMachinerySubject("urn:ng-eventually:inbox:deposit:1700:abc")).toBe(true);
+});
+
+test("consumer subjects are not machinery — including a NURI, which is what entities use", () => {
+  expect(isMachinerySubject("did:ng:o:doc1")).toBe(false);
+  expect(isMachinerySubject("urn:e2e:secret")).toBe(false);
+  expect(isMachinerySubject("http://example.org/thing")).toBe(false);
+});
+
+test("a look-alike prefix is NOT machinery — the boundary is exact, not fuzzy", () => {
+  // Anything that merely resembles the namespace must fall on the data side, or a
+  // consumer's own vocabulary could vanish from its reads.
+  expect(isMachinerySubject("urn:ng-eventuallyX:thing")).toBe(false);
+  expect(isMachinerySubject("urn:ng-event:thing")).toBe(false);
+  expect(isMachinerySubject("x-urn:ng-eventually:shim:index")).toBe(false);
+});
+
+test("an absent subject is not machinery — read paths hand bindings straight in", () => {
+  expect(isMachinerySubject(undefined)).toBe(false);
+  expect(isMachinerySubject("")).toBe(false);
+});
+
+test("the namespace is the prefix both writers actually use", () => {
+  // Guards against the constant drifting away from store-registry/inbox.
+  expect("urn:ng-eventually:shim".startsWith(MACHINERY_NS)).toBe(true);
+  expect("urn:ng-eventually:inbox".startsWith(MACHINERY_NS)).toBe(true);
+});