oracle-codec

This package implements the Kernel V5 kernel-canonical-value-v1 byte codec and its framing primitives. The source of authority is the versioned Kernel V5 grammar maintained by the codec owner.

It is a byte codec. It is not a Kernel client, graph API, command encoder, storage API, or application SDK.

Contract

The value model is closed and explicit. Signed and unsigned integers are different variants and both use bigint. A JavaScript number is never accepted as a Kernel 64-bit integer.

The encoder:

• emits the exact kernel-canonical-value-v1 tags and big-endian framing;
• sorts map entries by their UTF-8 key bytes;
• rejects duplicate canonical keys;
• preserves sequence order;
• rejects malformed JavaScript surrogate input instead of replacing it;
• performs no Unicode normalization, case folding, trimming, locale sorting, JSON serialization, or implicit conversion.

Map keys must contain 1 through 256 valid UTF-8 bytes. The generic codec does not apply the separate Kernel identifier NFC rule or the V5 object-schema ASCII field-name rule. It never normalizes a key. A schema that treats a sequence as a set remains responsible for sorting canonical element encodings bytewise and rejecting duplicates before it calls this primitive codec.

The decoder consumes exactly one value. It rejects unknown tags, invalid UTF-8, duplicate or non-increasing map keys, truncation, trailing bytes, oversized collections, depth overflow, and oversized input. It does not turn noncanonical bytes into a normalized value.

The V1 limits are:

• canonical value input or output: 1,048,576 bytes;
• collection entries: 16,384 per sequence or map;
• nesting depth: 64, with the enclosing value at depth 0;
• map key: 1 through 256 UTF-8 bytes.

Floating-point values are not part of the type model. JSON and RFC 8785/JCS are not used to encode canonical values.

Install and pin

Consumers must use an exact package version:

{
  "dependencies": {
    "oracle-codec": "0.1.0"
  }
}

Do not use a floating range for Kernel canonical-byte dependencies.

Examples

Encode an unsigned scalar:

import { encodeCanonicalValue } from "oracle-codec";

const bytes = encodeCanonicalValue({ type: "unsigned", value: 5n });
// 03 0000000000000005

Encode a map. The input array can be out of order. An array is used so that a duplicate key remains detectable.

import {
  type CanonicalValue,
  encodeCanonicalValue,
} from "oracle-codec";

const value: CanonicalValue = {
  type: "map",
  entries: [
    { key: "kind", value: { type: "utf8", value: "example" } },
    { key: "id", value: { type: "utf8", value: "item-1" } },
  ],
};

const canonical = encodeCanonicalValue(value); // `id` is emitted before `kind`.

Decode one strict value:

import { decodeCanonicalValue } from "oracle-codec";

const value = decodeCanonicalValue(
  Uint8Array.of(4, 255, 255, 255, 255, 255, 255, 255, 255),
);
// { type: "signed", value: -1n }

Frame an already-computed SHA-256 digest:

import { digestPair } from "oracle-codec";

const digest = new Uint8Array(32); // raw digest bytes, not textual hex
const framed = digestPair(digest);
// lp32(utf8("sha256")) || u32be(32) || digest

digestPair does not hash its input. DigestProvider is the small caller-side contract for a provider whose algorithm is exactly sha256. The core codec does not select Node crypto, Web Crypto, or another hashing implementation.

Runtime support

The checked package has no runtime dependencies. Its core uses standard Uint8Array, bigint, TextEncoder, and strict TextDecoder facilities. CI and the installed-tarball smoke test use Node 24. Local conformance also runs on Node 22.14. Modern browsers that provide those standards are compatible with the runtime-neutral core; browser bundler integration is not certified by this package test suite.

Versioning

The npm package uses independent plain semver. npm semver does not redefine the Kernel grammar. Any canonical-byte semantic change requires a new Kernel codec identity or profile. It must not appear silently in a package patch.

The complete cross-language corpus remains private maintainer conformance evidence and is not part of the npm tarball.