> Public reading copy of the V3 typed contract. Normative rules are unchanged from the repository source. > Original source SHA-256: `1c0fcbb098d087b383620648407b6e8e061b73581a016ad392e0b06d1d0a0cbc`. Source-only references are shown as paths. > [Scope manifest](la4kb-v3-scope-manifest.json) · [manifest signature](la4kb-v3-scope-manifest.signature.json). # LA4KB V3 typed candidate contract **Current status (2026-10-21):** this contract version retains the word `candidate` in its published wire identifier for compatibility. The isolated typed V3 API is now public at `/api/v3/`, with build `v3t-1013d7ecf712`. The AH build and the prepublication decisions recorded below are historical checkpoints, not the current public build or gate status. V1/V2 remain historical public APIs; their API-info responses still advertise POST routes, whose present write behavior was not checked in this documentation review. See `docs/releases/V3_PUBLIC_STATUS_20261021.md` (source path). ## Version and signed registry - `contract_version`: `la4kb-v3-typed-candidate-1`, required at the request root. - Public schema: `la4kb-public-api-v3-typed-candidate-1`; the public API reported build `v3t-1013d7ecf712` on 2026-10-21. The `v3t-` suffix is the first 12 hex characters of SHA-256 over the 32-byte manifest digest, the normalized admission-source digest, and the normalized execution-tree digest, in that order. The formula is implemented in `blackbox/typed_contract_v3.py` (source path). Earlier AH, AG, AF, AE and AD build IDs and their digests are preserved in the review history and signed receipts, not substituted for the current public build. The untyped V3 candidate has a separate `v3u-` identity and is not eligible for the isolated typed route. - `scope_schema_id`: required. The only accepted values are the exact versioned keys in [the public scope manifest](la4kb-v3-scope-manifest.json). Unknown IDs or other versions reject HTTP 422. - The registry of permitted types for every scope field and dimension is in that manifest. Its SHA-256 is pinned in V3 admission code and API metadata; the accompanying Ed25519 signature and public key permit offline integrity checking. This manifest signature is a **review artifact**, distinct from the production receipt-signing key. - Admission-source bytes are rechecked during admission. The execution-tree digest is calculated when the process starts and includes every `.py` file under `blackbox/` and `src/`, sorted by relative path, with CRLF normalized to LF and `__pycache__` excluded. The startup scan rejects a loadable first-party `.pyc` whose code object differs from compilation of its source, native extension modules under the hashed first-party tree, an earlier `sys.path` package or ZIP that shadows that tree, and already loaded first-party modules outside that tree. Once loaded, the V3 engine class's methods are compared by full Python code object against a fresh compilation of their corresponding hashed source methods; this rejects the reproduced AH01 `sys.meta_path` loader that spoofed `__file__` while changing a verdict in memory. Source identity is established before other first-party modules are imported by the V3 schema entry point. An engine change before startup therefore changes the build ID; tested bytecode, extension, earlier-path and AH01 substitutions fail startup. The execution tree is not rescanned on every request. A running process must use an immutable installation and restart after any source change. The trusted entry point and installation path are deployment assumptions: in-process checks cannot defend against replacement of the entire entry-point package, arbitrary import hooks, or a process under attacker control. The build ID identifies first-party source, not third-party package binaries, the interpreter, or post-start file mutations; the exact dependency environment and locked runtime must also be recorded for complete replay. - The `*.v1` schema IDs and exact manifest bytes are part of the published V3 contract observed on 2026-10-21. The earlier AC revision changed their allowed types **before** that publication. A future incompatible registry change requires new versioned IDs and review; the `*.v1` names alone must not be reused with different semantics. - The published V3 runtime is locked to Python 3.12.10 / Unicode 15.0.0. A future security update needs a new reviewed build and portability check. ## Wire grammar Every subject, scope value and present `measurement_identity` is a JSON object with an explicit `type`. Bare strings, numbers, booleans and null in these positions reject 422. No type is guessed from spelling. The admissible type for a scope coordinate is also constrained by the versioned registry. | Type | Exact form | Rule | | --- | --- | --- | | `git_commit` | `{"type":"git_commit","algorithm":"sha1","value":"9da8"}` (or `sha256`) | Lowercase hexadecimal, 4–40 characters for SHA-1 or 4–64 for SHA-256. Identical values match. Distinct non-prefix values, including 4/5-character values, differ. A strict prefix pair of length at least 4 rejects 422 across the request, regardless of coordinate. Mixing algorithms rejects 422. A producer declaration does not prove repository membership. | | `semver` | `{"type":"semver","value":"1.2.3-rc.1"}` | Strict `MAJOR.MINOR.PATCH`, with an optional SemVer prerelease. Comparison is exact, including prerelease. `+build` and leading-zero numeric identifiers reject 422. `1.2` is not inferred to be `1.2.0`. | | `integer` | `{"type":"integer","value":1000}` | Signed 64-bit JSON integer token only. `1e3`, `1000.0`, strings, booleans and out-of-range integers reject 422. | | `boolean` | `{"type":"boolean","value":true}` | JSON boolean only; never equal to integer 1 or 0. | | `label` | `{"type":"label","value":"lot-a12345"}` | ASCII `[A-Za-z0-9][A-Za-z0-9._-]{0,127}`; exact comparison without trim or case conversion. Ambiguous pairs within the same coordinate reject 422 under the skeleton rules below. `lot-a12345` and `lot-a123456` are distinct and remain admissible. | | `measurement_id` | `{"type":"measurement_id","value":"sensor-a"}` | Same ASCII grammar as `label`. Case/separator and digit-run skeleton collisions reject 422, including `sensor-1`/`sensor-01`. Other numeric and version-like skeletons do not apply; used only for `measurement_identity`. | | `date` | `{"type":"date","value":"2026-10-10"}` | A real ISO calendar date. | | `date_interval` | `{"type":"date_interval","start":"2026-01-01","end":"2026-12-31"}` | Real ISO dates with start no later than end. Identical intervals compare exactly; distinct intervals in one window coordinate reject 422 until an interval relation is part of the contract. | | `compound` | `{"type":"compound","parts":[{"type":"label","value":"svc"},{"type":"git_commit","algorithm":"sha1","value":"9da82"}]}` | Two to eight ordered typed parts. Exact part count and type sequence must agree within one coordinate. A mismatch rejects 422, including compound versus scalar. Part values compare exactly by their own type. No string is split into parts by the kernel. | The `predicate` is still an ASCII registered predicate string; `evidence_id` and source IDs remain ASCII strings with the historical validation and unique evidence-ID rule. Only the typed coordinates above use this new object grammar. The `scope` uses `dimensions` plus typed `software_version`, `document_revision`, `measurement_window`, `commit`, `build_number`, or `release_label`. The three release fields are mutually exclusive and map to one release coordinate. Legacy `release_or_commit` rejects 422. ### Meaning of an empty scope `{"scope":{"dimensions":{}}}` with no scope metadata and without `"is_explicit_global":true` means **unknown population**, not global coverage. Two matching empty scopes still have the pairwise relation `UNKNOWN_SCOPE`; their matching numeric values alone cannot establish `SUPPORTED`. This is an admitted request that can receive `INSUFFICIENT_EVIDENCE`, not an HTTP 422. If the source actually establishes a global population, declare `{"scope":{"dimensions":{},"is_explicit_global":true}}` on that source and the corresponding claim. For a known subset, declare its typed coordinates instead. Never add `is_explicit_global` merely to obtain a stronger verdict: the producer must be able to justify the scope from the cited source. A single `INSTANCE` still cannot prove a `UNIVERSAL` claim just because both scopes are explicitly global. The public feed-lots example intentionally returns `INSUFFICIENT_EVIDENCE`: one measured lot does not establish all lots. An equal-endpoint claim `RANGE` with either endpoint excluded is admitted but its solution set is empty. Comparable, nonempty evidence cannot support or refute that claim: the current V3 engine returns `INSUFFICIENT_EVIDENCE`. Reversed bounds (`low > high`) are malformed and reject HTTP 422. This clarifies the historical V2 contract erratum without changing the engine. ### Two kinds of conflict in V3 The sentence in the frozen V2 contract (section 5.3) that requires the same `measurement_identity` describes **conflicting reports of one observation**. V3 retains that check: two equal-tier, admissible, incompatible reports of the same observation can be `CONFLICTED` even when neither individually decides the claim. Different identities do not become one physical observation merely because their numeric values differ. V3 also has a separate **claim-level disagreement** rule. For an `UNQUANTIFIED` claim, two admissible `INSTANCE` reports with different measurement identities can yield `CONFLICTED` when they have the same subject and predicate, compatible declared scopes, equal dominant authority, disjoint solution sets, and one supports while the other contradicts the claim. This does not assert that the two physical observations are the same; it says equal-authority evidence points in opposite directions about this one unquantified claim. Two different readings that both support the claim do not trigger this rule. For example, with equal-tier instances of 42 and 250 from distinct identities: `GE 0` is `SUPPORTED`, while `EQ 42` is `CONFLICTED`. With 42 and 50, `LE 100` is `SUPPORTED`. Other claim-level conflicts include incompatible equal-tier constraints and competing same-population statistical aggregates, regardless of measurement identity. Distinct `INSTANCE` identities do not by themselves defeat an `EXISTENTIAL` witness; a `UNIVERSAL` claim still follows its counterexample rule. The V2 sentence is historical and is not an exhaustive V3 conflict definition. For a `STATISTICAL` claim, an individual `INSTANCE` cannot establish or refute the aggregate proposition, including when an authoritative aggregate is present in the same request. An aggregate that supports `LE 100` at `42` therefore remains `SUPPORTED` alongside an individual reading of `250`; two comparable, equally authoritative aggregates at `42` and `250` are `CONFLICTED`. This is a rule about the declared statistical proposition, not a finding that the individual reading is false. Exact requests, original signed receipts, and public replays of these examples are preserved in `evidence/reviews/2026-10-22-v3-af-independent/README.md` (source path). Label ambiguity checks never equate two different strings. Within one coordinate, two distinct labels reject 422 if their case/separator skeletons match; their decimal or numeric-value skeletons match (including exponent, hexadecimal/octal/binary, `k/M/G/T`, infinity and NaN spellings); or their digit-run skeletons match after leading zeroes are removed before separators. Grouped digits such as `1.000`/`1e3` and a lowercase `m` read as either milli or mega are rejected when either reading collides. In `software_version`, `document_revision` and `release_label`, version skeletons additionally recognize common version and document-revision prefixes, PEP 440-like prerelease/postrelease aliases and implicit zero components. Within a common label, embedded version patterns such as `rhel-9`/`rhel-9.0` also trigger rejection. Thus `v1.2`/`1.2`, `revA`/`A` in a document revision, `1.2a`/`1.2a0`, `1000`/`1e3`, `1.000`/`1e3`, `16`/`0x10`, `ubuntu-22.04`/`ubuntu-22.4`, `8`/`08`, and `500m`/`0.5` reject 422 when paired in the relevant coordinate. Distinct `run` labels `1` and `10` remain admissible. These are conservative ambiguity rejections, not conversions or equality rules. A hash embedded in a common label remains a producer-declaration limit. Some embedded version spellings are rejected by the ambiguity checks, but those checks do not establish the meaning of arbitrary labels. A producer can declare a subject as a typed `compound`. The present registry does not permit a compound `deployment`; that case requires a future schema or separately declared coordinates. A Git hash falsely declared inside a label can still escape the hash-prefix rule. Exotic numeric spellings listed as AE08 in the review archive are also a documented limit of this candidate. In the signed scope registry, `threads` is a 64-bit `integer`; `tier` permits either `integer` or `label`, with mixed types in one coordinate rejected; `run` is a run identifier of type `label`, including named lots and distinct labels such as `1` and `10`. A quantity of threads must be a JSON integer rather than a numeric-looking label. If `measurement_identity` is present, it must be a `measurement_id` object; explicit `null` rejects 422. The claim must explicitly provide `source_id` and `operator_provenance: {"type":"operator_declared","operator":"","source_id":""}`. Omission, a bare string, an unknown type, or disagreement with the claim rejects 422. `operator_declared` attests **only to the shape and source reference of the operator declaration**. It does not attest that the source exists, that the operator was faithfully extracted, or that the evidence is true. The same caveat applies to any value falsely declared as a `label`, including a Git hash: the kernel cannot detect producer misclassification without external evidence. No string is coerced into an integer, date, version, hash, or boolean, and no spelling is normalized to make two values agree. The adapter encodes already validated typed objects into deterministic opaque tokens for the V3 semantic engine. The signed `payload_hash` commits to the **typed wire payload**, not to those internal tokens. Raw JSON duplicate keys and lossy decimal literals are rejected before admission. ## Migration and compatibility All 108 immutable AB originals are preserved. They reject 422 under the new contract because they contain untyped identities and/or defaulted provenance. Explicit migrated copies and a per-case transition table live in `conformance/v3_typed` (source path). The migrated results are AB01: 77 rejects, 8 supports; AB02: 7 rejects; AB03: 13 rejects; AB04: 3 supports. Rejections in AB01 replace ambiguous missing-provenance text. The three AB04 controls establish that different lot, batch and release labels are still admissible. Earlier V3 payloads must be migrated explicitly by their producer. This was a breaking candidate contract; no automatic migration runs in the gateway. V1/V2 semantics and their known defects are not repaired by V3. At this AC review checkpoint, C01 was still open and candidate V1 `9b386b3` and V2 `7a999eb` were excluded from deployment. Owner approval and V3 publication occurred later, on 2026-10-19; this paragraph is retained as a dated decision, not a current publication block. ### Dated review checkpoints (AC–AU; not current publication status) The AC revision changed admission while the contract was still an unpublished candidate: ambiguous version/run labels and untyped `threads` reject 422; `tier` labels and distinct numeric run IDs are admitted; explicit null measurement IDs reject 422. Exact per-payload transitions and all three complete migrated demo banks are recorded in `evidence/campaigns/internal/codex/2026-10-10-ac-series-v01/`. The manifest hash and build ID changed together; prior signed receipts remain historical artifacts of their original build. The AD revision further rejects ambiguous numeric and version-like labels under the documented rules. It does not alter the signed type registry or the unpublished wire grammar; its build ID changes because the admission-source bytes changed. Prior AC receipts retain their old build ID and are historical, not receipts for this AD build. The AE revision extends ambiguity rejection to grouped digits, additional revision and version aliases, embedded version patterns, zero-padded measurement IDs and lowercase `m` as a possible milli suffix. AE01 adds this V3-only reconciliation rule: when a broad authoritative constraint supports a universal claim but an equally or more authoritative constraint over a strict subpopulation has a disjoint solution set, the rules yield `CONFLICTED` with both evidence IDs in `conflicted_pairs`. A regional rule alone remains `INSUFFICIENT_EVIDENCE`; an observed regional instance that refutes the universal claim remains `CONTRADICTED` because it is an actual counterexample. The owner selected this distinction for AE01. The AE build ID additionally commits to the first-party execution-tree source; AD receipts remain historical. At that AE checkpoint, C01 still blocked publication. The AF revision refines the rule-conflict decision. For a universal claim already `SUPPORTED` or `SUPPORTED_WITH_SCOPE`, a competing authoritative constraint over an overlapping scope disputes support when its value set is incompatible with a supporting constraint and admits values outside the claim. It must be at least as authoritative as the strongest covering supporting constraint. A weaker regional rule cannot create a conflict just because a weaker broad agreement is added; equally ranked conflicting rules cannot be ignored merely because both overlap the claim. Every disputing pair is recorded. A regional observed instance remains a counterexample under the existing authority rules. Cached first-party bytecode that CPython would load is checked against source at startup. The untyped legacy V3 candidate also uses a source-derived build ID; it remains ineligible for the typed route. Historical receipts retain their original IDs. At that AF checkpoint, C01 still blocked publication. The AS review clarifies authority gating: reports compete first within the same observation. At claim level, the strongest rank is selected only among evidence capable of deciding that claim. Positive point measurements cannot establish a universal claim, so a higher-tier positive measurement from another observation cannot hide a lower-tier covering rule or counterexample. A higher-tier covering rule may still dominate a lower-tier counterexample under the existing policy. Universal support is explained as coverage by an authoritative constraint, not as agreement by every observed instance. This changes the candidate source-derived build ID and requires new review receipts before publication; C01 was still open at that AS checkpoint. The AT review adds the disputed-counterexample rule: if two equal-tier reports of one observation disagree between support and contradiction, a lower-tier independent rule cannot resolve that dispute as unconditional support. The verdict remains `CONFLICTED`, with the disputed pair recorded. A same-tier or stronger independent claim-deciding observation can still decide; a disagreement among two positive reports does not alone block a covering rule. The hosted and isolated V3 HTTP listeners also disable Uvicorn proxy-header interpretation, so client-IP admission uses the actual socket peer rather than `X-Forwarded-For`. At that AT checkpoint, this was a candidate change and C01 was open. The AU review extends that reconciliation to every admissible report of the same measurement and authority tier. A universal claim is `CONTRADICTED` by a disputed measurement only if all reports in that measurement group independently refute it. If one report supports while another refutes, the observation is `CONFLICTED` at that tier; selecting a counterexample-only pair must not produce a stronger verdict. The exact U12–U12f payloads and their reversed-order controls are kept in the AU archive. At that AU checkpoint, this was a candidate change and C01 was open. ## Example ```json { "contract_version": "la4kb-v3-typed-candidate-1", "scope_schema_id": "la4kb.generic.v1", "claim": { "subject": {"type": "label", "value": "svc"}, "predicate": "latency", "operator": "LE", "value": 100, "source_id": "claim-operator-1", "operator_provenance": {"type": "operator_declared", "operator": "LE", "source_id": "claim-operator-1"}, "scope": {"dimensions": {"region": {"type": "label", "value": "EU"}}} }, "evidence_items": [{ "evidence_id": "measurement-1", "subject": {"type": "label", "value": "svc"}, "predicate": "latency", "operator": "EQ", "value": 75, "authority_tier": "PRIMARY_SOURCE", "evidence_nature": "INSTANCE", "measurement_identity": {"type": "measurement_id", "value": "sensor-a"}, "scope": {"dimensions": {"region": {"type": "label", "value": "EU"}}} }] } ```