Methodology

Scope, source locking, evidence states, and translation maintenance for the SQLSTATE atlas.

Scope and frozen inputs

The atlas starts from PostgreSQL release definitions and separates directory identity, source implementation, official documentation, and local runtime observation. The locked manifest contains 351 formal tags, one PostgreSQL 19 Beta 3 preview, 19 definition blobs, a 263-code union, and 44 classes. The public display is a smaller matrix of 16 formal major snapshots (9.0–18) plus the preview; it is not the complete tag history. PostgreSQL 18.6 is fixed at REL_18_6 commit 724edf9bde9d356724ad384a2e196edc3c9f80f7, with definitions in src/backend/utils/errcodes.txt; PostgreSQL 19 Beta 3 is a separate preview at 3638289fb57bdabec00deda98ee9624a35f5d66a.

Formal history has an 18.4→18.6 tag gap. Pre-9 collection covers 191 tags from 7.0 through 8.4.22: 7.4–8.4 have definition files, while 7.0–7.3 have candidate-path probes. Missing old paths are source gaps, not proof of absence. known_present_by is a presence boundary; exact introduction or removal is recorded only when adjacent source evidence proves both sides.

Evidence states

Each claim names the source path and fixed release, tag, or commit that supports it. definition_only establishes catalogue identity and history, not a reporting path. source_path_confirmed identifies a concrete call or implementation context. observed_runtime requires a real run record, applicable passed assertions, and the actual SQLSTATE; source scans and skipped cases cannot promote themselves to runtime coverage. unknown records an unresolved scope, not absolute absence.

Lexical source candidates are read in C context before adoption. The private call scan is bounded research input, not reader-facing proof. Core, contrib, extension, custom-function, ECPG, driver, and remote-server paths remain distinct. An ECPG program or client can reuse a PostgreSQL-defined code, and an FDW or driver can forward a remote code, without proving that server core reports that code in the same operation. Conversely, a core source path does not prove every wrapper or client exposes every field.

Official PO text can confirm a fixed commit, message domain, and placeholder boundary, but not Chinese runtime output. Locale, driver behavior, server version, and message delivery must be observed separately. Internal messages and dynamic fields retain their source conditions; translated or formatted strings are never stable protocol keys.

Runtime and recovery boundaries

Runtime observations use isolated versioned targets and preserve enough environment and structured result to identify the asserted case and version. A passed observation covers that case and version only. not_run, not_applicable, source-only, and driver-null-SQLSTATE cases remain explicit. Startup authentication/resource failures are outside a SQL transaction; a server log can carry SQLSTATE even when a startup exception has no driver SQLSTATE. In an explicit transaction, a root error and later 25P02 are separate observations; a savepoint handler, PL/pgSQL exception block, and whole-transaction retry have different scopes.

A deliberate PL/pgSQL custom code can demonstrate protocol delivery and handler matching, but is not evidence that core, contrib, FDW, ECPG, or a driver naturally reports the same code. Such observations are labeled as deliberate behavior rather than natural subsystem behavior.

Translation and maintenance

English is the source page. Each Chinese pair preserves anchors, SQLSTATE identity, facts, citations, diagnostic fields, and recovery boundaries in natural Chinese. Chinese front matter stores the English page’s deterministic UTF-8 SHA-256 over normalized {title, description, body}; changing English title, description, or prose makes the pair stale until translated and refreshed. Generated fact blocks are delimited and may be refreshed from data/errcodes; author prose and evidence are maintained separately.

A useful maintenance change updates fixed source citations, evidence state, and both language pages together. It does not infer a runtime mechanism from a renamed condition, old PO entry, generic API signature, or client wrapper. Published catalogue and evidence views are presentation layers over accepted records; they are not evidence creation.

Primary records

The public version matrix, catalogue, evidence index, and runtime case index expose accepted projections. Maintainers use reports/CATALOGUE.md, reports/SOURCE-SCAN.md, reports/RUNTIME-BOUNDARIES.md, and reports/RUNTIME.md for the underlying records; these report paths are repository locations, not public page links. The manifest lock is sources/manifest.lock.json (SHA-256 1727a275f336988ff96b4f9990a4ca253080f73fc5d316e7def165c8cf3708a8); the pre-9 lock is sources/pre9-manifest.lock.json (SHA-256 77bedf102d109972e91ff1b61841d78a38da7c7c049e428782392761a4ce7cd6).