create-principles-disciple 1.145.41 → 1.145.43

package/_release/product-identity.json

@@ -1,5 +1,5 @@
 {
   "schemaVersion": 1,
   "productVersion": "2.5.0",
-  "sourceCommit": "1c787bf80015d10ab8cd06bcb949c329f3dce473"
+  "sourceCommit": "5ee57d2ce6030686a3e8b98c78a9dfb636eb21bd"
 }

package/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/codex-adapter",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Codex CLI host adapter for Principles Disciple — implements HostAdapter interface for OpenAI Codex CLI's stdin/stdout JSON hook model (ADR-0020).",
   "type": "module",
   "main": "./dist/index.js",

package/console/dist/server/index.js

@@ -17,6 +17,7 @@ import { handleApprovalsRoute, disposeApprovalsModels } from './routes/approvals
 import { handleHealthRoute, disposeHealthModels } from './routes/health.js';
 import { handlePrinciplesRoute, handleCorePrinciplesRoute, disposePrinciplesModels } from './routes/principles.js';
 import { handleLifecycleRoute, disposeLifecycleModels } from './routes/lifecycle.js';
+import { handleExaminerRoute } from './routes/examiner.js';
 import { handleActivationsRoute, disposeActivationsModels } from './routes/activations.js';
 import { handleReceiptsRoute, disposeReceiptsModels } from './routes/receipts.js';
 import { handleApprovalsGroupedRoute, disposeApprovalsGroupedModels } from './routes/approvals-grouped.js';
@@ -456,6 +457,13 @@ function handleRequest(services) {
                 asyncHandler(() => handleLifecycleRoute(req, res, services.workspaceDir, subPath))(req, res);
                 return;
             }
+            // SPEC-PD-EXAMINER-001 v0.9 §8: Examiner offline studies (local-dev
+            // scope — the route answers 503 when the lab tooling is not present).
+            if (urlPath === '/api/v1/examiner' || urlPath.startsWith('/api/v1/examiner/')) {
+                const subPath = urlPath.slice('/api/v1/examiner'.length);
+                asyncHandler(() => handleExaminerRoute(req, res, services.workspaceDir, subPath))(req, res);
+                return;
+            }
             // CR8: GET /api/v1/activations
             if (urlPath === '/api/v1/activations' || urlPath.startsWith('/api/v1/activations/')) {
                 const subPath = urlPath.slice('/api/v1/activations'.length);

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

@@ -0,0 +1,254 @@
+export type LabModules = {
+    study: Record<string, unknown> & {
+        runExaminerPreflight: (input: Record<string, unknown>) => {
+            ok: boolean;
+            status: string;
+            blockers: unknown[];
+            warnings: unknown[];
+            checks: unknown[];
+        };
+        definePrimaryEndpoint: (input: {
+            id: string;
+        }) => Record<string, unknown>;
+        buildHostEffectivePrincipleSet: (input: Record<string, unknown>) => Record<string, unknown>;
+        buildRuleCodePolicy: (input: Record<string, unknown>) => Record<string, unknown>;
+        verifyExaminerStudyBindings: (studyDir: string, options?: {
+            requireAnchor?: boolean;
+        }) => {
+            ok: boolean;
+            anchor: string;
+            problems: string[];
+            bindingHash?: string | null;
+        };
+        verifyRuleCodePolicy: (policy: Record<string, unknown>) => {
+            ok: boolean;
+            reason?: string;
+        };
+        verifyHostEffectivePrincipleSet: (heps: Record<string, unknown>) => {
+            ok: boolean;
+            reason?: string;
+        };
+        writeExaminerStudyArtifacts: (input: Record<string, unknown>) => {
+            manifest: Record<string, unknown>;
+            pairAssignment: Record<string, unknown>;
+        };
+    };
+    runner: Record<string, unknown> & {
+        runChallengeStudy: (options: Record<string, unknown>) => Promise<{
+            units: Record<string, unknown>[];
+        }>;
+        verifyStudyRunReadiness: (studyDir: string) => unknown;
+    };
+    report: Record<string, unknown> & {
+        verifyBehaviorReportV2: (studyDir: string) => {
+            checks: {
+                ok: boolean;
+            }[];
+        };
+        writeBehaviorReportV2: (studyDir: string, options: {
+            now: string;
+            canWrite?: () => {
+                ok: boolean;
+                reason?: string;
+            };
+        }) => {
+            status: string;
+            written: boolean;
+        };
+    };
+    actor: Record<string, unknown> & {
+        createScriptedStub: (options: {
+            actions: Record<string, unknown>[];
+            armPrompt?: string | null;
+        }) => {
+            nextAction: () => Record<string, unknown>;
+            loadArmPrompt?: (prompt: string) => unknown;
+        };
+    };
+};
+/** Historical research-asset root — ALWAYS read-only, never a writable root. */
+export type StudyRoots = {
+    writable: string;
+    historical: string;
+};
+export declare const CONSOLE_OWNERSHIP_MARKER = ".console-study-owner.json";
+/** Stable, Owner-facing boundary reasons — never paths or exception text. */
+export declare const STUDY_PATH_PROBLEM: {
+    readonly unresolved: 'the study path cannot be resolved to a canonical location (fail-closed)';
+    readonly notInside: 'the study directory resolves outside the writable console root';
+    readonly historical: 'the study directory resolves inside the historical research area';
+    readonly 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 declare function canonicalPathSync(target: string): string | null;
+export declare function isSamePath(a: string, b: string): boolean;
+/** Strict containment: equal paths are NOT inside each other. */
+export declare function isPathInside(root: string, candidate: string): boolean;
+/** Resolve the two roots once. `PD_EXAMINER_STUDIES_ROOT` overrides the WRITABLE root only. */
+export declare function resolveStudyRoots(labRoot: string): StudyRoots;
+export declare function isJsonObject(value: unknown): value is Record<string, unknown>;
+/** Boundary-checked study file reader (fails closed on missing/malformed). */
+export declare function readStudyJson(studyDir: string, rel: string): Record<string, unknown>;
+/**
+ * List the study directory names the server itself enumerated under the
+ * studies root (sorted). The route layer treats this list as the allowlist.
+ */
+export declare function listStudyNames(studiesRoot: string): string[];
+export type StudyAccess = {
+    dir: string;
+    studyId: string;
+    readOnly: boolean;
+    reason: string;
+};
+/**
+ * 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 declare function verifyConsoleOwnership(writableRoot: string, studyDir: string): {
+    ok: boolean;
+    reason: string;
+};
+/**
+ * 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 declare function resolveStudyAccess(roots: StudyRoots, requested: string): StudyAccess | 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 declare function writableRootProblem(roots: StudyRoots): string | 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 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 {
+    readonly blockers: unknown[];
+    constructor(blockers: unknown[]);
+}
+export declare class ExaminerWriteRefusedError extends Error {
+    constructor(message: string);
+}
+/** The frozen study area + historical root this server must never write into. */
+export type StudyDirContext = {
+    labRoot: string;
+    roots: StudyRoots;
+};
+export declare function preflightCheck(modules: LabModules, studyDir: string, context?: StudyDirContext): {
+    ok: boolean;
+    status: string;
+    blockers: unknown[];
+    warnings: unknown[];
+    checks: unknown[];
+};
+/**
+ * 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 declare function offlineStudyPass(modules: LabModules, studyDir: string, context?: StudyDirContext): Promise<{
+    units: Record<string, unknown>[];
+}>;
+export declare function reportMaterialize(modules: LabModules, studyDir: string, now: string, context: StudyDirContext | undefined, canWrite: () => {
+    ok: boolean;
+    reason?: string;
+}): {
+    status: string;
+    written: boolean;
+};
+export declare function studyReportVerify(modules: LabModules, studyDir: string): {
+    checks: {
+        ok: boolean;
+    }[];
+};
+export declare function loadLabModules(labRoot: string): Promise<LabModules>;
+/** Host injection-capability ceiling table (from examiner-injection-evidence.mjs). */
+export declare function loadHostCapability(labRoot: string): Promise<Record<string, string>>;
+export type CreateStudyInputs = {
+    studyId: string;
+    studyDir: string;
+    experimentMode: 'isolated_principle' | 'full_library_incremental';
+    target: {
+        id: string;
+        version: string;
+        text: string;
+        status: string;
+        ruleCount?: number;
+    };
+    ledgerPrinciples: {
+        id: string;
+        version: string;
+        text: string;
+        status: string;
+        ruleCount?: number;
+    }[];
+    repetitionsPerCase: number;
+};
+/** Server-minted study handle + directory (crypto-random; never request-derived). */
+export declare function mintStudyHandle(roots: StudyRoots): {
+    studyId: string;
+    studyDir: string;
+} | null;
+/**
+ * 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 declare function materializeConsoleStudy(modules: LabModules, labRoot: string, roots: StudyRoots, selection: {
+    isolatedMode: boolean;
+    targetIndex: number;
+    ledgerPrinciples: {
+        id: string;
+        version: string;
+        text: string;
+        status: string;
+        ruleCount?: number;
+    }[];
+    repetitionsPerCase: number;
+}): Promise<{
+    studyId: string;
+    targetPrincipleId: string;
+    manifestHash: unknown;
+    plannedPairs: number | 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 declare function materializeOfflineStudy(modules: LabModules, labRoot: string, inputs: CreateStudyInputs): Promise<{
+    manifest: Record<string, unknown>;
+    pairAssignment: Record<string, unknown>;
+}>;