cjm-transcript-correction-core 0.0.3__tar.gz → 0.0.5__tar.gz

{cjm_transcript_correction_core-0.0.3/cjm_transcript_correction_core.egg-info → cjm_transcript_correction_core-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cjm-transcript-correction-core
-Version: 0.0.3
+Version: 0.0.5
 Summary: A frontend-agnostic core for the transcript correction workflow — the first downstream graph-extension core; composes the graph-storage capability worker into a headless pipeline that applies unified, non-destructive corrections (text, punctuation, segmentation) as a supersede-able overlay on a committed decomposition spine, recomputes the review worklist from deterministic signals, and exposes a CLI as its first driver.
 Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
 License: Apache-2.0
@@ -10,9 +10,9 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: cjm_substrate>=0.0.51
-Requires-Dist: cjm_context_graph_primitives>=0.0.14
-Requires-Dist: cjm-context-graph-layer>=0.0.10
+Requires-Dist: cjm_substrate>=0.0.57
+Requires-Dist: cjm_context_graph_primitives>=0.0.15
+Requires-Dist: cjm-context-graph-layer>=0.0.11
 Requires-Dist: cjm-transcript-graph-schema>=0.0.7
 Dynamic: license-file
 
@@ -40,37 +40,67 @@ A frontend-agnostic core for the transcript correction workflow — the first do
 - `main` _function_ — CLI entry point (console script: `cjm-transcript-correction-core`).
 - `review_command` _function_ — Execute the `review` subcommand: interactive text corrections over the flagged worklist.
 - `run_command` _function_ — Execute the `run` subcommand: correct a decomp manifest's committed spine.
+- `stats_command` _function_ — Execute the `stats` subcommand: flywheel accounting over the shared graph.
 
 ### `cjm_transcript_correction_core.graph`
 
 - `active_corrections` _function_ — Filter to the effective correction set (the layer's resolve_active over a read superseded set).
+- `active_speaker_assignments` _function_ — Project the ACTIVE speaker assignment per segment (latest-wins).
+- `aggregate_session_purposes` _function_ — Fold sessions into a per-source purpose mix (pure; d915d545 picker rung).
+- `apply_chunk_inserts` _function_ — Synthesize inserted chunks into the effective spine (DEC 3d3fa2a8).
+- `apply_time_nudges` _function_ — Apply timing corrections onto segment times (latest-wins per edge).
 - `build_boundary_shift_correction` _function_ — Build a grouping Correction that moves text across one segment boundary.
+- `build_chunk_insert_correction` _function_ — Build an insertion Correction that adds a chunk the skeleton never cut (DEC 3d3fa2a8).
+- `build_chunk_split_corrections` _function_ — Compose a chunk SPLIT from the EXISTING verbs (work item 99c1d2ba) — no
 - `build_correction_node` _function_ — Construct a Correction overlay node (pure; commit happens separately).
+- `build_mark_correction` _function_ — Build a NON-MUTATING mark Correction (DEC 2a231843: routed attention).
 - `build_prune_amendment` _function_ — Build a grouping Correction that supersedes a prune with a REDUCED set (unprune).
 - `build_prune_correction` _function_ — Build one batch grouping Correction that prunes empty segments (D14).
 - `build_reject_review` _function_ — Build a review Correction that REJECTS a prior correction (reject-as-supersede).
+- `build_speaker_assign_correction` _function_ — Build a speaker Correction — the assignment op envelope (DEC d6df3a8e).
 - `build_text_correction` _function_ — Build a text_content Correction + its CORRECTS (+ optional SUPERSEDES) edges.
+- `build_time_nudge_correction` _function_ — Build a timing Correction that nudges segment boundary TIMES (node + CORRECTS edges).
 - `commit_boundary_shift_correction` _function_ — Commit a boundary-shift correction (node + CORRECTS x2 [+ SUPERSEDES]) + REVIEWED markers on both segments.
+- `commit_chunk_insert_correction` _function_ — Commit a chunk insertion (node + CORRECTS per flank).
+- `commit_chunk_insert_removal` _function_ — Remove an inserted chunk WITHOUT touching layer-0 (reject-as-supersede).
+- `commit_chunk_split_correction` _function_ — Commit a chunk split: three composed nodes in ONE atomic batch + ONE journal op.
+- `commit_chunk_split_removal` _function_ — UNSPLIT: remove a split's right half AND its whole group (one review
+- `commit_mark_correction` _function_ — Commit a mark (node + CORRECTS per anchored segment [+ SUPERSEDES]).
+- `commit_mark_dismissal` _function_ — Dismiss an open mark WITHOUT a correction (reject-as-supersede).
 - `commit_nodes_edges` _function_ — Commit overlay nodes/edges through the layer's idempotent extend_graph.
 - `commit_prune_amendment` _function_ — Commit an unprune amendment (node + DERIVED_FROM edges + SUPERSEDES).
+- `commit_speaker_assign_correction` _function_ — Commit a speaker assignment (node + CORRECTS per segment + ASSIGNS).
+- `commit_speaker_entity` _function_ — Mint a source-spanning Entity into the shared registry (DEC 4ec6a49c).
 - `commit_text_correction` _function_ — Commit a text_content correction (node + CORRECTS [+ SUPERSEDES]) + a REVIEWED marker.
+- `commit_time_nudge_correction` _function_ — Commit a time-nudge correction (node + CORRECTS per touched segment).
+- `correction_stats` _function_ — Fold one Source's ACTIVE overlay into flywheel-accounting counts (pure).
 - `corrections_to_edits` _function_ — Map this core's Correction payloads onto the layer's spine-edit vocabulary.
-- `count_source_segments` _function_ — Count a Source's segments server-side under its chosen rendition (typed count mode).
+- `count_source_segments` _function_ — Count a Source's segments server-side under its chosen rendition + skeleton (typed count mode).
 - `find_active_text_correction` _function_ — Single-segment convenience over the batch read (cross-session; latest wins).
 - `find_active_text_corrections_batch` _function_ — Active text corrections for MANY segments in TWO round-trips (C17).
+- `find_chunk_split_group` _function_ — Resolve a split right-half's GROUP — the ac84360a group marker cashed in.
 - `find_corrections_for_session` _function_ — List corrections recorded in a session (typed property filter).
 - `find_prior_corrections_by_hash` _function_ — Cross-transcript correction-cache lookup (targeted; the graph IS the lexicon).
 - `get_session` _function_ — Fetch a CorrectionSession node by id (resume/reopen) — typed get, dict shape preserved.
+- `list_source_spines` _function_ — The SPINES coexisting under a Source's chosen rendition (DEC f1024568).
+- `list_speaker_entities` _function_ — Read the source-spanning entity registry (the picker's registry tier).
 - `load_empty_segments` _function_ — Load ONLY a Source's empty-text segments under its chosen rendition (D14 prune).
 - `load_review_markers` _function_ — Load a session's review markers (typed edge projection over REVIEWED edges).
 - `load_source_corrections` _function_ — Load every Correction targeting a Source (across sessions) + the superseded-id set.
-- `load_source_segments` _function_ — Load a Source's fine Segment spine under its chosen rendition (typed query surface).
+- `load_source_segments` _function_ — Load a Source's fine Segment spine under its chosen rendition + skeleton (typed query surface).
 - `load_variant_texts` _function_ — Resolve per-transcriber chunk texts from the segments' CharSlice refs.
+- `mark_anchor_segments` _function_ — Validate a mark anchor and list the Segment ids it touches.
+- `open_marks` _function_ — Filter to the OPEN marks — the pass-2 worklist ('query open marks, walk them').
 - `project_effective_spine` _function_ — Project the effective spine = layer-0 + applied corrections.
+- `reanchor_span` _function_ — Re-locate a span anchor in text that may have been edited since mark time.
 - `record_review_markers` _function_ — Persist per-(session, segment) review markers as REVIEWED edges.
+- `rename_speaker_entity` _function_ — Rename an Entity on its STABLE id — identification IS a rename (DEC 484e2d74).
 - `resolve_source_renditions` _function_ — Pick the AudioRendition set whose fine Segment spine correction operates on.
+- `session_purposes_by_source` _function_ — Read every CorrectionSession once and fold the per-source purpose mix.
+- `set_session_purpose` _function_ — Update a session's purpose + updated_at (the test-session hygiene tag, DEC c86714a4).
 - `set_session_status` _function_ — Update a session's status + updated_at.
 - `source_audio_segment_ids` _function_ — The Source's coarse spine (one small typed read; ordered by index).
+- `spine_where_for` _function_ — Resolve a skeleton selector against the observed spine set (pure).
 - `start_session` _function_ — Create + commit a new CorrectionSession node.
 - `submit_and_wait` _function_ — Submit one capability job, wait for it, return its result (raise on failure).
 
@@ -87,6 +117,7 @@ A frontend-agnostic core for the transcript correction workflow — the first do
 - `CorrectionManifest` _class_ — Durable record of one correction run (proto-bundle; chainable, CR-20).
 - `CorrectionRelations` _class_ — Registry of edge types the correction overlay adds to the spine graph.
 - `CorrectionSession` _class_ — A resumable, reopen-able correction review over one or more sources.
+- `Entity` _class_ — A source-spanning identity in the shared entity substrate (DEC 4ec6a49c).
 - `SpineSegment` _class_ — A committed layer-0 Segment loaded from the graph (read view).
 - `WorklistItem` _class_ — One spine segment surfaced for review, with its deterministic Tier-1 flags.
 - `new_run_id` _function_ — Generate a unique, sortable correction run id.
@@ -112,9 +143,10 @@ A frontend-agnostic core for the transcript correction workflow — the first do
 - `fa_coverage_flags` _function_ — Flag segments whose forced-alignment coverage looks suspect (Tier-1).
 - `levenshtein` _function_ — Levenshtein edit distance (pure, in-core; variant-clustering primitive).
 - `phonetic_key` _function_ — Compute a coarse phonetic key for a word (groups like-sounding variants).
+- `speaker_turn_proposals` _function_ — Dominant diarization cluster per segment — the assign lane's proposal paint.
 - `variant_divergence` _function_ — Within-segment cross-transcriber divergence (stage 5: intra-graph).
 
 ## Dependencies
 
 **Depends on:** `cjm-context-graph-layer`, `cjm-context-graph-primitives`, `cjm-substrate`, `cjm-transcript-graph-schema`
-**Used by:** `cjm-transcript-correction-tui`
+**Used by:** `cjm-transcript-correction-tui`, `cjm-workflow-hub-tui`

{cjm_transcript_correction_core-0.0.3 → cjm_transcript_correction_core-0.0.5}/README.md

@@ -22,37 +22,67 @@ A frontend-agnostic core for the transcript correction workflow — the first do
 - `main` _function_ — CLI entry point (console script: `cjm-transcript-correction-core`).
 - `review_command` _function_ — Execute the `review` subcommand: interactive text corrections over the flagged worklist.
 - `run_command` _function_ — Execute the `run` subcommand: correct a decomp manifest's committed spine.
+- `stats_command` _function_ — Execute the `stats` subcommand: flywheel accounting over the shared graph.
 
 ### `cjm_transcript_correction_core.graph`
 
 - `active_corrections` _function_ — Filter to the effective correction set (the layer's resolve_active over a read superseded set).
+- `active_speaker_assignments` _function_ — Project the ACTIVE speaker assignment per segment (latest-wins).
+- `aggregate_session_purposes` _function_ — Fold sessions into a per-source purpose mix (pure; d915d545 picker rung).
+- `apply_chunk_inserts` _function_ — Synthesize inserted chunks into the effective spine (DEC 3d3fa2a8).
+- `apply_time_nudges` _function_ — Apply timing corrections onto segment times (latest-wins per edge).
 - `build_boundary_shift_correction` _function_ — Build a grouping Correction that moves text across one segment boundary.
+- `build_chunk_insert_correction` _function_ — Build an insertion Correction that adds a chunk the skeleton never cut (DEC 3d3fa2a8).
+- `build_chunk_split_corrections` _function_ — Compose a chunk SPLIT from the EXISTING verbs (work item 99c1d2ba) — no
 - `build_correction_node` _function_ — Construct a Correction overlay node (pure; commit happens separately).
+- `build_mark_correction` _function_ — Build a NON-MUTATING mark Correction (DEC 2a231843: routed attention).
 - `build_prune_amendment` _function_ — Build a grouping Correction that supersedes a prune with a REDUCED set (unprune).
 - `build_prune_correction` _function_ — Build one batch grouping Correction that prunes empty segments (D14).
 - `build_reject_review` _function_ — Build a review Correction that REJECTS a prior correction (reject-as-supersede).
+- `build_speaker_assign_correction` _function_ — Build a speaker Correction — the assignment op envelope (DEC d6df3a8e).
 - `build_text_correction` _function_ — Build a text_content Correction + its CORRECTS (+ optional SUPERSEDES) edges.
+- `build_time_nudge_correction` _function_ — Build a timing Correction that nudges segment boundary TIMES (node + CORRECTS edges).
 - `commit_boundary_shift_correction` _function_ — Commit a boundary-shift correction (node + CORRECTS x2 [+ SUPERSEDES]) + REVIEWED markers on both segments.
+- `commit_chunk_insert_correction` _function_ — Commit a chunk insertion (node + CORRECTS per flank).
+- `commit_chunk_insert_removal` _function_ — Remove an inserted chunk WITHOUT touching layer-0 (reject-as-supersede).
+- `commit_chunk_split_correction` _function_ — Commit a chunk split: three composed nodes in ONE atomic batch + ONE journal op.
+- `commit_chunk_split_removal` _function_ — UNSPLIT: remove a split's right half AND its whole group (one review
+- `commit_mark_correction` _function_ — Commit a mark (node + CORRECTS per anchored segment [+ SUPERSEDES]).
+- `commit_mark_dismissal` _function_ — Dismiss an open mark WITHOUT a correction (reject-as-supersede).
 - `commit_nodes_edges` _function_ — Commit overlay nodes/edges through the layer's idempotent extend_graph.
 - `commit_prune_amendment` _function_ — Commit an unprune amendment (node + DERIVED_FROM edges + SUPERSEDES).
+- `commit_speaker_assign_correction` _function_ — Commit a speaker assignment (node + CORRECTS per segment + ASSIGNS).
+- `commit_speaker_entity` _function_ — Mint a source-spanning Entity into the shared registry (DEC 4ec6a49c).
 - `commit_text_correction` _function_ — Commit a text_content correction (node + CORRECTS [+ SUPERSEDES]) + a REVIEWED marker.
+- `commit_time_nudge_correction` _function_ — Commit a time-nudge correction (node + CORRECTS per touched segment).
+- `correction_stats` _function_ — Fold one Source's ACTIVE overlay into flywheel-accounting counts (pure).
 - `corrections_to_edits` _function_ — Map this core's Correction payloads onto the layer's spine-edit vocabulary.
-- `count_source_segments` _function_ — Count a Source's segments server-side under its chosen rendition (typed count mode).
+- `count_source_segments` _function_ — Count a Source's segments server-side under its chosen rendition + skeleton (typed count mode).
 - `find_active_text_correction` _function_ — Single-segment convenience over the batch read (cross-session; latest wins).
 - `find_active_text_corrections_batch` _function_ — Active text corrections for MANY segments in TWO round-trips (C17).
+- `find_chunk_split_group` _function_ — Resolve a split right-half's GROUP — the ac84360a group marker cashed in.
 - `find_corrections_for_session` _function_ — List corrections recorded in a session (typed property filter).
 - `find_prior_corrections_by_hash` _function_ — Cross-transcript correction-cache lookup (targeted; the graph IS the lexicon).
 - `get_session` _function_ — Fetch a CorrectionSession node by id (resume/reopen) — typed get, dict shape preserved.
+- `list_source_spines` _function_ — The SPINES coexisting under a Source's chosen rendition (DEC f1024568).
+- `list_speaker_entities` _function_ — Read the source-spanning entity registry (the picker's registry tier).
 - `load_empty_segments` _function_ — Load ONLY a Source's empty-text segments under its chosen rendition (D14 prune).
 - `load_review_markers` _function_ — Load a session's review markers (typed edge projection over REVIEWED edges).
 - `load_source_corrections` _function_ — Load every Correction targeting a Source (across sessions) + the superseded-id set.
-- `load_source_segments` _function_ — Load a Source's fine Segment spine under its chosen rendition (typed query surface).
+- `load_source_segments` _function_ — Load a Source's fine Segment spine under its chosen rendition + skeleton (typed query surface).
 - `load_variant_texts` _function_ — Resolve per-transcriber chunk texts from the segments' CharSlice refs.
+- `mark_anchor_segments` _function_ — Validate a mark anchor and list the Segment ids it touches.
+- `open_marks` _function_ — Filter to the OPEN marks — the pass-2 worklist ('query open marks, walk them').
 - `project_effective_spine` _function_ — Project the effective spine = layer-0 + applied corrections.
+- `reanchor_span` _function_ — Re-locate a span anchor in text that may have been edited since mark time.
 - `record_review_markers` _function_ — Persist per-(session, segment) review markers as REVIEWED edges.
+- `rename_speaker_entity` _function_ — Rename an Entity on its STABLE id — identification IS a rename (DEC 484e2d74).
 - `resolve_source_renditions` _function_ — Pick the AudioRendition set whose fine Segment spine correction operates on.
+- `session_purposes_by_source` _function_ — Read every CorrectionSession once and fold the per-source purpose mix.
+- `set_session_purpose` _function_ — Update a session's purpose + updated_at (the test-session hygiene tag, DEC c86714a4).
 - `set_session_status` _function_ — Update a session's status + updated_at.
 - `source_audio_segment_ids` _function_ — The Source's coarse spine (one small typed read; ordered by index).
+- `spine_where_for` _function_ — Resolve a skeleton selector against the observed spine set (pure).
 - `start_session` _function_ — Create + commit a new CorrectionSession node.
 - `submit_and_wait` _function_ — Submit one capability job, wait for it, return its result (raise on failure).
 
@@ -69,6 +99,7 @@ A frontend-agnostic core for the transcript correction workflow — the first do
 - `CorrectionManifest` _class_ — Durable record of one correction run (proto-bundle; chainable, CR-20).
 - `CorrectionRelations` _class_ — Registry of edge types the correction overlay adds to the spine graph.
 - `CorrectionSession` _class_ — A resumable, reopen-able correction review over one or more sources.
+- `Entity` _class_ — A source-spanning identity in the shared entity substrate (DEC 4ec6a49c).
 - `SpineSegment` _class_ — A committed layer-0 Segment loaded from the graph (read view).
 - `WorklistItem` _class_ — One spine segment surfaced for review, with its deterministic Tier-1 flags.
 - `new_run_id` _function_ — Generate a unique, sortable correction run id.
@@ -94,9 +125,10 @@ A frontend-agnostic core for the transcript correction workflow — the first do
 - `fa_coverage_flags` _function_ — Flag segments whose forced-alignment coverage looks suspect (Tier-1).
 - `levenshtein` _function_ — Levenshtein edit distance (pure, in-core; variant-clustering primitive).
 - `phonetic_key` _function_ — Compute a coarse phonetic key for a word (groups like-sounding variants).
+- `speaker_turn_proposals` _function_ — Dominant diarization cluster per segment — the assign lane's proposal paint.
 - `variant_divergence` _function_ — Within-segment cross-transcriber divergence (stage 5: intra-graph).
 
 ## Dependencies
 
 **Depends on:** `cjm-context-graph-layer`, `cjm-context-graph-primitives`, `cjm-substrate`, `cjm-transcript-graph-schema`
-**Used by:** `cjm-transcript-correction-tui`
+**Used by:** `cjm-transcript-correction-tui`, `cjm-workflow-hub-tui`

cjm_transcript_correction_core-0.0.5/cjm_transcript_correction_core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.5"

{cjm_transcript_correction_core-0.0.3 → cjm_transcript_correction_core-0.0.5}/cjm_transcript_correction_core/cli.py

@@ -3,11 +3,16 @@
 import argparse
 import asyncio
 import logging
+import os
 from pathlib import Path
 from typing import Dict, List, Optional
 
+from cjm_context_graph_layer.ops import graph_task
+from cjm_context_graph_primitives.query import NodeQuery
 from cjm_substrate.core.manager import CapabilityManager
 from cjm_substrate.core.queue import JobQueue
+from cjm_substrate.core.workspace import resolve_workspace
+from cjm_transcript_correction_core.graph import correction_stats, load_source_corrections
 from cjm_transcript_correction_core.models import CorrectionConfig
 from cjm_transcript_correction_core.pipeline import (load_decomp_manifest, resolve_graph_db_path,
                                                      run_correction, run_review)
@@ -18,7 +23,13 @@ logger = logging.getLogger(__name__)
 def _add_common_run_args(p: argparse.ArgumentParser) -> None:  # Shared run/review arguments
     """Attach the capability / session / output arguments shared by `run` and `review`."""
     p.add_argument("manifest", help="Decomp-core run manifest JSON (the committed spine)")
-    p.add_argument("--manifests-dir", default=".cjm/manifests", help="Capability manifests directory")
+    p.add_argument("--manifests-dir", default=None,
+                   help="Capability manifests directory (default: the workspace's .cjm/manifests "
+                        "when one is active, else .cjm/manifests under the cwd)")
+    p.add_argument("--workspace", default=None,
+                   help="Workspace root (5daadfc4; default: CJM_WORKSPACE env, else upward walk "
+                        "from cwd). Supplies manifests/output defaults and is exported so "
+                        "capability workers resolve workspace-scoped paths")
     p.add_argument("--graph-capability", default="cjm-capability-graph-sqlite", help="Graph-storage capability name")
     p.add_argument("--graph-db-path", default=None,
                    help="Override graph DB path (default: the decomp manifest's recorded db_path)")
@@ -26,12 +37,18 @@ def _add_common_run_args(p: argparse.ArgumentParser) -> None:  # Shared run/revi
                    help="Which AudioRendition spine to correct when a source has more than one "
                         "(\"raw\" or a preprocessing substring e.g. \"demucs\"); default: auto-select the "
                         "decomposed one (errors if ambiguous)")
+    p.add_argument("--skeleton", default=None,
+                   help="Which SKELETON spine to correct when several coexist under one rendition "
+                        "(sentence-split, DEC f1024568): \"legacy\" = the pre-split spine, or a "
+                        "skeleton-hash prefix; default: auto (errors when >1 coexist)")
     p.add_argument("--sysmon-capability", default=None,
                    help="monitor for empirical attribution (CR-7); loaded first; default: none")
     p.add_argument("--session", default=None, help="Resume an existing CorrectionSession id")
     p.add_argument("--reopen", action="store_true", help="Reopen a completed session (with --session)")
     p.add_argument("--actor", default="human", help="Actor recorded on corrections + review markers")
-    p.add_argument("--output", default=None, help="Correction-manifest output path (default: runs/<run_id>.json)")
+    p.add_argument("--output", default=None,
+                   help="Correction-manifest output path (default: <workspace>/runs/<run_id>.json "
+                        "when a workspace is active, else runs/<run_id>.json under the cwd)")
     p.add_argument("-v", "--verbose", action="store_true", help="DEBUG-level logging")
 
 
@@ -56,6 +73,26 @@ def build_parser() -> argparse.ArgumentParser:  # Configured CLI parser
     _add_common_run_args(review)
     review.add_argument("--review-max", type=int, default=0, help="Max worklist items to review (0 = all)")
     review.add_argument("-y", "--yes", action="store_true", help="Auto-mark every reviewed item (no edits)")
+
+    stats = sub.add_parser(
+        "stats", help="Flywheel accounting: active labeled spans / open marks / op counts per source")
+    stats.add_argument("--manifests-dir", default=None,
+                       help="Capability manifests directory (default: the workspace's .cjm/manifests "
+                            "when one is active, else .cjm/manifests under the cwd)")
+    stats.add_argument("--workspace", default=None,
+                       help="Workspace root (default: CJM_WORKSPACE env, else upward walk from cwd)")
+    stats.add_argument("--graph-capability", default="cjm-capability-graph-sqlite",
+                       help="Graph-storage capability name")
+    stats.add_argument("--graph-db-path", default=None,
+                       help="Graph db path (default: the capability's persisted workspace config)")
+    stats.add_argument("--source", default=None,
+                       help="Source node id or title substring (default: every Source)")
+    stats.add_argument("--label", default=None,
+                       help="Spotlight one label/class (e.g. inhale): prints its insert+mark grand total")
+    stats.add_argument("--genuine-only", action="store_true",
+                       help="Count only corrections from GENUINE sessions (purpose unset/genuine — "
+                            "feature-test noise excluded, DEC c86714a4); supersession stays global")
+    stats.add_argument("-v", "--verbose", action="store_true", help="DEBUG-level logging")
     return parser
 
 
@@ -84,6 +121,14 @@ async def run_command(
     args: argparse.Namespace,  # Parsed args for the `run` subcommand
 ) -> int:  # Process exit code
     """Execute the `run` subcommand: correct a decomp manifest's committed spine."""
+    # 5daadfc4 workspace: resolve BEFORE any substrate config loads; export so
+    # the process tree (substrate config, capability workers) is workspace-scoped.
+    ws = resolve_workspace(explicit=getattr(args, "workspace", None))
+    if ws is not None:
+        os.environ["CJM_WORKSPACE"] = str(ws.root)
+    if args.manifests_dir is None:
+        args.manifests_dir = (str(ws.substrate_data_dir / "manifests")
+                              if ws is not None else ".cjm/manifests")
     manifest_path = str(Path(args.manifest).resolve())
     if not Path(manifest_path).exists():
         raise SystemExit(f"decomp manifest not found: {manifest_path}")
@@ -96,7 +141,7 @@ async def run_command(
     cfg = CorrectionConfig(
         graph_capability=args.graph_capability, graph_db_path=graph_db_path,
         actor=args.actor, assume_yes=args.yes, prune_empty=not args.no_prune,
-        rendition_selector=args.rendition,
+        rendition_selector=args.rendition, skeleton_selector=args.skeleton,
     )
 
     manager = CapabilityManager(
@@ -122,8 +167,9 @@ async def run_command(
             except Exception as e:  # Best-effort teardown; never mask the run's outcome
                 logger.warning(f"unload {iid} failed: {e}")
 
-    out = Path(args.output) if args.output else Path("runs") / f"{manifest.run_id}.json"
-    manifest.save(out)
+    out = (Path(args.output) if args.output
+           else (ws.runs_dir if ws is not None else Path("runs")) / f"{manifest.run_id}.json")
+    manifest.save(out, workspace=ws)
     n_sources = len(manifest.sources)
     n_pruned = sum(s.get("pruned", 0) for s in manifest.sources)
     n_flagged = sum(s.get("worklist_flagged", 0) for s in manifest.sources)
@@ -137,6 +183,13 @@ async def review_command(
     args: argparse.Namespace,  # Parsed args for the `review` subcommand
 ) -> int:  # Process exit code
     """Execute the `review` subcommand: interactive text corrections over the flagged worklist."""
+    # 5daadfc4 workspace: same early resolution + export as run_command.
+    ws = resolve_workspace(explicit=getattr(args, "workspace", None))
+    if ws is not None:
+        os.environ["CJM_WORKSPACE"] = str(ws.root)
+    if args.manifests_dir is None:
+        args.manifests_dir = (str(ws.substrate_data_dir / "manifests")
+                              if ws is not None else ".cjm/manifests")
     manifest_path = str(Path(args.manifest).resolve())
     if not Path(manifest_path).exists():
         raise SystemExit(f"decomp manifest not found: {manifest_path}")
@@ -147,7 +200,7 @@ async def review_command(
 
     cfg = CorrectionConfig(graph_capability=args.graph_capability, graph_db_path=graph_db_path,
                            actor=args.actor, assume_yes=args.yes, prune_empty=False,
-                           rendition_selector=args.rendition)
+                           rendition_selector=args.rendition, skeleton_selector=args.skeleton)
     manager = CapabilityManager(search_paths=[Path(args.manifests_dir)], sysmon_capability_name=args.sysmon_capability)
     load_order = ([args.sysmon_capability] if args.sysmon_capability else []) + [cfg.graph_capability]
     load_capabilities(manager, load_order, configs={cfg.graph_capability: {"db_path": graph_db_path}})
@@ -167,8 +220,9 @@ async def review_command(
             except Exception as e:  # Best-effort teardown; never mask the run's outcome
                 logger.warning(f"unload {iid} failed: {e}")
 
-    out = Path(args.output) if args.output else Path("runs") / f"{manifest.run_id}.json"
-    manifest.save(out)
+    out = (Path(args.output) if args.output
+           else (ws.runs_dir if ws is not None else Path("runs")) / f"{manifest.run_id}.json")
+    manifest.save(out, workspace=ws)
     n_corr = sum(s.get("corrected", 0) for s in manifest.sources)
     n_active = sum(s.get("active_corrections", 0) for s in manifest.sources)
     print(f"correction manifest: {out}")
@@ -190,4 +244,99 @@ def main(
         return asyncio.run(run_command(args))
     if args.command == "review":
         return asyncio.run(review_command(args))
+    if args.command == "stats":
+        return asyncio.run(stats_command(args))
     raise SystemExit(f"unknown command: {args.command}")
+
+
+async def stats_command(
+    args: argparse.Namespace,  # Parsed args for the `stats` subcommand
+) -> int:  # Process exit code
+    """Execute the `stats` subcommand: flywheel accounting over the shared graph.
+
+    The manual-tally retirement (drive ask 2026-07-27): per Source, the ACTIVE
+    overlay folds into counts — labeled insert spans, split boundaries, open
+    marks by class, op totals — plus the session purpose mix so dev-noise is
+    visible; --genuine-only cuts the counts to genuine-session corrections
+    (the DEC c86714a4 tag), --label spotlights one class corpus-wide (the
+    "how many active inhale spans?" one-liner)."""
+    ws = resolve_workspace(explicit=getattr(args, "workspace", None))
+    if ws is not None:
+        os.environ["CJM_WORKSPACE"] = str(ws.root)
+    if args.manifests_dir is None:
+        args.manifests_dir = (str(ws.substrate_data_dir / "manifests")
+                              if ws is not None else ".cjm/manifests")
+    manager = CapabilityManager(search_paths=[Path(args.manifests_dir)])
+    configs = ({args.graph_capability: {"db_path": args.graph_db_path}}
+               if args.graph_db_path else None)
+    load_capabilities(manager, [args.graph_capability], configs=configs)
+    queue = JobQueue(deps=manager)
+    await queue.start()
+    try:
+        res = await graph_task(queue, args.graph_capability, "query_nodes",
+                               query=NodeQuery(label="Source", project=["title"]).to_dict())
+        sources = [(r["id"], str(r.get("title") or "")) for r in (res.rows or [])]
+        if args.source:
+            needle = args.source.lower()
+            sources = [(i, t) for i, t in sources
+                       if i == args.source or needle in t.lower()]
+        if not sources:
+            print("no matching Source nodes")
+            return 1
+        sres = await graph_task(queue, args.graph_capability, "query_nodes",
+                                query=NodeQuery(label="CorrectionSession").to_dict())
+        genuine_ids = set()
+        purpose_of: Dict[str, str] = {}
+        for n in (sres.nodes or []):
+            d = n.to_dict() if hasattr(n, "to_dict") else n
+            purpose = str((d.get("properties") or {}).get("purpose") or "genuine")
+            purpose_of[d["id"]] = purpose
+            if purpose == "genuine":
+                genuine_ids.add(d["id"])
+        totals: Dict[str, Dict[str, int]] = {"insert_labels": {}, "mark_classes": {}}
+        total_splits = 0
+        for sid, title in sources:
+            corrections, superseded = await load_source_corrections(
+                queue, args.graph_capability, sid)
+            counted = corrections
+            if args.genuine_only:
+                # Purpose scopes the COUNTS; the superseded set stays global —
+                # supersession is spine state whoever committed it.
+                counted = [c for c in corrections if c.get("session_id") in genuine_ids]
+            st = correction_stats(counted, superseded)
+            mix: Dict[str, int] = {}
+            for c in corrections:
+                p = purpose_of.get(str(c.get("session_id")), "genuine")
+                mix[p] = mix.get(p, 0) + 1
+            print(f"== {title or sid}  ({sid}) ==")
+            print("  ops by session purpose: "
+                  + (" ".join(f"{k}x{v}" for k, v in sorted(mix.items())) or "none"))
+            print(f"  active corrections: {st['active']}  ("
+                  + (" ".join(f"{k}={v}" for k, v in sorted(st["ops"].items())) or "none") + ")")
+            print(f"  splits: {st['splits']}")
+            print("  labeled inserts: "
+                  + (" · ".join(f"{k}x{v}" for k, v in sorted(st["insert_labels"].items())) or "none"))
+            print(f"  open marks ({st['open_marks']}): "
+                  + (" · ".join(f"{k}x{v}" for k, v in sorted(st["mark_classes"].items())) or "none"))
+            total_splits += st["splits"]
+            for k, v in st["insert_labels"].items():
+                totals["insert_labels"][k] = totals["insert_labels"].get(k, 0) + v
+            for k, v in st["mark_classes"].items():
+                totals["mark_classes"][k] = totals["mark_classes"].get(k, 0) + v
+        print(f"== TOTALS ({len(sources)} source(s)) ==")
+        print(f"  splits: {total_splits}")
+        print("  labeled inserts: "
+              + (" · ".join(f"{k}x{v}" for k, v in sorted(totals["insert_labels"].items())) or "none"))
+        print("  open marks: "
+              + (" · ".join(f"{k}x{v}" for k, v in sorted(totals["mark_classes"].items())) or "none"))
+        if args.label:
+            ins = totals["insert_labels"].get(args.label, 0)
+            mk = totals["mark_classes"].get(args.label, 0)
+            print(f"  active {args.label!r} spans: {ins + mk} (inserts {ins} + marks {mk})")
+    finally:
+        await queue.stop()
+        try:
+            manager.unload_capability(args.graph_capability)
+        except Exception as e:  # Best-effort teardown; never mask the stats outcome
+            logger.warning(f"unload {args.graph_capability} failed: {e}")
+    return 0