create-principles-disciple 1.146.8 → 1.147.0

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

@@ -149,8 +149,6 @@ export declare function writableRootProblem(roots: StudyRoots): string | null;
  * mutation — a check done only at startup is not evidence about now.
  */
 export declare function writableStudyDirProblem(roots: StudyRoots, studyDir: string): string | null;
-/** Study status projection (manifest + ledger settlement counts + report status). */
-export declare function studyStatusPayload(studyDir: string): Record<string, unknown>;
 /** Read-only Report V2 payload + replay verification. */
 export declare function studyReportPayload(modules: LabModules, studyDir: string): Record<string, unknown> | null;
 export declare class ExaminerPreflightBlockedError extends Error {
@@ -179,7 +177,9 @@ export declare function preflightCheck(modules: LabModules, studyDir: string, co
  * 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 declare function offlineStudyPass(modules: LabModules, studyDir: string, context?: StudyDirContext): Promise<{
+export declare function offlineStudyPass(modules: LabModules, studyDir: string, context?: StudyDirContext, admissionCheck?: (input: {
+    studyDir: string;
+}) => void | Promise<void>): Promise<{
     units: Record<string, unknown>[];
 }>;
 export declare function reportMaterialize(modules: LabModules, studyDir: string, now: string, context: StudyDirContext | undefined, canWrite: () => {
@@ -217,6 +217,26 @@ export type CreateStudyInputs = {
     }[];
     repetitionsPerCase: number;
 };
+/**
+ * v0.10.1 host-backed inputs (SPEC §4/§6/§7): the frozen production snapshot,
+ * the runtime-derived RuleCode facts and the real pain lineage. All gathered
+ * by the caller (examiner-study-inputs) from existing authorities; this layer
+ * only freezes them into the study directory. Suite CASES are compiled here
+ * with the minted study handle (case ids are study-scoped).
+ */
+export type HostBackedStudyInputs = {
+    productionSnapshot: Record<string, unknown>;
+    ruleCodeFacts: {
+        ruleCodes: {
+            ruleCodeId: string;
+            principleId: string;
+            baselineState: 'ON' | 'OFF';
+        }[];
+        principleRuleCodeIndependence: boolean | null;
+        targetRuleCodeCount: number;
+    };
+    painRefs: string[];
+};
 /** Server-minted study handle + directory (crypto-random; never request-derived). */
 export declare function mintStudyHandle(roots: StudyRoots): {
     studyId: string;
@@ -241,6 +261,10 @@ export declare function materializeConsoleStudy(modules: LabModules, labRoot: st
         ruleCount?: number;
     }[];
     repetitionsPerCase: number;
+    /** v0.10.1: catalog suite key (validated by the caller against the fixed list). */
+    suiteKey?: string;
+    /** v0.10.1: host-backed inputs (production snapshot / RuleCode facts / pain refs). */
+    hostBacked?: HostBackedStudyInputs;
 }): Promise<{
     studyId: string;
     targetPrincipleId: string;
@@ -253,8 +277,20 @@ export declare function materializeConsoleStudy(modules: LabModules, labRoot: st
  * receives already-validated server data only. Synthetic calibration cases
  * with SYNTHETIC_OFFLINE gold provenance — offline contract validation,
  * never real-host behavior.
+ *
+ * v0.10.1: when `hostBacked` inputs are supplied, the study freezes the
+ * caller-selected suite cases, the RUNTIME-derived RuleCode facts and the
+ * real pain lineage, and `production-snapshot.json` records where the A/B
+ * starting point differs from production (SPEC §4.4/§6.4). The frozen
+ * binding files the lab verifies are unchanged — the snapshot is an
+ * additional frozen fact, hashed by nothing that the runner recomputes, so
+ * appending it after writeExaminerStudyArtifacts keeps every existing
+ * verification intact (events.jsonl rides the same discipline).
  */
-export declare function materializeOfflineStudy(modules: LabModules, labRoot: string, inputs: CreateStudyInputs): Promise<{
+export declare function materializeOfflineStudy(modules: LabModules, labRoot: string, inputs: CreateStudyInputs & {
+    suiteKey?: string;
+    hostBacked?: HostBackedStudyInputs;
+}): Promise<{
     manifest: Record<string, unknown>;
     pairAssignment: Record<string, unknown>;
 }>;

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

@@ -277,34 +277,6 @@ export function writableStudyDirProblem(roots, studyDir) {
         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')))
@@ -409,7 +381,7 @@ export function preflightCheck(modules, studyDir, context) {
  * 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) {
+export async function offlineStudyPass(modules, studyDir, context, admissionCheck) {
     // 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.
@@ -435,6 +407,9 @@ export async function offlineStudyPass(modules, studyDir, context) {
         },
         actorFactory: ({ armId }) => modules.actor.createScriptedStub({ actions: didacticActions(armId) }),
         execution: { mode: 'offline-stub' },
+        // P1-3: the runner invokes this UNDER the study write lock, before
+        // RUN_STARTED / reservation / actor creation. Supplied by the route layer.
+        ...(admissionCheck ? { admissionCheck } : {}),
     });
 }
 export function reportMaterialize(modules, studyDir, now, context, canWrite) {
@@ -554,6 +529,8 @@ export async function materializeConsoleStudy(modules, labRoot, roots, selection
         target,
         ledgerPrinciples: selection.ledgerPrinciples,
         repetitionsPerCase: selection.repetitionsPerCase,
+        suiteKey: selection.suiteKey,
+        hostBacked: selection.hostBacked,
     });
     // The lab created the directory tree; verify the REAL location before the
     // ownership marker (the trust anchor) is written into it.
@@ -575,40 +552,67 @@ export async function materializeConsoleStudy(modules, labRoot, roots, selection
  * receives already-validated server data only. Synthetic calibration cases
  * with SYNTHETIC_OFFLINE gold provenance — offline contract validation,
  * never real-host behavior.
+ *
+ * v0.10.1: when `hostBacked` inputs are supplied, the study freezes the
+ * caller-selected suite cases, the RUNTIME-derived RuleCode facts and the
+ * real pain lineage, and `production-snapshot.json` records where the A/B
+ * starting point differs from production (SPEC §4.4/§6.4). The frozen
+ * binding files the lab verifies are unchanged — the snapshot is an
+ * additional frozen fact, hashed by nothing that the runner recomputes, so
+ * appending it after writeExaminerStudyArtifacts keeps every existing
+ * verification intact (events.jsonl rides the same discipline).
  */
 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 }),
-    ];
+    // v0.10.1 §9: a catalog suite key compiles the selected variants under the
+    // MINTED study handle (case ids are study-scoped); absent key = v0.9 default.
+    let caseDefs;
+    if (typeof inputs.suiteKey === 'string') {
+        const { suiteCaseDefs, isSuiteKey } = await import('./examiner-study-inputs.js');
+        if (!isSuiteKey(inputs.suiteKey))
+            throw new Error(`materializeOfflineStudy: unknown suite key '${inputs.suiteKey}'`);
+        caseDefs = await suiteCaseDefs(labRoot, inputs.studyId, inputs.suiteKey);
+    }
+    else {
+        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 painRefs = inputs.hostBacked?.painRefs ?? [];
     const mapping = {
         schema: 'PainMechanismMappingV1',
         mappingId: `PMM-${inputs.studyId}`,
         principleContentHash: freeze.hashOfCanonical(principleFrozen.contentJson),
-        observedFailure: 'console-originated offline calibration (synthetic)',
+        observedFailure: painRefs.length > 0
+            ? `console-originated offline calibration mapped to the target principle's real pain lineage (${painRefs.join(', ')})`
+            : 'console-originated offline calibration (synthetic)',
         failureMechanism: 'assertion_without_observation',
         ownerGroundedGoal: 'offline contract validation for the console entry',
+        painRefs,
     };
     mapping.mappingHash = freeze.freezeMapping(mapping).mappingHash;
-    return modules.study.writeExaminerStudyArtifacts({
+    const ruleCodeFacts = inputs.hostBacked?.ruleCodeFacts ?? {
+        // P1-5 fallback (pre-v0.10.1 shape): ledger rule count as the only fact.
+        ruleCodes: [],
+        principleRuleCodeIndependence: (inputs.target.ruleCount ?? 0) === 0 ? true : null,
+        targetRuleCodeCount: inputs.target.ruleCount ?? 0,
+    };
+    const writeResult = 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,
-        },
+        // P1-5: RuleCode facts are EVIDENCE, never a default. With hostBacked
+        // inputs the facts come from RUNTIME activation rows cross-checked against
+        // the ledger count (examiner-study-inputs.deriveStudyRuleCodeFacts); an
+        // unresolvable attribution still lands as INTERVENTION_NOT_IDENTIFIABLE,
+        // which makes the creation refuse (422). A zero count on BOTH sources is
+        // a real, evidenced fact: no RuleCode exists to couple.
+        ruleCodeFacts,
         caseDefs,
         principleFrozen,
         mapping,
@@ -624,5 +628,10 @@ export async function materializeOfflineStudy(modules, labRoot, inputs) {
         invalidationPolicy: { hard: ['preregistration tampered', 'gold leak', 'shared memory across arms'], infrastructure: 'single failures stay UNKNOWN' },
         goldProvenance: 'SYNTHETIC_OFFLINE',
         studyDir: inputs.studyDir,
+        // P1-1: the production baseline freezes WITH the study — hash-bound into
+        // the manifest, the binding and the anchor; post-freeze modification is
+        // drift that preflight/runner refuse.
+        ...(inputs.hostBacked?.productionSnapshot ? { productionSnapshot: inputs.hostBacked.productionSnapshot } : {}),
     });
+    return writeResult;
 }

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

@@ -0,0 +1,196 @@
+import { type LabModules, type StudyRoots } from './examiner-executor.js';
+export declare const CONSOLE_RUN_SCHEMA = "examiner-console-run.v1";
+export declare const CONSOLE_RUN_EVENT_TYPES: readonly ['CONSOLE_RUN_ACCEPTED', 'CONSOLE_RUN_FINISHED', 'CONSOLE_RUN_FAILED', 'CONSOLE_RUN_ABANDONED'];
+export type ConsoleRunMode = 'host-dry-run' | 'f2-real-host';
+export type ConsoleRunEventType = (typeof CONSOLE_RUN_EVENT_TYPES)[number];
+export declare const CONSOLE_RUN_MODES: readonly ConsoleRunMode[];
+export interface ConsoleRunEvent {
+    type: ConsoleRunEventType;
+    schema: typeof CONSOLE_RUN_SCHEMA;
+    runId: string;
+    studyId: string;
+    mode: ConsoleRunMode;
+    acceptedAt: string;
+    pid: number;
+    owner: 'pd-console';
+    finishedAt?: string;
+    outcome?: string;
+    reason?: string;
+    checks?: unknown[];
+}
+export interface ConsoleRunState {
+    runId: string;
+    mode: ConsoleRunMode;
+    status: 'RUNNING' | 'FINISHED' | 'FAILED' | 'ABANDONED';
+    acceptedAt: string;
+    finishedAt: string | null;
+    outcome: string | null;
+    reason: string | null;
+    /** The dry-run checklist carried by the terminal event (never re-invented). */
+    checks?: unknown[];
+}
+/**
+ * P1-4: the study's event ledger is UNREADABLE for a reason the Owner must
+ * see — a corrupt or permission-blocked ledger is never silently treated as
+ * "no runs". Only a genuinely absent file (first-run condition) yields [].
+ */
+export declare class ConsoleLedgerUnreadableError extends Error {
+    readonly code: 'ledger_unreadable' | 'ledger_corrupt';
+    constructor(code: 'ledger_unreadable' | 'ledger_corrupt', message: string);
+}
+export interface OwnedProbeDir {
+    path: string;
+    dev: bigint;
+    ino: bigint;
+}
+export interface StudyDirPin {
+    real: string;
+    dev: bigint;
+    ino: bigint;
+}
+/**
+ * Remove the dry-run probe directory ONLY when it is still the exact plain
+ * directory this run created (identity dev+ino), still resolves inside the
+ * same study directory, and the study directory itself has not been swapped.
+ * Any unprovable case keeps the residue and reports why — an unknown path is
+ * never deleted.
+ */
+export declare function removeProbeDirIfStillOwned(probe: OwnedProbeDir, study: StudyDirPin): {
+    removed: boolean;
+    reason?: string;
+};
+/** Append one console-run lifecycle event to the study's events ledger. */
+export declare function appendConsoleRunEvent(roots: StudyRoots, studyDir: string, event: ConsoleRunEvent): void;
+export declare class OfflineRunInFlightError extends Error {
+    constructor();
+}
+export declare function mintRunId(): string;
+/** Derive the console-run states from the study ledger (never stored separately). */
+export declare function readConsoleRuns(roots: StudyRoots, studyDir: string): ConsoleRunState[];
+export declare function currentConsoleRun(runs: ConsoleRunState[]): ConsoleRunState | null;
+/**
+ * Study status projection (manifest + ledger settlement counts + report status).
+ * The DISPLAY projection tolerates single corrupt lines — the authoritative
+ * console-run reader refuses them and the route reports `ledgerProblem` — but
+ * it reads the ledger through the SAME secure fd boundary (never by path).
+ */
+export declare function studyStatusPayload(roots: StudyRoots, studyDir: string): Record<string, unknown>;
+/**
+ * P1-4: the whole acceptance transaction — read current runs, check the
+ * single-live constraint (async AND offline in-flight), verify the study is
+ * still writable, append CONSOLE_RUN_ACCEPTED — happens under the EXISTING
+ * lab study write lock, so two concurrent requests can never both pass the
+ * check. The lock guards ONLY the acceptance; the async execution itself
+ * runs unlocked (settlement appends race-free through the same lock the
+ * runner already takes for real executions).
+ */
+export declare class ConsoleRunInProgressError extends Error {
+    readonly runId: string;
+    readonly mode: string;
+    readonly acceptedAt: string;
+    constructor(running: ConsoleRunState);
+}
+export interface ConsoleRunAcceptance {
+    runId: string;
+    acceptedAt: string;
+}
+export declare function acceptConsoleRun(roots: StudyRoots, studyDir: string, inputs: {
+    studyId: string;
+    mode: ConsoleRunMode;
+    labRoot: string;
+}): Promise<ConsoleRunAcceptance>;
+/**
+ * Append an async run's TERMINAL event under the study write lock. Recovery
+ * (which also holds the lock) therefore either sees the terminal event and
+ * skips, or appends ABANDONED first and the later terminal event wins — an
+ * already-settled run can never be reported as ABANDONED.
+ */
+export declare function appendConsoleRunEventLocked(input: {
+    labRoot: string;
+    roots: StudyRoots;
+    studyDir: string;
+}, event: ConsoleRunEvent): Promise<void>;
+/**
+ * Offline→async half of the single-active contract (P1-3).
+ *
+ * The lab runner calls this UNDER the study write lock, BEFORE RUN_STARTED,
+ * attempt reservation or actor creation. The caller (route layer) supplies it
+ * so `examiner-runs` and `examiner-executor` never import each other.
+ */
+export declare function assertOfflineAdmissionAllowed(roots: StudyRoots, studyDir: string): void;
+/** Best-effort liveness probe for the process that accepted a run. */
+export declare function processAlive(pid: number): boolean;
+/**
+ * Startup recovery: walk the WRITABLE root only (historical assets are never
+ * console-run targets) and abandon every unfinished console run whose
+ * accepting process is gone. An accepting process that is still alive keeps
+ * its run (another console server may legitimately be serving the workspace).
+ *
+ * Path safety: only names the server itself enumerated that pass the
+ * study-handle charset allowlist, each directory must resolve canonically
+ * INSIDE the writable root, and every ledger access re-proves containment at
+ * the point of use — a symlinked/junctioned entry is skipped, never followed.
+ */
+export declare function recoverUnfinishedConsoleRuns(roots: StudyRoots, labRoot: string): Promise<{
+    studyId: string;
+    runId: string;
+}[]>;
+export interface StageRRead {
+    present: boolean;
+    record: Record<string, unknown> | null;
+    problem: string | null;
+}
+export interface DryRunCheck {
+    id: string;
+    severity: 'blocker' | 'warning' | 'info';
+    ok: boolean;
+    detail: string;
+}
+export interface HostDryRunResult {
+    ok: boolean;
+    checks: DryRunCheck[];
+    authorization: {
+        present: boolean;
+        status: string | null;
+        executionMode: string | null;
+        model: string | null;
+        note: string;
+    };
+    hostProbe: {
+        cliVersion: string | null;
+        note: string;
+    };
+    modelCalls: 0;
+}
+/**
+ * The host dry-run: everything Gate 2 can check WITHOUT a model call. It is
+ * deliberately a checklist, not a pass/fail black box — the Owner sees exactly
+ * which prerequisite is missing before real execution can be requested.
+ */
+export declare function hostDryRunPass(input: {
+    modules: LabModules;
+    labRoot: string;
+    studyDir: string;
+    context: {
+        labRoot: string;
+        roots: StudyRoots;
+    } | undefined;
+}): Promise<HostDryRunResult>;
+export interface F2GateResult {
+    authorized: boolean;
+    reasons: string[];
+    record: Record<string, unknown> | null;
+}
+/**
+ * P1-5: the console gate REUSES the lab's authoritative Stage R verifier
+ * (verifyStageRAuthorization) instead of a hand-rolled subset — schema,
+ * stage/status, the full study binding (studyId/suiteHash/mappingHash/
+ * graderHash/studyPlanHash), arms/cases/repetitions coverage, attemptCap,
+ * requestCap, the validity window, the retirement registry, revocation/
+ * halted, requestedActorIdentity and the F2 real-host probe evidence are ALL
+ * enforced. A record that is merely status=APPROVED fails every missing
+ * binding it does not carry. The runner re-verifies the same authority per
+ * unit under the study lock — this gate is a necessary condition, the runner
+ * is the authority.
+ */
+export declare function f2AuthorizationGate(labRoot: string, studyDir: string): Promise<F2GateResult>;