yam-flow 2.7.0 → 2.8.0

package/dist/lib/next-step.js

@@ -0,0 +1,340 @@
+import { createHash } from 'node:crypto';
+const MAX_STEPS = 12;
+const MAX_LIST_ITEMS = 8;
+const MAX_CONTRACT_ERRORS = 64;
+const EVIDENCE_LEVELS = new Set(['L0', 'L1', 'L2', 'L3', 'L4', 'L5']);
+const EVIDENCE_RANK = { L0: 0, L1: 1, L2: 2, L3: 3, L4: 4, L5: 5 };
+const STEP_KINDS = new Set(['fix_first', 'planned']);
+const TRUTH_STATUSES = new Set([
+    'proven',
+    'verified',
+    'partial',
+    'fixture_only',
+    'fixture_instrumented_real',
+    'integration_optional',
+    'real_required_missing',
+    'skipped',
+    'blocked',
+    'assumed'
+]);
+const OWNER_ROUTES = new Set(['$quick', '$ueye', '$question', '$scout', '$deep', '$mission']);
+const INPUT_KEYS = ['current_situation', 'forward_outlook', 'critical_opinion', 'improvement_recommendations', 'steps', 'evidence_level', 'evidence_stamp', 'truth_status'];
+const STEP_INPUT_KEYS = ['kind', 'action', 'why', 'owner_route', 'owner_scope', 'blocked_by', 'safe_retry', 'side_effects'];
+const TOP_LEVEL_KEYS = ['schema', 'scan', 'steps', 'evidence', 'contract_valid', 'contract_errors', 'truth_status', 'digest'];
+const SCAN_KEYS = ['current_situation', 'forward_outlook', 'critical_opinion', 'improvement_recommendations'];
+const STEP_KEYS = ['order', 'kind', 'action', 'why', 'owner_route', 'owner_scope', 'blocked_by', 'safe_retry', 'side_effects'];
+const EVIDENCE_KEYS = ['level', 'stamp'];
+export function buildNextStep(input = {}) {
+    const errors = [];
+    const source = isRecord(input) ? input : {};
+    if (!isRecord(input))
+        errors.push('input_invalid');
+    else
+        unexpectedKeys(input, INPUT_KEYS, 'input', errors);
+    const currentSituation = requiredText(source.current_situation, 'current_situation', 1200, errors);
+    const forwardOutlook = requiredText(source.forward_outlook, 'forward_outlook', 1200, errors);
+    const criticalOpinion = requiredText(source.critical_opinion, 'critical_opinion', 1200, errors);
+    const improvementRecommendations = textList(source.improvement_recommendations, 'improvement_recommendations', MAX_LIST_ITEMS, 600, true, errors);
+    const rawSteps = Array.isArray(source.steps) ? source.steps : [];
+    if (!Array.isArray(source.steps) || !rawSteps.length)
+        errors.push('steps_missing');
+    if (rawSteps.length > MAX_STEPS)
+        errors.push('step_limit_exceeded');
+    let plannedSeen = false;
+    const steps = rawSteps.slice(0, MAX_STEPS).map((value, index) => {
+        const step = isRecord(value) ? value : {};
+        if (!isRecord(value))
+            errors.push(`steps[${index}]_invalid`);
+        else
+            unexpectedKeys(value, STEP_INPUT_KEYS, `steps[${index}]`, errors);
+        const rawKind = normalizedText(step.kind, 32);
+        const kind = STEP_KINDS.has(rawKind) ? rawKind : 'planned';
+        if (!STEP_KINDS.has(rawKind))
+            errors.push(`steps[${index}].kind_invalid`);
+        if (kind === 'planned')
+            plannedSeen = true;
+        if (kind === 'fix_first' && plannedSeen)
+            errors.push(`steps[${index}].fix_first_out_of_order`);
+        const rawRoute = normalizedText(step.owner_route, 32).toLowerCase();
+        const routeWithSigil = rawRoute && !rawRoute.startsWith('$') ? `$${rawRoute}` : rawRoute;
+        const ownerRoute = OWNER_ROUTES.has(routeWithSigil)
+            ? routeWithSigil
+            : '$quick';
+        if (!OWNER_ROUTES.has(routeWithSigil))
+            errors.push(`steps[${index}].owner_route_invalid`);
+        const blockedBy = textList(step.blocked_by, `steps[${index}].blocked_by`, MAX_LIST_ITEMS, 500, false, errors);
+        if (step.safe_retry !== undefined && typeof step.safe_retry !== 'string') {
+            errors.push(`steps[${index}].safe_retry_invalid`);
+        }
+        const suppliedSafeRetry = normalizedText(step.safe_retry, 800);
+        if (normalizedLength(step.safe_retry) > 800)
+            errors.push(`steps[${index}].safe_retry_too_long`);
+        if (blockedBy.length && !suppliedSafeRetry)
+            errors.push(`steps[${index}].safe_retry_missing`);
+        const safeRetry = suppliedSafeRetry || 'not required; confirm the recorded evidence is still current before execution';
+        return {
+            order: index + 1,
+            kind,
+            action: requiredText(step.action, `steps[${index}].action`, 800, errors),
+            why: requiredText(step.why, `steps[${index}].why`, 800, errors),
+            owner_route: ownerRoute,
+            owner_scope: textList(step.owner_scope, `steps[${index}].owner_scope`, MAX_LIST_ITEMS, 300, true, errors),
+            blocked_by: blockedBy,
+            safe_retry: safeRetry,
+            side_effects: textList(step.side_effects, `steps[${index}].side_effects`, MAX_LIST_ITEMS, 500, true, errors)
+        };
+    });
+    const actions = steps.map((step) => step.action).filter(Boolean);
+    if (new Set(actions).size !== actions.length)
+        errors.push('duplicate_step_action');
+    const rawEvidenceLevel = normalizedText(source.evidence_level, 8);
+    const evidenceLevel = EVIDENCE_LEVELS.has(rawEvidenceLevel)
+        ? rawEvidenceLevel
+        : 'L0';
+    if (!EVIDENCE_LEVELS.has(rawEvidenceLevel))
+        errors.push('evidence_level_invalid');
+    const evidenceStamp = requiredText(source.evidence_stamp, 'evidence_stamp', 512, errors);
+    const rawTruthStatus = normalizedText(source.truth_status, 48);
+    const requestedTruth = TRUTH_STATUSES.has(rawTruthStatus)
+        ? rawTruthStatus
+        : 'assumed';
+    if (!TRUTH_STATUSES.has(rawTruthStatus))
+        errors.push('truth_status_invalid');
+    const hasBlockers = steps.some((step) => step.blocked_by.length > 0);
+    if (hasBlockers && requestedTruth !== 'blocked')
+        errors.push('truth_status_contradicts_blockers');
+    if (!hasBlockers && requestedTruth === 'blocked')
+        errors.push('blocked_truth_without_blocker');
+    if (requestedTruth === 'verified' && EVIDENCE_RANK[evidenceLevel] < EVIDENCE_RANK.L2) {
+        errors.push('verified_truth_requires_l2_evidence');
+    }
+    if (requestedTruth === 'proven' && EVIDENCE_RANK[evidenceLevel] < EVIDENCE_RANK.L4) {
+        errors.push('proven_truth_requires_l4_evidence');
+    }
+    const contractErrors = boundedContractErrors(errors);
+    const contractValid = contractErrors.length === 0;
+    const truthStatus = contractValid
+        ? hasBlockers ? 'blocked' : requestedTruth
+        : 'blocked';
+    const canonical = {
+        schema: 'yam.next-step.v1',
+        scan: {
+            current_situation: currentSituation,
+            forward_outlook: forwardOutlook,
+            critical_opinion: criticalOpinion,
+            improvement_recommendations: improvementRecommendations
+        },
+        steps,
+        evidence: { level: evidenceLevel, stamp: evidenceStamp },
+        contract_valid: contractValid,
+        contract_errors: contractErrors,
+        truth_status: truthStatus
+    };
+    return {
+        ...canonical,
+        digest: digest(canonical)
+    };
+}
+export function verifyNextStep(value) {
+    const errors = [];
+    const record = isRecord(value) ? value : {};
+    exactKeys(record, TOP_LEVEL_KEYS, 'receipt', errors);
+    if (record.schema !== 'yam.next-step.v1')
+        errors.push('schema_invalid');
+    const scan = isRecord(record.scan) ? record.scan : {};
+    if (!isRecord(record.scan))
+        errors.push('scan_invalid');
+    exactKeys(scan, SCAN_KEYS, 'scan', errors);
+    validateText(scan.current_situation, 'current_situation', 1200, errors);
+    validateText(scan.forward_outlook, 'forward_outlook', 1200, errors);
+    validateText(scan.critical_opinion, 'critical_opinion', 1200, errors);
+    validateTextList(scan.improvement_recommendations, 'improvement_recommendations', MAX_LIST_ITEMS, 600, true, errors);
+    const steps = Array.isArray(record.steps) ? record.steps : [];
+    if (!Array.isArray(record.steps) || !steps.length)
+        errors.push('steps_missing');
+    if (steps.length > MAX_STEPS)
+        errors.push('step_limit_exceeded');
+    let plannedSeen = false;
+    let hasBlockers = false;
+    const actions = [];
+    for (const [index, value] of steps.entries()) {
+        const step = isRecord(value) ? value : {};
+        if (!isRecord(value))
+            errors.push(`steps[${index}]_invalid`);
+        exactKeys(step, STEP_KEYS, `steps[${index}]`, errors);
+        if (step.order !== index + 1)
+            errors.push(`steps[${index}].order_invalid`);
+        if (!STEP_KINDS.has(step.kind))
+            errors.push(`steps[${index}].kind_invalid`);
+        if (step.kind === 'planned')
+            plannedSeen = true;
+        if (step.kind === 'fix_first' && plannedSeen)
+            errors.push(`steps[${index}].fix_first_out_of_order`);
+        validateText(step.action, `steps[${index}].action`, 800, errors);
+        validateText(step.why, `steps[${index}].why`, 800, errors);
+        if (typeof step.action === 'string' && step.action)
+            actions.push(step.action);
+        if (!OWNER_ROUTES.has(step.owner_route))
+            errors.push(`steps[${index}].owner_route_invalid`);
+        validateTextList(step.owner_scope, `steps[${index}].owner_scope`, MAX_LIST_ITEMS, 300, true, errors);
+        validateTextList(step.blocked_by, `steps[${index}].blocked_by`, MAX_LIST_ITEMS, 500, false, errors);
+        validateText(step.safe_retry, `steps[${index}].safe_retry`, 800, errors);
+        validateTextList(step.side_effects, `steps[${index}].side_effects`, MAX_LIST_ITEMS, 500, true, errors);
+        const blockedBy = Array.isArray(step.blocked_by) ? step.blocked_by : [];
+        if (blockedBy.length)
+            hasBlockers = true;
+    }
+    if (new Set(actions).size !== actions.length)
+        errors.push('duplicate_step_action');
+    const evidence = isRecord(record.evidence) ? record.evidence : {};
+    if (!isRecord(record.evidence))
+        errors.push('evidence_invalid');
+    exactKeys(evidence, EVIDENCE_KEYS, 'evidence', errors);
+    if (!EVIDENCE_LEVELS.has(evidence.level))
+        errors.push('evidence_level_invalid');
+    validateText(evidence.stamp, 'evidence_stamp', 512, errors);
+    if (!TRUTH_STATUSES.has(record.truth_status))
+        errors.push('truth_status_invalid');
+    if (hasBlockers && record.truth_status !== 'blocked')
+        errors.push('truth_status_contradicts_blockers');
+    if (!hasBlockers && record.truth_status === 'blocked' && record.contract_valid === true)
+        errors.push('blocked_truth_without_blocker');
+    if (record.truth_status === 'verified' && EVIDENCE_RANK[evidence.level] < EVIDENCE_RANK.L2) {
+        errors.push('verified_truth_requires_l2_evidence');
+    }
+    if (record.truth_status === 'proven' && EVIDENCE_RANK[evidence.level] < EVIDENCE_RANK.L4) {
+        errors.push('proven_truth_requires_l4_evidence');
+    }
+    const contractErrors = Array.isArray(record.contract_errors) ? record.contract_errors : [];
+    if (!Array.isArray(record.contract_errors) || contractErrors.some((item) => typeof item !== 'string' || !item)) {
+        errors.push('contract_errors_invalid');
+    }
+    if (contractErrors.length > MAX_CONTRACT_ERRORS)
+        errors.push('contract_error_limit_exceeded');
+    if (typeof record.contract_valid !== 'boolean')
+        errors.push('contract_valid_missing');
+    if (record.contract_valid === true && contractErrors.length)
+        errors.push('contract_valid_with_errors');
+    if (record.contract_valid === false)
+        errors.push('receipt_contract_invalid');
+    const canonical = {
+        schema: record.schema,
+        scan: record.scan,
+        steps: record.steps,
+        evidence: record.evidence,
+        contract_valid: record.contract_valid,
+        contract_errors: record.contract_errors,
+        truth_status: record.truth_status
+    };
+    const expectedDigest = digest(canonical);
+    if (typeof record.digest !== 'string' || record.digest !== expectedDigest)
+        errors.push('digest_invalid');
+    const uniqueErrors = [...new Set(errors)];
+    return {
+        schema: 'yam.next-step-verification.v1',
+        valid: uniqueErrors.length === 0,
+        errors: uniqueErrors,
+        receipt_truth_status: TRUTH_STATUSES.has(record.truth_status)
+            ? record.truth_status
+            : 'blocked',
+        truth_status: uniqueErrors.length ? 'blocked' : 'verified',
+        next_action: uniqueErrors.length
+            ? `reject the Next step receipt and repair: ${uniqueErrors[0]}`
+            : 'retain the digest with the final report and execute steps in order'
+    };
+}
+function requiredText(value, label, max, errors) {
+    if (typeof value !== 'string') {
+        errors.push(`${label}_invalid`);
+        return '';
+    }
+    const text = normalizedText(value, max);
+    if (!text)
+        errors.push(`${label}_missing`);
+    if (normalizedLength(value) > max)
+        errors.push(`${label}_too_long`);
+    return text;
+}
+function textList(value, label, maxItems, maxChars, required, errors) {
+    const items = Array.isArray(value) ? value : [];
+    if (!Array.isArray(value) && value !== undefined)
+        errors.push(`${label}_invalid`);
+    if (items.length > maxItems)
+        errors.push(`${label}_limit_exceeded`);
+    const normalized = items.slice(0, maxItems).map((item, index) => requiredText(item, `${label}[${index}]`, maxChars, errors)).filter(Boolean);
+    const unique = [...new Set(normalized)];
+    if (unique.length !== normalized.length)
+        errors.push(`${label}_duplicate`);
+    if (required && !unique.length)
+        errors.push(`${label}_missing`);
+    return unique;
+}
+function validateText(value, label, max, errors) {
+    if (typeof value !== 'string' || !value || value !== normalizedText(value, max))
+        errors.push(`${label}_invalid`);
+    if (typeof value === 'string' && value.length > max)
+        errors.push(`${label}_too_long`);
+}
+function validateTextList(value, label, maxItems, maxChars, required, errors) {
+    if (!Array.isArray(value)) {
+        errors.push(`${label}_invalid`);
+        return;
+    }
+    if (value.length > maxItems)
+        errors.push(`${label}_limit_exceeded`);
+    if (required && !value.length)
+        errors.push(`${label}_missing`);
+    for (const [index, item] of value.entries())
+        validateText(item, `${label}[${index}]`, maxChars, errors);
+    if (new Set(value).size !== value.length)
+        errors.push(`${label}_duplicate`);
+}
+function exactKeys(record, expected, label, errors) {
+    const expectedSet = new Set(expected);
+    for (const key of Object.keys(record)) {
+        if (!expectedSet.has(key))
+            errors.push(`${label}_unexpected_key:${key}`);
+    }
+    for (const key of expected) {
+        if (!(key in record))
+            errors.push(`${label}_missing_key:${key}`);
+    }
+}
+function unexpectedKeys(record, allowed, label, errors) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(record)) {
+        if (!allowedSet.has(key))
+            errors.push(`${label}_unexpected_key:${key}`);
+    }
+}
+function boundedContractErrors(errors) {
+    const unique = [...new Set(errors)];
+    if (unique.length <= MAX_CONTRACT_ERRORS)
+        return unique;
+    return [...unique.slice(0, MAX_CONTRACT_ERRORS - 1), 'contract_error_limit_exceeded'];
+}
+function normalizedLength(value) {
+    return typeof value === 'string'
+        ? value.replace(/[\r\n\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().length
+        : 0;
+}
+function normalizedText(value, max) {
+    return typeof value === 'string'
+        ? value.replace(/[\r\n\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max)
+        : '';
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function digest(value) {
+    return `sha256:${createHash('sha256').update(stableJson(value)).digest('hex')}`;
+}
+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/release-auth-readiness.d.ts

@@ -0,0 +1,81 @@
+export type ReleaseAuthMode = 'trusted_publisher_oidc' | 'manual_token';
+export type RequestedReleaseAuthMode = 'auto' | 'oidc' | 'token';
+export interface TrustedPublisherWorkflowCheck {
+    id: 'workflow_dispatch' | 'id_token_write' | 'cloud_hosted_runner' | 'npm_publish' | 'provenance' | 'official_registry';
+    passed: boolean;
+}
+export interface TrustedPublisherWorkflowInspection {
+    path: string;
+    exists: boolean;
+    configured: boolean;
+    checks: TrustedPublisherWorkflowCheck[];
+    missing_checks: string[];
+}
+export interface LocalTokenProbe {
+    command: 'npm whoami';
+    ok: boolean;
+    note: string;
+}
+export interface ReleaseAuthBlocker {
+    kind: 'oidc_workflow_incomplete' | 'trusted_publisher_account_unverified' | 'auth_not_verified';
+    severity: 'error';
+    reason: string;
+    safe_next_action: string;
+    command: string;
+}
+export declare function inspectTrustedPublisherWorkflowText(text: string, workflowPath?: string, exists?: boolean): TrustedPublisherWorkflowInspection;
+export declare function buildReleaseAuthReadiness(input: {
+    workflow: TrustedPublisherWorkflowInspection;
+    local_token: LocalTokenProbe;
+    requested_mode?: RequestedReleaseAuthMode;
+}): {
+    schema: "yam.release-auth-readiness.v1";
+    requested_mode: "token" | "auto";
+    mode: "manual_token";
+    status: "authenticated" | "not_authenticated";
+    local_token: {
+        command: "npm whoami";
+        required_for_selected_mode: boolean;
+        status: "authenticated" | "not_authenticated";
+        account: string;
+        note: string;
+        truth_status: "verified";
+    };
+    trusted_publisher: {
+        provider: "github_actions";
+        workflow_path: string;
+        workflow_status: "not_configured";
+        workflow_checks: TrustedPublisherWorkflowCheck[];
+        missing_checks: string[];
+        account_status: "not_applicable";
+        note: string;
+    };
+    blockers: ReleaseAuthBlocker[];
+    next_action: string;
+    truth_status: "verified" | "blocked";
+} | {
+    schema: "yam.release-auth-readiness.v1";
+    requested_mode: "auto" | "oidc";
+    mode: "trusted_publisher_oidc";
+    status: "workflow_configured_account_unverified" | "workflow_incomplete";
+    local_token: {
+        required_for_selected_mode: boolean;
+        note: string;
+        command: "npm whoami";
+        status: "authenticated" | "not_authenticated";
+        account: string;
+        truth_status: "verified";
+    };
+    trusted_publisher: {
+        provider: "github_actions";
+        workflow_path: string;
+        workflow_status: "incomplete" | "static_config_verified";
+        workflow_checks: TrustedPublisherWorkflowCheck[];
+        missing_checks: string[];
+        account_status: "not_checked" | "not_verified";
+        note: string;
+    };
+    blockers: ReleaseAuthBlocker[];
+    next_action: string;
+    truth_status: "blocked";
+};

package/dist/lib/release-auth-readiness.js

@@ -0,0 +1,106 @@
+export function inspectTrustedPublisherWorkflowText(text, workflowPath = '.github/workflows/release.yml', exists = Boolean(text)) {
+    const source = String(text || '');
+    const activeSource = source
+        .split(/\r?\n/)
+        .filter((line) => !/^\s*#/.test(line))
+        .join('\n');
+    const checks = [
+        { id: 'workflow_dispatch', passed: /(?:^|\n)\s*workflow_dispatch\s*:/m.test(activeSource) },
+        { id: 'id_token_write', passed: /(?:^|\n)\s*id-token\s*:\s*write\s*(?:#.*)?$/m.test(activeSource) },
+        { id: 'cloud_hosted_runner', passed: /(?:^|\n)\s*runs-on\s*:\s*(?:ubuntu|macos|windows)-latest\s*(?:#.*)?$/m.test(activeSource) },
+        { id: 'npm_publish', passed: /(?:^|\n)\s*(?:-\s*)?(?:run:\s*(?:>-?\s*)?)?npm\s+publish\b/m.test(activeSource) },
+        { id: 'provenance', passed: /(?:^|\s)--provenance(?:\s|$)/m.test(activeSource) },
+        { id: 'official_registry', passed: /--registry\s+https:\/\/registry\.npmjs\.org\/?(?:\s|$)/m.test(activeSource) }
+    ];
+    const missingChecks = checks.filter((check) => !check.passed).map((check) => check.id);
+    return {
+        path: workflowPath,
+        exists,
+        configured: exists && missingChecks.length === 0,
+        checks,
+        missing_checks: missingChecks
+    };
+}
+export function buildReleaseAuthReadiness(input) {
+    const workflow = input.workflow;
+    const requestedMode = input.requested_mode || 'auto';
+    const oidcSelected = requestedMode === 'oidc' || (requestedMode === 'auto' && workflow.exists);
+    const localToken = {
+        command: 'npm whoami',
+        required_for_selected_mode: !oidcSelected,
+        status: input.local_token.ok ? 'authenticated' : 'not_authenticated',
+        account: input.local_token.ok ? 'observed_redacted' : '',
+        note: input.local_token.ok
+            ? 'npm account observed for the optional manual-token path; username intentionally redacted'
+            : input.local_token.note,
+        truth_status: 'verified'
+    };
+    if (!oidcSelected) {
+        const blockers = input.local_token.ok ? [] : [{
+                kind: 'auth_not_verified',
+                severity: 'error',
+                reason: input.local_token.note || 'npm whoami did not confirm an authenticated publisher for the selected manual-token path',
+                safe_next_action: 'refresh npm login/token, then rerun `npm whoami` before manual-token publishing',
+                command: 'npm whoami'
+            }];
+        return {
+            schema: 'yam.release-auth-readiness.v1',
+            requested_mode: requestedMode,
+            mode: 'manual_token',
+            status: input.local_token.ok ? 'authenticated' : 'not_authenticated',
+            local_token: localToken,
+            trusted_publisher: {
+                provider: 'github_actions',
+                workflow_path: workflow.path,
+                workflow_status: 'not_configured',
+                workflow_checks: workflow.checks,
+                missing_checks: workflow.missing_checks,
+                account_status: 'not_applicable',
+                note: 'No trusted-publisher release workflow was detected; manual-token authentication remains selected.'
+            },
+            blockers,
+            next_action: blockers[0]?.safe_next_action || 'manual-token authentication is verified; publishing still requires explicit user intent',
+            truth_status: blockers.length ? 'blocked' : 'verified'
+        };
+    }
+    const blockers = workflow.configured ? [{
+            kind: 'trusted_publisher_account_unverified',
+            severity: 'error',
+            reason: 'The local report cannot verify the npmjs.com account-side Trusted Publisher binding; npm whoami does not reflect OIDC authentication status.',
+            safe_next_action: `confirm the package Trusted Publisher repository and workflow filename match ${workflow.path}, then use the hosted workflow result as authentication evidence`,
+            command: 'npmjs.com package settings'
+        }] : [{
+            kind: 'oidc_workflow_incomplete',
+            severity: 'error',
+            reason: `The trusted-publisher workflow is missing required controls: ${workflow.missing_checks.join(', ')}`,
+            safe_next_action: `repair ${workflow.path}, then rerun workflow pins, actionlint, and release auth smoke before publishing`,
+            command: 'npm run release:auth-smoke'
+        }];
+    return {
+        schema: 'yam.release-auth-readiness.v1',
+        requested_mode: requestedMode,
+        mode: 'trusted_publisher_oidc',
+        status: workflow.configured ? 'workflow_configured_account_unverified' : 'workflow_incomplete',
+        local_token: {
+            ...localToken,
+            required_for_selected_mode: false,
+            note: input.local_token.ok
+                ? `${localToken.note}; npm whoami does not prove OIDC readiness`
+                : `${localToken.note || 'no local npm token was observed'}; this does not block the selected OIDC path`
+        },
+        trusted_publisher: {
+            provider: 'github_actions',
+            workflow_path: workflow.path,
+            workflow_status: workflow.configured ? 'static_config_verified' : 'incomplete',
+            workflow_checks: workflow.checks,
+            missing_checks: workflow.missing_checks,
+            account_status: workflow.configured ? 'not_verified' : 'not_checked',
+            note: workflow.configured
+                ? 'Local static checks cover the workflow only; npmjs.com account configuration and the publish-time OIDC exchange remain unverified.'
+                : 'The workflow must satisfy every required control before account-side Trusted Publisher evidence is relevant.'
+        },
+        blockers,
+        next_action: blockers[0].safe_next_action,
+        truth_status: 'blocked'
+    };
+}

package/dist/lib/release-registry-status.d.ts

@@ -0,0 +1,18 @@
+export type ReleaseRegistryCheck = {
+    id?: unknown;
+    status?: unknown;
+    note?: unknown;
+};
+export type ReleaseRegistryStatus = {
+    checked: boolean;
+    latest_version: string;
+    not_published: boolean;
+    note: string;
+    parse_failed: boolean;
+    queried_package: string;
+    queried_version: string;
+};
+export declare function releaseRegistryStatusFromChecks(checks?: ReleaseRegistryCheck[], expected?: {
+    package_name?: string;
+    version?: string;
+}): ReleaseRegistryStatus;

package/dist/lib/release-registry-status.js

@@ -0,0 +1,37 @@
+export function releaseRegistryStatusFromChecks(checks = [], expected = {}) {
+    const registryCheck = checks.find((check) => check.id === 'registry_status');
+    const note = String(registryCheck?.note || '');
+    const base = {
+        checked: false,
+        latest_version: '',
+        not_published: false,
+        note,
+        parse_failed: false,
+        queried_package: '',
+        queried_version: ''
+    };
+    if (registryCheck?.status !== 'passed')
+        return base;
+    const match = note.match(/registry:check:\s*ok\s*\((.+)@([^@\s()]+)\s+is not published\)/i);
+    if (!match)
+        return { ...base, parse_failed: true };
+    const queriedPackage = String(match[1] || '').trim();
+    const queriedVersion = String(match[2] || '').trim();
+    const expectedPackage = String(expected.package_name || '').trim();
+    const expectedVersion = String(expected.version || '').trim();
+    if ((expectedPackage && queriedPackage !== expectedPackage) || (expectedVersion && queriedVersion !== expectedVersion)) {
+        return {
+            ...base,
+            parse_failed: true,
+            queried_package: queriedPackage,
+            queried_version: queriedVersion
+        };
+    }
+    return {
+        ...base,
+        checked: true,
+        not_published: true,
+        queried_package: queriedPackage,
+        queried_version: queriedVersion
+    };
+}

package/dist/lib/scout-receipt.d.ts

@@ -0,0 +1,89 @@
+declare const FAILURE_KINDS: readonly ["not_measured", "no_results", "blocked_waf", "rate_limited", "auth_required", "paywall", "network_failed", "empty_content"];
+type FailureKind = typeof FAILURE_KINDS[number];
+export interface ScoutReceiptSpec {
+    subject: {
+        canonical_name: string;
+        aliases: string[];
+        canonical_url: string;
+    };
+    clocks: {
+        registry_latest: string;
+        release_tag: string;
+        main_version: string;
+        latest_commit: string;
+        stability: 'stable' | 'release_candidate' | 'unreleased' | 'mixed' | 'unknown';
+    };
+    sources: Array<{
+        id: string;
+        canonical_url: string;
+        access_path: string;
+        source_class: 'official' | 'implementation' | 'third_party' | 'community' | 'contrarian' | 'local';
+        retrieved_at: string;
+        version: string;
+        revision: string;
+        content_digest: string;
+        authority: 'high' | 'medium' | 'low';
+        freshness: 'high' | 'medium' | 'low';
+        directness: 'high' | 'medium' | 'low';
+    }>;
+    claims: Array<{
+        id: string;
+        text: string;
+        source_ids: string[];
+        confidence: 'high' | 'medium' | 'low';
+        uncertainty: string;
+        decision_impact: string;
+    }>;
+    acquisition_failures: Array<{
+        source_id: string;
+        kind: FailureKind;
+        note: string;
+    }>;
+    opposition: string;
+    recommendation: string;
+    stop_reason: string;
+}
+export interface ScoutReceipt extends ScoutReceiptSpec {
+    schema: 'yam.scout-receipt.v1';
+    created_at: string;
+    evidence_boundary: {
+        acquisition_by_yam: false;
+        source_interpretation: 'operator_supplied';
+        external_content_trusted_as_instruction: false;
+    };
+    truth_status: 'partial';
+    digest: string;
+}
+export declare function createScoutReceipt(input: {
+    root: string;
+    receipt_path: string;
+    spec: ScoutReceiptSpec;
+    now?: () => Date;
+}): Promise<{
+    schema: "yam.scout-receipt-write.v1";
+    receipt_path: string;
+    receipt: ScoutReceipt;
+    truth_status: "partial";
+    next_action: string;
+}>;
+export declare function verifyScoutReceipt(value: unknown): {
+    schema: "yam.scout-receipt-verification.v1";
+    valid: boolean;
+    errors: string[];
+    receipt_truth_status: any;
+    truth_status: "verified" | "blocked";
+    next_action: string;
+};
+export declare function verifyScoutReceiptFile(input: {
+    root: string;
+    receipt_path: string;
+}): Promise<{
+    receipt_path: string;
+    schema: "yam.scout-receipt-verification.v1";
+    valid: boolean;
+    errors: string[];
+    receipt_truth_status: any;
+    truth_status: "verified" | "blocked";
+    next_action: string;
+}>;
+export {};