cjm-transcript-decomp-core 0.0.1__py3-none-any.whl

cjm_transcript_decomp_core/models.py

@@ -0,0 +1,186 @@
+"""Lean data shapes for the transcript-decomposition pipeline: in-core mirrors of the forced-alignment / VAD / text DTOs (no FastHTML deps), run configuration, the committed graph-segment carrier, and the decomposition run manifest (proto-bundle)."""
+
+import json
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+
+@dataclass
+class FAWord:
+    """One word-level forced-alignment result (segment-local times).
+
+    Lean in-core mirror of the forced-alignment capability's `ForcedAlignItem`
+    wire shape, so the core needs no interface-library dependency for a
+    three-field DTO (pass-2 evidence: the typed FA result belongs to the
+    forced-alignment adapter interface).
+    """
+    text: str          # The aligned word (punctuation typically stripped by the model)
+    start_time: float  # Word start in seconds (relative to the segment audio)
+    end_time: float    # Word end in seconds (relative to the segment audio)
+
+    @classmethod
+    def from_wire(
+        cls,
+        d: Dict[str, Any],  # Capability wire dict
+    ) -> "FAWord":  # Parsed word (extra keys ignored)
+        """Build from a capability wire dict, tolerating extra keys."""
+        return cls(
+            text=str(d.get("text", "")),
+            start_time=float(d.get("start_time", 0.0)),
+            end_time=float(d.get("end_time", 0.0)),
+        )
+
+
+@dataclass
+class VADChunk:
+    """A voice-activity time range within one pipeline segment (segment-local)."""
+    index: int         # Chunk index within the pipeline segment
+    start_time: float  # Start in seconds (relative to the segment audio)
+    end_time: float    # End in seconds (relative to the segment audio)
+
+    @property
+    def duration(self) -> float:  # Chunk duration in seconds
+        """Chunk duration."""
+        return self.end_time - self.start_time
+
+
+@dataclass
+class TextSegment:
+    """A text segment produced by alignment, before graph commit.
+
+    Lean in-core mirror of the page-centric `TextSegment` (which imports FastHTML
+    card-stack types); the core carries only the alignment-relevant fields
+    (E11 precedent — keep core logic free of UI-adjacent deps).
+    """
+    index: int                                # Position within its pipeline segment
+    text: str                                 # Segment text content
+    source_id: Optional[str] = None           # Upstream transcription row id (job_id)
+    source_provider_id: Optional[str] = None  # Producing capability name
+    start_char: Optional[int] = None          # Start char offset into the pipeline-segment text
+    end_char: Optional[int] = None            # End char offset into the pipeline-segment text
+
+
+@dataclass
+class SegmentVariant:
+    """One transcriber's text + char range for one fine segment (stage 5).
+
+    Becomes a `GraphNodeRef(Transcript) + CharSlice` provenance ref on the
+    committed Segment node — text is stored ONCE per transcriber at the coarse
+    Transcript node; fine-grained variants are SLICES, never duplicated text
+    (Thread-1 slices-until-promoted)."""
+    transcriber: str            # Transcriber capability name
+    text: str                   # This transcriber's text for the chunk
+    start_char: Optional[int]   # Char offset into that transcriber's pipeline-segment text
+    end_char: Optional[int]     # End char offset
+
+    def to_dict(self) -> Dict[str, Any]:  # Plain-dict form
+        """Serialize to a plain dict."""
+        return asdict(self)
+
+
+@dataclass
+class DecompSegment:
+    """One fine spine segment (stage 5: shared audio-side skeleton + per-transcriber variants).
+
+    Identity is AUDIO-SIDE (owning pipeline segment + chunk range) — shared
+    across transcribers by construction; `text` is the AUTHORITATIVE
+    (accuracy-transcriber) alignment, with every transcriber's chunk text
+    riding `variants` (the authoritative one included)."""
+    index: int             # Source-wide 0-based fine-spine position
+    text: str              # Authoritative text (the --text-from transcriber's alignment; "" = no aligned words)
+    start_time: float      # Start in source-audio seconds (navigation)
+    end_time: float        # End in source-audio seconds
+    chunk_start: float     # VAD chunk start (chunk-local seconds within the pipeline-segment WAV)
+    chunk_end: float       # VAD chunk end (chunk-local seconds)
+    vad_chunk_index: int   # Chunk index within its pipeline segment
+    pseg_index: int        # Owning pipeline-segment (AudioSegment) index within the source
+    variants: List[SegmentVariant] = field(default_factory=list)  # Per-transcriber chunk texts + char ranges
+
+    def to_dict(self) -> Dict[str, Any]:  # Plain-dict form
+        """Serialize to a plain dict."""
+        return asdict(self)
+
+
+@dataclass
+class DecompConfig:
+    """Configuration for one transcript-decomposition run."""
+    vad_capability: str = "cjm-capability-silero-vad"                    # VAD capability id
+    fa_capability: str = "cjm-capability-qwen3-forced-aligner"  # Forced-alignment capability id
+    graph_capability: str = "cjm-capability-graph-sqlite"                     # Graph-storage capability id
+    text_from: Optional[str] = None  # Authoritative transcriber for layer-0 text (None: sole transcriber; REQUIRED for multi-transcriber manifests)
+    language: str = "English"  # Forced-alignment language
+    media_type: str = "audio"  # Source media type
+    force: bool = False        # Bypass capability-side caches (VAD + FA)
+    assume_yes: bool = False   # Auto-accept HITL seams (headless mode)
+
+    def to_dict(self) -> Dict[str, Any]:  # Plain-dict snapshot for the manifest
+        """Serialize to a plain dict."""
+        return asdict(self)
+
+
+@dataclass
+class DecompSourceRecord:
+    """Record of one Source whose fine spine this run committed (stage 5:
+    `Document` dissolved into `Source` — decomp EXTENDS the transcription-
+    emitted root rather than creating a document)."""
+    source_node_id: str  # Graph Source node id (deterministic; recomputable from the content hash)
+    source_path: str     # Originating source audio path (from the upstream manifest)
+    title: str           # Source display title
+    segment_count: int   # Number of fine Segment nodes committed
+    segment_ids: List[str] = field(default_factory=list)  # Graph Segment node ids, in order
+
+    def to_dict(self) -> Dict[str, Any]:  # Plain-dict form
+        """Serialize to a plain dict."""
+        return asdict(self)
+
+
+@dataclass
+class DecompManifest:
+    """Durable record of one decomposition run (proto-bundle; see CR-20).
+
+    Schema 0.2.0 (stage 5): `documents` became `sources` (Document dissolved
+    into Source); entries carry the deterministic Source node id."""
+    run_id: str             # Unique run identifier
+    created_at: float       # Unix timestamp at run start
+    config: Dict[str, Any]  # DecompConfig snapshot
+    source_manifest: str    # Path to the consumed transcription run manifest
+    source_format: str = ""  # Upstream manifest format tag (interchange contract)
+    source_version: str = ""  # Upstream manifest schema version
+    capabilities: Dict[str, Dict[str, Any]] = field(default_factory=dict)  # instance_id -> identity/db_path/config_hash
+    sources: List[DecompSourceRecord] = field(default_factory=list)   # Extended sources, input order
+
+    FORMAT: str = field(default="cjm-transcript-decomp-core/run-manifest", repr=False)  # Format tag
+    VERSION: str = field(default="0.2.1", repr=False)                                   # Schema version
+
+    def to_dict(self) -> Dict[str, Any]:  # Plain-dict form for JSON serialization
+        """Serialize to a plain dict with nested sources."""
+        return {
+            "format": self.FORMAT,
+            "version": self.VERSION,
+            "run_id": self.run_id,
+            "created_at": self.created_at,
+            "config": self.config,
+            "source_manifest": self.source_manifest,
+            "source_format": self.source_format,
+            "source_version": self.source_version,
+            "capabilities": self.capabilities,
+            "sources": [s.to_dict() for s in self.sources],
+        }
+
+    def save(
+        self,
+        path: Union[str, Path],  # Destination JSON file (parent dirs created)
+    ) -> Path:  # The written path
+        """Write the manifest as pretty-printed JSON."""
+        out = Path(path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(json.dumps(self.to_dict(), indent=2))
+        return out
+
+
+def new_run_id() -> str:  # e.g. "decomp_20260607_153000_1a2b3c4d"
+    """Generate a unique, sortable decomposition run id."""
+    return f"decomp_{time.strftime('%Y%m%d_%H%M%S')}_{uuid.uuid4().hex[:8]}"

cjm_transcript_decomp_core/pipeline.py

@@ -0,0 +1,475 @@
+"""The headless decomposition pipeline (stage 5: decomp is an EXTENDER). Load a transcription run manifest, verify the transcription-emitted graph root exists (the graph begins at transcription), then per source per pipeline-segment run VAD + per-transcriber forced alignment, build one aligned segment per VAD chunk with per-transcriber text variants, and attach the fine spine under the existing AudioSegment nodes via the layer's idempotent extend_graph — with HITL approval seams between alignment, commit, and the next source."""
+
+import json
+import logging
+import time
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from cjm_capability_primitives.forced_alignment import ForcedAlignResult
+from cjm_capability_primitives.vad import VADResult
+from cjm_context_graph_layer.declare import Derivation, derivation_to_graph
+from cjm_context_graph_layer.ops import extend_graph, graph_task
+from cjm_substrate.core.empirical_store import compute_config_hash
+from cjm_substrate.core.journal_store import JournalEvent, SubstrateEventType
+from cjm_substrate.core.manager import CapabilityManager
+from cjm_substrate.core.ports import Composition, CompositionNode, NodeState
+from cjm_substrate.core.queue import JobQueue, JobStatus
+from cjm_transcript_decomp_core.alignment import (assign_words_to_chunks,
+                                                  build_segments_from_alignment,
+                                                  map_fa_words_to_text, tier1_alignment_checks)
+from cjm_transcript_decomp_core.graph import (build_extension_payload, resolve_root_ids,
+                                              verify_source)
+from cjm_transcript_decomp_core.models import (DecompConfig, DecompManifest, DecompSegment,
+                                               DecompSourceRecord, FAWord, new_run_id,
+                                               SegmentVariant, VADChunk)
+
+# Typed wire-kind registration (stage 2): importing the DTO classes is what
+# lets the proxy's wire_decode hand this host process TYPED results. Both result
+# nouns live in cjm-capability-primitives (Option C / PILLAR 1c — the tool/host
+# depend on the data noun, never the adapter machinery). The tuple keeps these
+# SIDE-EFFECT imports referenced so the canonical emit cannot prune them.
+
+_REGISTERED_WIRE_KINDS = (VADResult, ForcedAlignResult)
+
+logger = logging.getLogger(__name__)
+
+
+async def submit_and_wait(
+    queue: JobQueue,   # Started job queue
+    instance_id: str,  # Capability instance to invoke
+    *,
+    timeout: Optional[float] = None,  # Seconds to wait; None = no limit
+    **kwargs,          # Forwarded to the capability's execute()
+) -> Any:  # The completed job's result payload
+    """Submit one capability job, wait for it, and return its result (raise on failure)."""
+    job_id = await queue.submit(instance_id, **kwargs)
+    job = await queue.wait_for_job(job_id, timeout=timeout)
+    if job.status != JobStatus.completed:
+        raise RuntimeError(f"{instance_id} job {job_id} {job.status}: {job.error}")
+    return job.result
+
+
+def load_source_manifest(
+    path: str,  # Path to a transcription-core run manifest JSON
+) -> Dict[str, Any]:  # Parsed manifest dict
+    """Load + lightly validate a transcription-core run manifest.
+
+    Consumed as untyped JSON — the format/version tags are the only interchange
+    contract (no shared schema type across cores; manifest-as-interchange, CR-20).
+    """
+    data = json.loads(Path(path).read_text())
+    fmt = data.get("format", "")
+    if "transcription-core" not in fmt:
+        logger.warning(f"unexpected source manifest format: {fmt!r} (continuing)")
+    return data
+
+
+def vad_chunks_from_result(
+    result: VADResult,  # Typed VAD result (wire-decoded at the proxy)
+) -> List[VADChunk]:  # Segment-local VAD chunks, sorted, re-indexed
+    """Normalize a typed VAD result into segment-local VAD chunks.
+
+    Pure normalizer (stage 3): the capability invocation moved into the
+    per-source composition (`build_alignment_composition`); this folds one
+    node's typed result. Per-segment VAD (not whole-source) is the validated
+    decomp path — originally a browser Web-Audio constraint, kept on the
+    merits (D11).
+    """
+    chunks = [VADChunk(index=0, start_time=float(r.start), end_time=float(r.end))
+              for r in result.ranges]
+    chunks.sort(key=lambda c: c.start_time)
+    for i, c in enumerate(chunks):
+        c.index = i
+    return chunks
+
+
+def fa_words_from_result(
+    result: "ForcedAlignResult",  # Typed FA result (wire-decoded at the proxy)
+) -> List[FAWord]:  # Word-level alignment results
+    """Normalize a typed forced-alignment result into FA words (pure; stage 3)."""
+    return [FAWord(text=str(it.text), start_time=float(it.start_time),
+                   end_time=float(it.end_time))
+            for it in result.items]
+
+
+def build_alignment_composition(
+    seg_list: List[Dict[str, Any]],  # Pipeline-segment entries from the transcription manifest (0.2.0)
+    vad_id: str,               # VAD capability instance id
+    fa_id: str,                # Forced-alignment capability instance id
+    transcribers: List[str],   # Transcriber names to align (manifest `transcripts` keys, stable order)
+    force: bool = False,       # Per-call cache-bypass control flag
+) -> Tuple[Composition, List[Dict[str, Any]]]:  # (composition, per-pseg meta rows)
+    """Build the whole-source M×(VAD ∥ T×FA) composition (D8 fan-in, stage-5 variants).
+
+    Each pipeline segment contributes one VAD node + one FA node PER TRANSCRIBER
+    with non-empty text — VAD is audio-only (run once; the shared skeleton), FA
+    maps each transcriber's text onto it. All nodes are independent; the host's
+    alignment fold fans them in. Pipeline segments where EVERY transcriber's
+    text is empty are recorded as skipped meta rows and contribute no nodes.
+
+    Stage 8 (Option C): every node rides the TASK CHANNEL now — VAD on
+    vad/detect_speech, FA on forced_alignment/align — and per-call `force` rides
+    `control` (the adapters own caching). The native-routed path is gone.
+    """
+    nodes: List[CompositionNode] = []
+    metas: List[Dict[str, Any]] = []
+    for i, pseg in enumerate(seg_list):
+        # Manifest entries are JSON dicts (manifest-as-interchange, CR-20).
+        model_input = str(pseg.get("model_input_path", ""))
+        seg_start = float(pseg.get("start", 0.0))
+        transcripts = pseg.get("transcripts") or {}
+        texts = {t: str((transcripts.get(t) or {}).get("text") or "")
+                 for t in transcribers if t in transcripts}
+        nonempty = {t: x for t, x in texts.items() if x.strip()}
+        if not nonempty:
+            metas.append({"skipped": True, "seg_start": seg_start, "pseg_index": i})
+            continue
+        vad_n = f"vad_{i:04d}"
+        # VAD via the task channel (vad/detect_speech); the adapter owns the cache
+        # + force. model_input is already model-ready (16k mono, converted upstream
+        # by transcription-core), so no convert here.
+        nodes.append(CompositionNode(vad_n, vad_id,
+                                     {"audio": model_input},
+                                     task_name="vad", method="detect_speech",
+                                     control={"force": force}))
+        fa_nodes: Dict[str, str] = {}
+        for ti, t in enumerate(transcribers):
+            if t not in nonempty:
+                continue
+            fa_n = f"fa_t{ti}_{i:04d}"
+            # FA via the task channel (forced_alignment/align); the adapter owns
+            # the cache + force. text is the per-transcriber transcript aligned
+            # against the (model-ready) audio.
+            nodes.append(CompositionNode(fa_n, fa_id,
+                                         {"audio": model_input, "text": nonempty[t]},
+                                         task_name="forced_alignment", method="align",
+                                         control={"force": force}))
+            fa_nodes[t] = fa_n
+        metas.append({"skipped": False, "seg_start": seg_start, "pseg_index": i,
+                      "vad_node": vad_n, "fa_nodes": fa_nodes, "texts": nonempty})
+    return Composition(nodes=nodes), metas
+
+
+async def decompose_source(
+    queue: JobQueue,
+    cfg: DecompConfig,         # Run configuration
+    source: Dict[str, Any],    # One source entry from the transcription manifest
+    source_index: int,         # Position of this source within the run
+    transcribers: List[str],   # Transcriber names (manifest order)
+    text_from: str,            # Authoritative transcriber (layer-0 text)
+) -> Tuple[str, List[DecompSegment]]:  # (source_path, ordered aligned segments)
+    """Decompose one source into aligned fine segments with per-transcriber variants.
+
+    The VAD-chunk skeleton is computed ONCE per pipeline segment (audio-only);
+    each transcriber's text is forced-aligned onto it independently, then the
+    pure fold merges per chunk: the `text_from` transcriber's alignment becomes
+    the authoritative text, every transcriber's chunk text + char range rides
+    `variants` (slice refs at commit). C4's "same skeleton, different text"
+    duplication is gone — agreement is stored once by construction.
+    """
+    source_path = str(source.get("source_path", ""))
+    seg_list = list(source.get("segments") or [])
+
+    comp, metas = build_alignment_composition(
+        seg_list, cfg.vad_capability, cfg.fa_capability, transcribers, force=cfg.force)
+    results: Dict[str, Any] = {}
+    if comp.nodes:
+        comp_id = await queue.submit_composition(comp)
+        crun = await queue.wait_for_composition(comp_id)
+        if crun.status != NodeState.completed:
+            failed = {nid: str(nr.error) for nid, nr in crun.node_runs.items()
+                      if nr.state == NodeState.failed}
+            raise RuntimeError(
+                f"alignment composition {crun.status.value} for {source_path}: {failed}")
+        results = crun.results_by_node()
+
+    aligned: List[DecompSegment] = []
+    global_index = 0
+    for m in metas:
+        seg_start = m["seg_start"]
+        if m["skipped"]:
+            logger.warning(f"[src {source_index}] no transcriber text at {seg_start:.1f}s; "
+                           f"skipping pipeline segment")
+            continue
+        vad_chunks = vad_chunks_from_result(results[m["vad_node"]])
+
+        # Per-transcriber fold over the SHARED skeleton.
+        per_t_segments: Dict[str, List[Any]] = {}
+        for t, fa_n in m["fa_nodes"].items():
+            text = m["texts"][t]
+            fa_words = fa_words_from_result(results[fa_n])
+            spans = map_fa_words_to_text(text, fa_words)
+            assignments = assign_words_to_chunks(fa_words, vad_chunks)
+            per_t_segments[t] = build_segments_from_alignment(
+                text=text, spans=spans, assignments=assignments,
+                num_chunks=len(vad_chunks), source_provider_id=t,
+            )
+        auth = per_t_segments.get(text_from)
+        if auth is not None:
+            for w in tier1_alignment_checks(auth, vad_chunks):
+                logger.warning(f"[src {source_index}] pseg @ {seg_start:.1f}s [{text_from}]: {w}")
+        else:
+            logger.warning(f"[src {source_index}] pseg @ {seg_start:.1f}s: authoritative "
+                           f"transcriber {text_from!r} has no text here — layer-0 text empty")
+
+        for k, vc in enumerate(vad_chunks):
+            variants = []
+            for t in transcribers:
+                tsegs = per_t_segments.get(t)
+                if tsegs is None:
+                    continue
+                ts = tsegs[k]
+                if ts.text:
+                    variants.append(SegmentVariant(transcriber=t, text=ts.text,
+                                                   start_char=ts.start_char, end_char=ts.end_char))
+            aligned.append(DecompSegment(
+                index=global_index,
+                text=(auth[k].text if auth is not None else ""),
+                start_time=seg_start + vc.start_time, end_time=seg_start + vc.end_time,
+                chunk_start=vc.start_time, chunk_end=vc.end_time,
+                vad_chunk_index=vc.index, pseg_index=m["pseg_index"],
+                variants=variants,
+            ))
+            global_index += 1
+        logger.info(f"[src {source_index}] pseg @ {seg_start:.1f}s -> "
+                    f"{len(vad_chunks)} chunks, {len(m['fa_nodes'])} transcriber alignment(s)")
+    return source_path, aligned
+
+
+def confirm_seam(
+    seam: str,                 # Seam label, e.g. "alignment-review"
+    summary_lines: List[str],  # What the operator is being asked to accept
+    warnings: List[str],       # Tier-1 warnings (logged prominently)
+    assume_yes: bool = False,  # Headless mode: accept without prompting
+) -> bool:  # True = proceed, False = operator aborted
+    """HITL approval seam in its cheapest viable form (log + optional CLI prompt).
+
+    Per-seam HITL-assist annotation (5 fields):
+      1. signal: per-document summary + Tier-1 warnings
+      2. deterministic pre-filter: tier1_alignment_checks (no AI)
+      3. modality-bridge candidate: spectrogram / word-overlay review (future Tier 2)
+      4. authoritative verifier: re-align or re-transcribe-and-compare (future Tier 3)
+      5. flywheel capture: accept/abort decisions logged; durable capture is a
+         pass-2 seam-contract concern, not solved here
+
+    NOTE: input() blocks the event loop — acceptable because seams sit between
+    stages with no jobs in flight; the pass-2 seam contract needs an async shape.
+    """
+    for line in summary_lines:
+        logger.info(f"[{seam}] {line}")
+    for w in warnings:
+        logger.warning(f"[{seam}] {w}")
+    if assume_yes:
+        logger.info(f"[{seam}] auto-accepted (assume_yes)")
+        return True
+    reply = input(f"[{seam}] proceed? [Y/n] ").strip().lower()
+    accepted = reply in ("", "y", "yes")
+    logger.info(f"[{seam}] {'accepted' if accepted else 'ABORTED'} by operator")
+    return accepted
+
+
+def collect_capability_info(
+    manager: CapabilityManager,   # Manager holding the loaded capabilities
+    instance_ids: List[str],  # Instance ids to record
+) -> Dict[str, Dict[str, Any]]:  # instance_id -> {name, version, db_path, config_hash}
+    """Record capability identity + data-DB pointers for the run manifest (provenance).
+
+    Stage 5: also records each capability's EFFECTIVE config hash (the same
+    `compute_config_hash` the empirical store keys on) — the VAD config hash is
+    a Segment identity input. `db_path` prefers the effective config over the
+    manifest default (a --graph-db-path override must be what downstream cores
+    resolve; the D19 lesson). Stage 6 (0.2.1): the EFFECTIVE config dict is
+    recorded READABLY beside its hash (the I8 lesson).
+    """
+    info: Dict[str, Dict[str, Any]] = {}
+    for iid in instance_ids:
+        meta = (getattr(manager, "capabilities", {}) or {}).get(iid)
+        if meta is None:
+            continue
+        manifest = getattr(meta, "manifest", {}) or {}
+        current_config: Dict[str, Any] = {}
+        try:
+            proxy = manager.get_capability(iid)
+            if proxy is not None:
+                current_config = proxy.get_current_config() or {}
+        except Exception as e:  # Best-effort: identity recording must not fail the run
+            logger.warning(f"collect_capability_info: get_current_config({iid}) failed: {e}")
+        info[iid] = {
+            "name": meta.name,
+            "version": getattr(meta, "version", None),
+            "db_path": current_config.get("db_path") or manifest.get("db_path"),
+            "config_hash": compute_config_hash(current_config),
+            "config": current_config,
+        }
+    return info
+
+
+def _journal_run_event(
+    manager: CapabilityManager,  # Manager owning the journal store
+    event_type: str,         # SubstrateEventType value (run_started / run_finished / verify_outcome)
+    run_id: str,             # This run's manifest id
+    actor: Optional[str],    # Who/what initiated the run
+    payload: Dict[str, Any], # Run-level structured detail
+) -> None:
+    """Append a host-tier run event to the journal (CR-14 follow-up).
+
+    The cores are the trusted host writer class: RUN_STARTED/RUN_FINISHED
+    bracket the run (run manifest <-> journal linkage by run_id) and
+    VERIFY_OUTCOME makes skeptical-lens results durable rows (I14). No-op
+    when the manager has no journal store; append failures stay LOUD.
+    """
+    journal = getattr(manager, "journal_store", None)
+    if journal is None:
+        return
+    journal.append(JournalEvent(
+        event_type=event_type, run_id=run_id, actor=actor, payload=payload))
+
+
+async def run_decomp(
+    manager: CapabilityManager,        # Manager with VAD + FA + graph capabilities loaded
+    queue: JobQueue,               # Started job queue
+    cfg: DecompConfig,             # Run configuration
+    source_manifest_path: str,     # Transcription run manifest to decompose
+    run_id: Optional[str] = None,  # Override run id (default: generated)
+    actor: Optional[str] = None,   # Who/what initiated (journal attribution; CLI default cli:<user>)
+) -> DecompManifest:  # Manifest of the sources extended
+    """Extend every source in a transcription run manifest with its fine spine.
+
+    Stage 5 (decomp-as-extender): the graph ROOT must already exist — decomp
+    recomputes the deterministic root ids from the manifest, verifies the
+    Source node is present (loud error pointing at transcription emission
+    otherwise), aligns per transcriber, and attaches the fine spine under the
+    run's AudioRendition (PART_OF rendition) via the layer's idempotent
+    `extend_graph` (re-runs verify-collide). The fold is declared as a
+    `Derivation` event when segments were actually created.
+    """
+    run_id = run_id or new_run_id()
+    # CR-14 follow-up: queue-scoped run context — every job submitted in this
+    # run carries run_id/actor into its journal rows + worker diagnostics
+    # (run-manifest <-> journal linkage); the run itself is bracketed by
+    # RUN_STARTED/RUN_FINISHED host-tier rows.
+    queue.set_run_context(run_id=run_id, actor=actor)
+    _journal_run_event(manager, SubstrateEventType.RUN_STARTED.value, run_id, actor, {
+        "core": "cjm-transcript-decomp-core",
+        "source_manifest": str(source_manifest_path),
+        "graph_capability": cfg.graph_capability,
+    })
+    src = load_source_manifest(source_manifest_path)
+    src_cfg = src.get("config", {}) or {}
+    transcribers = list(src_cfg.get("transcriber_capabilities") or [])
+    if not transcribers and src_cfg.get("transcriber_capability"):
+        # pre-0.2.0 manifest: single transcriber under the old key
+        transcribers = [str(src_cfg["transcriber_capability"])]
+    if not transcribers:
+        raise RuntimeError("source manifest lists no transcribers")
+    text_from = cfg.text_from or (transcribers[0] if len(transcribers) == 1 else None)
+    if text_from is None:
+        raise RuntimeError(
+            f"multi-transcriber manifest ({transcribers}) requires --text-from "
+            "(the authoritative transcriber for layer-0 text)")
+    if text_from not in transcribers:
+        raise RuntimeError(f"--text-from {text_from!r} not among the manifest's transcribers {transcribers}")
+    src_capabilities = src.get("capabilities", {}) or {}
+
+    manifest = DecompManifest(
+        run_id=run_id, created_at=time.time(), config=cfg.to_dict(),
+        source_manifest=str(source_manifest_path),
+        source_format=src.get("format", ""), source_version=src.get("version", ""),
+        capabilities=collect_capability_info(manager, [cfg.vad_capability, cfg.fa_capability, cfg.graph_capability]),
+    )
+    vad_config_hash = str((manifest.capabilities.get(cfg.vad_capability) or {}).get("config_hash") or "")
+
+    sources = src.get("sources", []) or []
+    status = "completed"
+    try:
+        for i, source in enumerate(sources):
+            # Extender pre-check: the transcription-emitted root must exist.
+            roots = resolve_root_ids(source, src_capabilities)
+            root = await graph_task(queue, cfg.graph_capability, "get_node", node_id=roots["source"])
+            if root is None:
+                raise RuntimeError(
+                    f"Source root {roots['source']} not found in the graph for "
+                    f"{source.get('source_path')!r} — the graph begins at transcription: "
+                    "re-run cjm-transcription-core with --graph-capability against this DB first")
+
+            source_path, aligned = await decompose_source(
+                queue, cfg, source, i, transcribers, text_from)
+            title = Path(source_path).stem or f"source-{i}"
+
+            empty = sum(1 for a in aligned if not a.text.strip())
+            warns = [f"{empty}/{len(aligned)} aligned segment(s) have empty layer-0 text"] if empty else []
+            if not confirm_seam("alignment-review",
+                                [f"{title}: {len(aligned)} aligned segment(s), text_from={text_from}"],
+                                warns, assume_yes=cfg.assume_yes):
+                logger.warning(f"run {run_id}: aborted at source {i} ({source_path})")
+                status = "aborted"
+                break
+
+            nodes, edges, ids = build_extension_payload(
+                source, src_capabilities, vad_config_hash, text_from, aligned)
+
+            if not confirm_seam("commit-review",
+                                [f"{title}: extending Source {ids['source'][:8]}… with "
+                                 f"{len(ids['segments'])} segment node(s) + {len(edges)} edge(s) "
+                                 f"via {cfg.graph_capability}"],
+                                [], assume_yes=cfg.assume_yes):
+                logger.warning(f"run {run_id}: commit declined at source {i} ({source_path})")
+                status = "aborted"
+                break
+
+            res = await extend_graph(queue, cfg.graph_capability, nodes, edges)
+            logger.info(f"[src {i}] extension: +{res.nodes_added} node(s) "
+                        f"({res.nodes_verified} verified present), +{res.edges_added} edge(s) "
+                        f"({res.edges_existing} existing)")
+            if res.nodes_added:
+                d = Derivation(
+                    actor="host:cjm-transcript-decomp-core", method="alignment-fold/v1",
+                    input_ids=ids["transcripts_used"], output_ids=[ids["source"]],
+                    properties={"run_id": run_id, "segments": len(ids["segments"]),
+                                "text_from": text_from},
+                )
+                dn, de = derivation_to_graph(d)
+                await extend_graph(queue, cfg.graph_capability, [dn], de)
+
+            # Fine spine hangs under the run's renditions — verify scopes there.
+            vr = await verify_source(queue, cfg.graph_capability, ids["source"], ids["renditions"])
+            if vr is None:
+                logger.error(f"[src {i}] verify: Source {ids['source']} NOT FOUND in graph")
+            else:
+                logger.info(f"[src {i}] verify: {'OK' if vr.ok else 'FAILED'} "
+                            f"(asegs={vr.audio_segment_count}, renditions={vr.rendition_count}, "
+                            f"segments={vr.segment_count}, "
+                            f"src_starts={vr.source_starts_with}, aseg_next={vr.aseg_next_complete}, "
+                            f"seg_next={vr.seg_next_complete}, part_of={vr.part_of_complete}, "
+                            f"rend_starts={vr.rendition_starts_with_complete}, "
+                            f"timing={vr.all_have_timing}, sources={vr.all_have_sources})")
+
+            # I14: verify outcomes are journal ROWS (absence of a log line is not
+            # green); the full check vector rides the payload.
+            _journal_run_event(manager, SubstrateEventType.VERIFY_OUTCOME.value, run_id, actor, {
+                "core": "cjm-transcript-decomp-core",
+                "source_node_id": ids["source"],
+                "found": vr is not None,
+                "ok": (vr.ok if vr is not None else False),
+                "checks": (asdict(vr) if vr is not None else None),
+            })
+
+            manifest.sources.append(DecompSourceRecord(
+                source_node_id=ids["source"], source_path=source_path, title=title,
+                segment_count=len(ids["segments"]), segment_ids=ids["segments"]))
+    except BaseException as e:
+        # The journal exists for exactly this row: a run that DIED records
+        # how far it got (failures stop being the unattributed case).
+        _journal_run_event(manager, SubstrateEventType.RUN_FINISHED.value, run_id, actor, {
+            "core": "cjm-transcript-decomp-core", "status": "failed", "error": repr(e),
+            "sources_completed": len(manifest.sources), "sources_total": len(sources),
+        })
+        raise
+    _journal_run_event(manager, SubstrateEventType.RUN_FINISHED.value, run_id, actor, {
+        "core": "cjm-transcript-decomp-core", "status": status,
+        "sources_completed": len(manifest.sources), "sources_total": len(sources),
+        "segments": sum(s.segment_count for s in manifest.sources),
+    })
+    return manifest