Metadata-Version: 2.4
Name: cjm-context-graph-layer
Version: 0.0.18
Summary: 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.
Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
License: Apache-2.0
Project-URL: Repository, https://github.com/cj-mills/cjm-context-graph-layer
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cjm-context-graph-primitives>=0.0.19
Requires-Dist: cjm-substrate>=0.0.51
Dynamic: license-file

# cjm-context-graph-layer

<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->

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.

## 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).
- `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_journal` _function_ — Move every wire on the retired ids out of the journal family into ONE new archive segment.
- `next_archive_path` _function_
- `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.
- `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`

- `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.
- `journal_extend` _function_ — Idempotent extend + journal the DELTA — the pipeline-write append-through.
- `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`.

### `cjm_context_graph_layer.ops`

- `ExtendResult` _class_ — Outcome of one idempotent extend_graph commit.
- `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).
- `stamp_op_time` _function_ — Stamp the op clock's time onto an element about to be added — the one function live

### `cjm_context_graph_layer.rebuild`

- `GraphStore` _class_ — A started graph: the queue + the capability id to address it.
- `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.

## 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-graph-schema`, `cjm-transcription-core`, `cjm-workflow-hub-qt`
