@mengine/medeo-client 1.0.1-alpha.2 → 1.1.0

package/dist/{document-DgffKwRw.js → document-C98vSu7J.js}

@@ -1,7 +1,6 @@
 import { Mirror, schema } from "loro-mirror";
 import { z } from "zod";
 import { LoroDoc } from "loro-crdt";
-import { produce } from "immer";
 //#region src/client/base64.ts
 function bytesToBase64(bytes) {
 	let binary = "";
@@ -536,7 +535,12 @@ function cascadeAfterVideoClipChanges(doc, makeEmptyPart) {
 function solveVideoDocument(document) {
 	const doc = videoDocumentToTimelineDoc(document);
 	let counter = 0;
-	cascadeAfterVideoClipChanges(doc, () => ({ partId: `empty_${counter++}` }));
+	const derivedFillerPartIds = /* @__PURE__ */ new Set();
+	cascadeAfterVideoClipChanges(doc, () => {
+		const partId = `empty_${counter++}`;
+		derivedFillerPartIds.add(partId);
+		return { partId };
+	});
 	const absByPartId = /* @__PURE__ */ new Map();
 	for (const item of doc.main_track) absByPartId.set(item.part_id, item.abs_time_position);
 	for (const item of doc.speech_track) absByPartId.set(item.part_id, item.abs_time_position);
@@ -552,7 +556,8 @@ function solveVideoDocument(document) {
 			}))
 		})),
 		durationMs: doc.timeline.duration_ms,
-		partLibrary: doc.part_library
+		partLibrary: doc.part_library,
+		derivedFillerPartIds
 	};
 }
 function videoDocumentToTimelineDoc(document) {
@@ -643,6 +648,42 @@ function seedAggregations(mainItems, speechItems) {
 	return order.map((host) => byHost.get(host));
 }
 /**
+* The four lanes in top-to-bottom stack order — the order a `tracks` list holds
+* them in (see {@link laneRank}).
+*
+* Exported so a document can be seeded with all four lanes up front. That seed is
+* not cosmetic: {@link ensureLaneTrack} is find-then-mint over a `LoroMovableList`,
+* so two concurrent writers that each mint the same absent lane both keep their
+* row, and the merged document holds two tracks for one lane. For the main lane
+* that is fatal — `videoDocumentSchema` allows at most one `video_clip` track, so
+* the merged document stops being projectable at all, symmetrically on both
+* replicas. Pre-seeding every lane makes `ensureLaneTrack` always take its find
+* branch, which removes the race by construction rather than by detection.
+*
+* What closes the race is that a track with the lane's `parts_kind` EXISTS — the
+* lookup is by kind, not by id. So a seed is only safe if it covers every lane:
+* a partial seed leaves the uncovered lanes exactly as exposed as before.
+*/
+const LANE_KINDS_IN_STACK_ORDER = [
+	"caption",
+	"video_clip",
+	"speech",
+	"bgm"
+];
+/**
+* The conventional track id for a lane (`main_track`, `<kind>_track`). Shared by
+* the up-front seed and {@link ensureLaneTrack}'s lazy mint so a document's lane
+* ids do not depend on which of the two created the track.
+*
+* Ids are cosmetic to the merge itself — lane lookup goes by `parts_kind`, so
+* drifting them apart would not reopen the concurrent-mint race. They matter to
+* readers that address a lane by id (the FE editor's panes, fixtures), which is
+* why there is one convention rather than two.
+*/
+function laneTrackId(kind) {
+	return kind === "video_clip" ? "main_track" : `${kind}_track`;
+}
+/**
 * Lane-stacking rank for the single `tracks` list (reference/17 §4): caption
 * (above) sits before the video_clip main track, which sits before speech / bgm
 * (below). The `tracks` array is kept in this top-to-bottom order so a freshly
@@ -673,14 +714,18 @@ function insertTrackByLaneOrder(tracks, track) {
 * Locate a lane's track row in the single `tracks` list by kind, minting an empty
 * row in lane-stacking order if absent (reference/17 §4: lane = `parts_kind`).
 * Ops use this to write authoritative items onto the right lane. The track id
-* mirrors the seed convention (`<kind>_track`).
+* comes from {@link laneTrackId}, shared with the up-front seed.
+*
+* The mint branch is a concurrency hazard, not a convenience: see
+* {@link LANE_KINDS_IN_STACK_ORDER}. A document seeded with all four lanes never
+* reaches it.
 */
 function ensureLaneTrack(draft, kind) {
 	draft.tracks ??= [];
 	let track = draft.tracks.find((t) => t?.parts_kind === kind);
 	if (track == null) {
 		track = {
-			id: kind === "video_clip" ? "main_track" : `${kind}_track`,
+			id: laneTrackId(kind),
 			parts_kind: kind,
 			is_hidden: void 0,
 			items: []
@@ -876,11 +921,59 @@ function validateVideoDocument(document) {
 		validatePartValues(partId, part, issues);
 	}
 	for (const [idx, track] of (doc.tracks ?? []).entries()) validateTrack(track, `tracks/${idx}`, partLibrary, issues, track.parts_kind === "video_clip");
+	validateLaneTrackUniqueness(doc, issues);
 	validateSpeechCaptionReferences(partLibrary, issues);
 	validatePositionReferences(doc, partLibrary, issues);
 	return issues;
 }
 /**
+* Report a duplicated lane: two tracks sharing the same `id`, or two secondary
+* tracks of the same `parts_kind`.
+*
+* Found by the Phase 6 M0/S2 concurrency probe. `ensureLaneTrack` locates a lane
+* by `parts_kind` and mints `<kind>_track` when absent, so two replicas that both
+* start without (say) a caption track each create one; `tracks` is a
+* `LoroMovableList`, so the merge keeps BOTH. The lane is then split across two
+* same-id tracks, and the projection's `find`-by-kind returns only one of them —
+* so an item can be authoritative yet invisible in the pane a reader looks at.
+*
+* Flagged **recoverable**, not `error`, for two reasons. It is a reachable
+* outcome of ordinary concurrent editing, and hard-rejecting would make an
+* unavoidable merge result un-projectable — the same argument §11.1 makes for
+* orphans. And the projection already tolerates it: `solveVideoDocument`
+* concatenates every track of a kind, so the cascade sees all items regardless.
+* The defect is a *reader-visible* split, so the right response is to surface it
+* (loudly, in a channel someone reads), not to block the document.
+*
+* The main track is exempt from the kind check: `parts_kind === 'video_clip'` may
+* legitimately appear on several tracks (the projection treats only the first as
+* the main pane), so only its `id` collision is reported.
+*/
+function validateLaneTrackUniqueness(doc, issues) {
+	const tracks = doc.tracks ?? [];
+	const seenIds = /* @__PURE__ */ new Set();
+	const seenSecondaryKinds = /* @__PURE__ */ new Set();
+	for (const [idx, track] of tracks.entries()) {
+		const id = track?.id;
+		if (id != null && id !== "") if (seenIds.has(id)) issues.push({
+			code: "duplicate_lane_track",
+			path: `/tracks/${idx}/id`,
+			message: `Track "tracks/${idx}" reuses track id "${id}"`,
+			severity: "recoverable"
+		});
+		else seenIds.add(id);
+		const kind = track?.parts_kind;
+		if (kind == null || kind === "video_clip") continue;
+		if (seenSecondaryKinds.has(kind)) issues.push({
+			code: "duplicate_lane_track",
+			path: `/tracks/${idx}/parts_kind`,
+			message: `Lane "${kind}" is split across more than one track (at "tracks/${idx}")`,
+			severity: "recoverable"
+		});
+		else seenSecondaryKinds.add(kind);
+	}
+}
+/**
 * An `anchored` item whose `anchorPartId` no longer exists in the library is the
 * orphan condition (RFC 02 §4/§11.1) — e.g. a speech whose host video, or a
 * caption whose host speech, was concurrently deleted while this item was being
@@ -1102,7 +1195,7 @@ function toAuthoritativePartLibrary(partLibrary) {
 			const { duration_ms, rest } = splitDurationMs(part.caption);
 			out[partId] = { caption: {
 				...rest,
-				initial_duration_ms: duration_ms
+				initial_duration_ms: rest.initial_duration_ms ?? duration_ms
 			} };
 		} else if (part.bgm != null) out[partId] = { bgm: omitDurationMs(part.bgm) };
 	}
@@ -1209,7 +1302,7 @@ function fromVideoDocument(document) {
 		above_main_tracks: aboveTracks.map((t) => draftTrack(t, view.absByPartId)),
 		below_main_tracks: belowTracks.map((t) => draftTrack(t, view.absByPartId)),
 		part_aggregations: view.aggregations,
-		part_library: toReadViewPartLibrary(view.partLibrary, view.durationMs),
+		part_library: toReadViewPartLibrary(view.partLibrary, view.durationMs, view.derivedFillerPartIds),
 		version: document.meta.version
 	};
 }
@@ -1225,31 +1318,38 @@ function fromVideoDocument(document) {
 *
 * Parts are deep-cloned; the engine extensions (`media_duration_ms`,
 * `initial_duration_ms`) are kept alongside the injected `duration_ms`.
+*
+* `derivedFillerPartIds` are skipped: the solve minted them to lay the track out
+* and they are not part of the document (see `fromVideoDocument`). An empty clip a
+* writer placed deliberately is NOT in that set and is projected normally.
 */
-function toReadViewPartLibrary(partLibrary, durationMs) {
+function toReadViewPartLibrary(partLibrary, durationMs, derivedFillerPartIds) {
 	const out = {};
-	for (const [partId, part] of Object.entries(partLibrary)) if (part.video_clip != null) {
-		const clip = clone(part.video_clip);
-		out[partId] = { video_clip: {
-			...clip,
-			duration_ms: effectiveVideoClipDurationMs(clip)
-		} };
-	} else if (part.speech != null) {
-		const speech = clone(part.speech);
-		out[partId] = { speech: {
-			...speech,
-			duration_ms: speech.media_duration_ms
-		} };
-	} else if (part.caption != null) {
-		const caption = clone(part.caption);
-		out[partId] = { caption: {
-			...caption,
-			duration_ms: caption.initial_duration_ms
+	for (const [partId, part] of Object.entries(partLibrary)) {
+		if (derivedFillerPartIds.has(partId)) continue;
+		if (part.video_clip != null) {
+			const clip = clone(part.video_clip);
+			out[partId] = { video_clip: {
+				...clip,
+				duration_ms: effectiveVideoClipDurationMs(clip)
+			} };
+		} else if (part.speech != null) {
+			const speech = clone(part.speech);
+			out[partId] = { speech: {
+				...speech,
+				duration_ms: speech.media_duration_ms
+			} };
+		} else if (part.caption != null) {
+			const caption = clone(part.caption);
+			out[partId] = { caption: {
+				...caption,
+				duration_ms: caption.initial_duration_ms
+			} };
+		} else if (part.bgm != null) out[partId] = { bgm: {
+			...clone(part.bgm),
+			duration_ms: durationMs
 		} };
-	} else if (part.bgm != null) out[partId] = { bgm: {
-		...clone(part.bgm),
-		duration_ms: durationMs
-	} };
+	}
 	return out;
 }
 /** Deep-clone a part payload, dropping the derived read-view `duration_ms`. */
@@ -1307,6 +1407,57 @@ function clone(value) {
 	return value;
 }
 //#endregion
+//#region src/document/initial-document.ts
+/**
+* Build the `VideoDocument` a newly created project starts from: the caller's
+* project facts, no parts, and one empty track per lane.
+*
+* The empty lane tracks are the reason this function exists rather than callers
+* assembling a document inline. Lane tracks are otherwise minted lazily by the
+* first op that needs one (`ensureLaneTrack`), which is find-then-mint over a
+* CRDT list — so if the Agent's first generation and a user edit race on an
+* empty document, each mints its own copy of the same lane and the merge keeps
+* both. Two video_clip tracks violate the at-most-one-main-track rule, and the
+* merged document becomes unprojectable for *every* reader (editor, render,
+* share) with no winning replica to fall back on. Seeding all four lanes up
+* front means `ensureLaneTrack` only ever finds, never mints, so the race cannot
+* happen on a document created here.
+*
+* All four, not just the main lane: the secondary lanes fail less loudly (a
+* duplicate pane rather than an unreadable document), but they fail by the same
+* mechanism, and covering only the fatal one would leave three live races.
+*
+* `timeline` is left absent: `unit_time_ms` is a display concern the editor
+* supplies, and total duration is derived on read (RFC 02 §6), so a new document
+* has no timeline fact to state.
+*/
+function buildInitialVideoDocument(facts) {
+	return {
+		meta: {
+			schema_version: VIDEO_DOCUMENT_SCHEMA_VERSION,
+			draft_id: facts.draftId,
+			project_id: facts.projectId,
+			owner_id: facts.ownerId,
+			thumbnail_storage_key: void 0,
+			chat_session_id: facts.chatSessionId,
+			video_creation_settings: facts.videoCreationSettings,
+			version: void 0
+		},
+		timeline: void 0,
+		tracks: emptyLaneTracks(),
+		part_library: {}
+	};
+}
+/** One empty track per lane, in lane-stacking order, with the conventional ids. */
+function emptyLaneTracks() {
+	return LANE_KINDS_IN_STACK_ORDER.map((kind) => ({
+		id: laneTrackId(kind),
+		parts_kind: kind,
+		is_hidden: void 0,
+		items: []
+	}));
+}
+//#endregion
 //#region src/document/mirror-read.ts
 /**
 * Project the mirror state (`VideoDocumentDraft`) into the authoritative
@@ -1422,7 +1573,8 @@ var MirrorVideoDocumentAdapter = class {
 			message: JSON.stringify({
 				semantic_op: audit.kind,
 				payload: audit.payload,
-				intent: audit.intent ?? null
+				intent: audit.intent ?? null,
+				actor: audit.actor ?? null
 			})
 		});
 	}
@@ -1436,7 +1588,7 @@ function createMirrorVideoDocument(document, options = {}) {
 		doc,
 		schema: videoDocumentMirrorSchema
 	}).setState((draft) => {
-		writeVideoDocumentToDraft(draft, document);
+		seedDraft(draft, document);
 	}, { origin: options.origin ?? "mengine.bootstrap" });
 	return doc;
 }
@@ -1444,8 +1596,8 @@ function createMirrorVideoDocument(document, options = {}) {
 function createMirrorVideoDocumentAdapter(document, options) {
 	return new MirrorVideoDocumentAdapter(createMirrorVideoDocument(document, options));
 }
-/** Write a whole `VideoDocument` into a draft (seed a fresh doc / plain-memory state). */
-function writeVideoDocumentToDraft(draft, document) {
+/** Write a whole `VideoDocument` into the mirror draft (used to seed a fresh doc). */
+function seedDraft(draft, document) {
 	draft.meta = {
 		schema_version: document.meta.schema_version,
 		draft_id: document.meta.draft_id ?? void 0,
@@ -1475,119 +1627,4 @@ function toTrackRow(track) {
 	};
 }
 //#endregion
-//#region src/editor/id-gen.ts
-/**
-* Part-id generation, aligned with the online ecosystem.
-*
-* The authoritative online producers — agent-harness (`@harness/shared`
-* `genObjId`) and director.v2 (`common/obj_id.py` `gen_obj_id`) — both mint part
-* ids as `` `${prefix}_${ulid()}` ``, and real captured drafts use exactly that
-* shape (`clip_…` / `spe_…` / `cap_…` / `bgm_…`, each a 26-char ULID). The engine
-* previously emitted `vc_<base36 timestamp><6 random>`, a different prefix AND a
-* different encoding — the sole cross-repo id divergence. This module removes it
-* by emitting the same `<prefix>_<ULID>` bytes.
-*
-* The ULID is generated inline (Crockford Base32, 48-bit time + 80-bit random)
-* rather than pulling the `ulid` npm package: the randomness class matches the
-* old generator (both `Math.random`-based) and it keeps `@mengine/medeo-client`
-* dependency-free for a purely mechanical id string. Part ids only need to be
-* unique and lexicographically time-sortable, which this satisfies.
-*/
-/** Crockford Base32 alphabet (no I, L, O, U), per the ULID spec. */
-const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-const TIME_LEN = 10;
-const RANDOM_LEN = 16;
-function encodeTime(now) {
-	let out = "";
-	let ms = now;
-	for (let i = TIME_LEN - 1; i >= 0; i--) {
-		const mod = ms % 32;
-		out = CROCKFORD[mod] + out;
-		ms = (ms - mod) / 32;
-	}
-	return out;
-}
-function encodeRandom() {
-	let out = "";
-	for (let i = 0; i < RANDOM_LEN; i++) out += CROCKFORD[Math.floor(Math.random() * 32)];
-	return out;
-}
-/** A 26-char Crockford Base32 ULID (10-char time + 16-char random). */
-function ulid() {
-	return encodeTime(Date.now()) + encodeRandom();
-}
-function generatePartId(prefix) {
-	return `${prefix}_${ulid()}`;
-}
-//#endregion
-//#region src/document/plain-memory-adapter.ts
-/**
-* Pure in-memory `SemanticDocumentAdapter` — no Loro/WASM. Holds a
-* `VideoDocumentDraft` object and applies each `transact` via immer `produce`,
-* journaling every audit that actually mutated state (plus any ids minted
-* during that transact).
-*
-* Known benign difference vs `MirrorVideoDocumentAdapter`: the editor's
-* `setPart` assigns a fresh part object on every call, so a same-value rewrite
-* produces a new immer state and IS journaled here, while the mirror's deep
-* diff emits no commit. Terminal `snapshot()` stays equal; replay is idempotent.
-*/
-var PlainMemoryAdapter = class {
-	state;
-	_journal = [];
-	baseIdFactory;
-	/** Non-null only while a `transact` edit callback is running. */
-	pendingIds = null;
-	/**
-	* Recording wrapper around the underlying factory. Callers (sandbox editor)
-	* use this so every minted id is appended to the current transact's list.
-	*/
-	idFactory;
-	constructor(document, options) {
-		assertValidVideoDocument(document);
-		const draft = {};
-		writeVideoDocumentToDraft(draft, document);
-		this.state = draft;
-		this.baseIdFactory = options?.idFactory ?? generatePartId;
-		this.idFactory = (prefix) => {
-			const id = this.baseIdFactory(prefix);
-			if (this.pendingIds != null) this.pendingIds.push(id);
-			return id;
-		};
-	}
-	get journal() {
-		return this._journal;
-	}
-	hasContent() {
-		return (this.state.meta?.schema_version ?? "") !== "";
-	}
-	snapshot() {
-		return readVideoDocumentFromDraft(this.state);
-	}
-	/**
-	* Apply one op via immer. A throw in `edit` discards the draft (state and
-	* journal unchanged). When `produce` returns the same reference, there was
-	* no structural change — skip journal, matching mirror "no change, no commit".
-	*/
-	transact(edit, audit) {
-		this.pendingIds = [];
-		try {
-			const next = produce(this.state, edit);
-			if (next !== this.state) {
-				this.state = next;
-				this._journal.push({
-					...audit,
-					generated_ids: this.pendingIds
-				});
-			}
-		} finally {
-			this.pendingIds = null;
-		}
-	}
-};
-/** Build a `PlainMemoryAdapter` seeded with `document`. */
-function createPlainMemoryAdapter(document, options) {
-	return new PlainMemoryAdapter(document, options);
-}
-//#endregion
-export { isEmptyVideoClip as A, bytesToBase64 as B, fillMainTrackTimeGaps as C, resolveSpeechOverlapByShiftingVideos as D, resolveAllSpeechOverlaps as E, speedOf as F, partUnionToDraft as I, recordEntries as L, safeDurationMs as M, VIDEO_DOCUMENT_SCHEMA_VERSION as N, syncAggregatedClipsTimePosition as O, effectiveVideoClipDurationMs as P, videoDocumentMirrorSchema as R, arrangeMainTrackSeamlessly as S, recalculateTimelineDuration as T, videoDocumentSchema as _, createMirrorVideoDocument as a, solveVideoDocument as b, readVideoDocumentFromDraft as c, fromVideoDocument as d, toVideoDocument as f, partUnionSchema as g, validateVideoDocument as h, MirrorVideoDocumentAdapter as i, partDurationMs as j, TIMELINE_SKELETON_DURATION_MS as k, buildSpeechHostMap as l, assertValidVideoDocument as m, createPlainMemoryAdapter as n, createMirrorVideoDocumentAdapter as o, VideoDocumentValidationError as p, generatePartId as r, writeVideoDocumentToDraft as s, PlainMemoryAdapter as t, derivePositionFromAbs as u, ensureLaneTrack as v, reassignSpeechesToVideoClipsByTime as w, cascadeAfterVideoClipChanges as x, findLaneTrack as y, base64ToBytes as z };
+export { partDurationMs as A, reassignSpeechesToVideoClipsByTime as C, syncAggregatedClipsTimePosition as D, resolveSpeechOverlapByShiftingVideos as E, recordEntries as F, videoDocumentMirrorSchema as I, base64ToBytes as L, VIDEO_DOCUMENT_SCHEMA_VERSION as M, effectiveVideoClipDurationMs as N, TIMELINE_SKELETON_DURATION_MS as O, partUnionToDraft as P, bytesToBase64 as R, fillMainTrackTimeGaps as S, resolveAllSpeechOverlaps as T, findLaneTrack as _, buildInitialVideoDocument as a, cascadeAfterVideoClipChanges as b, fromVideoDocument as c, assertValidVideoDocument as d, validateVideoDocument as f, ensureLaneTrack as g, LANE_KINDS_IN_STACK_ORDER as h, readVideoDocumentFromDraft as i, safeDurationMs as j, isEmptyVideoClip as k, toVideoDocument as l, videoDocumentSchema as m, createMirrorVideoDocument as n, buildSpeechHostMap as o, partUnionSchema as p, createMirrorVideoDocumentAdapter as r, derivePositionFromAbs as s, MirrorVideoDocumentAdapter as t, VideoDocumentValidationError as u, laneTrackId as v, recalculateTimelineDuration as w, arrangeMainTrackSeamlessly as x, solveVideoDocument as y };