The Boundary That Keeps Science in the Task
Praxist's central architectural question is not how to divide software into neat modules, but how to keep a research problem's meaning attached to the project that owns it. This chapter examines the handoff between an existing runnable project and Praxist's generic machinery, so a reader can judge whether a project is ready, what the one-unit canary establishes, and how frozen configuration makes the handoff auditable.
Takeover begins with a runnable scientific object
Praxist does not start with a blank prompt and promise to manufacture a research environment around it. It takes over an existing project that already has a baseline implementation, a normal way to run it, and the local assets needed to execute that path. The framework can orchestrate an investigation, but it cannot supply the thing being investigated.
Readiness has six connected conditions. The research code and its ordinary entrypoint must be present. An interpreter, container, or remote environment must be available and able to import the required dependencies. The required data or simulator must be reachable through the project's normal interface. The baseline must run without Praxist. At least one metric must distinguish better from worse and declare its direction. Finally, the scientific constraints must be expressible: what may change, what must stay fixed, and which trade-offs make a candidate invalid.
These conditions form a dependency chain rather than a checklist of independent conveniences. A metric is not useful if the evaluator cannot run. An evaluator is not comparable if the baseline is unknown. A baseline is not a meaningful reference if the data or simulator changes between candidates. And a high score is not necessarily progress if the candidate achieved it by violating a constraint that defines the task.
That is why takeover begins with a research brief. The brief identifies the objective, the evidence standard, the allowed environment and resources, the desired exploration policy, and the practical number of peers or generations. It gives the framework the information needed to build a task contract without smuggling scientific decisions into generic code. The project remains the authority on what its metric means and which protocol is credible.
The resulting task project is a compact boundary around the existing work. It normally describes the task identity and workflow, keeps roles and audit rules local, exposes evaluation through a public entrypoint, and places harness assets, baseline records, fixtures, and literature packs where the task can own them. This arrangement is more than organization. It lets the same Praxist runtime coordinate unrelated projects without treating one project's evaluator, data split, or notion of success as a universal default.
The canary proves a connection, not a discovery
Before expensive parallel execution, Praxist asks the task's public evaluator to complete a one-unit canary. “One unit” is task-defined: it might be the smallest valid case, scenario, fold, or simulation run for that project. It is not a framework-wide rule such as one epoch or one random seed.
The canary exercises the actual boundary that later work will use. The evaluator must launch under the intended runtime, accept the public command or function contract, write a structured result summary, and let that summary project into a finding. When Praxist owns process launch, the central scheduler is part of this check as well. If the implementation or command changes, the canary must be run again because the earlier proof applies only to the earlier boundary.
A successful canary answers a narrow operational question: can this task produce a result in the form the research loop can ingest? It does not answer whether the evaluator measures the intended phenomenon. It does not establish performance, mature evidence, generalization, or even a promising scientific direction. A weak score can be a valid canary; a strong score can still be scientifically misleading. Keeping those claims separate is one of the first signs that the task boundary is working.
The same distinction explains why takeover may stop. If the data is missing, Praxist does not silently acquire an unspecified replacement. If the simulator is absent, it does not invent a substitute. If the baseline has not been measured, it does not fabricate a plausible value. When all required assets are already present, an operator can authorize a bounded baseline measurement and record its provenance. Otherwise, the missing prerequisite remains a decision for the task owner rather than a problem the framework is allowed to conceal.
A public evaluator also gives the boundary a stable shape. Task-specific training, simulation, or benchmark helpers may change internally, but peers should call the one documented evaluation entrypoint. That entrypoint resolves task-owned paths relative to the task root and must work both from the project root and from a run-like working directory. This prevents a command from passing only because it accidentally found files in the operator's current shell. The evaluator owns the raw benchmark output and the compact summary; Praxist consumes the summary and builds its own canonical views. Keeping those responsibilities separate makes it possible to improve the harness without changing the framework's lifecycle contract.
This is also why generated output belongs outside the product source. Long-run variants, logs, findings, and reports are evidence about one task execution, not part of the framework's reusable implementation. If they were written into the framework checkout, a later run could mistake historical output for current source, or a task could contaminate another task's state. An external, task-local run directory lets the system preserve history while keeping the selected project and the Praxist installation independently maintainable.
Four owners make the system reusable
Once the project is ready, the architecture divides responsibility among four owners. The task project owns the scientific objective, baseline, evaluator, metrics, evidence policy, prompts, roles, assets, and constraints. Praxist core owns stable protocols, task and plugin resolution, canonical storage, replay, credentials, budgets, and extension interfaces. Generic plugins provide replaceable runtimes, API providers, workflow stages, tools, graph maintenance, panel topologies, and budget policies. The run directory owns the frozen configuration, artifacts, evidence, and lifecycle records for one execution.
The boundary is easiest to understand by asking what crosses it. The task sends a scientific contract into Praxist: what should be optimized, how it is measured, and what is forbidden. Praxist sends execution context back: which peer or planner is running, what role and tools are available, which model profile was selected, which budget applies, and where the run may write. The evaluator sends structured results into the run. The framework can then organize those results without rewriting their domain meaning.
This model also explains what core must not do. It must not contain benchmark-specific prompts, roles, evaluations, or task facts. It must not call a particular agent SDK directly or make provider-specific API calls directly. Those behaviors belong behind runtime, provider, or workflow interfaces. A component is genuinely generic only if unrelated task projects can use it without importing another task's private assumptions.
That rule has a practical consequence for customization. A task may carry task-local roles, audits, evaluations, and even a generic plugin under its own plugin root. Those components are discovered only when the operator explicitly selects that task. A task-specific role therefore cannot silently become a system-wide role, and a private evaluator cannot become a global definition of success.
Explicit selection is part of trust
Praxist requires an explicit task path at startup. The framework does not scan a broad filesystem and guess which research project should be run. This is a small interface choice with a large safety effect: it makes project identity part of the launch decision and gives the run a concrete source to fingerprint.
Plugin selection follows a similar pattern. A manifest describes a plugin's kind, version, compatibility, capabilities, entrypoint, dependencies, and the code or assets included in its content hash. Resolution discovers candidates from explicit sources, selects according to source priority and constraints, resolves dependencies, and records the selected descriptors, shadowed candidates, dependency edges, and hashes in the run. Executable resolution can restrict selection to trusted bundled or task-project sources.
“Stability” in a plugin manifest should not be confused with trust. Stability describes the interface promise: schema shape, prompt contract, or compatibility expected by callers. Trust comes from where executable code is allowed to come from. This distinction matters in systems that support extensions. A plugin can be experimental while still being intentionally scoped to one selected task, and a stable interface can still require an execution-source decision.
The manifests are therefore not just packaging metadata. They answer questions that arise after a run: which implementation was selected, what dependencies did it bring, and has the selected code drifted since the run was created? They make replacement possible without making replacement invisible.
Freeze choices before the work becomes complicated
At the command boundary, Praxist is designed to resolve operator intent once and pass explicit configuration downstream. The documented precedence is explicit command-line arguments, explicit environment values, an override specification, and task defaults. After normalization, core and plugin code should receive a frozen run configuration or a narrower request object instead of reconstructing the provider, model, task, runtime, or credential choice from strings later in the call graph.
The value of freezing is easiest to see in a long run. Suppose the operator starts a task with one model profile, one evaluator path, and one run directory, then changes the shell environment before a later generation. If the later generation silently rereads the shell, the run no longer has one coherent explanation. A persisted startup configuration lets replay and diagnostics answer which non-secret values were actually selected, independent of the state of the launching terminal.
The task itself has a related manifest. Praxist fingerprints the descriptor and relevant project files while excluding generated run trees and refusing to include symlink targets that escape the task root. The run can then identify the external project it used without treating its generated outputs as a new task definition. The result is a boundary between mutable source and immutable run history: the task may evolve for a future run, but an old run retains the contract it resolved.
This design is an architectural direction as well as a current implementation. The repository's configuration module explicitly notes that the migration away from ambient environment reads is not complete; core-adjacent paths still contain compatibility reads. That qualification matters. It is accurate to say that frozen explicit configuration is the intended control-plane contract and that important paths implement it. It would be inaccurate to claim that every current code path is already free of environment-dependent behavior.
The same restraint applies to replay. A hash can show that a selected file or manifest is the same as before. It cannot show that the evaluator's scientific assumptions were correct. A task-project boundary can prevent accidental cross-task state. It cannot decide whether the task owner chose a meaningful metric. Architecture narrows hidden coupling; it does not abolish judgment.
The handoff that makes a generation possible
A defensible handoff ends when three things are simultaneously clear: the project can execute its unchanged baseline, the task contract defines what counts as a credible result, and the run has a frozen record of the choices that will shape execution. Only then can Praxist's peer cohort do more than produce independent code edits. It can create comparable work whose provenance remains attached to the task that gives the measurements meaning.
The next step is temporal rather than structural. Once ownership and configuration are fixed, the important question becomes how those contracts move through a generation: what peers inherit, what they change, how the evaluator turns changes into results, and which boundary makes the resulting evidence available for the next agenda.