paces 0.0.10__tar.gz → 0.0.12__tar.gz

{paces-0.0.10 → paces-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.10
+Version: 0.0.12
 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.10 → paces-0.0.12}/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.10 → paces-0.0.12}/docs/README.md

@@ -13,7 +13,7 @@ a dance, plus a hand-written HTML aide-mémoire, plus a paragraph of steering pr
 deployed interactive practice page: <https://thorwhalen.com/que_calor_dance/>.
 
 The user now wants that generalised into a library, integrated with the **reelee** /
-`video_gen` fleet. Your job is to research, design and build it. **This folder exists so you
+`av` (formerly `video_gen`) fleet. Your job is to research, design and build it. **This folder exists so you
 do not start from scratch.** It records what was built, the parameters that were expensive to
 find, the failures and what each one teaches, the user's own framing of the generalisation,
 and an inventory of what already exists in the fleet.
@@ -28,7 +28,7 @@ Nothing here is a design you must follow. It is evidence and framing. Argue with
 | 2 | **`03-design-brief.md`** | The user's own framing: the parse→AST→render metaphor they explicitly asked to have recorded, the three generalisation axes, and the constraints the POC discovered. |
 | 3 | **`04-reelee-core.md`** | What reelee is, what a reelee "genre" is, and what to reuse. **This determines the package boundary**, so read it before deciding anything structural. |
 | 4 | **`07-annotation-model.md`** | The proposed shape of the AST — the contract between analysis and rendering. |
-| 5 | **`05-fleet-inventory.md`** | What already exists across `video_gen`, and honestly which parts are stubs. |
+| 5 | **`05-fleet-inventory.md`** | What already exists across `av`, and honestly which parts are stubs. |
 | 6 | **`02-technical-recipes.md`** | Every technique with working parameters. Reference, not narrative — come back to it when implementing. |
 | 7 | **`06-surfaces-and-conventions.md`** | House style: architecture-first seams, qh, py2mcp, storage, frontend, deploy. |
 | 8 | **`08-naming-candidates.md`** | PyPI-verified name options, and a better word for the "subject" axis. |
@@ -37,7 +37,7 @@ Nothing here is a design you must follow. It is evidence and framing. Argue with
 | — | **`adr/`** | The decisions. **`0003` `video + segmenter`** — read it before designing the analysis phase. `0002` the name. `0001` the alignment engine (intent) — note that much of what you'd otherwise build already exists in `muvid`, `mixing` and `kodokan`. |
 | — | **`alignment/`** | The research behind that ADR: one file per method family, prepared so you don't start from a literature search. |
 | — | **`KICKOFF.md`** | A paste-ready prompt to start a fresh session on this. |
-| — | **`REGISTRATION.md`** | **One command still pending** to register `paces` in the `video_gen` group, and why `priv pkg add-package` is deliberately deferred. |
+| — | **`REGISTRATION.md`** | **One command still pending** to register `paces` in the `av` group, and why `priv pkg add-package` is deliberately deferred. |
 | — | **`poc-reference/`** | The actual scripts and data. Read `poc-reference/README.md` first — several of those files are recorded dead ends. |
 
 ## The one-paragraph version

{paces-0.0.10 → paces-0.0.12}/docs/alignment/README.md

@@ -1,7 +1,7 @@
 # Alignment research
 
 *What this folder is for: preparation for a possible dedicated **alignment tool** in the
-`video_gen` / reelee fleet — the thing that answers "given some artifacts and some media,
+`av` (formerly `video_gen`) / reelee fleet — the thing that answers "given some artifacts and some media,
 which span of the media does each artifact correspond to?". The decision to build it is
 recorded as an intent in `../adr/0001-alignment-engine-as-a-fleet-package.md`; **read that
 first**, then come here for the method-by-method detail.*

{paces-0.0.10 → paces-0.0.12}/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.12/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.12/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.12/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.12/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)