cjm-transcript-graph-schema 0.0.7__tar.gz → 0.0.11__tar.gz

{cjm_transcript_graph_schema-0.0.7 → cjm_transcript_graph_schema-0.0.11}/MANIFEST.in

@@ -1,5 +1,4 @@
 include pyproject.toml
 include LICENSE
-include CONTRIBUTING.md
 include README.md
 recursive-exclude * __pycache__

cjm_transcript_graph_schema-0.0.11/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: cjm-transcript-graph-schema
+Version: 0.0.11
+Summary: Audio-transcript layer schema for context graphs: Source, AudioSegment, Transcript, and Segment nodes with deterministic identity tuples and graph-node mapping, shared by the transcription, decomposition, and correction workflow cores.
+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-transcript-graph-schema
+Keywords: python
+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-layer>=0.0.7
+Requires-Dist: cjm-context-graph-primitives>=0.0.12
+Dynamic: license-file
+
+# cjm-transcript-graph-schema
+
+<!-- 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) -->
+
+Audio-transcript layer schema for context graphs: Source, AudioSegment, Transcript, and Segment nodes with deterministic identity tuples and graph-node mapping, shared by the transcription, decomposition, and correction workflow cores.
+
+## Modules
+
+- **`cjm_transcript_graph_schema.schema`** — The audio-transcript layer schema (where-graph-begins locked layer schema): Source -> AudioSegment(coarse boundary) -> AudioRendition(model-input: raw | vocals | ...) -> Transcript(per-transcriber variants) emitted by transcription, extended with the fine Segment spine (per-rendition) by decomposition. Deterministic identity tuples per the stage-5 ratified rule; the AudioRendition node lets raw + preprocessed model-inputs of one boundary coexist in one graph. Document from the pre-CR-18 era dissolves into Source.
+
+## API
+
+### `cjm_transcript_graph_schema.schema`
+
+- `AudioRenditionNode` _class_ — A model-input rendition OF an AudioSegment — the materialized 16k-mono WAV
+- `AudioSegmentNode` _class_ — Coarse ~5-min spine member: a BOUNDARY range of the Source (an audio fact),
+- `CollectionNode` _class_ — An intrinsic collection (book, podcast series, lecture course) — the
+- `RespinedChunkEntry` _class_ — One chunk respine as the Source records it (0b4d5cfa (4)): the entry the
+- `SegmentNode` _class_ — Fine spine member: one VAD chunk — IMMUTABLE audio range + CORRECTABLE
+- `SourceNode` _class_ — The provenance root: one ingested media file.
+- `TranscriptGraphLabels` _class_ — Node labels of the audio-transcript layer schema.
+- `TranscriptNode` _class_ — One transcriber's text for one AudioRendition (per-transcriber variants at
+- `TranscriptSliceRef` _class_ — One per-transcriber char-range reference for a fine Segment: where this
+- `audio_rendition_node_id` _function_ — AudioRendition identity = (audio segment, preprocessing chain).
+- `audio_segment_node_id` _function_ — AudioSegment identity = (source, boundary range).
+- `collection_edges` _function_ — Membership edges for a collection (ae3464fc: ORDER IS OPTIONAL).
+- `collection_node_id` _function_ — Collection identity = the NORMALIZED TITLE (ratified fork, hub-session
+- `normalize_collection_title` _function_ — Normalize a collection title for identity derivation.
+- `segment_node_id` _function_ — Fine Segment identity = audio-side only (audio rendition, VAD config, chunk
+- `source_node_id` _function_ — Source identity = the ingested file's content hash (Thread-1 ingested-root identity).
+- `transcript_node_id` _function_ — Transcript identity = (audio rendition, transcriber, config) — MIRRORS the
+
+## Dependencies
+
+**Depends on:** `cjm-context-graph-layer`, `cjm-context-graph-primitives`
+**Used by:** `cjm-context-graph-layer`, `cjm-transcript-correction-core`, `cjm-transcript-correction-tui`, `cjm-transcript-decomp-core`, `cjm-transcription-core`

cjm_transcript_graph_schema-0.0.11/README.md

@@ -0,0 +1,36 @@
+# cjm-transcript-graph-schema
+
+<!-- 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) -->
+
+Audio-transcript layer schema for context graphs: Source, AudioSegment, Transcript, and Segment nodes with deterministic identity tuples and graph-node mapping, shared by the transcription, decomposition, and correction workflow cores.
+
+## Modules
+
+- **`cjm_transcript_graph_schema.schema`** — The audio-transcript layer schema (where-graph-begins locked layer schema): Source -> AudioSegment(coarse boundary) -> AudioRendition(model-input: raw | vocals | ...) -> Transcript(per-transcriber variants) emitted by transcription, extended with the fine Segment spine (per-rendition) by decomposition. Deterministic identity tuples per the stage-5 ratified rule; the AudioRendition node lets raw + preprocessed model-inputs of one boundary coexist in one graph. Document from the pre-CR-18 era dissolves into Source.
+
+## API
+
+### `cjm_transcript_graph_schema.schema`
+
+- `AudioRenditionNode` _class_ — A model-input rendition OF an AudioSegment — the materialized 16k-mono WAV
+- `AudioSegmentNode` _class_ — Coarse ~5-min spine member: a BOUNDARY range of the Source (an audio fact),
+- `CollectionNode` _class_ — An intrinsic collection (book, podcast series, lecture course) — the
+- `RespinedChunkEntry` _class_ — One chunk respine as the Source records it (0b4d5cfa (4)): the entry the
+- `SegmentNode` _class_ — Fine spine member: one VAD chunk — IMMUTABLE audio range + CORRECTABLE
+- `SourceNode` _class_ — The provenance root: one ingested media file.
+- `TranscriptGraphLabels` _class_ — Node labels of the audio-transcript layer schema.
+- `TranscriptNode` _class_ — One transcriber's text for one AudioRendition (per-transcriber variants at
+- `TranscriptSliceRef` _class_ — One per-transcriber char-range reference for a fine Segment: where this
+- `audio_rendition_node_id` _function_ — AudioRendition identity = (audio segment, preprocessing chain).
+- `audio_segment_node_id` _function_ — AudioSegment identity = (source, boundary range).
+- `collection_edges` _function_ — Membership edges for a collection (ae3464fc: ORDER IS OPTIONAL).
+- `collection_node_id` _function_ — Collection identity = the NORMALIZED TITLE (ratified fork, hub-session
+- `normalize_collection_title` _function_ — Normalize a collection title for identity derivation.
+- `segment_node_id` _function_ — Fine Segment identity = audio-side only (audio rendition, VAD config, chunk
+- `source_node_id` _function_ — Source identity = the ingested file's content hash (Thread-1 ingested-root identity).
+- `transcript_node_id` _function_ — Transcript identity = (audio rendition, transcriber, config) — MIRRORS the
+
+## Dependencies
+
+**Depends on:** `cjm-context-graph-layer`, `cjm-context-graph-primitives`
+**Used by:** `cjm-context-graph-layer`, `cjm-transcript-correction-core`, `cjm-transcript-correction-tui`, `cjm-transcript-decomp-core`, `cjm-transcription-core`

cjm_transcript_graph_schema-0.0.11/cjm_transcript_graph_schema/__init__.py

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

{cjm_transcript_graph_schema-0.0.7 → cjm_transcript_graph_schema-0.0.11}/cjm_transcript_graph_schema/schema.py

@@ -1,26 +1,17 @@
-"""The audio-transcript layer schema (where-graph-begins locked layer schema): `Source -> AudioSegment(coarse boundary) -> AudioRendition(model-input: raw | vocals | …) -> Transcript(per-transcriber variants)` emitted by transcription, extended with the fine `Segment` spine (per-rendition) by decomposition. Deterministic identity tuples per the stage-5 ratified rule; the `AudioRendition` node lets raw + preprocessed model-inputs of one boundary coexist in one graph. `Document` from the pre-CR-18 era dissolves into `Source`.
+"""The audio-transcript layer schema (where-graph-begins locked layer schema): Source -> AudioSegment(coarse boundary) -> AudioRendition(model-input: raw | vocals | ...) -> Transcript(per-transcriber variants) emitted by transcription, extended with the fine Segment spine (per-rendition) by decomposition, and with the intrinsic Collection layer ABOVE Source (book/series/course; proposed-by-tool / confirmed-by-actor, order optional) captured at transcription hand-off. Deterministic identity tuples per the stage-5 ratified rule; the AudioRendition node lets raw + preprocessed model-inputs of one boundary coexist in one graph. Document from the pre-CR-18 era dissolves into Source."""
 
-Docs: https://cj-mills.github.io/cjm-transcript-graph-schemaschema.html.md"""
-
-# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/schema.ipynb.
-
-# %% auto #0
-__all__ = ['TranscriptGraphLabels', 'source_node_id', 'audio_segment_node_id', 'audio_rendition_node_id', 'transcript_node_id',
-           'segment_node_id', 'SourceNode', 'AudioSegmentNode', 'AudioRenditionNode', 'TranscriptNode',
-           'TranscriptSliceRef', 'SegmentNode']
-
-# %% ../nbs/schema.ipynb #76d0dd1c
-from pathlib import Path
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import Any, Dict, List, Optional
 
+from cjm_context_graph_layer.grammar import (attribution, make_edge, OverlayRelations, spine_edges,
+                                             SpineRelations)
 from cjm_context_graph_layer.identity import derive_node_id
-from cjm_context_graph_layer.grammar import OverlayRelations, attribution, make_edge
 from cjm_context_graph_primitives.locators import FileRef, GraphNodeRef
-from cjm_context_graph_primitives.slices import TimeSlice, CharSlice, FullContent
 from cjm_context_graph_primitives.provenance import SourceRef
+from cjm_context_graph_primitives.slices import CharSlice, FullContent, TimeSlice
+
 
-# %% ../nbs/schema.ipynb #ff94773a
 class TranscriptGraphLabels:
     """Node labels of the audio-transcript layer schema."""
     SOURCE = "Source"                  # Provenance root: one ingested media file
@@ -28,20 +19,23 @@ class TranscriptGraphLabels:
     AUDIO_RENDITION = "AudioRendition" # A model-input rendition OF an AudioSegment (raw convert | vocals | future enhancement); OWNS the model-input WAV
     TRANSCRIPT = "Transcript"          # Per-transcriber text variant of one AudioRendition
     SEGMENT = "Segment"                # Fine spine member: one VAD chunk (immutable audio + correctable text), per-rendition
+    COLLECTION = "Collection"          # Intrinsic collection (book / series / course): the fractal spine layer ABOVE Source
+    REFERENCE = "Reference"            # Human-added resource link attached to a Source (publisher page / author post / related notes / cited work): Source -HAS_REFERENCE-> Reference (ruling a7ca900d (3), item ae103970)
 
     @classmethod
     def all(cls) -> list:  # All schema labels
         """All schema labels."""
-        return [cls.SOURCE, cls.AUDIO_SEGMENT, cls.AUDIO_RENDITION, cls.TRANSCRIPT, cls.SEGMENT]
+        return [cls.SOURCE, cls.AUDIO_SEGMENT, cls.AUDIO_RENDITION, cls.TRANSCRIPT, cls.SEGMENT, cls.COLLECTION,
+                cls.REFERENCE]
+
 
-# %% ../nbs/schema.ipynb #a5ea12db
 def source_node_id(
     content_hash: str,  # Content hash of the source media file ("algo:hexdigest")
 ) -> str:  # Deterministic Source node id
     """Source identity = the ingested file's content hash (Thread-1 ingested-root identity)."""
     return derive_node_id("source", content_hash)
 
-# %% ../nbs/schema.ipynb #794a019f
+
 def audio_segment_node_id(
     source_id: str,  # Owning Source node id
     start: float,    # Boundary start (source-coordinate seconds)
@@ -55,7 +49,7 @@ def audio_segment_node_id(
     the id; the model-input WAV lives on the `AudioRendition` child, not here."""
     return derive_node_id("audio-segment", source_id, start, end)
 
-# %% ../nbs/schema.ipynb #8e147ac9
+
 def audio_rendition_node_id(
     audio_segment_id: str,  # Owning AudioSegment node id
     chain: List[str],       # Ordered preprocessing-chain descriptors; [] = the raw convert-only rendition
@@ -73,7 +67,7 @@ def audio_rendition_node_id(
     search)."""
     return derive_node_id("audio-rendition", audio_segment_id, *chain)
 
-# %% ../nbs/schema.ipynb #6fe30fc8
+
 def transcript_node_id(
     rendition_id: str,  # Owning AudioRendition node id
     transcriber: str,   # Transcriber capability name (e.g. "cjm-transcription-plugin-whisper")
@@ -85,21 +79,65 @@ def transcript_node_id(
     RENDITION, so a raw vs vocals transcript of the same boundary are distinct."""
     return derive_node_id("transcript", rendition_id, transcriber, config_hash)
 
-# %% ../nbs/schema.ipynb #f0e4f510
+
+EXTERNAL_TRANSCRIBER_MARKER = "/manual"  # Suffix naming an operator-landed (pasted) transcript producer
+
+
+def external_transcriber_name(
+    model_id: str,  # The external model that produced the text (e.g. "gemini-2.5-pro")
+) -> str:  # The transcriber name an external landing files under
+    """Transcriber name for an EXTERNAL landing (ruling 9ffce5f7 (1)): the model id
+    plus a manual marker, so a pasted transcript is a THIRD TRANSCRIBER beside the
+    local capabilities — decomp folds it per chunk like any other variant, and the
+    marker keeps it distinguishable from a capability run of the same model."""
+    mid = (model_id or "").strip()
+    if not mid:
+        raise ValueError("external_transcriber_name: model_id is required")
+    return mid + EXTERNAL_TRANSCRIBER_MARKER
+
+
+def external_config_hash(
+    model_id: str,     # The external model id
+    prompt_hash: str,  # Hash of the prompt template the operator used ("" = no prompt recorded)
+) -> str:  # "sha256:<hex>" — the config-hash slot of an external landing
+    """The config hash an external landing carries where a capability's effective
+    config hash goes: sha256 over (model id, prompt hash). The prompt is DATA
+    (f304d31d), so a different prompt template is a different variant — and the
+    Transcript identity (rendition, transcriber, config_hash) stays recomputable
+    from the derived manifest alone."""
+    import hashlib
+    h = hashlib.sha256()
+    h.update((model_id or "").strip().encode("utf-8"))
+    h.update(b"\n")
+    h.update((prompt_hash or "").strip().encode("utf-8"))
+    return "sha256:" + h.hexdigest()
+
+
 def segment_node_id(
     rendition_id: str,     # Owning AudioRendition node id
-    vad_config_hash: str,  # VAD capability config hash (skeleton identity input)
+    vad_config_hash: str,  # Skeleton config hash (identity input: VAD config, + split policy when a split stage ran)
     chunk_start: float,    # VAD chunk start (chunk-local seconds within the rendition WAV)
     chunk_end: float,      # VAD chunk end (chunk-local seconds)
+    identity_salt: Optional[str] = None,  # Respine salt (0b4d5cfa (3)): joins the id ONLY; None = the spine's original derivation
 ) -> str:  # Deterministic Segment node id
     """Fine Segment identity = audio-side only (audio rendition, VAD config, chunk
     range) — so the skeleton's ids are SHARED across transcribers by
     construction (C4 "store agreement once" falls out of identity design). Keyed
     on the RENDITION: each rendition has its own fine spine (vocals isolation can
-    yield different VAD chunk boundaries than raw)."""
+    yield different VAD chunk boundaries than raw).
+
+    A CHUNK RESPINE (0b4d5cfa) re-derives one coarse chunk into the LIVE spine
+    from a landed external transcript: its segments keep the live skeleton hash
+    (every picker groups spines by it) and fork identity through `identity_salt`
+    = the landed Transcript's node id, so the same landing twice collides into
+    a no-op and a different landing mints fresh segments. None (the default)
+    reproduces every pre-salt id unchanged."""
+    if identity_salt:
+        return derive_node_id("segment", rendition_id, vad_config_hash, chunk_start, chunk_end,
+                              identity_salt)
     return derive_node_id("segment", rendition_id, vad_config_hash, chunk_start, chunk_end)
 
-# %% ../nbs/schema.ipynb #d768584a
+
 @dataclass
 class SourceNode:
     """The provenance root: one ingested media file."""
@@ -128,7 +166,7 @@ class SourceNode:
                                   content_hash=self.content_hash).to_dict()],
         }
 
-# %% ../nbs/schema.ipynb #3d76c961
+
 @dataclass
 class AudioSegmentNode:
     """Coarse ~5-min spine member: a BOUNDARY range of the Source (an audio fact),
@@ -169,7 +207,7 @@ class AudioSegmentNode:
             "sources": [],
         }
 
-# %% ../nbs/schema.ipynb #c97ae502
+
 @dataclass
 class AudioRenditionNode:
     """A model-input rendition OF an AudioSegment — the materialized 16k-mono WAV
@@ -216,7 +254,7 @@ class AudioRenditionNode:
         """DERIVED_FROM edge: this rendition derives from its AudioSegment's audio."""
         return make_edge(self.id, self.audio_segment, OverlayRelations.DERIVED_FROM)
 
-# %% ../nbs/schema.ipynb #9948f2c5
+
 @dataclass
 class TranscriptNode:
     """One transcriber's text for one AudioRendition (per-transcriber variants at
@@ -228,6 +266,8 @@ class TranscriptNode:
     audio_hash: str               # Content hash of the consumed model-input WAV (the rendition's)
     metadata: Dict[str, Any] = field(default_factory=dict)  # Transcriber-reported metadata
     asserted_at: Optional[float] = None  # Derivation timestamp; None = now
+    actor: Optional[str] = None   # Attribution actor; None = "capability:<transcriber>" (an EXTERNAL landing names the operator, 9ffce5f7 (1))
+    method: str = "transcribe"    # Attribution method ("transcribe" for a capability run; "external-landing" for pasted text)
 
     @property
     def id(self) -> str:  # Deterministic node id
@@ -244,7 +284,7 @@ class TranscriptNode:
         }
         if self.metadata:
             props["metadata"] = dict(self.metadata)
-        props.update(attribution(f"capability:{self.transcriber}", method="transcribe",
+        props.update(attribution(self.actor or f"capability:{self.transcriber}", method=self.method,
                                  asserted_at=self.asserted_at))
         return {
             "id": self.id,
@@ -259,7 +299,19 @@ class TranscriptNode:
         """DERIVED_FROM edge: this Transcript derives from its AudioRendition."""
         return make_edge(self.id, self.rendition, OverlayRelations.DERIVED_FROM)
 
-# %% ../nbs/schema.ipynb #0c830160
+    def supersedes_edge(
+        self,
+        prior_transcript_id: str,  # The Transcript variant this one replaces (same rendition + transcriber, an older config)
+    ) -> Dict[str, Any]:  # Edge wire dict
+        """SUPERSEDES edge: this variant replaces a prior one for the same (rendition,
+        transcriber) — a chunk-targeted re-run under a new config, or a re-landed
+        external transcript (ruling 910f3692 (2)). The prior node STAYS as append-only
+        history; readers treat a variant with an incoming SUPERSEDES edge as NOT LIVE."""
+        if prior_transcript_id == self.id:
+            raise ValueError("supersedes_edge: a Transcript cannot supersede itself")
+        return make_edge(self.id, prior_transcript_id, OverlayRelations.SUPERSEDES)
+
+
 @dataclass
 class TranscriptSliceRef:
     """One per-transcriber char-range reference for a fine Segment: where this
@@ -276,19 +328,28 @@ class TranscriptSliceRef:
                          content_hash=SourceRef.compute_hash(self.text.encode()),
                          slice=CharSlice(start=self.start_char, end=self.end_char)).to_dict()
 
-# %% ../nbs/schema.ipynb #fecb183e
+
 @dataclass
 class SegmentNode:
     """Fine spine member: one VAD chunk — IMMUTABLE audio range + CORRECTABLE
     text (the immutable-audio/mutable-text spine seam). PART_OF its AudioRendition
-    (each rendition has its own fine spine).
+    (each rendition has its own fine spine). Parallel SPINES coexist under one
+    rendition (sentence-split, DEC f1024568): the skeleton hash feeds every node
+    id AND rides the queryable `skeleton_hash` prop, so spine-scoped reads never
+    mix coexisting skeletons (pre-split nodes lack the prop = the legacy spine).
 
     Layer-0 `text` is the ACCURACY transcriber's alignment; the designation is
     per-segment provenance, not global config (`text_from` names the
     authoritative Transcript; every transcriber's char range rides
-    `text_slices`, the authoritative one included)."""
+    `text_slices`, the authoritative one included).
+
+    A CHUNK RESPINE (0b4d5cfa) replaces one coarse chunk's segments INSIDE the
+    live spine: the new segments carry `identity_salt` (joins the id only —
+    `skeleton_hash` stays the live spine's, so no reader splits the spine),
+    the old ones are stamped `superseded_by` (the respine op id) and leave the
+    live view — readers filter `superseded_by is null`; nothing is deleted."""
     rendition: str            # Owning AudioRendition node id
-    vad_config_hash: str      # VAD config hash (skeleton identity input)
+    vad_config_hash: str      # Skeleton config hash (identity input: VAD config, + split policy when a split stage ran)
     chunk_start: float        # VAD chunk start (chunk-local seconds within the rendition WAV)
     chunk_end: float          # VAD chunk end (chunk-local seconds)
     index: int                # Source-wide fine-spine index (0-based)
@@ -298,13 +359,18 @@ class SegmentNode:
     audio_hash: str = ""      # Content hash of the owning rendition's model-input WAV
     source: Optional[str] = None     # Source node id (convenience for direct filters)
     text_from: Optional[str] = None  # Authoritative Transcript node id (None when text is empty)
+    split_policy: Optional[str] = None  # Split policy+version that refined the skeleton (None = raw VAD chunks)
     text_slices: List[TranscriptSliceRef] = field(default_factory=list)  # All per-transcriber slice refs
+    identity_salt: Optional[str] = None  # Respine salt (the landed Transcript id): joins the id ONLY (0b4d5cfa (3)); None = original derivation
+    superseded_by: Optional[str] = None  # Respine op id that retired this segment from the live view (stamped post-hoc; None = live)
 
     @property
     def id(self) -> str:  # Deterministic node id
-        """Deterministic node id (audio-side identity; shared across transcribers, per-rendition)."""
+        """Deterministic node id (audio-side identity; shared across transcribers, per-rendition;
+        forked by `identity_salt` on a chunk respine)."""
         return segment_node_id(self.rendition, self.vad_config_hash,
-                               self.chunk_start, self.chunk_end)
+                               self.chunk_start, self.chunk_end,
+                               identity_salt=self.identity_salt)
 
     def to_graph_node(self) -> Dict[str, Any]:  # Node wire dict
         """Build the Segment node wire dict (audio ref + per-transcriber text slice refs)."""
@@ -316,11 +382,18 @@ class SegmentNode:
             "chunk_start": self.chunk_start,
             "chunk_end": self.chunk_end,
             "rendition_id": self.rendition,
+            "skeleton_hash": self.vad_config_hash,
         }
+        if self.split_policy:
+            props["split_policy"] = self.split_policy
         if self.source:
             props["source_id"] = self.source
         if self.text_from:
             props["text_from"] = self.text_from
+        if self.identity_salt:
+            props["identity_salt"] = self.identity_salt
+        if self.superseded_by:
+            props["superseded_by"] = self.superseded_by
         sources = [SourceRef(locator=GraphNodeRef(node_id=self.rendition),
                              content_hash=self.audio_hash,
                              slice=TimeSlice(start=self.chunk_start, end=self.chunk_end)).to_dict()]
@@ -331,3 +404,135 @@ class SegmentNode:
             "properties": props,
             "sources": sources,
         }
+
+
+RESPINE_OP_VERB = "chunk-respine"                # The journaled spine-fact op that lands a chunk respine (0b4d5cfa (4))
+SOURCE_RESPINED_CHUNKS_PROP = "respined_chunks"  # Source prop: the list of RespinedChunkEntry dicts, append-only
+SEGMENT_SUPERSEDED_BY_PROP = "superseded_by"     # Segment prop stamped on the chunk's old segments (live readers filter it null)
+
+
+@dataclass
+class RespinedChunkEntry:
+    """One chunk respine as the Source records it (0b4d5cfa (4)): the entry the
+    `chunk-respine` op appends to the Source's `respined_chunks` list — WHICH
+    coarse chunk, WHICH landed Transcript re-derived it (= the new segments'
+    identity salt), under WHICH decomp run, when, and what the op did to the
+    dependents (stranded ids on explicit say-so; carried = the corrections the
+    chunk-scoped transfer re-homed by time: accepted event inserts, speaker
+    assignments). The op id is what `superseded_by` on the old segments names."""
+    audio_segment: str                                  # AudioSegment node id (the coarse chunk)
+    transcript: str                                     # The landed Transcript node id (= identity_salt of the new segments)
+    run: str                                            # The decomp run id the re-derivation ran under
+    op_id: str                                          # The chunk-respine op id (stamped as superseded_by)
+    ts: float                                           # Wall-clock seconds of the landing
+    old_segments: List[str] = field(default_factory=list)   # The superseded segment ids, index order
+    new_segments: List[str] = field(default_factory=list)   # The replacement segment ids, index order
+    stranded: List[str] = field(default_factory=list)   # Dependent Correction ids that stopped projecting (on say-so)
+    carried: List[str] = field(default_factory=list)    # Fresh Correction ids the transfer minted onto the new segments
+    straddles: List[str] = field(default_factory=list)  # New segment ids left unassigned because they straddle two donor speakers (4a7ec4f8 (3))
+
+    def to_dict(self) -> Dict[str, Any]:  # The wire entry
+        """The entry as it rides the Source prop (plain JSON, list order preserved)."""
+        return {"audio_segment": self.audio_segment, "transcript": self.transcript,
+                "run": self.run, "op_id": self.op_id, "ts": self.ts,
+                "old_segments": list(self.old_segments), "new_segments": list(self.new_segments),
+                "stranded": list(self.stranded), "carried": list(self.carried),
+                "straddles": list(self.straddles)}
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "RespinedChunkEntry":  # Parsed entry
+        """Read an entry back off the Source prop (missing lists read empty)."""
+        return cls(audio_segment=str(d.get("audio_segment") or ""),
+                   transcript=str(d.get("transcript") or ""),
+                   run=str(d.get("run") or ""), op_id=str(d.get("op_id") or ""),
+                   ts=float(d.get("ts") or 0.0),
+                   old_segments=[str(s) for s in (d.get("old_segments") or [])],
+                   new_segments=[str(s) for s in (d.get("new_segments") or [])],
+                   stranded=[str(s) for s in (d.get("stranded") or [])],
+                   carried=[str(s) for s in (d.get("carried") or [])],
+                   straddles=[str(s) for s in (d.get("straddles") or [])])
+
+
+def normalize_collection_title(
+    title: str,  # Raw title (folder name, user input, ...)
+) -> str:  # Normalized identity form
+    """Normalize a collection title for identity derivation.
+
+    Casefold + underscores-to-spaces + whitespace collapse, so a folder named
+    ``Hardcore_History`` and a hand-typed ``Hardcore History`` converge on the
+    SAME collection node (ae3464fc: select-existing and retype-the-title are
+    the same act by construction). Display keeps the raw title; only identity
+    normalizes."""
+    return " ".join(title.replace("_", " ").split()).casefold()
+
+
+def collection_node_id(
+    title: str,  # Collection title (normalized internally)
+) -> str:  # Deterministic Collection node id
+    """Collection identity = the NORMALIZED TITLE (ratified fork, hub-session
+    2026-07-21): path-based identity breaks workspace relocatability, and
+    member-hash identity breaks late-added members — late binding is a feature.
+    The same book ingested twice (different paths, different machines, members
+    accreted over weeks) is the same collection; rare title collisions are
+    propose/confirm reconciler territory."""
+    return derive_node_id("collection", normalize_collection_title(title))
+
+
+@dataclass
+class CollectionNode:
+    """An intrinsic collection (book, podcast series, lecture course) — the
+    fractal spine layer ABOVE Source (the grammar's "series -> episode
+    tomorrow", arrived).
+
+    Status rides the node (ae3464fc actor criterion): a human who accepted,
+    renamed, or selected the collection at run launch has CONFIRMED it;
+    untouched tool defaults (headless folder run) land PROPOSED — visible and
+    grouping-usable everywhere, flagged as awaiting a human. A folder is
+    EVIDENCE of a grouping, not proof: proposed collections are cheap to
+    rename, refile out of, or dissolve. root_kind=asserted — a collection is
+    a grouping ASSERTION about ingested content, not ingested content itself.
+    Collection PART_OF Collection nesting is grammar-free (no v0 tooling)."""
+    title: str                     # Display title (identity input via normalize_collection_title)
+    status: str = "proposed"       # "proposed" (tool inference) | "confirmed" (human act)
+    actor: str = "human"           # Who declared it (attribution; e.g. "human", "tui:transcription", "cli:transcribe")
+    asserted_at: Optional[float] = None  # Declaration timestamp; None = now
+
+    @property
+    def id(self) -> str:  # Deterministic node id
+        """Deterministic node id."""
+        return collection_node_id(self.title)
+
+    def to_graph_node(self) -> Dict[str, Any]:  # Node wire dict
+        """Build the Collection node wire dict (asserted root; attribution included)."""
+        props: Dict[str, Any] = {
+            "title": self.title,
+            "status": self.status,
+            "root_kind": "asserted",
+        }
+        props.update(attribution(self.actor, method="collection-declaration",
+                                 asserted_at=self.asserted_at))
+        return {
+            "id": self.id,
+            "label": TranscriptGraphLabels.COLLECTION,
+            "properties": props,
+            "sources": [],
+        }
+
+
+def collection_edges(
+    collection_id: str,     # Collection node id
+    member_ids: List[str],  # Member Source node ids (declaration order when ordered=True)
+    ordered: bool = False,  # True = materialize the order (NEXT chain + STARTS_WITH)
+) -> List[Dict[str, Any]]:  # Edge wire dicts
+    """Membership edges for a collection (ae3464fc: ORDER IS OPTIONAL).
+
+    Unordered membership is just PART_OF member->collection — individually
+    accreted members (chapters run one at a time) attach without fabricating a
+    sequence. When an order IS known (a folder run's sorted expansion, or a
+    curation act), the full fractal spine pattern materializes via
+    spine_edges: PART_OF + NEXT chain + STARTS_WITH — identical grammar to
+    every layer below. Reordering and late insertion are curation ops, never
+    capture-time guesses."""
+    if ordered:
+        return spine_edges(collection_id, member_ids)
+    return [make_edge(m, collection_id, SpineRelations.PART_OF) for m in member_ids]

cjm_transcript_graph_schema-0.0.11/cjm_transcript_graph_schema.egg-info/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: cjm-transcript-graph-schema
+Version: 0.0.11
+Summary: Audio-transcript layer schema for context graphs: Source, AudioSegment, Transcript, and Segment nodes with deterministic identity tuples and graph-node mapping, shared by the transcription, decomposition, and correction workflow cores.
+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-transcript-graph-schema
+Keywords: python
+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-layer>=0.0.7
+Requires-Dist: cjm-context-graph-primitives>=0.0.12
+Dynamic: license-file
+
+# cjm-transcript-graph-schema
+
+<!-- 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) -->
+
+Audio-transcript layer schema for context graphs: Source, AudioSegment, Transcript, and Segment nodes with deterministic identity tuples and graph-node mapping, shared by the transcription, decomposition, and correction workflow cores.
+
+## Modules
+
+- **`cjm_transcript_graph_schema.schema`** — The audio-transcript layer schema (where-graph-begins locked layer schema): Source -> AudioSegment(coarse boundary) -> AudioRendition(model-input: raw | vocals | ...) -> Transcript(per-transcriber variants) emitted by transcription, extended with the fine Segment spine (per-rendition) by decomposition. Deterministic identity tuples per the stage-5 ratified rule; the AudioRendition node lets raw + preprocessed model-inputs of one boundary coexist in one graph. Document from the pre-CR-18 era dissolves into Source.
+
+## API
+
+### `cjm_transcript_graph_schema.schema`
+
+- `AudioRenditionNode` _class_ — A model-input rendition OF an AudioSegment — the materialized 16k-mono WAV
+- `AudioSegmentNode` _class_ — Coarse ~5-min spine member: a BOUNDARY range of the Source (an audio fact),
+- `CollectionNode` _class_ — An intrinsic collection (book, podcast series, lecture course) — the
+- `RespinedChunkEntry` _class_ — One chunk respine as the Source records it (0b4d5cfa (4)): the entry the
+- `SegmentNode` _class_ — Fine spine member: one VAD chunk — IMMUTABLE audio range + CORRECTABLE
+- `SourceNode` _class_ — The provenance root: one ingested media file.
+- `TranscriptGraphLabels` _class_ — Node labels of the audio-transcript layer schema.
+- `TranscriptNode` _class_ — One transcriber's text for one AudioRendition (per-transcriber variants at
+- `TranscriptSliceRef` _class_ — One per-transcriber char-range reference for a fine Segment: where this
+- `audio_rendition_node_id` _function_ — AudioRendition identity = (audio segment, preprocessing chain).
+- `audio_segment_node_id` _function_ — AudioSegment identity = (source, boundary range).
+- `collection_edges` _function_ — Membership edges for a collection (ae3464fc: ORDER IS OPTIONAL).
+- `collection_node_id` _function_ — Collection identity = the NORMALIZED TITLE (ratified fork, hub-session
+- `normalize_collection_title` _function_ — Normalize a collection title for identity derivation.
+- `segment_node_id` _function_ — Fine Segment identity = audio-side only (audio rendition, VAD config, chunk
+- `source_node_id` _function_ — Source identity = the ingested file's content hash (Thread-1 ingested-root identity).
+- `transcript_node_id` _function_ — Transcript identity = (audio rendition, transcriber, config) — MIRRORS the
+
+## Dependencies
+
+**Depends on:** `cjm-context-graph-layer`, `cjm-context-graph-primitives`
+**Used by:** `cjm-context-graph-layer`, `cjm-transcript-correction-core`, `cjm-transcript-correction-tui`, `cjm-transcript-decomp-core`, `cjm-transcription-core`

{cjm_transcript_graph_schema-0.0.7 → cjm_transcript_graph_schema-0.0.11}/cjm_transcript_graph_schema.egg-info/SOURCES.txt

@@ -3,11 +3,10 @@ MANIFEST.in
 README.md
 pyproject.toml
 cjm_transcript_graph_schema/__init__.py
-cjm_transcript_graph_schema/_modidx.py
 cjm_transcript_graph_schema/schema.py
 cjm_transcript_graph_schema.egg-info/PKG-INFO
 cjm_transcript_graph_schema.egg-info/SOURCES.txt
 cjm_transcript_graph_schema.egg-info/dependency_links.txt
-cjm_transcript_graph_schema.egg-info/entry_points.txt
 cjm_transcript_graph_schema.egg-info/requires.txt
-cjm_transcript_graph_schema.egg-info/top_level.txt
+cjm_transcript_graph_schema.egg-info/top_level.txt
+tests/test_schema.py

{cjm_transcript_graph_schema-0.0.7 → cjm_transcript_graph_schema-0.0.11}/pyproject.toml

@@ -10,7 +10,7 @@ readme = "README.md"
 requires-python = ">=3.12"
 license = {text = "Apache-2.0"}
 authors = [{name = "Christian J. Mills", email = "9126128+cj-mills@users.noreply.github.com"}]
-keywords = ['nbdev']
+keywords = ['python']
 classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
@@ -19,10 +19,6 @@ dependencies = ['cjm-context-graph-layer>=0.0.7', 'cjm-context-graph-primitives>
 
 [project.urls]
 Repository = "https://github.com/cj-mills/cjm-transcript-graph-schema"
-Documentation = "https://cj-mills.github.io/cjm-transcript-graph-schema/"
-
-[project.entry-points.nbdev]
-cjm_transcript_graph_schema = "cjm_transcript_graph_schema._modidx:d"
 
 [tool.setuptools.dynamic]
 version = {attr = "cjm_transcript_graph_schema.__version__"}
@@ -30,4 +26,3 @@ version = {attr = "cjm_transcript_graph_schema.__version__"}
 [tool.setuptools.packages.find]
 include = ["cjm_transcript_graph_schema*"]
 
-[tool.nbdev]