Status: Proposed. See README.md for repository-wide status and dependencies.
This file is the design overview: D001–D019, the boundary and port model, and where each normative decision lives. Where D023 and this file differ, p0a-contract-errata.md wins. Machine fields are authoritative in schemas/contract-v1.schema.json; this prose cannot widen or narrow them.
| File | Covers |
|---|---|
current-design.md |
this overview; D001, D003–D006, D010, D011; pointers to D002, D007–D009, D012–D019 |
schema-and-semantics.md |
D002/D017: canonical inferrsi-json-v1 encoding, identity projections, V01–V35 |
isolation-errors-and-cli.md |
D020 Knowledge split, D021 storage routing/errors, D022 Apps request/result matrix |
p0a-contract-errata.md |
P0a errata: prepare closure bytes, frozen code digest, deliver-then-seal context, claim-key order, CLI attempt save/replay; T36–T40 |
gate-policy-runstore-and-first-prs.md |
D009/D018 first-wave gate policy, D012-r2 RunStore, D019 first PRs |
function-owners.md |
D008 function ownership for the audited mixed modules |
acceptance-criteria.md |
T01–T40 unique outcomes |
figures.md |
the eight figures |
schemas/contract-v1.schema.json |
Draft 2020-12 definition library, 106 named $defs |
schemas/INDEX.json, dto-field-index.md |
machine-derived indexes; the schema wins on conflict |
fixtures/README.md |
historic baseline bytes vs current D023 vectors |
README.md |
index and status |
Historical candidate text, review dispositions, and the earlier Proposed drafts are evidence only. They are not a second live rule set. The 993-path inventory is path evidence, not a function-level audit, and does not itself authorize any first-wave change.
Decision: keep Knowledge, Harness, and Benchmark as sibling independent cores; Apps is the only assembler. Each core owns its types. Cross-boundary traffic uses versioned JSON envelopes with explicit conversion; there is no shared business contracts package. The technical-only inferrsi.contracts package re-exports only RunSpec, defined once in contracts/runspec.py; contracts/claim.py owns the same Verdict enum re-exported by Harness. These are not shared business DTOs. The old root contracts.py, runspec.py, claim.py, and _json_v1.py files are retired without forwarding shells, and so are the old root _repo_pack_data.py and evidence_paths.py. R1 (#412) retired eleven more root modules the same way: the seven Knowledge compatibility shells, the three old-run forwarders evaluation.py, execution.py and reporting.py, and root inspection.py, whose host binding is now inferrsi.apps.inspection over the facts API in inferrsi.apps.host.inspection. CHANGELOG.md maps every retired path to its replacement and states the import and pickle impact.
Permitted shared technical leaves are only:
inferrsi.contracts.json_v1— the canonical encoder (D002);inferrsi.contracts.runspecandinferrsi.contracts.claim— the existing RunSpec and Verdict technical types, with only RunSpec re-exported by the package initializer;inferrsi.contracts.evidence— the existing evidence segment names and pure path rules; it reads and writes no filesystem state and is not re-exported by the package initializer;inferrsi.resources.repository_packs— the neutral raw pack-data reader and the existing static data enumeration (D020), formerly rootinferrsi._repo_pack_data. Its parent initializerresources/__init__.pyimports nothing. Outside Knowledge it has one permanent importer,inferrsi.apps.host.inspection, which binds onlyrepository_pack; that exact rule is not a compatibility pair. A1 (#408) removed the separate temporary entry for rootarguments.py: the moved parserinferrsi.apps.cli.argumentsreads the sameREPO_TYPESobject throughinferrsi.knowledge.catalogand does not import the leaf.
The neutral leaf carries no target selection, task, scoring, scheduling, or public business DTO, and imports none of K/H/B/Apps. It still finds the Harness-owned pack.json through files("inferrsi").joinpath("harness", "data", "repo_packs", ...), so reading it never imports Harness. Creating the evidence directories is host I/O and stays in Apps, in inferrsi.apps.storage.evidence_layout; that module is not a shared leaf. The list is exact: a contracts. or resources. prefix admits no other module.
Why: this matches the accepted A–D direction and removes the reverse dependency that a shared DTO package creates. Rejected: a shared business DTO package; Apps owning scoring/sampling/budget algorithms; creating empty packages to declare migration done.
Acceptance: no core's public surface exposes another core's Python class; the transitive dependency graph of a core has no back edge to another core or to Apps; installing the ordinary distribution allows querying K without loading device or agent capability. Repository review is still required; delegation does not auto-approve.
Decision: C2-A. A legal fixed snapshot may be explicitly assessed offline once top-level identity and version checks pass; phase is not used as a blanket rejection. Synchronous admission refusal, re-entry anomalies, and pending-recovery states still stop automatic progression. Only historically existing committed revisions qualify; no checkpoint/submit API is added and no phase is required to commit.
A completed-measurement claim must satisfy the completion/sample/cleanup requirements frozen at prepare. not_started and legacy running are not successful measurements. Independent format/correctness claims may FAIL on trustworthy error proof. Missing or conflicting evidence without a task-specific rule makes that claim INCONCLUSIVE. Transient observations and uncommitted partial facts cannot enter a fixed determination. Unknown cleanup cannot override an independently proven candidate error.
Why: the fact axis and the judgment axis are independent. Rejected: rejecting every phase != finished; finished meaning automatic PASS; the UI inferring evidence that was never captured.
Acceptance: T04–T07, T11, T23; cross-process offline assess performs no subprocess, network, or device call.
Decision: results are stored by (claim_id, validation_scope); different scopes do not overwrite each other. Without a frozen aggregation protocol there is no overall verdict; the CLI summarizes only the primary scope the request explicitly names. Scope matching uses the exact canonical identifier/encoding given by B's public protocol. Containment, equivalence, and mapping come only from B's public rule; Apps never derives them.
A same-claim/same-scope conflict defaults to INCONCLUSIVE; last-write-wins is not used. Any rule allowing independent error proof must be frozen before prepare. When a strong independent FAIL coexists with other missing items, the claim's frozen rule decides; Apps does not invent a priority. Legacy run v0 aggregate behavior is preserved as a separate versioned legacy protocol (D009) and is not presented as the new overall result.
Acceptance: T02, T08–T10; an error in one scope must not change another. Rejected: "overall failure covers all scopes"; Apps treating "format passed" as correctness or measurement passed.
Decision: B owns the fixed worker recipe/entry revision, roles, sampling (AB/BA), repetition, timing, and aggregation; prepare/assess never start a worker. H schedules the outer declared steps and owns lifecycle, deadlines, capability, budget, and cleanup; the optimization loop and stop rules stay in H. Apps maps roles, fields, and versions verbatim and builds no second loop or retry policy.
The recipe participates in prepared_id and is archived immutably. Fixed resources required by execute map, by frozen role and artifact sha/size/media, to ExecutionSpec.InputSpec and the actual BoundInput; a same-named caller input cannot override or rebind them. H verifies only fixed identity and actual bytes and does not interpret task scoring; B re-checks that the evidence used in the run belongs to that frozen resource closure. materialized_path remains an explicit spec field, and relocating a path is not a modification criterion. Protocol, task assets, and the resources required for offline assess form the closure by fixed role/hash/size/format. Supported externally installed code binds by fixed version/capability; the interpreter is not archived wholesale and arbitrary archived modules or pickles are not executed, and missing pieces are not fetched from "latest".
Outcomes: missing capability for execution → not_started; unsupported assessor version → explicit refusal; missing single item inside an otherwise correct combination → the affected claim has missing evidence.
Acceptance: T15–T17, T21; relocating resources does not change logical roles or pins. Rejected: recipe as a mutable side attachment; H importing B to find its worker; Apps doing its own sampling.
Decision: keep the v0.3 unique-return table, completed here for the prose and figures.
| Input situation | Unique public result | Start / new Ref |
|---|---|---|
| schema/path invalid and not registered | InvalidExecutionSpec with field errors |
no start; no started record fabricated |
| first legal request, registration fails | ExecutionPersistenceError(started=false, partial_record=null) |
no start; no new RecordRef |
same request_id, different request_digest |
RequestConflict; original request preserved |
no start; no overwrite |
same request, old record finished |
the original fixed record | no rerun; no new run |
| same request, owner lock valid and executing | AttemptInProgress(attempt_id, latest_record_ref if any) |
short-circuit before any new binding/start; no wait |
same request, non-terminal registration but owner lock free/state unknown, or recovery_required |
RecoveryRequired(attempt_id, latest_record_ref if any) |
no takeover; no rerun |
| registered budget/resource/capability refusal | must submit not_started with reason; on success return the fixed RecordRef |
no start; on failed submission no valid new Ref |
| actual candidate identity check fails | after binding actual bytes, before start, as above; carries the failure fact | declared value is not treated as a captured value |
| execution ended but external resource/cleanup unconfirmed | fixed record with phase=recovery_required / truthful cleanup |
not a re-entry anomaly; not disguised as finished |
| submission fails after start | ExecutionPersistenceError(started=true, partial_record, retained_refs); best-effort cleanup |
no valid new Ref; an old Ref proves only its own revision |
| top-level prepared/record/attempt/operation/scope mismatch | refuse the handoff; no EvaluationResult/AssessmentRef for this call | diagnosis allowed; must not impersonate a judgment |
| single item inside a correct combination corrupt/foreign/missing | mark invalid/missing; B judges by the frozen claim rule | does not turn the whole correct record into "wrong record" |
| B has a result but assessment archiving fails | result and save failure reported separately; no new AssessmentRef | original RecordRef retained for explicit re-assessment |
For a registered admission or actual-identity refusal that never acquired a cleanable resource, the record encoding is fixed: phase=finished, process_outcome=not_started, started=false, cleanup=not_needed. If a lease was acquired, cleanup must be truthful: confirmed once confirmed; otherwise phase=recovery_required, not a falsified not_needed.
Phases: registered → preparing → running → stopping/finalizing → finished or recovery_required. registered does not mean budget was admitted. process_outcome is independent: not_started/exited/timed_out/cancelled/execution_error. Cleanup is independent: not_needed/confirmed/failed/unknown; finished is not allowed while an external process or lease is unconfirmed. Checks not performed are explicitly not_performed; no false positive facts are backfilled.
Recovery only verifies state, supplements submission, or confirms termination/cleanup under existing authorization; it never executes the candidate. Explicit rerun creates a new attempt with retry lineage, still under the original budget scope and deadline. The first phase introduces no cross-process cancel, daemon, or automatic takeover.
Acceptance: T01–T14, T22–T24, including the same-key conflict, finished replay, and candidate-byte mismatch rows.
Decision: knowledge/data/skill_library (records, configuration, compiled provenance and skill owners); pack.json separately at harness/data/repo_packs/<pack>/pack.json; the dashboard template at Apps/views/templates/dashboard.html. K01 migrates seven code modules only and moves no resources; K02 performs the three precise migration classes (importlib, checkout Path, plugin physical layout) with old logical pins/hashes preserved and without assuming a single loader.
Decision: see function-owners.md. Target new core layout:
- K keeps the seven original file names.
- H:
api.py,execution_service.py,input_binding.py,run_store.py,budget.py,resources.py,records/*. - B:
api.py,evaluation.py,legacy_run_v0.py,sampling.py,tasks/*,workers/*,validators/*. - Apps:
bridge.py,archive.py,result.py, andviews/legacy.
These are target names; src does not yet contain a production RunStore or worker. A name is not evidence that code exists. Mixed responsibilities are split by accepted responsibility, and unlisted unknown functions are not moved by filename.
Decision: see gate-policy-runstore-and-first-prs.md §B. Seven precise Knowledge root compatibility re-exports are the entire first wave; the current gate is unchanged until a formal architecture review accepts the exact policy first. No dynamic import escapes, no star imports, no sys.modules substitution, no blanket harness/* exception. overall isolation_complete stays false while any allowlist entry or registered residual legacy edge exists.
That is the first-wave decision as it was taken, and the older contract documents keep it as written. Current status after R1 (#412): the seven root re-exports are deleted and the allowlist is empty. D018 below records what replaced the last pair and what still keeps isolation false.
Decision: the ExecutionRecord minimal list, execute delivery, Apps→B mapping, and every figure carry capacity/reservation, actual usage, and releasable leases with confirmed release as three independent facts. Unknown is null with a reason; not-applicable is explicit; zero is never used to impersonate unknown; reservations are not charged as actual usage; units are never summed across currencies.
BudgetAdmission/Reservation are produced by actual H admission, not by an Apps preview. A paid capability with no policy is refused. Free CPU may use policy_ref=null only when H confirms there is no paid capability and the task requires no budget policy; scope, deadline, and observable usage are still kept.
Generation, evaluation, and retry share the budget scope and total deadline; they do not reset per attempt, and Apps invents no refund rule. Lease cleanup and cost settlement are recorded separately; an unconfirmed release is not reported as released.
Acceptance: the three facts are independently produced, projected, and read back consistently; a cancellation request is not an exited process or a release; elapsed/call-count/amount units stay independent; not_started still records admission and reservation facts that occurred.
Decision: keep Collection(items, omissions, collisions, no_match, limitations, selection?) as the public v1; do not add mandatory inspected/eligible/selected/delivered DTO layers. If selection is used it must retain the selection rule/version, input candidates/pins, and selection/omission notes. H separately retains the DeliveredContext bytes actually delivered; retrieved or selected is not the same as delivered or adopted. The five Bundle dimensions remain separate and are not collapsed into one lifecycle enum.
create/update/history keep existing CAS semantics; an expected_revision conflict must fail and is never implicitly overwritten. Storage schema 2 and _provenance are internal only; the port returns parsed schema-1 logical records. Author declaration goes through PR/CI and is not pushed into read/collect/update.
Acceptance: a pure-id Bundle read and an authority-qualified read ref are listed separately and history hashes do not change; an unavailable fixed revision fails explicitly; the delivered byte cap applies and omissions are explainable; no-match, collisions, and limitations are never silently dropped.
Decision: see gate-policy-runstore-and-first-prs.md §C. There is no production RunStore in src; the design selects a new H-owned local SQLite v1. It does not wrap a nonexistent system and does not treat an in-memory dict as a cross-process implementation. First phase is local filesystem only: no network disk, distributed transaction, daemon, or automatic takeover.
Decision: old entry points, arguments, Path, stdout, stderr, and old run 0/1/2 stay byte-for-byte compatible. New Apps naming/envelope/exit mapping is fixed by D022, but K01/H01 do not implement a CLI.
Current reading: this covers the CLI commands and the inferrsi and python -m inferrsi entry points. It no longer covers old root Python module paths. The revised delivery decision in #412, #451 and #408 retires those paths without aliases, in the change that moves their last consumers. R1 (#412) removed the old-run root modules evaluation, execution and reporting together with root inspection; the old run is inferrsi.apps.legacy and the host inspection binding is inferrsi.apps.inspection. A1 (#408) then moved root cli.py and arguments.py to inferrsi.apps.cli and inferrsi.apps.cli.arguments and deleted both root files; the console script and python -m inferrsi call inferrsi.apps.cli:main.
Decision: #333 and #371 are both Proposed, not accepted event schemas. ExecutionEventV1 is only an H-local fact read model; it is explicitly not a new format for #333 production events and does not cross-write legacy events.jsonl. Legacy STAGES/verdict capture/reconciliation belong to H; presentation belongs to Apps. A formal unified event implementation belongs to its own later slice and does not block K01/H01.
Decision: D019 fixes the first-wave PRs and their acceptance IDs (A00/A01/K01/K02/H01/H02/B01 rows) and the rollback rules; see gate-policy-runstore-and-first-prs.md §D. T01–T40 in acceptance-criteria.md are the single numbered acceptance set; T36–T40 come from D023. Acceptance IDs are expectations, not executed tests.
Decision: see schema-and-semantics.md. Draft 2020-12 library urn:inferrsi:design:contract-v1, 106 named definitions, all new fixed-object fields required, unknown fields rejected, null only where the schema permits it. The library root must not be used as a validation target; validate against a named $defs entry.
Decision: gate-policy-runstore-and-first-prs.md §B: exact seven leaf→module allowances, shape checks, transitive-closure checks, the registered residual harness/skill_evaluation.py → knowledge_operations → knowledge.* edge, the staged isolation test, and the rule that a non-empty allowlist keeps overall isolation_complete=false. The skill-evaluation split (#410) later removed the registered residual edge and its exemption.
Current status after R1 (#412):
- The seven root leaves are deleted, so
compatibility_pairsin../legacy-knowledge-manifest.jsonis empty. The nine pair records stay in itsrevision_history, unchanged, as the record of this decision. - The former ninth pair,
infra.inspection→inferrsi.resources.repository_packs, is a live import that no root deletion removes. It is now a permanent exact rule outside the allowlist: that one module binds the one namerepository_packwith one plain module-level import. The leaf's bytes, SHA-256, allowed imports, shape and import-free parent initializer stay locked, and noresources.orcontracts.prefix is allowed. - Root
arguments.py→ the same leaf, forREPO_TYPES, was a separate temporary entry with its own blocker. A1 (#408) removed both with the root file, and no Apps importer of the leaf replaced them. overall isolation_completeis true since R3 (#412). A1 (#408) cleared that temporary entry, R2 cleared the twelveharness→inferrsi.infrahits in six Harness modules and R3 cleared the five runtime resource loaders (a child-process protocol, two folded sibling modules and a permanent two-evaluator rule). The package root holds the two tracked files__init__.pyand__main__.py.- The permanent rule and that manifest revision require formal architecture review. The implementer does not self-approve them, and passing tests are not that review.
../module-layout.md has the exact rules and their negative controls.
Decision: gate-policy-runstore-and-first-prs.md §D. PR-00a (this contract set), PR-00b (gate policy), K01 (seven K modules), H01 (persistent record core), H02 (single-CPU execute), K02 (physical resource migration), then B01/Apps. H01 does not depend on K01 or H02; B/Apps do not block K01/H01.
| Owner | Port | Input → output | Prohibited side effects / invariant |
|---|---|---|---|
| K | read(reference, revision=None) |
KnowledgeReadRequest → KnowledgeReadResult |
returns actual pins; legacy logical record unchanged; read does not write the store or execute |
| K | collect(query/ids/pins/filters/selection) |
KnowledgeCollectRequest → KnowledgeCollection |
no-match/omission/collision explainable; dynamic selection does not claim permanent replay |
| K | resource(reference, path, revision) |
KnowledgeResourceRequest → result + read-only bytes |
revision required; never re-resolves current; path authorization and hash check |
| K | create/update/history |
Knowledge*Request → fixed revision/history |
CAS conflict is not success; no new write-idempotency log |
| B | prepare(PrepareRequest) |
PreparedEvaluation, plus, outside the object, in-process: canonical bytes of the frozen protocol and a read-only per-role entry to the resource closure |
no execution/budget admission/implicit archiving; freezes legal rules and closure; does not depend on Apps storage routing and does not store bytes itself |
| B | encode/decode/validate_prepared |
PreparedEvaluation ↔ canonical bytes (may accept an already-assigned location) |
pure computation; unknown version is not guessed |
| B | assess(prepared, evidence, *, artifacts) |
EvidenceInput → EvaluationResult |
reads retained bytes only; no worker/candidate start, no network, no device, no re-measurement |
| B | claim_keys(protocol) / validate_request_key |
frozen protocol → read-only claim-key set, or a business-free projection test of the requested key | read-only; no business judgment; writes no assessment; used by Apps before invoking the assessor (V34) |
| B | encode/decode/validate_assessment |
EvaluationResult ↔ canonical bytes |
only B decides claim/metric/eligibility/comparison |
| H | allocate_attempt(run_id, owner, target_request, deadline, resources, budget, retry*) |
AttemptContext |
allocates identity; no budget/resource taken, no start; request_id=attempt_id |
| H | execute(spec, *, cancellation=None) |
ExecutionSpec → flat ExecutionRecord or a stable PublicError class |
atomic registration, H admission/binding/run/record; verifies the actual entry code digest before start (V32); not B scoring |
| H | read(attempt_id, record_version=None) |
flat ExecutionRecord |
latest means latest committed; a specified version is fixed; no committed record → NoCommittedRecord; no snapshot fabrication, no takeover/restart |
| H injected | CandidateProvider.plan_generation / collect_candidate |
CandidateContext+AttemptContext → GenerationPlan; Record → CandidateProposal |
neither end performs external execution; H executes in the middle |
| H injected | EvaluationPort.execution_for / assess |
PreparedRef+CandidateProposal+AttemptContext+scope → ExecutionSpec; Record → AssessmentSummary |
implemented by Apps as an adapter; identity/deadline/budget not rebuilt; AssessmentRef only after the result is saved |
| H injected | ContextProvider.collect |
ContextRequest → DeliveredContextDraft (in-process value, not a JSON DTO) |
draft carries no uncommitted valid ArtifactRef; H seals DeliveredContext through its own capture/commit (V33) |
| Apps | archive_prepared / archive_assessment / bind_execution / to_evidence / to_summary |
fixed bytes → the corresponding Ref; explicit field conversion | Ref only after successful archive; never writes the H RunStore; invents no budget/judgment/scope semantics |
| each module's own reader port | ArtifactReader.open(ArtifactRef) |
read-only byte stream | authorized root, size/hash, safe path; no network/current fallback and no re-execute |
The D023-1 in-process closure delivery is not a new DTO and does not add a PreparedEvaluation field; the final location lives only in the existing ArtifactRef.location. The D023-3 DeliveredContextDraft is likewise an in-process value type (items/selection/omissions/limitations, bytes or stream, intended logical location and digest); it deliberately is not a $defs entry and no serializable stream shape is invented for it.
JSON Schema reference reuse is document structure only. It does not authorize K/H/B importing each other's DTO implementations or a shared business package.
inferrsi-json-v1: ASCII keys in lexicographic order; UTF-8 with no BOM, no trailing newline, and no insignificant spaces; arrays not reordered; Chinese not escaped and Unicode not normalized; duplicate keys, lone surrogates, float tokens, NaN/Infinity, and integers outside [-9007199254740991, 9007199254740991] rejected. Strings use language-independent escaping: \", \\, \b\t\n\f\r, and lowercase four-digit \u00xx for the remaining U+0000–U+001F; every other legal scalar is raw UTF-8, including /, U+007F, U+2028/U+2029, and non-BMP characters. Full rules and the identity projection P are in schema-and-semantics.md §3.
Machine schema fields, canonical rules, and semantic expectations are written down. Actual implementation tests remain implementation acceptance; nothing here claims they passed. The source audit covered known D1–D8 patch seams, private names, lazy imports, and the catalog split; the coverage boundary is disclosed, and no claim is made that all 993 functions were reviewed. H02 helper migration and the full K02 artifact build chain are measured point by point in their own implementation PRs; they are not prerequisites for starting K01/H01.
Final convergence requires a Fable review of this exact version stating no known design blocker, with the author independently reviewing the argument and integrating later source evidence. Repository review acceptance, real tests, and implementation authorization remain separate. All material in this set remains Proposed.