lacing 0.0.2__tar.gz

lacing-0.0.2/.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Edit(/.claude/skills/lacing-architecture/**)",
+      "Edit(/.claude/skills/lacing-time-and-intervals/**)",
+      "Edit(/.claude/skills/lacing-adapter-authoring/**)"
+    ],
+    "additionalDirectories": [
+      "/Users/thorwhalen/Dropbox/py/proj/t/lacing/.claude/skills"
+    ]
+  }
+}

lacing-0.0.2/.claude/skills/lacing-adapter-authoring/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: lacing-adapter-authoring
+description: Use when adding, modifying, or reviewing an I/O format adapter for lacing — Praat TextGrid, ELAN EAF, WebVTT, JAMS, Label Studio JSON, W3C Web Annotation, OpenTimelineIO, CoNLL, brat standoff, SubRip, TTML, CSV, or any new format. Triggers on "add a … adapter", "import/export … format", "support … in lacing", "round-trip … format", or any work under lacing/adapters/. Encodes the plugin contract, the round-trip test pattern, license-checking the underlying parser, schema URI conventions, and the common pitfalls (offset invalidation, rate mismatch, lossy round-trips).
+---
+
+# Lacing — Adapter Authoring
+
+Format support in lacing is **plugin-only**. The core never imports a format
+module. Each adapter is a small, independent file in `lacing/adapters/` that
+registers itself.
+
+## The plugin contract
+
+Every adapter exposes two functions and one registration call. The exact
+signature is fixed by [lacing/adapters/__init__.py](../../../lacing/adapters/__init__.py):
+
+```python
+# lacing/adapters/<format>.py
+import os
+from lacing.adapters import register_adapter
+from lacing.store import IntervalAnnotationStore, MemoryStore
+
+ADAPTER_NAME = "textgrid"
+BODY_SCHEMA_URI = "annot://schema/textgrid-label/v1"
+
+def load(
+    source: str | bytes | os.PathLike,
+    *,
+    rate: int = DEFAULT_RATE,
+    asset_id: str = "...",
+    attribution: str = "anonymous",
+    **kwargs,
+) -> IntervalAnnotationStore:
+    """Parse `source` into an in-memory store."""
+    ...
+
+def dump(
+    store: IntervalAnnotationStore,
+    target: str | os.PathLike | None = None,
+    **kwargs,
+) -> bytes | None:
+    """Serialize `store`. If `target` is None, return bytes; else write to target."""
+    ...
+
+register_adapter(
+    name=ADAPTER_NAME,
+    load=load,
+    dump=dump,
+    extensions=(".TextGrid",),                 # tuple, lowercased on register
+    media_types=("text/x-praat-textgrid",),     # tuple
+    body_schema_uris=(BODY_SCHEMA_URI,),        # tuple — adapters may emit multiple
+    description="...",
+)
+```
+
+Notes on the surface:
+- `register_adapter` is keyword-only and returns the `AdapterSpec`.
+- `body_schema_uris` is **plural / tuple** — adapters may produce multiple
+  body shapes (e.g. cue + chapter schemas).
+- `extensions` may be passed with or without leading dots; they're
+  normalized to lowercase with leading dot in the registry.
+- Use `register_adapter` (the registry, not direct imports) so users can
+  swap or add formats without touching core.
+
+## Round-trip is the acceptance test
+
+Every adapter ships with a round-trip test:
+
+```python
+# tests/adapters/test_<format>.py
+def test_roundtrip_<format>(sample_file):
+    store1 = load(sample_file)
+    blob = dump(store1)
+    store2 = load(blob)
+    assert_stores_equivalent(store1, store2)
+```
+
+`assert_stores_equivalent` compares **annotations modulo provenance
+timestamps and IDs**, not byte-equality. Some formats are lossy by design
+(WebVTT loses tier metadata). Document each lossy edge in the adapter
+docstring with what gets dropped.
+
+## Body schema URI
+
+Every adapter declares one or more `body_schema_uri` values it produces.
+
+- Format: `annot://schema/<name>/v<major>`.
+- Bumps are **additive-only** by default. Breaking change → new major + a
+  registered migration in `lacing/schema.py`.
+- The URI travels with each annotation; the validator picks the right Zod /
+  Pydantic schema by URI.
+
+## License-check the parser before you depend on it
+
+Before adding a parser library, check ANN-DOC §E or look up the package on
+PyPI. **Never bring in:**
+
+| Banned | Why | Use instead |
+|--------|-----|-------------|
+| `praat-parselmouth` | GPLv3+ | `praatio` (MIT) |
+| `aeneas` | AGPL v3 | Montreal Forced Aligner (MIT) or write a thin parser |
+| `portion` | LGPLv3 | `intervaltree` (Apache-2.0) |
+| Peaks.js | LGPL-3.0 | wavesurfer.js v7 (BSD-3) |
+| anything LGPL/GPL/AGPL/BSL | viral / commercial trap | find MIT/BSD/Apache equivalent or write a small parser |
+
+If the only library is non-MIT/BSD/Apache, **write the parser** — most
+annotation formats are XML/JSON/CSV with simple grammars (TextGrid is ~100
+lines, EAF is XML).
+
+## Time discipline at the parsing boundary
+
+Parsers receive floats from external formats. Convert immediately:
+
+```python
+def _to_rational(seconds: float | str, rate: int = 24000) -> RationalTime:
+    f = Fraction(seconds).limit_denominator(rate)
+    val = int(f * rate)
+    return RationalTime(value=val, rate=rate)
+```
+
+- Convert **once at the parse boundary**; everything internal is `RationalTime`.
+- If the source format guarantees integer ticks (MIDI PPQN, ELAN ms), use them directly — don't go through float.
+- Document the rate assumption in the adapter docstring.
+
+## Tier mapping
+
+Every format maps to lacing's ELAN tier stereotypes (Rule 6 in
+`lacing-architecture`). When the source format has no equivalent
+(WebVTT has flat tracks, no parent), pick `NONE` and document it.
+
+| Format | Stereotype map |
+|--------|----------------|
+| Praat TextGrid IntervalTier | `NONE` |
+| Praat TextGrid PointTier | `NONE` (point annotations) |
+| ELAN EAF parent tier | `NONE` |
+| ELAN EAF child with `Time_Subdivision` | `TIME_SUBDIVISION` |
+| ELAN EAF `Symbolic_Subdivision` | `SYMBOLIC_SUBDIVISION` |
+| ELAN EAF `Symbolic_Association` | `SYMBOLIC_ASSOCIATION` |
+| ELAN EAF `Included_In` | `INCLUDED_IN` |
+| WebVTT cues | `NONE` |
+| W3C Web Annotation | `NONE` (use `motivation` for tier semantics) |
+
+## Provenance on import
+
+Every imported annotation gets:
+
+```python
+Provenance(
+    was_generated_by=f"adapter:{adapter_name}",
+    was_attributed_to=kwargs.get("attribution", "anonymous"),
+    was_derived_from=[source_asset_id],   # content hash of the source file
+    generated_at_time=RationalTime.now(),
+    activity="import",
+)
+```
+
+If the source format encodes its own provenance (W3C Web Annotation has
+`creator` + `created`), preserve it under `was_derived_from` chain — don't
+overwrite.
+
+## Common pitfalls (catch in review)
+
+1. **Off-by-one on closed-vs-open intervals.** Praat is closed, lacing is half-open. Document the conversion.
+2. **Encoding assumptions.** TextGrid can be Latin-1 or UTF-8 with BOM. Always sniff.
+3. **Rate mismatch within a single file.** ELAN's `TIME_ORDER` defines named anchors with one rate; don't assume project rate.
+4. **String labels with embedded delimiters.** WebVTT cues with `-->` in the body. Use the format's escape rules, not naive split.
+5. **Empty intervals.** Some formats forbid `start == end`; lacing allows it. Document drop / convert.
+6. **Lossy round-trip not flagged.** If the format can't represent confidence/provenance, the adapter must say so in its docstring **and** in the dump return metadata.
+
+## Adapter checklist
+
+- [ ] `load` and `dump` signatures match the contract.
+- [ ] `register_adapter` called at module import.
+- [ ] License of any underlying parser is MIT/BSD/Apache.
+- [ ] All time conversions go through `_to_rational` at the boundary.
+- [ ] Tier stereotype mapping documented.
+- [ ] Provenance set with `was_generated_by="adapter:<name>"`.
+- [ ] Round-trip test on at least two real-world samples.
+- [ ] Lossy fields documented in module docstring.
+- [ ] `body_schema_uri` declared and registered.
+- [ ] No core imports leaked into the adapter (it depends on `lacing.model`, not the other way).
+
+## Adapter priority order (Phase 0 → Phase 1)
+
+Phase 0: **TextGrid, WebVTT, W3C Web Annotation JSON-LD** — *all three
+landed*. Three formats covering three audiences (linguistics, captions,
+web/scholarly).
+
+Phase 1: **ELAN EAF, JAMS, Label Studio JSON, OpenTimelineIO, CoNLL,
+brat standoff, SubRip, TTML, CSV.**
+
+Don't skip ahead — Phase 0 adapters validate the data model. If a Phase 0
+adapter exposes a model gap, fix the model before adding more adapters.
+
+## Examples to study
+
+The Phase 0/1 adapters are deliberately diverse and demonstrate the pattern:
+
+- [lacing/adapters/textgrid.py](../../../lacing/adapters/textgrid.py) — uses an external parser (`praatio`, MIT, optional install), maps both interval and point tiers, raises `ImportError` with the install hint when the extra is missing.
+- [lacing/adapters/webvtt.py](../../../lacing/adapters/webvtt.py) — pure-Python parser, no dependency. Flat cues, no tier hierarchy. Demonstrates the `from_string-or-from-path` source heuristic.
+- [lacing/adapters/web_annotation.py](../../../lacing/adapters/web_annotation.py) — JSON-LD, uses the standard `json` module. Demonstrates discriminated-union round-tripping and creator/provenance preservation.
+- [lacing/adapters/annot.py](../../../lacing/adapters/annot.py) — *lossless* SQLite-based portable file format. Demonstrates the `persistent=True` mode (returns a live `SqliteStore` instead of a `MemoryStore`) and the fast-copy path when the source is already a `SqliteStore`.
+- [lacing/adapters/eaf.py](../../../lacing/adapters/eaf.py) — ELAN EAF via `pympi-ling` (MIT, optional install). The first adapter that exercises the **tier hierarchy** end-to-end: maps EAF's `CONSTRAINTS` strings to lacing's four ELAN stereotypes verbatim, topo-sorts tiers on dump so parents are emitted before children, and pulls the first `MEDIA_DESCRIPTOR/MEDIA_URL` as the default `MediaRef.asset_id`.
+
+## Source pointers
+
+- Format catalogue and parser libraries: ANN-DOC §B, §E.
+- Adapter pattern as architecture: ANN-DOC §C ("non-negotiable"); OSS-DOC OTIO `SchemaDef`.
+- Provenance schema: ANN-DOC §C; BACK-DOC §4.5.
+- Round-trip test pattern: BACK-DOC §4.3.

lacing-0.0.2/.claude/skills/lacing-architecture/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: lacing-architecture
+description: Use when starting any non-trivial work on the lacing package — adding modules, designing APIs, choosing dependencies, planning a new feature, or making architectural decisions. Triggers on tasks like "implement X in lacing", "design the Y component", "add support for Z format", "where should this code go", or any edit under lacing/, lacing-server/, or lacing-ui/. Loads the ten non-negotiables, the package decomposition, and pointers to the design docs.
+---
+
+# Lacing Architecture Primer
+
+`lacing` is a **standoff, interval-keyed annotation system** with a Python
+backend and a TypeScript/React frontend sharing one schema-versioned model.
+
+## Always read first
+
+1. **[misc/docs/Lacing Development Roadmap.md](../../../misc/docs/Lacing%20Development%20Roadmap.md)** — phased plan, cross-referenced to design docs.
+2. The four design docs in [misc/docs/](../../../misc/docs/):
+   - **ANN-DOC** — `Annotation systems - formats, algorithms, architectures, and tooling.md`
+   - **BACK-DOC** — `Backend Architecture for Time-Interval Annotation Systems.md`
+   - **FRONT-DOC** — `Frontend UI for Multitrack Time-Interval Annotation Editors.md`
+   - **OSS-DOC** — `Open-Source Codebase Deep-Dive ...md`
+
+If the roadmap and a design doc disagree, **the design doc wins** — fix the roadmap.
+
+## The ten non-negotiables
+
+| # | Rule | Source |
+|---|------|--------|
+| 1 | **Time is `RationalTime(value: int, rate: int)`.** Never floats anywhere — wire, storage, UI. Wire as `{v, r}`; Python `fractions.Fraction`; TS `bigint` pair. | OSS-DOC OTIO; BACK-DOC §2.1 |
+| 2 | **Standoff annotations only.** Source media immutable; annotations reference by `(asset_id, interval)`. | ANN-DOC §C |
+| 3 | **One `Annotation` envelope, typed body.** Single shape, `body: dict` validated by `body_schema_uri` (semver). No polymorphic class hierarchy. | BACK-DOC §2.1 |
+| 4 | **Indexes:** `intervaltree` in memory; PostgreSQL `tstzrange` + GiST when persistent; SQLite + R*Tree for `.annot` files. | ANN-DOC §C; BACK-DOC §3.1, §4.2 |
+| 5 | **Public API is a `MutableMapping[TimeInterval, list[Annotation]]` facade** with Allen-relation methods (`intersects`, `during`, `meets`, …). Implemented as a `Protocol` (Python 3.12 forbids `Protocol` inheriting from a non-Protocol ABC); concrete backends like `MemoryStore` implement the full mapping interface structurally. | ANN-DOC §C; BACK-DOC §4.1 |
+| 6 | **ELAN tier stereotypes verbatim:** `NONE`, `TIME_SUBDIVISION`, `INCLUDED_IN`, `SYMBOLIC_SUBDIVISION`, `SYMBOLIC_ASSOCIATION`. | ANN-DOC §C; OSS-DOC tier-2.4 |
+| 7 | **Adapter pattern for I/O.** Core never imports a format module. Every format is a registered plugin. | ANN-DOC §C ("non-negotiable") |
+| 8 | **PROV-O provenance inline on every annotation.** `was_generated_by`, `was_derived_from`, `was_attributed_to`, `generated_at_time`. AI annotations carry `agent:<model>@<hash>`. | ANN-DOC §C; BACK-DOC §4.5 |
+| 9 | **Pydantic v2 → JSON Schema → Zod codegen.** One SoT, two languages. Use `datamodel-code-generator` + `json-schema-to-zod`. | BACK-DOC §6 |
+| 10 | **License hygiene: MIT/BSD/Apache only.** No LGPL, GPL, AGPL, BSL. Banned: `portion`, `praat-parselmouth`, `aeneas`, Peaks.js, Etro, `@theatre/studio`, Remotion. | ANN-DOC §E; FRONT-DOC §1.8; OSS-DOC tier-3 |
+
+## Package layout
+
+`lacing` (this repo) is the **core lib only** — no server, no UI, no infra.
+Server and UI live in sibling repos so the data model can be adopted alone.
+
+```
+lacing/                    ← THIS REPO: core library
+├── lacing/
+│   ├── time.py           RationalTime, TimeInterval
+│   ├── model.py          Annotation, Reference, Provenance
+│   ├── tier.py           Tier + 5 ELAN stereotypes
+│   ├── allen.py          13 Allen relations + composition
+│   ├── store/
+│   │   ├── base.py       IntervalAnnotationStore facade
+│   │   ├── memory.py     intervaltree-backed (Phase 0, done)
+│   │   ├── sqlite.py     .annot file format + persistent backend (Phase 1, done)
+│   │   └── postgres.py   int8range + GiST + per-tier EXCLUDE (Phase 1, done)
+│   ├── adapters/         plugin-registered I/O
+│   │   ├── textgrid.py        Praat (Phase 0, done)
+│   │   ├── webvtt.py          captions (Phase 0, done)
+│   │   ├── web_annotation.py  W3C JSON-LD (Phase 0, done)
+│   │   ├── annot.py           .annot SQLite (Phase 1, done)
+│   │   └── eaf.py             ELAN EAF (Phase 1, done)
+│   ├── cli.py            argh-based CLI (Phase 1, done)
+│   ├── quality.py        IAA: kappa, Krippendorff α, IoU, DER (Phase 0, done)
+│   └── schema.py         body_schema registry; JSON Schema export (TODO)
+└── misc/docs/            design docs + roadmap
+
+lacing-server/  ← sibling repo (FastAPI + Arq + MCP + Yjs bridge)
+lacing-ui/      ← sibling repo (React + zustand + wavesurfer + dnd-timeline)
+```
+
+## Phase awareness
+
+When asked to implement something, identify which phase from the roadmap:
+
+- **Phase 0** — Core: time, model, store, Allen relations, three adapters (TextGrid, WebVTT, W3C), quality metrics. **Done.**
+- **Phase 1** — Persistence (SQLite/Postgres) + more adapters + CLI. **Mostly done:** `SqliteStore` + `.annot` file format adapter, ELAN EAF adapter, **`PostgresStore` with `int8range`/GiST/per-tier EXCLUDE**, and `lacing` CLI (`convert`, `query`, `validate`, `list-formats`) are in. **Remaining:** more adapters (JAMS, Label Studio JSON, OTIO, CoNLL, brat, SubRip, TTML, CSV) and `schema.py` (body-schema registry + JSON Schema export).
+- **Phase 2** — FastAPI server + Arq workers + MCP + OpenTelemetry.
+- **Phase 3** — Frontend MVP (waveform + dialogue tier + viseme tier + monitor + inspector).
+- **Phase 4** — Yjs awareness, then full collab; WebCodecs; tier view.
+- **Phase 5** — Differentiators (full Allen API, soft labels, generator timing, MCP-native).
+
+If a request leapfrogs phases (e.g. "let's add Yjs collab" while Phase 1 isn't done), surface that and confirm before proceeding.
+
+## Module sizing rules
+
+- Helper used by ONE function → inner function.
+- Helper within SAME module → `_` prefix.
+- Helper used across modules → no prefix.
+- Prefer functional style; OOP only for facades/orchestrators.
+- Keyword-only after the 3rd argument; from the 2nd if it improves readability.
+- No magic numbers — externalize as kwargs with smart defaults.
+
+## When in doubt
+
+- If a decision touches **time or intervals**, also load `lacing-time-and-intervals`.
+- If you're **adding/modifying a format adapter**, load `lacing-adapter-authoring`.
+- If you're **changing the data model or schemas**, load `lacing-schema-codegen`.
+- If you're choosing a **dependency**, run the license through the rule-10 banlist before adding.
+- If you're tempted to add a custom interval CRDT — don't. BACK-DOC §4.4 explicitly says compose Yjs primitives, custom code count = zero.

lacing-0.0.2/.claude/skills/lacing-schema-codegen/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: lacing-schema-codegen
+description: Use when modifying lacing's data model, body schemas, or the Pydantic→JSON-Schema→Zod codegen pipeline. Triggers on edits to lacing/model.py, lacing/schema.py, lacing/tier.py, body_schema_uri, schema migrations, schema versioning, or anything in lacing-ui/packages/core/ that mirrors a Python type. Encodes the single-source-of-truth rule (Pydantic v2 is SoT), the additive-by-default versioning rule, the migration-registration pattern, and the codegen wiring (`datamodel-code-generator` + `json-schema-to-zod`).
+---
+
+# Lacing — Schema Codegen and Versioning
+
+The Python `Annotation` model is the **single source of truth**. JSON Schema
+is generated from it. Zod schemas are generated from the JSON Schema. The
+TypeScript frontend never hand-writes types that mirror Python.
+
+## The pipeline
+
+```
+lacing/model.py            (Pydantic v2 — single source of truth)
+        │
+        │  pydantic.BaseModel.model_json_schema()
+        ▼
+lacing/schema/<name>/v<N>.json    (JSON Schema artifacts, committed)
+        │
+        ├─►  Python validation: Pydantic at runtime (server boundary)
+        │
+        └─►  TypeScript codegen:
+                json-schema-to-zod  →  lacing-ui/packages/core/zod/<name>.ts
+                                       (Zod schema, committed)
+                                       │
+                                       └─►  z.infer<typeof S>  for TS types
+```
+
+Why **commit the generated artifacts** in JSON Schema and Zod:
+- Diffs become readable in PRs.
+- Frontend can build without running Python.
+- Schema migrations have clear before/after.
+
+## Where each piece lives
+
+| Concern | Location |
+|---------|----------|
+| Annotation envelope (`Annotation`, `Reference`, `Provenance`) | `lacing/model.py` |
+| Tier types + 5 ELAN stereotypes | `lacing/tier.py` |
+| Body schemas (per-domain payloads — phoneme, viseme, named-entity, etc.) | `lacing/bodies/<name>.py` |
+| Body schema registry | `lacing/schema.py` |
+| JSON Schema artifacts (committed) | `lacing/schema/<name>/v<N>.json` |
+| Zod artifacts (committed) | `lacing-ui/packages/core/zod/<name>.ts` |
+| Migrations | `lacing/migrations/<name>/v<N>_to_v<N+1>.py` |
+
+## body_schema_uri convention
+
+Every annotation's `body` is validated by the schema named in `body_schema_uri`:
+
+```
+annot://schema/<name>/v<major>
+```
+
+- `name` is `kebab-case`, matches the body file: `annot://schema/named-entity/v1` ↔ `lacing/bodies/named_entity.py`.
+- Only the **major** version is in the URI. Minor/patch bumps must remain backward-compatible.
+- The URI is part of every annotation's wire format. Validators look up the schema by URI.
+
+## Versioning: additive by default
+
+**Allowed without a major bump:**
+- Add an *optional* field with a sensible default.
+- Add a value to a string-enum-like field — but only if consumers ignore unknown values gracefully (document this contract per body).
+- Tighten a docstring or description.
+
+**Requires a major bump + migration:**
+- Remove or rename a field.
+- Change a field's type.
+- Make an optional field required.
+- Tighten a constraint (regex, range) that would invalidate existing data.
+- Change semantic meaning of an existing field.
+
+## Migration registration
+
+Every major bump ships a migration:
+
+```python
+# lacing/migrations/named_entity/v1_to_v2.py
+from lacing.schema import register_migration
+
+@register_migration(
+    schema_name="named-entity",
+    from_version=1,
+    to_version=2,
+)
+def upgrade(body: dict) -> dict:
+    """v1 used `type`; v2 renames it to `entity_type` and adds optional `confidence`."""
+    return {
+        **{k: v for k, v in body.items() if k != "type"},
+        "entity_type": body["type"],
+    }
+```
+
+- Migrations are **forward-only** by convention. If you need a downgrade, register it explicitly as a separate migration.
+- Migrations run lazily on read OR eagerly during a registered batch operation. Don't write code that assumes one or the other.
+- Every migration has a unit test with a v(N) sample → v(N+1) expected output.
+
+## The Pydantic v2 patterns we use
+
+```python
+from pydantic import BaseModel, Field, model_validator
+
+class NamedEntityBody(BaseModel):
+    """Body for named-entity annotations.
+
+    body_schema_uri: annot://schema/named-entity/v1
+    """
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    entity_type: str = Field(..., description="ENTITY type (PER, ORG, LOC, ...)")
+    text: str = Field(..., description="Surface form")
+    confidence: float | None = Field(None, ge=0.0, le=1.0)
+```
+
+- `model_config = {"frozen": True}` — annotations are immutable; replace, don't mutate.
+- `"extra": "forbid"` — unknown fields are an error, not silently accepted (catches typos and stale clients).
+- Use `Field(..., description=...)` — descriptions land in JSON Schema and Zod, then in the auto-generated Inspector form (FRONT-DOC §6.3).
+- Prefer `| None` over `Optional[...]` (Python 3.10+).
+- Validation logic via `@model_validator(mode="after")`, never side effects.
+
+## Codegen invocation
+
+The exact tooling (per BACK-DOC §6):
+
+```bash
+# Step 1: Pydantic → JSON Schema
+python -m lacing.schema.export --out lacing/schema/
+
+# Step 2: JSON Schema → Zod
+npx json-schema-to-zod -i lacing/schema/named-entity/v1.json -o lacing-ui/packages/core/zod/named-entity.ts
+```
+
+Wire this into a single `make codegen` (or equivalent) target. Both
+artifacts are committed. CI verifies they're up to date by re-running
+codegen and diffing.
+
+## The boundary between envelope and body
+
+```
+Annotation                       ← envelope: id, tier, reference, body, body_schema_uri, provenance
+   └── body: dict                ← validated by the schema at body_schema_uri
+       └── (NamedEntityBody, PhonemeBody, ChordBody, ...)
+```
+
+- The **envelope** is one model in `lacing/model.py`, single version, evolves rarely.
+- **Bodies** are many small models in `lacing/bodies/`, each with its own version.
+- Don't put domain fields in the envelope. Don't put generic fields in the body.
+- If a field needs to be queryable across all annotations (e.g., `confidence`, `author`), it goes in the envelope or in `Provenance`. If it's domain-specific (`pitch_hz`, `speaker_id`), it goes in the body.
+
+## Inspector form generation
+
+The frontend Inspector auto-generates a form from each body's Zod schema
+(FRONT-DOC §6.3) using `react-hook-form` + `@hookform/resolvers/zod`.
+
+- Field types come from JSON Schema → Zod.
+- Field labels come from the Pydantic `Field(..., description=...)`.
+- This is why descriptions matter — they're not just docs, they're UX strings.
+
+## Frontend mirrors of envelope-level types
+
+`RationalTime`, `TimeInterval`, `Reference`, `Provenance`, the 5 tier
+stereotypes — these are codegened. **Don't hand-write TS versions.** A
+hand-written TS type that drifts from Python is the #1 codegen failure mode.
+
+## Checklist before merging a model change
+
+- [ ] Is this additive (no version bump) or breaking (major bump + migration)?
+- [ ] If breaking: migration written and tested?
+- [ ] `body_schema_uri` follows `annot://schema/<name>/v<major>` exactly.
+- [ ] `model_config = {"frozen": True, "extra": "forbid"}` set.
+- [ ] All `Field(...)` have descriptions (these become Inspector labels).
+- [ ] JSON Schema regenerated and committed.
+- [ ] Zod regenerated and committed.
+- [ ] If envelope changed, frontend store/selectors checked for breakage.
+- [ ] No envelope ↔ body field bleed (queryable cross-cutting fields stay in envelope; domain fields stay in body).
+
+## Source pointers
+
+- Pydantic v2 model definitions: BACK-DOC §2.1, §4.1.
+- JSON-Schema-to-Zod codegen tooling: BACK-DOC §6 (`datamodel-code-generator` + `json-schema-to-zod`).
+- Schema versioning + additive-only default: ANN-DOC §C "Schema versioning"; BACK-DOC §4.5.
+- Inspector form auto-generation: FRONT-DOC §6.3 `AnnotationLayerSpec<T>`.
+- Migration as a registered processor: BACK-DOC §4.5.

lacing-0.0.2/.claude/skills/lacing-time-and-intervals/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: lacing-time-and-intervals
+description: Use when writing or reviewing any code in the lacing project that touches time, intervals, durations, rates, frame numbers, sample positions, timestamps, or interval queries. Triggers on `RationalTime`, `TimeInterval`, `fractions.Fraction`, `intervaltree`, Allen relations (overlap/during/meets/before), interval boundaries, half-open ranges, snapping, or any conversion between seconds/ticks/frames/samples. Catches the most common landmines: float drift, closed-vs-open boundaries, mixed rates, and ad-hoc overlap predicates.
+---
+
+# Lacing — Time and Intervals
+
+Time correctness is the #1 source of subtle bugs in annotation systems. All
+four design docs converge on the same rules. Follow them or annotations
+silently desync over long timelines.
+
+## Rule 1 — Time is rational, never float
+
+```python
+from fractions import Fraction
+from dataclasses import dataclass
+
+@dataclass(frozen=True, slots=True)
+class RationalTime:
+    value: int      # numerator
+    rate: int = 24000   # denominator (ticks per second)
+
+    def to_fraction(self) -> Fraction:
+        return Fraction(self.value, self.rate)
+
+    def to_seconds(self) -> float:
+        # ONLY for display / external systems that demand float
+        return self.value / self.rate
+```
+
+- **Default rate: 24000.** LCM 1008000 if you need exact representation of all common video rates simultaneously.
+- **Wire format:** `{"v": int, "r": int}`. TS mirrors with `bigint`.
+- Use `fractions.Fraction` for arithmetic. `float` only at the *very* edge (display, third-party libs that demand it).
+- `to_seconds()` returns float **for display only.** Never round-trip through it.
+
+**Banned patterns:**
+- `time_in_seconds: float` anywhere in the model, wire, or storage layer.
+- `start + duration` where any operand is a float.
+- `time1 == time2` on floats — use `Fraction` equality.
+
+## Rule 2 — Intervals are half-open `[start, end)`
+
+```python
+@dataclass(frozen=True, slots=True)
+class TimeInterval:
+    start: RationalTime
+    end: RationalTime  # exclusive
+
+    @property
+    def is_point(self) -> bool:
+        return self.start == self.end  # zero-length = point annotation
+```
+
+- `start <= end` always. `start == end` is a **valid point annotation**, not a degenerate case.
+- Match OTIO's `end_time_exclusive` naming. If you ever expose `end_time_inclusive`, name it explicitly.
+- Two intervals with identical bounds are **equal**, not "touching."
+
+## Rule 3 — Mixed rates: convert, don't compare
+
+Two `RationalTime`s with different rates are comparable via `Fraction`, but
+**adding/subtracting them across rates is a smell**. Either:
+- Keep one canonical rate per project, OR
+- Convert explicitly at the boundary via `t.to_rate(new_rate)` and document the rate.
+
+The actual implementation is in `lacing.time`:
+- `RationalTime.from_seconds(value, rate=...)` accepts `int | float | str | Fraction` and raises `LossyTimeConversionError` if the value can't be exactly represented at `rate`. Use **strings** for ingest from text formats (`"0.001"` is exact; `0.001` isn't).
+- `RationalTime.to_rate(new_rate)` raises `LossyTimeConversionError` on loss — never rounds silently.
+- `__add__` / `__sub__` operate on `Fraction` then quantize back at `self.rate`. They raise `LossyTimeConversionError` if the sum isn't exact at that rate. **This is stricter than you might expect** — adding `Fraction(1,3)` to a rate-2 `RationalTime` raises rather than rounding.
+
+Lossy conversion always raises, never rounds.
+
+## Rule 4 — Allen's 13 relations are the public predicate API
+
+Don't write ad-hoc `if a.start < b.end and b.start < a.end:` predicates.
+Use the registered Allen relations (in `lacing/allen.py`):
+
+| Relation | Symbol | Predicate |
+|----------|--------|-----------|
+| `before` | `<`   | `a.end < b.start` |
+| `after`  | `>`   | `a.start > b.end` |
+| `meets`  | `m`   | `a.end == b.start` |
+| `met_by` | `mi`  | `a.start == b.end` |
+| `overlaps` | `o` | `a.start < b.start < a.end < b.end` |
+| `overlapped_by` | `oi` | (mirror) |
+| `starts` | `s`   | `a.start == b.start and a.end < b.end` |
+| `started_by` | `si` | (mirror) |
+| `during` | `d`   | `a.start > b.start and a.end < b.end` |
+| `contains` | `di` | (mirror) |
+| `finishes` | `f` | `a.start > b.start and a.end == b.end` |
+| `finished_by` | `fi` | (mirror) |
+| `equals` | `=`   | `a.start == b.start and a.end == b.end` |
+
+For "any kind of overlap" use the disjunction `overlaps | overlapped_by | during | contains | starts | started_by | finishes | finished_by | equals` — exposed as `intersects(a, b)`. Don't reinvent it.
+
+## Rule 5 — Use the right index for the query
+
+| Query shape | In-memory | Persistent |
+|-------------|-----------|------------|
+| Point query / overlap with a single interval | `intervaltree.IntervalTree` (Apache-2.0) | `PostgresStore` (`int8range` + GiST) or `SqliteStore` (R*Tree, embedded) |
+| Aggregate over fixed range (count, sum) | segment tree with lazy propagation | PostgreSQL with materialized view |
+| Many concurrent reads, append-mostly writes | `intervaltree` is fine | GiST |
+| Bulk batch analytics | `pyranges` v1 (Rust/Polars) | Parquet/Arrow IPC export |
+| Embedded / single-file | n/a | SQLite + R*Tree (`.annot` format) |
+| Multi-dim (time × channel) | `rtree` (libspatialindex) | composite GiST |
+
+**Banned:** `portion` (LGPL-3.0). Use `intervaltree` for in-memory work.
+
+## Rule 6 — UI and storage layers can use different units
+
+The frontend doc allows **integer microseconds** at the UI layer for
+arithmetic speed, but **only**:
+- Convert at the wire boundary (`RationalTime ↔ µs`).
+- Reject non-exact conversions (raise on lossy).
+- Document the unit on every UI variable name (`pos_us`, `dur_us`).
+
+The Python model never speaks microseconds. It speaks `RationalTime`.
+
+## Rule 7 — Snapping is rate-aware
+
+Snap targets (playhead, in/out points, clip edges, markers, grid) are all
+`RationalTime`. Snapping logic stays in `Fraction` arithmetic. **Never**
+snap by rounding floats.
+
+## Quick checklist before commit
+
+- [ ] No `float` in any signature/field except display layers and external library bridges.
+- [ ] Every `TimeInterval` is half-open; point intervals (`start == end`) handled.
+- [ ] Overlap/containment predicates go through `lacing/allen.py`, not ad-hoc.
+- [ ] Any rate conversion has an explicit lossy-→-raise path.
+- [ ] No `portion` import (LGPL).
+- [ ] In-memory store uses `intervaltree`; persistent goes through `PostgresStore` (`int8range`/GiST) or `SqliteStore` (R*Tree).
+
+## Source pointers
+
+- Concrete Pydantic models: BACK-DOC §2.1.
+- Algorithm choices and complexity: ANN-DOC §C–D.
+- 13 relations + ORD-Horn tractable subalgebra: ANN-DOC §A.
+- UI µs convention: FRONT-DOC §3 "Time representation".
+- OTIO `RationalTime` parity: OSS-DOC OTIO section.

lacing-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation