@engramx/client 0.16.0-rc.13 → 0.16.0-rc.14

package/dist/recordChain.js

@@ -0,0 +1,145 @@
+// The chained record's hash contract, and the walk from one entry to a certified head.
+//
+// ⟨ADDED 2026-10-15, the owner's ruling 6B of 2026-10-14⟩ WHY THIS IS PUBLIC. Every engram, the
+// registry and the market keep a chained record: each entry's hash commits to the head before it,
+// and the canister certifies only the newest head. A stranger who wants to check ONE entry against
+// the subnet's signature has to walk from that entry to a certified head. Under the rule this file
+// mirrors, each entry is HASHED FIRST, THEN CHAINED:
+//
+//     body      = id|timestampNs|caller|role|operation|details|success      (success = "1" | "0")
+//     digest    = SHA-256(body)
+//     entryHash = SHA-256(previous head ‖ digest)                           (genesis head = empty)
+//
+// so the walk passes through every other entry knowing only its 32-byte digest — which the record
+// read (`listAuditEntries`) serves to anyone as a hash-only row — and never its body. Entries a
+// chain recorded before its upgrade to this rule were hashed SHA-256(previous head ‖ body); the read
+// says where each chain switched (`hashFirstFrom`), and a walk through an older entry needs its body.
+//
+// The Motoko half is src/shared/AuditLog.mo (`bodyOf`, `digestOf`, `link`, `legacyLink`). The two
+// are locked by the same known-answer vector, computed outside both (Python's hashlib): this
+// package's test/record-chain.test.ts and the repo's test/audit-log-hash-first.test.mo assert the
+// same constants. A diff in either is a contract change, never a routine test update.
+//
+// BROWSER-SAFE: hashing is WebCrypto (`crypto.subtle`), present in every browser and in Node ≥ 19;
+// nothing here imports a Node module (test/browser-safe-subpaths.test.ts walks `./verify`'s graph).
+const utf8 = new TextEncoder();
+const principalText = (p) => typeof p === 'string' ? p : p.toText();
+const roleText = (r) => typeof r === 'string' ? r : (Object.keys(r)[0] ?? '');
+/** The bytes an entry's hash covers — byte-for-byte `AuditLog.bodyOf`. */
+export function recordEntryBody(e) {
+    return utf8.encode([
+        BigInt(e.id).toString(),
+        BigInt(e.timestampNs).toString(),
+        principalText(e.caller),
+        roleText(e.callerRole),
+        e.operation,
+        e.details,
+        e.success ? '1' : '0',
+    ].join('|'));
+}
+function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+export async function sha256(bytes) {
+    return new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes));
+}
+/** SHA-256 of an entry's body — the digest a hash-only row carries. */
+export const recordDigest = (body) => sha256(body);
+/** The hash-first rule: SHA-256(prev ‖ digest). */
+export const recordLink = (prev, digest) => sha256(concat(prev, digest));
+/** The rule before a chain's switch point: SHA-256(prev ‖ body). */
+export const legacyRecordLink = (prev, body) => sha256(concat(prev, body));
+/**
+ * One entry's hash from its fields and the head before it, under the rule its id falls on.
+ * `hashFirstFrom` is the chain's switch point as its record read serves it.
+ */
+export async function recordEntryHash(e, prev, hashFirstFrom) {
+    const body = recordEntryBody(e);
+    return BigInt(e.id) >= hashFirstFrom
+        ? recordLink(prev, await recordDigest(body))
+        : legacyRecordLink(prev, body);
+}
+/** A full entry turned into the row a stranger would be served — for walking a page that mixes the two. */
+export async function sealedRowOf(e) {
+    return {
+        id: BigInt(e.id),
+        digest: await recordDigest(recordEntryBody(e)),
+        entryHash: Uint8Array.from(e.entryHash),
+    };
+}
+export const sameBytes = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+export const toHexString = (b) => Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+/**
+ * Walk from one entry's hash, through hash-only rows, to a certified head.
+ *
+ * `rows` are taken in the order given and must continue the chain from `fromId + 1` with no gap and
+ * no reordering — the walk does NOT sort them, so a removed or a swapped row is named rather than
+ * silently repaired. Leading rows at or below `fromId` are skipped (a fetched page may start earlier).
+ * Each row's digest is chained onto the running head; when the row carries an entry hash it must
+ * agree. The walk succeeds the moment the running head equals `certifiedHead`.
+ */
+export async function walkToCertifiedHead(args) {
+    const { fromId, fromHash, certifiedHead, hashFirstFrom } = args;
+    if (sameBytes(fromHash, certifiedHead))
+        return { ok: true, distance: 0n, headId: fromId };
+    const rows = args.rows;
+    let i = 0;
+    while (i < rows.length && rows[i].id <= fromId)
+        i++;
+    let h = fromHash;
+    let expected = fromId + 1n;
+    for (; i < rows.length; i++, expected++) {
+        const row = rows[i];
+        if (row.id !== expected) {
+            const next = rows[i + 1];
+            if (next && next.id === expected && row.id === expected + 1n) {
+                return {
+                    ok: false,
+                    at: expected,
+                    why: `rows ${expected} and ${row.id} are swapped: the chain is walked in id order, and a reordered row breaks it`,
+                };
+            }
+            if (row.id > expected) {
+                return {
+                    ok: false,
+                    at: expected,
+                    why: `row ${expected} is missing: the rows jump from ${expected - 1n} to ${row.id}, and every entry between the one checked and the certified head is needed`,
+                };
+            }
+            return {
+                ok: false,
+                at: row.id,
+                why: `row ${row.id} is out of order: it comes after row ${expected - 1n}`,
+            };
+        }
+        if (row.id < hashFirstFrom) {
+            return {
+                ok: false,
+                at: row.id,
+                why: `row ${row.id} was hashed under the record's older rule (below its switch point ${hashFirstFrom}): a walk through it needs its body, not its digest`,
+            };
+        }
+        const next = await recordLink(h, row.digest);
+        if (row.entryHash.length > 0 && !sameBytes(next, row.entryHash)) {
+            return {
+                ok: false,
+                at: row.id,
+                why: `row ${row.id} does not chain: SHA-256(previous head ‖ its digest) is ${toHexString(next)}, its entry hash is ${toHexString(row.entryHash)} — the row was altered, or a row before it was`,
+            };
+        }
+        h = next;
+        if (sameBytes(h, certifiedHead))
+            return { ok: true, distance: expected - fromId, headId: expected };
+    }
+    return {
+        ok: false,
+        at: expected,
+        why: `the certified head was not reached: walking ${expected - 1n - fromId} row(s) from entry ${fromId} ` +
+            `(to id ${expected - 1n}) never produced it. Either the rows stop short of the certified head, or the ` +
+            `certificate certifies a head from BEFORE this entry`,
+    };
+}
+//# sourceMappingURL=recordChain.js.map

package/dist/recordChain.js.map

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

package/dist/types.d.ts

@@ -27,9 +27,13 @@ export type MemoryEviction = Engram.MemoryEviction;
 export type MemoryHistory = Engram.MemoryHistory;
 export type AuditEntry = Engram.AuditEntry;
 /**
- * A window of the engram's record, as the reader may see it: an agent reads only the entries it
- * caused, so `items.length + withheld` is the window examined, and `total` is how many entries the
- * record has ever held. A page with `withheld > 0` is not the whole record.
+ * A window of the engram's record, as the reader may see it: an agent reads in full only the entries
+ * it caused, and every other entry in the window comes back in `sealed` as a hash-only row (id, the
+ * SHA-256 of its body, its entry hash), so `items.length + sealed.length` is the window examined and
+ * the chain can be walked through it. `total` is how many entries the record has ever held,
+ * `ringFloor` the oldest id still retained, and `hashFirstFrom` where the record switched to the
+ * hash-first rule. ⟨2026-10-18: this said `items.length + withheld`; the owner's ruling 6B of
+ * 2026-10-14 replaced the count with the sealed rows.⟩
  */
 export type AuditPage = OkOf<'listAuditEntries'>;
 /** The engram's public self-description — `about()`. The owner and the cycles balance are not in

package/dist/verify.d.ts

@@ -1,2 +1,6 @@
 export { verifyCertifiedAuditHead, verifyCertifiedLeaf, verifyCertifiedRegistryHead, verifyCertifiedAnchor, } from './certifiedAudit.js';
 export type { CertifiedAuditHead, VerifiedAuditHead, CertifiedLeaf } from './certifiedAudit.js';
+export { verifyHistoricalCertificate, IC_MAINNET_ROOT_KEY_HEX } from './certifiedAudit.js';
+export type { HistoricalCertificate } from './certifiedAudit.js';
+export { recordEntryBody, recordDigest, recordLink, legacyRecordLink, recordEntryHash, sealedRowOf, walkToCertifiedHead, } from './recordChain.js';
+export type { RecordEntryFields, SealedRow, WalkResult } from './recordChain.js';

package/dist/verify.js

@@ -8,4 +8,9 @@
 // nothing from Node; test/browser-safe-subpaths.test.ts walks their import graphs to hold that.
 // (The ratified name, from the 2026-08 architecture audit's "INTRODUCE @engramx/client/verify".)
 export { verifyCertifiedAuditHead, verifyCertifiedLeaf, verifyCertifiedRegistryHead, verifyCertifiedAnchor, } from './certifiedAudit.js';
+// ⟨2026-10-15, the owner's ruling 6B of 2026-10-14⟩ The historical-certificate check and the record
+// walk, browser-safe (WebCrypto hashing). The evidence bundle's content link needs the memory-file
+// hash contract, which hashes with node:crypto, so `checkEvidence` stays on the package root.
+export { verifyHistoricalCertificate, IC_MAINNET_ROOT_KEY_HEX } from './certifiedAudit.js';
+export { recordEntryBody, recordDigest, recordLink, legacyRecordLink, recordEntryHash, sealedRowOf, walkToCertifiedHead, } from './recordChain.js';
 //# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -1 +1 @@
-{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,+DAA+D;AAC/D,EAAE;AACF,oGAAoG;AACpG,8FAA8F;AAC9F,2FAA2F;AAC3F,qGAAqG;AACrG,gGAAgG;AAChG,iGAAiG;AACjG,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,+DAA+D;AAC/D,EAAE;AACF,oGAAoG;AACpG,8FAA8F;AAC9F,2FAA2F;AAC3F,qGAAqG;AACrG,gGAAgG;AAChG,iGAAiG;AACjG,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,oGAAoG;AACpG,mGAAmG;AACnG,8FAA8F;AAC9F,OAAO,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE3F,OAAO,EACL,eAAe,EACf,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,mBAAmB,GACpB,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engramx/client",
-  "version": "0.16.0-rc.13",
+  "version": "0.16.0-rc.14",
   "description": "Client SDK for EngramX — persistent, decentralized memory for AI agents on the Internet Computer",
   "license": "Apache-2.0",
   "author": "EngramX <developer@engramx.ai>",
@@ -53,7 +53,7 @@
     "@icp-sdk/core": "^6.1.0"
   },
   "dependencies": {
-    "@engramx/idl": "0.16.0-rc.13",
+    "@engramx/idl": "0.16.0-rc.14",
     "@icp-sdk/core": "^6.1.0",
     "@icp-sdk/vetkeys": "0.7.0",
     "@noble/curves": "^2.4.0"