# Technical review

## Task and place

Technical review asks whether the package is soundly built, whatever it means.
It sits after semantic review: meaning has been checked against the pinned
source, and now structure, pins, dependencies, suites, and reproducibility get
their own pass. The reviewer runs the tooling, reads the manifests, and records
an engineering opinion on the exact version in front of them.

## Inputs

- The package directory with its manifest, lock file, model files, suites, and
  pinned source bytes.
- The semantic opinion with its scope, so technical findings do not reopen
  meaning: the filled [EAI review record](/handbook/files/filled/eai-review-agent.md), the [candidate review record](/handbook/files/filled/eai-review-candidate.md), and the [R3 review record](/handbook/files/filled/eai-review-candidate-r3.md).
- The decision records behind the suite expectations: the filled [EAI tariff decision](/handbook/files/filled/eai-decision-tariff.md), [EAI threshold decision](/handbook/files/filled/eai-decision-threshold.md), and [EAI penalty decision](/handbook/files/filled/eai-decision-penalty.md).
- The [review record template](/handbook/files/templates/review-record.md), reused for the engineering opinion.

## Actions

- Read the manifest: package name, version, language line, namespace, declared
  suites with their worlds, and the explicit-imports marker.
- Read the lock file: dependency edges must match the manifest claim — empty
  for a zero-dependency package — and the root identity must name the same
  package and version.
- Confirm every pinned publication resolves: the local bytes exist and their
  hash matches the pin. A renamed or edited source file fails here.
- Run the static check, the full suite, and the pin comparison, and record the
  tool version with each result.
- Reproduce from a fresh copy: copy the directory, rerun the same commands,
  and confirm identical results before writing the opinion.

## Decisions

- Which findings block acceptance and which travel as notes: a broken pin or a
  failing check blocks; a style remark does not.
- How much of the dependency closure to recheck: for a zero-dependency package
  the closure is the package itself, stated in one line.
- Whether the suites earn trust: small named suites with fixed expectations
  count; expectations edited to match observed runs do not.

## Artifact

The artifact is the engineering opinion on the exact version reviewed: the
manifest and lock readings, the three recorded runs with the tool version, and
a verdict per engineering aspect. For the running example the opinion covers
the candidate snapshot only — any later edit needs a fresh pass, however small.

## EAI example

The running example is the employee accident insurance package: name kz.corpus.employee_accident_insurance, version 0.1.0, language 0.2, zero dependencies, explicit local imports. It covers the employer duty to insure, the twenty-two-class tariff with premium base as insured sum times rate plus the minimum floor, payout for capacity loss from thirty through one hundred percent, and penalty as unpaid times 0.015 times days. Sources are pinned to edition EAI_EDITION with materialization PINNED_UNOFFICIAL_COPY — an Adilet API copy retrieved 2026-09-13, sha256 pinned, local copy kept in the package. The static check reports OK and all thirty-seven candidate checks pass: loss thirty established against twenty-nine undecided, loss one hundred established against one hundred one undecided, per-row tariff premiums on an insured sum of one million, premium 59200 on a doubled sum against payroll one million, penalty of 3000 KZT on round figures and exactly 1.5 KZT on the fractional probe. The per-row tariff checks trip EAI-D1, the two boundary pairs trip EAI-D2, the fractional probe trips EAI-D3, the three premium-base probes trip EAI-D4.

Structure reading: four model files (vocabulary, sources, core rules, the R1
fix), seven suite files with thirty-seven checks in one family, a lock file with
empty dependency edges and empty package list, and the pinned Russian source
bytes beside the publication record. The manifest declares suites over a
single world matching the package name, and the authoring marker selects
explicit local imports.

## Pitfall

Trusting a green suite without reading the lock file. A suite can pass while
the manifest claims suites that never run, or while the lock file names
dependencies the manifest forgot. Read both files line by line: suite lists,
worlds, edges, and the root identity. A second trap is reviewing a dirty
directory — uncommitted edits make the opinion describe a version nobody can
reconstruct. List what changed before running anything, and record the exact
version in the opinion.

## Verify

The stage is done when the three runs are recorded with the tool version.
Observed runs on the accepted candidate with the pinned tool (`law` 0.1.0,
semantics law.core/0.2, published build):

```sh
$ law engine check docs/handbook/files/fixtures/eai-candidate
check OK: docs/handbook/files/fixtures/eai-candidate
$ law test docs/handbook/files/fixtures/eai-candidate
```

```text
  ok   [kz.corpus.employee_accident_insurance#authored] tests/tariff.lawtest / EAI-TARIFF-CLASS-01-PREMIUM
  ...
  ok   [kz.corpus.employee_accident_insurance#authored] tests/penalty-fractional.lawtest / EAI-PENALTY-FRACTIONAL-EXACT
total: 37 checked, 37 passed, 0 failed, 0 not run; code 0
```

A fresh copy of the candidate reproduces the tally exactly (thirty-seven of
thirty-seven, same build), and the local 0.1.0 build agrees. The pin
comparison runs on the local build only — the published build has no `gen`
command:

```sh
$ law gen pinning docs/handbook/files/fixtures/eai-candidate --check
```

The pin comparison prints nothing and exits zero: every pin holds.

Criterion: the static check reports OK, all thirty-seven lines read ok with
both boundary pairs disagreeing in the expected direction, and the pin
comparison exits zero without naming any drift. A fourth honest data point
comes from this handbook's own fixture work: a copy missing its lock file is
refused with LDC-E1104, and a copy missing its pinned source bytes is refused
with LDC-E5204 — both refusals observed, both proving the tooling reads the
files it claims to read.

## Limits

A technical review says nothing about meaning: pins can hold and suites can
pass while a whole branch of the act stays unmodeled — that was finding EAI-R1,
caught only by semantic review. It also covers one snapshot on one tool
release: a new tool release or a single edited line reopens the opinion. The
EAI opinion names the candidate snapshot id and tool release 0.1.0 together,
so a later reader knows exactly what was deemed sound.

## Next step

Continue with [Accept and release](/handbook/accept-release/), which turns the two review opinions into a release decision with a recorded identity.

## Sources

- [Semantic review](/handbook/semantic-review/) — the meaning pass this stage follows.
- [Pinning editions](/handbook/pin-editions/) — how pins are made and compared.
- [Reuse and dependencies](/handbook/reuse-dependencies/) — reading the lock file.
- [Command line](/cli/) — the check, test, and pinning commands used above.
- [Diagnostics](/diagnostics/) — reading refusals such as LDC-E1104 and LDC-E5204.