sneakoscope 4.2.0 → 4.3.0

package/dist/core/qa-loop/qa-contract-v2.js

@@ -0,0 +1,231 @@
+import { CODEX_APP_SERVER_DOC_URL } from '../routes.js';
+import { nowIso } from '../fsx.js';
+import { inferAuthMode, inferQaTargetKind, selectQaSurfaceForContract } from './qa-surface-router.js';
+import { DEFAULT_QA_MAX_CYCLES, QA_LOOP_CONTRACT_VERSION } from './qa-types.js';
+export function buildQaContractV2(legacy = {}, options = {}) {
+    const answers = legacy.answers || {};
+    const prompt = stringValue(legacy.prompt || answers.GOAL_PRECISE || '');
+    const targetUrl = normalizeUnset(answers.TARGET_BASE_URL) || firstUrl(prompt) || null;
+    const authMode = authModeFromAnswers(answers, prompt);
+    const kind = targetKindFromAnswers(answers, prompt, targetUrl, authMode);
+    const uiRequired = uiRequiredFromAnswers(answers);
+    const apiRequired = apiRequiredFromAnswers(answers);
+    const reportOnly = options.reportOnly === true || stringValue(answers.QA_CORRECTIVE_POLICY) === 'report_only_no_code_changes';
+    return {
+        schema: 'sks.qa-loop-contract.v2',
+        version: QA_LOOP_CONTRACT_VERSION,
+        generated_at: nowIso(),
+        mission_id: options.missionId || legacy.mission_id || null,
+        prompt,
+        target: {
+            url: targetUrl,
+            environment: normalizeUnset(answers.TARGET_ENVIRONMENT) || 'local_dev_server',
+            kind,
+            dev_server_command: normalizeUnset(answers.DEV_SERVER_COMMAND),
+            api_base_url: normalizeUnset(answers.API_BASE_URL)
+        },
+        scope: {
+            ui_required: uiRequired,
+            api_required: apiRequired,
+            visual_required: uiRequired,
+            gpt_image_2_review_required: gptImage2RequiredFromAnswers(answers, prompt)
+        },
+        auth: {
+            required: stringValue(answers.LOGIN_REQUIRED) === 'yes' || authMode !== 'not_required',
+            mode: authMode,
+            credential_storage: 'never_store_credentials_in_artifacts_or_wiki'
+        },
+        mutation: {
+            product_data_policy: productDataPolicyFromAnswers(answers),
+            source_code_patch_policy: reportOnly ? 'disabled_report_only' : 'enabled',
+            production_side_effects: 'blocked_by_default',
+            destructive_deployed_tests: 'never'
+        },
+        runtime: {
+            max_cycles: boundedInteger(options.maxCycles ?? answers.MAX_QA_CYCLES, 1, 50, DEFAULT_QA_MAX_CYCLES),
+            no_progress_stop: true,
+            convergence_stop: true,
+            same_flow_replay_required: true,
+            no_headless_only_pass: true,
+            no_artifact_only_pass: true,
+            no_mock_as_real: true
+        },
+        cli: {
+            report_only: reportOnly,
+            requested_surface: options.requestedSurface || surfaceOverrideFromAnswers(answers),
+            fix_mode: reportOnly ? 'report_only' : 'safe_local_code_fixes'
+        },
+        legacy_contract_hash: legacy.sealed_hash || null
+    };
+}
+export function buildQaJourneyGraphV2(contract) {
+    const surface = selectQaSurfaceForContract(contract).selected_surface;
+    const steps = journeyStepsForContract(contract, surface);
+    return {
+        schema: 'sks.qa-loop-journey-graph.v2',
+        generated_at: nowIso(),
+        mission_id: contract.mission_id,
+        surface,
+        target: contract.target.url,
+        replay_fingerprint: replayFingerprint(contract, steps),
+        steps,
+        same_flow_replay_required: contract.runtime.same_flow_replay_required
+    };
+}
+export function buildQaAuthDataSandboxPolicy(contract) {
+    return {
+        schema: 'sks.qa-loop-auth-data-sandbox-policy.v2',
+        generated_at: nowIso(),
+        mission_id: contract.mission_id,
+        auth: {
+            required: contract.auth.required,
+            mode: contract.auth.mode,
+            credential_storage: contract.auth.credential_storage,
+            artifact_redaction: 'credentials_cookies_tokens_sensitive_screenshots_redacted_or_omitted'
+        },
+        mutation: contract.mutation,
+        approvals: {
+            source_code_patch: contract.mutation.source_code_patch_policy,
+            product_data_mutation: contract.mutation.product_data_policy,
+            production_side_effects: contract.mutation.production_side_effects,
+            destructive_deployed_tests: contract.mutation.destructive_deployed_tests
+        },
+        docs_url: CODEX_APP_SERVER_DOC_URL
+    };
+}
+function journeyStepsForContract(contract, surface) {
+    const steps = [];
+    if (contract.scope.ui_required) {
+        steps.push({
+            id: 'open-target',
+            kind: 'open',
+            label: `Open target with ${surface}`,
+            target: contract.target.url,
+            expected: 'target renders without fatal error',
+            data_classification: contract.target.kind === 'local_web' ? 'local_fixture' : 'public'
+        });
+        steps.push({
+            id: 'exercise-primary-flow',
+            kind: 'click',
+            label: 'Exercise the primary user journey with real UI actions',
+            target: contract.target.url,
+            expected: 'actual state matches the expected journey state',
+            data_classification: contract.auth.required ? 'sensitive' : 'public'
+        });
+        steps.push({
+            id: 'assert-visible-state',
+            kind: 'assert',
+            label: 'Compare expected and observed rendered state',
+            target: contract.target.url,
+            expected: 'assertions are backed by action and observation ledger entries',
+            data_classification: 'public'
+        });
+    }
+    if (contract.scope.api_required) {
+        steps.push({
+            id: 'api-readiness',
+            kind: 'inspect',
+            label: 'Inspect safe API readiness and error states',
+            target: contract.target.api_base_url || contract.target.url,
+            expected: 'API checks stay inside the sandbox policy',
+            data_classification: 'public'
+        });
+    }
+    steps.push({
+        id: 'fix-and-replay',
+        kind: 'replay',
+        label: 'Replay exactly the same journey after each applied fix',
+        target: contract.target.url,
+        expected: 'every applied fix is followed by same-flow replay evidence',
+        data_classification: 'source_code'
+    });
+    return steps;
+}
+function targetKindFromAnswers(answers, prompt, targetUrl, authMode) {
+    const explicit = stringValue(answers.QA_TARGET_KIND);
+    if (isQaTargetKind(explicit))
+        return explicit;
+    return inferQaTargetKind({ prompt, targetUrl, authMode });
+}
+function authModeFromAnswers(answers, prompt) {
+    const explicit = stringValue(answers.QA_AUTH_MODE);
+    if (isQaAuthMode(explicit))
+        return explicit;
+    if (stringValue(answers.LOGIN_REQUIRED) === 'yes') {
+        if (stringValue(answers.TEMP_TEST_CREDENTIALS_READY) === 'yes_temp_only')
+            return 'runtime_ephemeral_credentials';
+        return 'blocked_missing_credentials';
+    }
+    return inferAuthMode(prompt);
+}
+function productDataPolicyFromAnswers(answers) {
+    const policy = stringValue(answers.QA_MUTATION_POLICY);
+    if (policy === 'seeded_create_change_remove_local_only')
+        return 'seeded_local_only';
+    if (policy === 'seeded_create_change_only')
+        return 'sandbox_only';
+    return 'read_only';
+}
+function surfaceOverrideFromAnswers(answers) {
+    const value = stringValue(answers.QA_SURFACE || answers.QA_REQUESTED_SURFACE || answers.REQUESTED_SURFACE);
+    if (!value || value === 'auto')
+        return value === 'auto' ? 'auto' : null;
+    if (['codex_in_app_browser', 'codex_chrome_extension', 'codex_computer_use', 'codex_app_plugin', 'structured_mcp', 'shell_or_api_diagnostic'].includes(value)) {
+        return value;
+    }
+    return null;
+}
+function uiRequiredFromAnswers(answers) {
+    const scope = stringValue(answers.QA_SCOPE || 'ui_e2e_only');
+    if (scope === 'api_e2e_only')
+        return false;
+    if (scope === 'all_available')
+        return Boolean(normalizeUnset(answers.TARGET_BASE_URL));
+    return ['ui_e2e_only', 'ui_and_api_e2e'].includes(scope);
+}
+function apiRequiredFromAnswers(answers) {
+    const scope = stringValue(answers.QA_SCOPE || 'ui_e2e_only');
+    return ['api_e2e_only', 'ui_and_api_e2e', 'all_available'].includes(scope);
+}
+function gptImage2RequiredFromAnswers(answers, prompt) {
+    const explicit = stringValue(answers.QA_VISUAL_REVIEW_IMAGEGEN_REQUIRED || answers.GPT_IMAGE_2_ANNOTATED_REVIEW_REQUIRED);
+    if (/^(yes|true|required|yes_gpt_image_2_annotated_review)$/i.test(explicit))
+        return true;
+    if (/^(no|false|not_required|none)$/i.test(explicit))
+        return false;
+    return /(gpt-image-2|gpt\s*image\s*2|imagegen|\$imagegen|annotated\s+review|callout|주석\s*이미지|콜아웃)/i.test(prompt);
+}
+function replayFingerprint(contract, steps) {
+    return [
+        contract.version,
+        contract.target.kind,
+        contract.target.url || 'no-url',
+        contract.auth.mode,
+        steps.map((step) => `${step.id}:${step.kind}:${step.target || ''}`).join('|')
+    ].join('::');
+}
+function firstUrl(value) {
+    return value.match(/https?:\/\/[^\s)\]}>,]+/i)?.[0] || null;
+}
+function normalizeUnset(value) {
+    const text = stringValue(value);
+    if (!text || /^(none|not_required|n\/a|na|unset|same_as_target)$/i.test(text))
+        return null;
+    return text;
+}
+function stringValue(value) {
+    return String(value || '').trim();
+}
+function boundedInteger(value, min, max, fallback) {
+    const n = Number.parseInt(String(value ?? ''), 10);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(min, Math.min(max, n));
+}
+function isQaTargetKind(value) {
+    return ['local_web', 'public_web', 'signed_in_web', 'native_gui', 'cross_app_gui', 'structured_data', 'api_or_shell'].includes(value);
+}
+function isQaAuthMode(value) {
+    return ['not_required', 'runtime_ephemeral_credentials', 'existing_browser_profile', 'blocked_missing_credentials', 'unknown'].includes(value);
+}
+//# sourceMappingURL=qa-contract-v2.js.map

package/dist/core/qa-loop/qa-gate-v2.js

@@ -0,0 +1,132 @@
+import path from 'node:path';
+import { exists, nowIso, readJson, readText, writeJsonAtomic } from '../fsx.js';
+import { QA_ACTION_LEDGER_ARTIFACT, QA_CONTRACT_V2_ARTIFACT, QA_FINDING_LEDGER_ARTIFACT, QA_FIX_LEDGER_ARTIFACT, QA_GATE_V2_ARTIFACT, QA_OBSERVATION_LEDGER_ARTIFACT, QA_REPLAY_LEDGER_ARTIFACT, QA_SURFACE_SELECTION_ARTIFACT } from './qa-types.js';
+export async function evaluateQaGateV2(dir) {
+    const contract = await readJson(path.join(dir, QA_CONTRACT_V2_ARTIFACT), null);
+    const surface = await readJson(path.join(dir, QA_SURFACE_SELECTION_ARTIFACT), null);
+    const actions = await readJsonl(path.join(dir, QA_ACTION_LEDGER_ARTIFACT));
+    const observations = await readJsonl(path.join(dir, QA_OBSERVATION_LEDGER_ARTIFACT));
+    const findings = await readJsonl(path.join(dir, QA_FINDING_LEDGER_ARTIFACT));
+    const fixes = await readJsonl(path.join(dir, QA_FIX_LEDGER_ARTIFACT));
+    const replays = await readJsonl(path.join(dir, QA_REPLAY_LEDGER_ARTIFACT));
+    const blockers = [];
+    const unverified = [];
+    if (!contract)
+        blockers.push('qa_contract_v2_missing');
+    if (!surface)
+        blockers.push('qa_surface_selection_missing');
+    const uiRequired = contract?.scope?.ui_required === true;
+    const findingRecords = findings.filter(isRuntimeRecord);
+    const fixRecords = fixes.filter(isRuntimeRecord);
+    const replayRecords = replays.filter(isRuntimeRecord);
+    const realActions = actions.filter(isRuntimeRecord).filter(isRealRecord);
+    const realObservations = observations.filter(isRuntimeRecord).filter(isRealRecord);
+    const unresolvedFindings = findingRecords.filter((record) => !['resolved', 'false_positive', 'deferred_nonfixable'].includes(String(record.status || record.data?.status || '')));
+    const appliedFixes = fixRecords.filter((record) => ['applied', 'verified'].includes(String(record.status || record.data?.status || '')));
+    const completedReplays = replayRecords.filter((record) => ['passed', 'completed', 'verified'].includes(String(record.status || record.data?.status || '')));
+    const sameFlowReplayComplete = appliedFixes.length === 0 || appliedFixes.every((fix) => {
+        const fixId = String(fix.fix_id || fix.data?.fix_id || fix.item_id || '');
+        const journey = String(fix.journey_fingerprint || fix.data?.journey_fingerprint || '');
+        return completedReplays.some((replay) => {
+            const replayFix = String(replay.fix_id || replay.data?.fix_id || replay.item_id || '');
+            const replayJourney = String(replay.journey_fingerprint || replay.data?.journey_fingerprint || '');
+            return (!fixId || replayFix === fixId) && (!journey || replayJourney === journey);
+        });
+    });
+    if (uiRequired && realActions.length === 0)
+        blockers.push('ui_required_but_real_action_count_zero');
+    if (uiRequired && realObservations.length === 0)
+        blockers.push('ui_required_but_observation_count_zero');
+    if (appliedFixes.length > 0 && !sameFlowReplayComplete)
+        blockers.push('applied_fix_without_same_flow_replay');
+    if (unresolvedFindings.length > 0)
+        blockers.push('unresolved_findings_remaining');
+    if (recordsContainSyntheticAsReal([...actions, ...observations, ...findings, ...fixes, ...replays]))
+        blockers.push('synthetic_or_mock_record_claimed_as_real');
+    if (surface?.selected_surface && uiRequired && ['structured_mcp', 'shell_or_api_diagnostic'].includes(surface.selected_surface)) {
+        blockers.push('ui_required_without_visual_surface');
+    }
+    if (surface && surface.visual_surface_required && realActions.length === 0) {
+        unverified.push(`${surface.selected_surface}_live_action_evidence_missing`);
+    }
+    const uniqueBlockers = [...new Set(blockers)];
+    const uniqueUnverified = [...new Set(unverified)];
+    const passed = uniqueBlockers.length === 0;
+    const result = {
+        schema: 'sks.qa-loop-gate.v2',
+        checked_at: nowIso(),
+        passed,
+        status: passed ? 'passed' : uniqueBlockers.some((item) => item.includes('missing') || item.includes('zero')) ? 'blocked' : 'failed',
+        mission_id: contract?.mission_id || surface?.mission_id || null,
+        selected_surface: surface?.selected_surface || null,
+        ui_required: uiRequired,
+        real_action_count: realActions.length,
+        observation_count: realObservations.length,
+        finding_count: findingRecords.length,
+        unresolved_finding_count: unresolvedFindings.length,
+        applied_fix_count: appliedFixes.length,
+        replay_count: completedReplays.length,
+        same_flow_replay_complete: sameFlowReplayComplete,
+        blockers: uniqueBlockers,
+        unverified: uniqueUnverified,
+        artifacts: {
+            contract_v2: QA_CONTRACT_V2_ARTIFACT,
+            surface_selection: QA_SURFACE_SELECTION_ARTIFACT,
+            action_ledger: QA_ACTION_LEDGER_ARTIFACT,
+            observation_ledger: QA_OBSERVATION_LEDGER_ARTIFACT,
+            finding_ledger: QA_FINDING_LEDGER_ARTIFACT,
+            fix_ledger: QA_FIX_LEDGER_ARTIFACT,
+            replay_ledger: QA_REPLAY_LEDGER_ARTIFACT
+        }
+    };
+    await writeJsonAtomic(path.join(dir, QA_GATE_V2_ARTIFACT), result);
+    return result;
+}
+async function readJsonl(file) {
+    if (!(await exists(file)))
+        return [];
+    const text = await readText(file, '');
+    const records = [];
+    for (const line of String(text).split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const value = JSON.parse(line);
+            if (value && typeof value === 'object')
+                records.push(value);
+        }
+        catch {
+            records.push({ schema: 'sks.qa-loop.invalid-jsonl-record', status: 'invalid_json' });
+        }
+    }
+    return records;
+}
+function isRealRecord(record) {
+    const status = String(record.status || record.data?.status || '');
+    if (status === 'invalid_json')
+        return false;
+    if (record.synthetic === true || record.mock === true || record.fixture === true)
+        return false;
+    if (record.data?.synthetic === true || record.data?.mock === true || record.data?.fixture === true)
+        return false;
+    return ['real', 'passed', 'completed', 'observed', 'captured', 'verified', 'failed'].includes(status)
+        || record.real === true
+        || record.data?.real === true;
+}
+function isRuntimeRecord(record) {
+    const status = String(record.status || record.data?.status || '');
+    const kind = String(record.kind || record.data?.kind || '');
+    if (status === 'metadata' || kind === 'ledger_initialized')
+        return false;
+    if (record.schema === 'sks.qa-loop-ledger-init.v2')
+        return false;
+    return status !== 'invalid_json';
+}
+function recordsContainSyntheticAsReal(records) {
+    return records.some((record) => {
+        const synthetic = record.synthetic === true || record.mock === true || record.fixture === true || record.data?.synthetic === true || record.data?.mock === true || record.data?.fixture === true;
+        const claimedReal = record.real === true || record.data?.real === true || /real|live/i.test(String(record.status || record.data?.status || ''));
+        return synthetic && claimedReal;
+    });
+}
+//# sourceMappingURL=qa-gate-v2.js.map

package/dist/core/qa-loop/qa-runtime-artifacts.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { appendJsonlBounded, nowIso, writeJsonAtomic } from '../fsx.js';
+import { buildQaAuthDataSandboxPolicy, buildQaContractV2, buildQaJourneyGraphV2 } from './qa-contract-v2.js';
+import { selectQaSurfaceForContract } from './qa-surface-router.js';
+import { evaluateQaGateV2 } from './qa-gate-v2.js';
+import { QA_ACTION_LEDGER_ARTIFACT, QA_ASSERTION_LEDGER_ARTIFACT, QA_AUTH_DATA_POLICY_ARTIFACT, QA_CONTRACT_V2_ARTIFACT, QA_FINDING_LEDGER_ARTIFACT, QA_FIX_LEDGER_ARTIFACT, QA_JOURNEY_GRAPH_ARTIFACT, QA_OBSERVATION_LEDGER_ARTIFACT, QA_REPLAY_LEDGER_ARTIFACT, QA_RUNTIME_EVENT_LEDGER_ARTIFACT, QA_SURFACE_SELECTION_ARTIFACT } from './qa-types.js';
+export async function initializeQaRuntimeArtifacts(dir, legacyContract, options = {}) {
+    const contract = buildQaContractV2(legacyContract, options);
+    const surface = selectQaSurfaceForContract(contract);
+    const journey = buildQaJourneyGraphV2(contract);
+    const authDataPolicy = buildQaAuthDataSandboxPolicy(contract);
+    await writeJsonAtomic(path.join(dir, QA_CONTRACT_V2_ARTIFACT), contract);
+    await writeJsonAtomic(path.join(dir, QA_SURFACE_SELECTION_ARTIFACT), surface);
+    await writeJsonAtomic(path.join(dir, QA_JOURNEY_GRAPH_ARTIFACT), journey);
+    await writeJsonAtomic(path.join(dir, QA_AUTH_DATA_POLICY_ARTIFACT), authDataPolicy);
+    await appendRuntimeEvent(dir, 'qa-runtime.v2.initialized', {
+        selected_surface: surface.selected_surface,
+        target_kind: surface.target_kind,
+        ui_required: contract.scope.ui_required,
+        max_cycles: contract.runtime.max_cycles
+    });
+    await ensureLedgerPlaceholders(dir);
+    const gateV2 = await evaluateQaGateV2(dir);
+    return { contract, surface, journey, authDataPolicy, gateV2 };
+}
+async function appendRuntimeEvent(dir, kind, data) {
+    await appendJsonlBounded(path.join(dir, QA_RUNTIME_EVENT_LEDGER_ARTIFACT), {
+        schema: 'sks.qa-loop-runtime-event.v2',
+        ts: nowIso(),
+        kind,
+        status: 'completed',
+        data
+    });
+}
+async function ensureLedgerPlaceholders(dir) {
+    for (const artifact of [
+        QA_ACTION_LEDGER_ARTIFACT,
+        QA_OBSERVATION_LEDGER_ARTIFACT,
+        QA_ASSERTION_LEDGER_ARTIFACT,
+        QA_FINDING_LEDGER_ARTIFACT,
+        QA_FIX_LEDGER_ARTIFACT,
+        QA_REPLAY_LEDGER_ARTIFACT
+    ]) {
+        await appendJsonlBounded(path.join(dir, artifact), {
+            schema: 'sks.qa-loop-ledger-init.v2',
+            ts: nowIso(),
+            kind: 'ledger_initialized',
+            status: 'metadata',
+            real: false
+        });
+    }
+}
+//# sourceMappingURL=qa-runtime-artifacts.js.map

package/dist/core/qa-loop/qa-surface-router.js

@@ -0,0 +1,114 @@
+import { CODEX_APP_SERVER_DOC_URL, CODEX_CHROME_EXTENSION_DOC_URL, CODEX_COMPUTER_USE_DOC_URL, CODEX_IN_APP_BROWSER_DOC_URL } from '../routes.js';
+import { nowIso } from '../fsx.js';
+export function inferQaTargetKind(input) {
+    const prompt = String(input.prompt || '').toLowerCase();
+    const url = String(input.targetUrl || '').trim();
+    if (/(native|desktop|macos|windows|os\s*setting|system settings|finder|xcode|appname|@computer|@appname|네이티브|데스크톱|운영체제|설정)/i.test(prompt)) {
+        return /(multi[- ]?app|cross[- ]?app|여러\s*앱|앱\s*간)/i.test(prompt) ? 'cross_app_gui' : 'native_gui';
+    }
+    if (input.authMode === 'existing_browser_profile' || /(signed[- ]?in|logged[- ]?in|cookie|profile|extension|internal tool|sso|로그인|쿠키|프로필|확장)/i.test(prompt)) {
+        return 'signed_in_web';
+    }
+    if (/^(?:https?:\/\/)?(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?(?:\/|$)/i.test(url) || /^file:\/\//i.test(url))
+        return 'local_web';
+    if (/^https?:\/\//i.test(url))
+        return 'public_web';
+    if (/(database|mcp|plugin|spreadsheet|notion|gmail|slack|data sync|structured data|데이터|플러그인)/i.test(prompt))
+        return 'structured_data';
+    if (/(api|endpoint|cli|shell|command|엔드포인트|명령어)/i.test(prompt))
+        return 'api_or_shell';
+    return 'local_web';
+}
+export function selectQaSurface(input) {
+    const uiRequired = input.uiRequired !== false;
+    const authMode = input.authMode || inferAuthMode(input.prompt || '');
+    const targetKind = input.targetKind || inferQaTargetKind({ prompt: input.prompt ?? null, targetUrl: input.targetUrl ?? null, authMode });
+    const requested = input.requestedSurface && input.requestedSurface !== 'auto' ? input.requestedSurface : null;
+    const policySurface = surfaceForKind(targetKind, uiRequired, authMode);
+    const selected = requested || policySurface;
+    const reason = requested
+        ? `operator_requested_${requested}_after_policy_kind_${targetKind}`
+        : reasonForSelection(policySurface, targetKind, authMode);
+    return {
+        schema: 'sks.qa-loop-surface-selection.v2',
+        selected_at: nowIso(),
+        mission_id: input.missionId || null,
+        selected_surface: selected,
+        target_kind: targetKind,
+        auth_mode: authMode,
+        ui_required: uiRequired,
+        reason,
+        docs_url: docsUrlForSurface(selected),
+        alternatives: alternativesFor(policySurface, selected, targetKind, authMode),
+        structured_data_first: targetKind === 'structured_data',
+        visual_surface_required: uiRequired && !['structured_mcp', 'shell_or_api_diagnostic'].includes(selected)
+    };
+}
+export function selectQaSurfaceForContract(contract) {
+    return selectQaSurface({
+        missionId: contract.mission_id,
+        prompt: contract.prompt,
+        targetUrl: contract.target.url,
+        uiRequired: contract.scope.ui_required,
+        authMode: contract.auth.mode,
+        requestedSurface: contract.cli.requested_surface,
+        targetKind: contract.target.kind
+    });
+}
+export function inferAuthMode(prompt) {
+    if (/(cookie|profile|existing tab|extension|signed[- ]?in session|browser state|쿠키|프로필|세션)/i.test(prompt))
+        return 'existing_browser_profile';
+    if (/(login|log in|signin|sign in|auth|credential|sso|로그인|인증|계정)/i.test(prompt))
+        return 'blocked_missing_credentials';
+    return 'not_required';
+}
+function surfaceForKind(kind, uiRequired, authMode) {
+    if (!uiRequired && kind === 'structured_data')
+        return 'structured_mcp';
+    if (!uiRequired)
+        return 'shell_or_api_diagnostic';
+    if (kind === 'signed_in_web' || authMode === 'existing_browser_profile' || authMode === 'runtime_ephemeral_credentials')
+        return 'codex_chrome_extension';
+    if (kind === 'native_gui' || kind === 'cross_app_gui')
+        return 'codex_computer_use';
+    if (kind === 'structured_data')
+        return 'structured_mcp';
+    return 'codex_in_app_browser';
+}
+function reasonForSelection(surface, kind, authMode) {
+    if (surface === 'codex_in_app_browser')
+        return `local_or_public_unauthenticated_web_kind_${kind}`;
+    if (surface === 'codex_chrome_extension')
+        return `signed_in_browser_state_required_auth_${authMode}`;
+    if (surface === 'codex_computer_use')
+        return `native_or_cross_app_gui_kind_${kind}`;
+    if (surface === 'structured_mcp')
+        return 'structured_data_operation_first_then_visual_verify_if_needed';
+    return 'api_or_shell_diagnostic_no_ui_surface_required';
+}
+function docsUrlForSurface(surface) {
+    if (surface === 'codex_in_app_browser')
+        return CODEX_IN_APP_BROWSER_DOC_URL;
+    if (surface === 'codex_chrome_extension')
+        return CODEX_CHROME_EXTENSION_DOC_URL;
+    if (surface === 'codex_computer_use')
+        return CODEX_COMPUTER_USE_DOC_URL;
+    return CODEX_APP_SERVER_DOC_URL;
+}
+function alternativesFor(policySurface, selected, kind, authMode) {
+    const choices = ['codex_in_app_browser', 'codex_chrome_extension', 'codex_computer_use', 'structured_mcp', 'shell_or_api_diagnostic'];
+    return choices.map((surface) => {
+        if (surface === selected)
+            return { surface, status: 'selected', reason: surface === policySurface ? 'policy_default' : 'operator_override' };
+        if (surface === policySurface)
+            return { surface, status: 'fallback_candidate', reason: 'policy_default_not_selected_due_override' };
+        if (surface === 'codex_chrome_extension' && authMode === 'not_required' && (kind === 'local_web' || kind === 'public_web')) {
+            return { surface, status: 'not_applicable', reason: 'no_signed_in_browser_state_required' };
+        }
+        if (surface === 'codex_computer_use' && !['native_gui', 'cross_app_gui'].includes(kind)) {
+            return { surface, status: 'blocked_by_policy', reason: 'not_native_or_cross_app_gui' };
+        }
+        return { surface, status: 'not_applicable', reason: `not_required_for_${kind}` };
+    });
+}
+//# sourceMappingURL=qa-surface-router.js.map

package/dist/core/qa-loop/qa-types.js

@@ -0,0 +1,18 @@
+export const QA_LOOP_CONTRACT_VERSION = 2;
+export const DEFAULT_QA_MAX_CYCLES = 5;
+export const QA_LOOP_V2_DIR = 'qa-loop';
+export const QA_CONTRACT_V2_ARTIFACT = 'qa-loop/qa-contract-v2.json';
+export const QA_SURFACE_SELECTION_ARTIFACT = 'qa-loop/qa-surface-selection.json';
+export const QA_JOURNEY_GRAPH_ARTIFACT = 'qa-loop/qa-journey-graph.json';
+export const QA_ACTION_LEDGER_ARTIFACT = 'qa-loop/action-ledger.jsonl';
+export const QA_OBSERVATION_LEDGER_ARTIFACT = 'qa-loop/observation-ledger.jsonl';
+export const QA_ASSERTION_LEDGER_ARTIFACT = 'qa-loop/assertion-ledger.jsonl';
+export const QA_FINDING_LEDGER_ARTIFACT = 'qa-loop/finding-ledger.jsonl';
+export const QA_FIX_LEDGER_ARTIFACT = 'qa-loop/fix-ledger.jsonl';
+export const QA_REPLAY_LEDGER_ARTIFACT = 'qa-loop/replay-ledger.jsonl';
+export const QA_RUNTIME_EVENT_LEDGER_ARTIFACT = 'qa-loop/runtime-events.jsonl';
+export const QA_GATE_V2_ARTIFACT = 'qa-loop/qa-gate-v2.json';
+export const QA_LIVE_SESSION_ARTIFACT = 'qa-loop/live-session.json';
+export const QA_DEV_SERVER_ARTIFACT = 'qa-loop/dev-server.json';
+export const QA_AUTH_DATA_POLICY_ARTIFACT = 'qa-loop/auth-data-sandbox-policy.json';
+//# sourceMappingURL=qa-types.js.map