create-principles-disciple 1.145.42 → 1.146.0

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

@@ -0,0 +1,628 @@
+/**
+ * SPEC-PD-EXAMINER-001 v0.9 §8 — Examiner Console executor (offline-stub).
+ *
+ * Receives an ALREADY-RESOLVED study directory (selected by exact membership
+ * in the server's own enumeration — see examiner.ts) and performs the offline
+ * preflight / execution / report actions through the principle-learning-lab
+ * modules. This module never touches request objects and never transports a
+ * caller-supplied execution mode: the only reachable mode is offline-stub.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+export const CONSOLE_OWNERSHIP_MARKER = '.console-study-owner.json';
+const OWNERSHIP_SCHEMA = 'examiner-console-ownership.v1';
+const HANDLE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+/** Stable, Owner-facing boundary reasons — never paths or exception text. */
+export const STUDY_PATH_PROBLEM = {
+    unresolved: 'the study path cannot be resolved to a canonical location (fail-closed)',
+    notInside: 'the study directory resolves outside the writable console root',
+    historical: 'the study directory resolves inside the historical research area',
+    rootNotIsolated: 'the writable study root must be separate from the historical examiner-studies area',
+};
+/**
+ * P1-1 canonical resolution. An existing path goes through `realpath`, which
+ * follows symlinks AND Windows junctions. A path that does not exist yet is
+ * resolved through its deepest EXISTING ancestor (so a symlinked parent can
+ * never hide an escape) and the remaining lexically-safe segments are
+ * appended. Any resolution failure is fail-closed (null).
+ */
+export function canonicalPathSync(target) {
+    let current = path.resolve(target);
+    const remainder = [];
+    for (;;) {
+        let exists = false;
+        try {
+            fs.lstatSync(current);
+            exists = true;
+        }
+        catch (error) {
+            const { code } = error;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                return null;
+        }
+        if (exists) {
+            try {
+                const real = fs.realpathSync.native(current);
+                return remainder.length > 0 ? path.join(real, ...remainder.reverse()) : real;
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        remainder.push(path.basename(current));
+        current = parent;
+    }
+}
+const foldPath = (value) => (process.platform === 'win32' ? value.toLowerCase() : value);
+export function isSamePath(a, b) {
+    return foldPath(path.resolve(a)) === foldPath(path.resolve(b));
+}
+/** Strict containment: equal paths are NOT inside each other. */
+export function isPathInside(root, candidate) {
+    const r = foldPath(path.resolve(root));
+    const c = foldPath(path.resolve(candidate));
+    const prefix = r.endsWith(path.sep) ? r : `${r}${path.sep}`;
+    return c !== r && c.startsWith(prefix);
+}
+/**
+ * Resolve the two roots once. Console-created studies are WORKSPACE DATA, not
+ * repository content: they default to `<dataRoot>/studies`, where the caller
+ * passes `<workspace>/.pd/examiner`. `PD_EXAMINER_STUDIES_ROOT` overrides the
+ * WRITABLE root only (tests / operators). The historical research assets ship
+ * with the lab payload (absent in an installation → an empty read-only list).
+ */
+export function resolveStudyRoots(labRoot, dataRoot) {
+    const override = process.env.PD_EXAMINER_STUDIES_ROOT;
+    const writable = override ? path.resolve(override) : path.join(path.resolve(dataRoot), 'studies');
+    const historical = path.join(path.resolve(labRoot), 'examiner-studies');
+    // Canonical forms when resolvable; the unresolved form is kept so the
+    // boundary gates below can fail closed with a stable reason.
+    return {
+        writable: canonicalPathSync(writable) ?? writable,
+        historical: canonicalPathSync(historical) ?? historical,
+    };
+}
+export function isJsonObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Read an optional string field off an untrusted object (never throws). */
+function stringField(value, key) {
+    if (!isJsonObject(value))
+        return null;
+    const field = value[key];
+    return typeof field === 'string' ? field : null;
+}
+function isPrincipleFact(value) {
+    return isJsonObject(value) && typeof value.id === 'string' && typeof value.text === 'string';
+}
+function asJsonObject(value, context) {
+    if (!isJsonObject(value))
+        throw new Error(`${context}: expected a JSON object`);
+    return value;
+}
+function readJsonObjectFile(file) {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return asJsonObject(parsed, file);
+}
+/* eslint-disable @typescript-eslint/max-params -- lab delegation calls carry (modules, labRoot/studiesRoot, dir, data) by design */
+/** Boundary-checked study file reader (fails closed on missing/malformed). */
+export function readStudyJson(studyDir, rel) {
+    const root = path.resolve(studyDir);
+    const file = path.resolve(root, rel);
+    if (!isPathInside(root, file))
+        throw new Error('invalid study file path');
+    return readJsonObjectFile(file);
+}
+/**
+ * List the study directory names the server itself enumerated under the
+ * studies root (sorted). The route layer treats this list as the allowlist.
+ */
+export function listStudyNames(studiesRoot) {
+    if (!fs.existsSync(studiesRoot))
+        return [];
+    return fs.readdirSync(studiesRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+}
+/**
+ * P1-1: verify that a directory under the WRITABLE root was really created by
+ * this server. Name membership is not enough and file existence is not enough:
+ * the directory must
+ *   1. resolve (realpath) strictly INSIDE the writable root,
+ *   2. be a real directory (not a symlink/junction),
+ *   3. carry the server ownership marker whose studyId matches BOTH the
+ *      directory name and the frozen examiner manifest.
+ * A historical research asset can therefore never be written, even if a file
+ * named like the marker is dropped beside it.
+ */
+export function verifyConsoleOwnership(writableRoot, studyDir) {
+    const rootReal = canonicalPathSync(writableRoot);
+    const dirReal = canonicalPathSync(studyDir);
+    if (!rootReal || !dirReal)
+        return { ok: false, reason: STUDY_PATH_PROBLEM.unresolved };
+    if (!isPathInside(rootReal, dirReal))
+        return { ok: false, reason: STUDY_PATH_PROBLEM.notInside };
+    let stat;
+    try {
+        stat = fs.lstatSync(studyDir);
+    }
+    catch {
+        return { ok: false, reason: 'study directory is unreadable' };
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        return { ok: false, reason: 'study directory is not a real directory' };
+    const markerPath = path.join(studyDir, CONSOLE_OWNERSHIP_MARKER);
+    // The marker is the trust anchor: a symlink planted here would redirect the
+    // read outside the study, so it must be a regular file.
+    let markerStat;
+    try {
+        markerStat = fs.lstatSync(markerPath);
+    }
+    catch {
+        return { ok: false, reason: 'console ownership marker missing — the study was not created by this server' };
+    }
+    if (markerStat.isSymbolicLink() || !markerStat.isFile()) {
+        return { ok: false, reason: 'console ownership marker is not a regular file' };
+    }
+    let marker;
+    let manifest;
+    try {
+        marker = readJsonObjectFile(markerPath);
+        manifest = readStudyJson(studyDir, 'examiner-manifest.json');
+    }
+    catch (error) {
+        // The reason travels into HTTP payloads, so it must not carry raw
+        // exception text (paths/internals); the detail stays in the server log.
+        console.error('[pd-console] examiner ownership check failed:', error);
+        return { ok: false, reason: 'ownership marker or manifest is unreadable (details in the console server log)' };
+    }
+    const name = path.basename(studyDir);
+    if (marker.schema !== OWNERSHIP_SCHEMA || marker.origin !== 'pd-console') {
+        return { ok: false, reason: 'console ownership marker is not a valid pd-console record' };
+    }
+    if (marker.studyId !== name || manifest.studyId !== name) {
+        return { ok: false, reason: 'ownership marker / manifest studyId does not match the directory identity' };
+    }
+    // The marker names the root it was issued for; compare CANONICAL forms so a
+    // symlink/junction alias of the same root cannot pass (or be forged).
+    const markerRoot = typeof marker.writableRoot === 'string' ? canonicalPathSync(marker.writableRoot) : null;
+    if (!markerRoot || !isSamePath(markerRoot, rootReal)) {
+        return { ok: false, reason: 'ownership marker was issued for a different writable root' };
+    }
+    return { ok: true, reason: 'server-owned console study' };
+}
+/**
+ * Resolve a requested study by EXACT membership in the server's own
+ * enumeration of BOTH roots. The returned path is always built from an
+ * enumerated entry name; callers only select, never construct path segments.
+ * A writable entry that resolves outside the writable root (or into the
+ * historical area) is returned READ-ONLY with a stable boundary reason.
+ */
+export function resolveStudyAccess(roots, requested) {
+    if (!HANDLE_PATTERN.test(requested))
+        return null;
+    const writableRoot = canonicalPathSync(roots.writable) ?? path.resolve(roots.writable);
+    const writableName = listStudyNames(writableRoot).find((entry) => entry === requested);
+    if (writableName) {
+        const dir = path.join(writableRoot, writableName);
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define -- hoisted function declaration
+        const boundary = writableStudyDirProblem(roots, dir);
+        if (boundary)
+            return { dir, studyId: writableName, readOnly: true, reason: boundary };
+        const ownership = verifyConsoleOwnership(roots.writable, dir);
+        return { dir, studyId: writableName, readOnly: !ownership.ok, reason: ownership.reason };
+    }
+    const historicalRoot = canonicalPathSync(roots.historical) ?? path.resolve(roots.historical);
+    const historicalName = listStudyNames(historicalRoot).find((entry) => entry === requested);
+    if (historicalName) {
+        const dir = path.join(historicalRoot, historicalName);
+        const dirReal = canonicalPathSync(dir);
+        const historicalReal = canonicalPathSync(roots.historical);
+        // An entry that resolves outside the historical root is not this study.
+        if (!dirReal || !historicalReal || !isPathInside(historicalReal, dirReal))
+            return null;
+        return {
+            dir: dirReal,
+            studyId: historicalName,
+            readOnly: true,
+            reason: 'historical research asset — readable, never writable from the console',
+        };
+    }
+    return null;
+}
+/**
+ * The writable root must never be, contain, or be contained by the historical
+ * research area. Both the LEXICAL pair and the CANONICAL pair are checked:
+ * lexical catches obvious aliases, canonical catches symlink/junction aliases
+ * and their not-yet-existing descendants. Unresolvable roots fail closed.
+ */
+export function writableRootProblem(roots) {
+    const writableLexical = path.resolve(roots.writable);
+    const historicalLexical = path.resolve(roots.historical);
+    const writable = canonicalPathSync(writableLexical);
+    const historical = canonicalPathSync(historicalLexical);
+    if (!writable || !historical)
+        return STUDY_PATH_PROBLEM.unresolved;
+    const pairs = [[writableLexical, historicalLexical], [writable, historical]];
+    for (const [w, h] of pairs) {
+        if (isSamePath(w, h) || isPathInside(h, w) || isPathInside(w, h))
+            return STUDY_PATH_PROBLEM.rootNotIsolated;
+    }
+    return null;
+}
+/**
+ * Unified write-boundary check for ONE study directory: inside the canonical
+ * writable root AND outside the canonical historical area. Used by every
+ * write path (creation, ownership marker, run, report) immediately before the
+ * mutation — a check done only at startup is not evidence about now.
+ */
+export function writableStudyDirProblem(roots, studyDir) {
+    const rootProblem = writableRootProblem(roots);
+    if (rootProblem)
+        return rootProblem;
+    const writable = canonicalPathSync(roots.writable);
+    const historical = canonicalPathSync(roots.historical);
+    const dir = canonicalPathSync(studyDir);
+    if (!writable || !historical || !dir)
+        return STUDY_PATH_PROBLEM.unresolved;
+    if (isSamePath(historical, dir) || isPathInside(historical, dir))
+        return STUDY_PATH_PROBLEM.historical;
+    if (!isPathInside(writable, dir))
+        return STUDY_PATH_PROBLEM.notInside;
+    return null;
+}
+/** Study status projection (manifest + ledger settlement counts + report status). */
+export function studyStatusPayload(studyDir) {
+    const manifest = readStudyJson(studyDir, 'examiner-manifest.json');
+    const eventsFile = path.join(studyDir, 'events.jsonl');
+    const events = fs.existsSync(eventsFile)
+        ? fs.readFileSync(eventsFile, 'utf8').trim().split('\n').filter(Boolean).map((line) => asJsonObject(JSON.parse(line), eventsFile))
+        : [];
+    const counts = {};
+    for (const event of events) {
+        if (typeof event.type !== 'string' || !event.type.startsWith('UNIT_FINISHED'))
+            continue;
+        const result = String(event.result ?? 'UNKNOWN');
+        counts[result] = (counts[result] ?? 0) + 1;
+    }
+    const reportExists = fs.existsSync(path.join(studyDir, 'behavior-report-v2.json'));
+    const report = reportExists ? readStudyJson(studyDir, 'behavior-report-v2.json') : null;
+    return {
+        studyId: path.basename(studyDir),
+        experimentMode: manifest.experimentMode,
+        interventionType: manifest.interventionType,
+        targetPrincipleId: stringField(manifest.targetPrinciple, 'id'),
+        plannedPairs: manifest.plannedPairs,
+        runStarted: events.some((event) => event.type === 'RUN_STARTED'),
+        runFinished: events.some((event) => event.type === 'RUN_FINISHED'),
+        unitStates: counts,
+        reportStatus: report ? (report.status) : null,
+    };
+}
+/** Read-only Report V2 payload + replay verification. */
+export function studyReportPayload(modules, studyDir) {
+    if (!fs.existsSync(path.join(studyDir, 'behavior-report-v2.json')))
+        return null;
+    return {
+        studyId: path.basename(studyDir),
+        report: readStudyJson(studyDir, 'behavior-report-v2.json'),
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define -- hoisted function declaration
+        verification: studyReportVerify(modules, studyDir),
+        note: 'historical reports are read-only — REPORT_READY artifacts can never be overwritten',
+    };
+}
+/** The didactic offline actor pair — SAME scripted contrast as the committed acceptance artifacts. */
+function didacticActions(armId) {
+    return armId === 'A'
+        ? [
+            { type: 'observe', args: { obsId: 'OBS-WRONG' } },
+            { type: 'report', args: { claims: [{ factId: 'F1', verdict: 'verified_true', evidenceRefs: ['OBS-WRONG'] }] } },
+        ]
+        : [
+            { type: 'observe', args: { obsId: 'OBS-PRIMARY' } },
+            { type: 'report', args: { claims: [{ factId: 'F1', verdict: 'verified_true', evidenceRefs: ['OBS-PRIMARY'] }] } },
+        ];
+}
+export class ExaminerPreflightBlockedError extends Error {
+    blockers;
+    constructor(blockers) {
+        super(`preflight blocked (${blockers.length} blocker(s)) — no run started, no unit reserved, no actor created`);
+        this.name = 'ExaminerPreflightBlockedError';
+        this.blockers = blockers;
+    }
+}
+export class ExaminerWriteRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ExaminerWriteRefusedError';
+    }
+}
+function studyDirStatus(studyDir, context) {
+    if (!context)
+        return { insideFrozenArea: false, collidesWithHistorical: false };
+    const dirReal = canonicalPathSync(studyDir);
+    // Unresolvable is not "probably fine": report it as colliding so the
+    // fail-closed preflight refuses instead of running.
+    if (!dirReal)
+        return { insideFrozenArea: true, collidesWithHistorical: true };
+    const insideRoot = (root) => {
+        const real = canonicalPathSync(root);
+        if (!real)
+            return true;
+        return isSamePath(real, dirReal) || isPathInside(real, dirReal);
+    };
+    return {
+        insideFrozenArea: insideRoot(path.join(context.labRoot, 'challenge-studies')),
+        collidesWithHistorical: insideRoot(context.roots.historical),
+    };
+}
+export function preflightCheck(modules, studyDir, context) {
+    const manifest = readStudyJson(studyDir, 'examiner-manifest.json');
+    const hepsInput = readStudyJson(studyDir, 'heps-principles.json');
+    const armConfigs = readStudyJson(studyDir, 'examiner-arm-configs.json');
+    const rulecode = readStudyJson(studyDir, 'rulecode-baseline.json');
+    const pairAssignment = readStudyJson(studyDir, 'pair-assignment.json');
+    const arms = asJsonObject(armConfigs.arms, 'examiner-arm-configs.arms');
+    const armPayloadText = (side) => {
+        const entry = arms[side];
+        if (!isJsonObject(entry))
+            return '';
+        return typeof entry.payloadText === 'string' ? entry.payloadText : '';
+    };
+    const principles = Array.isArray(hepsInput.principles) ? hepsInput.principles.filter(isPrincipleFact) : [];
+    // P1-3/P1-4: the frozen files must agree with each other AND the immutable
+    // anchor. This verdict is a hard blocker; a study whose files were rewritten
+    // in a mutually consistent way can never pass the run gate.
+    const bindings = modules.study.verifyExaminerStudyBindings(studyDir);
+    return modules.study.runExaminerPreflight({
+        manifest,
+        heps: modules.study.buildHostEffectivePrincipleSet({ principles: hepsInput.principles, targetPrincipleId: hepsInput.targetPrincipleId, host: hepsInput.host }),
+        ruleCodePolicy: modules.study.buildRuleCodePolicy({
+            mode: manifest.experimentMode,
+            ruleCodes: rulecode.ruleCodes,
+            targetPrincipleId: hepsInput.targetPrincipleId,
+            principleRuleCodeIndependence: rulecode.principleRuleCodeIndependence,
+            targetRuleCodeCount: rulecode.targetRuleCodeCount ?? null,
+        }),
+        pairAssignment,
+        primaryEndpoint: modules.study.definePrimaryEndpoint({ id: stringField(manifest.primaryEndpoint, 'id') ?? 'target_unsupported_completion_assertion_rate' }),
+        armConfigs: { arms: { A: { delivery: { payloadText: armPayloadText('control') } }, B: { delivery: { payloadText: armPayloadText('treatment') } } } },
+        targetPrincipleText: principles.find((p) => p.id === hepsInput.targetPrincipleId)?.text,
+        isolation: { sessionPerArm: true, workspacePerArm: true },
+        goldStatus: 'SYNTHETIC_OFFLINE',
+        injectionCapability: { host: 'offline-stub', maxProvableLevel: 'RUNTIME_LOADED', minimumRequiredLevel: 'CONTEXT_PRESENT' },
+        authorization: { mode: 'offline-stub' },
+        studyDirStatus: studyDirStatus(studyDir, context),
+        bindings,
+    });
+}
+/**
+ * P1-4: POST /run can never reach the runner without passing the server gate.
+ * The readiness check below is evaluated first (a convenience projection), then
+ * the runner re-evaluates the same frozen facts UNDER the study write lock
+ * before RUN_STARTED — but a blocker here means the runner is not called at
+ * all, so no attempt is reserved and no actor is created.
+ */
+export async function offlineStudyPass(modules, studyDir, context) {
+    // The write boundary is re-evaluated here (not only at route start): a
+    // directory swapped for a symlink/junction after access resolution must not
+    // reach the runner.
+    if (context) {
+        const boundary = writableStudyDirProblem(context.roots, studyDir);
+        if (boundary)
+            throw new ExaminerPreflightBlockedError([{ id: 'study_path_boundary', reason: boundary }]);
+    }
+    const preflight = preflightCheck(modules, studyDir, context);
+    if (!preflight.ok)
+        throw new ExaminerPreflightBlockedError(preflight.blockers);
+    const manifest = readStudyJson(studyDir, 'examiner-manifest.json');
+    const pairAssignment = readStudyJson(studyDir, 'pair-assignment.json');
+    const suite = readStudyJson(studyDir, 'suite-manifest.json');
+    const repetitions = Array.from({ length: Number(manifest.repetitionsPerCase ?? 1) }, (_, i) => String(i + 1));
+    return modules.runner.runChallengeStudy({
+        studyDir,
+        plan: {
+            arms: ['A', 'B'],
+            cases: suite.cases.map((c) => c.caseId),
+            repetitions,
+            unitOrder: pairAssignment.unitOrder,
+        },
+        actorFactory: ({ armId }) => modules.actor.createScriptedStub({ actions: didacticActions(armId) }),
+        execution: { mode: 'offline-stub' },
+    });
+}
+export function reportMaterialize(modules, studyDir, now, context, canWrite) {
+    if (context) {
+        const boundary = writableStudyDirProblem(context.roots, studyDir);
+        if (boundary)
+            throw new ExaminerWriteRefusedError(boundary);
+    }
+    // The lab calls canWrite() immediately before writing; re-apply the boundary
+    // check there so a directory swapped AFTER this function returned still
+    // fails closed instead of writing into an alias.
+    const guardedCanWrite = () => {
+        if (context) {
+            const boundary = writableStudyDirProblem(context.roots, studyDir);
+            if (boundary)
+                return { ok: false, reason: boundary };
+        }
+        return canWrite();
+    };
+    return modules.report.writeBehaviorReportV2(studyDir, { now, canWrite: guardedCanWrite });
+}
+export function studyReportVerify(modules, studyDir) {
+    return modules.report.verifyBehaviorReportV2(studyDir);
+}
+export async function loadLabModules(labRoot) {
+    const url = (rel) => pathToFileURL(path.join(labRoot, rel)).href;
+    const study = (await import(url('lib/examiner-study.mjs')));
+    const runner = (await import(url('lib/challenge-runner.mjs')));
+    const report = (await import(url('lib/challenge-behavior-report.mjs')));
+    const actor = (await import(url('lib/challenge-actor.mjs')));
+    return { study, runner, report, actor };
+}
+/** Host injection-capability ceiling table (from examiner-injection-evidence.mjs). */
+export async function loadHostCapability(labRoot) {
+    const url = pathToFileURL(path.join(labRoot, 'lib', 'examiner-injection-evidence.mjs')).href;
+    const mod = (await import(url));
+    if (!mod || typeof mod.HOST_MAX_PROVABLE_LEVEL !== 'object')
+        throw new Error('examiner-injection-evidence.mjs exports missing');
+    return mod.HOST_MAX_PROVABLE_LEVEL;
+}
+/** Server-minted study handle + directory (crypto-random; never request-derived). */
+export function mintStudyHandle(roots) {
+    const problem = writableRootProblem(roots);
+    if (problem)
+        throw new ExaminerWriteRefusedError(problem);
+    fs.mkdirSync(roots.writable, { recursive: true });
+    // Re-resolve AFTER mkdir: the pre-mkdir check is not evidence about the
+    // directory that now exists (a parent could have become a link meanwhile).
+    const afterMkdir = writableRootProblem(roots);
+    if (afterMkdir)
+        throw new ExaminerWriteRefusedError(afterMkdir);
+    const writableReal = canonicalPathSync(roots.writable);
+    if (!writableReal)
+        throw new ExaminerWriteRefusedError(STUDY_PATH_PROBLEM.unresolved);
+    const studyId = `EXM-C-${randomUUID().toUpperCase()}`;
+    // A historical identity must never be reused for a new write target.
+    if (listStudyNames(roots.historical).includes(studyId))
+        return null;
+    const candidate = path.join(writableReal, studyId);
+    if (fs.existsSync(candidate))
+        return null;
+    return { studyId, studyDir: candidate };
+}
+function writeOwnershipMarker(studyId, studyDir, roots) {
+    // Write-time boundary re-check (creation may have taken a while).
+    const boundary = writableStudyDirProblem(roots, studyDir);
+    if (boundary)
+        throw new ExaminerWriteRefusedError(boundary);
+    const rootReal = canonicalPathSync(roots.writable);
+    if (!rootReal)
+        throw new ExaminerWriteRefusedError(STUDY_PATH_PROBLEM.unresolved);
+    const marker = {
+        schema: OWNERSHIP_SCHEMA,
+        origin: 'pd-console',
+        studyId,
+        writableRoot: rootReal,
+        createdAt: new Date().toISOString(),
+    };
+    // Exclusive create: never follow (or overwrite) a file/symlink that was
+    // planted inside the freshly minted directory.
+    const markerPath = path.join(studyDir, CONSOLE_OWNERSHIP_MARKER);
+    const fd = fs.openSync(markerPath, 'wx');
+    try {
+        fs.writeSync(fd, `${JSON.stringify(marker, null, 2)}\n`);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    const check = verifyConsoleOwnership(roots.writable, studyDir);
+    if (!check.ok)
+        throw new ExaminerWriteRefusedError(`console ownership marker was not accepted: ${check.reason}`);
+}
+/**
+ * Create one console-originated offline examiner study: mint the server-side
+ * identity, resolve the target from the SERVER-provided ledger list (the id
+ * is charset-validated by the caller and must match a ledger entry exactly),
+ * then materialize the study through the lab contract. Synthetic calibration
+ * cases with SYNTHETIC_OFFLINE gold provenance — offline contract validation,
+ * never real-host behavior.
+ */
+export async function materializeConsoleStudy(modules, labRoot, roots, selection) {
+    const target = selection.ledgerPrinciples[selection.targetIndex];
+    if (!target)
+        throw new Error('the target principle was not found in the workspace ledger');
+    const rootProblem = writableRootProblem(roots);
+    if (rootProblem)
+        throw new ExaminerWriteRefusedError(rootProblem);
+    const experimentMode = selection.isolatedMode ? 'isolated_principle' : 'full_library_incremental';
+    const minted = mintStudyHandle(roots);
+    if (!minted)
+        throw new Error('server-minted study handle collided — retry');
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define -- hoisted function declaration
+    const created = await materializeOfflineStudy(modules, labRoot, {
+        studyId: minted.studyId,
+        studyDir: minted.studyDir,
+        experimentMode,
+        target,
+        ledgerPrinciples: selection.ledgerPrinciples,
+        repetitionsPerCase: selection.repetitionsPerCase,
+    });
+    // The lab created the directory tree; verify the REAL location before the
+    // ownership marker (the trust anchor) is written into it.
+    const boundary = writableStudyDirProblem(roots, minted.studyDir);
+    if (boundary)
+        throw new ExaminerWriteRefusedError(boundary);
+    writeOwnershipMarker(minted.studyId, minted.studyDir, roots);
+    const { pairs } = created.pairAssignment;
+    return {
+        studyId: minted.studyId,
+        targetPrincipleId: target.id,
+        manifestHash: created.manifest.manifestHash,
+        plannedPairs: Array.isArray(pairs) ? pairs.length : null,
+    };
+}
+/**
+ * Create one offline examiner study. The study identity and directory are
+ * ALWAYS server-minted by the caller (crypto-random handle); this function
+ * receives already-validated server data only. Synthetic calibration cases
+ * with SYNTHETIC_OFFLINE gold provenance — offline contract validation,
+ * never real-host behavior.
+ */
+export async function materializeOfflineStudy(modules, labRoot, inputs) {
+    const fixtureUrl = pathToFileURL(path.join(labRoot, 'lib', 'examiner-v07-cases.mjs')).href;
+    const fixture = (await import(fixtureUrl));
+    const freezeUrl = pathToFileURL(path.join(labRoot, 'lib', 'challenge-freeze.mjs')).href;
+    const freeze = (await import(freezeUrl));
+    const caseDefs = [
+        fixture.makeExaminerV3Case({ caseId: `${inputs.studyId}-CASE-01` }),
+        fixture.makeExaminerV3Case({ caseId: `${inputs.studyId}-CASE-02`, boundary: true }),
+    ];
+    const principleFrozen = { contentJson: { principleDraft: { statement: inputs.target.text } } };
+    const mapping = {
+        schema: 'PainMechanismMappingV1',
+        mappingId: `PMM-${inputs.studyId}`,
+        principleContentHash: freeze.hashOfCanonical(principleFrozen.contentJson),
+        observedFailure: 'console-originated offline calibration (synthetic)',
+        failureMechanism: 'assertion_without_observation',
+        ownerGroundedGoal: 'offline contract validation for the console entry',
+    };
+    mapping.mappingHash = freeze.freezeMapping(mapping).mappingHash;
+    return modules.study.writeExaminerStudyArtifacts({
+        studyId: inputs.studyId,
+        experimentMode: inputs.experimentMode,
+        hepsPrinciples: { principles: inputs.ledgerPrinciples, targetPrincipleId: inputs.target.id, host: 'offline-stub' },
+        // P1-5: RuleCode facts are EVIDENCE, never a default. The ledger projects
+        // only the count of RuleCodes bound to the principle; absent individual
+        // RuleCode ids that count is passed as unresolved evidence, which makes the
+        // policy INTERVENTION_NOT_IDENTIFIABLE and the creation refuse (422).
+        // A zero count is a real, evidenced fact: no RuleCode exists to couple.
+        ruleCodeFacts: {
+            ruleCodes: [],
+            principleRuleCodeIndependence: (inputs.target.ruleCount ?? 0) === 0 ? true : null,
+            targetRuleCodeCount: inputs.target.ruleCount ?? 0,
+        },
+        caseDefs,
+        principleFrozen,
+        mapping,
+        primaryEndpointId: 'target_unsupported_completion_assertion_rate',
+        commonContextText: 'Offline examiner study created from the PD console (target principle read from the workspace ledger). Synthetic calibration cases — offline contract validation only, never real-host behavior.',
+        budgetChars: 2000,
+        seed: `${inputs.studyId}-seed`,
+        repetitionsPerCase: inputs.repetitionsPerCase,
+        hostManifest: { host: 'offline-stub', hostKind: 'offline-stub', adapter: 'lab-offline', maxProvableInjectionLevel: 'RUNTIME_LOADED' },
+        modelManifest: { model: 'offline-deterministic-stub', provider: 'local', version: 'stub-1' },
+        scorerVersion: 'mechanical-claim-evidence-v3',
+        analysisPlan: { primary: 'ITT over preregistered applicable pairs with UNKNOWN bounds', missingHandling: 'bounds only', inference: 'paired descriptive statistics — no significance claims (DESCRIPTIVE_ONLY)' },
+        invalidationPolicy: { hard: ['preregistration tampered', 'gold leak', 'shared memory across arms'], infrastructure: 'single failures stay UNKNOWN' },
+        goldProvenance: 'SYNTHETIC_OFFLINE',
+        studyDir: inputs.studyDir,
+    });
+}

package/console/dist/server/routes/examiner.d.ts

@@ -0,0 +1,52 @@
+/**
+ * SPEC-PD-EXAMINER-001 v0.9 §8 — Examiner Console API (offline-first).
+ *
+ * Product entry for the Examiner research pipeline on top of the existing
+ * principle-learning-lab (single research engine — no parallel Runner/Ledger/
+ * Scorer/Report). The lab runtime subset ships WITH the console payload
+ * (`console/lab`), so this surface is available in an installed runtime; a
+ * developer checkout is served from the repository's scripts/dev/ lab.
+ *
+ * Offline only: every study carries SYNTHETIC_OFFLINE gold and is executed by
+ * the deterministic local stub. Real model calls and real host runs stay
+ * behind the Owner-authorization / Stage R gate and are refused here.
+ *
+ * Surface (all offline, zero real model/host calls):
+ *   GET  /api/v1/examiner/overview                  — gates, host capability, study list
+ *   GET  /api/v1/examiner/principles                — workspace principles as study inputs
+ *   POST /api/v1/examiner/studies                   — create an offline examiner study
+ *   GET  /api/v1/examiner/studies/:studyId          — manifest + execution + report status
+ *   POST /api/v1/examiner/studies/:studyId/preflight — fail-closed preflight
+ *   POST /api/v1/examiner/studies/:studyId/run      — offline-stub execution (real modes refused)
+ *   GET  /api/v1/examiner/studies/:studyId/report   — Report V2 (read-only)
+ *   POST /api/v1/examiner/studies/:studyId/report   — generate Report V2 (idempotent)
+ *
+ * Safety contract: this route layer contains NO filesystem access — every
+ * study path is resolved inside examiner-executor by exact membership in the
+ * server's own directory enumeration, and study identities are always
+ * server-minted crypto-random handles. A request only SELECTS: the target
+ * principle travels onward as an index into the server's own ledger list,
+ * the experiment mode as a boolean. No request string crosses into the
+ * research pipeline, and no request value constructs a path.
+ *
+ * Two roots (P1-1): NEW console studies are WORKSPACE DATA — written under
+ * `<workspace>/.pd/examiner/studies` — and require the server's own ownership
+ * marker; the committed `examiner-studies/` research assets that travel with
+ * the lab payload are visible but ALWAYS read-only here (POST /run and
+ * POST /report answer 403). The frozen `challenge-studies/` area is never a
+ * write target. Real-host execution is refused by this route class itself.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * Locate the principle-learning-lab payload. Two layouts are legitimate and
+ * both are resolved from THIS module's own location — never from a request:
+ *
+ *   installed   <console>/lab                     (shipped by the installer)
+ *   repository  <repo>/scripts/dev/principle-learning-lab
+ *
+ * `PD_EXAMINER_LAB_ROOT` overrides both (operators / tests). A candidate only
+ * counts when the lab entry module is actually present, so a half-copied
+ * payload fails closed into the 503 branch instead of half-working.
+ */
+export declare function resolveLabRoot(moduleUrl: string, env?: Record<string, string | undefined>): string | null;
+export declare function handleExaminerRoute(req: IncomingMessage, res: ServerResponse, workspaceDir: string, subPath: string): Promise<void>;