paces 0.0.9__tar.gz → 0.0.11__tar.gz

{paces-0.0.9 → paces-0.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.9
+Version: 0.0.11
 Summary: Turn instructional media into structured, interactive learning material
 Project-URL: Homepage, https://github.com/thorwhalen/paces
 Project-URL: Repository, https://github.com/thorwhalen/paces
@@ -20,6 +20,7 @@ Requires-Dist: argcomplete>=3; extra == 'cli'
 Requires-Dist: cw<0.2,>=0.1.1; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: cw<0.2,>=0.1.1; extra == 'dev'
+Requires-Dist: lacing>=0.0.40; extra == 'dev'
 Requires-Dist: mixing[audio,beats]>=0.0.39; extra == 'dev'
 Requires-Dist: numba>=0.59; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
@@ -29,6 +30,8 @@ Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
 Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: lacing
+Requires-Dist: lacing>=0.0.40; extra == 'lacing'
 Provides-Extra: media
 Requires-Dist: mixing>=0.0.39; extra == 'media'
 Provides-Extra: pose
@@ -152,6 +155,64 @@ run-through and the breakdown are the same step seen twice). Uncertainty is
 content (`OpenQuestion`), and human edits are protected from regeneration
 (`Lock`).
 
+## The evidence layer
+
+The document is the *contract*; the machine evidence behind it — the
+speech/music split, the metric grid, the beats, the transcript, the step
+candidates, the crop recipes, and the lineage between them — lives in a
+[`lacing`](https://github.com/thorwhalen/lacing) store, and the document is a
+**projection** of it. The document is derivable from the store; the store is
+not derivable from the document.
+
+```python
+from lacing import MemoryStore                 # pip install 'paces[lacing]'
+from paces import segment, from_store, to_store
+from paces.model import dumps_document
+
+grid = {"unit": "eight", "subdivisions": 8, "tempoBpm": "129.2", "origin": "51.2"}
+asset_sha256 = "a" * 64                        # lacing.hash_file(video) in real use
+seg = segment(None, steps=[("Mise en place", 2), ("Déhanchés", 8)], grid=grid)
+
+store = MemoryStore()                          # or SqliteStore('project.annot')
+guide = dict(doc_id="que-calor", title="Que Calor", domain="dance",
+             source="https://youtu.be/q_TUyxUhoEw")
+
+write = to_store(seg, store=store, asset_id=asset_sha256, **guide)
+
+dumps_document(from_store(store, asset_id=asset_sha256)) == dumps_document(write.document)
+# True — the projection is exact
+
+to_store(seg, store=store, asset_id=asset_sha256, **guide).written
+# 0 — a re-run of the same analysis writes nothing
+```
+
+The store is injected, never constructed for you: `MemoryStore()` in tests, a
+`SqliteStore` for a project sidecar, any `dol` store that conforms. Annotation
+ids are derived (`uuid5`) from the evidence they stand for, so a re-derivation
+*is* the same annotation — which is what keeps `was_derived_from` lineage
+resolving and lets `write.document`'s `Origin.annotationId` be committed. Rows
+whose value digest did not change are left completely alone, so freshness does
+not fire on a no-op re-run.
+
+`to_store` is a **re-derivation** of the guide, not a merge into it: a step
+that no longer exists is dropped rather than left to be resurrected by the
+next projection. Pruning only ever touches this asset, this `doc_id`, and the
+guide's own tiers. Evidence *about the asset* — the speech/music split, the
+beats, the transcript — is shared by every guide over that asset and is never
+pruned, so one guide can't delete what another's lineage points at; a
+re-measure adds a row under a new content-derived key and the old one stays.
+`prune=False` opts out of the rest.
+
+Analysis a `Segmentation` cannot carry rides along as keywords: `passes=`
+(the speech/music split), `beats=`, `transcript=`, `cues=`, `recipes=`. What
+stays on the document and never flows back into the store: `locks`,
+`questions`, `artifacts`, and span `excerpt` windows — those are human
+decisions, not measurements. Full table and rationale in
+`docs/07-annotation-model.md` §6.
+
+`import paces` does not import `lacing`: the core stays pydantic-only, and
+`paces.to_store` resolves the extra on first use.
+
 ## The pieces
 
 | you want | reach for |
@@ -164,6 +225,7 @@ content (`OpenQuestion`), and human edits are protected from regeneration
 | the committed artifact | `to_document(seg, ...)` → `StepDocument` |
 | real clips/gifs/posters for the page | `derive_document(doc, media=..., doc_path=...)` / `paces derive` (`pip install paces[media]`) |
 | auto-crop those clips to the people in frame | `derive(..., subject_locator=paces.pose.rtmlib_pose)` / `--subject-locator paces.pose:rtmlib_pose` (`pip install paces[pose]`) |
+| persist the analysis behind a document | `to_store(seg, store=..., asset_id=...)` / `from_store(store, asset_id=...)` (`pip install paces[lacing]`) |
 | a practice page | `render_html(doc)` |
 | wall-clock times from counts | `resolve(doc)` |
 | sanity checks | `validate_document(doc)` |
@@ -175,6 +237,6 @@ content (`OpenQuestion`), and human edits are protected from regeneration
 Young and moving. The document schema is validated by round-tripping a real
 proof of concept ([an interactive dance-practice
 page](https://thorwhalen.com/que_calor_dance/)) through it — see
-`tests/test_roundtrip_poc.py`. Media derivation (auto-cropped looping clips),
-intrinsic segmenters (scene/beat/speech detection), and the evidence layer
-are designed (see `docs/`) and arrive next.
+`tests/test_roundtrip_poc.py`. Media derivation (auto-cropped looping clips)
+and the evidence layer have landed; intrinsic segmenters (scene/beat/speech
+detection) are designed (see `docs/`) and arrive next.

{paces-0.0.9 → paces-0.0.11}/README.md

@@ -114,6 +114,64 @@ run-through and the breakdown are the same step seen twice). Uncertainty is
 content (`OpenQuestion`), and human edits are protected from regeneration
 (`Lock`).
 
+## The evidence layer
+
+The document is the *contract*; the machine evidence behind it — the
+speech/music split, the metric grid, the beats, the transcript, the step
+candidates, the crop recipes, and the lineage between them — lives in a
+[`lacing`](https://github.com/thorwhalen/lacing) store, and the document is a
+**projection** of it. The document is derivable from the store; the store is
+not derivable from the document.
+
+```python
+from lacing import MemoryStore                 # pip install 'paces[lacing]'
+from paces import segment, from_store, to_store
+from paces.model import dumps_document
+
+grid = {"unit": "eight", "subdivisions": 8, "tempoBpm": "129.2", "origin": "51.2"}
+asset_sha256 = "a" * 64                        # lacing.hash_file(video) in real use
+seg = segment(None, steps=[("Mise en place", 2), ("Déhanchés", 8)], grid=grid)
+
+store = MemoryStore()                          # or SqliteStore('project.annot')
+guide = dict(doc_id="que-calor", title="Que Calor", domain="dance",
+             source="https://youtu.be/q_TUyxUhoEw")
+
+write = to_store(seg, store=store, asset_id=asset_sha256, **guide)
+
+dumps_document(from_store(store, asset_id=asset_sha256)) == dumps_document(write.document)
+# True — the projection is exact
+
+to_store(seg, store=store, asset_id=asset_sha256, **guide).written
+# 0 — a re-run of the same analysis writes nothing
+```
+
+The store is injected, never constructed for you: `MemoryStore()` in tests, a
+`SqliteStore` for a project sidecar, any `dol` store that conforms. Annotation
+ids are derived (`uuid5`) from the evidence they stand for, so a re-derivation
+*is* the same annotation — which is what keeps `was_derived_from` lineage
+resolving and lets `write.document`'s `Origin.annotationId` be committed. Rows
+whose value digest did not change are left completely alone, so freshness does
+not fire on a no-op re-run.
+
+`to_store` is a **re-derivation** of the guide, not a merge into it: a step
+that no longer exists is dropped rather than left to be resurrected by the
+next projection. Pruning only ever touches this asset, this `doc_id`, and the
+guide's own tiers. Evidence *about the asset* — the speech/music split, the
+beats, the transcript — is shared by every guide over that asset and is never
+pruned, so one guide can't delete what another's lineage points at; a
+re-measure adds a row under a new content-derived key and the old one stays.
+`prune=False` opts out of the rest.
+
+Analysis a `Segmentation` cannot carry rides along as keywords: `passes=`
+(the speech/music split), `beats=`, `transcript=`, `cues=`, `recipes=`. What
+stays on the document and never flows back into the store: `locks`,
+`questions`, `artifacts`, and span `excerpt` windows — those are human
+decisions, not measurements. Full table and rationale in
+`docs/07-annotation-model.md` §6.
+
+`import paces` does not import `lacing`: the core stays pydantic-only, and
+`paces.to_store` resolves the extra on first use.
+
 ## The pieces
 
 | you want | reach for |
@@ -126,6 +184,7 @@ content (`OpenQuestion`), and human edits are protected from regeneration
 | the committed artifact | `to_document(seg, ...)` → `StepDocument` |
 | real clips/gifs/posters for the page | `derive_document(doc, media=..., doc_path=...)` / `paces derive` (`pip install paces[media]`) |
 | auto-crop those clips to the people in frame | `derive(..., subject_locator=paces.pose.rtmlib_pose)` / `--subject-locator paces.pose:rtmlib_pose` (`pip install paces[pose]`) |
+| persist the analysis behind a document | `to_store(seg, store=..., asset_id=...)` / `from_store(store, asset_id=...)` (`pip install paces[lacing]`) |
 | a practice page | `render_html(doc)` |
 | wall-clock times from counts | `resolve(doc)` |
 | sanity checks | `validate_document(doc)` |
@@ -137,6 +196,6 @@ content (`OpenQuestion`), and human edits are protected from regeneration
 Young and moving. The document schema is validated by round-tripping a real
 proof of concept ([an interactive dance-practice
 page](https://thorwhalen.com/que_calor_dance/)) through it — see
-`tests/test_roundtrip_poc.py`. Media derivation (auto-cropped looping clips),
-intrinsic segmenters (scene/beat/speech detection), and the evidence layer
-are designed (see `docs/`) and arrive next.
+`tests/test_roundtrip_poc.py`. Media derivation (auto-cropped looping clips)
+and the evidence layer have landed; intrinsic segmenters (scene/beat/speech
+detection) are designed (see `docs/`) and arrive next.

{paces-0.0.9 → paces-0.0.11}/paces/__init__.py

@@ -116,6 +116,36 @@ __all__ = [
     # editing & regeneration
     "apply_edits",
     "merge_regenerated",
+    # the evidence layer (issue #4) — resolved lazily, needs [lacing]
+    "to_store",
+    "from_store",
+    "StoreWrite",
     # rendering
     "render_html",
 ]
+
+#: The evidence layer's public names and where they live. Resolved on first
+#: attribute access rather than imported here, so ``import paces`` keeps the
+#: pydantic-only core of ADR-0004 — installing ``paces`` must not pull
+#: ``lacing`` in, and asking for ``paces.to_store`` without the ``[lacing]``
+#: extra must fail with an install line rather than an AttributeError.
+_LAZY = {
+    "to_store": "paces.evidence",
+    "from_store": "paces.evidence",
+    "StoreWrite": "paces.evidence",
+    "recipes_from_store": "paces.evidence",
+}
+
+
+def __getattr__(name: str):
+    """Resolve the evidence layer on demand (PEP 562)."""
+    module_name = _LAZY.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    return getattr(importlib.import_module(module_name), name)
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_LAZY})

paces-0.0.11/paces/bodies/__init__.py

@@ -0,0 +1,111 @@
+"""The body schemas paces registers with ``lacing`` — the evidence layer's vocabulary.
+
+Importing this package registers every URI paces owns into
+:mod:`lacing.schema`'s registry. That registry is **one flat, fleet-wide
+dict**, ``register_body_schema`` is last-write-wins and silent, and
+``annot://schema/beat/v1`` is already ``reelee``'s *narrative* beat — so
+every URI paces owns is prefixed ``guide-`` (the thing it describes: a step
+guide), and the one URI paces does not own, ``annot://schema/word/v1``, is
+reused from :mod:`lacing.bodies` unchanged. The reasoning is issue #4's
+decision comment and ``docs/07-annotation-model.md §6.3``.
+
+Tier names are *not* prefixed: tiers are store-local, so ``step``,
+``step.sub``, ``cue``, ``beat`` cost nothing and stay exactly as
+``docs/07 §6.3`` wrote them.
+
+Two rules hold across every body here:
+
+- **No interval in a body.** Annotations are standoff; the interval lives on
+  ``Annotation.reference``. A body that wants to say *when* says it by being
+  attached somewhere, never by carrying a number.
+- **No floats where the document would refuse one.** Times, durations and
+  box coordinates cross as decimal strings, matching the document's
+  no-floats wire (``docs/07 §6.5``). ``confidence`` is the one exception the
+  document itself already makes.
+"""
+
+from paces.bodies.derivation import (
+    RECIPE_BODY_SCHEMA_URI,
+    RECIPE_TIER,
+    GuideRecipeBodyV1,
+)
+from paces.bodies.document import (
+    DOC_BODY_SCHEMA_URI,
+    DOC_TIER,
+    SOURCE_BODY_SCHEMA_URI,
+    SOURCE_TIER,
+    GuideDocBodyV1,
+    GuideSourceBodyV1,
+)
+from paces.bodies.signal import (
+    BEAT_BODY_SCHEMA_URI,
+    BEAT_TIER,
+    GRID_BODY_SCHEMA_URI,
+    GRID_TIER,
+    PASS_BODY_SCHEMA_URI,
+    PASS_TIER,
+    WORD_BODY_SCHEMA_URI,
+    WORD_TIER,
+    GuideBeatBodyV1,
+    GuideGridBodyV1,
+    GuidePassBodyV1,
+)
+from paces.bodies.step import (
+    CUE_BODY_SCHEMA_URI,
+    CUE_TIER,
+    STEP_BODY_SCHEMA_URI,
+    STEP_TIER,
+    SUB_STEP_TIER,
+    GuideCueBodyV1,
+    GuideStepBodyV1,
+)
+
+#: Every ``body_schema_uri`` paces *owns*. ``word/v1`` is deliberately absent:
+#: it is lacing's, reused rather than claimed. Pinned by
+#: ``tests/test_evidence_schemas.py`` against a committed JSON Schema snapshot,
+#: so a rename or a field change fails the build (issue #4).
+PACES_BODY_SCHEMA_URIS = (
+    DOC_BODY_SCHEMA_URI,
+    SOURCE_BODY_SCHEMA_URI,
+    PASS_BODY_SCHEMA_URI,
+    STEP_BODY_SCHEMA_URI,
+    CUE_BODY_SCHEMA_URI,
+    GRID_BODY_SCHEMA_URI,
+    BEAT_BODY_SCHEMA_URI,
+    RECIPE_BODY_SCHEMA_URI,
+)
+
+__all__ = [
+    "PACES_BODY_SCHEMA_URIS",
+    # document envelope
+    "DOC_TIER",
+    "DOC_BODY_SCHEMA_URI",
+    "GuideDocBodyV1",
+    "SOURCE_TIER",
+    "SOURCE_BODY_SCHEMA_URI",
+    "GuideSourceBodyV1",
+    # steps and cues
+    "STEP_TIER",
+    "SUB_STEP_TIER",
+    "STEP_BODY_SCHEMA_URI",
+    "GuideStepBodyV1",
+    "CUE_TIER",
+    "CUE_BODY_SCHEMA_URI",
+    "GuideCueBodyV1",
+    # measured signal
+    "PASS_TIER",
+    "PASS_BODY_SCHEMA_URI",
+    "GuidePassBodyV1",
+    "GRID_TIER",
+    "GRID_BODY_SCHEMA_URI",
+    "GuideGridBodyV1",
+    "BEAT_TIER",
+    "BEAT_BODY_SCHEMA_URI",
+    "GuideBeatBodyV1",
+    "WORD_TIER",
+    "WORD_BODY_SCHEMA_URI",
+    # derivation
+    "RECIPE_TIER",
+    "RECIPE_BODY_SCHEMA_URI",
+    "GuideRecipeBodyV1",
+]

paces-0.0.11/paces/bodies/_base.py

@@ -0,0 +1,24 @@
+"""Shared conventions for every paces body schema.
+
+One base class and one type alias, so the three rules that make a body
+round-trippable are stated once rather than re-typed per module: frozen,
+``extra="forbid"`` (lacing non-negotiable #3), and decimal strings where the
+document would refuse a float.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+#: Exact decimal number as a string ("231.3") — the document's wire form for
+#: any quantity, mirrored here so a body never carries a float the document
+#: itself would reject (``docs/07 §6.5``).
+Decimal = Annotated[str, Field(pattern=r"^-?\d+(\.\d+)?$")]
+
+
+class BodyBase(BaseModel):
+    """Frozen, closed-world body model — lacing validates against it by URI."""
+
+    model_config = {"frozen": True, "extra": "forbid"}

paces-0.0.11/paces/bodies/derivation.py

@@ -0,0 +1,76 @@
+"""Body schema for derivation recipes — the POC's ``crops.json``, promoted.
+
+``annot://schema/guide-recipe/v1``, tier ``derivation``
+(``SYMBOLIC_ASSOCIATION`` under ``step``): the *parameters* a derived file
+was made with, so a re-run is stable and a human override survives it.
+``docs/07 §6.2``'s split, stated once: the document's
+:class:`~paces.model.ArtifactRef` says **what** a file is; this says **how**
+it was made.
+
+The recipe's ``window`` is not a field — it is the annotation's reference
+interval, which is exactly what a window is. Everything else is
+:class:`paces.derivation.CropRecipe` as it already exists on disk, with the
+box's coordinates crossing as decimal strings; the sidecar is committed, so
+it has always been float-free and the store keeps it that way.
+"""
+
+from __future__ import annotations
+
+from lacing.schema import register_body_schema
+from pydantic import Field
+
+from paces.bodies._base import BodyBase, Decimal
+
+RECIPE_TIER = "derivation"
+RECIPE_BODY_SCHEMA_URI = "annot://schema/guide-recipe/v1"
+
+
+class GuideRecipeBodyV1(BodyBase):
+    """One span's derivation parameters, keyed by the span address."""
+
+    doc_id: str = Field(..., description="Which guide this recipe belongs to.")
+    span_key: str = Field(
+        ...,
+        description=(
+            "The span address ``{step_id}/{source}/{role}/{start}`` — the same "
+            "key ``paces.derivation`` writes into the committed sidecar, so "
+            "the two layers join without a translation table."
+        ),
+    )
+    step_id: str = Field(..., description="The step this recipe derives media for.")
+    box: list[Decimal] | None = Field(
+        None,
+        description=(
+            "The resolved crop box (x, y, w, h) in pixels, as decimal "
+            "strings. None means full frame — a recorded decision, not a gap."
+        ),
+    )
+    frame_width: int = Field(..., description="Source frame width the box is in.")
+    frame_height: int = Field(..., description="Source frame height the box is in.")
+    source_asset_id: str | None = Field(
+        None, description="Hash of the media cut from. None = identity unverified."
+    )
+    locator: str = Field(
+        ..., description="Which subject locator resolved the box ('full_frame', ...)."
+    )
+    params: dict[str, Decimal] = Field(
+        default_factory=dict,
+        description=(
+            "Policy parameters the box was resolved under (aspect, pad). A "
+            "change here re-locates an unlocked entry."
+        ),
+    )
+    locked: bool = Field(
+        False, description="A human set this box; reconcile must not re-derive it."
+    )
+    media_digest: str | None = Field(
+        None,
+        description=(
+            "What the stored media was actually cut with (box + window + "
+            "source hash). A hand-edited box or a re-timed window changes it "
+            "and forces a re-encode instead of serving stale bytes."
+        ),
+    )
+
+
+register_body_schema(RECIPE_BODY_SCHEMA_URI, GuideRecipeBodyV1)

paces-0.0.11/paces/bodies/document.py

@@ -0,0 +1,118 @@
+"""Body schemas for the document envelope and its sources.
+
+- ``annot://schema/guide-doc/v1`` (tier ``document``) — the one annotation
+  that says *which guide this is*: id, title, language, domain, plus the
+  analysis run's own report (``method``, ``flags``). Everything ordered or
+  timed hangs off the other tiers.
+- ``annot://schema/guide-source/v1`` (tier ``source``) — one per
+  :class:`~paces.model.Source`.
+
+Neither body carries an interval; both annotations attach as point
+annotations at tick 0, which is lacing's spelling of "about the asset, not
+about a region of it".
+
+What is deliberately **not** here: ``locks``, ``questions``, ``artifacts``
+and span ``excerpt`` windows. Those are document-layer records — a human
+edit, an open question, a built file, a hand-picked loop — and
+``docs/07 §6.0`` is explicit that nothing flows document → store. The
+evidence layer holds what analysis produced; the document holds what people
+did to it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from lacing.schema import register_body_schema
+from pydantic import Field
+
+from paces.bodies._base import BodyBase, Decimal
+
+DOC_TIER = "document"
+DOC_BODY_SCHEMA_URI = "annot://schema/guide-doc/v1"
+
+SOURCE_TIER = "source"
+SOURCE_BODY_SCHEMA_URI = "annot://schema/guide-source/v1"
+
+
+class GuideDocBodyV1(BodyBase):
+    """The guide's envelope: identity, presentation language, and the run."""
+
+    doc_id: str = Field(
+        ...,
+        description=(
+            "Stable slug of the guide within a project. Distinct from the "
+            "annotation id, and the field that lets one store hold several "
+            "guides over the same asset."
+        ),
+    )
+    title: str = Field(..., description="Human title of the guide.")
+    lang: str = Field("en", description="BCP-47 language tag of the guide's prose.")
+    domain: str = Field(
+        "generic", description="Domain slug: dance | recipe | workout | ..."
+    )
+    schema_version: str = Field(
+        ..., description="Version of the StepDocument schema this was projected at."
+    )
+    credits: str | None = Field(
+        None, description="Attribution line, when there is one."
+    )
+    method: str = Field(
+        "",
+        description=(
+            "Which segmentation capability produced the steps "
+            "(``Segmentation.method``). Empty when unrecorded."
+        ),
+    )
+    flags: list[str] = Field(
+        default_factory=list,
+        description=(
+            "The run's honesty flags (``Segmentation.flags``) — "
+            "'naming-abstained', 'origin-estimated: ...', and friends. "
+            "Evidence about the run, never projected into the document."
+        ),
+    )
+    attrs: dict[str, Any] = Field(
+        default_factory=dict, description="Namespaced open bag, as on the document."
+    )
+
+
+class GuideSourceBodyV1(BodyBase):
+    """One input the guide's spans refer into."""
+
+    doc_id: str = Field(
+        ...,
+        description=(
+            "Which guide this source belongs to — one store can hold several "
+            "guides over the same asset, and a projection has to read back "
+            "only its own."
+        ),
+    )
+    ordinal: int = Field(
+        ..., description="Position in the document's source list, 0-based."
+    )
+    source_id: str = Field(
+        ..., description="Slug of the source within the guide. Not the annotation id."
+    )
+    kind: str = Field(..., description="video | audio | image | document | url.")
+    uri: str = Field(..., description="Where the source lives.")
+    asset_id: str | None = Field(
+        None, description="Content hash of a local copy, if any."
+    )
+    duration_s: Decimal | None = Field(
+        None, description="Source duration in seconds, as a decimal string."
+    )
+    title: str | None = Field(None, description="Source title.")
+    attribution: str | None = Field(None, description="Who made it.")
+    rights: str | None = Field(
+        None,
+        description=(
+            "Usage rights. First-class in this domain (``docs/07 §8.7``): a "
+            "guide that restyles someone's choreography has to say so."
+        ),
+    )
+    attrs: dict[str, Any] = Field(default_factory=dict, description="Open bag.")
+
+
+register_body_schema(DOC_BODY_SCHEMA_URI, GuideDocBodyV1)
+register_body_schema(SOURCE_BODY_SCHEMA_URI, GuideSourceBodyV1)

paces-0.0.11/paces/bodies/signal.py

@@ -0,0 +1,122 @@
+"""Body schemas for what was measured off the media: passes, the grid, beats.
+
+- ``annot://schema/guide-pass/v1`` (tier ``source.pass``) — *"[45 s, 215 s]
+  is a music pass; [220 s, 520 s] is speech"*. The speech/music split
+  ``paces.measure`` gets from ``mixing.find_segments``, which is what made
+  the POC's dual timestamps possible in the first place.
+- ``annot://schema/guide-grid/v1`` (tier ``grid``) — the metric grid, **one**
+  annotation over the region it governs.
+- ``annot://schema/guide-beat/v1`` (tier ``beat``) — one point annotation per
+  *measured* beat.
+
+Why the grid is one annotation and the beats are separate: paces' grid is
+closed form (``tempo_bpm`` + ``origin`` + ``subdivisions``), so materialising
+N beats *from* it would be a denormalised cache with no invalidation story —
+the same argument ``docs/07 §7`` uses to refuse materialising Allen
+relations. Beat annotations are therefore written only when a producer hands
+over times it actually measured, and they carry a ``was_derived_from`` edge
+to the grid so a re-measure invalidates them.
+
+Transcripts reuse lacing's own ``annot://schema/word/v1`` unchanged, on tier
+``transcript.word``; the URIs and tier name live here so every evidence tier
+is named in one place.
+"""
+
+from __future__ import annotations
+
+import lacing.bodies  # noqa: F401  — registers the word/v1 paces reuses
+from lacing.schema import register_body_schema
+from pydantic import Field
+
+from paces.bodies._base import BodyBase, Decimal
+
+PASS_TIER = "source.pass"
+PASS_BODY_SCHEMA_URI = "annot://schema/guide-pass/v1"
+
+GRID_TIER = "grid"
+GRID_BODY_SCHEMA_URI = "annot://schema/guide-grid/v1"
+
+BEAT_TIER = "beat"
+BEAT_BODY_SCHEMA_URI = "annot://schema/guide-beat/v1"
+
+#: Transcripts are lacing's, not paces'. Named here so the tier table is
+#: complete in one file; NOT registered here, and NOT in
+#: ``PACES_BODY_SCHEMA_URIS`` — ``lacing.bodies.word`` owns it.
+WORD_TIER = "transcript.word"
+WORD_BODY_SCHEMA_URI = "annot://schema/word/v1"
+
+
+class GuidePassBodyV1(BodyBase):
+    """A stretch of one source with a single character (music, speech, ...)."""
+
+    label: str = Field(
+        ...,
+        description=(
+            "What this stretch is: 'music' | 'speech' | '' when the detector "
+            "found a segment it would not name."
+        ),
+    )
+    detector: str = Field(
+        "",
+        description=(
+            "What produced the split ('mixing.find_segments:speech_music'). "
+            "Empty when the caller supplied passes without saying."
+        ),
+    )
+
+
+class GuideGridBodyV1(BodyBase):
+    """How the domain unit relates to wall-clock time, over the region it governs.
+
+    The document's ``metric`` is projected straight back out of this — one
+    grid, one source of truth, no second copy in the document envelope.
+    """
+
+    doc_id: str = Field(
+        ...,
+        description=(
+            "Which guide this grid governs. The grid is per-guide, not "
+            "per-asset: two guides can count the same video differently."
+        ),
+    )
+    unit: str = Field(..., description="The domain unit counted: eight | bar | rep.")
+    subdivisions: int = Field(1, ge=1, description="Beats per unit (8 for an 8-count).")
+    tempo_bpm: Decimal | None = Field(
+        None,
+        description=(
+            "Tempo as a decimal string. None spells 'tempo unknown' — never '0'."
+        ),
+    )
+    origin: Decimal | None = Field(
+        None, description="Seconds into ``origin_source`` where unit 0 starts."
+    )
+    origin_source: str | None = Field(
+        None, description="Which source ``origin`` is measured in."
+    )
+    beat_count: int | None = Field(
+        None,
+        description=(
+            "How many beats were actually tracked, when the grid was measured "
+            "rather than supplied. None means nobody counted."
+        ),
+    )
+    method: str = Field(
+        "",
+        description=(
+            "Which capability produced the grid ('grid-measured', "
+            "'grid-placed'). Empty when the caller supplied it outright."
+        ),
+    )
+
+
+class GuideBeatBodyV1(BodyBase):
+    """One measured beat. The time is the reference's point interval."""
+
+    index: int = Field(
+        ..., description="Position in the measured beat sequence, 0-based."
+    )
+
+
+register_body_schema(PASS_BODY_SCHEMA_URI, GuidePassBodyV1)
+register_body_schema(GRID_BODY_SCHEMA_URI, GuideGridBodyV1)
+register_body_schema(BEAT_BODY_SCHEMA_URI, GuideBeatBodyV1)