@zanii/ai-register 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,501 @@
+/**
+ * @zanii/ai-register: a regulator's register of AI systems, built from Ledger and Certify
+ * records, exported in the shapes public registers already use.
+ *
+ * One entry per AI system: its agent DIDs, the owner DID, a `zanii.jurisdiction` binding,
+ * an optional Zanii Certify certificate (the public `CertificateView` or the credential),
+ * an optional `@zanii/kyb` owner attestation and caller-supplied descriptive fields.
+ * Every export is a versioned field map in which each field either carries a value and its
+ * source or is null with the reason the inputs do not support it. Nothing is guessed.
+ *
+ * Exports:
+ * - EU AI Act Art. 49 / Annex VIII sections A, B and C (guidance: the EU database format
+ *   is still subject to Commission implementing acts and to the Digital Omnibus changes),
+ * - UK Algorithmic Transparency Recording Standard (ATRS) template 4.0,
+ * - Algorithmic Transparency Standard 0.3.1 (Eurocities; Amsterdam, Helsinki registers).
+ *
+ * The native `zanii.ai_register` snapshot is signed by the regulator or the operator.
+ */
+import { canonicalBytes, jcsHash, signObject, signObjectAsync, verifySignedObject, type RemoteSigner, type SignedObject } from '@zanii/core';
+import { verifyOwnerAttestation, type OwnerAttestation } from '@zanii/kyb';
+
+// ---------------------------------------------------------------------------------- //
+// Inputs
+// ---------------------------------------------------------------------------------- //
+
+/** The shared `zanii.jurisdiction` binding format (`@zanii/jurisdiction`); accepted as a plain object. */
+export interface JurisdictionBinding {
+  v: 1; type: 'zanii.jurisdiction'; subject: string; regulator: string; jurisdiction: string; sector: string;
+  licence: string; issued_at: string; expires_at: string; basis: 'self_declared' | 'regulator_attested'; signer: string; sig: string;
+}
+
+/** Certify `GET /v1/certificates/{hash}` (`CertificateView`), or any subset with `hash`. */
+export interface CertificateInput {
+  hash: string;
+  certificate?: { holder?: string; issuer?: string; issuer_domain?: string; claim?: { scheme?: string; profile?: string; level?: number }; issued_at?: string; exp?: string; [k: string]: unknown };
+  status?: { status?: string; reason?: string | null; since?: string };
+  agent?: { did?: string };
+  profile?: string; level?: number; issued_at?: string; exp?: string;
+  evidence?: string;
+}
+
+export const DESCRIBE_KEYS = [
+  'name', 'summary', 'description', 'intended_purpose', 'status', 'data_and_logic',
+  'provider_name', 'provider_address', 'provider_contact', 'submitter', 'authorised_representative',
+  'deployer_name', 'deployer_address', 'deployer_contact', 'contact_email', 'team', 'senior_responsible_owner',
+  'region', 'member_states', 'eu_database_url', 'declaration_of_conformity_url', 'instructions_url', 'more_info_url',
+  'notified_body_certificate', 'not_high_risk_condition', 'not_high_risk_grounds',
+  'fria_summary', 'fria_url', 'dpia_summary', 'dpia_url', 'human_review', 'appeals', 'risks', 'model', 'lang',
+] as const;
+export type DescribeKey = (typeof DESCRIBE_KEYS)[number];
+export type FieldValue = string | string[];
+export type Describe = Partial<Record<DescribeKey, FieldValue>>;
+
+export const FORMATS = ['eu-ai-act-annex-viii-a', 'eu-ai-act-annex-viii-b', 'eu-ai-act-annex-viii-c', 'uk-atrs', 'eurocities-ats'] as const;
+export type Format = (typeof FORMATS)[number];
+
+export interface SystemInput {
+  /** Register id of the system; defaults to the first agent DID (sorted). */
+  id?: string;
+  agents: string[];
+  owner: string;
+  jurisdiction?: JurisdictionBinding;
+  certificate?: CertificateInput;
+  /** A `@zanii/kyb` owner attestation by `owner`. */
+  kyb?: OwnerAttestation;
+  /** Which party the KYB entity is in the export: without it the KYB name fills no field. */
+  ownerRole?: 'provider' | 'deployer' | 'both';
+  describe?: Describe;
+  /** Per-format values by field id, for fields with no Zanii source: `{ 'uk-atrs': { '2.2.2': '...' } }`. */
+  overrides?: Partial<Record<Format, Record<string, FieldValue>>>;
+}
+
+export interface RegisterEntry {
+  system: string;
+  agents: string[];
+  owner: string;
+  jurisdiction: null | { hash: string; subject: string; regulator: string; jurisdiction: string; sector: string; licence: string; basis: string; issued_at: string; expires_at: string; current: boolean };
+  certificate: null | { hash: string; holder: string | null; issuer: string | null; issuer_domain: string | null; scheme: string | null; profile: string | null; level: number | null; status: string | null; reason: string | null; since: string | null; evidence: string | null; exp: string | null };
+  kyb: null | { hash: string; did: string; domain: string; entity: { name: string; jurisdiction: string | null; registration: string | null }; role: string | null };
+  describe: Describe;
+  overrides: Partial<Record<Format, Record<string, FieldValue>>>;
+  evidence: string[];
+}
+
+const HASH = /^sha256:[0-9a-f]{64}$/;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+const ms = (t: unknown) => (typeof t === 'string' && ISO.test(t) ? Date.parse(t) : NaN);
+const isDid = (x: unknown): x is string => typeof x === 'string' && x.startsWith('did:');
+const fail = (m: string): never => { throw new Error(`ai-register: ${m}`); };
+const isValue = (v: unknown) => typeof v === 'string' || (Array.isArray(v) && v.every((s) => typeof s === 'string'));
+
+function evidenceOf(e: Pick<RegisterEntry, 'jurisdiction' | 'certificate' | 'kyb'>): string[] {
+  return [e.jurisdiction?.hash, e.certificate?.hash, e.kyb?.hash].filter((h): h is string => !!h).sort();
+}
+
+/**
+ * One register entry. Refuses (throws) a binding that does not verify or is about another
+ * subject, a certificate for another agent or whose credential does not match its hash, and a
+ * KYB attestation that does not verify or is not by the owner. `verifyBinding` replaces the
+ * default check (the binding's own `signer` signature) when the caller trusts specific regulators.
+ */
+export function buildEntry(input: SystemInput, opts: { asOf: string; verifyBinding?: (b: JurisdictionBinding) => boolean }): RegisterEntry {
+  if (Number.isNaN(ms(opts?.asOf))) fail('asOf must be an ISO timestamp');
+  if (!Array.isArray(input?.agents) || !input.agents.length || !input.agents.every(isDid)) fail('agents must be a non-empty list of DIDs');
+  if (!isDid(input.owner)) fail('owner must be a DID');
+  const agents = [...new Set(input.agents)].sort();
+
+  let jurisdiction: RegisterEntry['jurisdiction'] = null;
+  const b = input.jurisdiction;
+  if (b) {
+    if (b.v !== 1 || b.type !== 'zanii.jurisdiction') fail('jurisdiction is not a zanii.jurisdiction binding (v1)');
+    if (b.basis !== 'self_declared' && b.basis !== 'regulator_attested') fail('jurisdiction basis must be self_declared or regulator_attested');
+    if (!agents.includes(b.subject) && b.subject !== input.owner) fail('jurisdiction binding is about another subject');
+    if (Number.isNaN(ms(b.issued_at)) || Number.isNaN(ms(b.expires_at))) fail('jurisdiction binding times must be ISO timestamps');
+    if (!(opts.verifyBinding ? opts.verifyBinding(b) : verifySignedObject(b))) fail('jurisdiction binding does not verify');
+    const t = ms(opts.asOf);
+    jurisdiction = {
+      hash: jcsHash(b), subject: b.subject, regulator: b.regulator, jurisdiction: b.jurisdiction, sector: b.sector, licence: b.licence,
+      basis: b.basis, issued_at: b.issued_at, expires_at: b.expires_at, current: ms(b.issued_at) <= t && t < ms(b.expires_at),
+    };
+  }
+
+  let certificate: RegisterEntry['certificate'] = null;
+  const c = input.certificate;
+  if (c) {
+    if (typeof c.hash !== 'string' || !HASH.test(c.hash)) fail('certificate hash must be a sha256 hash');
+    if (c.certificate && jcsHash(c.certificate) !== c.hash) fail('certificate hash does not match the credential');
+    const cred = c.certificate ?? {};
+    const holder = cred.holder ?? c.agent?.did ?? null;
+    if (holder !== null && !agents.includes(holder)) fail('certificate is held by another agent');
+    certificate = {
+      hash: c.hash, holder, issuer: cred.issuer ?? null, issuer_domain: cred.issuer_domain ?? null,
+      scheme: cred.claim?.scheme ?? null, profile: c.profile ?? cred.claim?.profile ?? null, level: c.level ?? cred.claim?.level ?? null,
+      status: c.status?.status ?? null, reason: c.status?.reason ?? null, since: c.status?.since ?? null,
+      evidence: c.evidence ?? null, exp: c.exp ?? cred.exp ?? null,
+    };
+  }
+
+  let kyb: RegisterEntry['kyb'] = null;
+  if (input.kyb) {
+    if (!verifyOwnerAttestation(input.kyb)) fail('kyb attestation does not verify');
+    if (input.kyb.did !== input.owner) fail('kyb attestation is not by the owner');
+    if (input.ownerRole !== undefined && !['provider', 'deployer', 'both'].includes(input.ownerRole)) fail('ownerRole must be provider, deployer or both');
+    const en = input.kyb.entity;
+    kyb = { hash: jcsHash(input.kyb), did: input.kyb.did, domain: input.kyb.domain, entity: { name: en.name, jurisdiction: en.jurisdiction ?? null, registration: en.registration ?? null }, role: input.ownerRole ?? null };
+  }
+
+  const describe: Describe = {};
+  for (const [k, v] of Object.entries(input.describe ?? {})) {
+    if (!(DESCRIBE_KEYS as readonly string[]).includes(k)) fail(`unknown describe field ${k}`);
+    if (!isValue(v)) fail(`describe.${k} must be a string or a list of strings`);
+    describe[k as DescribeKey] = v;
+  }
+  const overrides: RegisterEntry['overrides'] = {};
+  for (const [f, fields] of Object.entries(input.overrides ?? {})) {
+    if (!(FORMATS as readonly string[]).includes(f)) fail(`unknown override format ${f}`);
+    const ids = new Set(FIELD_MAPS[f as Format].fields.map((x) => x[0]));
+    for (const [id, v] of Object.entries(fields ?? {})) {
+      if (!ids.has(id)) fail(`unknown ${f} field ${id}`);
+      if (!isValue(v)) fail(`overrides.${f}.${id} must be a string or a list of strings`);
+    }
+    overrides[f as Format] = { ...fields };
+  }
+
+  const entry = { system: input.id ?? agents[0]!, agents, owner: input.owner, jurisdiction, certificate, kyb, describe, overrides, evidence: [] as string[] };
+  entry.evidence = evidenceOf(entry);
+  return entry;
+}
+
+/** `jcsHash` of an entry. */
+export function entryHash(entry: RegisterEntry): string {
+  return jcsHash(entry);
+}
+
+// ---------------------------------------------------------------------------------- //
+// Field maps
+// ---------------------------------------------------------------------------------- //
+
+/**
+ * A source is `d:<describe key>`, `kyb:provider`, `kyb:deployer` (the KYB entity name when
+ * `ownerRole` says so), `name+agents`, `certify`, `assessments` or `const:<value>`.
+ * No sources = not supported by Zanii inputs (supply an override).
+ */
+type FieldDef = [id: string, name: string, sources: string[], note?: string];
+interface FieldMap { format: Format; format_version: string; source_url: string; guidance: string; fields: FieldDef[] }
+
+const EU_GUIDANCE = 'Guidance: field list of Regulation (EU) 2024/1689 Annex VIII as consolidated at artificialintelligenceact.eu. The EU database (Art. 71) format and some items remain subject to Commission implementing acts and to the Digital Omnibus amendments, whose timing is not final. A field map, not legal advice.';
+const OMNIBUS = 'Marked "not present after the amendment" in the consolidated text (Digital Omnibus); kept for filings under the original text. Confirm before filing.';
+const party = (p: 'A' | 'B' | 'C', who: 'provider' | 'deployer'): FieldDef[] => [
+  [`${p}.1.name`, `Name of the ${who}`, [`d:${who}_name`, `kyb:${who}`]],
+  [`${p}.1.address`, `Address of the ${who}`, [`d:${who}_address`]],
+  [`${p}.1.contact`, `Contact details of the ${who}`, [`d:${who}_contact`]],
+  [`${p}.2`, `Name, address and contact details of the person submitting information on behalf of the ${who}`, ['d:submitter']],
+];
+const common = (p: 'A' | 'B'): FieldDef[] => [
+  ...party(p, 'provider'),
+  [`${p}.3`, 'Name, address and contact details of the authorised representative', ['d:authorised_representative']],
+  [`${p}.4`, 'AI system trade name and any additional unambiguous reference', ['name+agents']],
+  [`${p}.5`, 'Description of the intended purpose of the AI system', ['d:intended_purpose']],
+];
+
+export const FIELD_MAPS: Record<Format, FieldMap> = {
+  'eu-ai-act-annex-viii-a': {
+    format: 'eu-ai-act-annex-viii-a', format_version: 'Regulation (EU) 2024/1689, Annex VIII Section A (Art. 49(1))',
+    source_url: 'https://artificialintelligenceact.eu/annex/8/', guidance: EU_GUIDANCE,
+    fields: [
+      ...common('A'),
+      ['A.6', 'Basic and concise description of the information used by the system (data, inputs) and its operating logic', ['d:data_and_logic']],
+      ['A.7', 'Status of the AI system (on the market or in service; no longer; recalled)', ['d:status']],
+      ['A.8', 'Type, number and expiry date of the notified body certificate, and the notified body', ['d:notified_body_certificate'], 'A Zanii Certify certificate is not a notified-body certificate (Art. 44); Certify evidence is in the register entry.'],
+      ['A.9', 'Scanned copy of the notified body certificate', []],
+      ['A.10', 'Member States in which the AI system has been placed on the market, put into service or made available', ['d:member_states']],
+      ['A.11', 'Copy of the EU declaration of conformity (Art. 47)', ['d:declaration_of_conformity_url']],
+      ['A.12', 'Electronic instructions for use', ['d:instructions_url'], 'Not provided for high-risk systems in law enforcement or migration, asylum and border control (Annex III points 1, 6 and 7).'],
+      ['A.13', 'URL for additional information (optional)', ['d:more_info_url']],
+    ],
+  },
+  'eu-ai-act-annex-viii-b': {
+    format: 'eu-ai-act-annex-viii-b', format_version: 'Regulation (EU) 2024/1689, Annex VIII Section B (Art. 49(2))',
+    source_url: 'https://artificialintelligenceact.eu/annex/8/', guidance: EU_GUIDANCE,
+    fields: [
+      ...common('B'),
+      ['B.6', 'The condition or conditions under Art. 6(3) under which the system is considered not high-risk', ['d:not_high_risk_condition']],
+      ['B.7', 'Short summary of the grounds for considering the system not high-risk', ['d:not_high_risk_grounds'], OMNIBUS],
+      ['B.8', 'Status of the AI system', ['d:status']],
+      ['B.9', 'Member States in which the AI system has been placed on the market, put into service or made available', ['d:member_states'], OMNIBUS],
+    ],
+  },
+  'eu-ai-act-annex-viii-c': {
+    format: 'eu-ai-act-annex-viii-c', format_version: 'Regulation (EU) 2024/1689, Annex VIII Section C (Art. 49(3))',
+    source_url: 'https://artificialintelligenceact.eu/annex/8/', guidance: EU_GUIDANCE,
+    fields: [
+      ...party('C', 'deployer'),
+      ['C.3', 'URL of the entry of the AI system in the EU database by its provider', ['d:eu_database_url']],
+      ['C.4', 'Summary of the findings of the fundamental rights impact assessment (Art. 27)', ['d:fria_summary']],
+      ['C.5', 'Summary of the data protection impact assessment (GDPR Art. 35 or Directive (EU) 2016/680 Art. 27), where applicable', ['d:dpia_summary']],
+    ],
+  },
+  'uk-atrs': {
+    format: 'uk-atrs', format_version: 'ATRS template 4.0',
+    source_url: 'https://www.gov.uk/government/publications/algorithmic-transparency-template',
+    guidance: 'Field ids and names of the ATRS 4.0 template (ATRS_V4.0__FINAL.xlsx). Tier 1 is 1.x, tier 2 is 2.x. Most tier 2 fields describe the tool itself and have no Zanii source.',
+    fields: [
+      ['0.1', 'Title', ['d:name']],
+      ['0.2', 'Organisation name', ['d:deployer_name', 'kyb:deployer']],
+      ['0.3', 'Phase', ['d:status']],
+      ['0.4', 'Region', ['d:region']],
+      ['0.5', 'One sentence description', ['d:summary']],
+      ['1.1', 'Name', ['d:name']],
+      ['1.2', 'Description', ['d:summary']],
+      ['1.3', 'Website URL', ['d:more_info_url']],
+      ['1.4', 'Contact email', ['d:contact_email']],
+      ['2.1.1', 'Organisation or department', ['d:deployer_name', 'kyb:deployer']],
+      ['2.1.2', 'Team', ['d:team']],
+      ['2.1.3', 'Senior responsible owner', ['d:senior_responsible_owner']],
+      ['2.1.4', 'Third party involvement', []],
+      ['2.1.4.1', 'Third party', ['d:provider_name', 'kyb:provider']],
+      ['2.1.4.2', 'Companies House Number', []],
+      ['2.1.4.3', 'Third party role', []],
+      ['2.1.4.4', 'Procurement procedure type', []],
+      ['2.1.4.5', 'Third party data access terms', []],
+      ['2.2.1', 'Detailed description', ['d:description']],
+      ['2.2.2', 'Benefits', []],
+      ['2.2.3', 'Previous process', []],
+      ['2.2.4', 'Alternatives considered', []],
+      ['2.3.1', 'Integration into broader operational process', []],
+      ['2.3.2', 'Human review', ['d:human_review']],
+      ['2.3.3', 'Frequency and scale of usage', []],
+      ['2.3.4', 'Required training', []],
+      ['2.3.5', 'Appeals and review', ['d:appeals']],
+      ['2.4.1.1', 'System architecture', []],
+      ['2.4.1.2', 'System-level input', []],
+      ['2.4.1.3', 'System-level output', []],
+      ['2.4.1.4', 'Maintenance', []],
+      ['2.4.1.5', 'Models', ['d:model']],
+      ['2.4.2.1', 'Model name', ['d:model']],
+      ['2.4.2.2', 'Model version', []],
+      ['2.4.2.3', 'Model task', []],
+      ['2.4.2.4', 'Model input', []],
+      ['2.4.2.5', 'Model output', []],
+      ['2.4.2.6', 'Model architecture', []],
+      ['2.4.2.7', 'Model performance', ['certify'], 'Zanii Certify assesses the deployed agent configuration against a profile; it is not the model\'s own performance metrics.'],
+      ['2.4.2.8', 'Datasets and their purposes', []],
+      ['2.4.3.1', 'Development data description', []],
+      ['2.4.3.2', 'Data modality', []],
+      ['2.4.3.3', 'Data quantities', []],
+      ['2.4.3.4', 'Sensitive attributes', []],
+      ['2.4.3.5', 'Data completeness and representativeness', []],
+      ['2.4.3.6', 'Data cleaning', []],
+      ['2.4.3.7', 'Data collection', []],
+      ['2.4.3.8', 'Data access and storage', []],
+      ['2.4.3.9', 'Data sharing agreements', []],
+      ['2.4.4.1', 'Data sources', []],
+      ['2.4.4.2', 'Sensitive attributes', []],
+      ['2.4.4.3', 'Data processing methods', []],
+      ['2.4.4.4', 'Data access and storage', []],
+      ['2.4.4.5', 'Data sharing agreements', []],
+      ['2.5.1', 'Impact assessments', ['assessments']],
+      ['2.5.2', 'Risks and mitigations', ['d:risks']],
+    ],
+  },
+  'eurocities-ats': {
+    format: 'eurocities-ats', format_version: 'Algorithmic Transparency Standard 0.3.1',
+    source_url: 'https://www.algoritmeregister.org/standard/schemas/registration-v0.3.1.schema.json',
+    guidance: 'Field names of the Algorithmic Transparency Standard 0.3.1 JSON schema (Eurocities; Amsterdam and Helsinki registers). Enum fields (status, domain, risk_category, algorithm_type, type) are passed through unchecked.',
+    fields: [
+      ['name', 'Name', ['d:name']],
+      ['description_short', 'Short description', ['d:summary']],
+      ['organization', 'Organization', ['d:deployer_name', 'kyb:deployer']],
+      ['department', 'Department', ['d:team']],
+      ['contact_email', 'Contact email', ['d:contact_email']],
+      ['contact_phone', 'Contact phone', []],
+      ['contact_name', 'Contact name', []],
+      ['area', 'Area', []],
+      ['domain', 'Domain', []],
+      ['website', 'Website', ['d:more_info_url']],
+      ['status', 'Status', ['d:status']],
+      ['remark', 'Remark', []],
+      ['decision_making_process', 'Decision making process', []],
+      ['goal', 'Goal', ['d:intended_purpose']],
+      ['impact', 'Impact', []],
+      ['risks', 'Risks', ['d:risks']],
+      ['risk_category', 'Risk category', []],
+      ['proportionality', 'Proportionality', []],
+      ['lawful_basis', 'Lawful basis', []],
+      ['documentation', 'Documentation', ['d:instructions_url']],
+      ['training_data', 'Training data', []],
+      ['source_data', 'Source data', []],
+      ['data_bias', 'Data bias', []],
+      ['connected_data_sources', 'Connected data sources', []],
+      ['DPIA_description', 'DPIA description', ['d:dpia_summary']],
+      ['DPIA_url', 'DPIA URL', ['d:dpia_url']],
+      ['algorithm_type', 'Type of algorithm', []],
+      ['description', 'Description', ['d:description']],
+      ['methods_and_models', 'Methods and models', ['d:model']],
+      ['performance', 'Performance', ['certify'], 'Zanii Certify assesses the deployed agent configuration against a profile; it is not the model\'s own performance metrics.'],
+      ['alternatives_considered', 'Alternatives considered', []],
+      ['product_information', 'Product information', []],
+      ['codebase_url', 'Codebase URL', []],
+      ['product_page', 'Product page', []],
+      ['AIA_description', 'Algorithmic impact assessment description', ['d:fria_summary']],
+      ['AIA_url', 'Algorithmic impact assessment URL', ['d:fria_url']],
+      ['monitoring', 'Monitoring', []],
+      ['type', 'Type of use of the algorithm', []],
+      ['human_intervention', 'Human intervention', ['d:human_review']],
+      ['objection_procedure', 'Objection procedure', ['d:appeals']],
+      ['rollback', 'Rollback', []],
+      ['standard_version', 'Version of the standard used', ['const:0.3.1']],
+      ['uuid', 'Unique identifier', []],
+      ['lang', 'Language', ['d:lang']],
+      ['publication_date', 'Publication date', []],
+      ['last_change_date', 'Last change date', []],
+      ['revision_date', 'Revision date', []],
+      ['revision_note', 'Revision note', []],
+      ['keywords', 'Keywords', []],
+    ],
+  },
+};
+
+// ---------------------------------------------------------------------------------- //
+// Exports
+// ---------------------------------------------------------------------------------- //
+
+export type ExportField =
+  | { id: string; name: string; value: FieldValue; source: string; note?: string }
+  | { id: string; name: string; value: null; reason: string; note?: string };
+
+export interface RegisterExport {
+  v: 1; type: 'zanii.ai_register.export'; format: Format; format_version: string; source_url: string; guidance: string;
+  system: string; entry: string; fields: ExportField[];
+}
+
+function certifySummary(c: NonNullable<RegisterEntry['certificate']>): string {
+  let s = `Zanii Certify ${c.profile ?? 'profile not stated'}`;
+  if (c.level !== null) s += ` Level ${c.level}`;
+  if (c.scheme) s += ` (${c.scheme})`;
+  s += `, status ${c.status ?? 'not stated'}`;
+  if (c.reason) s += ` (${c.reason})`;
+  if (c.evidence) s += `, production evidence ${c.evidence}`;
+  return `${s}, certificate ${c.hash}`;
+}
+
+const LABEL: Record<string, string> = {
+  'kyb:provider': 'a KYB record with ownerRole provider or both',
+  'kyb:deployer': 'a KYB record with ownerRole deployer or both',
+  certify: 'a Certify certificate',
+  assessments: 'describe.fria_summary or describe.dpia_summary',
+};
+
+function resolve(src: string, e: RegisterEntry): { value: FieldValue; source: string } | null {
+  if (src.startsWith('d:')) {
+    const v = e.describe[src.slice(2) as DescribeKey];
+    return v === undefined || v === '' || (Array.isArray(v) && !v.length) ? null : { value: v, source: `describe.${src.slice(2)}` };
+  }
+  if (src.startsWith('const:')) return { value: src.slice(6), source: 'const' };
+  if (src === 'kyb:provider' || src === 'kyb:deployer') {
+    const role = src.slice(4);
+    return e.kyb && (e.kyb.role === role || e.kyb.role === 'both') ? { value: e.kyb.entity.name, source: 'kyb' } : null;
+  }
+  if (src === 'name+agents') {
+    const name = e.describe.name;
+    return { value: typeof name === 'string' && name ? `${name} (${e.agents.join(', ')})` : e.agents.join(', '), source: typeof name === 'string' && name ? 'describe.name+agents' : 'agents' };
+  }
+  if (src === 'certify') return e.certificate ? { value: certifySummary(e.certificate), source: 'certificate' } : null;
+  if (src === 'assessments') {
+    const out: string[] = [];
+    for (const [label, s, u] of [['FRIA', 'fria_summary', 'fria_url'], ['DPIA', 'dpia_summary', 'dpia_url']] as const) {
+      const sum = e.describe[s];
+      if (typeof sum === 'string' && sum) out.push(`${label}: ${sum}${typeof e.describe[u] === 'string' && e.describe[u] ? ` (${e.describe[u] as string})` : ''}`);
+    }
+    return out.length ? { value: out, source: 'describe.fria_summary+dpia_summary' } : null;
+  }
+  return fail(`unknown source ${src}`);
+}
+
+/** One export of an entry: a versioned field map, each field a value with its source or null with a reason. */
+export function exportEntry(entry: RegisterEntry, format: Format): RegisterExport {
+  const map = FIELD_MAPS[format] ?? fail(`unknown format ${String(format)}`);
+  const fields = map.fields.map(([id, name, sources, note]): ExportField => {
+    const o = entry.overrides?.[format]?.[id];
+    let f: ExportField;
+    const hit = o !== undefined ? { value: o, source: 'override' } : sources.map((s) => resolve(s, entry)).find((x) => x !== null);
+    if (hit) f = { id, name, value: hit.value, source: hit.source };
+    else {
+      const reason = sources.length
+        ? `not supplied: ${sources.map((s) => LABEL[s] ?? `describe.${s.slice(2)}`).join(' or ')}`
+        : `not supported by Zanii inputs: supply overrides["${format}"]["${id}"]`;
+      f = { id, name, value: null, reason };
+    }
+    if (note) f.note = note;
+    return f;
+  });
+  return { v: 1, type: 'zanii.ai_register.export', format, format_version: map.format_version, source_url: map.source_url, guidance: map.guidance, system: entry.system, entry: entryHash(entry), fields };
+}
+
+export const exportEuAiAct = (entry: RegisterEntry, section: 'A' | 'B' | 'C') =>
+  exportEntry(entry, `eu-ai-act-annex-viii-${section.toLowerCase()}` as Format);
+export const exportAtrs = (entry: RegisterEntry) => exportEntry(entry, 'uk-atrs');
+export const exportEurocities = (entry: RegisterEntry) => exportEntry(entry, 'eurocities-ats');
+
+/** `{ field id: value or null }`: for the Eurocities format this is the registration JSON object. */
+export function toRecord(x: RegisterExport): Record<string, FieldValue | null> {
+  return Object.fromEntries(x.fields.map((f) => [f.id, f.value]));
+}
+
+const cell = (v: unknown): string => {
+  const s = v === null || v === undefined ? '' : Array.isArray(v) ? v.join('; ') : String(v);
+  return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+};
+
+/** RFC 4180 CSV, one row per field: system, format, id, name, value, source, reason. */
+export function toCsv(exports: RegisterExport[]): string {
+  const rows = [['system', 'format', 'id', 'name', 'value', 'source', 'reason']];
+  for (const x of exports) for (const f of x.fields) rows.push([x.system, x.format, f.id, f.name, f.value as never, 'source' in f ? f.source : '', 'reason' in f ? f.reason : '']);
+  return rows.map((r) => r.map(cell).join(',')).join('\r\n') + '\r\n';
+}
+
+/** Canonical JSON (RFC 8785): the same bytes in TypeScript and Python. */
+export function toJson(x: unknown): string {
+  return new TextDecoder().decode(canonicalBytes(x));
+}
+
+// ---------------------------------------------------------------------------------- //
+// The signed register snapshot
+// ---------------------------------------------------------------------------------- //
+
+export type RegisterSnapshot = SignedObject<{ v: 1; type: 'zanii.ai_register'; regulator: string; jurisdiction: string; as_of: string; entries: RegisterEntry[] }>;
+
+/** Sign a snapshot of the register as the regulator or operator. Entries are sorted by `system`. */
+export function buildRegister(r: { regulator: string; jurisdiction: string; asOf: string; entries: RegisterEntry[] }, signerKey: Uint8Array): RegisterSnapshot {
+  if (!r?.regulator || !r.jurisdiction) fail('regulator and jurisdiction are required');
+  if (Number.isNaN(ms(r.asOf))) fail('asOf must be an ISO timestamp');
+  const entries = [...r.entries].sort((a, b) => (a.system < b.system ? -1 : a.system > b.system ? 1 : 0));
+  if (new Set(entries.map((e) => e.system)).size !== entries.length) fail('two entries have the same system id');
+  return signObject({ v: 1 as const, type: 'zanii.ai_register' as const, regulator: r.regulator, jurisdiction: r.jurisdiction, as_of: r.asOf, entries }, signerKey);
+}
+
+/** Signature by an allowed signer, entries sorted and distinct, evidence lists consistent, bindings for this jurisdiction. */
+export function verifyRegister(s: RegisterSnapshot, opts: { signers: string[] }): { ok: boolean; reasons: string[] } {
+  const reasons: string[] = [];
+  if (!s || typeof s !== 'object' || s.v !== 1 || s.type !== 'zanii.ai_register' || !Array.isArray(s.entries)) return { ok: false, reasons: ['not a zanii.ai_register snapshot (v1)'] };
+  if (!verifySignedObject(s)) reasons.push('bad signature');
+  else if (!opts?.signers?.length) reasons.push('no signers supplied: signer NOT checked');
+  else if (!opts.signers.includes(s.signer)) reasons.push('signed by a key that is not an allowed register signer');
+  if (Number.isNaN(ms(s.as_of))) reasons.push('as_of is not an ISO timestamp');
+  const ids = s.entries.map((e) => e?.system);
+  if (ids.some((id, i) => i > 0 && !(ids[i - 1]! < id!))) reasons.push('entries are not sorted and distinct by system');
+  for (const e of s.entries) {
+    if (!e || typeof e !== 'object') { reasons.push('an entry is not an object'); continue; }
+    if (evidenceOf(e).join() !== (Array.isArray(e.evidence) ? e.evidence.join() : '')) reasons.push(`entry ${e.system}: evidence does not match its records`);
+    if (e.jurisdiction && e.jurisdiction.jurisdiction !== s.jurisdiction) reasons.push(`entry ${e.system}: jurisdiction binding is for ${e.jurisdiction.jurisdiction}`);
+  }
+  return { ok: reasons.length === 0, reasons };
+}
+
+/** `buildRegister` with a raw key or a remote signer (HSM, KMS); all the same checks run. */
+export async function buildRegisterAsync(r: { regulator: string; jurisdiction: string; asOf: string; entries: RegisterEntry[] }, signer: Uint8Array | RemoteSigner): Promise<RegisterSnapshot> {
+  if (signer instanceof Uint8Array) return buildRegister(r, signer);
+  const { sig: _sig, signer: _signer, ...fields } = buildRegister(r, new Uint8Array(32).fill(1));
+  return (await signObjectAsync(fields, signer)) as unknown as RegisterSnapshot;
+}