cjm-context-graph-layer

Domain-neutral graph-aware layer for context graphs: deterministic node identity, spine and overlay grammar, spine-edit operations with effective-view projection, supersession resolution, idempotent emission/extension, and provenance-by-declaration.

Modules

• cjm_context_graph_layer.__init__
• cjm_context_graph_layer.compact — Journal COMPACTION — move retired wires out of the active journal family into an archive (ruling a7617bd4).
• cjm_context_graph_layer.declare — Provenance-by-declaration: host logic stays readable Python in the workflow core and DECLARES its provenance contributions as a Derivation event node (+ DERIVED_FROM input edges, PRODUCED output edges). This recovers audit completeness without the substrate executing host logic (pass-2 Thread 4's false-dichotomy resolution). The substrate stays untouched: declarations read composition/job ids from the outside.
• cjm_context_graph_layer.edits — The spine-edit operation vocabulary (prune / replace_text / boundary_shift) + supersession resolution + the effective-view projection. These are generic operations on any NEXT-chained text spine; correction workflows carry them in overlay-node payloads, and the projection interprets them at read time (migrates correction-core C11/C16 onto the layer).
• cjm_context_graph_layer.grammar — The domain-neutral context-graph grammar: spine relations (NEXT / PART_OF / STARTS_WITH, recurring fractally at every layer), overlay relations (SUPERSEDES / DERIVED_FROM / PRODUCED), root kinds, and the standardized attribution fields.
• cjm_context_graph_layer.graphdiff — Two graphs compared element for element, streamed: the one standing check for every lane (ruling f8b9c728).
• cjm_context_graph_layer.identity — Deterministic node/edge identity: UUIDv5 over canonical identity tuples (stage-5 ratified rule: a node's id derives from what makes it THE same node across re-derivation, never from its correctable content).
• cjm_context_graph_layer.journal — Journal replay for workflow graphs — the genesis baseline + the pluggable verb registry.
• cjm_context_graph_layer.ops — Queue-touching layer operations: the shared graph_task helper (task channel), idempotent emission (emit-if-absent + verify-if-present), and extend_graph — the one primitive every graph-extending workflow commits through. Deterministic ids (see identity) make idempotency a presence check instead of a search.
• cjm_context_graph_layer.rebuild — Rebuild a workflow graph db from its journal — the runnable disaster-recovery driver.
• cjm_context_graph_layer.testing — The write order's test kit, shared by every workflow core's suite.

API

cjm_context_graph_layer.compact

• CompactRefusal class — Compaction refused before writing: a kept op still references a retired id
• CompactReport class — What a compaction did (or, dry-run, would do).
• CompactionPlan class — A compaction scanned and resolved, nothing written (ruling 6683f49e (3)): what moves, where
• DanglingRef class — One kept op that names a retired id — the reason a compaction refuses.
• archive_segments function — The archive family beside a journal: <stem>.retired.NNNN.jsonl under archive_dir.
• compact_family function — A db-backed family's compaction, THE OP FIRST (ruling 6683f49e (3)): under the writer's
• compact_journal function — Move every wire on the retired ids out of the journal family into ONE new archive segment
• journaled_ops function — The family's ops of ONE verb, read once (ruling 9d57273a): cold segments, then the live tail
• move_compaction function — THE STORAGE MOVE: write the archive segment + manifest, then rewrite each changed segment
• next_archive_path function
• plan_compaction function — THE SCAN: classify every op of the family's cold segments -- moved whole, split, kept --
• scan_references function — The post-compaction static check: the family names none of the retired ids.

cjm_context_graph_layer.declare

• Derivation class — One host-logic transformation event, declared for the audit trail.
• derivation_to_graph function — Materialize a declaration as one event node + DERIVED_FROM / PRODUCED edges.

cjm_context_graph_layer.edits

• SpineEdit class — One spine-edit decision, as carried in an overlay node's payload.
• SpineEditError class — A spine edit could not be validated or applied (loud, never silent).
• SpineUnit class — Minimal projection unit: one spine position with its effective text.
• project_effective_spine function — Project the effective view: layer-0 + active edits, resolved at read time.
• resolve_active function — Resolve the active set under append-only supersession.

cjm_context_graph_layer.grammar

• OverlayRelations class — Overlay/derivation relations — the trust grammar shared by every
• SpineRelations class — Structural spine relations, reused fractally at every layer
• attribution function — Standardized attribution fields for derived/asserted nodes.
• grouped_spine_edges function — Spine edges for a fine layer grouped under coarse parents.
• make_edge function — Build an edge wire dict with a deterministic id by default.
• spine_edges function — The uniform spine pattern at any layer: PART_OF child->parent for each

cjm_context_graph_layer.graphdiff

• IdAttribution class — The elements a known cause accounts for, by id: every difference on them is the cause's.
• KindDiff class — The comparison of one element kind, fed one id-aligned pair at a time (either side may
• LagAttribution class — A time field whose A value precedes B's by under max_lag seconds, on an element written
• MarkAttribution class — A property carrying a copy of its element's own time column in A, where B holds an
• amerge_sorted function — merge_sorted over two async streams.
• compared_fields function — The compared fields of one element: its structural fields, each property key on its
• diff_graphs function — The comparison over elements already in memory (tests, small graphs): sorted by id,
• diff_stores function — Compare two graphs element for element, streamed: O(page) memory per side (plus, with
• merge_sorted function — Merge two id-ordered element streams into (A, B) pairs, None where a side lacks the id.
• normalize function — Rewrite mapped path prefixes in every string, recursively (keys stay as they are).
• render_diff function — Markdown (the verdict, the two graphs, the drift map by kind), or JSON for agents.
• render_head function — The verdict line: CLEAN or DIFFERENCES, and what each cause accounts for.
• render_kinds function — The drift map by kind, class and field; rows a cause accounts for print under each kind
• stream_elements function — Every node (or edge) of a graph through the storage capability, in id-ordered keyset
• wire function — The wire dict of a typed graph element (task results may arrive typed or as dicts).

cjm_context_graph_layer.identity

• canonical_part function — Render one identity-tuple part canonically.
• derive_edge_id function — Derive a deterministic edge id from (source, target, relation).
• derive_node_id function — Derive a deterministic node id from a kind + identity tuple.

cjm_context_graph_layer.journal

• MissingRegistry class — The env lacks a replay registry the workflow lane declares: refused when a writer opens,
• UnjournaledWrite class — A write on a journal-sourced graph with no journal path and no explicit unjournaled=True
• apply_op function — Apply ONE journaled op -- the dispatch replay runs per op and a live writer runs after its
• apply_wires function — The generic replay handler for wire-carrying ops (the single wires-replay authority).
• composed_replay_handlers function — Union every installed core's replay registry (DEC 426658f1 — the d066826a fix).
• genesis_export function — One-time whole-db GENESIS BASELINE: journal every node + edge as genesis ops.
• graph_writer function — The write order on a workflow graph (design detail 65f4a6c9): a JournalWriter whose cursors
• installed_handlers function — Every installed core's replay registry, composed once per process (read-only). The applier of
• journal_extend function — Idempotent extend + journal the DELTA — the pipeline-write append-through, on the write
• journal_op function — Journal one planned op, then apply it -- the write order for an op whose apply is its verb's
• refuse_unjournaled function — The one refusal of an unjournaled default (design detail 65f4a6c9 (3)): every write path of
• replay_journal function — Re-apply every journaled op in append order — the db-from-journal rebuild.
• sidecar_journal_path function — The db's sidecar journal path (DEC ccbab9f5 point 3: placement is per-workflow,
• wires_handlers function — Convenience registry: every named verb replays via apply_wires.
• workflow_handlers function — The workflow lane's replay registry (ruling 6683f49e (2)): the composed union, checked
• write_window function — A core verb's unit of work on a workflow graph (ruling 6683f49e (1)): the family's writer --

cjm_context_graph_layer.ops

• ExtendPlan class — What an extend would write, read off the graph and written nowhere (ruling 6683f49e (1)):
• ExtendResult class — Outcome of one idempotent extend_graph commit.
• GraphCursorStore class — A graph store's applied cursors as a writer's CursorStore (design detail 65f4a6c9 (2c)): the
• GraphIntegrityError class — An emitted node collided with an existing node of different identity content.
• extend_graph function — Idempotently extend the graph: emit-if-absent + verify-if-present.
• graph_task function — Invoke a graph-storage adapter method through the queue's task channel.
• node_identity_mismatch function — Verify-if-present check: label + sources content-hash set must match.
• observe_writes function — Collect every storage write made inside the block, one record per write:
• partition_by_presence function — Split wire dicts into absent (to add) and present (to verify).
• plan_extend function — The read half of extend_graph: one batched presence check per kind. Present nodes are
• stamp_op_time function — Stamp the op clock's time onto an element about to be added — the one function live
• store_covariates function — The store half of the instrument's growth covariates (design detail 681604c1): the nodes,

cjm_context_graph_layer.rebuild

• AdoptRefusal class — An adoption refused: the live db is not the journal's projection, or the drop list does not
• GraphStore class — A started graph: the queue + the capability id to address it.
• adopt_db function — THE ADOPTION (ruling 6683f49e (4), a verb by e35be447): a db written before its applied
• adopt_main function — The cjm-workflow-adopt console entrypoint -- a live workflow db adopts its journal
• diff_dbs function — Compare two workflow dbs element for element, both read-only, streamed side by side.
• diff_main function — The cjm-workflow-diff console entrypoint — two existing workflow dbs, compared
• main function — The cjm-workflow-rebuild console entrypoint — one command, fresh db from journal.
• open_store function — Stand up the graph capability on db_path and a started queue — the cores' own runtime
• rebuild_db function — Rebuild db_path from the journal — substrate standup + composed replay.

cjm_context_graph_layer.testing

• MemGraph class — An in-memory graph store behind a fake queue: the storage methods the write order uses.
• ProofContext class — What a step's call gets: the started store, the run's journal, and the run's earlier records.
• ProofStep class — One step of a core's crash-proof scenario: an async call(ctx) -- module-level, so a child
• crash_variants function — Every boundary a crash can fall on, as the runs that crash each step there: a unit torn
• run_proof function — Run a scenario once, every step in a child process, each crashed at variant and then healed

Dependencies

Depends on: cjm-context-graph-primitives, cjm-substrate Used by: cjm-context-graph-projection, cjm-dev-graph-schema, cjm-markdown-decompose-core, cjm-notebook-decompose-core, cjm-session-scratchpad-qt, cjm-transcript-correction-core, cjm-transcript-correction-qt, cjm-transcript-decomp-core, cjm-transcript-decomp-qt, cjm-transcript-graph-schema, cjm-transcription-core, cjm-workflow-hub-qt