Phase 1, Step 1 - City of San Jose — August 2026 — current operational control.
This file is the record. Generated by
build/build_rules_v1_4.pyfrombuild/ledgex_source.py. Do not hand-edit. The PDF of the same name is a presentation artifact rendered from this same source; where they differ, regenerate — never patch one to match the other. (I17)
| Rank | Document | Role |
|---|---|---|
| 1 | Engineering Reference Spec v1.7 | Machine-executed build contract. |
| 2 | Implementation Rules v1.4 | Operational restatement of the Spec. |
| 3 | Business Plan 2.1.4 | Commercial master. |
| 4 | Municipal Data & API Audit v1.1 | Municipal evidence and rights. |
| 5 | San José Data Source Checklist v1.2 | Source planning. |
Evidence, rights and immutability gates apply before any product or measurement use. Each invariant has a CI check. A pull request that violates one does not merge.
| ID | Invariant | Required enforcement |
|---|---|---|
| I1 | core/ contains no jurisdiction name, local rule or local field name. | make check-boundary; import-linter |
| I2 | A Fact cannot exist without source_id + snapshot_id when retrieved, or method_version + complete lineage when derived. | DB CHECK; Pydantic model |
| I3 | Every fact carries a non-null licence_id. | DB NOT NULL + FK |
| I4 | Facts are immutable. Corrections supersede prior facts; they never overwrite or destructively update them. | fact_no_update trigger |
| I5 | A derived fact inherits the most restrictive licence of every input. Application code computes it at write time and the database validates it. | derive(); licence trigger; CI |
| I6 | The composer omits or refuses every fact whose licence forbids the output channel, including facts used only internally for resolution. Unknown rights block. Rights and confidence are independent gates. | rights gate; touched-fact test |
| I7 | Stated source cadence, source publication date and retrieval date are separate stored fields and are never conflated. | schema; cadence test |
| I8 | Refusal is a typed return value, not an exception. Every runtime stage can refuse deterministically. | Result[T]; refusal tests |
| I9 | A derived conclusion never renders in the visual or structural treatment reserved for a retrieved fact. | claim renderer; isolation test |
| I10 | Base Core remains composable when the geometry module is disabled, provided its own dependencies clear. Placement and every geometry-dependent conclusion refuse by name; no fallback geometry is inferred. | base-core / no-fallback tests |
| I11 | Every rule application records the exact ruleset_version and a human-readable citation. | schema NOT NULL; citation test |
| I12 | Every detected exception is a stored, measurable row with evidence and a closeable internal outcome. | schema; exception metrics |
| I13 | Only direct, bulk and deterministic derived facts may exist. No human observation, portal reading, manual lookup or request-time LLM judgment becomes a fact. | method CHECK; no-human-facts test |
| I14 | Customer delivery is automated end to end. No stage may block on, queue for, assign to, route to or be supplemented by a person. A machine-unavailable field is omitted, downgraded or refused. | no queue schema; delivery-path test |
| I15 | commerce may reference public; public may never reference commerce. A commerce row cannot create, alter or supply a property fact or conclusion. | catalogue query; import-linter |
| I16 | Subscription billing is independent of Property File outcome. Composed, partial and refused never create an individual-file charge, price adjustment, credit, settlement, refund or confidence exception. | billing-independence tests |
| I17 | The Spec and Rules are authoritative only when read verbatim from the filesystem. A graph, summary or derived context artifact cannot supply a rule, citation, licence term or CI gate. | check-boundary; no-graph test |
| I18 | Rule and disclosure review evidence is immutable and uses either independent review or same-identity solo-founder attestation with a non-null attestation URI. Review never enters customer delivery. | DB CHECKs; review-mode matrix |
| I19 | Evaluation-to-permit outcome observations exist only in commerce as Track B measurement. They never enter core/compose, never render in a Property File and never become public facts or provenance inputs. | schema separation; no-render test |
| I20 | A footprint provider cannot occupy the active geometry slot unless an immutable approved measured-error record exists for the same provider version, method and jurisdiction. Runtime substitution is forbidden. | constraint trigger; provider-slot tests |
A target name without execution scope and a pass condition is not a definition of done.
| Target | Execution surface | Pass condition |
|---|---|---|
| make check-boundary | Jurisdiction-name grep, import-linter, public-to-commerce catalogue query, filesystem authority, no-graph and Track B no-render checks. | I1, I15, I17 and I19 pass; zero forbidden imports, FKs or derived authority. |
| make schema | Apply every forward-only migration to an empty database. | Clean apply; constraints, functions and triggers compile. |
| make schema-dump | Regenerate db/schema.sql from the applied database and compare the committed dump. | No diff; missing or stale generated DDL fails. |
| make conformance | Parameterized pack suite for sources, mappings, rights, dependency cascades and endpoint liveness. | Every enabled pack passes; no rights broadening or silent missing dependency. |
| make test | Unit and integration suites, including review, entitlement, outcome observation, provider slot, edge guard and billing independence. | All required tests pass with zero skips and no external network dependency in CI. |
| make golden | Normalized composed, partial, refused and geometry-disabled Base Core fixtures. | Output matches approved fixtures; intended changes require reviewed fixture updates. |
| Item | Title | Scope |
|---|---|---|
| A-1.1 | Control recovery / canonical invariants | Canonical I1-I20, internal-fact licence-gate rationale and six make targets. |
| A-1.2 | Evaluation-to-permit outcome loop | Immutable Track B evaluation-to-permit observations in commerce only. |
| A-1.3 | Validated footprint-provider slot | One validated footprint-provider slot; switching is controlled, never runtime fallback. No activation without approved measured-error evidence. |
| A-1.4 | Edge request guard | Edge infrastructure protection before entitlement and core/compose; rejection is HTTP 429, not a file outcome and not a fourth outcome. |
ONE INVARIANT SOURCE
build/ledgex_source.pyownsINVARIANTSandMAKE_TARGETS.build_spec_v1_7.pyimports the same objects. A change that produces different invariant text in the two artifacts fails document QA (python build/qa_check.py).
Converted verbatim from the v1.4 source document. Section numbering follows the original.
LEDGEX / ADU.X
Implementation Rules v1.4 Operational restatement of Engineering Reference Spec v1.7 and Architecture Addendum A-1
CONTROL
Commercial master: Business Plan 2.1.4. Build contract: Engineering Reference Spec v1.7. Rules v1.4 supersedes Rules v1.3 for engineering execution only. Checklist v1.2 and Audit v1.1 remain unchanged. No commercial threshold, price, credit, allowance, tier, runtime fallback or human delivery path is introduced.
A-1 scope
A-1.1: canonical I1-I20, internal-fact licence-gate rationale and six make targets.
A-1.2: immutable Track B evaluation-to-permit observations in commerce only.
A-1.3: one validated footprint-provider slot; switching is controlled, never runtime fallback.
A-1.4: edge infrastructure protection before entitlement and core/compose; rejection is HTTP 429, not a file outcome.
ONE INVARIANT SOURCE
This builder owns INVARIANTS. build_spec_v1_7.py imports the same object. A change that produces different invariant text in the two PDFs fails document QA.
Evidence, rights and immutability gates apply before any product or measurement use.
ID Invariant Required enforcement
I1 core/ contains no jurisdiction name, local rule or local field name. make check-boundary; import-linter
I2 A Fact cannot exist without source_id + snapshot_id when retrieved, or method_version + complete lineage DB CHECK; Pydantic model when derived.
I3 Every fact carries a non-null licence_id. DB NOT NULL + FK
I4 Facts are immutable. Corrections supersede prior facts; they never overwrite or destructively update them. fact_no_update trigger
I5 A derived fact inherits the most restrictive licence of every input. Application code computes it at write time derive(); licence trigger; CI and the database validates it.
I6 The composer omits or refuses every fact whose licence forbids the output channel, including facts used only rights gate; touched-fact test internally for resolution. Unknown rights block. Rights and confidence are independent gates.
I7 Stated source cadence, source publication date and retrieval date are separate stored fields and are never schema; cadence test conflated.
Refusal, claim treatment, geometry degradation and automated delivery remain deterministic.
ID Invariant Required enforcement
I8 Refusal is a typed return value, not an exception. Every runtime stage can refuse deterministically. Result[T]; refusal tests
I9 A derived conclusion never renders in the visual or structural treatment reserved for a retrieved fact. claim renderer; isolation test
I10 Base Core remains composable when the geometry module is disabled, provided its own dependencies clear. base-core / no-fallback tests Placement and every geometry-dependent conclusion refuse by name; no fallback geometry is inferred.
I11 Every rule application records the exact ruleset_version and a human-readable citation. schema NOT NULL; citation test
I12 Every detected exception is a stored, measurable row with evidence and a closeable internal outcome. schema; exception metrics
I13 Only direct, bulk and deterministic derived facts may exist. No human observation, portal reading, manual method CHECK; no-human-facts test lookup or request-time LLM judgment becomes a fact.
I14 Customer delivery is automated end to end. No stage may block on, queue for, assign to, route to or be no queue schema; delivery-path test supplemented by a person. A machine-unavailable field is omitted, downgraded or refused.
Commerce separation, billing independence, context authority, review evidence and the two A-1 gates.
ID Invariant Required enforcement
I15 commerce may reference public; public may never reference commerce. A commerce row cannot create, catalogue query; import-linter alter or supply a property fact or conclusion.
I16 Subscription billing is independent of Property File outcome. Composed, partial and refused never create an billing-independence tests individual-file charge, price adjustment, credit, settlement, refund or confidence exception.
I17 The Spec and Rules are authoritative only when read verbatim from the filesystem. A graph, summary or check-boundary; no-graph test derived context artifact cannot supply a rule, citation, licence term or CI gate.
I18 Rule and disclosure review evidence is immutable and uses either independent review or same-identity DB CHECKs; review-mode matrix solo-founder attestation with a non-null attestation URI. Review never enters customer delivery.
I19 Evaluation-to-permit outcome observations exist only in commerce as Track B measurement. They never schema separation; no-render test enter core/compose, never render in a Property File and never become public facts or provenance inputs.
I20 A footprint provider cannot occupy the active geometry slot unless an immutable approved measured-error constraint trigger; provider-slot tests record exists for the same provider version, method and jurisdiction. Runtime substitution is forbidden.
Every invariant is operative text. A pointer to absent text or a copied table that differs from Spec v1.7 is non-conforming.
A target name without execution scope and a pass condition is not a definition of done.
Target What it executes Pass condition
make check-boundary Jurisdiction-name grep, import-linter, public-to-commerce catalogue query, filesystem I1, I15, I17 and I19 pass; zero forbidden authority, no-graph and Track B no-render checks. imports, FKs or derived authority.
make schema Apply every forward-only migration to an empty database. Clean apply; constraints, functions and triggers compile.
make schema-dump Regenerate db/schema.sql from the applied database and compare the committed No diff; missing or stale generated DDL fails. dump.
make conformance Parameterized pack suite for sources, mappings, rights, dependency cascades and Every enabled pack passes; no rights endpoint liveness. broadening or silent missing dependency.
make test Unit and integration suites, including review, entitlement, outcome observation, All required tests pass with zero skips and no provider slot, edge guard and billing independence. external network dependency in CI.
make golden Normalized composed, partial, refused and geometry-disabled Base Core fixtures. Output matches approved fixtures; intended changes require reviewed fixture updates.
All six targets run locally and in CI with zero required skips. A missing target, stale schema dump or omitted test is a failure, not a green build.
Why the gate covers internal facts
Jurisdiction resolution is load-bearing. If city_limits is touched to decide whether a parcel belongs to San Jose, that fact participates in composition even when it is not printed. Allowing an unknown-rights boundary fact to pass internally would let every downstream fact inherit a commercial use that was never cleared. LICENCE_UNKNOWN at L0 is therefore the intended fail-closed result, not a defect. Do not add an override flag, gate-only source class or internal-use exemption. Confirm rights or refuse.
HISTORICAL DEFECT NOTE
The first generated Spec v1.6 file abbreviated the invariant table and contained two top-level sections numbered 14. Its corrected file version repaired both. Spec v1.7 carries the full table forward and preserves one §14 with §14.1 and §14.2.
Prohibited response to L0
Do not treat LICENCE_UNKNOWN as an availability error.
Do not retry through a different unvalidated or uncleared source.
Do not let subscription status, customer identity or output scope weaken I6.
Do not store a manually observed jurisdiction answer as a fact.
Begin recording Base evaluation intent in Phase 1. A scheduled matcher later joins immutable Property File requests to CC0 permit facts over a versioned lag-window method. It produces Track B observations showing which evaluated parcels later became projects. No user report-back is required, and no observation is a customer fact.
Operational rules
The loop lives in commerce/. It may read public facts; public never references commerce.
Every observation stores method_version, config hash, exact window, source snapshot and any matched permit fact.
Observations are immutable. A better matcher creates a new run and new observations; it never rewrites history.
Only a CC0 permit source may label a match under this loop. Rights failure aborts the run.
Track B aggregates internally. core/compose and renderers cannot import or query observation modules.
No lag duration, conversion threshold or success criterion is set in these Rules.
CANNOT BE BACKFILLED
Permit history can be re-read, but professional evaluation intent cannot be reconstructed if the original request row was never recorded. The request record and matcher schema ship in Phase 1 even if no match appears for a long period.
I19 makes this boundary a merge gate rather than a convention.
A jurisdiction has one active footprint-provider slot. Any provider version may be registered inactive. It can occupy the slot only after an immutable approved measured-error record exists for the same provider version, method and jurisdiction.
Activation and runtime rules
geometry_tier_enabled remains false while the slot is empty or its provider lacks approved validation.
Measured-error values and benchmark evidence are stored; this revision invents no numeric acceptance threshold.
A second provider can be validated and selected by a controlled configuration change without schema or composer rewrite.
Selection is not fallback. If the active provider fails during a request, placement and dependent conclusions refuse; runtime never chooses another provider.
Base Core continues under I10 when a provider is present but inactive.
REQUIRED TESTS
test_geometry_provider_requires_validation; test_geometry_slot_single_active; test_base_core_without_ld4; test_no_geometry_fallback. The last two run with a footprint_provider row present but inactive.
I20 makes activation fail in the database; an application convention is insufficient.
Product entitlement and infrastructure protection are separate. The edge request guard runs before resolve, entitlement checks and core/compose. A rejected request returns HTTP 429 and creates no Property File request, file, refusal or fourth outcome.
Contract
Protect limited-free endpoints and any other route selected by an approved edge policy.
Policy identity, version and hash are required deployment configuration; these Rules set no numeric rate, window or allowance.
A missing or invalid production policy fails service startup for a protected route.
Edge rejection occurs before source retrieval and composition cost is incurred.
429 telemetry is infrastructure telemetry. It is not an entitlement balance, credit event or Property File outcome.
No staff queue, exception or manual release path exists.
REQUIRED TESTS
test_edge_guard_precedes_resolve; test_edge_429_creates_no_file_or_request; test_edge_guard_independent_of_entitlement; test_protected_route_requires_policy.
REQUIRED BEFORE MERGE
make schema applies the A-1 migrations cleanly to an empty database.
test_schema_separation passes with all new references oriented commerce -> public.
test_base_core_without_ld4 and test_no_geometry_fallback pass with footprint_provider present but inactive.
These are repository merge gates. This document records the requirement; it does not claim the application tests have already run.
READ VERBATIM
Business Plan 2.1.4 - commercial boundary Engineering Reference Spec v1.7 - executable contract Implementation Rules v1.4 - operational restatement
PRESERVE I1-I20; automated composed / partial / refused commerce-only Track B observations; no customer rendering one validated geometry provider slot; no runtime substitution edge 429 before core/compose; no file outcome
RUN BEFORE MERGE
make schema test_schema_separation test_base_core_without_ld4 with inactive provider test_no_geometry_fallback with inactive provider
Revision record: v1.4 folds Architecture Addendum A-1 into the operational control without changing the commercial model or customer-delivery boundary.
Generated 2026-08-03 by build/build_rules_v1_4.py. Source of record: build/ledgex_source.py.