Classes
class	CheckpointError
class	CheckpointSignatureError
class	CheckpointWriteResult
class	CheckpointImportResult

Functions
dict[str, object]	export_checkpoint (Registry registry, *, bool sign=False)
CheckpointWriteResult	write_checkpoint (Registry registry, *, Path out, bool sign=False)
CheckpointImportResult	import_checkpoint (SQLiteBackend backend, *, Path checkpoint_path, bool skip_signature_check=False)
bool	verify_checkpoint (Mapping[str, object] checkpoint, *, bool skip_signature_check=False)
dict[str, list[dict[str, object]]]	_export_tables (Registry registry)
Path	_build_temp_database (SQLiteBackend backend, Mapping[str, object] checkpoint)
None	_insert_rows (sqlite3.Connection conn, str table, list[object] rows)
dict[str, object]	_signature_block (Registry registry, Mapping[str, object] payload)
str	_signature_hex (Mapping[str, object] payload, *, bytes\|None key=None)
dict[str, object]	_payload_without_signature (Mapping[str, object] payload)
tuple[bytes, str]	_resolve_checkpoint_key ()
str\|None	_active_operator_hmac_key_id (Registry registry)
bytes	_decode_key (bytes raw)
dict[str, object]	_read_checkpoint (Path path)
None	_validate_checkpoint_shape (Mapping[str, object] checkpoint)
list[str]	_table_names (sqlite3.Connection conn)
list[str]	_table_columns (sqlite3.Connection conn, str table)
str	_quote_identifier (object value)

Variables
int	CHECKPOINT_VERSION = 1
str	CHECKPOINT_SCHEMA_VERSION = "v0.2.3"
str	SIGNATURE_ALGORITHM = "HMAC-SHA256"
str	CHECKPOINT_KEY_ENV = "OC_REGISTRY_CHECKPOINT_KEY_PATH"
str	KEYRING_SERVICE = "oc_chat:registry:checkpoint"
str	KEYRING_USERNAME = "key"

Detailed Description

Signed JSON checkpoint export/import for the registry.

Purpose
-------
Provide canonical JSON checkpoint export/import with an HMAC signature block
for cross-machine registry transfer.

Responsibilities
----------------
- Export every registry table into deterministic canonical JSON.
- Sign and verify checkpoint payloads with HMAC-SHA256.
- Restore verified checkpoints by building a temporary SQLite database and
  replacing the target through the backend restore hook.

Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - checkpoint lifecycle events
    L3 - signature and table-count details
    L4 - per-table export/import tracing

Contracts
---------
- Signatures are verified before any target registry state changes.
- Operation-log and lock SQL ownership remains in the SQLite backend.
- No actor-auth or key-rotation semantics are introduced here.

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.backends.sqlite (schema/restore support)
- oc_chat.registry.canonical (canonical JSON serialization)
- oc_chat.registry.api (Registry facade whose backend and clock the export reads)
- keyring (lazy; checkpoint signing key when the key path environment variable is unset)

Function Documentation

◆ _active_operator_hmac_key_id()

str | None oc_chat.registry.checkpoint._active_operator_hmac_key_id ( Registry registry )

protected

Definition at line 331 of file checkpoint.py.

Here is the caller graph for this function:

◆ _build_temp_database()

Path oc_chat.registry.checkpoint._build_temp_database	(	SQLiteBackend	backend,
		Mapping[str, object]	checkpoint )

protected

Definition at line 214 of file checkpoint.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _decode_key()

bytes oc_chat.registry.checkpoint._decode_key ( bytes raw )

protected

Definition at line 351 of file checkpoint.py.

Here is the caller graph for this function:

◆ _export_tables()

dict[str, list[dict[str, object]]] oc_chat.registry.checkpoint._export_tables ( Registry registry )

protected

Definition at line 194 of file checkpoint.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _insert_rows()

None oc_chat.registry.checkpoint._insert_rows	(	sqlite3.Connection	conn,
		str	table,
		list[object]	rows )

protected

Definition at line 259 of file checkpoint.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _payload_without_signature()

dict[str, object] oc_chat.registry.checkpoint._payload_without_signature ( Mapping[str, object] payload )

protected

Definition at line 309 of file checkpoint.py.

Here is the caller graph for this function:

◆ _quote_identifier()

str oc_chat.registry.checkpoint._quote_identifier ( object value )

protected

Definition at line 399 of file checkpoint.py.

Here is the caller graph for this function:

◆ _read_checkpoint()

dict[str, object] oc_chat.registry.checkpoint._read_checkpoint ( Path path )

protected

Definition at line 363 of file checkpoint.py.

Here is the caller graph for this function:

◆ _resolve_checkpoint_key()

tuple[bytes, str] oc_chat.registry.checkpoint._resolve_checkpoint_key ( )

protected

Definition at line 313 of file checkpoint.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _signature_block()

dict[str, object] oc_chat.registry.checkpoint._signature_block	(	Registry	registry,
		Mapping[str, object]	payload )

protected

Definition at line 280 of file checkpoint.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _signature_hex()

str oc_chat.registry.checkpoint._signature_hex	(	Mapping[str, object]	payload,
		*	,
		bytes \| None	key = None )

protected

Definition at line 296 of file checkpoint.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _table_columns()

list[str] oc_chat.registry.checkpoint._table_columns	(	sqlite3.Connection	conn,
		str	table )

protected

Definition at line 391 of file checkpoint.py.

Here is the caller graph for this function:

◆ _table_names()

list[str] oc_chat.registry.checkpoint._table_names ( sqlite3.Connection conn )

protected

Definition at line 379 of file checkpoint.py.

Here is the caller graph for this function:

◆ _validate_checkpoint_shape()

None oc_chat.registry.checkpoint._validate_checkpoint_shape ( Mapping[str, object] checkpoint )

protected

Definition at line 370 of file checkpoint.py.

Here is the caller graph for this function:

◆ export_checkpoint()

dict[str, object] oc_chat.registry.checkpoint.export_checkpoint	(	Registry	registry,
		*	,
		bool	sign = False )

Return a canonical JSON-safe checkpoint mapping.

Definition at line 110 of file checkpoint.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ import_checkpoint()

CheckpointImportResult oc_chat.registry.checkpoint.import_checkpoint	(	SQLiteBackend	backend,
		*	,
		Path	checkpoint_path,
		bool	skip_signature_check = False )

Verify and restore ``checkpoint_path`` over ``backend``.

Definition at line 140 of file checkpoint.py.

Here is the call graph for this function:

◆ verify_checkpoint()

bool oc_chat.registry.checkpoint.verify_checkpoint	(	Mapping[str, object]	checkpoint,
		*	,
		bool	skip_signature_check = False )

Verify a checkpoint signature before import.

Definition at line 168 of file checkpoint.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ write_checkpoint()

CheckpointWriteResult oc_chat.registry.checkpoint.write_checkpoint	(	Registry	registry,
		*	,
		Path	out,
		bool	sign = False )

Write a checkpoint file and return its digest metadata.

Definition at line 124 of file checkpoint.py.

Here is the call graph for this function:

Variable Documentation

◆ CHECKPOINT_KEY_ENV

str oc_chat.registry.checkpoint.CHECKPOINT_KEY_ENV = "OC_REGISTRY_CHECKPOINT_KEY_PATH"

Definition at line 67 of file checkpoint.py.

◆ CHECKPOINT_SCHEMA_VERSION

str oc_chat.registry.checkpoint.CHECKPOINT_SCHEMA_VERSION = "v0.2.3"

Definition at line 65 of file checkpoint.py.

◆ CHECKPOINT_VERSION

int oc_chat.registry.checkpoint.CHECKPOINT_VERSION = 1

Definition at line 64 of file checkpoint.py.

◆ KEYRING_SERVICE

str oc_chat.registry.checkpoint.KEYRING_SERVICE = "oc_chat:registry:checkpoint"

Definition at line 68 of file checkpoint.py.

◆ KEYRING_USERNAME

str oc_chat.registry.checkpoint.KEYRING_USERNAME = "key"

Definition at line 69 of file checkpoint.py.

◆ SIGNATURE_ALGORITHM

str oc_chat.registry.checkpoint.SIGNATURE_ALGORITHM = "HMAC-SHA256"

Definition at line 66 of file checkpoint.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _active_operator_hmac_key_id()

◆ _build_temp_database()

◆ _decode_key()

◆ _export_tables()

◆ _insert_rows()

◆ _payload_without_signature()

◆ _quote_identifier()

◆ _read_checkpoint()

◆ _resolve_checkpoint_key()

◆ _signature_block()

◆ _signature_hex()

◆ _table_columns()

◆ _table_names()

◆ _validate_checkpoint_shape()

◆ export_checkpoint()

◆ import_checkpoint()

◆ verify_checkpoint()

◆ write_checkpoint()

Variable Documentation

◆ CHECKPOINT_KEY_ENV

◆ CHECKPOINT_SCHEMA_VERSION

◆ CHECKPOINT_VERSION

◆ KEYRING_SERVICE

◆ KEYRING_USERNAME

◆ SIGNATURE_ALGORITHM