yam-flow 2.5.1 → 2.7.0

package/dist/lib/gate-result.js

@@ -0,0 +1,219 @@
+import { createHash } from 'node:crypto';
+const GATE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,95}$/;
+const BOUNDARIES = new Set(['release', 'update', 'mission', 'generic']);
+const CHECK_STATUSES = new Set(['passed', 'failed', 'skipped']);
+export function buildStrictGateResult(input = {}) {
+    const gateId = boundedText(input.gate_id || '', 96);
+    const boundary = BOUNDARIES.has(input.boundary) ? input.boundary : 'generic';
+    const contractErrors = [];
+    if (!GATE_ID_PATTERN.test(gateId))
+        contractErrors.push('gate_id_invalid');
+    if (!BOUNDARIES.has(input.boundary))
+        contractErrors.push('boundary_invalid');
+    if (Array.isArray(input.checks) && input.checks.length > 128)
+        contractErrors.push('check_limit_exceeded');
+    if (Array.isArray(input.blockers) && input.blockers.length > 64)
+        contractErrors.push('blocker_limit_exceeded');
+    if (Array.isArray(input.evidence) && input.evidence.length > 128)
+        contractErrors.push('evidence_limit_exceeded');
+    const checks = Array.isArray(input.checks) ? input.checks.slice(0, 128).map((check, index) => {
+        const id = boundedText(check?.id || '', 96);
+        const status = CHECK_STATUSES.has(check?.status) ? check?.status : 'failed';
+        if (!GATE_ID_PATTERN.test(id))
+            contractErrors.push(`check_id_invalid:${index}`);
+        if (!CHECK_STATUSES.has(check?.status))
+            contractErrors.push(`check_status_invalid:${id || index}`);
+        return {
+            id,
+            status,
+            note: boundedText(check?.note || '', 512),
+            required: check?.required !== false
+        };
+    }) : [];
+    if (!checks.length)
+        contractErrors.push('checks_missing');
+    const checkIds = checks.map((check) => check.id).filter(Boolean);
+    if (new Set(checkIds).size !== checkIds.length)
+        contractErrors.push('duplicate_check_id');
+    const blockers = uniqueBounded(input.blockers, 64, 512);
+    const evidence = uniqueBounded(input.evidence, 128, 512);
+    if (!evidence.length)
+        contractErrors.push('evidence_missing');
+    for (const check of checks) {
+        if (check.required && check.status !== 'passed')
+            blockers.push(`${check.id || 'unnamed_check'}: ${check.note || 'required gate check did not pass'}`);
+    }
+    for (const error of contractErrors)
+        blockers.push(`gate_contract_invalid: ${error}`);
+    const finalBlockers = [...new Set(blockers)];
+    const contractValid = contractErrors.length === 0;
+    const passed = contractValid && finalBlockers.length === 0;
+    const generatedAt = new Date().toISOString();
+    const nextAction = boundedText(input.next_action || finalBlockers[0] || 'gate passed; retain the evidence digest with the dependent completion claim', 512);
+    const uniqueContractErrors = [...new Set(contractErrors)];
+    const truthStatus = passed ? 'verified' : 'blocked';
+    const canonical = {
+        schema: 'yam.gate-result.v1',
+        generated_at: generatedAt,
+        gate_id: gateId,
+        boundary,
+        status: passed ? 'passed' : 'failed',
+        checks,
+        blockers: finalBlockers,
+        evidence,
+        next_action: nextAction,
+        contract_valid: contractValid,
+        contract_errors: uniqueContractErrors,
+        truth_status: truthStatus
+    };
+    return {
+        schema: 'yam.gate-result.v1',
+        generated_at: generatedAt,
+        gate_id: gateId,
+        boundary,
+        status: passed ? 'passed' : 'failed',
+        checks,
+        blockers: finalBlockers,
+        evidence,
+        next_action: nextAction,
+        contract_valid: contractValid,
+        contract_errors: uniqueContractErrors,
+        digest: `sha256:${createHash('sha256').update(stableJson(canonical)).digest('hex')}`,
+        truth_status: truthStatus
+    };
+}
+export function verifyStrictGateResult(value) {
+    const errors = [];
+    const record = value && typeof value === 'object' ? value : {};
+    if (record.schema !== 'yam.gate-result.v1')
+        errors.push('schema_invalid');
+    if (typeof record.generated_at !== 'string' || !isIsoDate(record.generated_at))
+        errors.push('generated_at_invalid');
+    if (!GATE_ID_PATTERN.test(String(record.gate_id || '')))
+        errors.push('gate_id_invalid');
+    if (!BOUNDARIES.has(record.boundary))
+        errors.push('boundary_invalid');
+    if (!['passed', 'failed'].includes(String(record.status || '')))
+        errors.push('status_invalid');
+    const checks = Array.isArray(record.checks) ? record.checks : [];
+    const blockers = Array.isArray(record.blockers) ? record.blockers : [];
+    const evidence = Array.isArray(record.evidence) ? record.evidence : [];
+    const contractErrors = Array.isArray(record.contract_errors) ? record.contract_errors : [];
+    if (!checks.length)
+        errors.push('checks_missing');
+    if (checks.length > 128)
+        errors.push('check_limit_exceeded');
+    if (blockers.length > 64)
+        errors.push('blocker_limit_exceeded');
+    if (evidence.length > 128)
+        errors.push('evidence_limit_exceeded');
+    if (!Array.isArray(record.blockers) || blockers.some((item) => typeof item !== 'string'))
+        errors.push('blockers_invalid');
+    if (!Array.isArray(record.evidence) || !evidence.length || evidence.some((item) => typeof item !== 'string' || !item.trim()))
+        errors.push('evidence_missing');
+    if (typeof record.contract_valid !== 'boolean')
+        errors.push('contract_valid_missing');
+    if (!Array.isArray(record.contract_errors) || contractErrors.some((item) => typeof item !== 'string'))
+        errors.push('contract_errors_invalid');
+    if (record.contract_valid === true && contractErrors.length)
+        errors.push('contract_valid_with_errors');
+    if (record.contract_valid === false && !contractErrors.length)
+        errors.push('contract_invalid_without_errors');
+    if (record.status === 'passed' && record.contract_valid !== true)
+        errors.push('passed_with_invalid_contract');
+    if (typeof record.next_action !== 'string' || !record.next_action.trim())
+        errors.push('next_action_missing');
+    if (!['verified', 'blocked'].includes(String(record.truth_status || '')))
+        errors.push('truth_status_invalid');
+    if (record.status === 'passed' && record.truth_status !== 'verified')
+        errors.push('passed_truth_mismatch');
+    if (record.status === 'failed' && record.truth_status !== 'blocked')
+        errors.push('failed_truth_mismatch');
+    for (const [index, check] of checks.entries()) {
+        if (!check || typeof check !== 'object') {
+            errors.push(`check_invalid:${index}`);
+            continue;
+        }
+        const row = check;
+        if (!GATE_ID_PATTERN.test(String(row.id || '')))
+            errors.push(`check_id_invalid:${index}`);
+        if (!CHECK_STATUSES.has(row.status))
+            errors.push(`check_status_invalid:${index}`);
+        if (typeof row.note !== 'string')
+            errors.push(`check_note_invalid:${index}`);
+        if (typeof row.required !== 'boolean')
+            errors.push(`check_required_invalid:${index}`);
+    }
+    const checkIds = checks
+        .filter((check) => check && typeof check === 'object')
+        .map((check) => String(check.id || ''))
+        .filter(Boolean);
+    if (new Set(checkIds).size !== checkIds.length)
+        errors.push('duplicate_check_id');
+    if (record.status === 'passed' && Array.isArray(record.blockers) && record.blockers.length > 0)
+        errors.push('passed_with_blockers');
+    if (record.status === 'passed' && checks.length) {
+        const failedRequired = checks.some((check) => {
+            if (!check || typeof check !== 'object')
+                return true;
+            const row = check;
+            return row.required !== false && row.status !== 'passed';
+        });
+        if (failedRequired)
+            errors.push('passed_with_failed_required_check');
+    }
+    if (record.status === 'failed') {
+        const hasFailedRequired = checks.some((check) => {
+            if (!check || typeof check !== 'object')
+                return false;
+            const row = check;
+            return row.required !== false && row.status !== 'passed';
+        });
+        if (record.contract_valid === true && blockers.length === 0 && !hasFailedRequired)
+            errors.push('failed_without_blocker_or_failed_check');
+    }
+    const canonical = {
+        schema: record.schema,
+        generated_at: record.generated_at,
+        gate_id: String(record.gate_id || ''),
+        boundary: record.boundary,
+        status: record.status,
+        checks,
+        blockers,
+        evidence,
+        next_action: record.next_action,
+        contract_valid: record.contract_valid,
+        contract_errors: contractErrors,
+        truth_status: record.truth_status
+    };
+    const expectedDigest = `sha256:${createHash('sha256').update(stableJson(canonical)).digest('hex')}`;
+    if (typeof record.digest !== 'string' || record.digest !== expectedDigest)
+        errors.push('digest_invalid');
+    return {
+        schema: 'yam.gate-result-verification.v1',
+        valid: errors.length === 0,
+        errors: [...new Set(errors)],
+        truth_status: errors.length ? 'blocked' : 'verified',
+        next_action: errors.length ? `reject the gate result and repair: ${errors[0]}` : 'gate result contract is structurally valid'
+    };
+}
+function isIsoDate(value) {
+    return !Number.isNaN(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+function uniqueBounded(value, maxItems, maxChars) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.map((item) => boundedText(item, maxChars)).filter(Boolean))].slice(0, maxItems);
+}
+function boundedText(value, max) {
+    return String(value || '').replace(/[\r\n\u0000-\u001f\u007f]+/g, ' ').trim().slice(0, max);
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableJson(item)).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}

package/dist/lib/media-provider-receipt.d.ts

@@ -0,0 +1,79 @@
+export interface MediaProviderAssetInput {
+    id: string;
+    role: 'input' | 'output';
+    file_path: string;
+    provenance: {
+        kind: 'operator' | 'provider';
+        source_ref: string;
+        recorded_at: string;
+    };
+}
+export interface MediaProviderReceipt {
+    schema: 'yam.media-provider-receipt.v1';
+    created_at: string;
+    demand_trigger: {
+        kind: 'media_generation' | 'media_transformation';
+        evidence: string;
+        evidence_truth: 'operator_asserted';
+    };
+    provider: {
+        name: string;
+        model: string;
+    };
+    provider_calls: number;
+    provider_execution: boolean;
+    dry_run: boolean;
+    submit: boolean;
+    assets: Array<MediaProviderAssetInput & {
+        sha256: string;
+        bytes: number;
+    }>;
+    execution_boundary: {
+        provider_calls_by_yam: false;
+        provider_claim_source: 'operator_asserted';
+        optional: true;
+    };
+    claims: {
+        asset_integrity: 'digest_bound';
+        provider_execution: 'operator_asserted';
+        visual_correctness: 'not_verified';
+        implementation_correctness: 'not_verified';
+    };
+    truth_status: 'partial';
+    digest: string;
+}
+export declare function createMediaProviderReceipt(input: {
+    root: string;
+    receipt_path: string;
+    demand_trigger: {
+        kind: 'media_generation' | 'media_transformation';
+        evidence: string;
+    };
+    provider: {
+        name: string;
+        model: string;
+    };
+    provider_calls: number;
+    provider_execution: boolean;
+    dry_run: boolean;
+    submit: boolean;
+    assets: MediaProviderAssetInput[];
+}): Promise<{
+    schema: "yam.media-provider-receipt-write.v1";
+    receipt_path: string;
+    receipt: MediaProviderReceipt;
+    truth_status: "partial";
+    next_action: string;
+}>;
+export declare function verifyMediaProviderReceipt(input: {
+    root: string;
+    receipt_path: string;
+}): Promise<{
+    schema: "yam.media-provider-receipt-verification.v1";
+    receipt_path: string;
+    valid: boolean;
+    errors: string[];
+    receipt_truth_status: "partial";
+    truth_status: "verified" | "blocked";
+    next_action: string;
+}>;