@synoi/sraid 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SynOI Inc. / Foundation X, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROJECTION_SPEC.md

@@ -0,0 +1,245 @@
+# SRAID CDRO OID Projection — Normative Specification
+
+Status: Normative
+Version: 1.0
+Date: 2026-07-05
+Authority: ADR_019 (L0 Normative Contract Unification), decisions 1-3.
+License: CC0-1.0 (public domain). Non-TypeScript SDKs MUST derive from this
+document; the TypeScript reference implementation is `@synoi/sraid`
+(`src/oid.ts`, `src/canonicalize.ts`).
+
+This document is the SINGLE NORMATIVE SOURCE of prose for:
+
+1. the CDRO OID content-core projection (the field-set removed before hashing),
+2. the number rule (finite integers only), and
+3. the RFC 8785 (JCS) rules SRAID relies on.
+
+Any implementation (TS, Python, Rust, Go, or other) that produces a byte
+string different from the reference for the same input is non-conformant. The
+cross-language ABI is enforced by the conformance vectors generated from the
+reference implementation; this prose exists so a new SDK can be DERIVED from
+one written source instead of re-inventing a divergent copy. There have been
+four divergent projections and two number rules across the stack; this spec
+collapses them to one.
+
+---
+
+## 1. The OID
+
+A CDRO's OID (Object IDentifier) is:
+
+```
+OID = "sha256:" + lowercase_hex( SHA-256( canonicalize( cdroContentCore(object) ) ) )
+```
+
+- The hash is SHA-256 (FIPS 180-4). It stays quantum-relevant only via Grover,
+  which halves preimage resistance to 2^128 — acceptable.
+- The digest is emitted as exactly 64 lowercase hexadecimal characters.
+- The prefix is the literal ASCII string `sha256:`. It is NEVER truncated. A
+  bare hex string with no algorithm prefix is NOT a conformant OID.
+- `canonicalize` is the RFC 8785 subset defined in §3.
+- `cdroContentCore` is the projection defined in §2.
+
+The OID is content-addressed: any byte-level change to the canonical content
+core yields a different OID. Signatures are computed over the SAME canonical
+bytes and attach AFTER hashing, so signing (or rotating a signature) never
+changes the OID.
+
+---
+
+## 2. The content-core projection (`cdroContentCore`)
+
+`cdroContentCore(object)` returns `object` with EXACTLY the following six
+top-level fields REMOVED, and every other field KEPT unchanged:
+
+| Field                 | Why it is removed                                        |
+| --------------------- | -------------------------------------------------------- |
+| `oid`                 | The projection OUTPUT; it cannot be an input to itself.  |
+| `signature`           | Legacy hybrid `SignatureEnvelope`; attaches after hash.  |
+| `ml_dsa_signature`    | Detached ML-DSA-65 signature; produced by the signer.    |
+| `signature_key_id`    | Signer-stamped key id; produced by the signer.           |
+| `signature_algorithm` | Signer-stamped algorithm id; produced by the signer.     |
+| `attestation`         | DSSE `AttestationEnvelope`; attaches after hash.         |
+
+### 2.1 The strip-set is SEMANTIC, not a per-surface enumeration
+
+The removed set is defined by ONE rule: **remove every field the signer
+produces AFTER canonicalization, plus the OID output itself.** The six names
+above are the concrete realization of that rule for the current object shape.
+An implementation MUST NOT maintain its own independent hand-listed strip-set;
+it derives the set from this rule and this table. A field that a future signer
+stamps post-hash is added here, in this one place, and nowhere else.
+
+### 2.2 Everything else is KEPT and hashed into identity
+
+In particular the following are IN the content core and therefore IN the OID:
+
+- `gap_version` — IN identity so a protocol downgrade is OID-detectable. A
+  receipt claiming `gap_version: "1.0"` cannot be silently re-presented as a
+  different protocol version without changing its OID.
+- `supersedes` — IN identity because the SRAID Merkle-DAG "head proves history"
+  property requires every lineage edge to be inside the hash. Superseding mints
+  a NEW object; it never mutates the superseded object's bytes, so keeping the
+  pointer inside identity is safe and makes the lineage edge tamper-evident. An
+  edge cannot be added, removed, or re-pointed without changing the OID.
+- `prev`, `links` — L3 lineage edges, same rationale as `supersedes`.
+- `authority` — the L4 authorized-axis block. IN identity so it cannot be
+  stripped or swapped without breaking the OID and the signature.
+- `sensitivity` — the coarse, opaque propagating tier. IN identity so a
+  classification cannot be silently downgraded.
+- `type`, `sraid_version`, `tenant_id`, `created_at_ms`, `created_by`, `body`,
+  and every other content field.
+
+### 2.3 Pre- vs post-attestation invariance (the keystone)
+
+This is the property the entire "portable, independently verifiable receipt"
+thesis depends on: **`cdroOid(object)` yields the SAME OID whether `object` is
+pre-attestation (no signature fields) or post-attestation (signature fields
+attached).** Because §2 strips the six detached fields, a third party who
+recomputes the OID of a SIGNED receipt gets the byte-identical value the signer
+stamped. A projection that hashes `attestation` (or any of the six) into the
+OID breaks this: the third party recomputes a different OID and wrongly
+concludes a valid receipt was tampered.
+
+Reference conformance vector (from `test/oid.test.ts`, `baseCdro`):
+
+```
+cdroOid(pre-attestation)  == cdroOid(post-attestation)
+                          == sha256:d1d5d5c51d2d5f80470089ff10b8b642e19fc76db6be298f4f346616528a087a
+```
+
+where the object is
+
+```json
+{
+  "type": "gap:decision_receipt",
+  "sraid_version": "2.0",
+  "gap_version": "1.0",
+  "tenant_id": "tenant-x",
+  "created_at_ms": 1720000000000,
+  "created_by": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+  "body": { "decision": "allow", "amount_minor": 1299 },
+  "authority": { "grant_oid": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "decision": "allow" },
+  "supersedes": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+}
+```
+
+The post-attestation form is the same object with `oid`, `attestation`,
+`signature`, `ml_dsa_signature`, `signature_key_id`, and `signature_algorithm`
+added; its `cdroOid` is byte-identical to the pre-attestation form's.
+
+---
+
+## 3. The number rule and the JCS rules (`canonicalize`)
+
+`canonicalize(value)` is a STRICT SUBSET of RFC 8785 (JCS). It produces a
+deterministic UTF-8 string, byte-identical across conformant implementations
+for the same input.
+
+### 3.1 Number rule — finite integers ONLY (ADR_019 decision 2)
+
+A number is legal **iff it is a finite integer.** All of the following are
+REJECTED with a typed error BEFORE any hashing:
+
+- `NaN`, `+Infinity`, `-Infinity` (RFC 8785 already forbids non-finite).
+- Any non-integer number (float), e.g. `1.5`, `0.1`, `2e-3`, `9.99`.
+
+Rationale: the product is settlement-grade signed receipts. All money is
+represented as integer minor units (e.g. cents); all timestamps are integer
+milliseconds. No conformant SRAID object legitimately carries a float.
+Forbidding floats removes the single hardest RFC 8785 cross-language trap
+(shortest-round-trip float serialization) from a signed byte string, with
+near-zero blast radius.
+
+Notes:
+
+- `-0` is an integer and serializes as `"0"` (`JSON.stringify(-0) === "0"`).
+  There is NO bespoke `-0` special-case in the reference implementation; the
+  integer path handles it. Implementations MUST NOT add a separate `-0` branch
+  (it is a divergence source and cannot fire on legal input differently).
+- A source token like `56.0` that a JSON parser collapses to the integer `56`
+  is legal (it IS the integer 56 after parsing). The rule constrains the parsed
+  numeric VALUE, not the source lexeme.
+- Legal integers serialize via the ECMAScript number-to-string of RFC 8785
+  §3.2.2.3, which for integers is the plain decimal form (`1000`, `-42`, `0`).
+
+### 3.2 JCS rules SRAID relies on (MUST NOT regress)
+
+- **Object key ordering:** keys are sorted in ascending UTF-16 code-unit order
+  (RFC 8785 §3.2.3 for UTF-16 host languages; this is JS `Array.prototype.sort`
+  default order). This is verified byte-for-byte against the RFC 8785 reference
+  vectors (`arrays`, `french`, `structures`, `unicode`, `weird`).
+- **String escaping:** minimal JSON string escaping — only the characters JSON
+  requires be escaped are escaped, using the shortest form. No locale, no
+  Unicode normalization (the input's code points are emitted as-is; e.g. an
+  unnormalized `A` + combining ring is NOT normalized).
+- **No whitespace:** separators are bare `,` and `:`; no spaces or newlines.
+- **`null`:** emitted as the literal `null`. Booleans as `true` / `false`.
+- **Arrays:** element order preserved; each element recursively canonicalized.
+
+### 3.3 Reject-loud domain (out-of-domain values throw, never coerce)
+
+A typed error is thrown, never a silent wrong/invalid form, for:
+
+- non-integer / non-finite numbers (§3.1),
+- `undefined` / function / symbol / bigint as any value, INCLUDING an array
+  element (which would otherwise produce invalid JSON like `[1,,2]`),
+- a sparse array hole,
+- any object exposing a `toJSON()` method (e.g. `Date`, `Buffer`, decimal
+  libraries) — convert to a JSON value (e.g. an ISO string) first.
+
+Object properties whose value is `undefined` are OMITTED (matching the JSON
+data model). An `undefined` ARRAY element throws (omitting it would shift
+indices and silently change meaning).
+
+### 3.4 Relationship to full RFC 8785
+
+SRAID's number domain is a DOCUMENTED NARROWING of RFC 8785: the RFC permits
+non-integer numbers with a defined serialization; SRAID forbids them. SRAID is
+therefore RFC 8785 conformant on ordering and string escaping (proven against
+the reference vectors), and INTENTIONALLY stricter on numbers. A general-purpose
+RFC 8785 float vector (e.g. the reference `values` vector) is expected to be
+REJECTED by a conformant SRAID canonicalizer, not to round-trip a float.
+
+---
+
+## 4. Firewalls — schemes that are NOT this projection
+
+Two adjacent schemes look similar and MUST NOT be merged into this normative
+CDRO projection. Confusing them is signature confusion, which is fatal.
+
+### 4.1 The v1 flat-scalar receipt projection (legacy, separate)
+
+The gateway's legacy v1 flat signer uses a DIFFERENT strip-set (its
+`GAP_SIGNING_EXCLUDED` set additionally excludes `gap_version` and
+`supersedes`, and folds the body to flat scalars). That is a SEPARATE, LEGACY
+signing shape gated behind the `receipt_scheme` discriminator. It is NOT the
+CDRO content core and MUST NOT be used to recompute a CDRO OID. The live v2
+signer uses THIS projection (`@synoi/sraid`'s `cdroContentCore`); the v1 flat
+scheme is retained only for objects minted before v2 and is never confused for
+a content core.
+
+### 4.2 The Vault L1 binary-TLV canonical hash (separate identity contract)
+
+The Vault L1 `canonical_hash` (a binary TLV encoding, `@synoi/vault`) is a
+DISTINCT, deliberately-frozen identity contract governing a different layer. It
+is explicitly OUT OF SCOPE and firewalled — NOT merged with this JSON/JCS
+projection. A Vault L1 identity and a CDRO OID are computed by different rules
+by design.
+
+---
+
+## 5. Conformance
+
+An implementation is conformant iff, for every generated conformance vector:
+
+1. its `cdroContentCore` removes exactly the six §2 fields and keeps all others,
+2. `cdroOid(pre-attestation) == cdroOid(post-attestation)` (§2.3),
+3. every float-bearing input is REJECTED (§3.1),
+4. changing `supersedes` or `gap_version` changes the OID (§2.2),
+5. its `canonicalize` matches the RFC 8785 reference ordering/escaping vectors
+   byte-for-byte (§3.2).
+
+The reference vectors are generated from `@synoi/sraid` and consumed
+byte-for-byte by all SDKs, the gateway signer, and the verifiers in CI. A
+divergent strip-set, number rule, or canonicalize turns a vector red.

package/README.md

@@ -0,0 +1,149 @@
+# @synoi/sraid
+
+Reference TypeScript implementation of **SRAID (Self-Routing Addressable
+Identity Data)** — L0 of the SynOI SRAID Stack. MIT-licensed.
+
+SRAID defines:
+
+- a content-addressed object envelope, the **CDRO** (Canonical Data-Rich Object),
+- a deterministic canonical object serializer used as input to hashing and signing,
+- a content-derived **OID** (`sha256:` followed by 64 hex chars) over the canonical bytes,
+- a hybrid **Ed25519 + ML-DSA-65** signature envelope,
+- an **L3 Merkle-DAG lineage** layer (`prev` edge + typed `links[]`), hashed into the OID so a head id commits its whole reachable history, and
+- a supersession record, the **SRO** (Supersession Record Object), that links a successor CDRO to its predecessor.
+
+The three legacy supersession mechanisms — the self-asserted `supersedes`
+string, the standalone SRO, and the `prev` edge — are unified by the lineage
+helpers (`lineageLinks`, `supersededOids`, `latestWins`). `latestWins` resolves
+a set of versions to its single head by following the identity-bound `prev`/
+`links` edges, giving a verifier a **latest-wins / monotone** rule instead of an
+unwitnessed pointer. Given the complete version set, `latestWins` will not name
+a superseded object as head; full rollback-replay resistance additionally
+requires that the superseding object cannot be withheld, which is a Resolver /
+transparency-log property (DESIGN, not yet deployed). The `set_complete` field
+on `LatestWinsResult` is the local signal that lets a caller detect an
+incomplete (potentially withheld) set.
+
+Higher layers — Vault/Resolver (L1), Inference Broker/Resonance (L2), GAP (L3)
+— are built on SRAID objects. This package is intentionally tiny and has no
+storage, no HTTP surface, and no governance logic.
+
+## Install
+
+```bash
+npm install @synoi/sraid
+```
+
+## Minimal example
+
+```ts
+import {
+  canonicalize,
+  oidOf,
+  verifySignature,
+  validateCdro,
+  type CDRO,
+  type SignatureEnvelope,
+} from '@synoi/sraid'
+import { ed25519 } from '@noble/curves/ed25519'
+import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js'
+import { randomBytes } from 'node:crypto'
+
+// 1. Build a CDRO body and derive its OID.
+const body = { capability: 'door.unlock', risk_class: 'B' }
+const oid = oidOf(body)                          // sha256:<64 hex chars>
+
+const cdro: CDRO<typeof body> = {
+  oid,
+  type: 'gap:capability_declaration',
+  sraid_version: '2.0',
+  tenant_id: 't-home',
+  created_at_ms: Date.now(),
+  created_by: 'actor:skill:demo',
+  body,
+}
+
+console.log(validateCdro(cdro))                  // { ok: true, errors: [] }
+
+// 2. Sign the canonical bytes with both Ed25519 and ML-DSA-65.
+const canonical = canonicalize(cdro.body)
+const message = new TextEncoder().encode(canonical)
+
+const edPriv = new Uint8Array(randomBytes(32))
+const edPub = ed25519.getPublicKey(edPriv)
+const mlKeys = ml_dsa65.keygen(new Uint8Array(randomBytes(32)))
+
+const envelope: SignatureEnvelope = {
+  ed25519: Buffer.from(ed25519.sign(message, edPriv)).toString('base64'),
+  ml_dsa_65: Buffer.from(ml_dsa65.sign(message, mlKeys.secretKey)).toString('base64'),
+  signer_kid: 'synoi-demo-2026-05',
+}
+
+// 3. Verify.
+const v = verifySignature({
+  canonical,
+  envelope,
+  ed25519_pub: edPub,
+  ml_dsa_pub: mlKeys.publicKey,
+})
+console.log(v)                                   // { valid: true, reasons: [] }
+```
+
+## Surface
+
+```ts
+canonicalize(value: unknown): string
+oidOf(canonical: unknown): string
+oidOfCanonical(canonical: string | Uint8Array): string
+
+verifySignature(args: {
+  canonical:   string | Uint8Array
+  envelope:    SignatureEnvelope
+  ed25519_pub: Uint8Array
+  ml_dsa_pub:  Uint8Array
+}): { valid: boolean; reasons: string[] }
+
+validateCdro(x: unknown): { ok: boolean; errors: string[] }
+validateSro(x: unknown): { ok: boolean; errors: string[] }
+validateSignatureEnvelope(x: unknown): { ok: boolean; errors: string[] }
+
+// Types
+interface CDRO<TBody>            { /* envelope */ }
+interface SRO                    { /* supersession record */ }
+interface SignatureEnvelope      { ed25519: string; ml_dsa_65: string; signer_kid: string }
+```
+
+## Canonical form
+
+The canonical form is recursive JCS-lite JSON:
+
+- primitives via `JSON.stringify`,
+- objects emit keys in lexicographic order,
+- `undefined` properties are omitted,
+- arrays preserve order,
+- no whitespace.
+
+This canonical form is a wire contract. **Any byte-level change to the
+serializer changes every OID and invalidates every previously-created
+signature.** Treat it as frozen for SRAID v1.0; evolve it only via a new,
+explicitly versioned canonical profile.
+
+## OID format
+
+```
+OID = "sha256:" + lowercase_hex( sha256( canonicalize(content) ) )
+```
+
+The hash input is the OBJECT MINUS its own `oid` and `signature` fields, so
+signature rotation does not change the OID.
+
+## Why hybrid signatures
+
+SRAID objects are signed with both Ed25519 and ML-DSA-65. The classical
+Ed25519 path is fast and ubiquitously verifiable today; the post-quantum
+ML-DSA-65 path future-proofs receipts against quantum attacks. `verifySignature`
+in this package returns `valid: true` only when BOTH succeed.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

package/SPEC.md

@@ -0,0 +1,216 @@
+# SRAID - Self-Routing Addressable Identity Data, Core Object Specification
+
+**Core Specification, Version 1.0**
+
+> To the extent possible under law, SynOI Inc. has waived all copyright and related rights to this specification under the Creative Commons CC0 1.0 Universal Public Domain Dedication (https://creativecommons.org/publicdomain/zero/1.0/). The reference implementation `@synoi/sraid` is MIT-licensed; the conformance suite `@synoi/conformance` is Apache-2.0-licensed.
+
+The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119.
+
+---
+
+## 1. Overview
+
+SRAID defines a **canonical, content-addressed object** (serialized in a canonical object format) and its **object identifier (OID)**. The goals are:
+
+- **Determinism.** The same content yields the same canonical bytes and the same OID on any implementation.
+- **Content addressing.** An object's identity is derived from its content, so identical content deduplicates and any party can recompute and check an OID.
+- **Independent verification.** An object carries its own signatures, so a third party can verify authenticity offline, without contacting the issuer.
+
+SRAID Core is intentionally small. It specifies the object envelope, the canonical form, the OID, and the signature requirement. Higher-level concerns (storage, retrieval, access control) are out of scope and are layered above SRAID by other specifications.
+
+## 2. The SRAID object
+
+A SRAID object (the Canonical Data Record Object, or **CDRO**) is a map with the following members:
+
+| Member | Required | Meaning |
+|---|---|---|
+| `oid` | yes | The object's content identifier (Section 4). `"sha256:" + lowercase_hex(SHA-256(canonical bytes))`. Excluded from the OID input. |
+| `type` | yes | Object type discriminator (a non-empty string, for example `"gap:capability_grant"` or `"sraid:sro"`). |
+| `sraid_version` | yes | SRAID protocol version. The only defined value is the string `"2.0"`. |
+| `tenant_id` | yes | Non-empty string identifying the tenant that owns the object. |
+| `created_at_ms` | yes | Unix-millisecond creation timestamp (a positive integer). |
+| `created_by` | yes | OID or other non-empty string identifying the actor (skill, user, device) that created the object. |
+| `body` | yes | The type-specific payload. May be any JSON value, but the member MUST be present. |
+| `supersedes` | optional | If present, a canonical OID (`sha256:` followed by exactly 64 lowercase hex characters) of the previous version this object supersedes. |
+| `sensitivity` | optional | If present, a **coarse, opaque sensitivity tier** (Section 7): one of `"s0"`, `"s1"`, `"s2"`, `"s3"`, `"s4"` (lowest to highest). It MUST NOT be a literal content category (for example `"phi"` or `"financial"`). Part of the canonical content, so it is hashed into the OID and cannot be silently stripped or downgraded. |
+| `attestation` | optional | If present, a detached **DSSE attestation envelope** (Section 6) carrying one or more signatures over the object's PAE-encoded canonical bytes. This is the preferred signing form. May be absent on draft or unsigned objects. |
+| `signature` | optional | LEGACY. If present, a single detached hybrid signature envelope over the object's bare canonical bytes (Section 6.4). Retained for back-compat; new producers SHOULD emit `attestation` instead. May be absent on draft or unsigned objects. |
+
+The `oid`, `attestation`, and `signature` members are excluded from the OID input (Section 4) so that the same content produces the same OID and re-signing never changes identity. All other members are part of the canonical content and therefore contribute to the OID.
+
+**Lineage fields are independent.** An object MAY carry `supersedes`, `prev`, and one or more `links[]` simultaneously. `supersedes` asserts a version-replacement relationship (this object is the authoritative successor of the referenced OID); `prev` is the hash-chain backpointer for ordered append; `links[]` are typed semantic edges (L3). Each is validated for canonical-OID format in isolation. The validator does NOT enforce agreement among them (for example it does not require `supersedes === prev`), nor does it resolve or fetch the referenced objects. Higher layers (Vault/Resolver, GAP) are responsible for any cross-field lineage semantics. The signed supersession receipt (SRO, type `sraid:sro`) is distinct from the self-asserted `supersedes` field on a CDRO: the SRO is an independently signed object authored by a governing actor; `supersedes` is a producer-asserted claim inside the envelope. Both fields are format-validated but neither implies the other.
+
+## 3. Canonical form
+
+SRAID v1.0 defines one normative canonical object format, identified as **`sraid/json`** (strict RFC 8785 JCS):
+
+1. Take the value to canonicalize. For OID derivation this is the CDRO with its `oid` and `signature` members removed (Section 4); for signing it is the same value the signer hashed.
+2. Serialize it as JSON deterministically per RFC 8785:
+   - **Objects** emit their keys sorted in ascending lexicographic (UTF-16 code-unit) order. Each member is `key:value` with no whitespace; members are joined by a bare `,`.
+   - Object members whose value is `undefined` are OMITTED entirely (an absent member and a member set to `undefined` canonicalize identically).
+   - **Arrays** preserve their element order; each element is recursively canonicalized and joined by a bare `,`.
+   - **Strings** are emitted with standard JSON string escaping.
+   - **Numbers** use the ECMAScript number-to-string serialization defined by RFC 8785 §3.2.2.3. An implementation MUST reject (throw an error for) any number value that is `NaN`, positive `Infinity`, or negative `Infinity` — these values are not representable in JSON and MUST NOT be silently coerced to `null` or any other value. The value `-0` MUST serialize as `"0"` (the positive-zero form) per RFC 8785 §3.2.2.3.
+   - `null`, `true`, and `false` are emitted literally.
+   - No insignificant whitespace appears anywhere; the only separators are bare `,` and `:`.
+3. Encode the result as UTF-8. The resulting byte string is the object's **canonical bytes**.
+
+The precise canonicalization is pinned by the test vectors in `@synoi/conformance` (Section 8); an implementation is canonical-correct if and only if it reproduces those vectors.
+
+A binary profile, **`sraid/cbor`** (CBOR per RFC 8949 with COSE per RFC 9052 for signatures), is reserved for a future version. An implementation MUST declare which profile it produces; a v1.0 producer MUST produce `sraid/json`.
+
+**Serialization format decision (closed, 2026-06-27).** `sraid/json` is the one normative format for v1.0. The choice is settled for this version; it is not under deliberation. Rationale: (a) RFC 8785 JCS specifies a single, deterministic output with no schema dependency, which is required because `body` may be any JSON value (Section 2); (b) the conformance vectors (Section 8) already pin the byte-exact output, establishing a concrete interoperability floor; (c) JSON tooling is universally available across the implementation environments SRAID targets. `sraid/cbor` is explicitly deferred to a post-v1.0 additive binary profile. When introduced, it MUST yield the same OID-bearing content model as `sraid/json` (identical member set and semantics), not a replacement format. A `sraid/cbor` producer is therefore still bound by all CDRO structural rules in Section 2.
+
+## 4. The Object Identifier (OID)
+
+> The OID is the single normative identifier of SRAID v1.0.
+
+The OID is computed over the canonical bytes of the CDRO with its `oid`, `attestation`, and `signature` members excluded from the input (so signing or re-signing never changes the OID):
+
+```
+OID = "sha256:" + lowercase_hex( SHA-256( canonical_bytes ) )
+```
+
+- An OID MUST match the regular expression `^sha256:[0-9a-f]{64}$`.
+- The OID is both the object's content identity and its deduplication key: two CDROs whose members are identical after removing `oid`, `attestation`, and `signature` MUST yield identical canonical bytes and therefore an identical OID.
+- Deduplication, supersession, and any trust or truth decision MUST use the full OID. An implementation MUST NOT substitute a truncation of the hash for these purposes.
+- The 64-hex `sha256:` OID is the sole normative object identifier. The class/schema-prefixed `[4+12]` short form of Section 5 is a non-normative routing prefix only and is never an object identity.
+
+SHA-256 provides approximately 128-bit pre-image resistance against a quantum adversary (Grover) and approximately 128-bit collision resistance, so the OID does not require migration for post-quantum reasons. Algorithm agility (a self-describing multihash form) is reserved for a future version and, if introduced, MUST be a distinct, versioned change rather than a silent one.
+
+## 5. Routing prefix (non-normative)
+
+Implementations MAY derive a short, fixed-size **routing prefix** from an object for type-partitioned placement or fast bucketing. A routing prefix begins with class/schema bytes followed by a prefix of the object's SHA-256.
+
+- A routing prefix MUST NOT be used as a security identity, nor for deduplication, supersession, or trust decisions; those use the full OID (Section 4). A routing-prefix collision is a placement event, resolved by comparing full OIDs.
+- The exact byte layout of the routing prefix is not fixed by SRAID v1.0 and is reserved as a separate, non-normative profile.
+
+## 6. Attestation (signatures)
+
+An object MAY carry a detached **attestation envelope** that authenticates its canonical bytes. SRAID v1.0 defines a **hybrid signature suite** combining a classical and a post-quantum algorithm, BOTH required:
+
+- **Ed25519** (RFC 8032), and
+- **ML-DSA-65** (FIPS 204).
+
+The preferred form is a **DSSE** (Dead Simple Signing Envelope) JSON-profile envelope in the optional `attestation` member (Section 6.1–6.3). A legacy bare-bytes envelope (the `signature` member) is retained for back-compat only (Section 6.4). The `attestation` and `signature` members are not part of the OID (Section 4), so an object may be re-signed without changing its identity.
+
+### 6.1 The DSSE attestation envelope
+
+The `attestation` member has three members:
+
+- `payloadType` — a non-empty media-type string identifying the payload kind (for example `application/vnd.synoi.sraid+json`, or `application/vnd.in-toto+json` for an in-toto/SLSA supply-chain attestation),
+- `payload` — the canonical UTF-8 string that is attested (the CDRO content core per Section 3–4, i.e. the object minus its `oid`, `attestation`, and `signature` members), and
+- `signatures` — an array of signature entries, each with members `alg` (the algorithm identifier, e.g. `"ed25519"` or `"ml-dsa-65"`), `sig` (the base64-encoded signature bytes), and an optional `keyid` (an opaque string identifying the keypair).
+
+### 6.2 Pre-Authentication Encoding (PAE) — type binding
+
+Each signature in `attestation.signatures` is computed over the **PAE** of the envelope, NOT over the bare payload:
+
+```
+PAE(payloadType, payload) =
+    "DSSEv1" SP LEN(payloadType) SP payloadType SP LEN(payload) SP payload
+```
+
+where `SP` is a single ASCII space (0x20), `LEN(x)` is the ASCII-decimal byte length of `x` in its UTF-8 encoding, and `payloadType` and `payload` are their raw UTF-8 bytes. Because `payloadType` (and both lengths) are inside the signed bytes, the payload TYPE is structurally bound into every signature. A signature minted for one `payloadType` therefore CANNOT verify against an envelope that claims a different `payloadType`, even if the `payload` bytes are identical. This closes the cross-type / confused-deputy hazard inherent in signing bare canonical bytes (where all object kinds are signed identically).
+
+### 6.3 The both-required (AND) policy
+
+DSSE is, by itself, an OR-of-signatures envelope. SRAID layers a stricter rule on top: a conformant SRAID attestation MUST carry both an `ed25519` and an `ml-dsa-65` entry over the same PAE, and a verifier MUST require BOTH to verify (against the supplied public keys) before the object is considered signed. The presence of additional `signatures` entries with other algorithms is permitted and ignored by a SRAID hybrid verifier. Signatures are base64-encoded (standard alphabet, with `=` padding).
+
+### 6.4 Legacy bare-bytes envelope (`signature`) — deprecated
+
+For back-compat, an object MAY instead carry the legacy `signature` member with three members `ed25519`, `ml_dsa_65` (both base64-encoded signatures), and `signer_kid` (an opaque non-empty string). In the legacy form both signatures are computed over the bare canonical bytes (the CDRO minus its `oid`, `attestation`, and `signature` members, per Section 4) with NO payload-type binding. A verifier MUST require BOTH signatures to verify. New producers SHOULD NOT emit the legacy form; it lacks the PAE type binding of Section 6.2 and is retained only so objects minted before DSSE adoption keep verifying.
+
+### 6.5 Binary profile
+
+The `sraid/cbor` binary profile (Section 3) reserves **COSE** (RFC 9052) as the CBOR-profile attestation form. It is reserved, not defined by SRAID v1.0.
+
+## 7. Envelope metadata privacy
+
+The envelope members other than `body` (notably `type`, `tenant_id`, `created_by`, `created_at_ms`, and `supersedes`) are part of the canonical, signed, NON-encrypted envelope. They are in the clear so that the system can route, deduplicate, and govern an object without decrypting its `body`.
+
+Because those members are visible to anyone who can see the object, an implementation SHOULD treat the envelope as a public surface and keep semantically sensitive content inside `body` (which higher layers MAY encrypt) rather than in envelope members. In particular, the `type` discriminator SHOULD identify the structural object kind (for example `sraid:sro`) and SHOULD NOT encode a semantic content category (for example a literal `health` or `financial` label), so that the envelope does not leak the nature of the encrypted `body`.
+
+### 7.1 The sensitivity tier — coarse and opaque
+
+SRAID v1.0 defines an optional `sensitivity` member: a **coarse, opaque** tier drawn from the ordered, fixed ladder `"s0" < "s1" < "s2" < "s3" < "s4"` (lowest to highest). The tier is OPAQUE by construction. Because the envelope is a public surface, the member MUST NOT carry a literal content category (for example `"phi"`, `"health"`, or `"financial"`): such a label would leak the nature of an encrypted `body` to anyone who can see the object. The mapping from a real-world classification (PHI, PII, secret, …) to a tier is a higher-layer POLICY concern that is kept OFF the wire; the envelope only ever exposes the opaque level. An implementation MUST reject a `sensitivity` value that is not one of the five defined tiers.
+
+The member is part of the canonical content (Section 4), so it is hashed into the OID. A producer therefore cannot strip it or downgrade it without changing the OID and invalidating any signature.
+
+**Monotone carry-forward (`max`).** Sensitivity propagates monotonically through derivation. When an object is derived from one or more sources (for example a consolidated or summarized memory record built from raw records, linked by `consolidated_from`/`derived_from`), its tier MUST be at least the **maximum** tier among those sources. In other words a summary of higher-tier inputs MUST NOT be assigned a lower tier than its highest input. This is the standard lattice-based information-flow rule (Denning 1976): the join (`max`) of the source labels is the floor for the derived label. The reference implementation provides `sensitivityCarryForward` and `sensitivityMonotoneCheck` for this.
+
+> **Note (reserved).** SRAID v1.0 does NOT define a commitment-based selective-disclosure scheme that would CONCEAL the tier itself; the reference implementation carries none. Concealing the opaque tier (so that even the level is hidden) is reserved for a future version (Section 9) and MUST NOT be assumed by a v1.0 implementation. The v1.0 tier is opaque as to CATEGORY, not hidden as to LEVEL.
+
+## 8. Delegation chains
+
+A **delegation chain** is an ordered sequence of capability grant CDROs of type `gap:capability_grant` (or any type that carries a `body.capability_scopes` array) that traces authority from a trusted root principal down to a leaf grantee. Delegation verification is OFFLINE (verify-only): the verifier makes NO live-revocation or existence claim. Those remain resolver-dependent.
+
+### 8.1 Chain shape
+
+A chain MUST contain at least one grant. The ordered sequence is `links = [leaf, ancestor_0, ..., root]`, where `links[i]` is the direct child of `links[i+1]` and `links[links.length - 1]` is the terminal root grant. A chain MUST NOT exceed `MAX_DELEGATION_DEPTH = 8` links; an over-depth chain MUST be rejected before any hashing or signature work (cheap DoS guard).
+
+### 8.2 OID honesty
+
+Every link's `oid` MUST equal `sha256: + lowercase_hex(SHA-256(canonicalize(cdroContentCore(link))))`. A link whose claimed OID does not match the recomputed value MUST be rejected.
+
+### 8.3 Per-hop structure
+
+For each child `links[i]` under parent `links[i+1]`:
+
+**(a) Linkage.** `child.body.granted_by` MUST equal `parent.body.grantee.actor_oid`. A mismatch means the chain is broken and MUST be rejected.
+
+**(b) Attenuation.** Every capability in `child.body.capability_scopes` MUST be covered by at least one capability in `parent.body.capability_scopes` (segment-boundary wildcard match, Section 6 of the capability matching spec). A child grant with an **empty `capability_scopes` array MUST be rejected** — an empty scope set is not vacuously attenuated and grants nothing. A child scope that widens beyond all parent scopes (not covered by any parent scope) MUST be rejected.
+
+**(c) Expiry monotone narrowing.** A `null` parent expiry is unbounded; a `null` child expiry under a bounded parent is widening and MUST be rejected. When both are non-null, `child.body.expires_at_ms` MUST NOT exceed `parent.body.expires_at_ms`.
+
+### 8.4 Hybrid DSSE attestation, every link
+
+Every link MUST carry a valid hybrid DSSE attestation envelope (Section 6.1) over `PAE(payloadType, payload)` (Section 6.2) where `payload = canonicalize(cdroContentCore(link))`. Both Ed25519 AND ML-DSA-65 signatures are required (Section 6.3). A missing attestation or an attestation whose payload does not match the link's content core MUST cause the chain to fail.
+
+### 8.5 Root anchor (caller-asserted)
+
+The terminal link's issuer key MUST deep-equal the caller-supplied `rootPubkeys`. A mismatch means the chain does not anchor to a known trusted root and MUST be rejected.
+
+### 8.6 Action coverage (optional)
+
+When the verifier is called with an optional `action` string, the leaf grant's `capability_scopes` MUST cover that action (using the same segment-boundary wildcard match as Section 8.3(b)). An uncovered action MUST fail closed (`authorized: false`). When no `action` is supplied, coverage of a specific action is not checked (GATE 5 skipped; `action_checked: false`).
+
+### 8.7 No live-state claims
+
+Delegation verification MUST NOT assert revocation status or grant existence. Implementations MUST return literal `false` (not a computed boolean) for `revocation_checked`, `not_revoked`, and `existence_checked`. Those remain RESOLVER-DEPENDENT and are out of scope for offline verification.
+
+## 9. Conformance
+
+An implementation conforms to SRAID Core v1.0 if it:
+
+1. Produces `sraid/json` canonical bytes that match the published vectors,
+2. Computes OIDs per Section 4 that match the published vectors, and
+3. Verifies signatures per Section 6.
+
+The conformance vectors in `@synoi/conformance` are the normative test of conformance.
+
+## 10. Reserved for future versions
+
+The following are reserved by name so that independent implementations do not adopt incompatible forms:
+
+- **`sraid/cbor`** - a CBOR + COSE binary profile (Section 3). Reserved as a future additive binary profile only. The v1.0 serialization format is settled as `sraid/json` (see Section 3 decision note, 2026-06-27); `sraid/cbor` is not a candidate for v1.0 and MUST NOT be interpreted as an open question for this version.
+- **routing-prefix layout** - the exact byte layout of the non-normative routing prefix (Section 5).
+- **algorithm agility** - a self-describing (multihash-style) OID form and additional signature suites (Sections 4, 6).
+- **sensitivity concealment** - a commitment-based selective-disclosure scheme that CONCEALS the opaque sensitivity tier itself (Section 7.1). The coarse, opaque tier member and its monotone `max` carry-forward ARE defined in v1.0 (Section 7.1); only the mechanism to hide the level is reserved.
+
+## 11. References
+
+- RFC 2119 - Key words for use in RFCs.
+- RFC 8032 - Edwards-Curve Digital Signature Algorithm (EdDSA), Ed25519.
+- FIPS 204 - Module-Lattice-Based Digital Signature Standard (ML-DSA).
+- RFC 8949 - Concise Binary Object Representation (CBOR).
+- RFC 9052 - CBOR Object Signing and Encryption (COSE): Structures and Process.
+- FIPS 180-4 - Secure Hash Standard (SHA-256).
+
+## Appendix A. Closed design decisions
+
+This appendix records decisions that were implicit in the spec text and have been explicitly closed. It exists so that future readers and implementers do not treat settled questions as still open.
+
+| ID | Date | Decision | Status |
+|---|---|---|---|
+| DD-1 | 2026-06-27 | Serialization format for v1.0 is `sraid/json` (RFC 8785 JCS). `sraid/cbor` is deferred to a post-v1.0 additive binary profile. See Section 3 for rationale. | CLOSED |