oc_connect.comms Namespace Reference

Classes
class	CommsMigrationError
class	MigratedFile
class	MigrationReport
class	CommsBus

Functions
str	_encode (int value, int length)
str	new_ulid (datetime now, *, bytes|None entropy=None)
str	utc_stamp (datetime now)
str	message_filename (datetime now, str source, str ulid)
str	content_digest (bytes payload)
None	_atomic_write (Path destination, bytes payload)
int	_count_records (str name, bytes payload)
tuple[Path,...]	_message_paths (Path directory)

Variables
str	_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
str	OUTBOX_FILENAME = "outbox.json"
str	AUDIT_FILENAME = "audit.jsonl"

Detailed Description

The comms bus: one workspace-anchored root with lane-separated storage.

Proposal V1 §3, verbatim layout::

    oc_chat/.option_c/comms/
      outbound/            # the plan-219 durable outbox, relocated here
      inbound/
        telegram/          # operator replies, one JSON file per message
      lanes/
        worker-reports/    # created by plan 231, not here
      audit/               # hash-only audit trail across all lanes

Lane separation is structural, not advisory: the directories exist, each
consumer is handed only the directory it may touch, and every stored record
names its lane, direction and risk class (§9's binding rule).

The plan-219 state moves in through :meth:`CommsBus.migrate_from`, which is a
*verified* move: hash the source, write the destination, re-read and re-hash the
destination, and only then unlink the source. A mismatch aborts with the source
still in place, so a failed migration loses nothing.

Dependencies
------------
- oc_connect.workspace (comms_root - the workspace-anchored root of the bus)
- oc_diagnostics (_dbg structured logger)

Function Documentation

_atomic_write()

None oc_connect.comms._atomic_write ( Path destination, bytes payload )

protected

Definition at line 129 of file comms.py.

_count_records()

int oc_connect.comms._count_records ( str name, bytes payload )

protected

Definition at line 148 of file comms.py.

Here is the caller graph for this function:

_encode()

str oc_connect.comms._encode ( int value, int length )

protected

Definition at line 54 of file comms.py.

Here is the caller graph for this function:

_message_paths()

tuple[Path, ...] oc_connect.comms._message_paths ( Path directory )

protected

Definition at line 319 of file comms.py.

Here is the caller graph for this function:

content_digest()

str oc_connect.comms.content_digest

(

bytes

payload

)

Return the lowercase SHA-256 digest of raw file bytes.

Definition at line 93 of file comms.py.

Here is the caller graph for this function:

message_filename()

str oc_connect.comms.message_filename	(	datetime	now,
		str	source,
		str	ulid )

Return the ``<utc-stamp>_<source>_<ulid>.json`` name from §3.

Definition at line 86 of file comms.py.

new_ulid()

str oc_connect.comms.new_ulid	(	datetime	now,
		*	,
		bytes | None	entropy = None )

Return a 26-character ULID: 48 bits of time, 80 bits of randomness.

Time-first encoding means lexical order is arrival order, which is what
makes the flood bound's oldest-first rule a plain directory sort.
*entropy* exists so tests can pin the random half; production leaves it
``None`` and draws from :mod:`secrets`.

Definition at line 62 of file comms.py.

Here is the call graph for this function:

utc_stamp()

str oc_connect.comms.utc_stamp

(

datetime

now

)

Return a filename-safe UTC stamp; colons are illegal on Windows.

Definition at line 79 of file comms.py.

Variable Documentation

_CROCKFORD

str oc_connect.comms._CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"

protected

Definition at line 44 of file comms.py.

AUDIT_FILENAME

str oc_connect.comms.AUDIT_FILENAME = "audit.jsonl"

Definition at line 47 of file comms.py.

OUTBOX_FILENAME

str oc_connect.comms.OUTBOX_FILENAME = "outbox.json"

Definition at line 46 of file comms.py.