README.md

Architecture decision records

This directory records the cross-cutting implementation decisions behind judgment-pack-runtime — the ones no single commit or pull request captures well, such as the repository layout or the adapter strategy.

These are ADRs, not RFCs. The split follows the repository boundary:

• This runtime → ADRs. Implementation decisions for one nonnormative consumer of JPS, recorded after they are effectively made. Lightweight; no comment-before-commit process.
• The specification → RFCs. Normative, public, cross-implementation proposals open for comment before a decision, in judgment-pack-spec under rfcs/ (see its rfcs/0000-rfc-process).

A runtime decision graduates into a spec RFC only if it ever needs agreement across independent implementations (for example, a standard MCP surface every JPS validator should expose).

architecture.md describes the system as it is now; ADRs record why and when it became that way. architecture.md links out to the relevant ADR rather than restating it.

Adding a record

1. Copy template.md to NNNN-short-title.md using the next free number.
2. Write it, set status: proposed, and open it in the pull request that makes the decision.
3. On merge, set status: accepted. ADRs are immutable once accepted: a later change is a new ADR that supersedes the old one (which is then marked superseded by NNNN), never an edit.

Partial supersession. A later ADR may supersede a named determination of an earlier record without superseding the record: the earlier record keeps its own status and its text is not edited, and the index row for it carries the annotation naming what was superseded and by which record. Record-level superseded by NNNN is for a record no longer in force as a whole.

Review of material decisions

A material decision in this runtime follows the interim review regime recorded in the specification repository's GOVERNANCE.md and designed in RFC 0009. A decision is material when it changes a public surface, a documented claim, conformance-relevant behavior, the security posture, or a dependency boundary. The trigger is the decision, not the paperwork: a material decision made without an ADR is still material, and skipping the ADR does not skip the review.

Such a decision requires a recorded adversarial review by a model from a different vendor than any model that assisted the drafting, with a written maintainer disposition for each finding, on the pull request that makes the decision. The record states the commit SHA that was reviewed. A material change after the reviewed SHA requires a fresh review, with one exception mirrored from the regime: a change that implements a dispositioned finding of a review already recorded on the same pull request is covered by that finding's disposition. Vendor means the organization that controls the model's weights and training — the developer, not the API host and not a reseller; hosted copies of the same model share lineage and count as the same vendor. Assisted the drafting means generated or revised text that survives in the merged artifact, or planning, analysis, structure, or design choices supplied by a model and relied on to produce it; paraphrase does not launder assistance, so a model that shaped the outline or settled a design question assisted the drafting even when none of its sentences survive. Applying an accepted finding in one's own words does not make the reviewer a drafter, and adopting reviewer-generated text verbatim under an accepted finding does not retroactively invalidate the review that produced it — no further review is required on that account — but the record says where each such adoption happened. ADRs are written after the decision and are immutable once accepted, so the review attaches to the pull request, not to the ADR text.

The review obligation applies to the pull request that introduces this section and every later pull request that makes a material decision, including one that supersedes an existing ADR. Beginning with the introducing pull request, every pull request — material or not — carries the declaration below. "Later" is determined by commit ancestry from the commit introducing this section, not by a calendar date. The specification repository's GOVERNANCE.md governs only that repository; this section is what places this runtime under the obligation.

Every pull request in this repository states its impact in the description, on one line:

Material-decision impact: none
Material-decision impact: <category>[, <category>...]; review: <link to the review record on this PR>

Categories: public-surface, documented-claim, conformance, security, dependency. none appears alone; otherwise list every category that applies, comma-separated, followed by review: and a permanent link (or links) to review records covering every listed decision. A test-only or behavior-preserving change is none unless it changes what conformance checking accepts, which is conformance. A routine dependency version bump is none; a bump that fixes a vulnerability is security; adding, removing, or replacing a dependency is dependency. An automated pull request (dependency bots) gets its declaration added by the maintainer before merge. none is a claim, not a formality: it is the author classifying their own change, and it is wrong whenever the change turns out to be material.

Materiality is classified by the maintainer, who is also the author — the weak point of this arrangement, stated rather than papered over. The declaration does not fix that; a checkbox its own author ticks measures the author's care, not the change. What it does is make silence a policy violation: when the rule is followed, the classification is explicit, dated, recorded on the pull request with the reviewed SHA, and contestable there — and omitting the ADR and the review no longer omits the classification with them. Model review substitutes for review breadth while the project has a single maintainer; it is not decision authority, and following it confers no conformance status on anything.

Index

#	Decision	Status
0000	Record runtime decisions with MADR-format ADRs	accepted
0001	Idiomatic Go single-module layout; no packages/ umbrella	accepted
0002	Language plurality lives at the wire and in thin clients, not polyglot packages	accepted
0003	MCP is the runtime's integration and testing surface	accepted
0004	Permanently decline an in-runtime HTTP API	accepted
0005	Use a single JPS- prefix for diagnostic codes	accepted
0006	The authoring lifecycle lives in the client; the runtime is a stateless oracle	accepted; no-store determination partially superseded by 0018
0007	Ship an experimental evaluator behind an explicit experimental surface	accepted; claim posture superseded by 0011
0008	Serve authoring method as MCP prompts; the intelligence stays in the client	accepted
0009	Prototype spec RFC 0008 quantifiers behind an opt-in experimental flag	accepted
0010	Retarget the experimental evaluator at 0.2.0-draft's evaluator class; claim nothing	accepted; claim-scope determination superseded by 0011
0011	Supply the §10 evaluation limits and make the first §3.4.1 evaluator-conformance claim	accepted
0012	Adopt a jpack.json project convention in the runtime, deliberately outside the spec (configVersion value list superseded by 0017)	accepted; nothing-writes determination partially superseded by 0018
0013	Distribute the released binary as an OCI image and publish it to the MCP registry	accepted
0014	Report derived matrix coverage in packs test, and never gate on it	accepted; two witness clauses narrowed and three derivation universals generalized by 0023; never-gates determination partially superseded, for a run that asks for a coverage requirement, by 0080
0015	Prototype pack composition as an experimental graph surface (jpack.json determination partially superseded by 0017)	accepted
0016	Report derived coverage in experimental graph test, and never gate on it	accepted
0017	Declare graphs in the project configuration, and walk them like matrices	accepted; configVersion value list and schema $id partially superseded by 0018
0018	Record evaluations into the project's own tree, and only when the project asks	accepted; record-every-completed-evaluation determination narrowed for declared rehearsals by 0028, and for declared graph rehearsals by 0041; configVersion value list and schema $id extended by 0044
0019	Pin the reviewed set in a sibling lock, and refuse to decide under law that left it	accepted; deciding-surfaces-consult determination narrowed for declared rehearsals by 0028, and for declared graph rehearsals by 0041; draft-never-refused determination narrowed for projects that set requireReviewed by 0044
0020	Report the fact pointers a pack's conditions read, on the inventory row	accepted; its "a trace entry carries no pointer" determination superseded for unknown causes and cross-type comparisons by 0040
0021	Run the declared matrix over MCP, and keep the rehearsal outside the record	accepted
0022	Lint every consulted pointer against a producer declaration	accepted
0023	Derive a boundary probe for every ordered comparison, witnessed by a row's facts	accepted; option C's refusal partially superseded, for a run that asks for --require-boundaries, by 0080
0024	Derive candidate test-row inputs from a pack's own literals, and never their expectations	accepted
0025	Let a matrix row assert the handoff target, because no disposition can carry it	accepted; graph-surface-untouched determination partially superseded, and its deferral discharged, by 0032
0026	Run the declared graph matrix over MCP, and stop a runaway matrix early	accepted
0027	Pin the evaluation trace: deterministic, complete, ordered, and still informative	accepted; §0's matrix-results-carry-no-traces determination partially superseded for graph matrix node comparisons by 0031; entry shapes extended by two optional members in 0040, clause 6 unchanged
0028	Declare an evaluation a rehearsal, so exploration never writes a decision record	accepted; its shape applied to graph evaluation by 0041, as its clause 5 anticipated
0029	Serve the configured graphs and their inventory over the wire, read-only	accepted
0030	Bind graph matrix runs and validations to the loaded document	accepted
0031	Report node traces in the graph matrix on request	accepted
0032	Let a graph row assert the handoff target	accepted
0033	A decision record cites the receipts it relied on, as given	accepted; where-it-lands determination superseded for a project that keeps no trail by 0051
0034	Profile a matrix against its history: agreement by origin, values at each threshold, rows that cite receipts; never gated	accepted
0035	Validate proposed exact expectations before authoring admission	accepted; reachability-finding deferral discharged by 0037
0036	Admit test matrices and rehearse exact pack snapshots through MCP	accepted
0037	Report an expectation no pack can reach under its own code, in the admission tool alone	accepted
0038	Refuse malformed Unicode at the stdio transport, for every string argument and everywhere else in the request line	accepted
0039	Prototype spec RFC 0016 outcome values behind an opt-in experimental flag	accepted
0040	Say what left a result unknown: causes and cross-type comparisons in the trace, unmet evidence beside it	accepted; option D (a check of a facts document against a pack) taken up for projects that set requireComparableFacts by 0046
0041	Declare a graph evaluation a rehearsal, on ADR-0028's terms	accepted
0042	Let a packs test run require every selected pack to have a matrix	accepted
0043	Record the executable's digest on every audit record	accepted
0044	Say in the payload whether the reviewed set was applied, and let a project require it	accepted; configVersion value list and schema $id extended by 0046
0045	Compare what two versions of a pack decide for the same inputs	accepted
0046	Keep the trace's type and unknown notes on the audit record, and let a project refuse a fact no comparison can match	accepted
0047	Make a decision record defensible to someone who does not trust its operator	accepted; Selection (T3) settled by 0048; unsigned-records-never-fail-a-decision determination narrowed for projects that set requireSigning, and configVersion value list and schema $id extended, by 0071
0048	Refusals and rehearsals stay outside the trail, and the trail says so	accepted
0049	Bind graph evaluations to the bytes actually loaded	accepted
0050	Record a caller's binding digest on the evaluation record, as given and never interpreted	accepted
0051	Refuse citations where no trail is kept, as a binding is refused	accepted
0052	Offline dialect document tooling with explicit encoding-only scope	accepted
0053	Validate version-2 dialect document forms and references offline	accepted
0054	Serve pinned authoring resources and compare dialect targets with pack inventory	accepted
0055	Share exact artifact version options through CLI and MCP	accepted
0056	Check supported version-3 Dialect declarations through shared authoring tools	accepted
0057	Share offline tools for named Dialect artifacts	accepted
0059	Prototype Policy document and retained-reference checks offline	accepted
0060	Add an explicit Policy contract candidate without changing prototype clients	accepted; source/maturity for new explicit 1.0.0 operations superseded by 0061; candidate-only corrected URI scope superseded by 0064
0061	Adopt immutable official Policy draft resources in the shared offline reader	accepted; effective upon required CI and introducing PR merge
0062	Expose bounded static fact-type advice without authoring expectations	accepted
0063	Add explicit base-only Core 0.3.0 contracts without changing legacy defaults	accepted; optional-advisory skipping superseded by 0066
0064	Share RFC 3986 URI grammar while preserving prototype Policy compatibility	accepted; partially supersedes 0060's candidate-only corrected URI scope
0065	Read exact configured audit bytes and structured history with bounded MCP tools	accepted; history 64 MiB source-limit determination partially superseded by 0069
0066	Report bounded rule-overlap advice without changing document conformance	accepted
0067	Retain every actual outcome contributor outside the disposition	accepted
0068	Rehearse an explicit finite domain for optional pack-design advice	accepted
0069	Bound history reads by window independently of source size	accepted
0070	Publish truthful owner taxonomy and digest-addressed method skills	accepted; effective upon required CI and introducing PR merge
0071	Say at decision time why a record is unsigned, and let a project require signing	accepted
0072	Answer whether a reviewed-set lock covers a document's exact bytes, without opening a project	accepted
0073	Expose loading and evaluating a pack as an experimental in-process Go API	accepted
0074	Describe a loaded pack, every member as written, through the Go API and jpack packs describe	accepted
0075	Admit the staged draft selector 0.4.0-draft experimentally: evaluate its evaluation form, and show and filter its annotations	superseded by 0077
0076	Show every annotation character outside printable ASCII recoverably: exact in the JSON, in ASCII in the Markdown and the messages	accepted
0077	Admit Core 0.5.0, base profile, and retire the staged selector 0.4.0-draft	accepted; its dialect-check refusal superseded by 0082, its pack-design analysis refusal by 0089
0078	Keep annotation text from reordering its line, and keep a run of spaces visible, in the Markdown views	accepted
0079	Return a canonical decision record for one evaluation from the Go API, written nowhere	accepted
0080	Let a packs test run require a coverage level and witnessed boundaries	accepted
0081	Carry the rule-overlap advice of spec validate in packs validate	accepted
0082	Let the dialect check read Core 0.5.0 packs	accepted
0083	Sign a pack file's bytes, and check the signature against an expected key before the pack is used	accepted
0084	Measure a matrix's test strength with variants of its pack	accepted
0085	Evaluate a batch of fact documents in one run	accepted
0086	Compare two pack documents member by member, annotations included, and three-way	accepted
0087	Name the facts on a decision record by a digest the caller keys, in a second form, and publish the canonical text	accepted
0088	Check each outcome's severity against the Spec's annotation vocabulary in packs validate, and list it in the view	accepted
0089	Analyse a Core 0.5.0 pack as its evaluation form	accepted
0090	Check, over a git repository's own tags, that a published pack or dialect identity keeps its bytes	accepted
0091	Revalidate a project's matrix results against a baseline file before moving a Runtime pin	accepted