lacing.bodies.review#

Body schema for review notes — the edit-loop’s communication channel.

URI: annot://schema/review/v1

A review annotation is a structured note attached to one or more artifacts (a panel, a beat, a segmentation alternate, a render result), optionally pointing at a typed payload like a ContinuityViolationBodyV1. Reviews are produced by:

  • automated checkers (continuity, grammar, timing, segmentation rules)

  • the edit-loop (“this caption needs a revision”)

  • the orchestrator (“the user declined the cost gate at panel 12”)

  • the user (“approve” / “needs revision” notes)

The body is intentionally minimal. The kind (review_kind) routes the FE renderer; the payload is opaque to lacing.

An approval review carries a decision — this is the record lacing.server.operations.accept_ai_suggestion() writes when a human accepts or rejects an AI suggestion, so that the human’s edit is attributed to the human without overwriting the agent’s provenance on the annotation being judged (lacing#18).

Note

decision is additive and optional, so stored bodies validate unchanged and lacing owes no migration. Downstream mirrors of this schema are a different matter: reelee-web’s generated Zod type is .strict() and its JSON Schema is additionalProperties: false, so an additive field here is a breaking change there until the mirror is regenerated — tracked as thorwhalen/reelee-web#234.

References

  • reelee/docs/Narrative to Storyboard.md §6.5–6.6.

  • reelee/docs/reelee 03 -- Human-AI Collaboration UX Patterns… §10 (annotation overlays).

Module Attributes

ReviewKind

What flavor of review this is.

ReviewStatus

Open is the initial state; the others are user / agent resolutions.

Author

Coarse author classification.

ReviewDecision

The verdict an approval review carries.

Classes

ReviewBodyV1(**data)

Body of a review annotation.
lacing.bodies.review.Author#

Coarse author classification. The annotation envelope’s was_attributed_to carries the specific identity; this field is the quick chip for the FE.

alias of Literal[‘human’, ‘agent’, ‘system’]

class lacing.bodies.review.ReviewBodyV1(**data)[source]#

Bases: SchemaModel

Body of a review annotation.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

lacing.bodies.review.ReviewDecision#

The verdict an approval review carries. Only review_kind = "approval" reviews have one — a continuity or grammar note is an observation, not a ruling, so decision stays None there.

Why this is a field rather than something to read off the reviewed annotation’s confidence: the verdict is a fact about *the review event*, and confidence is a mutable field on a different record that the next write can move. Recovering “was this accepted?” by dereferencing a live value is exactly the coupling that made lacing#18 possible.

alias of Literal[‘accepted’, ‘rejected’]

lacing.bodies.review.ReviewKind#

What flavor of review this is. Drives the FE’s renderer choice and the producing-Transform’s routing logic.

alias of Literal[‘continuity’, ‘segmentation’, ‘prompt’, ‘grammar’, ‘timing’, ‘iconic_moment’, ‘manual’, ‘approval’]

lacing.bodies.review.ReviewStatus#

Open is the initial state; the others are user / agent resolutions.

alias of Literal[‘open’, ‘addressed’, ‘wont_fix’, ‘deferred’]