yam-flow 2.5.0 → 2.6.0

package/src/lib/gate-result.ts

@@ -0,0 +1,223 @@
+import { createHash } from 'node:crypto';
+
+export type GateBoundary = 'release' | 'update' | 'mission' | 'generic';
+export type GateCheckStatus = 'passed' | 'failed' | 'skipped';
+
+export interface GateCheckInput {
+  id?: string;
+  status?: GateCheckStatus;
+  note?: string;
+  required?: boolean;
+}
+
+export interface StrictGateInput {
+  gate_id?: string;
+  boundary?: GateBoundary;
+  checks?: GateCheckInput[];
+  blockers?: string[];
+  evidence?: string[];
+  next_action?: string;
+}
+
+export interface StrictGateResult {
+  schema: 'yam.gate-result.v1';
+  generated_at: string;
+  gate_id: string;
+  boundary: GateBoundary;
+  status: 'passed' | 'failed';
+  checks: Array<{
+    id: string;
+    status: GateCheckStatus;
+    note: string;
+    required: boolean;
+  }>;
+  blockers: string[];
+  evidence: string[];
+  next_action: string;
+  contract_valid: boolean;
+  contract_errors: string[];
+  digest: string;
+  truth_status: 'verified' | 'blocked';
+}
+
+const GATE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,95}$/;
+const BOUNDARIES = new Set<GateBoundary>(['release', 'update', 'mission', 'generic']);
+const CHECK_STATUSES = new Set<GateCheckStatus>(['passed', 'failed', 'skipped']);
+
+export function buildStrictGateResult(input: StrictGateInput = {}): StrictGateResult {
+  const gateId = boundedText(input.gate_id || '', 96);
+  const boundary = BOUNDARIES.has(input.boundary as GateBoundary) ? input.boundary as GateBoundary : 'generic';
+  const contractErrors: string[] = [];
+  if (!GATE_ID_PATTERN.test(gateId)) contractErrors.push('gate_id_invalid');
+  if (!BOUNDARIES.has(input.boundary as GateBoundary)) 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 as GateCheckStatus) ? check?.status as GateCheckStatus : 'failed';
+    if (!GATE_ID_PATTERN.test(id)) contractErrors.push(`check_id_invalid:${index}`);
+    if (!CHECK_STATUSES.has(check?.status as GateCheckStatus)) 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' as const : 'blocked' as const;
+  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: unknown) {
+  const errors: string[] = [];
+  const record = value && typeof value === 'object' ? value as Record<string, unknown> : {};
+  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 as GateBoundary)) 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 as Record<string, unknown>;
+    if (!GATE_ID_PATTERN.test(String(row.id || ''))) errors.push(`check_id_invalid:${index}`);
+    if (!CHECK_STATUSES.has(row.status as GateCheckStatus)) 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 as Record<string, unknown>).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 as Record<string, unknown>;
+      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 as Record<string, unknown>;
+      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' as const,
+    valid: errors.length === 0,
+    errors: [...new Set(errors)],
+    truth_status: errors.length ? 'blocked' as const : 'verified' as const,
+    next_action: errors.length ? `reject the gate result and repair: ${errors[0]}` : 'gate result contract is structurally valid'
+  };
+}
+
+function isIsoDate(value: string) {
+  return !Number.isNaN(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+
+function uniqueBounded(value: unknown, maxItems: number, maxChars: number) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.map((item) => boundedText(item, maxChars)).filter(Boolean))].slice(0, maxItems);
+}
+
+function boundedText(value: unknown, max: number) {
+  return String(value || '').replace(/[\r\n\u0000-\u001f\u007f]+/g, ' ').trim().slice(0, max);
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map((item) => stableJson(item)).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}

package/src/lib/skill-installation.ts

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from 'node:crypto';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
+import { compareStableText } from './stable-order.js';
 
 export const INSTALL_RECEIPT_NAME = '.yam-flow-install-receipt.json';
 export const INSTALL_LOCK_NAME = '.yam-flow-install.lock';
@@ -211,7 +212,7 @@ async function collectTreeManifest(root: string, prefix = ''): Promise<InstallFi
   const files: InstallFileDigest[] = [];
   async function walk(current: string, relative: string): Promise<void> {
     const entries = await fsp.readdir(current, { withFileTypes: true });
-    entries.sort((left, right) => left.name.localeCompare(right.name));
+    entries.sort((left, right) => compareStableText(left.name, right.name));
     for (const entry of entries) {
       const absolute = path.join(current, entry.name);
       const nextRelative = relative ? path.join(relative, entry.name) : entry.name;
@@ -226,7 +227,7 @@ async function collectTreeManifest(root: string, prefix = ''): Promise<InstallFi
   }
 
   await walk(root, '');
-  return files.sort((left, right) => left.path.localeCompare(right.path));
+  return files.sort((left, right) => compareStableText(left.path, right.path));
 }
 
 async function expectedInstallManifest(sourceRoot: string, skills: string[]) {
@@ -253,7 +254,7 @@ async function expectedInstallManifest(sourceRoot: string, skills: string[]) {
       });
     }
   }
-  return files.sort((left, right) => left.path.localeCompare(right.path));
+  return files.sort((left, right) => compareStableText(left.path, right.path));
 }
 
 async function copyTree(source: string, target: string): Promise<void> {
@@ -278,8 +279,12 @@ async function copyTree(source: string, target: string): Promise<void> {
 }
 
 function manifestDigest(files: InstallFileDigest[]) {
+  return digestManifestFiles([...files].sort((left, right) => compareStableText(left.path, right.path)));
+}
+
+function digestManifestFiles(files: InstallFileDigest[]) {
   const digest = createHash('sha256');
-  for (const file of [...files].sort((left, right) => left.path.localeCompare(right.path))) {
+  for (const file of files) {
     digest.update(file.path);
     digest.update('\0');
     digest.update(String(file.bytes));
@@ -290,6 +295,20 @@ function manifestDigest(files: InstallFileDigest[]) {
   return digest.digest('hex');
 }
 
+function allowsLegacyManifestOrder(version: unknown) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(String(version || ''));
+  if (!match) return false;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  const patch = Number(match[3]);
+  return major < 2 || (major === 2 && (minor < 5 || (minor === 5 && patch === 0)));
+}
+
+function receiptManifestDigestMatches(files: InstallFileDigest[], digest: unknown, version: unknown) {
+  if (digest === manifestDigest(files)) return true;
+  return allowsLegacyManifestOrder(version) && digest === digestManifestFiles(files);
+}
+
 function manifestIssues(expected: InstallFileDigest[], actual: InstallFileDigest[], label: string) {
   const issues: string[] = [];
   const expectedByPath = new Map(expected.map((file) => [file.path, file]));
@@ -379,7 +398,7 @@ function ownershipReceiptIssues(
   if (value.integrity?.file_count !== files.length) {
     issues.push('install receipt file count does not match its manifest');
   }
-  if (value.integrity?.source_digest !== manifestDigest(files)) {
+  if (!receiptManifestDigestMatches(files, value.integrity?.source_digest, value.package?.version)) {
     issues.push('install receipt source digest does not match its manifest');
   }
   if (Array.isArray(value.skills)) {

package/src/lib/stable-order.ts

@@ -0,0 +1,4 @@
+export function compareStableText(left: string, right: string): number {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}

package/src/lib/trust-kernel.ts

@@ -1,3 +1,5 @@
+import { verifyStrictGateResult } from './gate-result.js';
+
 export const TRUTH_STATUSES = Object.freeze([
   'verified',
   'proven',
@@ -1395,7 +1397,24 @@ function missionCompletionCap(value: unknown = ''): TruthStatus {
     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);
+    const record = parsed as Record<string, unknown>;
+    const strictGate = record.gate_result && typeof record.gate_result === 'object'
+      ? record.gate_result as Record<string, unknown>
+      : null;
+    const reportedContract = record.gate_contract && typeof record.gate_contract === 'object'
+      ? record.gate_contract as Record<string, unknown>
+      : null;
+    const strictVerification = verifyStrictGateResult(strictGate);
+    const strictReady = Boolean(
+      strictGate
+      && strictGate.boundary === 'mission'
+      && strictGate.gate_id === 'mission-completion'
+      && strictGate.status === 'passed'
+      && strictVerification.valid
+      && reportedContract?.valid === true
+      && reportedContract?.truth_status === 'verified'
+    );
+    return weakestTruth(weakest, strictReady ? gate.truth_status : 'blocked');
   }, 'proven');
 }
 

package/src/lib/ueye-artifacts.ts

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { constants as fsConstants } from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
+import { compareStableText } from './stable-order.js';
 
 export interface InspectedImageFile {
   path: string;
@@ -102,7 +103,7 @@ export async function upsertUeyeAsset(input: {
   };
   if (existingIndex >= 0) manifest.assets[existingIndex] = entry;
   else manifest.assets.push(entry);
-  manifest.assets.sort((left, right) => left.id.localeCompare(right.id));
+  manifest.assets.sort((left, right) => compareStableText(left.id, right.id));
   manifest.updated_at = new Date().toISOString();
   await writeJsonAtomic(manifestPath, manifest);
   const warnings = assetWarnings(entry);
@@ -205,7 +206,7 @@ export async function archiveUeyeRevision(input: {
   } else {
     history.revisions.push(entry);
   }
-  history.revisions.sort((left, right) => left.round - right.round || left.artifact_id.localeCompare(right.artifact_id));
+  history.revisions.sort((left, right) => left.round - right.round || compareStableText(left.artifact_id, right.artifact_id));
   history.updated_at = new Date().toISOString();
   await writeJsonAtomic(manifestPath, history);
   return {

package/yam.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "yam",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "principles": [
     "Direction before execution.",
     "Start fast.",
@@ -29,7 +29,7 @@
     {
       "id": "ueye",
       "stage": "v0.4",
-      "purpose": "Tight UI/UX/design implementation and visual review with visual provenance, local asset integrity, revision history, reference-read proof, visual comparison, design quality review, and P0-P3 issue tracking."
+      "purpose": "Tight UI/UX/design implementation and visual review with visual provenance, local asset integrity, revision history, reference-read proof, visual comparison, design quality review, P0-P3 issue tracking, and an opt-in demand-gated Canvas/two-revision/final-gallery production phase."
     },
     {
       "id": "question",