Engineering standards — object model, boundaries, determinism, testing method and dependency policy¶

Date: 2026-09-10 · Revised: 2026-09-11 (§10a, §10b and §11 amended for the lockfile drift check, the advisory type lane and the fork-workflow settings) · Status: policy, not product architecture (ADR-009); this document changes without an architecture version bump · Authority: ADR-003, ADR-006, ADR-009, ADR-012; framework-spec.md §2, §4, §6

0. Standing, and how to read this¶

Most of this document is the house default and the reason behind it, not a rule you can fail. Three things here are binding, and each is binding because a claim the project publishes is false without it: Protocol ports (§1, because conformance must be executable without depending on the product), determinism seams (§4, INV-42) and record canonicalization (§5, INV-43). Everything else is a default. A contribution that departs from a default and states why is a normal contribution.

The distinction is deliberate and matches public-development-strategy.md §4b: the project is strict about what it claims and generous about how the code is written. A check that would only make the repository tidier is a comment, not a gate.

Read this when you are about to write code, not before deciding whether to. public-development-strategy.md §4a names the two or three documents that actually apply to a given contribution.

The architecture states what the system is and what must never be true. This document states how the code that realizes it is built, bounded and verified. Where it disagrees with an ADR, framework-spec.md or a schema, those win. §12 records the practices deliberately left ungated, and why.

1. Object model¶

Two of the entries below are binding because a claim depends on them; the rest are the house default and the reason for it. A contribution that departs from a default and says why is a normal contribution, not a violation. Nothing in this section is a merge gate on its own.

Patterns that earn their place and the reason each is required rather than preferred:

• Adapter/port at all ten extension points — the conformance contract.
• Strategy over a mechanism registry for resource calculation, whose registry default is unknown. INV-32 forbids selecting a formula from a modality or family label; a registry whose miss returns a fallback would violate it silently.
• Policy combination in the authorization engine: deny-overrides, intersection of independently supplied constraints, indeterminate never permitting. This is a rule-combining algorithm and is tested as one, with an explicit truth table, not as a sequence of conditionals.
• Frozen value objects for every record and envelope.

2. Adapter discovery¶

Adapters register through packaging metadata, one entry-point group per extension point:

[project.entry-points."apron.engines"]
vllm = "apron_vllm:VllmEngineAdapter"

[project.entry-points."apron.artifact_sources"]
huggingface = "apron.adapters.huggingface:HubResolver"

importlib.metadata.entry_points(group=...) is the loader. Entry points are a PyPA interoperability specification and are available in the standard library from the declared Python floor. Group names are apron.engines, apron.artifact_sources, apron.render_targets, apron.evidence_sources, apron.planning_sources, apron.evaluation_adapters, apron.execution_targets, apron.signal_sources, apron.authority_sources and apron.publishers. Discovery never implies support: a discovered adapter still resolves to unknown or unsupported per stage until its conformance record exists.

3. Module boundaries¶

Distribution layout is src/apron/. The twenty-two directories named in framework-spec.md §6 are subpackages within it, assigned to four layers with one permitted dependency direction. The assignment is recorded here so that it is not re-derived by each reader:

Five of the §6 directories are not source packages and sit at the repository root instead: conformance/, which is published as its own distribution (§7); rules/, holding diagnosis rules as YAML-frontmatter markdown; records/, append-only; interim/, for implementations awaiting an upstream home (ADR-008 §3); and upstream/, the index of open contributions. docs/ and tests/ join them.

domain imports nothing from the other three. application imports domain. adapters import domain and application. interfaces import all three and contain no recommendation, calculation, ranking or promotion logic.

Contracts are declared in pyproject.toml and checked by import-linter in ordinary CI. This is the mechanism INV-11 requires; the invariant previously named an architectural test without naming how it is executed.

4. Determinism (INV-42)¶

The architecture describes the optimizer, the authorization engine, corrections, generated endpoint plans and decision reports as deterministic. That claim is unverifiable while any component can read an ambient clock, generate an identifier or draw randomness.

• Wall-clock time, identifier generation and randomness reach domain/ only through injected Clock, IdGenerator and Rng ports.
• A component described as deterministic names its seed sources and produces byte-identical output for identical inputs.
• No execution, solution, artifact or task fingerprint contains a value obtained from an uninjected source.
• The same ports are the seam through which orchestration replay, crash and duplicate-event tests (ADR-010, INV-21, INV-22) become executable without a live provider.

These ports are cheap while domain/ is small and are not retrofittable once record writers and the orchestrator exist. They are a start condition for schema implementation.

5. Record serialization and identity (INV-43)¶

INV-35 derives an evidence release's identity from a schema-versioned manifest and record digests rather than a host URL, and INV-12 requires reproducibility to the limit of a typed claim. Both require a defined mapping from a record to bytes; without it, mapping order, floating-point representation, Unicode normalization and omitted optional fields all change the digest.

• Canonical form is RFC 8785 (JSON Canonicalization Scheme).
• Identity is SHA-256 over that form, carried with a multihash prefix so the algorithm is recorded rather than assumed.
• Test vectors are published with the schemas. A digest is correct when an independent implementation, in another language, reproduces it from the same record.
• A digest computed from an uncanonicalized encoding is rejected rather than stored.

The vectors matter more than the algorithm choice. The portability claim in INV-35 is that another tool can reconstruct and verify a release; an implementation that cannot recompute a digest falsifies it.

6. Concurrency¶

The default is a synchronous domain/, with asynchrony inside the adapters that perform network or subprocess I/O, and an interface owning the event loop at its composition root.

The reason is testability rather than performance: the deterministic core is where properties, replay and simulation execute, and asynchrony there would make every determinism check depend on scheduling. Where an extension point genuinely needs an asynchronous contract — a streaming evaluation adapter is the likely first case — that is a contract change proposed with its reason, not a rule to work around.

7. Conformance suites and third-party execution¶

framework-spec.md §1 states that a new implementation is accepted when the conformance suite passes on the golden fixtures and that there is no other acceptance path. That acceptance path must be executable by whoever wrote the adapter.

• The suites are published from apron as a separate distribution, apron-conformance, installable without the product. ADR-012 §1 restricts speculative repositories, not distributions; this adds no repository.
• The distribution exposes a pytest plugin. An adapter author runs the suite against their own implementation in their own repository, against fixtures they did not write.
• The suite is written before the first adapter of a given extension point, with a fake adapter as its first client.
• Fixtures recorded from a pinned engine carry the engine digest and capture date. A recording older than the currently pinned image fails the suite (ADR-003 §9 amendment). Without expiry, GPU-free tests drift from the engine and pass against a fiction.

8. Test kinds and where each applies¶

The corpus already specifies verification obligations in four places: the enforced by column of framework-spec.md §2, the required conformance and failure tests of ADR-011, the required fixtures of ADR-007, and the injected failure classes of ADR-005 §3, plus each phase exit gate. This section states what kind of test satisfies an obligation, not which obligations exist.

9. Where test-first does not apply¶

Test-first is the default for domain/ and for every contract in §7. It is explicitly not the method for code whose specification is an external system's observed behaviour: engine execution output, artifact-source responses, provider APIs.

Those are recorded-fixture-first. Capture the real response, commit it with provenance and capture date, then write the code that parses it. A test written before observing the system asserts an assumption about it — the same distinction the architecture already draws between predicted and measured, applied to the test suite.

10. CI tiers¶

Budgets are set from measurement rather than declared in advance. GPU-free CI never emits engine or GPU validation (INV-37).

10a. What guards a pull request¶

A change can deviate from the product in three ways, and each has its own automated guard. Nothing else is gated. The point of naming them is that a contributor can predict, before opening a pull request, exactly which class of objection is possible.

Shape — where code may live and what it may import. Contract — the typed surfaces an implementation must satisfy. Claim — what the produced data is allowed to assert.

Most of the enforced by column of framework-spec.md §2 is GPU-free and therefore runs at pull-request time. The exception is stated in ADR-003: engine compatibility, boot, kernel and profile verdicts require GPU execution and are a release gate, not a pull-request gate. GPU-free CI never presents its own result as engine validation (INV-37).

Two properties of this set matter more than its contents. Every blocking job answers a question about the product rather than about the contributor, so a rejection is always traceable to a claim that would otherwise become false. And every blocking job is runnable locally by the person writing the change — the conformance suites are installable, the fixtures are in the tree, and the same commands run in CI — so a contributor never discovers an objection they could not have anticipated.

10b. The checks run before the commit, not after the pull request¶

The job graph above is the backstop. Its primary use is local, and it is written to be usable that way: every job in §10a runs from one command in the working tree, against fixtures that are in the tree, using suites that are installable.

That command is the last step of authoring rather than the first step of review. An agent or contributor runs it before committing, so what reaches a reviewer is a question of intent rather than of correctness. This is the project's answer to the measured increase in review burden that AI-assisted authoring produces — a 19% productivity decline for experienced developers and a 6.5% rise in review load (arXiv 2510.10165). The burden is removed by moving correctness into the loop that writes the code, not by adding a second reviewer after the code exists.

Two consequences follow:

• No check may exist that cannot run locally. A gate reachable only through continuous integration moves a discoverable error to the latest and most expensive moment, and teaches a contributor that the rules are found by failing rather than by reading.
• Automated review of a proposed change belongs in the authoring session, which already holds the full context of the change, rather than in a workflow holding a credential. A continuous-integration reviewer sees less than the session that wrote the code, and costs a credential boundary to operate: pull requests from forks carry no secrets by design (INV-37), and the workflow trigger that circumvents that restriction is precisely the one that exposes them.

An external automated reviewer is introduced when external pull requests exist to calibrate it against, not before. When introduced it is advisory under public-development-strategy.md §4b: it comments, and the deterministic checks gate. It is also triggered by a maintainer on a specific pull request and never posts automatically on every pull request — LLVM's AI tool policy states that "automated review tools that publish comments without human review are not allowed", and Node.js's AI guidelines (merged 2026-08-12) forbid automated review responses, so a reviewer that posts on arrival is a contribution this project could not itself make upstream. Its subject is the judgment the checks cannot make — whether an abstraction suits the extension point, whether evidence language claims more than its fingerprint supports, whether an unknown is honest — never a re-derivation of a result §10a already produced deterministically and for free.

Workflow security follows ADR-009 and is not negotiable per job. The default token permission is read-only and widened only where a job demonstrably needs it. Every job declares a timeout and the workflow declares a concurrency group that cancels superseded runs. Third-party actions are pinned to reviewed full commit SHAs. Pull requests from forks receive no secrets, no protected environment and no side-effect authority (INV-37); provider execution, release publication, evidence publication and external-repository mutation each use a separate credential scope and a protected environment with a required reviewer, and are reachable only by explicit dispatch, never by a pull-request event. No workflow triggered by a fork's pull request runs with elevated context. Two concrete consequences: no workflow uses pull_request_target, which is the trigger that grants a fork's code the elevated context this rule forbids, and the repository setting for fork pull request workflow approval is all external contributors, the strictest of the three values GitHub offers.

11. Dependency and version policy¶

12. Recommended practice, deliberately ungated¶

The following improve the suite and are recorded here as practice. None is an invariant, an exit gate or a checklist item, because each requires recurring human attention or recurring cost and would therefore be dropped. An obligation the project states and stops honouring is a false claim under INV-1 and §2a, which is a worse outcome than not stating it.

• Mutation testing over the pure core, scoped to changed lines rather than a global score.
• A unified index mapping every written verification obligation across framework-spec.md, ADR-005, ADR-007, ADR-011 and the phase exit gates to a named test with a stable identifier. Valuable, and only durable if the placeholder for an unwritten test expires rather than remaining indefinitely skipped.
• Scheduled re-recording of external contract fixtures.
• Ownership controls on golden fixtures. The mechanical half — surfacing the byte difference of a regenerated fixture in the change description — costs nothing and is retained; a review gate on the same files is not.
• Tolerance bands and repetition policy for profiled memory observations, which are not reproducible between executions.
• Deterministic simulation of the full orchestrator, as distinct from the §4 ports, which are required.
• Instrumentation tests proving that telemetry events fire, are counted by the published rules, and that the absence of consent suppresses transmission.

Any of these may be promoted to an invariant later, on the evidence that it was actually held.