Give the AI four minutes at a time, from one shared document (source)

The decision

To keep the editing of long videos manageable for an AI, I set a working scale of roughly five minutes per step. The specification refined it into four-minute segments that are views of one editable project document. The segment map describes context; it is not another editable timeline.

The cost is more planner calls and segmentation logic, in exchange for never merging separate editable documents. The code makes a practical compromise: prefer meaningful boundaries, but keep the size bound when none is available.

From the source

The design at a glance:

Concern	Recorded choice
Editable state	One `EditProject`; derived segments can be recomputed.
Normal target	Four minutes; nominal bounds of two to five minutes.
Continuity	Ten seconds of neighboring context plus shared direction.
Missing semantic boundary	Use the bounded clock fallback.
Final remainder	Permit a shorter tail rather than exceed the maximum.

Architecture specification. The rejected alternative and its cost are explicit:

D1
Segments are derived, not authored, and the timeline stays whole
EditSegment { index, startMs, endMs, title, summary, firstWordId, lastWordId } computed from the transcript + scene list; stored as a cache column (segments jsonb, segments_hash text) invalidated when the source, transcript or clip order changes
A second editable structure (per-segment documents) would need merge logic, undo across segments and a render that stitches them — Spec 161 D1's whole-composition rule applied to editing. A derived map can always be recomputed; an authored one drifts

Segment planner. When no sentence or scene boundary falls inside the bounds, the segment ends at the clock maximum:

    const inRange = candidates.filter((c) => c.atMs > minMs && c.atMs <= maxMs);
    const pick =
      inRange.length > 0
        ? inRange.reduce((best, c) =>
            Math.abs(c.atMs - targetMs) < Math.abs(best.atMs - targetMs)
              ? c
              : best,
          )
        : null;

    const endMs = pick ? pick.atMs : maxMs;

Segment planner. The final tail is deliberately allowed to be shorter:

   * Whatever is left is one segment, and the loop condition guarantees it is at
   * most SEGMENT_MAX_MS. It can be SHORTER than the minimum, and that is
   * correct: a 40-second tail merged into its neighbour would push that
   * neighbour past the maximum, and the maximum is the constraint that exists
   * to keep a turn manageable. D2's "merge a short segment with its neighbour"
   * applies to interior segments, which this walk never produces.

What this shows

A limit on how much the AI sees at once turned into a single-document design with explicit edge cases: sentence and scene boundaries are a preference inside a hard size limit. The four-minute target is a design choice, not a measured optimum.