Kernel

Purpose and authority boundary

Kernel answers a narrow but consequential question: when two components claim to refer to the same scientific bytes or record, how is that identity reproduced? It owns representation mechanics, not research meaning. Protocol decides what belongs in protocol content; Workflow decides what belongs in a plan; Kernel gives both a deterministic encoding and digest vocabulary.

Authority rule: a parsed digest string or deserialized envelope is only a claim. DigestEnvelope.RehydrateAndVerify returns VerifiedDigestEnvelope only after the caller supplies the expected digest, scope, schema id, and schema version and the implementation reproduces all of them.

Key types and services

• CanonicalJsonValue, CanonicalJsonObject, and CanonicalJsonSerializer form the explicit value tree and serializer. Objects reject duplicate keys and can be frozen recursively.
• ContentDigest accepts only sha256:<64 lowercase hex>; default values fail when read as authority.
• DigestScope closes the base vocabulary to raw bytes, canonical records, protocol content, approval records, provenance events, bundle manifests, and NDJSON streams.
• DigestEnvelope binds algorithm, profile, scope, schema, version, and content before hashing.
• CanonicalTimestamp emits UTC as yyyy-MM-ddTHH:mm:ss.fffffffZ.
• EntityId<TTag>, IIdGenerator, GuidV7IdGenerator, IClock, and SystemClock keep identity and time explicit at record-creation boundaries.
• NdjsonCanonicalizer rejects BOM and carriage returns unless CRLF normalization is explicitly enabled.

Source: NexusScholar.Kernel. The profile correction is recorded in ADR 0017.

Canonical identity pipeline

typed domain content
  → schema-owned ordering and omission rules
  → DigestEnvelope(scope, schema, version, content)
  → nexus-jcs-nfc-v1 UTF-8 bytes, no BOM
  → SHA-256
  → sha256:<lowercase hex>

The profile normalizes strings and property names to NFC, rejects collisions introduced by normalization, sorts object properties ordinally, preserves array order, and renders finite IEEE-754 binary64 numbers using the RFC 8785/ECMAScript thresholds. Negative zero becomes 0. Non-finite values and caller-visible integers or decimals that cannot be represented exactly in the accepted numeric model are rejected; schemas must model wider exact values as strings.

Digest scope is semantic. The same information hashed as raw-artifact-bytes and as canonical-json-record does not establish interchangeable authority. Absolute paths, machine names, runtime identity, serializer defaults, current time, secrets, caches, embeddings, and generated narratives are forbidden from scientific identity unless a narrower accepted contract explicitly makes them authoritative.

Typical developer flow

1. Build a typed canonical object in the owning domain; normalize logically unordered collections there.
2. Select an approved scope and explicit schema id/version.
3. Construct DigestEnvelope and call ComputeDigest().
4. Persist or exchange the envelope bytes and digest together.
5. On read, treat JSON as untrusted; call RehydrateAndVerify with authority selected outside the payload.
6. Pass only the verified wrapper across an authority boundary.

var envelope = new DigestEnvelope(
    DigestScope.CanonicalJsonRecord,
    "nexus.example-record",
    "1.0.0",
    content);
var digest = envelope.ComputeDigest();

Failure and refusal behavior

Kernel fails closed on uppercase or prefix-free digests, unsupported algorithms/scopes, unknown or duplicate envelope fields, null or wrongly typed metadata, wrong profile/schema/version/scope, digest mismatch, tampered nested content, lone Unicode surrogates, post-normalization duplicate properties, non-finite numbers, invalid IDs, BOM-bearing NDJSON, and noncanonical line endings. Transport whitespace and object property order may differ during envelope input, but the reconstructed canonical digest must still match.

Tests and evidence

DeterministicKernelTests cover direct behavior. KernelFixtureTests replay the Kernel conformance pack, including RFC 8785 Appendix B vectors and adversarial rehydration records. Hardening evidence is recorded in HARDENING-01 and HARDENING-02.

Extension points and nonclaims

Domain packages extend Kernel by defining schema-specific canonical codecs and verified wrappers; they should not add ad hoc digest formats or reuse a scope with different semantics. Kernel provides no persistence, signature, encryption, authorization, schema registry, migration, network, UI, or scientific-validity guarantee. The profile is Nexus-specific because NFC preprocessing is not pure RFC 8785. Pre-correction rfc8785-jcs digests are invalid provisional state, not silently migrated compatibility records.