yam-flow 2.2.0 → 2.3.0

package/src/lib/trust-kernel.ts

@@ -21,6 +21,10 @@ export type LoopStageStatus = 'passed' | 'failed' | 'blocked' | 'skipped' | 'par
 export type LoopEvidenceLevel = 'none' | 'fixture' | 'smoke' | 'local' | 'real';
 export type ToolIntent = 'read_only' | 'write' | 'destructive' | 'runtime' | 'visual' | 'publish';
 export type ReadinessState = 'usable' | 'degraded' | 'blocked' | 'unknown';
+export type MissionLaneRole = 'implementer' | 'reviewer' | 'ux_verifier' | 'doctor' | 'other';
+export type MissionAccessMode = 'read_only' | 'write';
+export type MissionLifecycleStatus = 'pending' | 'running' | 'stopped' | 'failed' | 'cancelled';
+export type MissionOutcome = 'passed' | 'failed' | 'blocked' | 'ambiguous';
 
 export interface SafetyHit {
   level: SafetyLevel;
@@ -134,6 +138,53 @@ export interface MissionPatchEnvelope {
   truth_status: TruthStatus;
 }
 
+export interface MissionContractCheck {
+  id: string;
+  label: string;
+  status: 'pass' | 'fail' | 'warning';
+  next_action: string;
+}
+
+export interface MissionSubagentReceipt {
+  schema: 'yam.mission-subagent-receipt.v1';
+  receipt_id: string;
+  generated_at: string;
+  thread_id: string;
+  lane_id: string;
+  agent_id: string;
+  role: MissionLaneRole;
+  access_mode: MissionAccessMode;
+  lifecycle_status: MissionLifecycleStatus;
+  outcome: MissionOutcome;
+  assigned_scope: string;
+  changed_files: string[];
+  verification_evidence: string[];
+  remaining_risks: string[];
+  checks: MissionContractCheck[];
+  blockers: string[];
+  warnings: string[];
+  completion_eligible: boolean;
+  truth_status: TruthStatus;
+}
+
+export interface MissionCompletionGate {
+  schema: 'yam.mission-completion-gate.v1';
+  generated_at: string;
+  expected_thread_ids: string[];
+  receipt_count: number;
+  receipts: MissionSubagentReceipt[];
+  missing_thread_ids: string[];
+  duplicate_thread_ids: string[];
+  unexpected_thread_ids: string[];
+  invalid_thread_ids: string[];
+  read_only_violations: string[];
+  blockers: string[];
+  warnings: string[];
+  ready_to_claim_complete: boolean;
+  next_action: string;
+  truth_status: TruthStatus;
+}
+
 export interface RuntimeBackendEvidence {
   schema: 'yam.runtime-backend-evidence.v1';
   backend: RuntimeBackend;
@@ -300,6 +351,8 @@ export interface ProofSummary {
   unverified?: unknown;
   visualProvenance?: unknown;
   missionEnvelope?: unknown;
+  missionReceipt?: unknown;
+  missionCompletion?: unknown;
   rollbackHint?: unknown;
   runtimeBackendEvidence?: unknown;
   mediaProof?: unknown;
@@ -336,6 +389,8 @@ export interface YamCompletionProof {
   runtime: string[];
   visualProvenance: string[];
   missionEnvelope: string[];
+  missionReceipt: string[];
+  missionCompletion: string[];
   rollbackHint: string[];
   runtimeBackendEvidence: string[];
   mediaProof: string[];
@@ -509,6 +564,137 @@ export function buildMissionPatchEnvelope(input: Partial<MissionPatchEnvelope> =
   };
 }
 
+export function buildMissionSubagentReceipt(input: Partial<MissionSubagentReceipt> & Record<string, unknown> = {}): MissionSubagentReceipt {
+  const role = normalizeMissionLaneRole(input.role);
+  const accessMode = normalizeMissionAccessMode(input.access_mode, role);
+  const lifecycleStatus = normalizeMissionLifecycleStatus(input.lifecycle_status);
+  const outcome = normalizeMissionOutcome(input.outcome);
+  const threadId = String(input.thread_id || '');
+  const assignedScope = String(input.assigned_scope || '');
+  const changedFiles = asList(input.changed_files);
+  const verificationEvidence = asList(input.verification_evidence);
+  const remainingRisks = asList(input.remaining_risks);
+  const readOnlyRole = role === 'reviewer' || role === 'doctor';
+  const checks = [
+    missionContractCheck('thread_id', 'Thread id is recorded', Boolean(threadId), 'record --thread-id for every spawned thread'),
+    missionContractCheck('assigned_scope', 'Assigned scope is recorded', Boolean(assignedScope), 'record the bounded lane scope'),
+    missionContractCheck('read_only_role', 'Reviewer and doctor lanes stay read-only', !readOnlyRole || (accessMode === 'read_only' && changedFiles.length === 0), 'rerun reviewer/doctor without write access or changed files'),
+    missionContractCheck('terminal_lifecycle', 'Lifecycle reached a terminal state', ['stopped', 'failed', 'cancelled'].includes(lifecycleStatus), 'wait for a terminal lifecycle event before finalization'),
+    missionContractCheck('explicit_outcome', 'Outcome is explicit and unambiguous', outcome !== 'ambiguous', 'record passed, failed, or blocked; a stop event alone is not success evidence'),
+    missionContractCheck('passed_evidence', 'Passed outcome has verification evidence', outcome !== 'passed' || verificationEvidence.length > 0, 'attach at least one concrete verification item for a passed outcome')
+  ];
+  const blockers = checks.filter((check) => check.status === 'fail').map((check) => `${check.id}: ${check.next_action}`);
+  if (outcome === 'failed' || outcome === 'blocked') blockers.push(`outcome_${outcome}: resolve or hand off this thread before mission completion`);
+  if ((lifecycleStatus === 'failed' || lifecycleStatus === 'cancelled') && outcome === 'passed') {
+    blockers.push('lifecycle_outcome_conflict: a failed or cancelled lifecycle cannot claim a passed outcome');
+  }
+  const warnings = remainingRisks.length ? ['remaining risks are recorded and must be included in the mission handoff'] : [];
+  const completionEligible = blockers.length === 0 && lifecycleStatus === 'stopped' && outcome === 'passed';
+  const truth: TruthStatus = completionEligible ? 'verified' : blockers.length ? 'blocked' : 'partial';
+  return {
+    schema: 'yam.mission-subagent-receipt.v1',
+    receipt_id: String(input.receipt_id || `receipt-${threadId || 'unassigned'}`),
+    generated_at: String(input.generated_at || new Date().toISOString()),
+    thread_id: threadId,
+    lane_id: String(input.lane_id || threadId),
+    agent_id: String(input.agent_id || ''),
+    role,
+    access_mode: accessMode,
+    lifecycle_status: lifecycleStatus,
+    outcome,
+    assigned_scope: assignedScope,
+    changed_files: changedFiles,
+    verification_evidence: verificationEvidence,
+    remaining_risks: remainingRisks,
+    checks,
+    blockers: uniqueStrings(blockers),
+    warnings,
+    completion_eligible: completionEligible,
+    truth_status: truth
+  };
+}
+
+export function buildMissionCompletionGate(input: Partial<MissionCompletionGate> & Record<string, unknown> = {}): MissionCompletionGate {
+  const expectedThreadIds = uniqueStrings(asList(input.expected_thread_ids));
+  const receipts = asObjectList(input.receipts).map((receipt) => buildMissionSubagentReceipt(receipt));
+  const receiptCounts = new Map<string, number>();
+  for (const receipt of receipts) {
+    receiptCounts.set(receipt.thread_id, (receiptCounts.get(receipt.thread_id) || 0) + 1);
+  }
+  const missingThreadIds = expectedThreadIds.filter((threadId) => !receiptCounts.has(threadId));
+  const duplicateThreadIds = [...receiptCounts.entries()].filter(([, count]) => count > 1).map(([threadId]) => threadId).filter(Boolean);
+  const unexpectedThreadIds = uniqueStrings(receipts.map((receipt) => receipt.thread_id).filter((threadId) => threadId && !expectedThreadIds.includes(threadId)));
+  const expectedReceipts = receipts.filter((receipt) => expectedThreadIds.includes(receipt.thread_id));
+  const invalidThreadIds = uniqueStrings([
+    ...expectedReceipts.filter((receipt) => !receipt.completion_eligible).map((receipt) => receipt.thread_id),
+    ...receipts.filter((receipt) => !receipt.thread_id).map((receipt) => `missing:${receipt.receipt_id}`)
+  ]);
+  const readOnlyViolations = uniqueStrings(receipts
+    .filter((receipt) => receipt.checks.some((check) => check.id === 'read_only_role' && check.status === 'fail'))
+    .map((receipt) => receipt.thread_id || receipt.lane_id));
+  const blockers: string[] = [];
+  if (!expectedThreadIds.length) blockers.push('expected_thread_inventory_missing: record every spawned thread before finalization');
+  if (missingThreadIds.length) blockers.push(`missing_receipts: ${missingThreadIds.join(', ')}`);
+  if (duplicateThreadIds.length) blockers.push(`duplicate_receipts: ${duplicateThreadIds.join(', ')}`);
+  if (unexpectedThreadIds.length) blockers.push(`unexpected_receipts: ${unexpectedThreadIds.join(', ')}`);
+  if (invalidThreadIds.length) blockers.push(`invalid_or_incomplete_receipts: ${invalidThreadIds.join(', ')}`);
+  if (readOnlyViolations.length) blockers.push(`read_only_contract_violations: ${readOnlyViolations.join(', ')}`);
+  blockers.push(...asList(input.blockers));
+  const warnings = uniqueStrings(asList(input.warnings));
+  const ready = blockers.length === 0 && expectedReceipts.length === expectedThreadIds.length;
+  return {
+    schema: 'yam.mission-completion-gate.v1',
+    generated_at: String(input.generated_at || new Date().toISOString()),
+    expected_thread_ids: expectedThreadIds,
+    receipt_count: receipts.length,
+    receipts,
+    missing_thread_ids: missingThreadIds,
+    duplicate_thread_ids: duplicateThreadIds,
+    unexpected_thread_ids: unexpectedThreadIds,
+    invalid_thread_ids: invalidThreadIds,
+    read_only_violations: readOnlyViolations,
+    blockers: uniqueStrings(blockers),
+    warnings,
+    ready_to_claim_complete: ready,
+    next_action: ready ? 'attach this gate to the mission proof summary' : blockers[0] || 'resolve mission receipt warnings',
+    truth_status: ready ? 'verified' : 'blocked'
+  };
+}
+
+function missionContractCheck(id: string, label: string, passed: boolean, nextAction: string): MissionContractCheck {
+  return {
+    id,
+    label,
+    status: passed ? 'pass' : 'fail',
+    next_action: nextAction
+  };
+}
+
+function normalizeMissionLaneRole(value: unknown = ''): MissionLaneRole {
+  const text = String(value || '').toLowerCase().replace(/[- ]/g, '_');
+  if (['implementer', 'reviewer', 'ux_verifier', 'doctor'].includes(text)) return text as MissionLaneRole;
+  return 'other';
+}
+
+function normalizeMissionAccessMode(value: unknown = '', role: MissionLaneRole = 'other'): MissionAccessMode {
+  const text = String(value || '').toLowerCase().replace(/[- ]/g, '_');
+  if (text === 'read_only' || text === 'readonly') return 'read_only';
+  if (text === 'write') return 'write';
+  return role === 'reviewer' || role === 'doctor' ? 'read_only' : 'write';
+}
+
+function normalizeMissionLifecycleStatus(value: unknown = ''): MissionLifecycleStatus {
+  const text = String(value || '').toLowerCase();
+  if (['pending', 'running', 'stopped', 'failed', 'cancelled'].includes(text)) return text as MissionLifecycleStatus;
+  return 'pending';
+}
+
+function normalizeMissionOutcome(value: unknown = ''): MissionOutcome {
+  const text = String(value || '').toLowerCase();
+  if (['passed', 'failed', 'blocked'].includes(text)) return text as MissionOutcome;
+  return 'ambiguous';
+}
+
 export function buildRuntimeBackendEvidence(input: Partial<RuntimeBackendEvidence> = {}): RuntimeBackendEvidence {
   const backend = normalizeRuntimeBackend(input.backend);
   const claim = normalizeRuntimeClaim(input.claim);
@@ -997,6 +1183,12 @@ export function classifyEvidenceTruth(summary: ProofSummary = {}, options: Proof
   for (const envelope of asList(summary.missionEnvelope)) {
     rows.push(evidenceRow('evidence', envelope, metadataTruth(envelope, 'partial')));
   }
+  for (const receipt of asList(summary.missionReceipt)) {
+    rows.push(evidenceRow('evidence', receipt, metadataTruth(receipt, 'partial')));
+  }
+  for (const completion of asList(summary.missionCompletion)) {
+    rows.push(evidenceRow('evidence', completion, metadataTruth(completion, 'partial')));
+  }
   for (const rollback of asList(summary.rollbackHint)) {
     rows.push(evidenceRow('evidence', rollback, metadataTruth(rollback, 'partial')));
   }
@@ -1046,6 +1238,19 @@ export function applyProofTruthCaps(summary: ProofSummary = {}, options: ProofOp
       unverified.push('ueye_design_completion_not_verified');
     }
   }
+  const missionRoute = String(summary.route || '').replace(/^\$/, '').toLowerCase() === 'mission';
+  const missionCompletionValues = asValueList(summary.missionCompletion);
+  if (missionRoute && ['verified', 'proven'].includes(requested)) {
+    if (!missionCompletionValues.length) {
+      cappedTruth = weakestTruth(cappedTruth, 'partial');
+      unverified.push('mission_completion_gate_missing');
+    } else {
+      const missionTruth = missionCompletionCap(missionCompletionValues);
+      cappedTruth = weakestTruth(cappedTruth, missionTruth);
+      if (missionTruth === 'blocked') blockers.push('mission_completion_gate_blocked');
+      if (!['verified', 'proven'].includes(missionTruth)) unverified.push('mission_completion_not_verified');
+    }
+  }
   if (requested !== cappedTruth) {
     caps.push(`requested ${requested} capped to ${cappedTruth} by evidence`);
   }
@@ -1102,6 +1307,8 @@ export function buildYamCompletionProof(summary: ProofSummary = {}, options: Pro
     runtime: asList(summary.runtime),
     visualProvenance: asList(summary.visualProvenance),
     missionEnvelope: asList(summary.missionEnvelope),
+    missionReceipt: asList(summary.missionReceipt),
+    missionCompletion: asList(summary.missionCompletion),
     rollbackHint: asList(summary.rollbackHint),
     runtimeBackendEvidence: asList(summary.runtimeBackendEvidence),
     mediaProof: asList(summary.mediaProof),
@@ -1181,6 +1388,17 @@ function designCompletionCap(value: unknown = ''): TruthStatus | null {
   return items.reduce<TruthStatus>((weakest, item) => weakestTruth(weakest, readStructuredTruth(item, 'partial')), 'proven');
 }
 
+function missionCompletionCap(value: unknown = ''): TruthStatus {
+  const items = asValueList(value);
+  if (!items.length) return 'partial';
+  return items.reduce<TruthStatus>((weakest, item) => {
+    const parsed = parseStructuredValue(item);
+    if (!parsed || typeof parsed !== 'object') return weakestTruth(weakest, 'blocked');
+    const gate = buildMissionCompletionGate(parsed as Record<string, unknown>);
+    return weakestTruth(weakest, gate.truth_status);
+  }, 'proven');
+}
+
 function strongestSupportedTruth(rows: EvidenceRow[] = []): TruthStatus {
   if (rows.some((row) => row.truth === 'blocked')) return 'blocked';
   if (rows.some((row) => row.truth === 'real_required_missing')) return 'real_required_missing';
@@ -1301,6 +1519,27 @@ function asList(value?: unknown): string[] {
   return Array.isArray(value) ? value.filter(Boolean).map(String) : [String(value)].filter(Boolean);
 }
 
+function asValueList(value?: unknown): unknown[] {
+  if (value === undefined || value === null || value === '') return [];
+  return Array.isArray(value) ? value.filter(Boolean) : [value];
+}
+
+function parseStructuredValue(value: unknown): Record<string, unknown> | null {
+  if (value && typeof value === 'object') return value as Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(String(value || ''));
+    return parsed && typeof parsed === 'object' ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
+function asObjectList(value?: unknown): Array<Record<string, unknown>> {
+  if (!value) return [];
+  const items = Array.isArray(value) ? value : [value];
+  return items.filter((item) => Boolean(item) && typeof item === 'object') as Array<Record<string, unknown>>;
+}
+
 function uniqueStrings(values: unknown[] = []): string[] {
   return [...new Set(values.filter(Boolean).map(String))];
 }

package/src/lib/ueye-artifacts.ts

@@ -0,0 +1,354 @@
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+export interface InspectedImageFile {
+  path: string;
+  sha256: string;
+  bytes: number;
+  dimensions: string;
+}
+
+export interface UeyeAssetEntry {
+  id: string;
+  file_path: string;
+  source_url: string;
+  source_page_url: string;
+  retrieved_at: string;
+  license_note: string;
+  operator_provided: boolean;
+  do_not_replace: boolean;
+  allowed_for_edit: boolean;
+  sha256: string;
+  bytes: number;
+  dimensions: string;
+}
+
+export interface UeyeAssetManifest {
+  schema: 'yam.ueye-asset-manifest.v1';
+  updated_at: string;
+  assets: UeyeAssetEntry[];
+}
+
+export interface UeyeRevisionEntry {
+  artifact_id: string;
+  round: number;
+  source_path: string;
+  archived_path: string;
+  archived_at: string;
+  sha256: string;
+  bytes: number;
+  dimensions: string;
+}
+
+export interface UeyeRevisionHistory {
+  schema: 'yam.ueye-revision-history.v1';
+  updated_at: string;
+  revisions: UeyeRevisionEntry[];
+}
+
+export async function inspectImageFile(file: string): Promise<InspectedImageFile> {
+  const absolute = path.resolve(file);
+  const buffer = await fsp.readFile(absolute);
+  const stat = await fsp.stat(absolute);
+  return {
+    path: absolute,
+    sha256: createHash('sha256').update(buffer).digest('hex'),
+    bytes: stat.size,
+    dimensions: imageDimensions(buffer)
+  };
+}
+
+export async function upsertUeyeAsset(input: {
+  manifest_path: string;
+  id: string;
+  file: string;
+  source_url?: string;
+  source_page_url?: string;
+  retrieved_at?: string;
+  license_note?: string;
+  operator_provided?: boolean;
+  do_not_replace?: boolean;
+  allowed_for_edit?: boolean;
+  replace?: boolean;
+}) {
+  const manifestPath = path.resolve(input.manifest_path);
+  const id = safeId(input.id, 'asset id');
+  const info = await inspectImageFile(input.file);
+  validateOptionalHttpUrl(input.source_url, 'source_url');
+  validateOptionalHttpUrl(input.source_page_url, 'source_page_url');
+  const manifest = await readAssetManifest(manifestPath);
+  const existingIndex = manifest.assets.findIndex((asset) => asset.id === id);
+  const existing = existingIndex >= 0 ? manifest.assets[existingIndex] : null;
+  if (existing?.do_not_replace && existing.sha256 !== info.sha256 && !input.replace) {
+    throw new Error(`asset ${id} is protected by do_not_replace; pass --replace only after explicit review`);
+  }
+  const duplicate = manifest.assets.find((asset) => asset.id !== id && asset.sha256 === info.sha256);
+  if (duplicate) throw new Error(`asset content already exists as ${duplicate.id}; reuse that asset id`);
+  const entry: UeyeAssetEntry = {
+    id,
+    file_path: relativePortablePath(path.dirname(manifestPath), info.path),
+    source_url: String(input.source_url ?? existing?.source_url ?? ''),
+    source_page_url: String(input.source_page_url ?? existing?.source_page_url ?? ''),
+    retrieved_at: String(input.retrieved_at ?? existing?.retrieved_at ?? new Date().toISOString()),
+    license_note: String(input.license_note ?? existing?.license_note ?? ''),
+    operator_provided: input.operator_provided ?? existing?.operator_provided ?? (!input.source_url && !input.source_page_url),
+    do_not_replace: input.do_not_replace ?? existing?.do_not_replace ?? false,
+    allowed_for_edit: input.allowed_for_edit ?? existing?.allowed_for_edit ?? false,
+    sha256: info.sha256,
+    bytes: info.bytes,
+    dimensions: info.dimensions
+  };
+  if (existingIndex >= 0) manifest.assets[existingIndex] = entry;
+  else manifest.assets.push(entry);
+  manifest.assets.sort((left, right) => left.id.localeCompare(right.id));
+  manifest.updated_at = new Date().toISOString();
+  await writeJsonAtomic(manifestPath, manifest);
+  const warnings = assetWarnings(entry);
+  return {
+    schema: 'yam.ueye-asset-update.v1',
+    action: existing ? 'updated' : 'added',
+    manifest_path: manifestPath,
+    asset: entry,
+    warnings,
+    next_action: warnings[0] || 'run `yam ueye asset verify` before relying on this manifest for a done claim',
+    truth_status: warnings.length ? 'partial' : 'verified'
+  };
+}
+
+export async function verifyUeyeAssetManifest(manifestFile: string) {
+  const manifestPath = path.resolve(manifestFile);
+  const manifest = await readAssetManifest(manifestPath, false);
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const seenHashes = new Map<string, string>();
+  for (const asset of manifest.assets) {
+    try {
+      validateOptionalHttpUrl(asset.source_url, `${asset.id}.source_url`);
+      validateOptionalHttpUrl(asset.source_page_url, `${asset.id}.source_page_url`);
+      const file = resolveManifestFile(manifestPath, asset.file_path);
+      const info = await inspectImageFile(file);
+      if (info.sha256 !== asset.sha256) errors.push(`${asset.id}: sha256 mismatch; the asset changed after it was recorded`);
+      if (asset.bytes && info.bytes !== asset.bytes) errors.push(`${asset.id}: byte size mismatch`);
+      if (asset.dimensions && info.dimensions !== asset.dimensions) errors.push(`${asset.id}: dimensions mismatch`);
+      const duplicate = seenHashes.get(info.sha256);
+      if (duplicate && duplicate !== asset.id) errors.push(`${asset.id}: duplicates ${duplicate} by sha256`);
+      else seenHashes.set(info.sha256, asset.id);
+      warnings.push(...assetWarnings(asset));
+    } catch (error) {
+      errors.push(`${asset.id}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (!manifest.assets.length) errors.push('asset manifest is empty');
+  const uniqueWarnings = uniqueStrings(warnings);
+  return {
+    schema: 'yam.ueye-asset-verification.v1',
+    manifest_path: manifestPath,
+    asset_count: manifest.assets.length,
+    protected_count: manifest.assets.filter((asset) => asset.do_not_replace).length,
+    editable_count: manifest.assets.filter((asset) => asset.allowed_for_edit).length,
+    errors: uniqueStrings(errors),
+    warnings: uniqueWarnings,
+    ready: errors.length === 0,
+    next_action: errors[0] || uniqueWarnings[0] || 'attach this manifest verification to the Ueye report when asset provenance matters',
+    truth_status: errors.length ? 'blocked' : uniqueWarnings.length ? 'partial' : 'verified'
+  };
+}
+
+export async function archiveUeyeRevision(input: {
+  file: string;
+  root: string;
+  manifest_path?: string;
+  round: number;
+  artifact_id?: string;
+}) {
+  const round = Number(input.round);
+  if (!Number.isInteger(round) || round < 1) throw new Error('revision round must be a positive integer');
+  const source = await inspectImageFile(input.file);
+  const root = path.resolve(input.root);
+  const manifestPath = path.resolve(input.manifest_path || path.join(root, 'manifest.json'));
+  const extension = path.extname(source.path);
+  const artifactId = safeId(input.artifact_id || path.basename(source.path, extension), 'artifact id');
+  const roundDir = path.join(root, `r${round}`);
+  const archivedPath = path.join(roundDir, `${artifactId}${extension}`);
+  await fsp.mkdir(roundDir, { recursive: true });
+  let action = 'archived';
+  try {
+    await fsp.copyFile(source.path, archivedPath, fsConstants.COPYFILE_EXCL);
+  } catch (error: any) {
+    if (error?.code !== 'EEXIST') throw error;
+    const existing = await inspectImageFile(archivedPath);
+    if (existing.sha256 !== source.sha256) {
+      throw new Error(`revision r${round}/${artifactId} already exists with different content; choose a new round`);
+    }
+    action = 'already_archived';
+  }
+  const history = await readRevisionHistory(manifestPath);
+  const existingIndex = history.revisions.findIndex((entry) => entry.round === round && entry.artifact_id === artifactId);
+  const entry: UeyeRevisionEntry = {
+    artifact_id: artifactId,
+    round,
+    source_path: source.path,
+    archived_path: relativePortablePath(path.dirname(manifestPath), archivedPath),
+    archived_at: new Date().toISOString(),
+    sha256: source.sha256,
+    bytes: source.bytes,
+    dimensions: source.dimensions
+  };
+  if (existingIndex >= 0) {
+    if (history.revisions[existingIndex].sha256 !== entry.sha256) {
+      throw new Error(`revision history already records different content for r${round}/${artifactId}`);
+    }
+    entry.archived_at = history.revisions[existingIndex].archived_at;
+    history.revisions[existingIndex] = entry;
+  } else {
+    history.revisions.push(entry);
+  }
+  history.revisions.sort((left, right) => left.round - right.round || left.artifact_id.localeCompare(right.artifact_id));
+  history.updated_at = new Date().toISOString();
+  await writeJsonAtomic(manifestPath, history);
+  return {
+    schema: 'yam.ueye-revision-archive.v1',
+    action,
+    manifest_path: manifestPath,
+    revision: entry,
+    next_action: 'edit the live artifact, then use a later round for the next preserved version',
+    truth_status: 'verified'
+  };
+}
+
+export async function verifyUeyeRevisionHistory(manifestFile: string) {
+  const manifestPath = path.resolve(manifestFile);
+  const history = await readRevisionHistory(manifestPath, false);
+  const errors: string[] = [];
+  const seen = new Set<string>();
+  for (const revision of history.revisions) {
+    const key = `${revision.round}:${revision.artifact_id}`;
+    if (seen.has(key)) errors.push(`${key}: duplicate revision entry`);
+    seen.add(key);
+    try {
+      const file = resolveManifestFile(manifestPath, revision.archived_path);
+      const info = await inspectImageFile(file);
+      if (info.sha256 !== revision.sha256) errors.push(`${key}: sha256 mismatch; archived content changed`);
+      if (revision.bytes && info.bytes !== revision.bytes) errors.push(`${key}: byte size mismatch`);
+      if (revision.dimensions && info.dimensions !== revision.dimensions) errors.push(`${key}: dimensions mismatch`);
+    } catch (error) {
+      errors.push(`${key}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (!history.revisions.length) errors.push('revision history is empty');
+  return {
+    schema: 'yam.ueye-revision-verification.v1',
+    manifest_path: manifestPath,
+    revision_count: history.revisions.length,
+    rounds: [...new Set(history.revisions.map((entry) => entry.round))].sort((left, right) => left - right),
+    errors: uniqueStrings(errors),
+    ready: errors.length === 0,
+    next_action: errors[0] || 'attach this revision history to the Ueye report when iterative visual work matters',
+    truth_status: errors.length ? 'blocked' : 'verified'
+  };
+}
+
+async function readAssetManifest(file: string, allowMissing = true): Promise<UeyeAssetManifest> {
+  try {
+    const data = JSON.parse(await fsp.readFile(file, 'utf8'));
+    if (data.schema !== 'yam.ueye-asset-manifest.v1' || !Array.isArray(data.assets)) throw new Error('invalid Ueye asset manifest schema');
+    return data;
+  } catch (error: any) {
+    if (allowMissing && error?.code === 'ENOENT') return { schema: 'yam.ueye-asset-manifest.v1', updated_at: '', assets: [] };
+    throw error;
+  }
+}
+
+async function readRevisionHistory(file: string, allowMissing = true): Promise<UeyeRevisionHistory> {
+  try {
+    const data = JSON.parse(await fsp.readFile(file, 'utf8'));
+    if (data.schema !== 'yam.ueye-revision-history.v1' || !Array.isArray(data.revisions)) throw new Error('invalid Ueye revision history schema');
+    return data;
+  } catch (error: any) {
+    if (allowMissing && error?.code === 'ENOENT') return { schema: 'yam.ueye-revision-history.v1', updated_at: '', revisions: [] };
+    throw error;
+  }
+}
+
+async function writeJsonAtomic(file: string, value: unknown) {
+  await fsp.mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await fsp.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    await fsp.rename(temporary, file);
+  } finally {
+    await fsp.rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+function validateOptionalHttpUrl(value: unknown, label: string) {
+  const text = String(value || '');
+  if (!text) return;
+  const url = new URL(text);
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') throw new Error(`${label} must use http or https`);
+}
+
+function assetWarnings(asset: UeyeAssetEntry): string[] {
+  const warnings: string[] = [];
+  if (!asset.source_url && !asset.source_page_url && !asset.operator_provided) warnings.push(`${asset.id}: source provenance is missing`);
+  if (!asset.license_note) warnings.push(`${asset.id}: license_note is missing; usage rights were not recorded`);
+  if (asset.dimensions === 'unknown') warnings.push(`${asset.id}: image dimensions are unknown`);
+  return warnings;
+}
+
+function safeId(value: unknown, label: string): string {
+  const text = String(value || '');
+  if (!/^[A-Za-z0-9._-]{1,64}$/.test(text)) throw new Error(`${label} must match [A-Za-z0-9._-] and be at most 64 characters`);
+  return text;
+}
+
+function relativePortablePath(base: string, target: string): string {
+  return path.relative(base, target).split(path.sep).join('/') || path.basename(target);
+}
+
+function resolveManifestFile(manifestPath: string, file: string): string {
+  return path.isAbsolute(file) ? file : path.resolve(path.dirname(manifestPath), file);
+}
+
+function imageDimensions(buffer: Buffer): string {
+  const png = pngDimensions(buffer);
+  if (png) return png;
+  const jpeg = jpegDimensions(buffer);
+  if (jpeg) return jpeg;
+  const gif = gifDimensions(buffer);
+  if (gif) return gif;
+  return 'unknown';
+}
+
+function pngDimensions(buffer: Buffer): string {
+  if (buffer.length < 24) return '';
+  if (buffer.readUInt32BE(0) !== 0x89504e47 || buffer.readUInt32BE(4) !== 0x0d0a1a0a) return '';
+  return `${buffer.readUInt32BE(16)}x${buffer.readUInt32BE(20)}`;
+}
+
+function gifDimensions(buffer: Buffer): string {
+  if (buffer.length < 10) return '';
+  const signature = buffer.toString('ascii', 0, 6);
+  if (signature !== 'GIF87a' && signature !== 'GIF89a') return '';
+  return `${buffer.readUInt16LE(6)}x${buffer.readUInt16LE(8)}`;
+}
+
+function jpegDimensions(buffer: Buffer): string {
+  if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) return '';
+  let offset = 2;
+  while (offset + 9 < buffer.length) {
+    if (buffer[offset] !== 0xff) return '';
+    const marker = buffer[offset + 1];
+    const length = buffer.readUInt16BE(offset + 2);
+    if (marker >= 0xc0 && marker <= 0xc3) return `${buffer.readUInt16BE(offset + 7)}x${buffer.readUInt16BE(offset + 5)}`;
+    if (length < 2) return '';
+    offset += 2 + length;
+  }
+  return '';
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))];
+}