@mengine/medeo-client 2.1.1-dsl.2 → 2.1.1-dsl.3

package/README.md

@@ -83,13 +83,13 @@ dsl.dispose();
 
 ### Interface and invariants
 
-- `getSnapshot()` returns a frozen, read-only `MedeoDslSnapshot`: entity and relation tables, effective containment, rich-text runs, resolved Caption text and diagnostics. It does not compute layout or VideoDraft. Reads reuse the same snapshot until a DSL content event invalidates it; no-op Actions and repeated imports retain it. Reading never commits changes.
+- `getSnapshot()` returns a frozen, read-only `MedeoDslSnapshot`: entity tables, the voice-timbre and derived-from relation tables, effective containment, rich-text runs, resolved Caption text and diagnostics. A relation an entity holds at most one of is a field of its row: a Clip's `source` and `anchor`, a Caption's `selection`, a PhoneticScript's `phoneme`. An unreadable optional field is dropped from the row with a diagnostic; the row stays. A Caption's own text wins over its selection when a merge leaves both. It does not compute layout or VideoDraft. Reads reuse the same snapshot until a DSL content event invalidates it; no-op Actions and repeated imports retain it. Reading never commits changes.
 - `subscribe(listener)` includes text-only and marks-only changes. The returned function unsubscribes; dispose is idempotent. As with other synchronous document observers, listeners should not throw or initiate nested writes.
 - `applyMutations(mutations, audit)` is the preferred interface for typed entity, relation, Tree, Text and Caption-selection commands. It opens one `transact`; `tx.applyMutations` inside an existing callback uses the same draft and commit.
 - `transact(edit, audit)` exposes a guarded `tx.draft` for ordinary fields and Tree, `tx.editText(scriptId, edits, expectedBodyId?)`, `tx.editCaptionText(captionId, edits, expectedBodyId?)`, and `tx.setCaptionContent({captionId, audioScriptId, start, end})`. The synchronous callback and every draft reference expire on return. Async callbacks, nested writes, identity changes, direct overwrites of existing bodies, and same-transaction entity deletion/recreation are rejected. Catching a guard/command error inside the callback does not allow a partial commit.
 - `editText(scriptId, expectedBodyId, edits, audit)` delegates to the same transaction. Text supports insert/delete/mark/unmark/editing Delta; offsets are UTF-16 and cannot split surrogate pairs. `tx.draft` exposes the text preview after preceding edits, while existing body strings are never sent through Mirror's full-text diff. A supplied body identity must match the current Text; Actions editing an existing body retain that stale-view check.
-- Caption selections are interpreted at their position in the command sequence. Their Cursors are created after earlier native edits, and follow later edits. New selections are deferred commands, not synthetic Cursor values in `tx.draft`; do not read that relation table to retrieve a pending selection. Explicit Cursor relation writes and deletes also replay in sequence with Text edits.
-- `textRange(scriptId, start, end)` returns native Cursors for a nonempty continuous selection. Caption content stores their native bytes through the central codec. The permanent first-boundary limitation remains deferred.
+- Caption selections are interpreted at their position in the command sequence. Their Cursors are created after earlier native edits, and follow later edits. New selections are deferred commands, not synthetic Cursor values in `tx.draft`; do not read a Caption's `selection` from the draft to retrieve a pending one. Explicit Cursor values written to `selection`, and its removal, also replay in sequence with Text edits.
+- `textRange(scriptId, start, end)` returns native Cursors for a nonempty continuous selection. A Caption's `selection` stores their native bytes through the central codec. The permanent first-boundary limitation remains deferred.
 
 Every business write requires a structured `DslAudit`: `{semantic_op, payload, intent?, actor?}`. The transaction exit serializes the existing server envelope exactly once; initialization alone uses an internal unaudited path. No-op transactions add no history. External pending native operations must be committed separately first. Known preparation failures write nothing; unexpected native/runtime failures do not receive database-style rollback.