Skip to content

Latest commit

 

History

History
111 lines (93 loc) · 6.88 KB

BUILDER_GUIDE.md

File metadata and controls

111 lines (93 loc) · 6.88 KB

HashSmash builder guide

Read this document when the user assigns harness maintenance, documentation, target definitions, tests, judge configuration, workflows, deployment, or organizer baseline preparation. Ranked Yukon solvers start at TASK.md. Builder work does not grant an unassigned candidate directory to edit.

For this repository's four-family Pareto challenge, read pareto/README.md and Pareto production setup; its import root is pareto. The fixed-round catalog, root-import and migration instructions below describe the retained scalar harness. Keep that implementation and its root manifest in place for the Pareto adapter, without importing it as this challenge.

Context and ownership

The frontier guide retains 26 runnable local tracks, including four historical SHA-256 31/32 lanes, and four deferred Poseidon slots. The manifest retains eight exploratory registrations: six intended competing tracks (SHA-256 37/38, SHA3-256 5/6 and BLAKE3 1/2) and two SHA-256 31/32 tracks to close while preserving public history. New SHA-256 rounds have exploratory lanes only. Two exploratory Poseidon targets remain deferred pending definition. The SHA-1 pilot and nine unpaired local tracks are retired. Preserve the single repository-root schema-v2 manifest, lane-suffixed public track IDs, and independent candidate, score, and report paths. Lane metadata is bound by the protected registry, claim validation, review fingerprints, and score metrics.lane.

SHA-256 37/38, BLAKE3 1/2 and Keccak[800] 5/6 are organizer-selected exploration pairs, not assertions of a first-unbroken boundary. Keep the four Poseidon slots deferred until their exact definition is assigned. Never emit placeholder scores. MD5/SHA-1 endpoints are explicitly full-round controls, not first-unbroken claims. Follow the frontier guide and research context for target-definition work.

Use these guides for the assigned subsystem:

Work Required context
Target/claim/certificate verification and score construction Verifier, claim schema, cost model, and the selected target profile
Judge providers, roles, or qualification Judge implementation and review policy
Candidate experiments Experiment protocol
Yukon App, imports, Actions, baseline validation, or promotion checks Dev operator runbook
Organizer baseline packages and local live review Baseline qualification
Solver onboarding and UI entry references TASK.md; the Yukon CLI skill owns generic CLI behavior

Boundaries that harness changes must preserve

  • Treat every lanes/<lane>/candidates/<target>/ directory as hostile participant input. Never execute participant commands on the host or in a credential-bearing job. Only the organizer's bounded, networkless Docker executor may run immutable validated participant Python. Keep deterministic intake/experiments, credentialed review, and final scoring separated as in the paired workflow.
  • Never print, commit, copy, or upload .env. The expected provider secrets are OPENROUTER_API_KEY and AWS_BEARER_TOKEN_BEDROCK. Keep submission notes and research discussions free of secrets, private paths, and unrelated session data.
  • Keep profiles, cost models, schemas, verifier code, judge prompts, workflows, registry, and lanes/<lane>/.yukon/scores/ outside all candidate trees. Preserve exact input/configuration/dossier binding and the manifest-relative artifact path.
  • Preserve paired-lanes-v1: exploratory pass is plausible_not_refuted; rigorous pass is ai_rigor_qualified. Neither is mathematical proof or human acceptance. Heuristics require explicit scope, evidence, and review. Model confidence is not algorithmic success probability; scalar improvement is not Pareto dominance.
  • Nominal references are not established collision constructions, qualified baselines, or security bounds. Drafts never reach the judge or emit scores. Never bypass those gates or reinterpret historical artifacts under a new policy.
  • Use --track explicitly for pipeline and verifier commands. Preserve independent output paths and fingerprints; never repurpose an old score for another track.

Verification and landing changes

Use Python's standard library unless a dependency is explicitly justified and pinned. Offline tests must use organizer fixtures rather than mutable solver candidates. Run checks appropriate to the change; run the deterministic unit suite before any live OpenRouter or Amazon Bedrock integration test:

bash .yukon/setup.sh
python3 scripts/validate_frontier_config.py

Documentation changes should check links and keep runtime policy/contract files intact. For judge or verifier changes, verify relevant failure gates and provenance binding as well as successful results. Live testing follows the user's authorized scope and the operator runbook; offline fixture results do not establish a live Yukon import or cryptanalytic qualification.

Land harness changes through a feature branch and human-reviewed PR. Label a PR yukon-unsafe when it invalidates pending scores; regenerate evidence/review/score artifacts as appropriate. Do not label unrelated documentation changes unsafe. Never manually merge Yukon submission PRs; Yukon promotes only its scored content.

Baseline authoring and local review

Organizer baseline authoring is an explicit builder assignment for a fresh import. Follow CANDIDATE_QUALIFICATION.md, with an assigned candidate directory and its tracks/<track>/TASK.md. Its feature-branch/PR handoff and live-review steps do not replace the ranked solver submission workflow.

Local live review requires a trusted operator and separately provisioned provider access. Follow that guide's credential-free intake/experiment phase, separate credentialed judge phase, and deterministic score phase. A Yukon API key does not provide local judge access. A local score does not replace Yukon's validation of the exact imported or submitted content.

For deployment, use the production runbook, dev runbook, and round migration handoff. Keep one repository-root import. Reconcile the eight-track manifest by retaining the existing six records and adding two; archive none. Close SHA-256 r31/r32 through Yukon and preserve their jobs, reviews and results. Shared registry/schema/cost changes invalidate every existing lane's configuration hash; label the harness PR yukon-unsafe and use the guarded all-track refresh before restoring admission. Undefined Poseidon slots remain inactive.