@ixo/domain.md 0.3.0

package/dist/spec.js

@@ -0,0 +1,23 @@
+import {
+  getOracleCapsuleContract,
+  getOracleCapsuleJcsVectors,
+  getOracleCapsuleSchema,
+  getOracleCapsuleSourceLockSchema,
+  getRules,
+  getSchema,
+  getSchemaSource,
+  getSpecification,
+  getTemplateManifestSchema
+} from "./chunk-T3STBWXP.js";
+export {
+  getOracleCapsuleContract,
+  getOracleCapsuleJcsVectors,
+  getOracleCapsuleSchema,
+  getOracleCapsuleSourceLockSchema,
+  getRules,
+  getSchema,
+  getSchemaSource,
+  getSpecification,
+  getTemplateManifestSchema
+};
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/templates/index.d.ts

@@ -0,0 +1,7 @@
+import { T as TemplateManifest } from '../resolver-B3mwnjJq.js';
+export { F as FileTemplateResolver, H as HttpsTemplateResolver, I as IpfsTemplateResolver, R as RenderTemplateRequest, a as RenderTemplateResult, b as RenderedFile, c as ResolvedTemplateResource, d as TemplateBundleRecord, e as TemplateDerivedType, f as TemplateFileRecord, g as TemplateResolver, h as TemplateResolverContext, i as TemplateRole, j as TemplateValidationError, r as relativeTemplateUri, k as renderTemplateBundle, v as validateHttpsTarget } from '../resolver-B3mwnjJq.js';
+import '../cli-KcUIQEiE.js';
+
+declare function parseTemplateManifest(bytes: Uint8Array): TemplateManifest;
+
+export { TemplateManifest, parseTemplateManifest };

package/dist/templates/index.js

@@ -0,0 +1,24 @@
+import {
+  FileTemplateResolver,
+  HttpsTemplateResolver,
+  IpfsTemplateResolver,
+  TemplateValidationError,
+  parseTemplateManifest,
+  relativeTemplateUri,
+  renderTemplateBundle,
+  validateHttpsTarget
+} from "../chunk-BYBC2TSS.js";
+import "../chunk-T3STBWXP.js";
+import "../chunk-XDIWMZVF.js";
+import "../chunk-G7PZJYAJ.js";
+export {
+  FileTemplateResolver,
+  HttpsTemplateResolver,
+  IpfsTemplateResolver,
+  TemplateValidationError,
+  parseTemplateManifest,
+  relativeTemplateUri,
+  renderTemplateBundle,
+  validateHttpsTarget
+};
+//# sourceMappingURL=index.js.map

package/dist/templates/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/workers-Dr8B8a2O.d.ts

@@ -0,0 +1,19 @@
+import { r as LintOptions, s as LintReport, P as ParseOptions, t as ParseResult } from './cli-KcUIQEiE.js';
+import './capsule/index.js';
+
+declare function lint(content: string, options?: LintOptions): LintReport;
+
+declare function parseDomain(content: string, options?: ParseOptions): ParseResult;
+
+/** The published package version; semantic-release sets it at release time. */
+declare const PACKAGE_VERSION: string;
+declare const SPEC_VERSION = "1.0.0-rc.3";
+declare const CONSTITUTION_STATUSES: readonly ["not_applicable", "draft", "adopted", "in_force", "suspended", "superseded"];
+declare const CONSTITUTION_TYPES: readonly ["con:OperationalConstitution", "con:PersonalConstitution", "con:AssetConstitution", "con:FinancialSubjectConstitution", "con:WorkConstitution", "con:ServiceConstitution", "con:OracleConstitution", "con:InformationSubjectConstitution", "con:PlaceConstitution", "con:BiologicalSubjectConstitution", "con:NetworkConstitution", "con:StateConstitution", "con:InternationalOrganizationConstitution", "con:OrganizationalConstitution", "con:CorporateConstitution", "con:TrustConstitution", "con:CooperativeConstitution", "con:PartnershipConstitution", "con:FoundationConstitution", "con:PublicBodyConstitution", "con:ProjectConstitution", "con:ProtocolConstitution", "con:DAOConstitution", "con:AgenticConstitution", "con:SchemeConstitution"];
+declare const CONSTITUTIONAL_SUBJECT_TYPES: readonly ["con:Person", "con:Organization", "con:Asset", "con:Commodity", "con:FinancialInstrument", "con:PropertyRight", "con:Agreement", "con:Deed", "con:Project", "con:Work", "con:Protocol", "con:Service", "con:Oracle", "con:Claim", "con:Credential", "con:Evidence", "con:Decision", "con:Outcome", "con:Place", "con:BiologicalEntity", "con:Network", "con:AgenticTwin"];
+declare const CONSTITUTIONAL_ARCHETYPES: readonly ["con:Stewarded", "con:Owned", "con:Managed", "con:Governed", "con:Regulated", "con:Verified", "con:Settled"];
+declare const CONSTITUTION_INSTRUMENT_FUNCTIONS: readonly ["constitutive", "governing", "amending", "interpretive", "executable"];
+declare const CONSTITUTION_EXECUTION_MODES: readonly ["human_interpreted", "machine_assisted", "machine_executable", "hybrid"];
+declare const CONSTITUTION_AI_MODES: readonly ["none", "context_only", "critique_and_revise", "policy_evaluate", "hybrid"];
+
+export { CONSTITUTIONAL_ARCHETYPES as C, PACKAGE_VERSION as P, SPEC_VERSION as S, CONSTITUTIONAL_SUBJECT_TYPES as a, CONSTITUTION_AI_MODES as b, CONSTITUTION_EXECUTION_MODES as c, CONSTITUTION_INSTRUMENT_FUNCTIONS as d, CONSTITUTION_STATUSES as e, CONSTITUTION_TYPES as f, lint as l, parseDomain as p };

package/dist/workers.d.ts

@@ -0,0 +1,3 @@
+export { P as PACKAGE_VERSION, S as SPEC_VERSION, l as lint, p as parseDomain } from './workers-Dr8B8a2O.js';
+export { CapsuleCanonicalizationError, CapsuleExternalCheck, CapsuleExternalCheckCategory, CapsuleValidationOptions, CapsuleValidationReport, JcsGoldenVector, JsonPrimitive, JsonValue, StrictJsonDocument, StrictJsonOptions, StrictJsonResult, canonicalizeCapsuleJson, capsuleJcsSha256, oracleCapsuleReleaseDigest, oracleCapsuleReleaseProjection, parseCapsuleJson, validateOracleCapsule } from './capsule/index.js';
+export { C as ChangeClassification, c as ConformanceProfile, d as ConstitutionDeclaration, e as ConstitutionStatus, f as ConstitutionalAI, g as ConstitutionalExecution, h as ConstitutionalGovernance, i as ConstitutionalInstrument, j as ConstitutionalInstrumentFunction, k as ConstitutionalSubjectProfile, a as DiffOptions, b as DiffReport, l as DomainChange, m as DomainDocument, n as DomainMode, D as DomainRecord, o as DomainSection, E as ExportOptions, p as ExternalCheck, F as Finding, q as FindingSummary, L as LegalEffect, r as LintOptions, s as LintReport, P as ParseOptions, t as ParseResult, S as Severity, u as SourceLocation } from './cli-KcUIQEiE.js';

package/dist/workers.js

@@ -0,0 +1,31 @@
+import {
+  CapsuleCanonicalizationError,
+  canonicalizeCapsuleJson,
+  capsuleJcsSha256,
+  oracleCapsuleReleaseDigest,
+  oracleCapsuleReleaseProjection,
+  parseCapsuleJson,
+  validateOracleCapsule
+} from "./chunk-W7MRQP7I.js";
+import {
+  lint,
+  parseDomain
+} from "./chunk-XDIWMZVF.js";
+import {
+  PACKAGE_VERSION,
+  SPEC_VERSION
+} from "./chunk-G7PZJYAJ.js";
+export {
+  CapsuleCanonicalizationError,
+  PACKAGE_VERSION,
+  SPEC_VERSION,
+  canonicalizeCapsuleJson,
+  capsuleJcsSha256,
+  lint,
+  oracleCapsuleReleaseDigest,
+  oracleCapsuleReleaseProjection,
+  parseCapsuleJson,
+  parseDomain,
+  validateOracleCapsule
+};
+//# sourceMappingURL=workers.js.map

package/dist/workers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@ixo/domain.md",
+  "version": "0.3.0",
+  "description": "Authority-aware domain.md specification, validator, authoring library, and CLI",
+  "license": "Apache-2.0",
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ixoworld/domain.md.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/ixoworld/domain.md/issues"
+  },
+  "homepage": "https://github.com/ixoworld/domain.md#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "domain.md",
+    "ixo",
+    "ai-agents",
+    "did",
+    "governance",
+    "validation",
+    "oracle-capsule",
+    "rfc8785"
+  ],
+  "bin": {
+    "domain.md": "./dist/cli.js",
+    "domainmd": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./spec": {
+      "types": "./dist/spec.d.ts",
+      "import": "./dist/spec.js"
+    },
+    "./templates": {
+      "types": "./dist/templates/index.d.ts",
+      "import": "./dist/templates/index.js"
+    },
+    "./capsule": {
+      "types": "./dist/capsule/index.d.ts",
+      "import": "./dist/capsule/index.js"
+    },
+    "./workers": {
+      "types": "./src/workers.ts",
+      "import": "./src/workers.ts"
+    }
+  },
+  "files": [
+    "assets",
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test tsup.config.ts vitest.config.ts",
+    "package:check": "npm pack --dry-run --json"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "citty": "0.2.2",
+    "ipaddr.js": "2.4.0",
+    "multiformats": "14.0.4",
+    "remark-frontmatter": "5.0.0",
+    "remark-parse": "11.0.0",
+    "unified": "11.0.5",
+    "unist-util-visit": "5.1.0",
+    "yaml": "2.9.0"
+  },
+  "devDependencies": {
+    "@types/mdast": "4.0.4",
+    "@vitest/coverage-v8": "4.1.10",
+    "tsup": "8.5.1",
+    "vitest": "4.1.10"
+  }
+}

package/src/capsule/canonical.ts

@@ -0,0 +1,74 @@
+import { createHash } from 'node:crypto';
+
+import type { JsonValue } from './types.js';
+
+export class CapsuleCanonicalizationError extends Error {
+  readonly code = 'capsule-canonicalization';
+}
+
+function canonical(value: unknown, path: string): string {
+  if (value === null) return 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'string') {
+    for (let index = 0; index < value.length; index += 1) {
+      const code = value.charCodeAt(index);
+      if (code >= 0xd800 && code <= 0xdbff) {
+        const low = value.charCodeAt(index + 1);
+        if (!Number.isInteger(low) || low < 0xdc00 || low > 0xdfff)
+          throw new CapsuleCanonicalizationError(`Lone high surrogate at ${path}.`);
+        index += 1;
+      } else if (code >= 0xdc00 && code <= 0xdfff) {
+        throw new CapsuleCanonicalizationError(`Lone low surrogate at ${path}.`);
+      }
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value))
+      throw new CapsuleCanonicalizationError(`Non-finite number at ${path}.`);
+    if (Number.isInteger(value) && !Number.isSafeInteger(value))
+      throw new CapsuleCanonicalizationError(`Unsafe integer at ${path}.`);
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((child, index) => canonical(child, `${path}/${index}`)).join(',')}]`;
+  }
+  if (typeof value === 'object' && value !== undefined) {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record)
+      .sort()
+      .map((key) => `${canonical(key, path)}:${canonical(record[key], `${path}/${key}`)}`)
+      .join(',')}}`;
+  }
+  throw new CapsuleCanonicalizationError(`Unsupported JSON value at ${path}.`);
+}
+
+/** RFC 8785 JCS serialization for already parsed I-JSON-compatible values. */
+export function canonicalizeCapsuleJson(value: JsonValue): string {
+  return canonical(value, '/');
+}
+
+export function capsuleJcsSha256(value: JsonValue): string {
+  return createHash('sha256').update(canonicalizeCapsuleJson(value), 'utf8').digest('hex');
+}
+
+/**
+ * Release digests omit only metadata.release_digest, the one self-referential
+ * field. Exact fetched-byte SHA/CID verification remains a separate operation.
+ */
+export function oracleCapsuleReleaseProjection(value: JsonValue): JsonValue {
+  if (typeof value !== 'object' || value === null || Array.isArray(value))
+    throw new CapsuleCanonicalizationError('A capsule release must be a JSON object.');
+  const root = structuredClone(value) as Record<string, JsonValue>;
+  const metadata = root.metadata;
+  if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata))
+    throw new CapsuleCanonicalizationError('A capsule release must contain metadata.');
+  const projectedMetadata = { ...metadata } as Record<string, JsonValue>;
+  delete projectedMetadata.release_digest;
+  root.metadata = projectedMetadata;
+  return root;
+}
+
+export function oracleCapsuleReleaseDigest(value: JsonValue): string {
+  return capsuleJcsSha256(oracleCapsuleReleaseProjection(value));
+}

package/src/capsule/index.ts

@@ -0,0 +1,10 @@
+export {
+  canonicalizeCapsuleJson,
+  CapsuleCanonicalizationError,
+  capsuleJcsSha256,
+  oracleCapsuleReleaseDigest,
+  oracleCapsuleReleaseProjection,
+} from './canonical.js';
+export { parseCapsuleJson } from './json.js';
+export { validateOracleCapsule } from './validate.js';
+export type * from './types.js';

package/src/capsule/json.ts

@@ -0,0 +1,373 @@
+import { ORACLE_CAPSULE_LIMITS } from '../constants.js';
+import type { Finding, SourceLocation } from '../types.js';
+import type {
+  JsonValue,
+  StrictJsonDocument,
+  StrictJsonOptions,
+  StrictJsonResult,
+} from './types.js';
+
+class JsonFailure extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly path: string,
+    readonly offset: number,
+  ) {
+    super(message);
+  }
+}
+
+function pointerSegment(value: string): string {
+  return value.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+
+function decodeInput(input: string | Uint8Array): string {
+  if (typeof input === 'string') return input;
+  if (input[0] === 0xef && input[1] === 0xbb && input[2] === 0xbf)
+    throw new JsonFailure('capsule-encoding', 'UTF-8 byte-order marks are forbidden.', '/', 0);
+  try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(input);
+  } catch {
+    throw new JsonFailure('capsule-encoding', 'Input must be valid UTF-8.', '/', 0);
+  }
+}
+
+class StrictJsonParser {
+  private offset = 0;
+  private nodes = 0;
+  private readonly lineStarts = [0];
+  readonly locations = new Map<string, SourceLocation>();
+
+  constructor(
+    private readonly source: string,
+    private readonly options: Required<
+      Pick<StrictJsonOptions, 'maxDepth' | 'maxNodes' | 'maxScalarLength'>
+    >,
+  ) {
+    for (let index = 0; index < source.length; index += 1) {
+      if (source.charCodeAt(index) === 0x0a) this.lineStarts.push(index + 1);
+    }
+  }
+
+  parse(): JsonValue {
+    this.skipWhitespace();
+    const value = this.parseValue('/', 0);
+    this.skipWhitespace();
+    if (this.offset !== this.source.length)
+      this.fail('capsule-json-syntax', 'Unexpected trailing content.', '/');
+    return value;
+  }
+
+  private location(offset: number): SourceLocation {
+    let low = 0;
+    let high = this.lineStarts.length;
+    while (low + 1 < high) {
+      const middle = Math.floor((low + high) / 2);
+      if ((this.lineStarts[middle] ?? 0) <= offset) low = middle;
+      else high = middle;
+    }
+    return { line: low + 1, column: offset - (this.lineStarts[low] ?? 0) + 1 };
+  }
+
+  failureLocation(offset: number): SourceLocation {
+    return this.location(offset);
+  }
+
+  private fail(code: string, message: string, path: string, offset = this.offset): never {
+    throw new JsonFailure(code, message, path, offset);
+  }
+
+  private node(path: string, depth: number): void {
+    if (depth > this.options.maxDepth)
+      this.fail('capsule-limit', `JSON exceeds maximum depth ${this.options.maxDepth}.`, path);
+    this.nodes += 1;
+    if (this.nodes > this.options.maxNodes)
+      this.fail('capsule-limit', `JSON exceeds maximum node count ${this.options.maxNodes}.`, path);
+    this.locations.set(path, this.location(this.offset));
+  }
+
+  private skipWhitespace(): void {
+    while (/[\t\n\r ]/.test(this.source[this.offset] ?? '')) this.offset += 1;
+  }
+
+  private parseValue(path: string, depth: number): JsonValue {
+    this.node(path, depth);
+    const character = this.source[this.offset];
+    if (character === '{') return this.parseObject(path, depth);
+    if (character === '[') return this.parseArray(path, depth);
+    if (character === '"') return this.parseString(path);
+    if (character === '-' || (character !== undefined && /[0-9]/.test(character)))
+      return this.parseNumber(path);
+    if (this.source.startsWith('true', this.offset)) {
+      this.offset += 4;
+      return true;
+    }
+    if (this.source.startsWith('false', this.offset)) {
+      this.offset += 5;
+      return false;
+    }
+    if (this.source.startsWith('null', this.offset)) {
+      this.offset += 4;
+      return null;
+    }
+    return this.fail('capsule-json-syntax', 'Expected a JSON value.', path);
+  }
+
+  private parseObject(path: string, depth: number): { [key: string]: JsonValue } {
+    const result: { [key: string]: JsonValue } = {};
+    const seen = new Set<string>();
+    this.offset += 1;
+    this.skipWhitespace();
+    if (this.source[this.offset] === '}') {
+      this.offset += 1;
+      return result;
+    }
+    while (true) {
+      if (this.source[this.offset] !== '"')
+        this.fail('capsule-json-syntax', 'Object names must be JSON strings.', path);
+      const keyOffset = this.offset;
+      const key = this.parseString(path);
+      const childPath = path === '/' ? `/${pointerSegment(key)}` : `${path}/${pointerSegment(key)}`;
+      if (seen.has(key))
+        this.fail(
+          'capsule-duplicate-key',
+          `Duplicate object name ${JSON.stringify(key)}.`,
+          childPath,
+          keyOffset,
+        );
+      seen.add(key);
+      this.skipWhitespace();
+      if (this.source[this.offset] !== ':')
+        this.fail('capsule-json-syntax', 'Expected a colon after the object name.', childPath);
+      this.offset += 1;
+      this.skipWhitespace();
+      result[key] = this.parseValue(childPath, depth + 1);
+      this.skipWhitespace();
+      const separator = this.source[this.offset];
+      if (separator === '}') {
+        this.offset += 1;
+        return result;
+      }
+      if (separator !== ',')
+        this.fail('capsule-json-syntax', 'Expected a comma or closing brace.', path);
+      this.offset += 1;
+      this.skipWhitespace();
+    }
+  }
+
+  private parseArray(path: string, depth: number): JsonValue[] {
+    const result: JsonValue[] = [];
+    this.offset += 1;
+    this.skipWhitespace();
+    if (this.source[this.offset] === ']') {
+      this.offset += 1;
+      return result;
+    }
+    while (true) {
+      const childPath = path === '/' ? `/${result.length}` : `${path}/${result.length}`;
+      result.push(this.parseValue(childPath, depth + 1));
+      this.skipWhitespace();
+      const separator = this.source[this.offset];
+      if (separator === ']') {
+        this.offset += 1;
+        return result;
+      }
+      if (separator !== ',')
+        this.fail('capsule-json-syntax', 'Expected a comma or closing bracket.', path);
+      this.offset += 1;
+      this.skipWhitespace();
+    }
+  }
+
+  private parseString(path: string): string {
+    this.offset += 1;
+    let value = '';
+    while (this.offset < this.source.length) {
+      const code = this.source.charCodeAt(this.offset);
+      if (code === 0x22) {
+        this.offset += 1;
+        if (value.length > this.options.maxScalarLength)
+          this.fail(
+            'capsule-limit',
+            `String exceeds maximum length ${this.options.maxScalarLength}.`,
+            path,
+          );
+        return value;
+      }
+      if (code < 0x20)
+        this.fail('capsule-json-syntax', 'Unescaped control character in string.', path);
+      if (code === 0x5c) {
+        value += this.parseEscape(path);
+        continue;
+      }
+      if (code >= 0xd800 && code <= 0xdbff) {
+        const low = this.source.charCodeAt(this.offset + 1);
+        if (!Number.isInteger(low) || low < 0xdc00 || low > 0xdfff)
+          this.fail('capsule-unicode', 'Lone high surrogate is not I-JSON compatible.', path);
+        value += this.source.slice(this.offset, this.offset + 2);
+        this.offset += 2;
+        continue;
+      }
+      if (code >= 0xdc00 && code <= 0xdfff)
+        this.fail('capsule-unicode', 'Lone low surrogate is not I-JSON compatible.', path);
+      value += this.source[this.offset] ?? '';
+      this.offset += 1;
+    }
+    return this.fail('capsule-json-syntax', 'Unterminated JSON string.', path);
+  }
+
+  private parseEscape(path: string): string {
+    this.offset += 1;
+    const escape = this.source[this.offset];
+    const simple: Record<string, string> = {
+      '"': '"',
+      '\\': '\\',
+      '/': '/',
+      b: '\b',
+      f: '\f',
+      n: '\n',
+      r: '\r',
+      t: '\t',
+    };
+    if (escape !== undefined && escape in simple) {
+      this.offset += 1;
+      return simple[escape] ?? '';
+    }
+    if (escape !== 'u') return this.fail('capsule-json-syntax', 'Invalid JSON escape.', path);
+    const first = this.readUnicodeEscape(path);
+    if (first >= 0xd800 && first <= 0xdbff) {
+      if (this.source.slice(this.offset, this.offset + 2) !== '\\u')
+        return this.fail(
+          'capsule-unicode',
+          'Escaped high surrogate must be followed by a low surrogate.',
+          path,
+        );
+      const second = this.readUnicodeEscape(path);
+      if (second < 0xdc00 || second > 0xdfff)
+        return this.fail(
+          'capsule-unicode',
+          'Escaped high surrogate must be followed by a low surrogate.',
+          path,
+        );
+      return String.fromCharCode(first, second);
+    }
+    if (first >= 0xdc00 && first <= 0xdfff)
+      return this.fail('capsule-unicode', 'Lone escaped low surrogate is forbidden.', path);
+    return String.fromCharCode(first);
+  }
+
+  private readUnicodeEscape(path: string): number {
+    const digitsAt =
+      this.source[this.offset] === 'u'
+        ? this.offset + 1
+        : this.source.slice(this.offset, this.offset + 2) === '\\u'
+          ? this.offset + 2
+          : -1;
+    if (digitsAt < 0) return this.fail('capsule-json-syntax', 'Invalid Unicode escape.', path);
+    const hex = this.source.slice(digitsAt, digitsAt + 4);
+    if (!/^[0-9a-fA-F]{4}$/.test(hex))
+      return this.fail(
+        'capsule-json-syntax',
+        'Unicode escapes require four hexadecimal digits.',
+        path,
+      );
+    this.offset = digitsAt + 4;
+    return Number.parseInt(hex, 16);
+  }
+
+  private parseNumber(path: string): number {
+    const remaining = this.source.slice(this.offset);
+    const match = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(remaining);
+    if (!match) return this.fail('capsule-json-syntax', 'Invalid JSON number.', path);
+    const token = match[0];
+    const following = remaining[token.length];
+    if (following !== undefined && !/[\t\n\r ,\]}]/.test(following))
+      return this.fail('capsule-json-syntax', 'Invalid character after JSON number.', path);
+    this.offset += token.length;
+    const value = Number(token);
+    if (!Number.isFinite(value))
+      return this.fail('capsule-number', 'Non-finite numbers are not I-JSON compatible.', path);
+    if (Number.isInteger(value) && !Number.isSafeInteger(value))
+      return this.fail(
+        'capsule-number',
+        'Integers must be within the interoperable safe-integer range.',
+        path,
+      );
+    return value;
+  }
+}
+
+function finding(error: JsonFailure, location: SourceLocation): Finding {
+  return {
+    severity: 'error',
+    code: error.code,
+    message: error.message,
+    path: error.path,
+    location,
+  };
+}
+
+export function parseCapsuleJson(
+  input: string | Uint8Array,
+  options: StrictJsonOptions = {},
+): StrictJsonResult {
+  const sourceName = options.sourceName ?? '<memory>';
+  let source: string;
+  try {
+    source = decodeInput(input);
+  } catch (error) {
+    const failure = error as JsonFailure;
+    return { ok: false, findings: [finding(failure, { line: 1, column: 1 })] };
+  }
+  const maxBytes = options.maxBytes ?? ORACLE_CAPSULE_LIMITS.maxBytes;
+  if (Buffer.byteLength(source, 'utf8') > maxBytes) {
+    return {
+      ok: false,
+      findings: [
+        {
+          severity: 'error',
+          code: 'capsule-file-too-large',
+          message: `Input exceeds ${maxBytes} bytes.`,
+          path: '/',
+          location: { line: 1, column: 1 },
+        },
+      ],
+    };
+  }
+  if (source.charCodeAt(0) === 0xfeff) {
+    return {
+      ok: false,
+      findings: [
+        {
+          severity: 'error',
+          code: 'capsule-encoding',
+          message: 'UTF-8 byte-order marks are forbidden.',
+          path: '/',
+          location: { line: 1, column: 1 },
+        },
+      ],
+    };
+  }
+  const parser = new StrictJsonParser(source, {
+    maxDepth: options.maxDepth ?? ORACLE_CAPSULE_LIMITS.maxDepth,
+    maxNodes: options.maxNodes ?? ORACLE_CAPSULE_LIMITS.maxNodes,
+    maxScalarLength: options.maxScalarLength ?? ORACLE_CAPSULE_LIMITS.maxScalarLength,
+  });
+  try {
+    const value = parser.parse();
+    const document: StrictJsonDocument = {
+      value,
+      raw: source,
+      sourceName,
+      locations: parser.locations,
+    };
+    return { ok: true, document, findings: [] };
+  } catch (error) {
+    const failure =
+      error instanceof JsonFailure
+        ? error
+        : new JsonFailure('capsule-json-syntax', String(error), '/', 0);
+    return { ok: false, findings: [finding(failure, parser.failureLocation(failure.offset))] };
+  }
+}