yam-flow 2.5.1 → 2.6.0

package/dist/lib/benchmark-promotion.js

@@ -0,0 +1,204 @@
+import { createHash } from 'node:crypto';
+const DIGEST_PATTERN = /^(?:sha256:)?[a-f0-9]{64}$/i;
+const SEED_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+const MAX_SAMPLES = 256;
+export function parsePromotionSample(value) {
+    const parts = String(value || '').split(':');
+    if (parts.length !== 3)
+        throw new Error('sample must use seed:candidate:baseline');
+    const [seed, candidateText, baselineText] = parts;
+    const candidate = Number(candidateText);
+    const baseline = Number(baselineText);
+    if (!SEED_PATTERN.test(seed))
+        throw new Error('sample seed must use 1-64 letters, numbers, dot, underscore, or dash');
+    if (!Number.isFinite(candidate) || !Number.isFinite(baseline))
+        throw new Error(`sample ${seed} must contain finite candidate and baseline numbers`);
+    return { seed, candidate, baseline };
+}
+export function buildBoundedPromotionReport(input = {}) {
+    const requestedTarget = String(input.target || 'higher');
+    const target = requestedTarget === 'lower' ? 'lower' : 'higher';
+    const minSamples = integerInRange(input.min_samples, 2, MAX_SAMPLES, 2, 'min_samples');
+    const minMeanDelta = finiteAtLeast(input.min_mean_delta, 0, 0, 'min_mean_delta');
+    const minWinRate = finiteRange(input.min_win_rate, 0, 1, 0.5, 'min_win_rate');
+    const candidateDigest = normalizeDigest(input.candidate_digest);
+    const baselineDigest = normalizeDigest(input.baseline_digest);
+    const unit = boundedText(input.unit || '', 64);
+    const evidenceSource = boundedText(input.evidence_source || '', 512);
+    const rawSamples = Array.isArray(input.samples) ? input.samples : [];
+    const validationFailures = [];
+    if (!['higher', 'lower'].includes(requestedTarget))
+        validationFailures.push('target_invalid: target must be higher or lower');
+    if (!candidateDigest)
+        validationFailures.push('candidate_digest_invalid: record a SHA-256 candidate digest');
+    if (!baselineDigest)
+        validationFailures.push('baseline_digest_invalid: record a SHA-256 baseline digest');
+    if (candidateDigest && baselineDigest && candidateDigest === baselineDigest) {
+        validationFailures.push('candidate_matches_baseline: compare two distinct configuration digests');
+    }
+    if (!unit)
+        validationFailures.push('unit_missing: record what each paired score measures');
+    if (!evidenceSource)
+        validationFailures.push('evidence_source_missing: record where the paired measurements came from');
+    if (rawSamples.length > MAX_SAMPLES)
+        validationFailures.push(`sample_limit_exceeded: at most ${MAX_SAMPLES} paired samples are accepted`);
+    const seenSeeds = new Set();
+    const samples = [];
+    for (const row of rawSamples.slice(0, MAX_SAMPLES)) {
+        const seed = String(row?.seed || '');
+        const candidate = Number(row?.candidate);
+        const baseline = Number(row?.baseline);
+        if (!SEED_PATTERN.test(seed)) {
+            validationFailures.push('sample_seed_invalid: every seed must use 1-64 letters, numbers, dot, underscore, or dash');
+            continue;
+        }
+        if (seenSeeds.has(seed)) {
+            validationFailures.push(`duplicate_seed: ${seed}`);
+            continue;
+        }
+        seenSeeds.add(seed);
+        if (!Number.isFinite(candidate) || !Number.isFinite(baseline)) {
+            validationFailures.push(`sample_not_finite: ${seed}`);
+            continue;
+        }
+        const directionalDelta = target === 'higher' ? candidate - baseline : baseline - candidate;
+        if (!Number.isFinite(directionalDelta)) {
+            validationFailures.push(`sample_delta_not_finite: ${seed}`);
+            continue;
+        }
+        samples.push({
+            seed,
+            candidate,
+            baseline,
+            directional_delta: directionalDelta,
+            winner: directionalDelta > 0 ? 'candidate' : directionalDelta < 0 ? 'baseline' : 'tie'
+        });
+    }
+    samples.sort((left, right) => left.seed < right.seed ? -1 : left.seed > right.seed ? 1 : 0);
+    const candidateMean = samples.length ? mean(samples.map((sample) => sample.candidate)) : null;
+    const baselineMean = samples.length ? mean(samples.map((sample) => sample.baseline)) : null;
+    const directionalMeanDelta = samples.length ? mean(samples.map((sample) => sample.directional_delta)) : null;
+    const winRate = samples.length ? samples.filter((sample) => sample.winner === 'candidate').length / samples.length : null;
+    const failures = [...validationFailures];
+    if (!validationFailures.length) {
+        if (samples.length < minSamples)
+            failures.push(`minimum_samples_not_met: observed ${samples.length}, required ${minSamples}`);
+        if (directionalMeanDelta !== null && directionalMeanDelta < minMeanDelta) {
+            failures.push(`minimum_mean_delta_not_met: observed ${directionalMeanDelta}, required ${minMeanDelta}`);
+        }
+        if (winRate !== null && winRate < minWinRate)
+            failures.push(`minimum_win_rate_not_met: observed ${winRate}, required ${minWinRate}`);
+    }
+    const decision = validationFailures.length
+        ? 'blocked'
+        : samples.length < minSamples
+            ? 'insufficient-evidence'
+            : failures.length
+                ? 'revert'
+                : 'keep';
+    const canonicalEvidence = {
+        candidate_digest: candidateDigest,
+        baseline_digest: baselineDigest,
+        target,
+        unit,
+        evidence_source: evidenceSource,
+        policy: { min_samples: minSamples, min_mean_delta: minMeanDelta, min_win_rate: minWinRate },
+        samples: samples.map(({ seed, candidate, baseline }) => ({ seed, candidate, baseline }))
+    };
+    return {
+        schema: 'yam.bounded-promotion-receipt.v1',
+        generated_at: new Date().toISOString(),
+        label: boundedText(input.label || 'unnamed', 160),
+        candidate_digest: candidateDigest,
+        baseline_digest: baselineDigest,
+        target,
+        unit,
+        policy: {
+            min_samples: minSamples,
+            min_mean_delta: minMeanDelta,
+            min_win_rate: minWinRate
+        },
+        samples,
+        sample_count: samples.length,
+        candidate_mean: candidateMean,
+        baseline_mean: baselineMean,
+        directional_mean_delta: directionalMeanDelta,
+        win_rate: winRate,
+        decision,
+        failures,
+        blockers: decision === 'keep' ? [] : failures,
+        evidence_source: evidenceSource,
+        evidence_digest: `sha256:${createHash('sha256').update(stableJson(canonicalEvidence)).digest('hex')}`,
+        measurement_truth: 'operator_asserted',
+        arithmetic_truth_status: validationFailures.length ? 'blocked' : 'verified',
+        truth_status: validationFailures.length ? 'blocked' : 'partial',
+        next_action: promotionNextAction(decision)
+    };
+}
+function normalizeDigest(value) {
+    const text = String(value || '').trim().toLowerCase();
+    if (!DIGEST_PATTERN.test(text))
+        return '';
+    return text.startsWith('sha256:') ? text : `sha256:${text}`;
+}
+function integerInRange(value, min, max, fallback, label) {
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < min || number > max)
+        throw new Error(`${label} must be an integer from ${min} to ${max}`);
+    return number;
+}
+function finiteAtLeast(value, min, fallback, label) {
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    const number = Number(value);
+    if (!Number.isFinite(number) || number < min)
+        throw new Error(`${label} must be a finite number at least ${min}`);
+    return number;
+}
+function finiteRange(value, min, max, fallback, label) {
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    const number = Number(value);
+    if (!Number.isFinite(number) || number < min || number > max)
+        throw new Error(`${label} must be between ${min} and ${max}`);
+    return number;
+}
+function mean(values) {
+    const scale = Math.max(...values.map((value) => Math.abs(value)));
+    if (scale === 0)
+        return 0;
+    let sum = 0;
+    let compensation = 0;
+    for (const value of values) {
+        const normalized = value / scale;
+        const next = sum + normalized;
+        compensation += Math.abs(sum) >= Math.abs(normalized)
+            ? (sum - next) + normalized
+            : (normalized - next) + sum;
+        sum = next;
+    }
+    return ((sum + compensation) / values.length) * scale;
+}
+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);
+}
+function promotionNextAction(decision) {
+    if (decision === 'keep')
+        return 'keep the candidate only with the recorded evidence source and smallest relevant regression check';
+    if (decision === 'revert')
+        return 'revert or revise the candidate because one or more promotion thresholds failed';
+    if (decision === 'insufficient-evidence')
+        return 'record more paired samples with the same explicit policy before deciding';
+    return 'repair the malformed or ambiguous promotion evidence before making a keep/revert decision';
+}

package/dist/lib/design-production.d.ts

@@ -0,0 +1,306 @@
+type JsonObject = Record<string, unknown>;
+export type PlanReviewVerdict = 'approve' | 'request_changes';
+export type DesignRevisionStatus = 'active' | 'accepted' | 'two_round_limit' | 'integrity_blocked';
+export type GalleryCompletionState = 'draft' | 'ready_for_inspection' | 'packaged';
+export interface PlanReviewArtifact {
+    id: string;
+    role: 'plan' | 'reference' | 'deliverable';
+    file_path: string;
+    sha256: string;
+}
+export interface PlanReviewComment {
+    id: string;
+    anchor: {
+        artifact_id: string;
+        kind: 'line' | 'region' | 'text';
+        locator: string;
+    };
+    finding: string;
+    requested_change: string;
+    anchor_context: string;
+}
+export interface PlanReviewSession {
+    schema: 'yam.plan-review-canvas.v1';
+    session_id: string;
+    title: string;
+    created_at: string;
+    updated_at: string;
+    status: 'open' | 'closed';
+    verdict: PlanReviewVerdict | null;
+    closed_at: string | null;
+    demand_trigger: DesignProductionDemandTrigger & {
+        evidence_truth: 'operator_asserted';
+        recorded_at: string;
+    };
+    execution_boundary: {
+        storage: 'local_only';
+        rendering: 'static_html';
+        sandbox: 'csp_no_script_no_network';
+        remote_sharing: false;
+        server: false;
+        background_service: false;
+    };
+    artifacts: PlanReviewArtifact[];
+    comments: PlanReviewComment[];
+}
+export interface UeyeRevisionReference {
+    artifact_id: string;
+    manifest_path: string;
+    round: number;
+    sha256: string;
+    archived_at: string;
+    intent: 'preserve' | 'edit_copy';
+    asset_manifest_path: string | null;
+    asset_id: string | null;
+}
+export interface DesignRevisionRound {
+    round: number;
+    reviewer_finding: {
+        id: string;
+        source_comment_id: string;
+        summary: string;
+        evidence: string;
+    };
+    planned_change: string;
+    outcome: 'accepted' | 'changes_requested';
+    revision_refs: UeyeRevisionReference[];
+    recorded_at: string;
+}
+export interface DesignRevisionState {
+    schema: 'yam.design-revision-state.v1';
+    session_id: string;
+    canvas_session_path: string;
+    canvas_session_sha256: string;
+    updated_at: string;
+    max_rounds: 2;
+    status: DesignRevisionStatus;
+    stop_reason: string;
+    rounds: DesignRevisionRound[];
+}
+export interface GalleryArtifact {
+    id: string;
+    role: 'primary' | 'supporting' | 'reference';
+    provenance: {
+        kind: 'operator' | 'generated' | 'downloaded';
+        source_ref: string;
+        license_note: string;
+    };
+    revision_ref: UeyeRevisionReference;
+    dimensions: string;
+    sha256: string;
+    completion_state: GalleryCompletionState;
+    final_path: string;
+}
+export interface FinalGalleryManifest {
+    schema: 'yam.final-gallery-manifest.v1';
+    session_id: string;
+    created_at: string;
+    completion_state: GalleryCompletionState;
+    purpose: 'inspection_and_packaging_evidence_only';
+    claims: {
+        visual_correctness: 'not_verified';
+        license_correctness: 'not_verified';
+        implementation_correctness: 'not_verified';
+    };
+    artifacts: GalleryArtifact[];
+}
+export interface DesignProductionDemandTrigger {
+    kind: 'repeated_plan_review' | 'multi_asset_production';
+    evidence: string;
+}
+export declare function createPlanReviewCanvas(input: {
+    root: string;
+    session_id: string;
+    title: string;
+    demand_trigger: DesignProductionDemandTrigger;
+    artifacts: Array<Omit<PlanReviewArtifact, 'sha256'> & {
+        sha256?: string;
+    }>;
+    session_path?: string;
+    render_path?: string;
+}): Promise<{
+    schema: string;
+    session_path: string;
+    render_path: string;
+    session: PlanReviewSession;
+    next_action: string;
+    claims: {
+        session_artifact_integrity: string;
+        visual_correctness: string;
+        implementation_correctness: string;
+    };
+    truth_status: "verified" | "partial";
+}>;
+export declare function addPlanReviewComment(input: {
+    root: string;
+    session_path: string;
+    render_path: string;
+    comment: Omit<PlanReviewComment, 'anchor_context'>;
+}): Promise<{
+    schema: string;
+    session_path: string;
+    render_path: string;
+    session: PlanReviewSession;
+    next_action: string;
+    claims: {
+        session_artifact_integrity: string;
+        visual_correctness: string;
+        implementation_correctness: string;
+    };
+    truth_status: "verified" | "partial";
+}>;
+export declare function closePlanReviewCanvas(input: {
+    root: string;
+    session_path: string;
+    render_path: string;
+    verdict: PlanReviewVerdict;
+}): Promise<{
+    schema: string;
+    session_path: string;
+    render_path: string;
+    session: PlanReviewSession;
+    next_action: string;
+    claims: {
+        session_artifact_integrity: string;
+        visual_correctness: string;
+        implementation_correctness: string;
+    };
+    truth_status: "verified" | "partial";
+}>;
+export declare function readPlanReviewSession(file: string): Promise<PlanReviewSession>;
+export declare function createDesignRevisionState(input: {
+    root: string;
+    session_id: string;
+    state_path?: string;
+}): Promise<{
+    schema: string;
+    state_path: string;
+    state: DesignRevisionState;
+    truth_status: "verified";
+}>;
+export declare function recordDesignRevisionRound(input: {
+    root: string;
+    state_path: string;
+    reviewer_finding: DesignRevisionRound['reviewer_finding'];
+    planned_change: string;
+    outcome: DesignRevisionRound['outcome'];
+    revision_refs: UeyeRevisionReference[];
+}): Promise<{
+    schema: string;
+    state_path: string;
+    round: DesignRevisionRound;
+    state: DesignRevisionState;
+    next_action: string;
+    truth_status: "verified";
+}>;
+export declare function readDesignRevisionState(file: string): Promise<DesignRevisionState>;
+export declare function readCanonicalDesignRevisionState(input: {
+    root: string;
+    state_path: string;
+}): Promise<DesignRevisionState>;
+export declare function writeFinalGalleryManifest(input: {
+    root: string;
+    manifest_path: string;
+    session_id: string;
+    completion_state: GalleryCompletionState;
+    artifacts: GalleryArtifact[];
+}): Promise<{
+    schema: string;
+    manifest_path: string;
+    manifest: FinalGalleryManifest;
+    ready: boolean;
+    warnings: string[];
+    next_action: string;
+    truth_status: "partial";
+}>;
+export declare function verifyFinalGalleryManifest(input: {
+    root: string;
+    manifest_path: string;
+}): Promise<{
+    schema: string;
+    manifest_path: string;
+    artifact_count: number;
+    errors: string[];
+    ready: boolean;
+    claims: {
+        visual_correctness: string;
+        license_correctness: string;
+        implementation_correctness: string;
+    };
+    next_action: string;
+    truth_status: "blocked" | "partial";
+}>;
+export declare function finalizeDesignProductionPhase(input: {
+    root: string;
+    demand_trigger: DesignProductionDemandTrigger;
+    canvas_session_path: string;
+    revision_state_path: string | null;
+    gallery_manifest_path: string;
+    receipt_path: string;
+}): Promise<{
+    receipt_path: string;
+    receipt_digest: string;
+    schema: string;
+    session_id: string;
+    recorded_at: string;
+    demand_trigger: {
+        evidence_truth: "operator_asserted";
+        kind: "repeated_plan_review" | "multi_asset_production";
+        evidence: string;
+    };
+    canvas: {
+        path: string;
+        status: "closed";
+        verdict: PlanReviewVerdict;
+        artifact_integrity: string;
+    };
+    revision: {
+        path: string;
+        status: DesignRevisionStatus;
+        rounds: number;
+        reference_integrity: string;
+    };
+    gallery: {
+        path: string;
+        completion_state: "draft" | "ready_for_inspection" | "packaged";
+        integrity: string;
+        claims: {
+            visual_correctness: string;
+            license_correctness: string;
+            implementation_correctness: string;
+        };
+    };
+    upstream_digests: {
+        canvas_session: string;
+        revision_state: string;
+        gallery_manifest: string;
+    };
+    execution_boundary: {
+        storage: "local_only";
+        rendering: "static_html";
+        sandbox: "csp_no_script_no_network";
+        remote_sharing: false;
+        server: false;
+        background_service: false;
+    };
+    phase_evidence_status: "complete" | "bounded_stop" | "incomplete";
+    ready: boolean;
+    ready_to_claim_correctness: boolean;
+    next_action: string;
+    truth_status: "partial";
+}>;
+export declare function verifyDesignProductionPhaseReceipt(input: {
+    root: string;
+    receipt_path: string;
+}): Promise<{
+    schema: string;
+    receipt_path: string;
+    ready: boolean;
+    errors: string[];
+    upstream_digests: JsonObject;
+    receipt_digest: string;
+    ready_to_claim_correctness: boolean;
+    next_action: string;
+    truth_status: "blocked" | "partial";
+}>;
+export {};