|
oc_chat
|
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() |
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)
|
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.
|
protected |
|
protected |
|
protected |
|
protected |
Parse a single column-definition clause into its constraints.
Definition at line 252 of file invariant_matrix.py.
|
protected |
Definition at line 316 of file invariant_matrix.py.
|
protected |
|
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.
|
protected |
Parse a table-level clause (composite PK, table CHECK, table FK).
Definition at line 284 of file invariant_matrix.py.
|
protected |
Definition at line 542 of file invariant_matrix.py.
|
protected |
Deterministic readable slug from a SQL expression (stable across runs).
Definition at line 220 of file invariant_matrix.py.
|
protected |
Split a CREATE TABLE body into top-level comma-separated clauses (paren-aware).
Definition at line 228 of file invariant_matrix.py.
|
protected |
Definition at line 549 of file invariant_matrix.py.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
|
protected |
Definition at line 214 of file invariant_matrix.py.
|
protected |
Definition at line 743 of file invariant_matrix.py.
|
protected |
Definition at line 398 of file invariant_matrix.py.
|
protected |
Definition at line 201 of file invariant_matrix.py.
|
protected |
Definition at line 210 of file invariant_matrix.py.
|
protected |
Definition at line 205 of file invariant_matrix.py.
|
protected |
Definition at line 580 of file invariant_matrix.py.
|
protected |
Definition at line 585 of file invariant_matrix.py.
|
protected |
Definition at line 395 of file invariant_matrix.py.
|
protected |
Definition at line 91 of file invariant_matrix.py.
|
protected |
Definition at line 97 of file invariant_matrix.py.
|
protected |
Definition at line 396 of file invariant_matrix.py.
|
protected |
Definition at line 249 of file invariant_matrix.py.
|
protected |
Definition at line 559 of file invariant_matrix.py.
| dict oc_chat.registry.invariant_matrix.CLASSIFICATION = _build_classification() |
Definition at line 805 of file invariant_matrix.py.
| tuple oc_chat.registry.invariant_matrix.ENFORCEMENT_CODE_FILES |
Definition at line 103 of file invariant_matrix.py.
| frozenset oc_chat.registry.invariant_matrix.NEVER_WRITTEN_TABLES |
Definition at line 118 of file invariant_matrix.py.
| frozenset oc_chat.registry.invariant_matrix.RUNTIME_TABLES |
Definition at line 122 of file invariant_matrix.py.
| 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.
| frozenset oc_chat.registry.invariant_matrix.SOURCE_POPULATED_TABLES |
Definition at line 112 of file invariant_matrix.py.
| 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.
| frozenset oc_chat.registry.invariant_matrix.VALID_CLASSES = frozenset({"D", "R", "X", "NA"}) |
Definition at line 127 of file invariant_matrix.py.
| dict oc_chat.registry.invariant_matrix.WITNESS_REGISTRY |
Definition at line 469 of file invariant_matrix.py.
| frozenset oc_chat.registry.invariant_matrix.WITNESS_TYPES |
Definition at line 129 of file invariant_matrix.py.