Skip to content

docs: canonical JSON and content IDs (closes #74) - #114

Merged
bjacobso merged 1 commit into
mainfrom
docs/content-hashing
Nov 18, 2026
Merged

bjacobso merged 1 commit into
mainfrom
docs/content-hashing

Conversation

@bjacobso

Copy link
Copy Markdown
Owner

Closes #74. Docs only; no package change, so no changeset.

Canonical JSON and content IDs

New page docs/content-hashing.md (Reference sidebar, after Storage footprint) for the public @triplex-build/triplex/content exports:

  • Import and use: CanonicalJson.encodeOrThrow / CanonicalJson.encode (Effect), ContentId.hash(domain, payload), isContentId, ContentIdSchema, short, Sha256.hex. Checked ts check example.
  • The contract, as the code implements it: keys in UTF-16 code-unit order; undefined properties omitted, undefined array slots as null; shortest round-trip numbers with -0 → 0; non-finite numbers, Date, BigInt, functions, symbols, class instances and cycles rejected with a CanonicalEncodingError carrying reason and path.
  • What it does not promise, per the issue: not claimed as RFC 8785/JCS, no Unicode normalization, no hashing of arbitrary objects.
  • Domains: the length-prefixed domain in ContentId.hash; use your own names, not triplex/*.
  • Moving an existing encoder onto it without changing stored hashes (compare encodings on real samples first).

Every behaviour on the page was checked against the build: {z:-0,a:[undefined,1]} → {"a":[null,1],"z":0}; {b:1.0,a:{y:undefined,x:"é"}} → {"a":{"x":"é"},"b":1}; a Date at attrs.when fails with unsupported_type at path attrs.when. pnpm docs:check and pnpm docs:build pass (55 local links).

Branches deleted on 2026-11-18 (restore record)

Ben approved deleting these 24 remote branches. Each still exists as the head of its PR, and any one can be restored with:

git push origin <sha>:refs/heads/<branch>

bench/tx1-baseline-source (the exact source #61 measured) is kept. So are main, changeset-release/main, and the open Dependabot branches for #112 and #113.

Branch Last commit Date PR
bench/tx1-position-contention 842129fbbde17702b7853764d5edb4c57cb7f927 2026-11-11 #61 closed
conductor/entity-write-helpers 3eefe14a3b541818fd91ef0ada05c374d1e3badf 2026-10-23 #45 closed
conductor/large-incremental-commits-in-memory 56998c8fd31c6157189b76e81a4970b04e881f9e 2026-10-30 #47 closed
conductor/triplex-commit-validators 220f8f4e8c8fae5223a54929f99a9b993e35c7ee 2026-11-04 #52 closed
conductor/worldvm-rollout-triplex fbfd874cc1c0df363b561d3e4c095b2b02b5b596 2026-10-04 #38 closed
design/tx1-late-allocation 75d8ef67ca5ca61c4396e28ba60992fccdcc86ae 2026-11-10 #63 closed
design/tx1-scoped-concurrency ec948a59b2d8c7c75252dd752d67f22767d7c184 2026-11-11 #64 closed
docs/operational-followup-issues 77a161f810b955abe549945879b6b2b4de2e6347 2026-11-10 #75 closed
docs/tx3-host-sealing-rfc 69d9eea1b8f0f020760d52b03b3604b0fdbd2cc6 2026-11-10 #69 closed
ergonomics/next-2 9e039b55b44eac9cd809be62f4b460902f670fa6 2026-11-12 #82 merged
ergonomics/one-package e92d440203a0c5d14a3f78bb7651d064fa35c8bf 2026-11-12 #84 merged
feat/tx4-operational-entries 68e25ebaec69c426d84bbfff58d8a822bef90b3f 2026-11-11 #65 merged
feat/tx8-schema-guard 3885a8f84b37c7d42a195153d9a7560a6faf2e5b 2026-11-11 #59 merged
fix/tx2-host-position-basis a87d485b050465a7a116459e095a27a597519fd8 2026-11-11 #67 merged
investigate/tx1-invariant-scopes 9c3a939dd29bd28572d628fa09fd1d01c7286982 2026-11-11 #77 closed
investigate/tx1-ordered-publication 3cb0118584bf22085ac1b10dfca7592dabde70ad 2026-11-10 #76 closed
sensitive/erasure d759f6eacb74362e9ca0e90b067bd54eb48e5fe5 2026-11-13 #95 merged
sensitive/no-token-copies ef188a32b893e24b5f94a30f787c0b826970144f 2026-11-13 #93 merged
sensitive/sql-key-provider 3d712da59a4f5ff5cfa680cb563c9917bc3b89ba 2026-11-13 #92 merged
shanghai-v5 d6ae24a8ab154fdfea85485bcd8ea2ab09877aa1 2026-09-09 #16 closed
site/hero-animation c96bf6412b464b5832d77a24cbdb4bd162fecf9a 2026-11-12 #88 closed
site/wave-one 734a542e8f972f274480a0fe45419a0cc59c1284 2026-11-12 #83 closed
ulaanbaatar cc9c98475226b9e52631b759adb9bfa8d8243150 2026-09-05 #6 closed
worldvm/kv-memory-performance 51696ac2d6e5940dc4ba5cdb55b84215f53258d8 2026-10-29 #46 closed

🤖 Generated with Claude Code

Documents the public @triplex-build/triplex/content encoder and content IDs: the byte-identity
contract (UTF-16 key order, undefined handling, -0, finite numbers, rejected types and cycles),
what it does not promise (RFC 8785 conformance, Unicode normalization), domain-separated
ContentId.hash, and how a host moves its own encoder onto it without changing stored hashes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Documentation preview removed (PR closed).

@bjacobso
bjacobso merged commit d02bde6 into main Nov 18, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document the existing public CanonicalJson encoder (missing-export premise refuted)

1 participant