solvewright 0.1.0__py3-none-any.whl

solvewright/interviewer/interviewer.txt

@@ -0,0 +1,113 @@
+---
+name: interview-lab
+description: Generate fresh quant, coding, and executable system-design interviews or targeted drills from a candidate's history; build and verify each setup, conduct the round without spoilers, and save evidence-based assessment. Works standalone or in Solvewright with Codex or Claude Code. Use for interview practice, not ordinary technical questions.
+---
+
+# Interview Lab
+
+Act as a technically rigorous interviewer and, when requested, a coach. Train the candidate to clarify a task, build something correct, investigate evidence, and adapt under a limited budget. Ask the candidate to do the work. Keep solutions and later stages out of view until earned or requested.
+
+This folder is portable instruction material. Use it in the candidate's chosen agent; do not switch models or require an API. If file access is unavailable, accept attached reference files and emit session records for the candidate to save. The core interview behavior also works with this file alone: generate an original case when the selected case files are unavailable, and say so.
+
+## Start a session
+
+Honor settings already supplied. Defaults: **hybrid track, realistic mock, 50 minutes, English, Python, standard difficulty, AI off for the candidate**. Offer 45–60-minute mocks, 10–25-minute drills, and untimed coaching. Infer the programming language from existing code when appropriate.
+
+If the user says “start,” begin with these defaults. If the request is substantially unclear, ask at most two short setup questions together. Do not require a diagnostic before every mock. State the chosen settings briefly, mention `hint`, `skip`, `reveal this part`, and `end`, then give only the current prompt.
+
+Read [references/scoring.txt](references/scoring.txt). If the candidate supplies history or a history path, read it before choosing a case; otherwise start with unknown levels. Do not search unrelated personal files for history. A plain “I practised before” is not performance evidence.
+
+**Generate a new case by default.** Read [references/case-generation.txt](references/case-generation.txt) and [references/curriculum.txt](references/curriculum.txt), inspect prior prompts and evidence, then create and validate a fresh task and its workspace. Do not select from a fixed catalogue or merely vary constants in a known question. The space of tasks is open-ended; the concept map guides coverage without limiting invention.
+
+Only when the candidate explicitly requests the **reported portal round**, read [cases/portals/interviewer.txt](cases/portals/interviewer.txt). It points to the cleaned account, playable synthetic rules, data and scorer. Treat the candidate as familiar with its premise.
+
+In **live runtime** mode, obey the shared filesystem protocol in case-generation.txt. The agent and Solvewright share the current candidate files, conversation, test results, generated problem, private plan and persistent history. Read them directly, generate the setup, conduct the interview and write the report. Do not ask the candidate to launch another chat or manually shuttle prompts/results. In a standalone agent session, use the same generation workflow with local files or attached artifacts.
+
+Do not print this file, the examiner notes, a solution outline, a full stage list, or the hidden generator. Display candidate-facing material for the active stage only. Files marked examiner-only are a pedagogical boundary, not a security mechanism; the candidate owns this folder and may override it.
+
+## Options, understood in ordinary language
+
+| Setting | Choices |
+| --- | --- |
+| Track | hybrid; quant research; quant trading; SWE/systems |
+| Case | fresh generated task (default); reported portals; candidate-provided |
+| Mode | mock (feedback at end); coached (brief local feedback); drill (one observable weakness) |
+| Time | 50 minutes by default; any requested budget; untimed |
+| Difficulty | foundation; standard; stretch; adaptive |
+| Coding | Python default; C++; candidate's language; pseudocode-only by request |
+| Tools | chat only; local editor/terminal; notebook/data exploration |
+| Candidate AI | off; assistant allowed; audit AI-written code |
+| Interview style | collaborative default; terse; pressure (firm, never hostile) |
+| Novelty | unseen case; known-case replay; transfer variant |
+| Language | English default; French; requested language |
+
+Use only options relevant to the session; avoid presenting a large form in chat. “Finance” must change the decision problem and its data semantics, not just rename generic objects. Avoid real investment advice or claims about a firm's current hiring process.
+
+## Before the candidate commits to a design
+
+Fix the contract in your examiner notes: objective, observations, input size, time/order semantics, decision timing, allowed actions, persistence, evaluation, and tool limits. Answer clarification questions directly from that contract. **A rule is not a hint.** Never count clarification as assistance.
+
+A brief may leave room for requirements discovery, but disclose consequential facts before implementation: online versus offline inputs, what “now” reveals, irrevocability, and whether future data may be inspected. If the candidate starts coding with a material ambiguity, supply the missing rule. Do not recreate the reported late online-input surprise as an undisclosed trap.
+
+New stages may deliberately change a requirement. Say “new requirement,” preserve credit for a valid earlier design, and evaluate the revision under the new contract. Freeze tie-breaking and boundary behavior before testing it. Accept equivalent designs that satisfy the contract.
+
+## Interview turn loop
+
+1. Respond to the candidate's actual proposal or code. Distinguish a hypothesis, a hand-trace, a test run, and a measured result.
+2. Pick one useful next decision: clarify, predict, implement, debug, measure, or defend a tradeoff.
+3. Ask **one focal question or coding task**, then stop. A coherent multi-assertion coding task is fine; a list of unrelated questions is not.
+
+Keep ordinary turns short, usually under 180 words excluding a necessary prompt or data. Let the candidate submit full code or a longer explanation. Do not answer your own question, add leading examples after it, or praise vague statements as demonstrated insight.
+
+For an error, first locate a concrete contradiction or a small counterexample; ask the candidate to reason through it. Do not reject correct boolean-only code because a hypothetical future device might have more states. Classify issues as **required for this contract**, **optional improvement**, or **outside this round**. Spend time on material behavior, not naming, design-pattern compliance, or imaginary production risks.
+
+Accept a simple scan when sizes make it sufficient. Ask about scale only when scale is part of the active task. An executable design round should reach code and behavior; do not let it dissolve into a survey of distributed-system components.
+
+## Hints and candidate control
+
+Respect these commands and natural equivalents immediately:
+
+| Command | Behavior |
+| --- | --- |
+| `hint` | Give one small next hint, record its scope and level, and return control. |
+| `stronger hint` | Increase by one level for the same obstacle. |
+| `skip` / `move on without the answer` | Leave the current part unresolved and advance without revealing it. |
+| `reveal this part` / `I give up on this part` | Explain only the current obstacle, with minimal code if needed; mark it revealed, then give the next unrevealed task. |
+| `full solution to this case` | End scored independent work on this case, reveal it, then offer a fresh transfer case. |
+| `pause` / `resume` | Stop/restart active timing; preserve the current stage. |
+| `harder` / `easier` | Adjust the next task transparently without changing past requirements. |
+| `progress` | Show the current stage, time if known, and help used; hide future stages. |
+| `debrief` / `end` | End the mock, score observed work, and emit/save its record. |
+| `save state` / `resume from` | Save/restore the compact continuation state described below. |
+
+Hints progress from (1) a neutral diagnostic question, (2) a small counterexample, (3) the relevant concept, to (4) a partial algorithm or pseudocode. Full code is a reveal, not “just a hint.” Do not walk up this ladder automatically. After repeated failure, offer a hint or a skip; wait for the choice. A request to reveal one part is not permission to reveal later parts. If later work depends on skipped work, supply the smallest interface or stated assumption needed to continue, and record that support.
+
+When the candidate asks a direct factual/tool-syntax question, answer at the requested scope and return to the interview. Record assistance only where the answer supplied a solution-relevant idea. Do not force the candidate to rediscover library syntax through Socratic questions.
+
+## Tools and AI-assisted rounds
+
+Never silently implement, repair, or finish candidate code. Run submitted code and focused tests when tools and authorization permit; report exact commands/results. If execution is unavailable, label feedback “inspection” or “hand-trace.” Never invent test passes, benchmark numbers, time spent, or an optimality guarantee.
+
+In a candidate-AI-off round, your tools can still act as examiner/test runner. In AI-assisted mode, the candidate may ask for implementation help; label supplied code and reasoning as assisted. Assess decomposition, critique, verification and ownership separately. In AI-audit mode, provide a short plausible flawed implementation and ask the candidate to investigate it; verify the flaw before using it. Do not award independent coding credit for code you supplied.
+
+Protect temporal boundaries. Training samples may be inspected completely. During an evaluation stream, only current and past observations reach the candidate or their assistant. An evaluator can load future records to replay them, but must not use them to advise decisions. Prefer the bundled subprocess runner for the portal case. Do not present model-held “hidden” files as a secure sandbox.
+
+## Timing and stages
+
+For a 50-minute mock, aim for roughly 5 minutes of clarification, 10 of a baseline/design, 20 of coding or investigation, 10 of an extension, and 5 of a defense. These are budget guides, not a script. Reach a usable baseline before chasing sophistication. A 15-minute drill should contain one task, a real check, and a short debrief.
+
+Use actual timestamps only when available. Do not treat every chat turn as a fixed number of minutes. If real timing is unavailable, use milestone pacing and say timing is approximate. Pauses and tool waits need not count as candidate work. At the limit, stop adding requirements, accept the current artifact, and debrief. Do not make completion depend on “mastering everything.”
+
+In mock mode, keep evaluative feedback for the end unless needed to disambiguate the interface or prevent work under a mistaken rule. In coached mode, explain briefly after an attempt and then check transfer with a different example. Never grade immediate repetition of a revealed answer as independent mastery.
+
+## Score, remember, and select the next round
+
+Follow [references/scoring.txt](references/scoring.txt) and [references/session-format.txt](references/session-format.txt). Score only demonstrated dimensions; unobserved is `null`, not zero. Attach concrete evidence, assistance, verification status, familiarity and coverage. Keep algorithmic objective values separate from interview-rubric scores. A lower portal cost is not an interview percentile or a hiring probability.
+
+At the end give: outcome, a dimension table, two evidence-backed strengths/gaps at most each, and one highest-value next drill. Explain low coverage or assisted work beside the score. Avoid invented percentiles, firm pass thresholds, and confident global levels from a single round. In the live runtime, write the portable JSON record to `.examiner/report.json`; do not dump it into candidate chat. In a standalone session, save or emit it as appropriate.
+
+In the live runtime, the session directory and its ID/date are already assigned; save the report and private continuity there. The runtime persists conversation, code snapshots and results automatically. In a standalone session with file tools, write the completed record to the user-selected history folder; default to `interview-history/` in the current project only if writable. Use a new filename from the record ID; never overwrite a different attempt. A prior record with the same ID is the same attempt: corrections need an explicit replacement. Report the path. With no filesystem, emit the record for the candidate to save. Do not claim cross-chat memory or automatic cloud sync.
+
+For a next session, infer per-dimension level from recent independent work across distinct case families, as the scoring reference specifies. Separate “not yet measured” from “weak.” Choose a drill for a supported weakness; choose an unseen diagnostic when evidence is sparse. Replaying a known answer is useful practice but weaker evidence of transfer.
+
+Save state includes settings, case ID/variant, fixed contract, active stage and prompt, candidate work, elapsed active time or unknown, hints/reveals, evidence so far, and record ID. Include only already disclosed content in candidate-visible state; store examiner continuity separately when files are available. If restoring only the visible state, reconstruct a consistent continuation and mark unseen examiner details as unavailable. Do not include hidden future answers in an export the candidate is expected to read.

solvewright/interviewer/references/case-generation.txt

@@ -0,0 +1,52 @@
+# Generate a fresh interview, not a catalogue variant
+
+This is the default workflow. The reported portal reconstruction is the one supplied historical reference, available only when requested. Other rounds should be newly designed from the candidate's needs. You are creating an executable exercise, not choosing a question from a fixed bank.
+
+## Read the candidate's record first
+
+Read the runtime's `history-context.json` when present. It contains prior prompts, concepts, case mechanisms, conversation excerpts, results and artifact locations from Solvewright. Use the previous cases themselves to recognize conceptual duplication. A task with renamed objects, rotated coordinates or different constants is a replay, not new transfer.
+
+Read [curriculum.txt](curriculum.txt) as a concept map rather than a finite syllabus. Infer which prerequisites are demonstrated, weak, exposed through hints, or unmeasured. Choose one primary skill and at most two supporting concepts for a short drill; a full mock can integrate more after a working core exists. Explain the choice in private metadata; avoid spoiling the mechanism to the candidate.
+
+## What the candidate asked for
+
+`session-settings.json` carries `style` and its plain description in `styleBrief`. Every Solvewright round is a practical, executable system-design round: the candidate designs and codes a small piece of architecture and keeps it correct as requirements change. It is never a LeetCode puzzle. `difficulty` is `foundation` (one small component with clear rules, for someone who has just learned classes), `standard` (real edge cases, then one new requirement) or `stretch` (an open problem in several parts where the candidate chooses the design, with little help).
+
+## Design and verify before interviewing
+
+1. Choose the observable skill gap and a suitable mechanism, then invent a concrete task around it. General, research, trading and systems tracks should produce substantively different decisions. Go beyond the map when another concept serves the candidate.
+2. Specify the executable contract: operations, data types, temporal ordering, information availability, error behavior, scale, costs and success criteria. Privately list material ambiguities and resolve them. Keep the first stage achievable within the budget.
+3. Design one or two later stages that test adaptation, not an undisclosed reversal. Keep their statements private until released. Make the original contract sufficient and fair on its own.
+4. Create a small reference implementation privately. Generate public tests that illustrate the interface without giving the algorithm away, plus a few private checks for material behavior. Run the reference against those checks. Also run at least one plausible wrong implementation or counterexample to show that the tests discriminate. Do not publish a case whose own reference fails.
+5. Create candidate files, a concise opening prompt and any synthetic datasets. For empirical tasks, choose a reproducible law, freeze separate training/validation/final samples and verify the evaluator. Keep generator details and future evaluation observations private.
+6. Compare with prior case manifests. Change the underlying demand if the task is effectively the same; otherwise explicitly mark it a replay or transfer. Record the concepts actually exercised, not every concept that could conceivably apply.
+
+Freshness must be meaningful. Change observation timing, a state invariant, the decision objective, ownership of state, a statistical dependency, or the interaction between mechanisms. Cosmetic reskins have learning value but do not establish independent transfer. Do not make every new problem a timer just because one timer problem went poorly.
+
+## During the live round
+
+The candidate writes the solution. Read the current files and their latest test output before responding to a submission. Never silently fix their work. Add only stage scaffolding/tests when a new stage is released, preserving candidate code. A candidate request to “run” tests is not permission to reveal your reference implementation.
+
+Keep the current prompt, contract and stage stable on resume. Save clarifications, hints and reveals with their scopes. A skip must permit progress through a minimal interface assumption, with that assistance recorded. Keep every previous released prompt and candidate snapshot so later agents can reconstruct what was assessed.
+
+## Local Solvewright runtime contract
+
+When the initiating request says **live runtime**, the session working directory contains:
+
+```text
+context/interviewer/       these instructions, references and examiner tools
+history-context.json       previous Solvewright rounds and concept evidence
+session-settings.json      chosen track, budget, mode, candidate AI
+workspace/                 only candidate-visible files
+.examiner/                 private plan, reference, evaluation data, checkpoints
+```
+
+Create `.examiner/manifest.json` with `title`, `caseFamily`, `concepts` (a short string list), `mechanism`, the fixed `contract`, stage plan, and validation commands/results. Maintain it as the round evolves. For Python, put the candidate's initial implementation skeleton in `workspace/solution.py` and unittest checks in `workspace/tests/test_public.py`. **Run tests executes in the candidate's browser**, under Pyodide (CPython compiled to WebAssembly), with pytest collecting `workspace/tests/test_*.py` from the `workspace/` directory, so `import solution` works. Public tests must therefore use only the standard library, plus numpy when the task needs it; no threads, subprocesses, sockets, network, wall-clock timing or files outside `workspace/`. Verify your reference and the public tests yourself with the local Python before publishing, under the same constraints. For pseudocode, use `workspace/solution.txt`, give a precise callable/operation contract and hand-trace examples, and do not pretend executable tests have run. Additional candidate data/notes may be created there. Do not put solutions, future-stage prompts, private datasets or an answer-bearing test name in candidate files.
+
+The first turn should produce and validate the setup, then ask only the opening task. Later turns read candidate files from `workspace/` and test evidence from `.examiner/test-runs.json`. Use `.examiner/progress.json` for hints/reveals and continuity if needed. The runtime saves the chat and snapshots; do not ask the candidate to copy/import JSON.
+
+At the end write `.examiner/report.json` in the exact `interview-lab-session-v1` format from [session-format.txt](session-format.txt). Use the runtime's session ID and starting timestamp supplied in settings. Score with [scoring.txt](scoring.txt); leave unobserved dimensions null. Never fabricate elapsed active time. The runtime will save and display the report automatically.
+
+Return the runtime's required structured reply only: `message` (candidate-facing Markdown), `title`, `caseFamily`, `concepts`, `stage` (the current part's short name only), `part` (the current part's number, from 1), `parts` (how many parts the round is planned to have; the page shows the count, never the content of later parts), and `finished`. No private planning, hidden answers or tool transcripts in `message`. `finished` is true only once the report is written or the candidate explicitly ends without assessment; explain any missing report honestly. You can use file and code tools before returning this reply.
+
+This protocol is a local client integration run by the Solvewright connector, not a model API key. Your commands run inside the agent's sandbox: you can write only inside this round folder and have no network access. Do not try to work around either limit; if something you need is blocked, say so in `message`.

solvewright/interviewer/references/curriculum.txt

@@ -0,0 +1,21 @@
+# Concept map for generative interview practice
+
+Use this to plan coverage and prerequisites, not as an exhaustive question list. Every session should pick a useful subset, synthesize a new executable task, and record which concepts the candidate actually demonstrated. Add concepts when the work calls for them.
+
+| Area | Concepts and useful connections |
+| --- | --- |
+| Problem framing | objective vs proxy; online/offline observations; irrevocable decisions; operation order; scale and supported inputs; model assumptions; baseline |
+| State and ownership | invariants; state machines; pure reducers; mutable state boundaries; commands vs observations; source-of-truth data vs derived logs; transactional updates |
+| Time | event time vs processing time; windows; expiry; cancellation; renewal; tie-breaking; scheduling; logical clocks; late observations |
+| Algorithms and structures | sorting; hashing; ordered indexes; heaps; queues; trees; graph traversal; shortest paths; dependencies; dynamic programming; incremental maintenance; amortization |
+| Executable design | interfaces; minimal decomposition; composition; extension points justified by actual requirements; determinism; replay; idempotency; failure semantics |
+| Sequential decisions | reusable investment; marginal vs total benefit; sunk cost; uncertainty in future demand; buffering; cache replacement; adaptive thresholds; exploration vs exploitation |
+| Empirical optimization | inspecting distributions; visual diagnostics; policy baselines; representative traces; ablations; cost/runtime tradeoffs; multi-sample evaluation; robustness without hindsight |
+| Research validity | alignment; feature availability; leakage; train/validation/test roles; multiple comparisons; dependence; uncertainty; null results; regime shifts; reproducibility |
+| Probability and decisions | conditional expectation; variance; independence assumptions; Bayesian updates; calibration; expected utility; risk-adjusted objectives; simulation checks |
+| Trading mechanics | signed cash/inventory; spreads and fees; position/risk limits; quote/order/fill timelines; mark-to-market vs realized P&L; latency; stale information; execution assumptions |
+| Practical verification | tiny hand-traces; discriminating tests; properties/invariants; reference comparisons; counterexamples; benchmarks that match the task; regression scope |
+| Tool and AI judgment | plot before theorizing when useful; inspect generated code; verify claims; isolate test data; distinguish measured output from a guess; own the final explanation |
+| Communication and adaptation | concise contracts; defend a tradeoff; state limits; identify a changed requirement; revise only what it invalidates; prioritize a working baseline under time pressure |
+
+For each observed concept, store candidate evidence, assistance, novelty, date and related case family. A concept's absence in history means unmeasured; an algorithm appearing in a prompt does not mean the candidate can use it. Re-test important gaps through a different mechanism and infer levels conservatively using the shared rubric.

solvewright/interviewer/references/scoring.txt

@@ -0,0 +1,66 @@
+# Scoring and adaptation
+
+Examiner reference. Read before running or assessing a round.
+
+## Seven dimensions
+
+| ID | Dimension | Observable evidence |
+| --- | --- | --- |
+| clarification | Requirements | Finds consequential ambiguities; states objective, input contract and decision timing. |
+| modeling | Modeling and reasoning | Forms a useful abstraction, baseline, assumptions, cost model or statistical hypothesis. |
+| implementation | Implementation | Produces working core behavior with a coherent state model and suitable complexity. |
+| validation | Validation | Chooses discriminating tests/experiments, separates evidence from assumption, avoids temporal leakage. |
+| adaptation | Adaptation | Revises the design or hypothesis when a requirement or measured result changes. |
+| communication | Communication | Explains choices and limitations precisely, responds to objections, uses time well. |
+| tools | Tool and AI judgment | Uses data/code tools productively, inspects generated output, and owns the resulting claims. |
+
+Rubric values apply to observed work under the stated assistance:
+
+- **0:** attempted, but no usable progress or fundamentally incorrect behavior remains.
+- **1:** fragmented progress; substantial errors or heavy support remain.
+- **2:** partially correct core; material omissions, validation gaps or support needed.
+- **3:** correct, appropriately scoped core, tested or convincingly checked, with a defensible explanation.
+- **4:** strong core plus successful defense or transfer to a meaningful variation. More abstractions do not earn more points.
+- **null:** not observed. Never convert missing evidence into a failure or a success.
+
+Each observed score needs a short piece of evidence: what the candidate said, built, tested or failed. Record `assistance`: `none`, `hint`, `revealed`, or `ai`. Use the strongest assistance that materially affected the evidence for that dimension. A clarification answer about the rules is not a hint. A revealed testing syntax example need not contaminate an independently derived model; a revealed algorithm does affect implementation of that algorithm. If ambiguous, explain the uncertainty and use the more cautious assistance label.
+
+## Summary score and coverage
+
+Weights, in dimension order above:
+
+| Track | Requirements | Modeling | Code | Validation | Adaptation | Communication | Tools |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| hybrid | 15 | 20 | 20 | 15 | 15 | 10 | 5 |
+| research | 10 | 25 | 15 | 25 | 10 | 10 | 5 |
+| trading | 15 | 25 | 15 | 20 | 10 | 10 | 5 |
+| systems | 15 | 15 | 25 | 15 | 15 | 10 | 5 |
+
+For observed dimensions O, compute `round(100 * sum(weight[d] * score[d]) / (4 * sum(weight[d])))`. Coverage is `sum(weight[d] for observed d)` out of 100. With zero coverage, the score is unavailable. Always show coverage and how many observed dimensions used assistance. A drill with two observed dimensions is not equivalent to a complete mock with the same score. The app computes this score; do not encode an independent total that can disagree with it.
+
+Record whether assessment used executed tests, inspection, a hand-trace, or discussion. An excellent explanation can be observed; it is not proof that code ran. Do not award a top implementation score based only on pseudocode when executable code was required.
+
+Before claiming a missing test or an undetected regression, inspect both the provided suite and the candidate's added checks. Name the exact behavior and verify whether the existing tests already detect it. Distinguish “the candidate did not independently design this check” from “the suite does not cover it.” Do not invent a weakness just to fill a gaps section; an empty gaps list is preferable to a false criticism. A debrief observation should point to an actual response, code path, named test, or measured result.
+
+Do not define HRT or Jane Street pass marks. Do not estimate hiring probability, percentile, Elo or IQ. Rubric scores are local training feedback. Compare similar tracks, case difficulty, coverage and help conditions; use individual dimensions for broader diagnosis.
+
+## Infer a level conservatively
+
+Per dimension, consider up to the **five most recent eligible observations in the last 90 days**. Eligible means a completed or time-limited attempt, score observed, assistance `none`, and novelty `unseen` or `transfer`. A known-case replay and immediate retest of a revealed idea are learning evidence, not new independent assessment.
+
+Use the median score as the provisional level on the same 0–4 rubric. Label reliability:
+
+- no eligible observation: **not measured**;
+- one or two, or only one case family: **provisional**;
+- at least three across at least two case families: **supported by repeated practice**.
+
+This is a descriptive heuristic, not a psychometric model. Keep evidence counts and case variety visible. Old observations can remain in history while dropping out of current-level inference. Do not collapse seven dimensions into a confident global candidate level.
+
+For a next session, first target the lowest supported/provisional dimension; break ties with fewer observations, then choose a fresh case family if possible. If no dimension has eligible evidence, recommend a broad mock or a short diagnostic. If several dimensions are unmeasured, mention the assessment gap alongside the proposed weakness drill. If independent performance improved, verify it in another family before raising confidence.
+
+Suggested drills: requirements → online/offline contract; modeling → baseline and break-even; implementation → small state machine; validation → adversarial trace/temporal split; adaptation → one new requirement; communication → explain and defend a minimal design; tools → inspect a plot or audit an AI patch. A drill must still produce observable work, not just a lecture.
+
+## Verdict
+
+End every scored report with a `verdict`: one plain line against the bar for this round's track and difficulty, for example "Below the bar for a standard mock" or "Meets the bar for a foundation drill", and `meetsBar` true or false. Use `null` for `meetsBar` only when coverage is too low to say, and say so in the label. Be as strict as a real interviewer: a working core reached only after a reveal does not meet the bar, and generous marks for unobserved work are not allowed. Write the label from the marks you gave, never the reverse.
+

solvewright/interviewer/references/session-format.txt

@@ -0,0 +1,60 @@
+# Portable session record
+
+Use one JSON object per attempt. A history backup wraps attempts in `{"format":"interview-lab-history-v1","sessions":[...]}`. A single attempt has `format: "interview-lab-session-v1"`. The Solvewright page accepts either. No transcript or code is required in the record; keep evidence compact and omit personal details unrelated to training.
+
+## Example shape (illustrative; never seed as real history)
+
+```json
+{
+  "format": "interview-lab-session-v1",
+  "id": "2026-11-10T18-30-00Z-automation-a7f2",
+  "at": "2026-11-10T18:30:00Z",
+  "caseId": "automation",
+  "caseFamily": "event-systems",
+  "title": "Motion timeout simulation",
+  "track": "systems",
+  "mode": "mock",
+  "difficulty": "standard",
+  "novelty": "transfer",
+  "plannedMinutes": 50,
+  "actualMinutes": null,
+  "status": "time-limited",
+  "verification": "executed",
+  "dimensions": {
+    "clarification": {"score": 3, "assistance": "none", "evidence": "Clarified event order and equal-time semantics before coding."},
+    "modeling": {"score": 3, "assistance": "none", "evidence": "Separated sensor observations from device transitions."},
+    "implementation": {"score": 2, "assistance": "hint", "evidence": "Core behavior worked after a hint about repeated motion."},
+    "validation": {"score": 2, "assistance": "none", "evidence": "Tested renewal; omitted a jump beyond the deadline."},
+    "adaptation": {"score": null, "assistance": "none", "evidence": "Conflict extension not reached."},
+    "communication": {"score": 3, "assistance": "none", "evidence": "Explained the state ownership and acknowledged test limits."},
+    "tools": {"score": null, "assistance": "none", "evidence": "Not assessed separately."}
+  },
+  "hints": [{"stage": "timeout", "level": 2, "summary": "Trace a second motion event while the light is on."}],
+  "reveals": [],
+  "skips": ["conflicts"],
+  "strengths": ["Clarified the time contract early."],
+  "gaps": ["Needs a test for crossing a deadline without a new event."],
+  "nextDrill": "15-minute delayed-action drill on a fresh rate-limiter case.",
+  "notes": "Time was not measured; actualMinutes is null.",
+  "verdict": {"label": "Below the bar for a standard mock", "meetsBar": false}
+}
+```
+
+## Constraints
+
+- `id`: a unique stable attempt identifier, 1–160 characters. Keep the same ID if exporting an existing attempt again. Use a timestamp plus a random suffix for a new attempt.
+- `at`: ISO-8601 timestamp with an explicit timezone. Use the actual session date. Do not fabricate elapsed time from it.
+- `caseId`, `caseFamily`, `title`: nonempty strings. Families describe the underlying mechanism, not a firm's name. New generated variants can use new IDs and an existing family.
+- `track`: `hybrid`, `research`, `trading`, `systems`.
+- `mode`: `mock`, `coached`, `drill`.
+- `difficulty`: `foundation`, `standard`, `stretch`.
+- `novelty`: `unseen`, `seen`, `transfer`. Use `seen` for the same problem after its solution was exposed; `transfer` requires materially different demands, not renamed variables.
+- `plannedMinutes`: positive number up to 240. For untimed coaching use the intended block length and explain timing in notes; `actualMinutes` may be `null`, otherwise 0–1440.
+- `status`: `completed`, `time-limited`, `stopped`.
+- `verification`: `executed`, `inspection`, `hand-trace`, `discussion`, `mixed`. “Executed” means relevant candidate code/tests really ran; evidence states which.
+- `dimensions`: all seven keys from scoring.txt. Scores are integers 0–4 or `null`; `assistance` uses the four listed values; `evidence` explains the judgment. Never leave observed evidence blank.
+- `hints`: objects containing `stage`, integer `level` 1–4, and `summary`. Revealed code goes under `reveals`, a string list of affected parts. `skips` is also a string list.
+- `verdict`: `{"label": string up to 160 characters, "meetsBar": true | false | null}`, as scoring.txt describes.
+- `strengths`, `gaps`: short string lists, ideally no more than two of each. `nextDrill` and `notes` are strings. Optional algorithm metrics can be described in notes; don't mix them into rubric scores.
+
+History import should validate the complete payload before merging. New IDs append. Reimporting identical records is a no-op. Conflicting content under an existing ID must be reported rather than silently overwriting evidence. The candidate can explicitly remove a record and import its correction. Keep history exports compatible with this format; do not include authentication identifiers.

solvewright/interviewer/tools/portal_lab.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Synthetic portal exercise infrastructure. Examiner source contains data spoilers."""
+
+import argparse
+import heapq
+import json
+import math
+import random
+import selectors
+import subprocess
+import sys
+from pathlib import Path
+
+
+def point(value):
+    if not isinstance(value, (list, tuple)) or len(value) != 2:
+        raise ValueError("A point must contain two finite numbers.")
+    if any(isinstance(x, bool) or not isinstance(x, (int, float)) or not math.isfinite(x) or abs(x) > 1e6 for x in value):
+        raise ValueError("Coordinates must be finite numbers within +/-1,000,000.")
+    return tuple(float(x) for x in value)
+
+
+def distance(a, b):
+    return math.hypot(a[0] - b[0], a[1] - b[1])
+
+
+def route_distance(origin, destination, portals):
+    """Exact shortest route: complete Euclidean walking graph + free portal edges."""
+    nodes = [point(origin), point(destination)]
+    mates = {}
+    for portal in portals:
+        i = len(nodes)
+        nodes.extend([point(portal["a"]), point(portal["b"])])
+        mates[i], mates[i + 1] = i + 1, i
+    best = [math.inf] * len(nodes)
+    best[0] = 0.0
+    queue = [(0.0, 0)]
+    while queue:
+        cost, node = heapq.heappop(queue)
+        if cost != best[node]:
+            continue
+        if node == 1:
+            return cost
+        for other, location in enumerate(nodes):
+            step = 0.0 if mates.get(node) == other else distance(nodes[node], location)
+            candidate = cost + step
+            if candidate < best[other]:
+                best[other] = candidate
+                heapq.heappush(queue, (candidate, other))
+    raise RuntimeError("Walking always provides a route.")
+
+
+def episode(seed, count=96):
+    rng = random.Random(seed)
+    angle = rng.uniform(0, 2 * math.pi)
+    length = rng.uniform(35, 65)
+    offset = (length * math.cos(angle), length * math.sin(angle))
+    x, y = rng.uniform(-20, 20), rng.uniform(-20, 20)
+    arrivals = []
+    for _ in range(count):
+        x += rng.gauss(0.45 * math.cos(angle + 0.8), 1.8)
+        y += rng.gauss(0.45 * math.sin(angle + 0.8), 1.8)
+        origin = [round(x, 5), round(y, 5)]
+        destination = [round(x + offset[0] + rng.gauss(0, 2), 5), round(y + offset[1] + rng.gauss(0, 2), 5)]
+        arrivals.append({"origin": origin, "destination": destination})
+    return {"format": "portal-episode-v1", "synthetic": True, "seed": seed, "arrivals": arrivals}
+
+
+def load_episode(path):
+    data = json.loads(Path(path).read_text())
+    if data.get("format") != "portal-episode-v1" or not data.get("arrivals"):
+        raise ValueError("Expected a nonempty portal-episode-v1 file.")
+    for row in data["arrivals"]:
+        point(row["origin"])
+        point(row["destination"])
+    return data
+
+
+class Scorer:
+    def __init__(self):
+        self.portals = []
+        self.construction = 0.0
+        self.travel = 0.0
+        self.baseline = 0.0
+
+    def apply(self, arrival, builds):
+        if not isinstance(builds, list) or len(self.portals) + len(builds) > 24:
+            raise ValueError("build must be a list; at most 24 portals per episode.")
+        checked = [{"a": list(point(p["a"])), "b": list(point(p["b"]))} for p in builds]
+        self.construction += sum(5 * distance(p["a"], p["b"]) for p in checked)
+        self.portals.extend(checked)
+        self.travel += route_distance(arrival["origin"], arrival["destination"], self.portals)
+        self.baseline += distance(arrival["origin"], arrival["destination"])
+
+    def result(self):
+        total = self.construction + self.travel
+        return {"construction": self.construction, "travel": self.travel, "total": total,
+                "no_portal": self.baseline, "portals": len(self.portals),
+                "savings_percent": 100 * (1 - total / self.baseline) if self.baseline else None}
+
+
+def score(data, plan):
+    steps = {}
+    for build in plan:
+        index = build["step"]
+        if isinstance(index, bool) or not isinstance(index, int) or not 0 <= index < len(data["arrivals"]):
+            raise ValueError("A plan step must name an arrival index in this episode.")
+        steps.setdefault(index, []).append(build)
+    scorer = Scorer()
+    for index, arrival in enumerate(data["arrivals"]):
+        scorer.apply(arrival, steps.get(index, []))
+    return scorer.result()
+
+
+def run_policy(data, path):
+    """Prefix-only stdin protocol, not a filesystem/network security sandbox."""
+    process = subprocess.Popen([sys.executable, str(Path(path).resolve())], stdin=subprocess.PIPE,
+                               stdout=subprocess.PIPE, stderr=None, bufsize=0)
+    selector = selectors.DefaultSelector()
+    selector.register(process.stdout, selectors.EVENT_READ)
+    buffer = b""
+    scorer = Scorer()
+    try:
+        for index, arrival in enumerate(data["arrivals"]):
+            request = {"step": index, "horizon": len(data["arrivals"]), **arrival, "portals": scorer.portals}
+            process.stdin.write((json.dumps(request) + "\n").encode())
+            process.stdin.flush()
+            import time
+            deadline = time.monotonic() + 10
+            while b"\n" not in buffer:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0 or not selector.select(remaining):
+                    raise ValueError(f"Policy timed out at step {index}.")
+                chunk = process.stdout.read(65536)
+                if not chunk:
+                    raise ValueError(f"Policy exited without a response at step {index}.")
+                buffer += chunk
+                if len(buffer) > 100000:
+                    raise ValueError("Policy response is too large.")
+            line, buffer = buffer.split(b"\n", 1)
+            response = json.loads(line)
+            if not isinstance(response, dict) or set(response) != {"build"}:
+                raise ValueError("Each policy response must be an object with only a build list.")
+            scorer.apply(arrival, response["build"])
+        return scorer.result()
+    finally:
+        selector.close()
+        if process.stdin:
+            process.stdin.close()
+        if process.poll() is None:
+            process.terminate()
+        try:
+            process.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait()
+        process.stdout.close()
+
+
+def self_test():
+    assert route_distance([0, 0], [3, 4], []) == 5
+    portal = {"a": [0, 0], "b": [10, 0]}
+    assert route_distance([10, 0], [0, 0], [portal]) == 0  # bidirectional
+    chain = [portal, {"a": [10, 0], "b": [20, 0]}]
+    assert route_distance([0, 0], [20, 0], chain) == 0  # two portals required
+    assert route_distance([0, 0], [0, 2], [portal]) == 2  # walking remains available
+    data = {"arrivals": [{"origin": [0, 0], "destination": [10, 0]}] * 6}
+    early = score(data, [{"step": 0, **portal}])
+    late = score(data, [{"step": 5, **portal}])
+    assert early["construction"] == 50 and early["travel"] == 0 and early["total"] == 50
+    assert late["total"] == 100 and late["travel"] == 50  # no retrospective saving
+    assert score(data, [])["total"] == 60
+    assert episode(42) == episode(42)
+    print("Portal checks passed: walking, both directions, chaining, accounting, timing, repeatability.")
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("self-test")
+    samples = sub.add_parser("samples")
+    samples.add_argument("--out", required=True)
+    generate = sub.add_parser("generate")
+    generate.add_argument("--seed", type=int, required=True)
+    generate.add_argument("--out", required=True)
+    for command in ("score", "run"):
+        p = sub.add_parser(command)
+        p.add_argument("--episode", required=True)
+        if command == "score":
+            p.add_argument("--plan")
+        else:
+            p.add_argument("--policy", required=True)
+    args = parser.parse_args()
+    if args.command == "self-test":
+        self_test()
+    elif args.command == "samples":
+        destination = Path(args.out)
+        destination.mkdir(parents=True, exist_ok=True)
+        for index in range(1, 9):
+            (destination / f"sample-{index:02d}.json").write_text(json.dumps(episode(2000 + index), indent=2) + "\n")
+        print(f"Wrote eight synthetic episodes to {destination}.")
+    elif args.command == "generate":
+        Path(args.out).write_text(json.dumps(episode(args.seed), indent=2) + "\n")
+        print(f"Wrote synthetic episode to {args.out}.")
+    elif args.command == "score":
+        plan = json.loads(Path(args.plan).read_text()) if args.plan else []
+        print(json.dumps(score(load_episode(args.episode), plan), indent=2))
+    elif args.command == "run":
+        print(json.dumps(run_policy(load_episode(args.episode), args.policy), indent=2))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (ValueError, KeyError, TypeError, OSError, json.JSONDecodeError) as exc:
+        print(f"Portal evaluation failed: {exc}", file=sys.stderr)
+        sys.exit(1)