oc_chat
Loading...
Searching...
No Matches
oc_chat.registry.invariant_matrix Namespace Reference

Classes

class  DdlConstraint
class  Marker
class  MatrixRow
class  Matrix

Functions

str _slug (str text)
list[str] _split_table_body (str body)
list[DdlConstraint] _parse_column_clause (str table, str clause)
list[DdlConstraint] _parse_table_constraint_clause (str table, str clause)
list[DdlConstraint] _parse_create_tables (str sql)
list[DdlConstraint] _parse_indexes_and_triggers (str sql)
list[DdlConstraint] _parse_store_scope ()
list[DdlConstraint] parse_ddl_inventory (Path sql_path=SCHEMA_V0_3_1_SQL, *, bool include_store_scope=True)
list[Marker] extract_markers (str text, *, str form, str source)
list[Marker] extract_doc_markers (Path doc_path=V0_3_1_DOC)
list[Marker] extract_code_markers (tuple[Path,...] files=ENFORCEMENT_CODE_FILES)
str _hash_lines (list[str] lines)
str constraint_inventory_hash (list[DdlConstraint] ddl)
str app_invariant_inventory_hash (list[Marker] markers)
MatrixRow _D (str witness_id, str handling, **object kw)
MatrixRow _R (str rule, str ac, str code, str neg_fixture, str handling)
MatrixRow _X (str ratification, str handling)
MatrixRow _NA (str handling)
dict[str, MatrixRow] _build_classification ()
Matrix generate_matrix (Path sql_path=SCHEMA_V0_3_1_SQL, Path doc_path=V0_3_1_DOC, tuple[Path,...] code_files=ENFORCEMENT_CODE_FILES)
list[str] verify_matrix (Matrix matrix)
list[str] code_markers_not_in_matrix (Matrix matrix)
list[str] unimplemented_r_rows (Matrix matrix)
set[str] app_layer_invariant_ids (Optional[dict[str, MatrixRow]] classification=None)
dict[str, object] build_audit_payload (Optional[Matrix] matrix=None)

Variables

str _ORCH = Path(__file__).resolve().parents[1] / "docs" / "architecture" / "orchestration"
str SCHEMA_V0_3_1_SQL = _ORCH / "REGISTRY_SCHEMA_V0_3_1.sql"
str V0_3_1_DOC = _ORCH / "REGISTRY_ROADMAP_SCHEMA_V0_3_1.md"
str _REGEN = Path(__file__).resolve().parent / "regenerate"
tuple ENFORCEMENT_CODE_FILES
frozenset SOURCE_POPULATED_TABLES
frozenset NEVER_WRITTEN_TABLES
frozenset RUNTIME_TABLES
frozenset VALID_CLASSES = frozenset({"D", "R", "X", "NA"})
frozenset WITNESS_TYPES
 _CREATE_TABLE_RE
 _CREATE_UNIQUE_INDEX_RE
 _CREATE_TRIGGER_RE
 _ALTER_ADD_COLUMN_RE
tuple _SQL_RESERVED_CLAUSE_HEADS = ("CHECK", "PRIMARY", "UNIQUE", "FOREIGN", "CONSTRAINT")
 _HTML_MARKER_RE = re.compile(r"<!--\s*@invariant:\s*([A-Za-z0-9._:>-]+)\s*-->")
 _SQL_MARKER_RE = re.compile(r"--\s*@invariant:\s*([A-Za-z0-9._:>-]+)")
 _CODE_MARKER_RE = re.compile(r"#\s*@invariant:\s*([A-Za-z0-9._:>-]+)")
dict WITNESS_REGISTRY
 _VERSION_LINEAGE_ROW
str _DV = "inv.version_lineage_derived"
dict _EXPLICIT
dict _APP_LAYER
dict CLASSIFICATION = _build_classification()

Detailed Description

The V0_3(.1) invariant-preservation matrix generator (Plan 142 P1.5, §5.3.1).

Purpose
-------
Close the ``regenerate``-bypass class by construction for the DDL half and
machine-gate it against drift for the application-layer half (Registry Source &
Storage Spec V0.22 §5.3.1 / AC §8.49). ``regenerate`` builds the temp DB by
**direct insert**, not through ``execute_domain_command``, so every
application-layer-only invariant is silently bypassed on rebuild and must be
independently handled. This module builds the **two machine-extracted
inventories** that anchor the matrix:

1. A **DDL-constraint inventory** parsed from the consolidated
   ``REGISTRY_SCHEMA_V0_3_1.sql`` (the post-amendment baseline) plus the
   ``registry_meta.store_scope`` constraint emitted by
   ``v0_3_2_roadmap_source_fields.migration_sql()`` — one stable-ID record for
   every enforceable constraint (CHECK / unique index / ``UNIQUE`` / PK / FK /
   ``NOT NULL`` / trigger); plain non-unique performance indexes are excluded.
2. An **application-layer ``@invariant`` inventory** extracted from
   ``@invariant: <id>`` markers in the ``REGISTRY_ROADMAP_SCHEMA_V0_3_1``
   amendment doc (HTML-comment + SQL-fence forms) and the rebuild enforcement
   code (code-comment form).

Each inventory ID is classified exactly once (``D``/``R``/``X``/``NA``) by the
authored :data:`CLASSIFICATION` map; :func:`generate_matrix` joins the parsed
inventories to that map and applies the D-safety predicate, so the test suite
(``test_invariant_matrix.py``) can assert correctness, the two mutation gates,
the ``{code} ⊆ {matrix}`` drift gate, and the reverse-inclusion R gate.

Why ``.1.sql`` (not ``V0_3.sql`` + ``.1.sql``)
----------------------------------------------
AC §8.49 names "``REGISTRY_SCHEMA_V0_3.sql`` + the consolidated
``REGISTRY_SCHEMA_V0_3_1.sql``". The consolidated ``.1.sql`` is, by its own
header, the fresh-create state **after** applying ``V0_3.sql`` then the
``v0_3_2`` migration — i.e. a superset of every ``V0_3`` roadmap constraint with
the amendments folded in. Parsing both would double-count (duplicate stable
IDs); parsing the consolidated baseline alone covers every ``V0_3`` constraint
with no loss. The one constraint the consolidated ``.1.sql`` omits is the base
``registry_meta.store_scope`` (a base-capability ALTER, not part of the roadmap
snapshot — umbrella §12 wave-1 follow-up), which is recovered from
``migration_sql()``.

Responsibilities
----------------
- :func:`parse_ddl_inventory` — parse a ``.sql`` file into ``DdlConstraint`` records.
- :func:`extract_markers` — extract ``@invariant: <id>`` markers from md/sql/py text.
- :func:`generate_matrix` — join inventories to :data:`CLASSIFICATION`; return a
  :class:`Matrix` with the first-class derive-verify rows + the validity hashes.
- :func:`build_audit_payload` — the §9.1 audit ``.json`` payload (counts + hashes).

Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - generation lifecycle
    L3 - inventory + classification joins
    L4 - per-constraint parse tracing

Contracts
---------
- Pure / read-only: parses files + the authored classification; never mutates them.
- Deterministic: inventories + matrix rows are order-stable (sorted by stable ID).

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.migrations.v0_3_2_roadmap_source_fields (store_scope DDL)

Function Documentation

◆ _build_classification()

dict[str, MatrixRow] oc_chat.registry.invariant_matrix._build_classification ( )
protected
Assemble the authoritative classification: explicit source-populated +
app-layer rows, plus programmatic NA for the never-written + v1-empty tables.

Built once from the canonical ``.1.sql`` inventory so the mutation tests
(which parse a *fixture* ``.sql``) see injected ids absent from this map.

Definition at line 777 of file invariant_matrix.py.

Here is the call graph for this function:

◆ _D()

MatrixRow oc_chat.registry.invariant_matrix._D ( str witness_id,
str handling,
**object kw )
protected

Definition at line 534 of file invariant_matrix.py.

Here is the caller graph for this function:

◆ _hash_lines()

str oc_chat.registry.invariant_matrix._hash_lines ( list[str] lines)
protected

Definition at line 439 of file invariant_matrix.py.

Here is the caller graph for this function:

◆ _NA()

MatrixRow oc_chat.registry.invariant_matrix._NA ( str handling)
protected

Definition at line 553 of file invariant_matrix.py.

Here is the caller graph for this function:

◆ _parse_column_clause()

list[DdlConstraint] oc_chat.registry.invariant_matrix._parse_column_clause ( str table,
str clause )
protected
Parse a single column-definition clause into its constraints.

Definition at line 252 of file invariant_matrix.py.

Here is the caller graph for this function:

◆ _parse_create_tables()

list[DdlConstraint] oc_chat.registry.invariant_matrix._parse_create_tables ( str sql)
protected

Definition at line 316 of file invariant_matrix.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _parse_indexes_and_triggers()

list[DdlConstraint] oc_chat.registry.invariant_matrix._parse_indexes_and_triggers ( str sql)
protected

Definition at line 335 of file invariant_matrix.py.

Here is the caller graph for this function:

◆ _parse_store_scope()

list[DdlConstraint] oc_chat.registry.invariant_matrix._parse_store_scope ( )
protected
Recover ``registry_meta.store_scope`` from the v0_3_2 migration ALTER (the
consolidated ``.1.sql`` omits the base ``registry_meta`` table — umbrella §12).

Definition at line 358 of file invariant_matrix.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _parse_table_constraint_clause()

list[DdlConstraint] oc_chat.registry.invariant_matrix._parse_table_constraint_clause ( str table,
str clause )
protected
Parse a table-level clause (composite PK, table CHECK, table FK).

Definition at line 284 of file invariant_matrix.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _R()

MatrixRow oc_chat.registry.invariant_matrix._R ( str rule,
str ac,
str code,
str neg_fixture,
str handling )
protected

Definition at line 542 of file invariant_matrix.py.

◆ _slug()

str oc_chat.registry.invariant_matrix._slug ( str text)
protected
Deterministic readable slug from a SQL expression (stable across runs).

Definition at line 220 of file invariant_matrix.py.

Here is the caller graph for this function:

◆ _split_table_body()

list[str] oc_chat.registry.invariant_matrix._split_table_body ( str body)
protected
Split a CREATE TABLE body into top-level comma-separated clauses (paren-aware).

Definition at line 228 of file invariant_matrix.py.

Here is the caller graph for this function:

◆ _X()

MatrixRow oc_chat.registry.invariant_matrix._X ( str ratification,
str handling )
protected

Definition at line 549 of file invariant_matrix.py.

◆ app_invariant_inventory_hash()

str oc_chat.registry.invariant_matrix.app_invariant_inventory_hash ( list[Marker] markers)
A stable hash over the extracted app-layer ``@invariant`` ids.

Definition at line 452 of file invariant_matrix.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ app_layer_invariant_ids()

set[str] oc_chat.registry.invariant_matrix.app_layer_invariant_ids ( Optional[dict[str, MatrixRow]] classification = None)
The §9.1 app-layer-invariant checklist denominator: every invariant the
rebuild bypasses unless independently handled — the ``inv.*`` rows (R +
derive-verify) plus the ``X`` conscious relaxations. The pure-DDL ``D``/``NA``
constraints are by-construction and are NOT app-layer invariants (§5.3.1).

Definition at line 914 of file invariant_matrix.py.

Here is the caller graph for this function:

◆ build_audit_payload()

dict[str, object] oc_chat.registry.invariant_matrix.build_audit_payload ( Optional[Matrix] matrix = None)
The machine-readable §9.1 audit ``.json`` payload: the frozen checklist,
the generated-inventory counts, and the audit's own validity-key hashes
(the Accepted-doc + enforcement-code marker hashes + the generated-inventory
hash — NOT the roadmap source_hash, V0.19 Codex V16 F4).

Definition at line 926 of file invariant_matrix.py.

Here is the call graph for this function:

◆ code_markers_not_in_matrix()

list[str] oc_chat.registry.invariant_matrix.code_markers_not_in_matrix ( Matrix matrix)
{code-enforced @invariant ids} ⊄ {matrix ids} — the drift gate (AC §8.49).

Definition at line 897 of file invariant_matrix.py.

◆ constraint_inventory_hash()

str oc_chat.registry.invariant_matrix.constraint_inventory_hash ( list[DdlConstraint] ddl)
A stable hash over the DDL inventory (stable IDs) — the stamp + audit key.

Definition at line 447 of file invariant_matrix.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ extract_code_markers()

list[Marker] oc_chat.registry.invariant_matrix.extract_code_markers ( tuple[Path, ...] files = ENFORCEMENT_CODE_FILES)
Extract ``@invariant`` markers from the rebuild enforcement code.

Definition at line 424 of file invariant_matrix.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ extract_doc_markers()

list[Marker] oc_chat.registry.invariant_matrix.extract_doc_markers ( Path doc_path = V0_3_1_DOC)
Extract the prose ``@invariant`` markers from the V0_3_1 amendment doc.

Definition at line 417 of file invariant_matrix.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ extract_markers()

list[Marker] oc_chat.registry.invariant_matrix.extract_markers ( str text,
* ,
str form,
str source )
Extract ``@invariant: <id>`` markers from ``text`` in the given ``form``
(``html`` = Markdown prose, ``sql`` = SQL fence, ``code`` = Python comment).

Definition at line 401 of file invariant_matrix.py.

Here is the caller graph for this function:

◆ generate_matrix()

Matrix oc_chat.registry.invariant_matrix.generate_matrix ( Path sql_path = SCHEMA_V0_3_1_SQL,
Path doc_path = V0_3_1_DOC,
tuple[Path, ...] code_files = ENFORCEMENT_CODE_FILES )
Join the two machine-extracted inventories to :data:`CLASSIFICATION`.

Definition at line 808 of file invariant_matrix.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ parse_ddl_inventory()

list[DdlConstraint] oc_chat.registry.invariant_matrix.parse_ddl_inventory ( Path sql_path = SCHEMA_V0_3_1_SQL,
* ,
bool include_store_scope = True )
Parse ``sql_path`` (+ the ``registry_meta.store_scope`` migration ALTER)
into a deterministic, de-duplicated DDL-constraint inventory.

Definition at line 372 of file invariant_matrix.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ unimplemented_r_rows()

list[str] oc_chat.registry.invariant_matrix.unimplemented_r_rows ( Matrix matrix)
Matrix ``R`` ids whose ``source_validation_rule`` has no enforcement-code
``@invariant`` marker — the reverse-inclusion R-completeness gate (AC §8.49).

Definition at line 904 of file invariant_matrix.py.

◆ verify_matrix()

list[str] oc_chat.registry.invariant_matrix.verify_matrix ( Matrix matrix)
Run the §5.3.1 correctness predicate over ``matrix``; return a list of
violation strings (empty == the matrix is complete + correct).

Asserts: (a) every DDL-inventory id + every extracted ``@invariant`` id is
classified **exactly once**; (b) every ``D`` satisfies the D-safety predicate
(a registered witness; a ``derive_verify_rule`` names stored columns + a
positive fixture per branch); (c) no catch-all (every row carries a specific
handling); (d) every ``R`` names a source-validation rule + AC + §10 code +
negative fixture; (e) every ``X`` names a ``V0_3_1`` ratification; (f) every
``NA`` names why the rebuild never exercises it.

Definition at line 839 of file invariant_matrix.py.

Variable Documentation

◆ _ALTER_ADD_COLUMN_RE

oc_chat.registry.invariant_matrix._ALTER_ADD_COLUMN_RE
protected
Initial value:
1= re.compile(
2 r"ALTER TABLE\s+(\w+)\s+ADD COLUMN\s+(.+?);",
3 re.DOTALL | re.IGNORECASE,
4)

Definition at line 214 of file invariant_matrix.py.

◆ _APP_LAYER

dict oc_chat.registry.invariant_matrix._APP_LAYER
protected

Definition at line 743 of file invariant_matrix.py.

◆ _CODE_MARKER_RE

oc_chat.registry.invariant_matrix._CODE_MARKER_RE = re.compile(r"#\s*@invariant:\s*([A-Za-z0-9._:>-]+)")
protected

Definition at line 398 of file invariant_matrix.py.

◆ _CREATE_TABLE_RE

oc_chat.registry.invariant_matrix._CREATE_TABLE_RE
protected
Initial value:
1= re.compile(
2 r"CREATE TABLE(?: IF NOT EXISTS)?\s+(\w+)\s*\‍((.*?)\n\‍)\s*;",
3 re.DOTALL | re.IGNORECASE,
4)

Definition at line 201 of file invariant_matrix.py.

◆ _CREATE_TRIGGER_RE

oc_chat.registry.invariant_matrix._CREATE_TRIGGER_RE
protected
Initial value:
1= re.compile(
2 r"CREATE\s+TRIGGER(?: IF NOT EXISTS)?\s+(\w+)\s+(BEFORE|AFTER)\s+(\w+)\s+ON\s+(\w+)",
3 re.IGNORECASE,
4)

Definition at line 210 of file invariant_matrix.py.

◆ _CREATE_UNIQUE_INDEX_RE

oc_chat.registry.invariant_matrix._CREATE_UNIQUE_INDEX_RE
protected
Initial value:
1= re.compile(
2 r"CREATE\s+UNIQUE\s+INDEX(?: IF NOT EXISTS)?\s+(\w+)\s+ON\s+(\w+)\s*\‍(([^)]*)\‍)"
3 r"(?:\s+WHERE\s+(.+?))?\s*;",
4 re.DOTALL | re.IGNORECASE,
5)

Definition at line 205 of file invariant_matrix.py.

◆ _DV

str oc_chat.registry.invariant_matrix._DV = "inv.version_lineage_derived"
protected

Definition at line 580 of file invariant_matrix.py.

◆ _EXPLICIT

dict oc_chat.registry.invariant_matrix._EXPLICIT
protected

Definition at line 585 of file invariant_matrix.py.

◆ _HTML_MARKER_RE

oc_chat.registry.invariant_matrix._HTML_MARKER_RE = re.compile(r"<!--\s*@invariant:\s*([A-Za-z0-9._:>-]+)\s*-->")
protected

Definition at line 395 of file invariant_matrix.py.

◆ _ORCH

str oc_chat.registry.invariant_matrix._ORCH = Path(__file__).resolve().parents[1] / "docs" / "architecture" / "orchestration"
protected

Definition at line 91 of file invariant_matrix.py.

◆ _REGEN

str oc_chat.registry.invariant_matrix._REGEN = Path(__file__).resolve().parent / "regenerate"
protected

Definition at line 97 of file invariant_matrix.py.

◆ _SQL_MARKER_RE

oc_chat.registry.invariant_matrix._SQL_MARKER_RE = re.compile(r"--\s*@invariant:\s*([A-Za-z0-9._:>-]+)")
protected

Definition at line 396 of file invariant_matrix.py.

◆ _SQL_RESERVED_CLAUSE_HEADS

tuple oc_chat.registry.invariant_matrix._SQL_RESERVED_CLAUSE_HEADS = ("CHECK", "PRIMARY", "UNIQUE", "FOREIGN", "CONSTRAINT")
protected

Definition at line 249 of file invariant_matrix.py.

◆ _VERSION_LINEAGE_ROW

oc_chat.registry.invariant_matrix._VERSION_LINEAGE_ROW
protected
Initial value:
1= MatrixRow(
2 classification="D",
3 # OCT-LINT: disable=no_hardcoded_secrets reason="SQL keywords, table/column names and SRC_* codes are schema constants"
4 handling="version status / lineage (C3–C6) / one-current-per-era / bump_kind are "
5 "DERIVED from the ordered changelog (numeric-per-field) then recomputed-and-"
6 "verified at step-7 before any use; a violating value is unreachable in the built store",
7 witness_type="derive_verify_rule",
8 witness_id="inv.version_lineage_derived",
9 derive_rule_id="derive_verify.derive_versions",
10 source_fields=("version", "era", "date", "round", "bump_override"),
11 stored_columns=("status", "parent_version_id", "supersedes_version_id",
12 "superseded_by_version_id", "bump_kind"),
13 verify_phase="step-7",
14 # OCT-LINT: disable=no_hardcoded_secrets reason="SQL keywords, table/column names and SRC_* codes are schema constants"
15 read_barrier="verified_projection.assert_verified_projection (REGEN_UNVERIFIED_PROJECTION)",
16 positive_fixtures=("test_version_ordering_numeric_across_major_boundary",
17 "test_version_selection_skip_superseded",
18 "test_version_selection_per_era_cardinality"),
19 error_code="REGEN_BUILD_FAILED",
20)

Definition at line 559 of file invariant_matrix.py.

◆ CLASSIFICATION

dict oc_chat.registry.invariant_matrix.CLASSIFICATION = _build_classification()

Definition at line 805 of file invariant_matrix.py.

◆ ENFORCEMENT_CODE_FILES

tuple oc_chat.registry.invariant_matrix.ENFORCEMENT_CODE_FILES
Initial value:
1= (
2 _REGEN / "cross_record.py",
3 _REGEN / "derive_verify.py",
4 _REGEN / "build.py",
5 _REGEN / "pipeline.py",
6)

Definition at line 103 of file invariant_matrix.py.

◆ NEVER_WRITTEN_TABLES

frozenset oc_chat.registry.invariant_matrix.NEVER_WRITTEN_TABLES
Initial value:
1= frozenset({
2 "roadmap_item_events", "roadmap_plan_links",
3})

Definition at line 118 of file invariant_matrix.py.

◆ RUNTIME_TABLES

frozenset oc_chat.registry.invariant_matrix.RUNTIME_TABLES
Initial value:
1= frozenset({
2 "agents", "rounds", "plans", "operation_log",
3})

Definition at line 122 of file invariant_matrix.py.

◆ SCHEMA_V0_3_1_SQL

str oc_chat.registry.invariant_matrix.SCHEMA_V0_3_1_SQL = _ORCH / "REGISTRY_SCHEMA_V0_3_1.sql"

Definition at line 93 of file invariant_matrix.py.

◆ SOURCE_POPULATED_TABLES

frozenset oc_chat.registry.invariant_matrix.SOURCE_POPULATED_TABLES
Initial value:
1= frozenset({
2 "roadmap_eras", "roadmap_versions", "roadmap_phases", "roadmap_tracks",
3 "roadmap_items_v3", "roadmap_item_tracks", "roadmap_item_dependencies",
4 "roadmap_render_sections",
5})

Definition at line 112 of file invariant_matrix.py.

◆ V0_3_1_DOC

str oc_chat.registry.invariant_matrix.V0_3_1_DOC = _ORCH / "REGISTRY_ROADMAP_SCHEMA_V0_3_1.md"

Definition at line 95 of file invariant_matrix.py.

◆ VALID_CLASSES

frozenset oc_chat.registry.invariant_matrix.VALID_CLASSES = frozenset({"D", "R", "X", "NA"})

Definition at line 127 of file invariant_matrix.py.

◆ WITNESS_REGISTRY

dict oc_chat.registry.invariant_matrix.WITNESS_REGISTRY

Definition at line 469 of file invariant_matrix.py.

◆ WITNESS_TYPES

frozenset oc_chat.registry.invariant_matrix.WITNESS_TYPES
Initial value:
1= frozenset({
2 "source_validation_rule", "projection_fill_rule", "derive_verify_rule",
3})

Definition at line 129 of file invariant_matrix.py.