yam-flow 2.2.1 → 2.3.1

package/dist/lib/trust-kernel.d.ts

@@ -9,6 +9,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;
     reason: string;
@@ -110,6 +114,50 @@ export interface MissionPatchEnvelope {
     rollback_hint: RollbackHint;
     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;
@@ -266,6 +314,8 @@ export interface ProofSummary {
     unverified?: unknown;
     visualProvenance?: unknown;
     missionEnvelope?: unknown;
+    missionReceipt?: unknown;
+    missionCompletion?: unknown;
     rollbackHint?: unknown;
     runtimeBackendEvidence?: unknown;
     mediaProof?: unknown;
@@ -299,6 +349,8 @@ export interface YamCompletionProof {
     runtime: string[];
     visualProvenance: string[];
     missionEnvelope: string[];
+    missionReceipt: string[];
+    missionCompletion: string[];
     rollbackHint: string[];
     runtimeBackendEvidence: string[];
     mediaProof: string[];
@@ -319,6 +371,8 @@ export declare function buildUeyeSurfaceContext(input?: Partial<UeyeSurfaceConte
 export declare function buildUeyeDesignCompletionGate(input?: Partial<UeyeDesignCompletionGate> & Record<string, unknown>): UeyeDesignCompletionGate;
 export declare function buildRollbackHint(input?: Partial<RollbackHint>): RollbackHint;
 export declare function buildMissionPatchEnvelope(input?: Partial<MissionPatchEnvelope>): MissionPatchEnvelope;
+export declare function buildMissionSubagentReceipt(input?: Partial<MissionSubagentReceipt> & Record<string, unknown>): MissionSubagentReceipt;
+export declare function buildMissionCompletionGate(input?: Partial<MissionCompletionGate> & Record<string, unknown>): MissionCompletionGate;
 export declare function buildRuntimeBackendEvidence(input?: Partial<RuntimeBackendEvidence>): RuntimeBackendEvidence;
 export declare function buildStudyNote(input?: Partial<StudyNote> & Record<string, unknown>): StudyNote;
 export declare function buildLoopReport(input?: Partial<LoopReport> & Record<string, unknown>): LoopReport;

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;
+}>;