@complior/engine 0.9.0

package/src/domain/passport/import/a2a-importer.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest';
+import { importFromA2A } from './a2a-importer.js';
+
+const validCard = {
+  schemaVersion: '1.0.0',
+  humanReadableId: 'test-agent',
+  agentVersion: '2.0.0',
+  name: 'Test Agent',
+  description: 'A test agent for compliance',
+  url: 'https://deploy.example.com/agent',
+  provider: { name: 'OpenAI', url: 'https://openai.com' },
+  capabilities: {
+    a2aVersion: '1.0.0',
+    supportedMessageParts: ['text'],
+    supportsPushNotifications: false,
+  },
+  skills: [
+    { id: 'skill-1', name: 'file_read', description: 'Tool capability: file_read' },
+    { id: 'skill-2', name: 'code_write', description: 'Tool capability: code_write' },
+  ],
+  tags: ['risk:high', 'autonomy:L3', 'type:autonomous', 'region:eu-west'],
+  lastUpdated: '2026-03-01T00:00:00Z',
+};
+
+describe('importFromA2A', () => {
+  it('maps humanReadableId to name', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.name).toBe('test-agent');
+  });
+
+  it('maps name to display_name', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.display_name).toBe('Test Agent');
+  });
+
+  it('maps description', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.description).toBe('A test agent for compliance');
+  });
+
+  it('maps agentVersion to version', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.version).toBe('2.0.0');
+  });
+
+  it('maps provider to model.provider', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.model?.provider).toBe('openai');
+  });
+
+  it('maps url to model.deployment', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.model?.deployment).toBe('https://deploy.example.com/agent');
+  });
+
+  it('maps skills to permissions.tools', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.permissions?.tools).toEqual(['file_read', 'code_write']);
+  });
+
+  it('parses risk tag to compliance.risk_class', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.compliance?.eu_ai_act?.risk_class).toBe('high');
+  });
+
+  it('parses autonomy tag to autonomy_level', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.autonomy_level).toBe('L3');
+  });
+
+  it('parses type tag', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.type).toBe('autonomous');
+  });
+
+  it('parses region tag to data_residency', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.model?.data_residency).toBe('eu-west');
+  });
+
+  it('sets source.mode to semi-auto', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.source?.mode).toBe('semi-auto');
+  });
+
+  it('sets source.generated_by to complior-a2a-import', () => {
+    const { passport } = importFromA2A(validCard);
+    expect(passport.source?.generated_by).toBe('complior-a2a-import');
+  });
+
+  it('reports fieldsImported', () => {
+    const { fieldsImported } = importFromA2A(validCard);
+    expect(fieldsImported).toContain('name');
+    expect(fieldsImported).toContain('display_name');
+    expect(fieldsImported).toContain('description');
+    expect(fieldsImported).toContain('permissions');
+  });
+
+  it('reports fieldsMissing', () => {
+    const { fieldsMissing } = importFromA2A(validCard);
+    expect(fieldsMissing).toContain('owner');
+    expect(fieldsMissing).toContain('framework');
+    expect(fieldsMissing).toContain('logging');
+  });
+
+  it('throws on invalid A2A card', () => {
+    expect(() => importFromA2A({ invalid: true })).toThrow('Invalid A2A Card');
+  });
+
+  it('handles card with no tags', () => {
+    const card = { ...validCard, tags: [] };
+    const { passport } = importFromA2A(card);
+    expect(passport.type).toBe('assistive'); // default
+    expect(passport.autonomy_level).toBe('L2'); // default
+  });
+
+  it('handles card with no skills', () => {
+    const card = { ...validCard, skills: [] };
+    const { passport } = importFromA2A(card);
+    expect(passport.permissions?.tools).toEqual([]);
+  });
+
+  it('handles unknown provider URL', () => {
+    const card = { ...validCard, provider: { name: 'Custom', url: 'https://custom.ai' } };
+    const { passport } = importFromA2A(card);
+    expect(passport.model?.provider).toBe('Custom');
+  });
+
+  it('generates unique agent_id with timestamp', () => {
+    const { passport: p1 } = importFromA2A(validCard);
+    expect(p1.agent_id).toMatch(/^imported-test-agent-\d+$/);
+  });
+});

package/src/domain/passport/import/a2a-importer.ts

@@ -0,0 +1,156 @@
+import { A2ACardSchema, PROVIDER_URLS, type A2ACard } from '../export/a2a-mapper.js';
+import type { AgentPassport, AgentType, AutonomyLevel, PassportRiskClass } from '../../../types/passport.types.js';
+import { ValidationError } from '../../../types/errors.js';
+
+export interface A2AImportResult {
+  readonly passport: AgentPassport;
+  readonly fieldsImported: readonly string[];
+  readonly fieldsMissing: readonly string[];
+}
+
+// Derive reverse map from shared PROVIDER_URLS (single source of truth)
+const PROVIDER_URL_TO_NAME: Readonly<Record<string, string>> = Object.freeze(
+  Object.fromEntries(Object.entries(PROVIDER_URLS).map(([k, v]) => [v, k]))
+);
+
+const resolveProviderName = (url: string): string =>
+  PROVIDER_URL_TO_NAME[url] ?? '';
+
+const parseTagValue = (tags: readonly string[], prefix: string): string =>
+  tags.find(t => t.startsWith(`${prefix}:`))?.slice(prefix.length + 1) ?? '';
+
+const VALID_AGENT_TYPES = new Set<AgentType>(['autonomous', 'assistive', 'hybrid']);
+const VALID_AUTONOMY_LEVELS = new Set<AutonomyLevel>(['L1', 'L2', 'L3', 'L4', 'L5']);
+const VALID_RISK_CLASSES = new Set<PassportRiskClass>(['prohibited', 'high', 'limited', 'minimal']);
+
+const toAgentType = (val: string): AgentType =>
+  VALID_AGENT_TYPES.has(val as AgentType) ? val as AgentType : 'assistive';
+
+const toAutonomyLevel = (val: string): AutonomyLevel =>
+  VALID_AUTONOMY_LEVELS.has(val as AutonomyLevel) ? val as AutonomyLevel : 'L2';
+
+const toRiskClass = (val: string): PassportRiskClass =>
+  VALID_RISK_CLASSES.has(val as PassportRiskClass) ? val as PassportRiskClass : 'minimal';
+
+export const importFromA2A = (data: unknown): A2AImportResult => {
+  const parsed = A2ACardSchema.safeParse(data);
+  if (!parsed.success) {
+    throw new ValidationError(`Invalid A2A Card: ${parsed.error.message}`);
+  }
+  const card: A2ACard = parsed.data;
+
+  const fieldsImported: string[] = [];
+  const allFields = [
+    '$schema', 'manifest_version', 'agent_id', 'name', 'display_name',
+    'description', 'version', 'created', 'updated', 'owner', 'type',
+    'autonomy_level', 'autonomy_evidence', 'framework', 'model',
+    'permissions', 'constraints', 'compliance', 'disclosure', 'logging',
+    'lifecycle', 'interop', 'source', 'signature',
+  ];
+
+  // Map A2A fields -> passport fields
+  const now = new Date().toISOString();
+
+  if (card.humanReadableId) fieldsImported.push('name');
+  if (card.name) fieldsImported.push('display_name');
+  if (card.description) fieldsImported.push('description');
+  if (card.agentVersion) fieldsImported.push('version');
+  if (card.provider?.name) fieldsImported.push('model');
+  if (card.skills.length > 0) fieldsImported.push('permissions');
+  if (card.url) fieldsImported.push('model.deployment');
+
+  // Parse tags for risk_class, autonomy_level, type
+  const riskClass = parseTagValue(card.tags, 'risk');
+  const autonomyLevel = parseTagValue(card.tags, 'autonomy');
+  const agentType = parseTagValue(card.tags, 'type');
+  const dataResidency = parseTagValue(card.tags, 'region');
+
+  if (riskClass) fieldsImported.push('compliance.risk_class');
+  if (autonomyLevel) fieldsImported.push('autonomy_level');
+  if (agentType) fieldsImported.push('type');
+
+  const fieldsMissing = allFields.filter(f => !fieldsImported.some(fi => fi === f || fi.startsWith(f)));
+
+  const passport: AgentPassport = {
+    $schema: 'https://complior.dev/schemas/agent-passport-v1.json',
+    manifest_version: '1.0.0',
+    agent_id: `imported-${card.humanReadableId}-${Date.now()}`,
+    name: card.humanReadableId,
+    display_name: card.name,
+    description: card.description,
+    version: card.agentVersion,
+    created: now,
+    updated: now,
+    owner: { team: '', contact: '', responsible_person: '' },
+    type: agentType ? toAgentType(agentType) : 'assistive',
+    autonomy_level: autonomyLevel ? toAutonomyLevel(autonomyLevel) : 'L2',
+    autonomy_evidence: {
+      human_approval_gates: 0,
+      unsupervised_actions: 0,
+      no_logging_actions: 0,
+      auto_rated: false,
+    },
+    framework: '',
+    model: {
+      provider: card.provider?.name ? resolveProviderName(card.provider.url) || card.provider.name : '',
+      model_id: '',
+      deployment: card.url || '',
+      data_residency: dataResidency,
+    },
+    permissions: {
+      tools: card.skills.map(s => s.name),
+      data_access: { read: [], write: [], delete: [] },
+      denied: [],
+    },
+    constraints: {
+      rate_limits: { max_actions_per_minute: 60 },
+      budget: { max_cost_per_session_usd: 10 },
+      human_approval_required: [],
+      prohibited_actions: [],
+    },
+    compliance: {
+      eu_ai_act: {
+        risk_class: riskClass ? toRiskClass(riskClass) : 'minimal',
+        applicable_articles: [],
+        deployer_obligations_met: [],
+        deployer_obligations_pending: [],
+      },
+      complior_score: 0,
+      last_scan: '',
+    },
+    disclosure: {
+      user_facing: false,
+      disclosure_text: '',
+      ai_marking: { responses_marked: false, method: '' },
+    },
+    logging: {
+      actions_logged: false,
+      retention_days: 180,
+      includes_decision_rationale: false,
+    },
+    lifecycle: {
+      status: 'draft',
+      deployed_since: '',
+      next_review: '',
+      review_frequency_days: 90,
+    },
+    interop: { mcp_servers: [] },
+    source: {
+      mode: 'semi-auto',
+      generated_by: 'complior-a2a-import',
+      code_analyzed: false,
+      fields_auto_filled: fieldsImported.slice(),
+      fields_manual: [],
+      confidence: 0.5,
+    },
+    signature: {
+      algorithm: '',
+      public_key: '',
+      signed_at: '',
+      hash: '',
+      value: '',
+    },
+  };
+
+  return { passport, fieldsImported, fieldsMissing };
+};

package/src/domain/passport/import/index.ts

@@ -0,0 +1,2 @@
+export { importFromA2A } from './a2a-importer.js';
+export type { A2AImportResult } from './a2a-importer.js';

package/src/domain/passport/index.ts

@@ -0,0 +1,32 @@
+// Discovery
+export { discoverAgents } from './discovery/agent-discovery.js';
+export { analyzeAutonomy } from './discovery/autonomy-analyzer.js';
+export type { AutonomyAnalysis } from './discovery/autonomy-analyzer.js';
+export { scanPermissions, scanPermissionsDetailed } from './discovery/permission-scanner.js';
+export type { DiscoveredPermissions, ToolFramework, DiscoveredTool, DiscoveredPermissionsDetailed } from './discovery/permission-scanner.js';
+
+// Builder
+export { mapDomain } from './builder/domain-mapper.js';
+export { buildPassport, resolveRiskClass, getApplicableArticles } from './builder/manifest-builder.js';
+export { inferDataResidency, computeNextReview, buildOversight, computeDeployerObligations } from './builder/manifest-builder.js';
+export { ALL_PASSPORT_FIELDS } from './builder/manifest-builder.js';
+export type { ProjectProfile, ExistingPassportDates, PassportBuildInput } from './builder/manifest-builder.js';
+export { computeManifestDiff } from './builder/manifest-diff.js';
+export type { ManifestDiffField, ManifestDiffResult } from './builder/manifest-diff.js';
+export { isPassportManifest, filterPassportManifests, extractRiskClass } from './builder/manifest-files.js';
+
+// Validation
+export { OBLIGATION_FIELD_MAP, getFieldValue, isNonEmpty, getRequiredFields, getMissingFields } from './obligation-field-map.js';
+export type { ObligationFieldMapping, MissingField } from './obligation-field-map.js';
+export { computeCompleteness, validatePassport } from './passport-validator.js';
+export type { ValidationError, CompletenessResult, ValidationResult } from './passport-validator.js';
+
+// Crypto
+export { generateKeyPair, loadOrCreateKeyPair, signPassport, verifyPassport } from './crypto-signer.js';
+
+// Compliance
+export { deriveDocStatusFromFindings, buildScanSummary, buildDocQualitySummary } from './scan-to-compliance.js';
+
+// Testing
+export { generateComplianceTests } from './test-generator.js';
+export type { TestGeneratorInput, GeneratedTestSuite } from './test-generator.js';

package/src/domain/passport/obligation-field-map.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest';
+import {
+  OBLIGATION_FIELD_MAP,
+  getFieldValue,
+  getRequiredFields,
+  getMissingFields,
+} from './obligation-field-map.js';
+import type { AgentPassport } from '../../types/passport.types.js';
+import { buildPassport } from './builder/manifest-builder.js';
+import type { PassportBuildInput } from './builder/manifest-builder.js';
+import { generateKeyPair, signPassport } from './crypto-signer.js';
+
+// --- Helper: create a fully signed manifest ---
+
+const buildTestManifest = (): AgentPassport => {
+  const input: PassportBuildInput = {
+    agent: {
+      name: 'test-agent',
+      entryFile: 'src/index.ts',
+      framework: 'OpenAI',
+      language: 'typescript',
+      detectedSdks: ['openai'],
+      detectedModels: ['gpt-4'],
+      confidence: 0.9,
+      sourceFiles: ['src/index.ts'],
+    },
+    autonomy: {
+      level: 'L3',
+      evidence: {
+        human_approval_gates: 2,
+        unsupervised_actions: 1,
+        no_logging_actions: 0,
+        auto_rated: true,
+      },
+      agentType: 'hybrid',
+    },
+    permissions: {
+      tools: ['search'],
+      dataAccess: { read: ['users'], write: [], delete: [] },
+      denied: [],
+      mcpServers: [],
+      humanApprovalRequired: ['deploy'],
+    },
+  };
+
+  const unsigned = buildPassport(input);
+  const { privateKey } = generateKeyPair();
+  const signature = signPassport(unsigned, privateKey);
+  return { ...unsigned, signature };
+};
+
+// --- Tests ---
+
+describe('obligation-field-map', () => {
+  it('has non-empty map', () => {
+    expect(OBLIGATION_FIELD_MAP.length).toBeGreaterThan(20);
+  });
+
+  it('all fields have valid obligation format', () => {
+    for (const mapping of OBLIGATION_FIELD_MAP) {
+      expect(mapping.obligation).toMatch(/^OBL-\d+[A-Z]?$/);
+    }
+  });
+
+  it('all fields have article reference', () => {
+    for (const mapping of OBLIGATION_FIELD_MAP) {
+      expect(mapping.article).toMatch(/^Art\.\d+/);
+    }
+  });
+
+  it('no duplicate fields', () => {
+    const fields = OBLIGATION_FIELD_MAP.map((m) => m.field);
+    expect(new Set(fields).size).toBe(fields.length);
+  });
+
+  it('required fields subset is non-empty', () => {
+    const required = getRequiredFields();
+    expect(required.length).toBeGreaterThan(10);
+    expect(required.every((m) => m.required)).toBe(true);
+  });
+});
+
+describe('getFieldValue', () => {
+  const manifest = buildTestManifest();
+
+  it('accesses top-level fields', () => {
+    expect(getFieldValue(manifest, 'name')).toBe('test-agent');
+    expect(getFieldValue(manifest, 'agent_id')).toMatch(/^ag_/);
+  });
+
+  it('accesses nested fields', () => {
+    expect(getFieldValue(manifest, 'owner.team')).toBeDefined();
+    expect(getFieldValue(manifest, 'compliance.complior_score')).toBeDefined();
+    expect(getFieldValue(manifest, 'model.provider')).toBeDefined();
+  });
+
+  it('returns undefined for missing paths', () => {
+    expect(getFieldValue(manifest, 'nonexistent.field')).toBeUndefined();
+    expect(getFieldValue(manifest, 'owner.nonexistent')).toBeUndefined();
+  });
+});
+
+describe('getMissingFields', () => {
+  it('returns gaps for manifest', () => {
+    const manifest = buildTestManifest();
+    const missing = getMissingFields(manifest);
+    // All missing fields should reference obligations
+    for (const m of missing) {
+      expect(m.obligation).toMatch(/^OBL-/);
+      expect(m.article).toMatch(/^Art\./);
+    }
+  });
+});

package/src/domain/passport/obligation-field-map.ts

@@ -0,0 +1,117 @@
+import type { AgentPassport } from '../../types/passport.types.js';
+
+// --- Types ---
+
+export interface ObligationFieldMapping {
+  readonly field: string;
+  readonly obligation: string;
+  readonly article: string;
+  readonly description: string;
+  readonly required: boolean;
+}
+
+export interface MissingField {
+  readonly field: string;
+  readonly obligation: string;
+  readonly article: string;
+  readonly description: string;
+}
+
+// --- Obligation → field mappings ---
+
+export const OBLIGATION_FIELD_MAP: readonly ObligationFieldMapping[] = [
+  // Identity (Art.49 — Registration)
+  { field: 'agent_id', obligation: 'OBL-049', article: 'Art.49(1)', description: 'Unique AI system identifier for EU database', required: true },
+  { field: 'name', obligation: 'OBL-049', article: 'Art.49(1)', description: 'AI system name for registration', required: true },
+  { field: 'display_name', obligation: 'OBL-049', article: 'Art.49(2)', description: 'Public-facing name of AI system', required: true },
+  { field: 'description', obligation: 'OBL-049', article: 'Art.49(3)', description: 'Description of AI system purpose', required: true },
+  { field: 'version', obligation: 'OBL-049', article: 'Art.49(1)', description: 'Version tracking for AI system', required: true },
+
+  // Ownership (Art.26(6) — Deployer responsible person)
+  { field: 'owner.team', obligation: 'OBL-012', article: 'Art.26(6)', description: 'Team responsible for AI system', required: true },
+  { field: 'owner.contact', obligation: 'OBL-012', article: 'Art.26(6)', description: 'Contact for AI system inquiries', required: true },
+  { field: 'owner.responsible_person', obligation: 'OBL-012', article: 'Art.26(6)', description: 'Designated responsible natural person', required: true },
+
+  // Autonomy (Art.14 — Human oversight)
+  { field: 'type', obligation: 'OBL-014', article: 'Art.14(1)', description: 'Agent type classification for oversight', required: true },
+  { field: 'autonomy_level', obligation: 'OBL-014', article: 'Art.14(1)', description: 'Autonomy level (L1-L5) for oversight requirements', required: true },
+  { field: 'autonomy_evidence.human_approval_gates', obligation: 'OBL-014', article: 'Art.14(4)', description: 'Number of human approval checkpoints', required: true },
+  { field: 'autonomy_evidence.unsupervised_actions', obligation: 'OBL-014', article: 'Art.14(4)', description: 'Number of unsupervised actions', required: true },
+
+  // Tech stack (Art.13 — Transparency)
+  { field: 'framework', obligation: 'OBL-013', article: 'Art.13(3)', description: 'AI framework used (for technical transparency)', required: false },
+  { field: 'model.provider', obligation: 'OBL-013', article: 'Art.13(3)', description: 'Model provider for transparency', required: true },
+  { field: 'model.model_id', obligation: 'OBL-013', article: 'Art.13(3)', description: 'Model identifier for traceability', required: true },
+  { field: 'model.data_residency', obligation: 'OBL-013', article: 'Art.13(3)', description: 'Data residency for GDPR alignment', required: false },
+
+  // Permissions (Art.26(4) — Deployer monitoring)
+  { field: 'permissions.tools', obligation: 'OBL-026', article: 'Art.26(4)', description: 'Tools accessible by AI agent', required: true },
+  { field: 'permissions.denied', obligation: 'OBL-026', article: 'Art.26(4)', description: 'Explicitly denied actions', required: false },
+
+  // Constraints (Art.9 — Risk management)
+  { field: 'constraints.rate_limits.max_actions_per_minute', obligation: 'OBL-009', article: 'Art.9(2)', description: 'Rate limits for risk mitigation', required: false },
+  { field: 'constraints.human_approval_required', obligation: 'OBL-014', article: 'Art.14(4)', description: 'Actions requiring human approval', required: true },
+  { field: 'constraints.prohibited_actions', obligation: 'OBL-005', article: 'Art.5', description: 'Prohibited AI practices', required: true },
+  { field: 'constraints.escalation_rules', obligation: 'OBL-014', article: 'Art.14(4)', description: 'Structured escalation rules for human oversight', required: false },
+  { field: 'permissions.data_boundaries', obligation: 'OBL-009', article: 'Art.9(2)', description: 'Data handling boundaries including PII and geographic restrictions', required: false },
+
+  // Compliance (Art.9 — Risk management system)
+  { field: 'compliance.eu_ai_act.risk_class', obligation: 'OBL-009', article: 'Art.9(1)', description: 'AI Act risk classification', required: true },
+  { field: 'compliance.complior_score', obligation: 'OBL-009', article: 'Art.9(4)', description: 'Overall compliance score', required: true },
+  { field: 'compliance.last_scan', obligation: 'OBL-009', article: 'Art.9(9)', description: 'Date of last compliance scan', required: true },
+
+  // Per-agent document status
+  { field: 'compliance.technical_documentation.documented', obligation: 'OBL-005', article: 'Art.11', description: 'Technical documentation exists for this AI system', required: false },
+  { field: 'compliance.declaration_of_conformity.documented', obligation: 'OBL-019', article: 'Art.47', description: 'Declaration of conformity issued', required: false },
+  { field: 'compliance.art5_screening.completed', obligation: 'OBL-002', article: 'Art.5', description: 'Art.5 prohibited practices screening completed', required: false },
+  { field: 'compliance.instructions_for_use.documented', obligation: 'OBL-007', article: 'Art.13', description: 'Instructions for use documented', required: false },
+
+  // Disclosure (Art.50 — Transparency for users)
+  { field: 'disclosure.user_facing', obligation: 'OBL-050', article: 'Art.50(1)', description: 'Whether AI system interacts with users', required: true },
+  { field: 'disclosure.disclosure_text', obligation: 'OBL-050', article: 'Art.50(1)', description: 'Disclosure text shown to users', required: true },
+  { field: 'disclosure.ai_marking.responses_marked', obligation: 'OBL-050', article: 'Art.50(2)', description: 'Whether AI-generated content is marked', required: true },
+
+  // Logging (Art.12 — Record-keeping)
+  { field: 'logging.actions_logged', obligation: 'OBL-012L', article: 'Art.12(1)', description: 'Whether agent actions are logged', required: true },
+  { field: 'logging.retention_days', obligation: 'OBL-012L', article: 'Art.12(3)', description: 'Log retention period in days', required: true },
+  { field: 'logging.includes_decision_rationale', obligation: 'OBL-012L', article: 'Art.12(2)', description: 'Whether decision rationale is logged', required: false },
+
+  // Lifecycle (Art.26(5) — Deployer monitoring)
+  { field: 'lifecycle.status', obligation: 'OBL-026L', article: 'Art.26(5)', description: 'Current lifecycle status', required: true },
+  { field: 'lifecycle.next_review', obligation: 'OBL-026L', article: 'Art.26(5)', description: 'Next scheduled review date', required: true },
+  { field: 'lifecycle.review_frequency_days', obligation: 'OBL-026L', article: 'Art.26(5)', description: 'Review frequency in days', required: false },
+] as const;
+
+// --- Field accessor ---
+
+export const getFieldValue = (manifest: AgentPassport, fieldPath: string): unknown => {
+  const parts = fieldPath.split('.');
+  let current: unknown = manifest;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+};
+
+// --- Helpers ---
+
+export const isNonEmpty = (value: unknown): boolean => {
+  if (value === null || value === undefined || value === '') return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === 'object') return Object.keys(value as Record<string, unknown>).length > 0;
+  return true;
+};
+
+export const getRequiredFields = (): readonly ObligationFieldMapping[] =>
+  OBLIGATION_FIELD_MAP.filter((m) => m.required);
+
+export const getMissingFields = (manifest: AgentPassport): readonly MissingField[] =>
+  OBLIGATION_FIELD_MAP
+    .filter((m) => m.required && !isNonEmpty(getFieldValue(manifest, m.field)))
+    .map(({ field, obligation, article, description }) => ({
+      field,
+      obligation,
+      article,
+      description,
+    }));