Functions
str	_sha256_hex (bytes data)
str	_hash_preimage (dict[str, Any] preimage)
dict[str, Any]	raw_source_tree_preimage (Path root)
str	raw_source_tree_hash (Path root)
dict[str, Any]	source_hash_preimage (list[ScannedRecord] records)
str	source_hash (list[ScannedRecord] records)
dict[str, Any]	semantic_preimage (list[tuple[ScannedRecord, RegistryModel]] loaded)
str	semantic_hash (list[tuple[ScannedRecord, RegistryModel]] loaded)
bool	_table_exists (sqlite3.Connection conn, str name)
list[sqlite3.Row]	_rows (sqlite3.Connection conn, str table, str columns)
Optional[str]	_canonical_query_params (Optional[str] value, str section_path)
dict[str, Any]	logical_state_projection (sqlite3.Connection conn)
str	logical_state_hash (sqlite3.Connection conn)
dict[str, Optional[str]]	stage_hashes (str stage, *, Optional[str] raw=None, Optional[str] source=None, Optional[str] logical=None)
dict[str, Any]	hash_preimage (str which, *, Optional[Path] root=None, Optional[list[ScannedRecord]] records=None, Optional[list[tuple[ScannedRecord, RegistryModel]]] loaded=None, Optional[sqlite3.Connection] conn=None)

Variables
int	HASH_PREIMAGE_SCHEMA_VERSION = 1
str	STAGE_SCAN = "scan"
str	STAGE_PARSE = "parse"
str	STAGE_CROSS_RECORD = "cross_record"
str	STAGE_BUILD = "build"
str	STAGE_CLEAN = "clean"

Detailed Description

The three AuthoredSource hash projections (+ envelope nullability).

Purpose
-------
Implement Registry Source & Storage Spec V0.22 §3.2: (1) the canonical
source-tree hash, (2) the source semantic projection, (3) the canonical
logical-state hash over the RuntimeStore durable roadmap rows (surrogate →
natural-key resolution + canonical ``query_params_json``), plus the §10 raw
source-tree hash and the failure-envelope hash nullability rule.

Responsibilities
----------------
- ``raw_source_tree_hash`` — sha256 over raw observed bytes (incl. files that
  later fail validation; computable before parse; null only on scan failure).
- ``source_hash`` — sha256 over canonical record bytes (projection 1).
- ``semantic_hash`` — sha256 over the source semantic projection (projection 2).
- ``logical_state_hash`` — sha256 over the §3.2 store projection (projection 3).
- ``hash_preimage`` — the printed preimage (with ``hash_preimage_schema_version``).
- ``stage_hashes`` — the §10 nullability of the three hashes per failure stage.

Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - hash lifecycle
    L3 - projection details
    L4 - per-row projection tracing

Contracts
---------
- All hashes are sha256 hex over ``canonical_json`` of a preimage that begins
  with ``hash_preimage_schema_version`` (starts at integer 1).
- The logical projection includes/excludes exactly the §3.2 columns; surrogate
  keys are resolved to natural keys; ``query_params_json`` is re-emitted canonical.
- ``logical_state_hash`` reads an already-built store; it derives nothing
  (version status/lineage derive-verify is the P1.4 step-7 publish-gate).

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.canonical (canonical_json)
- oc_chat.registry.source.scanner (ScannedRecord and observed_files - the records and files the hashes cover)
- oc_chat.registry.source.canonical (canonical_record_bytes - the canonical bytes behind the source hash)
- oc_chat.registry.source.errors (SRC_BAD_QUERY_PARAMS and SourceValidationError - an invalid query_params_json)
- option_c_registry_contracts (RegistryModel - the loaded record models behind the semantic hash)

Function Documentation

◆ _canonical_query_params()

Optional[str] oc_chat.registry.source.hashing._canonical_query_params	(	Optional[str]	value,
		str	section_path )

protected

Definition at line 172 of file hashing.py.

Here is the caller graph for this function:

◆ _hash_preimage()

str oc_chat.registry.source.hashing._hash_preimage ( dict[str, Any] preimage )

protected

Definition at line 90 of file hashing.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _rows()

list[sqlite3.Row] oc_chat.registry.source.hashing._rows	(	sqlite3.Connection	conn,
		str	table,
		str	columns )

protected

Definition at line 166 of file hashing.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _sha256_hex()

str oc_chat.registry.source.hashing._sha256_hex ( bytes data )

protected

Definition at line 86 of file hashing.py.

Here is the caller graph for this function:

◆ _table_exists()

bool oc_chat.registry.source.hashing._table_exists	(	sqlite3.Connection	conn,
		str	name )

protected

Definition at line 158 of file hashing.py.

Here is the caller graph for this function:

◆ hash_preimage()

dict[str, Any] oc_chat.registry.source.hashing.hash_preimage	(	str	which,
		*	,
		Optional[Path]	root = None,
		Optional[list[ScannedRecord]]	records = None,
		Optional[list[tuple[ScannedRecord, RegistryModel]]]	loaded = None,
		Optional[sqlite3.Connection]	conn = None )

Return the canonical preimage for ``which`` projection (debug surface).

Definition at line 327 of file hashing.py.

Here is the call graph for this function:

◆ logical_state_hash()

str oc_chat.registry.source.hashing.logical_state_hash ( sqlite3.Connection conn )

Definition at line 299 of file hashing.py.

Here is the call graph for this function:

◆ logical_state_projection()

dict[str, Any] oc_chat.registry.source.hashing.logical_state_projection ( sqlite3.Connection conn )

Build the §3.2 projection-3 preimage over the durable roadmap rows.

Definition at line 186 of file hashing.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ raw_source_tree_hash()

str oc_chat.registry.source.hashing.raw_source_tree_hash ( Path root )

Definition at line 108 of file hashing.py.

Here is the call graph for this function:

◆ raw_source_tree_preimage()

dict[str, Any] oc_chat.registry.source.hashing.raw_source_tree_preimage ( Path root )

``[(relative_posix_path, sha256(raw_file_bytes))]`` over observed files.

Definition at line 95 of file hashing.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ semantic_hash()

str oc_chat.registry.source.hashing.semantic_hash ( list[tuple[ScannedRecord, RegistryModel]] loaded )

Definition at line 153 of file hashing.py.

Here is the call graph for this function:

◆ semantic_preimage()

dict[str, Any] oc_chat.registry.source.hashing.semantic_preimage ( list[tuple[ScannedRecord, RegistryModel]] loaded )

Authored records normalized to canonical JSON using source field names.

Definition at line 136 of file hashing.py.

Here is the caller graph for this function:

◆ source_hash()

str oc_chat.registry.source.hashing.source_hash ( list[ScannedRecord] records )

Definition at line 131 of file hashing.py.

Here is the call graph for this function:

◆ source_hash_preimage()

dict[str, Any] oc_chat.registry.source.hashing.source_hash_preimage ( list[ScannedRecord] records )

``[(relative_posix_path, sha256(canonical_record_bytes))]`` (projection 1).

[OP-5] promoted parity: promoted items are now included (the earlier
model-gap skip is removed), so ``source_hash`` is a complete fingerprint of
the authored tree — an edit to a promoted file moves ``source_hash``.

Definition at line 112 of file hashing.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ stage_hashes()

dict[str, Optional[str]] oc_chat.registry.source.hashing.stage_hashes	(	str	stage,
		*	,
		Optional[str]	raw = None,
		Optional[str]	source = None,
		Optional[str]	logical = None )

Return the three envelope hash fields with the §10 nullability for ``stage``.

scan failure → raw null; parse/local/canonicalisation → source null, raw
present; cross-record / pre-build → logical null, source present; clean →
all three present.

Definition at line 304 of file hashing.py.

Variable Documentation

◆ HASH_PREIMAGE_SCHEMA_VERSION

int oc_chat.registry.source.hashing.HASH_PREIMAGE_SCHEMA_VERSION = 1

Definition at line 76 of file hashing.py.

◆ STAGE_BUILD

str oc_chat.registry.source.hashing.STAGE_BUILD = "build"

Definition at line 82 of file hashing.py.

◆ STAGE_CLEAN

str oc_chat.registry.source.hashing.STAGE_CLEAN = "clean"

Definition at line 83 of file hashing.py.

◆ STAGE_CROSS_RECORD

str oc_chat.registry.source.hashing.STAGE_CROSS_RECORD = "cross_record"

Definition at line 81 of file hashing.py.

◆ STAGE_PARSE

str oc_chat.registry.source.hashing.STAGE_PARSE = "parse"

Definition at line 80 of file hashing.py.

◆ STAGE_SCAN

str oc_chat.registry.source.hashing.STAGE_SCAN = "scan"

Definition at line 79 of file hashing.py.

Functions

Variables

Detailed Description

Function Documentation

◆ _canonical_query_params()

◆ _hash_preimage()

◆ _rows()

◆ _sha256_hex()

◆ _table_exists()

◆ hash_preimage()

◆ logical_state_hash()

◆ logical_state_projection()

◆ raw_source_tree_hash()

◆ raw_source_tree_preimage()

◆ semantic_hash()

◆ semantic_preimage()

◆ source_hash()

◆ source_hash_preimage()

◆ stage_hashes()

Variable Documentation

◆ HASH_PREIMAGE_SCHEMA_VERSION

◆ STAGE_BUILD

◆ STAGE_CLEAN

◆ STAGE_CROSS_RECORD

◆ STAGE_PARSE

◆ STAGE_SCAN