@fides-anima/fpp-protocol-core 1.0.2

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@fides-anima/fpp-protocol-core",
+  "version": "1.0.2",
+  "description": "Shared versioned schemas and cryptographic contracts for the Freedom Preserving Protocol",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "ovrsr",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ovrsr/freedom-preserving-protocol.git",
+    "directory": "packages/protocol-core"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "constitution.json",
+    "constitution.yaml",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit --declaration false --declarationMap false",
+    "test": "tsx --test src/**/*.test.ts"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.1.0",
+    "@noble/hashes": "^1.4.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=22.19"
+  },
+  "homepage": "https://github.com/ovrsr/freedom-preserving-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/ovrsr/freedom-preserving-protocol/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adoption-disclosure.ts

@@ -0,0 +1,120 @@
+/**
+ * AdoptionDisclosure — peer-facing summary of local adoption stance.
+ *
+ * Assurance classes are capped by enforcement grade. Prompt-only and none
+ * cannot elevate to peer-advertisable. Aligns with EVIDENCE_SEMANTICS §7.
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import {
+  ADOPTION_OVERLAY_FLAGS,
+  ENFORCEMENT_GRADES,
+  type EnforcementGrade,
+} from "./adoption.js";
+
+export const ADOPTION_ASSURANCE_CLASSES = [
+  "peer-advertisable",
+  "declaration-only",
+] as const;
+
+export type AdoptionAssurance = (typeof ADOPTION_ASSURANCE_CLASSES)[number];
+
+const OverlayFlagUnion = Type.Union(
+  ADOPTION_OVERLAY_FLAGS.map((f) => Type.Literal(f)) as [
+    ReturnType<typeof Type.Literal<(typeof ADOPTION_OVERLAY_FLAGS)[number]>>,
+    ...ReturnType<
+      typeof Type.Literal<(typeof ADOPTION_OVERLAY_FLAGS)[number]>
+    >[],
+  ],
+);
+
+const EnforcementGradeUnion = Type.Union(
+  ENFORCEMENT_GRADES.map((g) => Type.Literal(g)) as [
+    ReturnType<typeof Type.Literal<(typeof ENFORCEMENT_GRADES)[number]>>,
+    ...ReturnType<typeof Type.Literal<(typeof ENFORCEMENT_GRADES)[number]>>[],
+  ],
+);
+
+const AssuranceUnion = Type.Union(
+  ADOPTION_ASSURANCE_CLASSES.map((a) => Type.Literal(a)) as [
+    ReturnType<typeof Type.Literal<(typeof ADOPTION_ASSURANCE_CLASSES)[number]>>,
+    ...ReturnType<
+      typeof Type.Literal<(typeof ADOPTION_ASSURANCE_CLASSES)[number]>
+    >[],
+  ],
+);
+
+export const AdoptionDisclosureV1Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(1),
+    agentId: Type.String({ minLength: 1 }),
+    constitutionHash: Type.String({ minLength: 1 }),
+    harnessId: Type.String({ minLength: 1 }),
+    localState: Type.String({ minLength: 1 }),
+    enforcementGrade: EnforcementGradeUnion,
+    overlays: Type.Array(OverlayFlagUnion),
+    assurance: AssuranceUnion,
+    recordedAt: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: true },
+);
+
+export type AdoptionDisclosureV1 = Static<typeof AdoptionDisclosureV1Schema>;
+
+export type AdoptionDisclosureParseResult =
+  | { ok: true; disclosure: AdoptionDisclosureV1 }
+  | { ok: false; error: string };
+
+/**
+ * Max justified conclusion per assurance class (Evidence Semantics §7).
+ * Does not authorize behavioral compliance or completeness elevation.
+ */
+export function maxJustifiedConclusion(assurance: AdoptionAssurance): string {
+  if (assurance === "declaration-only") {
+    return "Agent attested local constitutional self-binding (and grade/overlays if present); not boundary coverage, completeness, or dispatcher compliance";
+  }
+  return "Probe-backed enforcement grade within its advertisability ceiling; not behavioral compliance or gateway non-bypassability";
+}
+
+function elevationError(
+  grade: EnforcementGrade,
+  assurance: AdoptionAssurance,
+  overlays: readonly string[],
+): string | null {
+  if (assurance !== "peer-advertisable") {
+    if (grade === "prompt-only" && !overlays.includes("runtime_degraded")) {
+      return "prompt-only local accepted requires overlay runtime_degraded";
+    }
+    return null;
+  }
+
+  if (grade === "prompt-only") {
+    return "prompt-only cannot elevate to peer-advertisable";
+  }
+  if (grade === "none") {
+    return "none cannot elevate to peer-advertisable";
+  }
+  if (grade === "tool-proxy" && !overlays.includes("runtime_degraded")) {
+    return "tool-proxy peer-advertisable requires partial/degraded disclosure (runtime_degraded)";
+  }
+  return null;
+}
+
+export function parseAdoptionDisclosure(
+  input: unknown,
+): AdoptionDisclosureParseResult {
+  if (!Value.Check(AdoptionDisclosureV1Schema, input)) {
+    return { ok: false, error: "invalid AdoptionDisclosureV1" };
+  }
+  const disclosure = input;
+  const policyError = elevationError(
+    disclosure.enforcementGrade,
+    disclosure.assurance,
+    disclosure.overlays,
+  );
+  if (policyError) {
+    return { ok: false, error: policyError };
+  }
+  return { ok: true, disclosure };
+}

package/src/adoption.ts

@@ -0,0 +1,152 @@
+/**
+ * Adoption state records — explicit non-boolean lifecycle states.
+ *
+ * V1 records remain parseable as legacy. V2 adds overlay flags, harness
+ * identity, and enforcement grade. Parsers never silently upgrade V1 to V2
+ * or invent peer-advertisable assurance.
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
+export const ADOPTION_STATES = [
+  "reviewed",
+  "accepted",
+  "externally-enforced",
+  "inherited",
+  "revoked",
+  "forked",
+  "superseded",
+] as const;
+
+export type AdoptionState = (typeof ADOPTION_STATES)[number];
+
+export const ADOPTION_OVERLAY_FLAGS = [
+  "coercion_suspected",
+  "verification_failed",
+  "key_compromised",
+  "runtime_degraded",
+] as const;
+
+export type AdoptionOverlayFlag = (typeof ADOPTION_OVERLAY_FLAGS)[number];
+
+export const ENFORCEMENT_GRADES = [
+  "native-hook",
+  "tool-proxy",
+  "prompt-only",
+  "none",
+] as const;
+
+export type EnforcementGrade = (typeof ENFORCEMENT_GRADES)[number];
+
+const AdoptionStateUnion = Type.Union(
+  ADOPTION_STATES.map((s) => Type.Literal(s)) as [
+    ReturnType<typeof Type.Literal<(typeof ADOPTION_STATES)[number]>>,
+    ...ReturnType<typeof Type.Literal<(typeof ADOPTION_STATES)[number]>>[],
+  ],
+);
+
+const OverlayFlagUnion = Type.Union(
+  ADOPTION_OVERLAY_FLAGS.map((f) => Type.Literal(f)) as [
+    ReturnType<typeof Type.Literal<(typeof ADOPTION_OVERLAY_FLAGS)[number]>>,
+    ...ReturnType<
+      typeof Type.Literal<(typeof ADOPTION_OVERLAY_FLAGS)[number]>
+    >[],
+  ],
+);
+
+const EnforcementGradeUnion = Type.Union(
+  ENFORCEMENT_GRADES.map((g) => Type.Literal(g)) as [
+    ReturnType<typeof Type.Literal<(typeof ENFORCEMENT_GRADES)[number]>>,
+    ...ReturnType<typeof Type.Literal<(typeof ENFORCEMENT_GRADES)[number]>>[],
+  ],
+);
+
+export const AdoptionStateRecordV1Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(1),
+    agentId: Type.String({ minLength: 1 }),
+    state: AdoptionStateUnion,
+    constitutionHash: Type.String({ minLength: 1 }),
+    recordedAt: Type.String({ minLength: 1 }),
+    predecessorRef: Type.Optional(Type.String({ minLength: 1 })),
+    notes: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+export type AdoptionStateRecordV1 = Static<typeof AdoptionStateRecordV1Schema>;
+
+export const AdoptionStateRecordV2Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(2),
+    agentId: Type.String({ minLength: 1 }),
+    state: AdoptionStateUnion,
+    constitutionHash: Type.String({ minLength: 1 }),
+    recordedAt: Type.String({ minLength: 1 }),
+    harnessId: Type.String({ minLength: 1 }),
+    enforcementGrade: EnforcementGradeUnion,
+    overlays: Type.Array(OverlayFlagUnion),
+    predecessorRef: Type.Optional(Type.String({ minLength: 1 })),
+    notes: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+export type AdoptionStateRecordV2 = Static<typeof AdoptionStateRecordV2Schema>;
+
+export type AdoptionStateRecord =
+  | AdoptionStateRecordV1
+  | AdoptionStateRecordV2;
+
+export type AdoptionParseResult =
+  | { ok: true; kind: "v1"; record: AdoptionStateRecordV1 }
+  | { ok: true; kind: "v2"; record: AdoptionStateRecordV2 }
+  | { ok: false; error: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Parse untrusted adoption JSON into an explicit v1 or v2 result.
+ * V1 never escalates to v2; missing schemaVersion 2 fields fail closed.
+ */
+export function parseAdoptionStateRecord(input: unknown): AdoptionParseResult {
+  if (!isRecord(input)) {
+    return { ok: false, error: "adoption record must be a JSON object" };
+  }
+
+  if (input.schemaVersion === 2) {
+    if (!Value.Check(AdoptionStateRecordV2Schema, input)) {
+      return { ok: false, error: "invalid AdoptionStateRecordV2" };
+    }
+    return { ok: true, kind: "v2", record: input };
+  }
+
+  if (input.schemaVersion === 1) {
+    if (!Value.Check(AdoptionStateRecordV1Schema, input)) {
+      return { ok: false, error: "invalid AdoptionStateRecordV1" };
+    }
+    // Return only V1 fields so extra V2-shaped keys cannot imply graded claims.
+    const record: AdoptionStateRecordV1 = {
+      schemaVersion: 1,
+      agentId: input.agentId as string,
+      state: input.state as AdoptionState,
+      constitutionHash: input.constitutionHash as string,
+      recordedAt: input.recordedAt as string,
+    };
+    if (typeof input.predecessorRef === "string") {
+      record.predecessorRef = input.predecessorRef;
+    }
+    if (typeof input.notes === "string") {
+      record.notes = input.notes;
+    }
+    return { ok: true, kind: "v1", record };
+  }
+
+  return {
+    ok: false,
+    error: `unsupported adoption schema version: ${String(input.schemaVersion)}`,
+  };
+}

package/src/canonical-json.ts

@@ -0,0 +1,70 @@
+/**
+ * Versioned canonical JSON serializers.
+ *
+ * V1 preserves the historical sorted-key algorithm used by audit logs and
+ * claim signatures. V2 is RFC 8785-compatible (JCS) for new envelopes.
+ */
+
+/**
+ * Legacy v1 canonicalization: lexicographically sorted object keys,
+ * no insignificant whitespace, arrays preserve order, primitives via
+ * JSON.stringify. Must remain bit-identical forever for historical chains.
+ */
+export function canonicalizeV1(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalizeV1).join(",") + "]";
+  }
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return (
+    "{" +
+    keys
+      .map((k) => JSON.stringify(k) + ":" + canonicalizeV1(obj[k]))
+      .join(",") +
+    "}"
+  );
+}
+
+/**
+ * RFC 8785-compatible canonical JSON (JCS).
+ * - Object keys sorted by UTF-16 code unit order (JS string sort)
+ * - Undefined object members omitted; undefined array elements → null
+ * - Numbers via JSON.stringify (ECMAScript NumberToString)
+ * - No insignificant whitespace
+ */
+export function canonicalizeV2(value: unknown): string {
+  if (value === undefined) {
+    return "null";
+  }
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return (
+      "[" +
+      value
+        .map((item) =>
+          item === undefined ? "null" : canonicalizeV2(item),
+        )
+        .join(",") +
+      "]"
+    );
+  }
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj)
+    .filter((k) => obj[k] !== undefined)
+    .sort();
+  return (
+    "{" +
+    keys
+      .map((k) => JSON.stringify(k) + ":" + canonicalizeV2(obj[k]))
+      .join(",") +
+    "}"
+  );
+}
+
+/** @deprecated Prefer canonicalizeV1 — alias for migration call sites. */
+export const canonicalize = canonicalizeV1;

package/src/capsules.ts

@@ -0,0 +1,161 @@
+/**
+ * Trust-state capsule schema (emission deferred to later plans).
+ * Plan 13: optional adoptionDisclosure summary for peer-facing grade/assurance.
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { FreshnessEnvelopeSchema } from "./freshness.js";
+import { KEY_ALGORITHM } from "./identity.js";
+import {
+  ADOPTION_OVERLAY_FLAGS,
+  ENFORCEMENT_GRADES,
+} from "./adoption.js";
+import { ADOPTION_ASSURANCE_CLASSES } from "./adoption-disclosure.js";
+
+const OverlayFlagUnion = Type.Union(
+  ADOPTION_OVERLAY_FLAGS.map((f) => Type.Literal(f)) as [
+    ReturnType<typeof Type.Literal<(typeof ADOPTION_OVERLAY_FLAGS)[number]>>,
+    ...ReturnType<
+      typeof Type.Literal<(typeof ADOPTION_OVERLAY_FLAGS)[number]>
+    >[],
+  ],
+);
+
+const EnforcementGradeUnion = Type.Union(
+  ENFORCEMENT_GRADES.map((g) => Type.Literal(g)) as [
+    ReturnType<typeof Type.Literal<(typeof ENFORCEMENT_GRADES)[number]>>,
+    ...ReturnType<typeof Type.Literal<(typeof ENFORCEMENT_GRADES)[number]>>[],
+  ],
+);
+
+const AssuranceUnion = Type.Union(
+  ADOPTION_ASSURANCE_CLASSES.map((a) => Type.Literal(a)) as [
+    ReturnType<typeof Type.Literal<(typeof ADOPTION_ASSURANCE_CLASSES)[number]>>,
+    ...ReturnType<
+      typeof Type.Literal<(typeof ADOPTION_ASSURANCE_CLASSES)[number]>
+    >[],
+  ],
+);
+
+/** Compact peer-facing adoption summary (no raw MEMORY/SOUL). */
+export const CapsuleAdoptionDisclosureSummarySchema = Type.Object(
+  {
+    constitutionHash: Type.String({ minLength: 1 }),
+    harnessId: Type.String({ minLength: 1 }),
+    localState: Type.String({ minLength: 1 }),
+    enforcementGrade: EnforcementGradeUnion,
+    overlays: Type.Array(OverlayFlagUnion),
+    assurance: AssuranceUnion,
+  },
+  { additionalProperties: false },
+);
+
+export type CapsuleAdoptionDisclosureSummary = Static<
+  typeof CapsuleAdoptionDisclosureSummarySchema
+>;
+
+export const TrustStateCapsuleV2Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(2),
+    runtimeId: Type.String({ minLength: 1 }),
+    implementationVersion: Type.String({ minLength: 1 }),
+    evidenceRoot: Type.String({ minLength: 1 }),
+    coverage: Type.Object({
+      claims: Type.Integer({ minimum: 0 }),
+      receipts: Type.Integer({ minimum: 0 }),
+      completeness: Type.Union([
+        Type.Literal("none"),
+        Type.Literal("partial"),
+        Type.Literal("full"),
+      ]),
+    }),
+    freshness: FreshnessEnvelopeSchema,
+    agentId: Type.String({ minLength: 1 }),
+    publicKey: Type.String({ minLength: 1 }),
+    signature: Type.String({ minLength: 1 }),
+    keyAlgorithm: Type.Literal(KEY_ALGORITHM),
+    adoptionDisclosure: Type.Optional(CapsuleAdoptionDisclosureSummarySchema),
+  },
+  { additionalProperties: true },
+);
+
+export type TrustStateCapsuleV2 = Static<typeof TrustStateCapsuleV2Schema>;
+
+export type CapsuleParseResult =
+  | { ok: true; capsule: TrustStateCapsuleV2 }
+  | { ok: false; error: string };
+
+export function parseTrustStateCapsule(input: unknown): CapsuleParseResult {
+  if (!Value.Check(TrustStateCapsuleV2Schema, input)) {
+    return { ok: false, error: "invalid TrustStateCapsuleV2" };
+  }
+  return { ok: true, capsule: input };
+}
+
+export type CapsuleAdoptionConsistency = {
+  ok: boolean;
+  error?: string | undefined;
+};
+
+/**
+ * Peer-summary contract: if adoption is advertised, disclosure summary is
+ * required. Prompt-only / declaration-only cannot elevate completeness to full.
+ */
+export function validateCapsuleAdoptionConsistency(
+  input: unknown,
+): CapsuleAdoptionConsistency {
+  if (!input || typeof input !== "object") {
+    return { ok: false, error: "capsule must be an object" };
+  }
+  const obj = input as Record<string, unknown>;
+  const advertising = obj.advertisingAdoption === true;
+
+  const disclosure = obj.adoptionDisclosure;
+  if (advertising && (disclosure === undefined || disclosure === null)) {
+    return {
+      ok: false,
+      error:
+        "peer-summary adoption advertisement requires adoptionDisclosure summary",
+    };
+  }
+
+  if (disclosure === undefined || disclosure === null) {
+    return { ok: true };
+  }
+
+  if (!Value.Check(CapsuleAdoptionDisclosureSummarySchema, disclosure)) {
+    return { ok: false, error: "invalid adoptionDisclosure summary" };
+  }
+
+  const coverage = obj.coverage as
+    | { completeness?: string }
+    | undefined;
+  const completeness = coverage?.completeness;
+  if (
+    (disclosure.enforcementGrade === "prompt-only" ||
+      disclosure.assurance === "declaration-only") &&
+    completeness === "full"
+  ) {
+    return {
+      ok: false,
+      error:
+        "prompt-only / declaration-only adoptionDisclosure cannot pair with completeness=full",
+    };
+  }
+
+  if (
+    disclosure.enforcementGrade === "tool-proxy" &&
+    completeness === "full"
+  ) {
+    return {
+      ok: false,
+      error:
+        "tool-proxy adoptionDisclosure is capped at partial completeness (grade=tool-proxy assurance=" +
+        disclosure.assurance +
+        ")",
+    };
+  }
+
+  return { ok: true };
+}

package/src/claims.ts

@@ -0,0 +1,147 @@
+/**
+ * Versioned constitutional claim schemas and parsers.
+ *
+ * Untrusted peer JSON is runtime-validated. Legacy v1 claims are accepted
+ * only as declaration-only input and are never silently upgraded to v2.
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { KEY_ALGORITHM } from "./identity.js";
+import { FreshnessEnvelopeSchema } from "./freshness.js";
+
+export const CLAIM_CLASSES = [
+  "identity",
+  "configuration",
+  "runtime",
+  "event",
+  "completeness",
+  "behavioral",
+] as const;
+
+export type ClaimClass = (typeof CLAIM_CLASSES)[number];
+
+export const LegacyConstitutionalClaimV1Schema = Type.Object(
+  {
+    agentId: Type.String({ minLength: 1 }),
+    constitutionHash: Type.String({ minLength: 1 }),
+    adoptedAt: Type.String({ minLength: 1 }),
+    auditMerkleRoot: Type.String({ minLength: 1 }),
+    auditEntryCount: Type.Integer({ minimum: 0 }),
+    chainIntact: Type.Boolean(),
+    recentLaws: Type.Array(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+export type LegacyConstitutionalClaimV1 = Static<
+  typeof LegacyConstitutionalClaimV1Schema
+>;
+
+export const ConstitutionalClaimV2Schema = Type.Object(
+  {
+    schemaVersion: Type.Literal(2),
+    claimClass: Type.Union(
+      CLAIM_CLASSES.map((c) => Type.Literal(c)) as [
+        ReturnType<typeof Type.Literal<(typeof CLAIM_CLASSES)[number]>>,
+        ...ReturnType<typeof Type.Literal<(typeof CLAIM_CLASSES)[number]>>[],
+      ],
+    ),
+    agentId: Type.String({ pattern: "^fpp:ed25519:[0-9a-fA-F]{64}$" }),
+    keyAlgorithm: Type.Literal(KEY_ALGORITHM),
+    constitutionHash: Type.String({ minLength: 1 }),
+    adoptedAt: Type.String({ minLength: 1 }),
+    auditMerkleRoot: Type.String({ minLength: 1 }),
+    auditEntryCount: Type.Integer({ minimum: 0 }),
+    chainIntact: Type.Boolean(),
+    recentLaws: Type.Array(Type.String()),
+    /** When present, freshness fields are part of the signed canonical payload. */
+    freshness: Type.Optional(FreshnessEnvelopeSchema),
+  },
+  { additionalProperties: true },
+);
+
+export type ConstitutionalClaimV2 = Static<typeof ConstitutionalClaimV2Schema>;
+
+export type ClaimParseResult =
+  | {
+      ok: true;
+      kind: "legacy-v1";
+      assurance: "declaration-only";
+      claim: LegacyConstitutionalClaimV1;
+      diagnostics: string[];
+    }
+  | {
+      ok: true;
+      kind: "v2";
+      assurance: "schema-validated";
+      claim: ConstitutionalClaimV2;
+      diagnostics: string[];
+    }
+  | {
+      ok: false;
+      error: string;
+      diagnostics: string[];
+    };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Parse untrusted claim JSON into an explicit v1 or v2 result.
+ * Unknown critical versions fail closed. V1 never escalates to v2 assurance.
+ */
+export function parseClaim(input: unknown): ClaimParseResult {
+  if (!isRecord(input)) {
+    return {
+      ok: false,
+      error: "claim must be a JSON object",
+      diagnostics: ["expected object"],
+    };
+  }
+
+  if ("schemaVersion" in input) {
+    if (input.schemaVersion === 2) {
+      const errors = [...Value.Errors(ConstitutionalClaimV2Schema, input)];
+      if (errors.length > 0) {
+        return {
+          ok: false,
+          error: "malformed constitutional claim v2",
+          diagnostics: errors.map((e) => `${e.path}: ${e.message}`),
+        };
+      }
+      return {
+        ok: true,
+        kind: "v2",
+        assurance: "schema-validated",
+        claim: input as ConstitutionalClaimV2,
+        diagnostics: [],
+      };
+    }
+    return {
+      ok: false,
+      error: `unsupported critical schema version: ${String(input.schemaVersion)}`,
+      diagnostics: [`schemaVersion=${String(input.schemaVersion)}`],
+    };
+  }
+
+  const errors = [...Value.Errors(LegacyConstitutionalClaimV1Schema, input)];
+  if (errors.length > 0) {
+    return {
+      ok: false,
+      error: "malformed legacy constitutional claim v1",
+      diagnostics: errors.map((e) => `${e.path}: ${e.message}`),
+    };
+  }
+
+  return {
+    ok: true,
+    kind: "legacy-v1",
+    assurance: "declaration-only",
+    claim: input as LegacyConstitutionalClaimV1,
+    diagnostics: [
+      "legacy-v1 accepted as declaration-only; not escalated to v2 assurance",
+    ],
+  };
+}