wyuc fcb464bdf0
fix(dsl): migrate away legacy rotate/height fields on line elements (#1261)
* fix(dsl): strip legacy rotate/height from line elements on migration and import (#1260)

* fix(dsl): cover whiteboard slides in the legacy line strip, drop redundant import wiring

Round-1 review findings (#1261): the strip only walked
scenes[*].content.canvas.elements, leaving the same bug class latent on
interactive whiteboard slides (scenes[*].whiteboards[*].elements); and the
import-site sanitize was redundant because the document store already runs
the ladder on save, while its comment misdescribed that mechanism. Extend
the strip to whiteboards and let the ladder alone own the cleanup.

* fix(dsl): cover stage-level whiteboard boards and row envelopes in the legacy line strip

Round-2 terminal audit findings (#1261): the strip walked only the
document envelope's scene surfaces, so dirty line elements under
stage.whiteboard (the stage-level explainer boards) and under bare
Scene/Stage row envelopes passed through while the runner stamped the
document current. Walk every line-element surface of every migratable
envelope: scene canvas, scene whiteboards, and stage whiteboard, at
document, Scene-row, and Stage-row roots.

* fix(dsl): gate the canvas strip on the slide discriminant; run the ladder on legacy-only exports

Round-3 terminal audit findings (#1261): the canvas walk fired on any
canvas-shaped content regardless of the scene kind, so a non-slide scene
carrying a canvas-shaped app extension would have fields deleted from it
— gate on content.type ('slide' or absent, the dirty-line epoch predates
schema enforcement). And the lock-free exportDatabase fallback
hand-stamped DSL_VERSION onto a payload the ladder never walked, so a
backup could read as current on restore and permanently skip the
migration — build the export unstamped and let migrate stamp it.

* fix(agent-runtime): bring stale-stamped documents current before incremental scene writes

Round-4 audit finding (#1261): putScene rejects documents whose stored
DSL stamp is older than the current one, and the aggregate read migrates
in memory only, so the first server-side tool write into a course stored
at an older version (every pre-bump course, including previously
imported ones) failed with a version error. Route the server tools'
incremental scene writes through a wrapper whose not-current fallback
reloads the migrated aggregate and full-saves it with the scene spliced
in — the server-side counterpart of the app autosave's
catch-and-full-save.

* style: prettier

* docs(agent-runtime): record the reviewed concurrency window on the stale-stamp fallback
2026-08-28 14:06:03 +08:00

50 lines
2.4 KiB
TypeScript

import { DocumentVersionError, type DocumentStore } from '@openmaic/storage';
import type { Scene, Stage } from '@/lib/types/stage';
/**
* Incremental scene writes land only in already-current documents (see the
* `DocumentVersionError` guard in `putScene`): a stale stored stamp means the
* document's other scenes have not been lifted yet, and marking the whole
* document current off one scene write would strand them below the
* migrate-on-read line. A server tool hits that guard on its first write into
* a course stored at an older DSL version, because the aggregate read
* migrates in memory only — the stored stamp is still old.
*
* This wrapper is the server-side counterpart of the app autosave's
* catch-and-full-save: on `not-current`, reload the (already migrated)
* aggregate, splice the written scene in, and save the whole document, so the
* current stamp is earned by an actually-run migration instead of being
* asserted off one scene. Any other failure mode is rethrown untouched, and a
* document that vanished between the failed write and the reload rethrows the
* original error — nothing exists to bring current.
*
* Accepted limitation (reviewed in #1261): the fallback's reload → splice →
* save spans two transactions, so a writer committing another scene inside
* that window would be pruned by the snapshot save. Cross-session server
* writers are excluded by the per-stage lease; the remaining competitor is
* the browser autosave, which already replaces the whole document
* last-writer-wins (the system's pre-existing document-level concurrency
* model), and its data is periodic — the editor re-saves its live state on
* the next tick. The window is one-shot per document: once the stamp is
* current, every later write takes the `putScene` fast path.
*/
export async function putSceneBringingCurrent(
store: DocumentStore<Scene, Stage>,
stageId: string,
scene: Scene,
): Promise<void> {
try {
await store.putScene(stageId, scene);
return;
} catch (error) {
if (!(error instanceof DocumentVersionError) || error.kind !== 'not-current') throw error;
const doc = await store.loadDocument(stageId);
if (!doc) throw error;
const scenes = doc.scenes.filter((item) => item.id !== scene.id);
scenes.push(scene);
scenes.sort((a, b) => a.order - b.order);
await store.saveDocument({ ...doc, scenes });
}
}