@kashscript/lexicons 0.1.0

package/src/extensions/trade.ts

@@ -0,0 +1,210 @@
+/**
+ * Trade Extension — domain lexicons (Duedale-shaped but Duedale-agnostic).
+ *
+ *   kash.trade.offer@1.0.0    — an item / service for sale.
+ *   kash.trade.receipt@1.0.0  — a cryptographically signed completed transaction.
+ *   kash.trade.status@1.0.0   — a lightweight logistics update.
+ *
+ * Import path: `@kashscript/lexicons/extensions/trade`.
+ *
+ * This file is an **extension**: the Foundry core never auto-loads it.
+ * Consumers explicitly register `TRADE_EXTENSION` against their
+ * `LexiconRegistry` to opt in to trade-domain validation.
+ *
+ * Prices follow ISO 4217 (currency codes) and store amounts as DECIMAL STRINGS
+ * to avoid IEEE-754 float drift. Locations use ISO 3166-2 region codes when
+ * available, falling back to free-form region strings.
+ */
+
+import { RECORD_REF_SCHEMA, type RecordRef } from "../envelope";
+import type { LexiconDef } from "../registry";
+import { S, type ObjectSchema } from "../schema";
+
+/* ─────────────────────────────────────────────────────────────────
+ * Money — ISO 4217 amount as a decimal string. AI-parseable.
+ * ───────────────────────────────────────────────────────────────── */
+
+const DECIMAL_AMOUNT_RE = /^(?:0|[1-9][0-9]{0,17})(?:\.[0-9]{1,8})?$/;
+
+export type PriceUnit = "fixed" | "per-hour" | "per-day" | "per-month" | "per-unit";
+
+export interface PriceSpec {
+  readonly amount: string;
+  readonly currency: string;
+  readonly unit?: PriceUnit;
+}
+
+const PRICE_SPEC: ObjectSchema = S.object(
+  {
+    amount:   S.string({ pattern: DECIMAL_AMOUNT_RE, maxLength: 32 }),
+    currency: S.string({ format: "iso4217" }),
+    unit:     S.optional(S.enum("fixed", "per-hour", "per-day", "per-month", "per-unit")),
+  },
+  ["amount", "currency"],
+);
+
+/* ─────────────────────────────────────────────────────────────────
+ *  kash.trade.offer@1.0.0
+ * ───────────────────────────────────────────────────────────────── */
+
+export const KASH_TRADE_OFFER_NSID    = "kash.trade.offer" as const;
+export const KASH_TRADE_OFFER_VERSION = { major: 1, minor: 0, patch: 0 } as const;
+export const KASH_TRADE_OFFER_ID      = "kash.trade.offer@1.0.0" as const;
+
+export type TradeCategory  = "goods" | "services" | "rentals" | "digital";
+export type TradeStatus    = "open" | "reserved" | "closed";
+export type FulfilmentMode = "pickup" | "ship" | "digital";
+
+export interface OfferMediaRef {
+  readonly cid: string;
+  readonly mimeType: "image/jpeg" | "image/png" | "image/webp";
+}
+
+export interface LocationSpec {
+  readonly region: string;
+  readonly handler: FulfilmentMode;
+}
+
+export interface KashTradeOfferBody {
+  readonly title: string;
+  readonly description?: string;
+  readonly category: TradeCategory;
+  readonly price: PriceSpec;
+  readonly media?: readonly OfferMediaRef[];
+  readonly location?: LocationSpec;
+  readonly validUntil?: string;
+  readonly status: TradeStatus;
+  readonly relatedPost?: RecordRef;
+}
+
+const OFFER_MEDIA_REF: ObjectSchema = S.object(
+  {
+    cid:      S.string({ format: "cid" }),
+    mimeType: S.enum("image/jpeg", "image/png", "image/webp"),
+  },
+  ["cid", "mimeType"],
+);
+
+const LOCATION_SPEC: ObjectSchema = S.object(
+  {
+    region:  S.string({ minLength: 1, maxLength: 64 }),
+    handler: S.enum("pickup", "ship", "digital"),
+  },
+  ["region", "handler"],
+);
+
+export const KASH_TRADE_OFFER_BODY_SCHEMA: ObjectSchema = S.object(
+  {
+    title:       S.string({ minLength: 1, maxLength: 140 }),
+    description: S.optional(S.string({ maxLength: 4000 })),
+    category:    S.enum("goods", "services", "rentals", "digital"),
+    price:       PRICE_SPEC,
+    media:       S.optional(S.array(OFFER_MEDIA_REF, { maxItems: 8 })),
+    location:    S.optional(LOCATION_SPEC),
+    validUntil:  S.optional(S.string({ format: "iso8601" })),
+    status:      S.enum("open", "reserved", "closed"),
+    relatedPost: S.optional(RECORD_REF_SCHEMA),
+  },
+  ["title", "category", "price", "status"],
+);
+
+/* ─────────────────────────────────────────────────────────────────
+ *  kash.trade.receipt@1.0.0
+ *
+ *  Dual-receipt pattern: each party publishes their OWN receipt.
+ *  Cross-domain interop: optional `linkedPost` references a `kash.social.post`.
+ * ───────────────────────────────────────────────────────────────── */
+
+export const KASH_TRADE_RECEIPT_NSID    = "kash.trade.receipt" as const;
+export const KASH_TRADE_RECEIPT_VERSION = { major: 1, minor: 0, patch: 0 } as const;
+export const KASH_TRADE_RECEIPT_ID      = "kash.trade.receipt@1.0.0" as const;
+
+export type TradeRole = "buyer" | "seller";
+
+export interface KashTradeReceiptBody {
+  readonly offer: RecordRef;
+  readonly counterparty: string;
+  readonly role: TradeRole;
+  readonly price: PriceSpec;
+  readonly settledAt: string;
+  readonly paymentRef?: string;
+  readonly counterpartyReceipt?: RecordRef;
+  readonly linkedPost?: RecordRef;
+}
+
+export const KASH_TRADE_RECEIPT_BODY_SCHEMA: ObjectSchema = S.object(
+  {
+    offer:               RECORD_REF_SCHEMA,
+    counterparty:        S.string({ format: "did-ks" }),
+    role:                S.enum("buyer", "seller"),
+    price:               PRICE_SPEC,
+    settledAt:           S.string({ format: "iso8601" }),
+    paymentRef:          S.optional(S.string({ minLength: 1, maxLength: 128 })),
+    counterpartyReceipt: S.optional(RECORD_REF_SCHEMA),
+    linkedPost:          S.optional(RECORD_REF_SCHEMA),
+  },
+  ["offer", "counterparty", "role", "price", "settledAt"],
+);
+
+/* ─────────────────────────────────────────────────────────────────
+ *  kash.trade.status@1.0.0
+ * ───────────────────────────────────────────────────────────────── */
+
+export const KASH_TRADE_STATUS_NSID    = "kash.trade.status" as const;
+export const KASH_TRADE_STATUS_VERSION = { major: 1, minor: 0, patch: 0 } as const;
+export const KASH_TRADE_STATUS_ID      = "kash.trade.status@1.0.0" as const;
+
+export type TradeState =
+  | "pending" | "shipped" | "in-transit" | "delivered"
+  | "received" | "disputed" | "refunded" | "cancelled";
+
+export interface KashTradeStatusBody {
+  readonly receipt: RecordRef;
+  readonly state: TradeState;
+  readonly note?: string;
+  readonly trackingRef?: string;
+  readonly at?: string;
+}
+
+export const KASH_TRADE_STATUS_BODY_SCHEMA: ObjectSchema = S.object(
+  {
+    receipt:     RECORD_REF_SCHEMA,
+    state:       S.enum("pending", "shipped", "in-transit", "delivered", "received", "disputed", "refunded", "cancelled"),
+    note:        S.optional(S.string({ minLength: 1, maxLength: 280 })),
+    trackingRef: S.optional(S.string({ minLength: 1, maxLength: 128 })),
+    at:          S.optional(S.string({ format: "iso8601" })),
+  },
+  ["receipt", "state"],
+);
+
+/* ─────────────────────────────────────────────────────────────────
+ *  Extension bundle
+ * ───────────────────────────────────────────────────────────────── */
+
+/** All Trade-domain lexicons. Pass to `LexiconRegistry.registerAll()`. */
+export const TRADE_EXTENSION: readonly LexiconDef[] = [
+  {
+    id: KASH_TRADE_OFFER_ID,
+    nsid: KASH_TRADE_OFFER_NSID,
+    semver: KASH_TRADE_OFFER_VERSION,
+    bodySchema: KASH_TRADE_OFFER_BODY_SCHEMA,
+    title: "Trade Offer",
+    description: "An item or service for sale — ISO 4217 price, optional location and media.",
+  },
+  {
+    id: KASH_TRADE_RECEIPT_ID,
+    nsid: KASH_TRADE_RECEIPT_NSID,
+    semver: KASH_TRADE_RECEIPT_VERSION,
+    bodySchema: KASH_TRADE_RECEIPT_BODY_SCHEMA,
+    title: "Trade Receipt",
+    description: "Cryptographically signed completed transaction. Dual-receipt pattern; optionally links to a social post.",
+  },
+  {
+    id: KASH_TRADE_STATUS_ID,
+    nsid: KASH_TRADE_STATUS_NSID,
+    semver: KASH_TRADE_STATUS_VERSION,
+    bodySchema: KASH_TRADE_STATUS_BODY_SCHEMA,
+    title: "Trade Status",
+    description: "Lightweight logistics update bound to a receipt.",
+  },
+];

package/src/extensions/zkp.ts

@@ -0,0 +1,108 @@
+/**
+ * ZKP Extension — privacy-bearing proof submissions.
+ *
+ *   kash.zkp.proof-of-claim@1.0.0
+ *     The on-the-wire shape a holder uses to submit a SNARK proof to a
+ *     verifier. Pairs naturally with the {@link @kashscript/identity-zkp}
+ *     prover surface but is transport-agnostic — verifiers can accept it
+ *     over HTTP, Kafka, anywhere a Kash-Event flows.
+ *
+ * **F3 (audit) — one-shot-keypair pattern.** Every submission carries a
+ * `submitWith` discriminator that names the keypair model the envelope
+ * uses:
+ *
+ *   • `"ephemeral-keypair"` — the holder mints a FRESH keypair just for
+ *     this submission. The envelope's `kid` is the ephemeral DID; the
+ *     verifier learns nothing about the holder's persistent identity.
+ *     This is the unlinkable mode. Cross-verifier correlation requires
+ *     the verifiers to combine OUT-OF-BAND signals (network, billing) —
+ *     the wire format itself reveals nothing.
+ *
+ *   • `"session-keypair"` — the holder uses a per-verifier session key
+ *     (typically derived from a verifier-bound nonce). Submissions to
+ *     the SAME verifier within the session are linkable; submissions
+ *     across verifiers/sessions are not.
+ *
+ *   • `"persistent-keypair"` — the holder uses their long-lived DID key.
+ *     All submissions are correlatable. Use only when correlation is
+ *     desired (e.g., audit-trail flows; high-trust authenticated grants).
+ *
+ * The lexicon DOES NOT enforce which discriminator is used — that is a
+ * holder choice — but verifiers MUST surface the chosen mode in their
+ * UX and decision logic.
+ *
+ * Import path: `@kashscript/lexicons/extensions/zkp`.
+ */
+
+import type { LexiconDef } from "../registry";
+import { S, type ObjectSchema } from "../schema";
+
+/* ─────────────────────────────────────────────────────────────────
+ *  kash.zkp.proof-of-claim@1.0.0
+ * ───────────────────────────────────────────────────────────────── */
+
+export const KASH_ZKP_PROOF_OF_CLAIM_NSID    = "kash.zkp.proof-of-claim" as const;
+export const KASH_ZKP_PROOF_OF_CLAIM_VERSION = { major: 1, minor: 0, patch: 0 } as const;
+export const KASH_ZKP_PROOF_OF_CLAIM_ID      = "kash.zkp.proof-of-claim@1.0.0" as const;
+
+/** Keypair-model discriminator. See module docstring. */
+export type SubmitWith = "ephemeral-keypair" | "session-keypair" | "persistent-keypair";
+
+/** Supported SNARK envelopes. Mirrors `@kashscript/identity-zkp` `ProofSystem`. */
+export type ZkpProofSystem = "groth16" | "plonk" | "fflonk";
+
+export interface KashZkpProofOfClaimBody {
+  /** The claim being proven, in plain language (display-only — never signed-into-circuit). */
+  readonly claim: string;
+  /** Stable circuit id (e.g., `"kash-range-proof-on-commitment-v1"`). */
+  readonly circuitId: string;
+  /** Proof system the envelope targets. */
+  readonly system: ZkpProofSystem;
+  /** The opaque proof envelope as emitted by snarkjs (any JSON shape). */
+  readonly proof: Readonly<Record<string, unknown>>;
+  /** Public signals — ordered, snarkjs decimal-string convention. */
+  readonly publicSignals: readonly string[];
+  /** Keypair model the holder used to submit. See module docstring. */
+  readonly submitWith: SubmitWith;
+  /**
+   * OPTIONAL audience identifier when the holder bound the proof to a specific
+   * verifier (typically the verifier's DID or origin URL). Verifiers SHOULD
+   * reject submissions whose `audience` does not match their own identity.
+   */
+  readonly audience?: string;
+  /** OPTIONAL ISO-8601 expiry. Verifiers SHOULD reject after this instant. */
+  readonly expiresAt?: string;
+  /** OPTIONAL base58btc-encoded SHA-256 over `{ proof, publicSignals, audience, expiresAt }`. */
+  readonly bindingHashB58?: string;
+}
+
+export const KASH_ZKP_PROOF_OF_CLAIM_BODY_SCHEMA: ObjectSchema = S.object(
+  {
+    claim:          S.string({ minLength: 1, maxLength: 280 }),
+    circuitId:      S.string({ minLength: 1, maxLength: 128, pattern: /^[a-z0-9][a-z0-9-]*$/ }),
+    system:         S.enum("groth16", "plonk", "fflonk"),
+    proof:          S.object({}, []),                // open shape — system-dependent
+    publicSignals:  S.array(S.string({ maxLength: 96 }), { maxItems: 32 }),
+    submitWith:     S.enum("ephemeral-keypair", "session-keypair", "persistent-keypair"),
+    audience:       S.optional(S.string({ minLength: 1, maxLength: 512 })),
+    expiresAt:      S.optional(S.string({ format: "iso8601" })),
+    bindingHashB58: S.optional(S.string({ minLength: 32, maxLength: 64 })),
+  },
+  ["claim", "circuitId", "system", "proof", "publicSignals", "submitWith"],
+);
+
+/* ─────────────────────────────────────────────────────────────────
+ *  Extension bundle
+ * ───────────────────────────────────────────────────────────────── */
+
+/** All ZKP-domain lexicons. Pass to `LexiconRegistry.registerAll()`. */
+export const ZKP_EXTENSION: readonly LexiconDef[] = [
+  {
+    id: KASH_ZKP_PROOF_OF_CLAIM_ID,
+    nsid: KASH_ZKP_PROOF_OF_CLAIM_NSID,
+    semver: KASH_ZKP_PROOF_OF_CLAIM_VERSION,
+    bodySchema: KASH_ZKP_PROOF_OF_CLAIM_BODY_SCHEMA,
+    title: "ZKP Proof of Claim",
+    description: "Wire envelope for submitting a SNARK proof to a verifier. Carries a submitWith discriminator that names the keypair-model the envelope uses, so verifiers can reason about linkability.",
+  },
+];

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @kashscript/lexicons — main export surface.
+ *
+ * Exposes:
+ *   - Framework (types, schema DSL, semver, envelope) — the Box.
+ *   - Registry + Engine (LexiconRegistry, validateEvent, getSchemaDefinition).
+ *   - Standard Library (identity-tier lexicons) — the agnostic core Content.
+ *
+ * Domain Extensions (Social, Trade, …) are NOT auto-exported here.
+ * They live under subpath imports:
+ *   - @kashscript/lexicons/extensions/social
+ *   - @kashscript/lexicons/extensions/trade
+ *
+ * This package is zero-dependency. No network, no crypto, no storage —
+ * pure data modelling and validation.
+ */
+
+export * from "./types";
+export * from "./schema";
+export * from "./semver";
+export * from "./envelope";
+export * from "./registry";
+export * from "./engine";
+export * from "./json-schema";
+
+// Standard Library (identity tier) — lexicons consumers will almost always want.
+// Domain content (social, trade, neuron) ships as separately-imported Extensions.
+export * from "./lexicons";
+
+export const LEXICONS_FRAMEWORK_VERSION = "1.0.0" as const;

package/src/json-schema.ts

@@ -0,0 +1,141 @@
+/**
+ * Convert a `Schema` (the internal DSL) to a JSON-Schema Draft 2020-12 object.
+ *
+ * Output is intended for consumption by external AI tools and documentation
+ * generators (Oreoasis ingestion, OpenAPI exporters, schema crawlers). The
+ * conversion is lossless for our DSL: every constraint we model maps to a
+ * documented JSON-Schema keyword.
+ *
+ * Kash-specific string formats (did-ks, cid, lexicon-id, …) are exposed via
+ * the `format` keyword AND as `pattern` regex so consumers without a custom
+ * format registry can still validate.
+ */
+
+import {
+  FORMAT_PATTERNS,
+  type ArraySchema,
+  type EnumSchema,
+  type LiteralSchema,
+  type NumberSchema,
+  type ObjectSchema,
+  type RecordSchema,
+  type Schema,
+  type SchemaStringFormat,
+  type StringSchema,
+  type UnionSchema,
+} from "./schema";
+
+/** Minimal JSON-Schema object. Booleans (`true`/`false` schemas) are NOT emitted. */
+export type JsonSchema = Readonly<Record<string, unknown>>;
+
+/** Map Kash string-format identifiers to JSON-Schema `format` values.
+ *  Standard formats (date-time, uri) use the JSON-Schema names; Kash-specific
+ *  ones use a prefix. The regex source is reused from `FORMAT_PATTERNS` so we
+ *  never duplicate the canonical regex. */
+const FORMAT_NAMES: Record<SchemaStringFormat, string> = {
+  "did-ks":     "did-ks",
+  "cid":        "cid",
+  "iso8601":    "date-time",
+  "url":        "uri",
+  "multibase":  "multibase",
+  "bcp47":      "bcp47-language-tag",
+  "iso4217":    "iso-4217-currency",
+  "lexicon-id": "kash-lexicon-id",
+  "nsid":       "kash-nsid",
+};
+
+/** Convert any internal Schema to a JSON-Schema-Draft-2020-12 object. */
+export function toJsonSchema(schema: Schema): JsonSchema {
+  switch (schema.kind) {
+    case "any":
+      return {};
+    case "boolean":
+      return { type: "boolean" };
+    case "literal":
+      return convertLiteral(schema);
+    case "enum":
+      return convertEnum(schema);
+    case "string":
+      return convertString(schema);
+    case "number":
+      return convertNumber(schema);
+    case "array":
+      return convertArray(schema);
+    case "object":
+      return convertObject(schema);
+    case "union":
+      return convertUnion(schema);
+    case "optional":
+      // Optionality is encoded by the parent object's `required` array.
+      return toJsonSchema(schema.inner);
+    case "record":
+      return convertRecord(schema);
+  }
+}
+
+function convertLiteral(s: LiteralSchema): JsonSchema {
+  return { const: s.value };
+}
+
+function convertEnum(s: EnumSchema): JsonSchema {
+  return { enum: [...s.values] };
+}
+
+function convertString(s: StringSchema): JsonSchema {
+  const out: Record<string, unknown> = { type: "string" };
+  if (s.minLength !== undefined) out.minLength = s.minLength;
+  if (s.maxLength !== undefined) out.maxLength = s.maxLength;
+  if (s.pattern) out.pattern = s.pattern.source;
+  if (s.format) {
+    out.format = FORMAT_NAMES[s.format];
+    if (out.pattern === undefined) out.pattern = FORMAT_PATTERNS[s.format].source;
+  }
+  return out;
+}
+
+function convertNumber(s: NumberSchema): JsonSchema {
+  const out: Record<string, unknown> = { type: s.integer ? "integer" : "number" };
+  if (s.min !== undefined) out.minimum = s.min;
+  if (s.max !== undefined) out.maximum = s.max;
+  return out;
+}
+
+function convertArray(s: ArraySchema): JsonSchema {
+  const out: Record<string, unknown> = {
+    type: "array",
+    items: toJsonSchema(s.items),
+  };
+  if (s.minItems !== undefined) out.minItems = s.minItems;
+  if (s.maxItems !== undefined) out.maxItems = s.maxItems;
+  return out;
+}
+
+function convertObject(s: ObjectSchema): JsonSchema {
+  const properties: Record<string, JsonSchema> = {};
+  for (const k of Object.keys(s.properties)) {
+    const sub = s.properties[k]!;
+    properties[k] = toJsonSchema(sub);
+  }
+  const out: Record<string, unknown> = {
+    type: "object",
+    properties,
+    additionalProperties: s.additionalProperties,
+  };
+  if (s.required.length > 0) out.required = [...s.required];
+  return out;
+}
+
+function convertUnion(s: UnionSchema): JsonSchema {
+  return { anyOf: s.variants.map(toJsonSchema) };
+}
+
+function convertRecord(s: RecordSchema): JsonSchema {
+  const out: Record<string, unknown> = {
+    type: "object",
+    additionalProperties: toJsonSchema(s.values),
+  };
+  if (s.keys.pattern) {
+    out.propertyNames = { pattern: s.keys.pattern.source };
+  }
+  return out;
+}

package/src/lexicons/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Standard Library — the agnostic, foundry-shipped lexicons.
+ *
+ * This registry slice contains ONLY the identity-tier lexicons:
+ *   - kash.id.profile@1.0.0
+ *   - kash.id.audit@1.0.0
+ *   - kash.id.preferences@1.0.0
+ *
+ * Domain lexicons (Social, Trade, Neuron, third-party `app.*`) ship as
+ * Extensions and live under `src/extensions/<domain>.ts`. Consumers
+ * register what they need. The Core never auto-loads domain content —
+ * that is the load-bearing rule of the Box-vs-Content separation.
+ */
+
+export * from "./kash-id-profile";
+export * from "./kash-id-audit";
+export * from "./kash-id-preferences";
+
+import type { LexiconDef } from "../registry";
+import {
+  KASH_PROFILE_BODY_SCHEMA, KASH_PROFILE_ID, KASH_PROFILE_NSID, KASH_PROFILE_VERSION,
+} from "./kash-id-profile";
+import {
+  KASH_AUDIT_BODY_SCHEMA, KASH_AUDIT_ID, KASH_AUDIT_NSID, KASH_AUDIT_VERSION,
+} from "./kash-id-audit";
+import {
+  KASH_PREFERENCES_BODY_SCHEMA, KASH_PREFERENCES_ID, KASH_PREFERENCES_NSID, KASH_PREFERENCES_VERSION,
+} from "./kash-id-preferences";
+
+/**
+ * The Standard Library — every identity-tier lexicon every Kash actor
+ * needs to interoperate at the protocol layer.
+ *
+ * Bootstrap pattern:
+ *
+ * ```ts
+ * import { LexiconRegistry } from "@kashscript/lexicons";
+ * import { STANDARD_LIBRARY } from "@kashscript/lexicons";
+ *
+ * const registry = new LexiconRegistry().registerAll(STANDARD_LIBRARY);
+ * ```
+ */
+export const STANDARD_LIBRARY: readonly LexiconDef[] = [
+  {
+    id: KASH_PROFILE_ID,
+    nsid: KASH_PROFILE_NSID,
+    semver: KASH_PROFILE_VERSION,
+    bodySchema: KASH_PROFILE_BODY_SCHEMA,
+    title: "Kash Profile",
+    description: "Sovereign user profile — display name, bio, avatar, pinned PDS URLs.",
+  },
+  {
+    id: KASH_AUDIT_ID,
+    nsid: KASH_AUDIT_NSID,
+    semver: KASH_AUDIT_VERSION,
+    bodySchema: KASH_AUDIT_BODY_SCHEMA,
+    title: "Kash Audit Entry",
+    description: "Append-only ledger of identity lifecycle events.",
+  },
+  {
+    id: KASH_PREFERENCES_ID,
+    nsid: KASH_PREFERENCES_NSID,
+    semver: KASH_PREFERENCES_VERSION,
+    bodySchema: KASH_PREFERENCES_BODY_SCHEMA,
+    title: "Kash Preferences",
+    description: "App-agnostic settings — theme, language, AI consent flags.",
+  },
+];

package/src/lexicons/kash-id-audit.ts

@@ -0,0 +1,61 @@
+/**
+ * Lexicon: kash.id.audit@1.0.0
+ *
+ * Append-only ledger of identity-state changes. Each record references the
+ * corresponding op-log entry from the Identity Protocol so consumers can
+ * audit history without re-replaying the full chain.
+ */
+
+import { S, type ObjectSchema } from "../schema";
+
+export const KASH_AUDIT_NSID    = "kash.id.audit" as const;
+export const KASH_AUDIT_VERSION = { major: 1, minor: 0, patch: 0 } as const;
+export const KASH_AUDIT_ID      = "kash.id.audit@1.0.0" as const;
+
+/* ── types ──────────────────────────────────────────────────────── */
+
+export type KashAuditEventType =
+  | "key-rotated"
+  | "key-revoked"
+  | "pds-migrated"
+  | "witnesses-changed"
+  | "quorum-set"
+  | "quorum-recovered"
+  | "deactivated";
+
+export interface KashAuditBody {
+  /** Type of identity-state event being logged. */
+  readonly event: KashAuditEventType;
+  /** CID of the underlying op-log entry (Identity Protocol §3.4 head.opCid). */
+  readonly opCid: string;
+  /** Sequence number from the op log (Identity Protocol §4.2). */
+  readonly opSeq: number;
+  /** Op-log entry type ("update", "recover", "quorum-recover", etc.). */
+  readonly opType: string;
+  /** Human-readable summary for audit-log UIs. 1–280 chars. */
+  readonly summary: string;
+  /** Optional structured details; shape is per-event-type, free-form here. */
+  readonly details?: Readonly<Record<string, unknown>>;
+}
+
+/* ── runtime schema ─────────────────────────────────────────────── */
+
+export const KASH_AUDIT_BODY_SCHEMA: ObjectSchema = S.object(
+  {
+    event:   S.enum(
+      "key-rotated",
+      "key-revoked",
+      "pds-migrated",
+      "witnesses-changed",
+      "quorum-set",
+      "quorum-recovered",
+      "deactivated",
+    ),
+    opCid:   S.string({ format: "cid" }),
+    opSeq:   S.number({ integer: true, min: 0 }),
+    opType:  S.string({ minLength: 1, maxLength: 64 }),
+    summary: S.string({ minLength: 1, maxLength: 280 }),
+    details: S.optional(S.record(S.any())),
+  },
+  ["event", "opCid", "opSeq", "opType", "summary"],
+);