@ixo/domain.md 0.3.0

package/src/constants.ts

@@ -0,0 +1,250 @@
+import packageJson from '../package.json' with { type: 'json' };
+
+/** The published package version; semantic-release sets it at release time. */
+export const PACKAGE_VERSION: string = packageJson.version;
+export const SPEC_VERSION = '1.0.0-rc.3';
+export const SCHEMA_ID = `urn:ixo:domain-md:schema:${SPEC_VERSION}`;
+export const TEMPLATE_SCHEMA_ID = `urn:ixo:domain-md:template-manifest-schema:${SPEC_VERSION}`;
+export const ORACLE_CAPSULE_CONTRACT = 'ixo.earth/oracle-capsule/v0alpha1';
+export const ORACLE_CAPSULE_SCHEMA_ID = 'urn:ixo:domain-md:x-oracle-capsule:manifest:0.1.0';
+export const ORACLE_CAPSULE_SOURCE_LOCK_SCHEMA_ID =
+  'urn:ixo:domain-md:x-oracle-capsule:source-lock:0.1.0';
+export const ORACLE_CAPSULE_MEDIA_TYPE = 'application/vnd.ixo.oracle-capsule+json';
+export const ORACLE_CAPSULE_SOURCE_LOCK_MEDIA_TYPE =
+  'application/vnd.ixo.oracle-capsule.source-lock+json';
+export const ORACLE_CAPSULE_LIMITS = {
+  maxBytes: 1_048_576,
+  maxDepth: 64,
+  maxNodes: 10_000,
+  maxScalarLength: 10_000,
+  maxLockedFiles: 10_000,
+  maxLockedBytes: 67_108_864,
+} as const;
+export const ORACLE_CAPSULE_EXTERNAL_CHECKS = [
+  'oracle-identity-current',
+  'subject-domain-current',
+  'capability-current-and-unrevoked',
+  'trusted-time-available',
+  'private-resource-access-authorized',
+  'human-review-authorized',
+  'runtime-distribution-trusted',
+  'receipt-signer-current-and-unrevoked',
+] as const;
+export const MAX_DOMAIN_BYTES = 1024 * 1024;
+export const MAX_LINKED_BYTES = 2 * 1024 * 1024;
+export const MAX_YAML_DEPTH = 64;
+export const MAX_YAML_NODES = 10_000;
+export const MAX_SCALAR_LENGTH = 10_000;
+export const EXTERNAL_CHECKS = [
+  {
+    code: 'cid-verification',
+    category: 'integrity',
+    reason: 'Resolve external bytes and verify their declared CIDs.',
+  },
+  {
+    code: 'did-iid-resolution',
+    category: 'identity',
+    reason: 'Resolve the current DID/IID state with the configured resolver.',
+  },
+  {
+    code: 'canonical-state-consistency',
+    category: 'identity',
+    reason: 'Compare the document with current fact-scoped canonical state.',
+  },
+  {
+    code: 'capability-revocation',
+    category: 'authorization',
+    reason: 'Verify live delegation and revocation state before acting.',
+  },
+  {
+    code: 'trusted-clock',
+    category: 'time',
+    reason: 'Evaluate time-bound grants against a trusted clock.',
+  },
+  {
+    code: 'chain-anchor',
+    category: 'chain',
+    reason: 'Verify the declared chain anchor and confirmation policy.',
+  },
+  {
+    code: 'constitutional-instrument-cid',
+    category: 'integrity',
+    reason: 'Verify every constitutional instrument against its declared CID and exact bytes.',
+  },
+  {
+    code: 'constitutional-authority-current',
+    category: 'authorization',
+    reason: 'Resolve current adoption, amendment, interpretation, and enforcement authority.',
+  },
+  {
+    code: 'constitutional-effective-status',
+    category: 'time',
+    reason:
+      'Verify effective, suspended, and superseded status against a trusted clock and canonical state.',
+  },
+  {
+    code: 'constitutional-implementation-integrity',
+    category: 'integrity',
+    reason: 'Verify executable governance code and conformance-test identities.',
+  },
+  {
+    code: 'constitutional-enforcement-deployment',
+    category: 'authorization',
+    reason: 'Verify the declared enforcement point is deployed and authorized for this subject.',
+  },
+  {
+    code: 'constitutional-ai-profile-binding',
+    category: 'authorization',
+    reason:
+      'Verify the active agent and model profile are bound to the declared principles and procedures.',
+  },
+] as const;
+
+export const CANONICAL_SECTIONS = [
+  'Overview',
+  'Operating Model',
+  'Authority & Control',
+  'Constitutional Governance',
+  'Services',
+  'Resources',
+  'Rights & Capabilities',
+  'Claims, Evidence & Evaluation',
+  'Linked Entities',
+  'Accounts & Value',
+  'POD, Flows & Agents',
+  'Privacy & Source-of-Truth Boundaries',
+  'Playbooks',
+  "Do's and Don'ts",
+  'Changelog',
+] as const;
+
+export const KNOWN_TOP_LEVEL_KEYS = new Set([
+  'version',
+  'kind',
+  'conformance',
+  'document_revision',
+  'name',
+  'description',
+  'last_updated',
+  'maintainers',
+  'domain',
+  'source_of_truth',
+  'documents',
+  'constitution',
+  'agent_default_mode',
+  'controllers',
+  'services',
+  'resources',
+  'rights',
+  'claims',
+  'linked_entities',
+  'accounts',
+  'pods',
+  'agents',
+  'privacy',
+  'graph_policy',
+  'validation',
+  'critical_do_not',
+  'governance',
+  'protocols',
+  'asset',
+  'deed',
+  'protocol',
+  'investment',
+  'x-oracle-capsule',
+]);
+
+export const CONSTITUTION_STATUSES = [
+  'not_applicable',
+  'draft',
+  'adopted',
+  'in_force',
+  'suspended',
+  'superseded',
+] as const;
+
+export const CONSTITUTION_TYPES = [
+  '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',
+] as const;
+
+export const CONSTITUTIONAL_SUBJECT_TYPES = [
+  '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',
+] as const;
+
+export const CONSTITUTIONAL_ARCHETYPES = [
+  'con:Stewarded',
+  'con:Owned',
+  'con:Managed',
+  'con:Governed',
+  'con:Regulated',
+  'con:Verified',
+  'con:Settled',
+] as const;
+
+export const CONSTITUTION_INSTRUMENT_FUNCTIONS = [
+  'constitutive',
+  'governing',
+  'amending',
+  'interpretive',
+  'executable',
+] as const;
+
+export const CONSTITUTION_EXECUTION_MODES = [
+  'human_interpreted',
+  'machine_assisted',
+  'machine_executable',
+  'hybrid',
+] as const;
+
+export const CONSTITUTION_AI_MODES = [
+  'none',
+  'context_only',
+  'critique_and_revise',
+  'policy_evaluate',
+  'hybrid',
+] as const;

package/src/diff.ts

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+
+import { lint } from './lint.js';
+import type {
+  ChangeClassification,
+  DiffOptions,
+  DiffReport,
+  DomainChange,
+  DomainRecord,
+} from './types.js';
+
+const SECURITY_PREFIXES = [
+  '/controllers',
+  '/rights',
+  '/accounts',
+  '/privacy',
+  '/source_of_truth',
+  '/constitution',
+  '/claims',
+  '/agents',
+  '/agent_default_mode',
+  '/critical_do_not',
+];
+const OPERATIONAL_PREFIXES = [
+  '/services',
+  '/resources',
+  '/linked_entities',
+  '/pods',
+  '/graph_policy',
+  '/documents',
+];
+
+function classify(path: string): ChangeClassification {
+  if (SECURITY_PREFIXES.some((prefix) => path.startsWith(prefix))) return 'security-sensitive';
+  if (OPERATIONAL_PREFIXES.some((prefix) => path.startsWith(prefix))) return 'operational';
+  return path.startsWith('/sections/') ? 'narrative' : 'operational';
+}
+
+function stable(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (typeof value === 'object' && value !== null) {
+    return `{${Object.entries(value as DomainRecord)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, child]) => `${JSON.stringify(key)}:${stable(child)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function compare(before: unknown, after: unknown, path: string, changes: DomainChange[]): void {
+  if (stable(before) === stable(after)) return;
+  if (
+    before &&
+    after &&
+    typeof before === 'object' &&
+    typeof after === 'object' &&
+    !Array.isArray(before) &&
+    !Array.isArray(after)
+  ) {
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of [...keys].sort())
+      compare(
+        (before as DomainRecord)[key],
+        (after as DomainRecord)[key],
+        `${path}/${key}`,
+        changes,
+      );
+    return;
+  }
+  changes.push({ path: path || '/', classification: classify(path), before, after });
+}
+
+function sectionHashes(content: string): DomainRecord {
+  const report = lint(content);
+  return Object.fromEntries(
+    (report.document?.sections ?? []).map((section) => [
+      section.heading,
+      createHash('sha256').update(section.content).digest('hex'),
+    ]),
+  );
+}
+
+export function diffDomains(
+  beforeContent: string,
+  afterContent: string,
+  options: DiffOptions = {},
+): DiffReport {
+  const beforeReport = lint(beforeContent, { sourceName: 'before' });
+  const afterReport = lint(afterContent, { sourceName: 'after' });
+  const changes: DomainChange[] = [];
+  compare(
+    beforeReport.document?.frontmatter ?? {},
+    afterReport.document?.frontmatter ?? {},
+    '',
+    changes,
+  );
+  compare(sectionHashes(beforeContent), sectionHashes(afterContent), '/sections', changes);
+  const conformanceRegression =
+    afterReport.summary.errors > beforeReport.summary.errors ||
+    (beforeReport.ok && !afterReport.ok);
+  const requiresReview = changes.some((change) => change.classification === 'security-sensitive');
+  const regression = conformanceRegression || (options.failOn === 'review' && requiresReview);
+  return {
+    before: beforeReport.summary,
+    after: afterReport.summary,
+    changes,
+    conformanceRegression,
+    requiresReview,
+    regression,
+  };
+}

package/src/export.ts

@@ -0,0 +1,28 @@
+import { lint } from './lint.js';
+import { toSarif } from './sarif.js';
+import type { ExportOptions } from './types.js';
+
+export function exportDomain(content: string, options: ExportOptions): string {
+  const report = lint(
+    content,
+    options.sourceName === undefined ? {} : { sourceName: options.sourceName },
+  );
+  if (options.format === 'sarif') return `${JSON.stringify(toSarif(report), null, 2)}\n`;
+  if (!report.ok || !report.document)
+    throw new Error('Cannot export a JSON model while conformance errors remain.');
+  return `${JSON.stringify(
+    {
+      specVersion: report.specVersion,
+      profile: report.profile,
+      frontmatter: report.document.frontmatter,
+      sections: report.document.sections.map(({ heading, content, location }) => ({
+        heading,
+        content,
+        location,
+      })),
+      note: 'This normalized model is not CID-canonical bytes.',
+    },
+    null,
+    2,
+  )}\n`;
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+export { diffDomains } from './diff.js';
+export { exportDomain } from './export.js';
+export { lint } from './lint.js';
+export { parseDomain } from './parser.js';
+export * from './capsule/index.js';
+export {
+  getOracleCapsuleContract,
+  getOracleCapsuleJcsVectors,
+  getOracleCapsuleSchema,
+  getOracleCapsuleSourceLockSchema,
+  getRules,
+  getSchema,
+  getSchemaSource,
+  getSpecification,
+  getTemplateManifestSchema,
+} from './spec.js';
+export { renderTemplateBundle } from './templates/render.js';
+export { TemplateValidationError } from './templates/errors.js';
+export {
+  CONSTITUTIONAL_ARCHETYPES,
+  CONSTITUTIONAL_SUBJECT_TYPES,
+  CONSTITUTION_AI_MODES,
+  CONSTITUTION_EXECUTION_MODES,
+  CONSTITUTION_INSTRUMENT_FUNCTIONS,
+  CONSTITUTION_STATUSES,
+  CONSTITUTION_TYPES,
+  PACKAGE_VERSION,
+  SPEC_VERSION,
+} from './constants.js';
+export {
+  FileTemplateResolver,
+  HttpsTemplateResolver,
+  IpfsTemplateResolver,
+} from './templates/resolver.js';
+export type * from './types.js';
+export type * from './templates/types.js';

package/src/lint.ts

@@ -0,0 +1,42 @@
+import { EXTERNAL_CHECKS, PACKAGE_VERSION, SPEC_VERSION } from './constants.js';
+import { parseDomain } from './parser.js';
+import { getProfile, inferMode, validateSemantics } from './semantic.js';
+import type { Finding, FindingSummary, LintOptions, LintReport } from './types.js';
+
+function summarize(findings: Finding[]): FindingSummary {
+  return {
+    errors: findings.filter((item) => item.severity === 'error').length,
+    warnings: findings.filter((item) => item.severity === 'warning').length,
+    infos: findings.filter((item) => item.severity === 'info').length,
+  };
+}
+
+export function lint(content: string, options: LintOptions = {}): LintReport {
+  const parsed = parseDomain(content, options);
+  const findings = [...parsed.findings];
+  if (parsed.document)
+    findings.push(...validateSemantics(parsed.document, options.expectedProfile));
+  const summary = summarize(findings);
+  const profile = parsed.document ? getProfile(parsed.document.frontmatter) : null;
+  const externalChecksRequired =
+    profile === 'persisted_draft'
+      ? EXTERNAL_CHECKS.filter((check) => check.code === 'cid-verification')
+      : profile === 'anchored' || profile === 'runtime'
+        ? [...EXTERNAL_CHECKS]
+        : [];
+  const result: LintReport = {
+    tool: '@ixo/domain.md',
+    toolVersion: PACKAGE_VERSION,
+    specVersion: SPEC_VERSION,
+    sourceName: options.sourceName ?? '<memory>',
+    mode: parsed.document ? inferMode(parsed.document.frontmatter) : null,
+    profile,
+    status: summary.errors === 0 ? 'static-pass' : 'fail',
+    ok: summary.errors === 0,
+    summary,
+    findings,
+    externalChecksRequired,
+  };
+  if (parsed.document) result.document = parsed.document;
+  return result;
+}

package/src/parser.ts

@@ -0,0 +1,174 @@
+import type { Heading, Root, YAML as MdastYaml } from 'mdast';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { visit as visitTree } from 'unist-util-visit';
+import { isAlias, parseDocument, visit as visitYaml } from 'yaml';
+
+import {
+  MAX_DOMAIN_BYTES,
+  MAX_SCALAR_LENGTH,
+  MAX_YAML_DEPTH,
+  MAX_YAML_NODES,
+} from './constants.js';
+import type { DomainRecord, DomainSection, Finding, ParseOptions, ParseResult } from './types.js';
+
+const FRONTMATTER = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+
+function finding(code: string, message: string, path = '/'): Finding {
+  return { severity: 'error', code, message, path, location: { line: 1, column: 1 } };
+}
+
+function isRecord(value: unknown): value is DomainRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function nodeText(value: unknown): string {
+  if (!isRecord(value)) return '';
+  if (typeof value.value === 'string') return value.value;
+  return Array.isArray(value.children) ? value.children.map(nodeText).join('') : '';
+}
+
+function parseFrontmatter(source: string, findings: Finding[]): DomainRecord | undefined {
+  const match = FRONTMATTER.exec(source);
+  if (!match?.[1]) {
+    findings.push(
+      finding(
+        'missing-frontmatter',
+        'A domain.md must begin with YAML frontmatter.',
+        '/frontmatter',
+      ),
+    );
+    return undefined;
+  }
+  const yaml = parseDocument(match[1], { prettyErrors: true, uniqueKeys: true, version: '1.2' });
+  if (yaml.errors.length > 0 || yaml.warnings.length > 0) {
+    findings.push(
+      finding(
+        'unsafe-yaml',
+        [...yaml.errors, ...yaml.warnings].map((item) => item.message).join('; '),
+        '/frontmatter',
+      ),
+    );
+    return undefined;
+  }
+  const unsafe = new Set<string>();
+  let nodes = 0;
+  let depth = 0;
+  let scalarTooLong = false;
+  visitYaml(yaml, {
+    Node(_key, node, path) {
+      const candidate = node as { anchor?: string; tag?: string; value?: unknown };
+      nodes += 1;
+      depth = Math.max(depth, path.length + 1);
+      if (typeof candidate.value === 'string' && candidate.value.length > MAX_SCALAR_LENGTH)
+        scalarTooLong = true;
+      if (isAlias(node)) unsafe.add('alias');
+      if (candidate.anchor) unsafe.add('anchor');
+      if (candidate.tag?.startsWith('!')) unsafe.add('custom-tag');
+    },
+    Pair(_key, pair) {
+      const key = pair.key as { value?: unknown } | null;
+      if (key?.value === '<<') unsafe.add('merge-key');
+    },
+  });
+  if (nodes > MAX_YAML_NODES || depth > MAX_YAML_DEPTH || scalarTooLong) {
+    findings.push(
+      finding('unsafe-yaml', 'YAML exceeds the node, depth, or scalar limits.', '/frontmatter'),
+    );
+    return undefined;
+  }
+  if (unsafe.size > 0) {
+    findings.push(
+      finding(
+        'unsafe-yaml',
+        `Forbidden YAML feature(s): ${[...unsafe].sort().join(', ')}.`,
+        '/frontmatter',
+      ),
+    );
+    return undefined;
+  }
+  let value: unknown;
+  try {
+    value = yaml.toJS({ maxAliasCount: 0 });
+  } catch (error) {
+    findings.push(
+      finding(
+        'unsafe-yaml',
+        error instanceof Error ? error.message : String(error),
+        '/frontmatter',
+      ),
+    );
+    return undefined;
+  }
+  if (!isRecord(value)) {
+    findings.push(
+      finding('frontmatter-shape', 'YAML frontmatter must be a mapping.', '/frontmatter'),
+    );
+    return undefined;
+  }
+  return value;
+}
+
+function extractSections(tree: Root, source: string): DomainSection[] {
+  const headings: Heading[] = [];
+  visitTree(tree, 'heading', (node: Heading) => {
+    if (node.depth === 2) headings.push(node);
+  });
+  return headings.map((heading, index) => {
+    const next = headings[index + 1];
+    const start = heading.position?.start.offset ?? 0;
+    const end = next?.position?.start.offset ?? source.length;
+    const title = nodeText(heading);
+    return {
+      heading: title,
+      content: source.slice(start, end).trimEnd(),
+      location: {
+        line: heading.position?.start.line ?? 1,
+        column: heading.position?.start.column ?? 1,
+        ...(heading.position?.end.line === undefined ? {} : { endLine: heading.position.end.line }),
+        ...(heading.position?.end.column === undefined
+          ? {}
+          : { endColumn: heading.position.end.column }),
+      },
+    };
+  });
+}
+
+export function parseDomain(content: string, options: ParseOptions = {}): ParseResult {
+  const sourceName = options.sourceName ?? '<memory>';
+  const findings: Finding[] = [];
+  const maxBytes = options.maxBytes ?? MAX_DOMAIN_BYTES;
+  if (Buffer.byteLength(content, 'utf8') > maxBytes) {
+    return { ok: false, findings: [finding('file-too-large', `Input exceeds ${maxBytes} bytes.`)] };
+  }
+  if (content.charCodeAt(0) === 0xfeff) {
+    findings.push(finding('encoding', 'UTF-8 byte-order marks are forbidden.'));
+  }
+  const frontmatter = parseFrontmatter(content, findings);
+  if (!frontmatter) return { ok: false, findings };
+
+  const tree = unified().use(remarkParse).use(remarkFrontmatter, ['yaml']).parse(content);
+  const yamlNodes: MdastYaml[] = [];
+  visitTree(tree, 'yaml', (node: MdastYaml) => yamlNodes.push(node));
+  const frontmatterLength = FRONTMATTER.exec(content)?.[0].length ?? 0;
+  const additionalFence = /(?:^|\r?\n)---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/.test(
+    content.slice(frontmatterLength),
+  );
+  if (yamlNodes.length !== 1 || tree.children[0]?.type !== 'yaml' || additionalFence) {
+    findings.push(
+      finding(
+        'frontmatter-fence',
+        'Exactly one YAML frontmatter block must appear at the start.',
+        '/frontmatter',
+      ),
+    );
+  }
+  const document = {
+    frontmatter,
+    sections: extractSections(tree, content),
+    sourceName,
+    raw: content,
+  };
+  return { ok: findings.every((item) => item.severity !== 'error'), document, findings };
+}

package/src/sarif.ts

@@ -0,0 +1,49 @@
+import type { Finding, LintReport } from './types.js';
+
+function level(finding: Finding): 'error' | 'warning' | 'note' {
+  return finding.severity === 'info' ? 'note' : finding.severity;
+}
+
+export function toSarif(report: LintReport): Record<string, unknown> {
+  const ruleMap = new Map(report.findings.map((finding) => [finding.code, finding]));
+  return {
+    version: '2.1.0',
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: report.tool,
+            version: report.toolVersion,
+            rules: [...ruleMap.entries()].map(([id, finding]) => ({
+              id,
+              shortDescription: { text: finding.message },
+            })),
+          },
+        },
+        results: report.findings.map((finding) => ({
+          ruleId: finding.code,
+          level: level(finding),
+          message: { text: finding.message },
+          locations: [
+            {
+              physicalLocation: {
+                artifactLocation: { uri: report.sourceName },
+                region: {
+                  startLine: finding.location.line,
+                  startColumn: finding.location.column,
+                  ...(finding.location.endLine === undefined
+                    ? {}
+                    : { endLine: finding.location.endLine }),
+                  ...(finding.location.endColumn === undefined
+                    ? {}
+                    : { endColumn: finding.location.endColumn }),
+                },
+              },
+            },
+          ],
+        })),
+      },
+    ],
+  };
+}