yam-flow 2.2.0 → 2.3.0

package/dist/lib/trust-kernel.js

@@ -162,6 +162,142 @@ export function buildMissionPatchEnvelope(input = {}) {
         truth_status: isTruthStatus(input.truth_status) ? input.truth_status : 'partial'
     };
 }
+export function buildMissionSubagentReceipt(input = {}) {
+    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 = 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 = {}) {
+    const expectedThreadIds = uniqueStrings(asList(input.expected_thread_ids));
+    const receipts = asObjectList(input.receipts).map((receipt) => buildMissionSubagentReceipt(receipt));
+    const receiptCounts = new Map();
+    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 = [];
+    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, label, passed, nextAction) {
+    return {
+        id,
+        label,
+        status: passed ? 'pass' : 'fail',
+        next_action: nextAction
+    };
+}
+function normalizeMissionLaneRole(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[- ]/g, '_');
+    if (['implementer', 'reviewer', 'ux_verifier', 'doctor'].includes(text))
+        return text;
+    return 'other';
+}
+function normalizeMissionAccessMode(value = '', role = 'other') {
+    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 = '') {
+    const text = String(value || '').toLowerCase();
+    if (['pending', 'running', 'stopped', 'failed', 'cancelled'].includes(text))
+        return text;
+    return 'pending';
+}
+function normalizeMissionOutcome(value = '') {
+    const text = String(value || '').toLowerCase();
+    if (['passed', 'failed', 'blocked'].includes(text))
+        return text;
+    return 'ambiguous';
+}
 export function buildRuntimeBackendEvidence(input = {}) {
     const backend = normalizeRuntimeBackend(input.backend);
     const claim = normalizeRuntimeClaim(input.claim);
@@ -661,6 +797,12 @@ export function classifyEvidenceTruth(summary = {}, options = {}) {
     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')));
     }
@@ -715,6 +857,22 @@ export function applyProofTruthCaps(summary = {}, options = {}) {
             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`);
     }
@@ -769,6 +927,8 @@ export function buildYamCompletionProof(summary = {}, options = {}) {
         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),
@@ -854,6 +1014,18 @@ function designCompletionCap(value = '') {
         return null;
     return items.reduce((weakest, item) => weakestTruth(weakest, readStructuredTruth(item, 'partial')), 'proven');
 }
+function missionCompletionCap(value = '') {
+    const items = asValueList(value);
+    if (!items.length)
+        return 'partial';
+    return items.reduce((weakest, item) => {
+        const parsed = parseStructuredValue(item);
+        if (!parsed || typeof parsed !== 'object')
+            return weakestTruth(weakest, 'blocked');
+        const gate = buildMissionCompletionGate(parsed);
+        return weakestTruth(weakest, gate.truth_status);
+    }, 'proven');
+}
 function strongestSupportedTruth(rows = []) {
     if (rows.some((row) => row.truth === 'blocked'))
         return 'blocked';
@@ -977,6 +1149,28 @@ function asList(value) {
         return [];
     return Array.isArray(value) ? value.filter(Boolean).map(String) : [String(value)].filter(Boolean);
 }
+function asValueList(value) {
+    if (value === undefined || value === null || value === '')
+        return [];
+    return Array.isArray(value) ? value.filter(Boolean) : [value];
+}
+function parseStructuredValue(value) {
+    if (value && typeof value === 'object')
+        return value;
+    try {
+        const parsed = JSON.parse(String(value || ''));
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function asObjectList(value) {
+    if (!value)
+        return [];
+    const items = Array.isArray(value) ? value : [value];
+    return items.filter((item) => Boolean(item) && typeof item === 'object');
+}
 function uniqueStrings(values = []) {
     return [...new Set(values.filter(Boolean).map(String))];
 }

package/dist/lib/ueye-artifacts.d.ts

@@ -0,0 +1,98 @@
+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 declare function inspectImageFile(file: string): Promise<InspectedImageFile>;
+export declare 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;
+}): Promise<{
+    schema: string;
+    action: string;
+    manifest_path: string;
+    asset: UeyeAssetEntry;
+    warnings: string[];
+    next_action: string;
+    truth_status: string;
+}>;
+export declare function verifyUeyeAssetManifest(manifestFile: string): Promise<{
+    schema: string;
+    manifest_path: string;
+    asset_count: number;
+    protected_count: number;
+    editable_count: number;
+    errors: string[];
+    warnings: string[];
+    ready: boolean;
+    next_action: string;
+    truth_status: string;
+}>;
+export declare function archiveUeyeRevision(input: {
+    file: string;
+    root: string;
+    manifest_path?: string;
+    round: number;
+    artifact_id?: string;
+}): Promise<{
+    schema: string;
+    action: string;
+    manifest_path: string;
+    revision: UeyeRevisionEntry;
+    next_action: string;
+    truth_status: string;
+}>;
+export declare function verifyUeyeRevisionHistory(manifestFile: string): Promise<{
+    schema: string;
+    manifest_path: string;
+    revision_count: number;
+    rounds: number[];
+    errors: string[];
+    ready: boolean;
+    next_action: string;
+    truth_status: string;
+}>;

package/dist/lib/ueye-artifacts.js

@@ -0,0 +1,317 @@
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+export async function inspectImageFile(file) {
+    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) {
+    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 = {
+        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) {
+    const manifestPath = path.resolve(manifestFile);
+    const manifest = await readAssetManifest(manifestPath, false);
+    const errors = [];
+    const warnings = [];
+    const seenHashes = new Map();
+    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) {
+    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) {
+        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 = {
+        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) {
+    const manifestPath = path.resolve(manifestFile);
+    const history = await readRevisionHistory(manifestPath, false);
+    const errors = [];
+    const seen = new Set();
+    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, allowMissing = true) {
+    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) {
+        if (allowMissing && error?.code === 'ENOENT')
+            return { schema: 'yam.ueye-asset-manifest.v1', updated_at: '', assets: [] };
+        throw error;
+    }
+}
+async function readRevisionHistory(file, allowMissing = true) {
+    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) {
+        if (allowMissing && error?.code === 'ENOENT')
+            return { schema: 'yam.ueye-revision-history.v1', updated_at: '', revisions: [] };
+        throw error;
+    }
+}
+async function writeJsonAtomic(file, value) {
+    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, label) {
+    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) {
+    const warnings = [];
+    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, label) {
+    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, target) {
+    return path.relative(base, target).split(path.sep).join('/') || path.basename(target);
+}
+function resolveManifestFile(manifestPath, file) {
+    return path.isAbsolute(file) ? file : path.resolve(path.dirname(manifestPath), file);
+}
+function imageDimensions(buffer) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return [...new Set(values.filter(Boolean))];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",

package/references/final-report.md

@@ -13,6 +13,8 @@ Always keep final reports short. Include these when they apply:
 - Truth status, when verification or runtime claims matter.
 - Security notes when auth, payment, DB, secrets, permissions, deployment, dependency, or public-release surfaces are relevant.
 - Source boundaries when reference material shaped the decision.
+- Mission receipt/gate status when real subagents were used and the report claims verified/proven completion.
+- Ueye asset/revision integrity status when protected references or iterative artifact replacement materially affected a visual done claim.
 - Context pressure or cleanup findings when they could affect the next run.
 - Publish blocker evidence when npm/release work fails.
 - Structured diagnostic next action, when a check found a concrete next step.

package/references/honest-completion.md

@@ -64,6 +64,7 @@ Runtime work needs stronger evidence because long-running processes can create f
 - No automatic tmux for ordinary work.
 - No release-blocking runtime proof unless the user chooses `$deep` or `$mission`.
 - No full `$mission` claim without real subagent/team evidence; downgrade to `$deep`, or mark mission partial/blocked.
+- No verified/proven Mission claim without a passing completion gate covering every expected thread; lifecycle stop alone is not success.
 
 Design baseline: