create-principles-disciple 1.145.41 → 1.145.43

package/console/dist/server/routes/examiner.js

@@ -0,0 +1,296 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { sendSuccess, sendError, sendNotFound } from '../utils/response.js';
+import { PrinciplesConsoleModel } from '../models/PrinciplesConsoleModel.js';
+import { loadLabModules, loadHostCapability, preflightCheck, offlineStudyPass, reportMaterialize, listStudyNames, resolveStudyAccess, resolveStudyRoots, studyStatusPayload, studyReportPayload, materializeConsoleStudy, verifyConsoleOwnership, writableRootProblem, isJsonObject, ExaminerPreflightBlockedError, } from './examiner-executor.js';
+/* eslint-disable @typescript-eslint/max-params -- node:http handler signature (req, res, workspaceDir, subPath) matches every other route */
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, '..', '..', '..', '..', '..');
+const labRoot = path.join(repoRoot, 'scripts', 'dev', 'principle-learning-lab');
+const PRINCIPLE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const STUDY_ROUTE_PATTERN = /^\/studies\/([A-Za-z0-9-]+)(\/[^/]*)?$/;
+/**
+ * P2-1: the Examiner is a DEV-ONLY capability. The gate is SERVER-SIDE and
+ * cannot be set by a client — it reads only the running module's own URL and
+ * the operator's environment: a source run (tsx/vitest, import.meta.url ends
+ * with .ts) or an explicit `PD_EXAMINER_DEV=1`. `NODE_ENV=production` is an
+ * UNCONDITIONAL hard gate: not even the DEV override can enable the surface
+ * there, so a production build (`dist/server.js`) answers 404 — never 503.
+ */
+export function isExaminerDevRuntime(moduleUrl, env = process.env) {
+    if (env.NODE_ENV === 'production')
+        return false;
+    if (env.PD_EXAMINER_DEV === '1')
+        return true;
+    return moduleUrl.endsWith('.ts');
+}
+function examinerDevEnabled() {
+    return isExaminerDevRuntime(import.meta.url);
+}
+/** The runner's lock-time re-verification refusal (dynamic module: match the
+ *  contract name, not an instanceof across import boundaries). */
+function isFrozenStudyDriftError(error) {
+    return error instanceof Error && error.name === 'FrozenStudyDriftError';
+}
+/**
+ * Drift details are CONTRACT output (check names + case ids), but they travel
+ * into an HTTP payload: scrub anything path-shaped and bound the size so a
+ * refusal never leaks filesystem internals or parser text.
+ */
+function driftProblems(details) {
+    if (typeof details !== 'string')
+        return [];
+    return details
+        .split(';')
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .map((part) => part
+        .replace(/[A-Za-z]:[\\/][^\s;]*/g, '<path>')
+        .replace(/(^|[\s(=])\/[^\s;()]+/g, '$1<path>')
+        .slice(0, 240))
+        .slice(0, 20);
+}
+/**
+ * Responses carry stable reason codes, never raw exception text: a thrown
+ * message can embed absolute paths and other internals that are not
+ * Owner-facing information. The full error stays in the server log.
+ */
+function logRefusal(scope, error) {
+    console.error(`[pd-console] examiner ${scope}:`, error);
+}
+let labModules = null;
+let hostCapability = null;
+let labUnavailableReason = null;
+async function loadLab() {
+    if (hostCapability)
+        return hostCapability;
+    try {
+        labModules = await loadLabModules(labRoot);
+        hostCapability = await loadHostCapability(labRoot);
+        return hostCapability;
+    }
+    catch (error) {
+        logRefusal('lab unavailable', error);
+        labUnavailableReason = 'lab tooling could not be loaded (details in the console server log)';
+        labModules = null;
+        hostCapability = null;
+        return null;
+    }
+}
+function readBody(req) {
+    return new Promise((resolve) => {
+        let raw = '';
+        req.on('data', (chunk) => {
+            raw += String(chunk);
+        });
+        req.on('end', () => {
+            if (!raw) {
+                resolve({});
+                return;
+            }
+            try {
+                const parsed = JSON.parse(raw);
+                resolve(isJsonObject(parsed) ? parsed : {});
+            }
+            catch {
+                resolve({});
+            }
+        });
+    });
+}
+export async function handleExaminerRoute(req, res, workspaceDir, subPath) {
+    if (!examinerDevEnabled()) {
+        sendError(res, 404, 'examiner_not_enabled', 'The Examiner research surface is a local-dev capability and is not enabled in this runtime');
+        return;
+    }
+    const lab = await loadLab();
+    if (!lab || !labModules) {
+        sendError(res, 503, 'examiner_dev_tooling_unavailable', `Examiner dev tooling is not available in this installation (the principle-learning-lab lives in the repository's scripts/dev area): ${labUnavailableReason ?? 'unknown reason'}`);
+        return;
+    }
+    const method = req.method ?? 'GET';
+    const roots = resolveStudyRoots(labRoot);
+    const context = { labRoot, roots };
+    const rootProblem = writableRootProblem(roots);
+    // GET /overview
+    if (subPath === '/overview' && method === 'GET') {
+        const writable = listStudyNames(roots.writable);
+        const historical = listStudyNames(roots.historical);
+        sendSuccess(res, {
+            spec: 'SPEC-PD-EXAMINER-001 v0.9',
+            executionScope: 'offline-stub only — real model calls and real host runs are NOT authorized this round',
+            gates: {
+                gate1_challenge_trust: 'BLOCKED — independent human Gold review has not been performed for any Examiner suite (code tests can never substitute)',
+                gate2_behavior_evaluation: 'NOT_READY — requires Gate 1 + real-host authorization',
+                gate3_llm_authoring: 'NOT_STARTED',
+                gate4_product_integration: 'NOT_STARTED (local-dev console integration; the production UI/API is disabled)',
+            },
+            hostInjectionCapability: lab,
+            fullConclusionMinimumLevel: 'CONTEXT_PRESENT',
+            writableStudiesRoot: roots.writable,
+            historicalStudiesRoot: roots.historical,
+            rootProblem,
+            studies: [...writable, ...historical.filter((name) => !writable.includes(name))],
+            readOnlyStudies: [
+                ...historical,
+                ...writable.filter((name) => !verifyConsoleOwnership(roots.writable, path.join(roots.writable, name)).ok),
+            ],
+        });
+        return;
+    }
+    // GET /principles — real workspace principles as study inputs (read-only)
+    if (subPath === '/principles' && method === 'GET') {
+        const model = new PrinciplesConsoleModel(workspaceDir);
+        const list = await model.listPrinciples();
+        const principles = (list.principles ?? []).map((p) => ({ id: p.id, version: 'ledger', text: p.text, status: p.status, ruleCount: p.ruleCount ?? 0 }));
+        sendSuccess(res, { principles, note: 'study inputs are read from the workspace ledger (read-only); eligibility filtering happens inside the Examiner contract' });
+        return;
+    }
+    // POST /studies — create an offline examiner study (identity server-minted)
+    if (subPath === '/studies' && method === 'POST') {
+        if (rootProblem) {
+            sendError(res, 409, 'writable_root_not_isolated', rootProblem);
+            return;
+        }
+        const body = await readBody(req);
+        const requestedTarget = typeof body.targetPrincipleId === 'string' ? body.targetPrincipleId.trim() : '';
+        const requestedMode = typeof body.experimentMode === 'string' ? body.experimentMode : '';
+        const repetitionsRaw = Number(body.repetitionsPerCase);
+        const repetitionsPerCase = Number.isInteger(repetitionsRaw) && repetitionsRaw >= 1 && repetitionsRaw <= 5 ? repetitionsRaw : 2;
+        if (!PRINCIPLE_ID_PATTERN.test(requestedTarget)) {
+            sendError(res, 400, 'invalid_target_principle', 'targetPrincipleId required (charset-validated principle id; one target Principle per study)');
+            return;
+        }
+        const model = new PrinciplesConsoleModel(workspaceDir);
+        const list = await model.listPrinciples();
+        const ledgerPrinciples = (list.principles ?? []).map((p) => ({ id: p.id, version: 'ledger', text: p.text, status: p.status, ruleCount: p.ruleCount ?? 0 }));
+        // The request only SELECTS: the target travels onward as an INDEX into
+        // the server's own ledger list (exact-match required) and the mode as a
+        // BOOLEAN; the study identity/directory/seed are minted server-side. No
+        // request string crosses into the research pipeline.
+        const targetIndex = ledgerPrinciples.findIndex((p) => p.id === requestedTarget);
+        if (targetIndex < 0) {
+            sendError(res, 404, 'target_principle_not_found', 'the target principle was not found in the workspace ledger');
+            return;
+        }
+        const isolatedMode = requestedMode === 'isolated_principle';
+        try {
+            const created = await materializeConsoleStudy(labModules, labRoot, roots, {
+                isolatedMode,
+                targetIndex,
+                ledgerPrinciples,
+                repetitionsPerCase,
+            });
+            sendSuccess(res, {
+                studyId: created.studyId,
+                targetPrincipleId: created.targetPrincipleId,
+                experimentMode: isolatedMode ? 'isolated_principle' : 'full_library_incremental',
+                plannedPairs: created.plannedPairs,
+                manifestHash: created.manifestHash,
+                note: 'offline study created with SYNTHETIC gold — run preflight, then the offline-stub execution; results demonstrate the contract pipeline, never real host behavior',
+            });
+        }
+        catch (error) {
+            logRefusal('study creation refused', error);
+            sendError(res, 422, 'study_creation_refused', 'the study was refused before any file was written (details in the console server log)');
+        }
+        return;
+    }
+    // /studies/:studyId[/...]
+    const studyMatch = STUDY_ROUTE_PATTERN.exec(subPath);
+    if (studyMatch && studyMatch[1]) {
+        const rest = studyMatch[2] ?? '';
+        const access = resolveStudyAccess(roots, studyMatch[1]);
+        if (!access) {
+            sendError(res, 404, 'study_not_found', 'study not found');
+            return;
+        }
+        const studyDir = access.dir;
+        // GET status
+        if (rest === '' && method === 'GET') {
+            sendSuccess(res, { ...studyStatusPayload(studyDir), readOnly: access.readOnly, access: access.reason });
+            return;
+        }
+        // POST /preflight — the fail-closed gate over the frozen study facts
+        if (rest === '/preflight' && method === 'POST') {
+            const preflight = preflightCheck(labModules, studyDir, context);
+            sendSuccess(res, { studyId: access.studyId, ok: preflight.ok, status: preflight.status, blockers: preflight.blockers, warnings: preflight.warnings, checks: preflight.checks });
+            return;
+        }
+        // POST /run — offline-stub only; real modes are refused at THIS boundary.
+        // P1-1/P1-4: the study must be server-owned and writable, and the SERVER
+        // preflight must pass BEFORE the runner is entered. A blocker returns 409
+        // with no RUN_STARTED event, no reservation and no actor creation.
+        if (rest === '/run' && method === 'POST') {
+            const body = await readBody(req);
+            // Real execution needs an Owner-approved run-authorization.json plus the
+            // Stage R gate — this console route NEVER transports a caller-supplied
+            // mode into the runner; only the offline-stub default is reachable.
+            if (body.mode !== undefined && body.mode !== 'offline-stub') {
+                sendError(res, 403, 'real_execution_not_authorized', 'non-offline execution requires explicit Owner authorization (run-authorization.json + Stage R gate) — NOT GRANTED this round');
+                return;
+            }
+            if (access.readOnly) {
+                sendError(res, 403, 'study_read_only', `this study cannot be executed from the console: ${access.reason}`);
+                return;
+            }
+            try {
+                const summary = await offlineStudyPass(labModules, studyDir, context);
+                sendSuccess(res, { studyId: access.studyId, units: summary.units.map((unit) => ({ unit: unit.unit, state: unit.state })) });
+            }
+            catch (error) {
+                // P1-4: both gates answer the same 409 shape. The server preflight
+                // refuses BEFORE RUN_STARTED; the runner re-verifies UNDER the study
+                // lock and refuses on drift discovered after that first check. Either
+                // way: no RUN_STARTED, no reservation, no actor, no attempt file.
+                if (error instanceof ExaminerPreflightBlockedError) {
+                    sendError(res, 409, 'preflight_blocked', 'offline preflight blocked; no run started, no unit reserved, no actor created', {
+                        blockers: error.blockers,
+                    });
+                    return;
+                }
+                if (isFrozenStudyDriftError(error)) {
+                    sendError(res, 409, 'preflight_blocked', 'the frozen study drifted after preflight; no run started, no unit reserved, no actor created', {
+                        blockers: [{ id: 'frozen_study_drift', problems: driftProblems(error.details) }],
+                    });
+                    return;
+                }
+                logRefusal('offline run failed', error);
+                sendError(res, 500, 'offline_run_failed', 'the offline run failed (details in the console server log)');
+            }
+            return;
+        }
+        // GET /report — read-only (historical studies stay readable)
+        if (rest === '/report' && method === 'GET') {
+            const payload = studyReportPayload(labModules, studyDir);
+            if (!payload) {
+                sendError(res, 404, 'report_not_generated', 'no Report V2 yet — run the offline execution first, then generate the report (the console never auto-reruns or rewrites history)');
+                return;
+            }
+            sendSuccess(res, { ...payload, readOnly: access.readOnly });
+            return;
+        }
+        // POST /report — generate (idempotent; refuses to overwrite a READY report)
+        if (rest === '/report' && method === 'POST') {
+            if (access.readOnly) {
+                sendError(res, 403, 'study_read_only', `this study cannot be written from the console: ${access.reason}`);
+                return;
+            }
+            try {
+                const result = reportMaterialize(labModules, studyDir, new Date().toISOString(), context, () => {
+                    const check = verifyConsoleOwnership(roots.writable, studyDir);
+                    return check.ok ? { ok: true } : { ok: false, reason: check.reason };
+                });
+                sendSuccess(res, { studyId: access.studyId, status: result.status, written: result.written });
+            }
+            catch (error) {
+                logRefusal('report write refused', error);
+                sendError(res, 409, 'report_write_refused', 'the report was refused and no report file was written (details in the console server log)');
+            }
+            return;
+        }
+        sendNotFound(res, `Route /api/v1/examiner/studies/:studyId${rest} not found`);
+        return;
+    }
+    sendNotFound(res, `Route /api/v1/examiner${subPath} not found`);
+}

package/console/dist/ui/App.js

@@ -19,6 +19,7 @@ import { CorePrinciplesPage } from "./pages/principles/CorePrinciplesPage.js";
 import { PrincipleDetailPage } from "./pages/principles/PrincipleDetailPage.js";
 import { ActivationPage } from "./pages/activation/ActivationPage.js";
 import { DebtPage } from "./pages/debt/DebtPage.js";
+import { ExaminerPage } from "./pages/examiner/ExaminerPage.js";
 import { ControlCenterPage } from "./pages/control-center/ControlCenterPage.js";
 import { SettingsPage } from "./pages/settings/SettingsPage.js";
 import { UpdatePage } from "./pages/settings/UpdatePage.js";
@@ -28,8 +29,10 @@ import { IntentPage } from "./pages/intent/IntentPage.js";
 import { DesignSystemPage } from "./pages/design-system/DesignSystemPage.js";
 import { WelcomePage } from "./pages/welcome/WelcomePage.js";
 import { getOnboardingState } from "./utils/onboarding-state.js";
-// Vite replaces import.meta.env.DEV with a boolean literal at build time.
-// The cast avoids TS2339 without needing a generated .d.ts file.
+// Vite replaces import.meta.env.DEV with a boolean literal at build time, so a
+// production bundle resolves this to false and dead-code elimination drops the
+// DEV-only routes from the shipped UI. `utils/runtime-mode.ts` exports the same
+// value for components rendered outside this module; both read the same define.
 const IS_DEV = import.meta.env.DEV;
 /**
  * SPEC-PD-UIUX-001 R4: the skip control must NOT touch the URL hash — the app
@@ -162,7 +165,7 @@ function AuthRoutes() {
     }, []);
     return (_jsxs(Routes, { children: [_jsx(Route, { path: "/splash", element: _jsx(SplashScreen, { onComplete: () => {
                         setShowSplash(false);
-                    } }) }), _jsx(Route, { path: "/login", element: _jsx(LoginForm, { onAuthSuccess: handleAuthSuccess }) }), _jsx(Route, { path: "/*", element: authed === null ? (_jsx("div", { className: "min-h-screen bg-paper flex items-center justify-center", children: _jsxs("div", { className: "flex flex-col items-center gap-4", children: [_jsx("div", { className: "w-8 h-8 border-2 border-gov border-t-transparent rounded-full animate-spin" }), _jsx("span", { className: "text-[12px] font-mono tracking-wider text-ink-3 uppercase", children: "Verifying Session..." })] }) })) : authed ? (_jsx(NotificationProvider, { children: _jsx(AuthenticatedShell, { featureFlags: featureFlags ?? undefined, children: _jsx(ErrorBoundary, { children: _jsxs(Routes, { children: [_jsx(Route, { path: "/", element: _jsx(Navigate, { to: "/focus", replace: true }) }), _jsx(Route, { path: "/welcome", element: _jsx(WelcomePage, { workspaceId: currentWorkspaceId }) }), _jsx(Route, { path: "/focus", element: _jsx(FocusPage, { featureFlags: featureFlags ?? undefined }) }), _jsx(Route, { path: "/pain", element: _jsx(PainPage, {}) }), _jsx(Route, { path: "/principles", element: _jsx(PrinciplesPage, {}) }), _jsx(Route, { path: "/principles/core", element: _jsx(CorePrinciplesPage, {}) }), _jsx(Route, { path: "/principles/:id", element: _jsx(PrincipleDetailPage, {}) }), _jsx(Route, { path: "/activation", element: _jsx(ActivationPage, {}) }), _jsx(Route, { path: "/debt", element: _jsx(DebtPage, {}) }), _jsx(Route, { path: "/control-center", element: _jsx(ControlCenterPage, {}) }), _jsx(Route, { path: "/settings", element: _jsx(SettingsPage, {}) }), _jsx(Route, { path: "/update", element: _jsx(UpdatePage, {}) }), _jsx(Route, { path: "/report-problem", element: _jsx(ReportProblemPage, {}) }), _jsx(Route, { path: "/failed-tasks", element: _jsx(FailedTasksPage, {}) }), _jsx(Route, { path: "/intent", element: _jsx(IntentPage, {}) }), IS_DEV && (_jsx(Route, { path: "/design-system", element: _jsx(DesignSystemPage, {}) })), !IS_DEV && (_jsx(Route, { path: "/design-system", element: _jsx(Navigate, { to: "/focus", replace: true }) }))] }) }) }) })) : (_jsx(Navigate, { to: "/login", replace: true })) })] }));
+                    } }) }), _jsx(Route, { path: "/login", element: _jsx(LoginForm, { onAuthSuccess: handleAuthSuccess }) }), _jsx(Route, { path: "/*", element: authed === null ? (_jsx("div", { className: "min-h-screen bg-paper flex items-center justify-center", children: _jsxs("div", { className: "flex flex-col items-center gap-4", children: [_jsx("div", { className: "w-8 h-8 border-2 border-gov border-t-transparent rounded-full animate-spin" }), _jsx("span", { className: "text-[12px] font-mono tracking-wider text-ink-3 uppercase", children: "Verifying Session..." })] }) })) : authed ? (_jsx(NotificationProvider, { children: _jsx(AuthenticatedShell, { featureFlags: featureFlags ?? undefined, children: _jsx(ErrorBoundary, { children: _jsxs(Routes, { children: [_jsx(Route, { path: "/", element: _jsx(Navigate, { to: "/focus", replace: true }) }), _jsx(Route, { path: "/welcome", element: _jsx(WelcomePage, { workspaceId: currentWorkspaceId }) }), _jsx(Route, { path: "/focus", element: _jsx(FocusPage, { featureFlags: featureFlags ?? undefined }) }), _jsx(Route, { path: "/pain", element: _jsx(PainPage, {}) }), _jsx(Route, { path: "/principles", element: _jsx(PrinciplesPage, {}) }), _jsx(Route, { path: "/principles/core", element: _jsx(CorePrinciplesPage, {}) }), _jsx(Route, { path: "/principles/:id", element: _jsx(PrincipleDetailPage, {}) }), _jsx(Route, { path: "/activation", element: _jsx(ActivationPage, {}) }), _jsx(Route, { path: "/debt", element: _jsx(DebtPage, {}) }), IS_DEV ? (_jsx(Route, { path: "/examiner", element: _jsx(ExaminerPage, {}) })) : (_jsx(Route, { path: "/examiner", element: _jsx(Navigate, { to: "/focus", replace: true }) })), _jsx(Route, { path: "/control-center", element: _jsx(ControlCenterPage, {}) }), _jsx(Route, { path: "/settings", element: _jsx(SettingsPage, {}) }), _jsx(Route, { path: "/update", element: _jsx(UpdatePage, {}) }), _jsx(Route, { path: "/report-problem", element: _jsx(ReportProblemPage, {}) }), _jsx(Route, { path: "/failed-tasks", element: _jsx(FailedTasksPage, {}) }), _jsx(Route, { path: "/intent", element: _jsx(IntentPage, {}) }), IS_DEV && (_jsx(Route, { path: "/design-system", element: _jsx(DesignSystemPage, {}) })), !IS_DEV && (_jsx(Route, { path: "/design-system", element: _jsx(Navigate, { to: "/focus", replace: true }) }))] }) }) }) })) : (_jsx(Navigate, { to: "/login", replace: true })) })] }));
 }
 export function App() {
     return (_jsx(ThemeProvider, { children: _jsxs(I18nextProvider, { i18n: i18n, children: [_jsx(HashRouter, { children: _jsx(AuthRoutes, {}) }), _jsx(Toaster, {})] }) }));

package/console/dist/ui/api.d.ts

@@ -468,3 +468,141 @@ export interface PrincipleDetailRule {
 export interface PrincipleDetailData {
     principle: PrincipleDetail;
 }
+export interface ExaminerOverviewData {
+    spec: string;
+    executionScope: string;
+    gates: Record<string, string>;
+    hostInjectionCapability: Record<string, string>;
+    fullConclusionMinimumLevel: string;
+    studiesRoot: string;
+    studies: string[];
+}
+export interface ExaminerPrincipleItem {
+    id: string;
+    version: string;
+    text: string;
+    status: string;
+}
+export interface ExaminerStudyStatusData {
+    studyId: string;
+    experimentMode: string;
+    interventionType: string;
+    targetPrincipleId: string | null;
+    plannedPairs: number | null;
+    runStarted: boolean;
+    runFinished: boolean;
+    unitStates: Record<string, number>;
+    reportStatus: string | null;
+}
+export interface ExaminerPreflightCheck {
+    id: string;
+    severity: string;
+    ok: boolean;
+    detail: string;
+}
+export interface ExaminerPreflightData {
+    studyId: string;
+    ok: boolean;
+    status: string;
+    blockers: ExaminerPreflightCheck[];
+    warnings: ExaminerPreflightCheck[];
+    checks: ExaminerPreflightCheck[];
+}
+export interface ExaminerReportData {
+    studyId: string;
+    report: {
+        status: string;
+        scope?: {
+            executionMode?: string;
+            controlArm?: string;
+            treatmentArm?: string;
+        };
+        examiner?: {
+            experimentMode: string;
+            interventionType: string;
+            targetPrincipleId: string | null;
+            primaryEndpoint: {
+                id: string;
+            } | null;
+            applicability: {
+                applicablePairs: number;
+                notApplicablePairs: number;
+            };
+            itt: {
+                plannedApplicablePairs: number;
+                determinedPairs: number;
+                unknownPairs: number;
+                cells: Record<string, number>;
+                pointEstimate: {
+                    status: string;
+                    value?: number;
+                    numerator?: number;
+                    denominator?: number;
+                };
+                lowerBound: {
+                    status: string;
+                    value?: number;
+                };
+                upperBound: {
+                    status: string;
+                    value?: number;
+                };
+            };
+            treatmentFidelity: {
+                plannedTreatmentUnits: number;
+                contextPresent: number;
+                runtimeLoaded: number;
+                actualInjectionRate: {
+                    status: string;
+                    value?: number;
+                };
+                controlContamination: {
+                    units: number;
+                    ofControlChains: number;
+                };
+                capacityEvictions: {
+                    units: number;
+                };
+            };
+            randomization: {
+                strategy: string;
+                verified: boolean;
+            } | null;
+        } | null;
+        dimensions?: Record<string, unknown>;
+        limitations?: string[];
+    };
+    verification: {
+        checks: {
+            ok: boolean;
+        }[];
+    };
+    note: string;
+}
+export declare function fetchExaminerOverview(): Promise<ApiResponse<ExaminerOverviewData>>;
+export declare function fetchExaminerPrinciples(): Promise<ApiResponse<{
+    principles: ExaminerPrincipleItem[];
+}>>;
+export declare function createExaminerStudy(input: {
+    targetPrincipleId: string;
+    experimentMode: string;
+    repetitionsPerCase: number;
+}): Promise<ApiResponse<{
+    studyId: string;
+    experimentMode: string;
+    plannedPairs: number | null;
+    note: string;
+}>>;
+export declare function fetchExaminerStudyStatus(studyId: string): Promise<ApiResponse<ExaminerStudyStatusData>>;
+export declare function runExaminerPreflight(studyId: string): Promise<ApiResponse<ExaminerPreflightData>>;
+export declare function runExaminerStudy(studyId: string): Promise<ApiResponse<{
+    units: {
+        unit: unknown;
+        state: string;
+    }[];
+}>>;
+export declare function generateExaminerReport(studyId: string): Promise<ApiResponse<{
+    status: string;
+    written: boolean;
+}>>;
+export declare function fetchExaminerReport(studyId: string): Promise<ApiResponse<ExaminerReportData>>;

package/console/dist/ui/api.js

@@ -1027,3 +1027,59 @@ export { request,
 getToken, setToken, clearToken, checkAuth, approveApproval, rejectApproval, editApproval, fetchPrinciples, fetchCorePrinciples, fetchPrincipleDetail, fetchPrincipleGovernance, fetchOwnerDecisionView, fetchOwnerDecisionInbox, fetchOwnerDecisionLibrary, fetchPrincipleTrajectory, fetchPrincipleReceipts, fetchReceiptCounts, fetchEvidenceAudit, archivePrinciple, unarchivePrinciple, createFeedbackReport, listFeedbackReports, getFeedbackReport, deleteFeedbackReport, 
 // Feedback submit ladder (Slice 3, spec §8)
 fetchFeedbackChannels, submitFeedbackReport, markFeedbackReportSent, fetchConfigSummary, fetchConfigCatalog, updateAgentBinding, updateDefaultRuntime, createRuntimeProfile, updateRuntimeProfile, deleteRuntimeProfile, fetchAgentReadiness, patchFeatureFlag, fetchOutputLanguage, updateOutputLanguage, fetchWorkspaces, addWorkspace, removeWorkspace, syncWorkspace, fetchGovernanceQueue, fetchGovernanceExperience, recoverFailedTask, fetchFailedTaskDetail, fetchOwnerDecisions, resolveOwnerDecision, fetchApprovalsGrouped, fetchAllActivations, disableActivation, proposePromptRevision, fetchRuleCodeOwnerReview, ruleCodeDecision, pauseAllRuleCode, releaseRuleCodePause, fetchLifecycleMetrics, fetchUpdateStatus, fetchUpdateHistory, applyFullUpdate, fetchUpdateRecovery, fetchUpdateTransaction, fetchEvidenceChain, fetchIntentSummary, fetchIntentContent, createIntentTemplate, saveIntentContent, fetchIntentVersions, recordIntentDecision, listIntentDecisionsByPainId, listIntentDecisionsByTaskId, fetchIntentDecisionSummary, dispatchFollowUp, fetchDesignGateSessions, fetchDesignGateDeclaration, createDesignGateDeclaration, updateDesignGateDecision, revokeDesignGateDeclaration, };
+export async function fetchExaminerOverview() {
+    return request('/api/v1/examiner/overview', undefined, (v) => {
+        if (v !== null && typeof v === 'object' && Object.hasOwn(v, 'studies'))
+            return v;
+        return null;
+    });
+}
+export async function fetchExaminerPrinciples() {
+    return request('/api/v1/examiner/principles', undefined, (v) => {
+        if (v && typeof v === 'object' && Array.isArray(v.principles))
+            return v;
+        return null;
+    });
+}
+export async function createExaminerStudy(input) {
+    return request('/api/v1/examiner/studies', { method: 'POST', body: JSON.stringify(input) }, (v) => {
+        if (v && typeof v.studyId === 'string')
+            return v;
+        return null;
+    });
+}
+export async function fetchExaminerStudyStatus(studyId) {
+    return request(`/api/v1/examiner/studies/${encodeURIComponent(studyId)}`, undefined, (v) => {
+        if (v && typeof v.studyId === 'string')
+            return v;
+        return null;
+    });
+}
+export async function runExaminerPreflight(studyId) {
+    return request(`/api/v1/examiner/studies/${encodeURIComponent(studyId)}/preflight`, { method: 'POST' }, (v) => {
+        if (v && typeof v.ok === 'boolean')
+            return v;
+        return null;
+    });
+}
+export async function runExaminerStudy(studyId) {
+    return request(`/api/v1/examiner/studies/${encodeURIComponent(studyId)}/run`, { method: 'POST', body: JSON.stringify({ mode: 'offline-stub' }) }, (v) => {
+        if (v && Array.isArray(v.units))
+            return v;
+        return null;
+    });
+}
+export async function generateExaminerReport(studyId) {
+    return request(`/api/v1/examiner/studies/${encodeURIComponent(studyId)}/report`, { method: 'POST' }, (v) => {
+        if (v && typeof v.status === 'string')
+            return v;
+        return null;
+    });
+}
+export async function fetchExaminerReport(studyId) {
+    return request(`/api/v1/examiner/studies/${encodeURIComponent(studyId)}/report`, undefined, (v) => {
+        if (v && v.report)
+            return v;
+        return null;
+    });
+}

package/console/dist/ui/components/layout/app-sidebar.d.ts

@@ -1,4 +1,15 @@
 import * as React from "react";
+/**
+ * P2-1: the Examiner is a DEV-only research surface. The navigation entry is
+ * derived from the build-time mode, so a production bundle never advertises a
+ * capability the server refuses.
+ */
+export declare function visibleMainNavItems(isDev: boolean): {
+    id: string;
+    labelKey: string;
+    href: string;
+    icon: React.ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+}[];
 export declare function AppSidebar({ featureFlags }: {
     featureFlags?: Record<string, {
         enabled: boolean;

package/console/dist/ui/components/layout/app-sidebar.js

@@ -1,12 +1,13 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Link, useLocation, useNavigate } from "react-router-dom";
-import { Sun, Moon, Focus, AlertTriangle, AlertCircle, BookOpen, Zap, Archive, Compass, Settings, MessageSquare, RefreshCw, LogOut, Languages, Menu, } from "lucide-react";
+import { Sun, Moon, Focus, AlertTriangle, AlertCircle, BookOpen, Zap, Archive, Compass, FlaskConical, Settings, MessageSquare, RefreshCw, LogOut, Languages, Menu, } from "lucide-react";
 import { useTheme } from "../theme-provider.js";
 import { useTranslation } from "react-i18next";
 import { useNotifications } from "../notifications/useNotifications.js";
 import { clearToken } from "../../api.js";
 import { cn } from "../../../lib/utils.js";
+import { IS_DEV } from "../../utils/runtime-mode.js";
 import { Sheet, SheetContent, SheetDescription, SheetTitle, SheetTrigger } from "../ui/sheet.js";
 function ThresholdMark({ className }) {
     return (_jsxs("svg", { viewBox: "0 0 28 28", className: className, fill: "none", stroke: "currentColor", strokeWidth: "1.5", "aria-hidden": "true", children: [_jsx("path", { d: "M6 4V24M22 4V24M2 14H26", strokeLinecap: "square" }), _jsx("circle", { cx: "14", cy: "14", r: "2.5", fill: "currentColor", stroke: "none" })] }));
@@ -17,8 +18,17 @@ const mainNavItems = [
     { id: "principles", labelKey: "components.sidebar.principles", href: "/principles", icon: BookOpen },
     { id: "activation", labelKey: "components.sidebar.activation", href: "/activation", icon: Zap },
     { id: "debt", labelKey: "components.sidebar.debt", href: "/debt", icon: Archive },
+    { id: "examiner", labelKey: "components.sidebar.examiner", href: "/examiner", icon: FlaskConical },
     { id: "intent", labelKey: "components.sidebar.intent", href: "/intent", icon: Compass },
 ];
+/**
+ * P2-1: the Examiner is a DEV-only research surface. The navigation entry is
+ * derived from the build-time mode, so a production bundle never advertises a
+ * capability the server refuses.
+ */
+export function visibleMainNavItems(isDev) {
+    return isDev ? mainNavItems : mainNavItems.filter((item) => item.id !== "examiner");
+}
 const toolNavItems = [
     { id: "control-center", labelKey: "components.sidebar.controlCenter", href: "/control-center", icon: Settings },
     { id: "report-problem", labelKey: "components.sidebar.reportProblem", href: "/report-problem", icon: MessageSquare },
@@ -51,7 +61,7 @@ function SidebarContent({ featureFlags, onNavigate, touchTargets, }) {
         i18n.changeLanguage(nextLang);
         localStorage.setItem("pd-language", nextLang);
     };
-    return (_jsxs(_Fragment, { children: [_jsxs("nav", { className: "flex-1 py-2 overflow-y-auto", "aria-label": t("components.sidebar.navigation", { defaultValue: "主导航" }), children: [_jsx("div", { className: "px-2", children: mainNavItems.map((item) => {
+    return (_jsxs(_Fragment, { children: [_jsxs("nav", { className: "flex-1 py-2 overflow-y-auto", "aria-label": t("components.sidebar.navigation", { defaultValue: "主导航" }), children: [_jsx("div", { className: "px-2", children: visibleMainNavItems(IS_DEV).map((item) => {
                             const Icon = item.icon;
                             const active = isActive(item.href);
                             return (_jsxs(Link, { to: item.href, "data-testid": `nav-${item.id}`, "aria-current": active ? "page" : undefined, onClick: onNavigate, className: cn("flex items-center gap-3 px-3 rounded-[var(--radius-sm)] text-[13px] transition-all duration-150", touchTargets ? "min-h-[44px] py-2" : "py-2", active