videobook 0.0.0-stage → 0.2.0

package/dist/media-library.js

@@ -0,0 +1,535 @@
+import { join } from "node:path";
+import { registerLocalClipSearchProvider } from "./local-search-models.js";
+import { enqueueTemporalSearchPreparation } from "./jobs/prepare-temporal-search.js";
+import { enqueueSearchIndex } from "./jobs/enqueue-search-index.js";
+import { missingVisualIndexes } from "./search-index-coverage.js";
+import { markDescendantsStale } from "./notebook-action-catalog.js";
+import { mutateNotebook } from "./notebook-mutations.js";
+import { searchReferenceStore } from "./search-reference-store.js";
+import { comparableHitScore } from "./search-scoring.js";
+import { buildAssetList } from "./tools/reconcile-project-work.js";
+import { assetRecency, readAssetUsage, recordAssetUse } from "./asset-usage.js";
+import { matchesTagFilter, tagFacetCounts, transferAssetTags, } from "./asset-tags.js";
+import { addStatusCounts, countBrowseStatuses, emptyStatusCounts, matchesBrowseStatus, pageLibraryAssets, } from "./library-browse.js";
+function isMediaCellType(value) {
+    return value === "audio" || value === "image" || value === "video";
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function compatibleArtifact(cell, artifact) {
+    if (cell.type === "video") {
+        return artifact.kind === "video" || artifact.kind === "final";
+    }
+    return cell.type === artifact.kind;
+}
+function assertMediaCell(document, cellId) {
+    const cell = document.cells.find((candidate) => candidate.id === cellId);
+    if (!cell)
+        throw new Error(`Cell not found: ${cellId}`);
+    if (!isMediaCellType(cell.type)) {
+        throw new Error("Only audio, image, and video cells can hold media slots");
+    }
+    return cell;
+}
+function withCellExecution(document, cellId, status) {
+    const currentExecution = document.execution ?? {};
+    const currentCell = isRecord(currentExecution[cellId])
+        ? currentExecution[cellId]
+        : {};
+    return {
+        ...document,
+        execution: {
+            ...currentExecution,
+            [cellId]: {
+                ...currentCell,
+                status,
+                stale: false,
+                error: undefined,
+            },
+        },
+    };
+}
+function bindMediaSlot(document, cellId, artifact) {
+    const cell = assertMediaCell(document, cellId);
+    if (artifact && !compatibleArtifact(cell, artifact)) {
+        throw new Error(`A ${cell.type} cell cannot use a ${artifact.kind} artifact`);
+    }
+    if (artifact
+        && document.edges.some((edge) => edge.target === cellId)) {
+        throw new Error("Clear connected inputs before attaching Library media");
+    }
+    const cells = document.cells.map((candidate) => {
+        if (candidate.id !== cellId)
+            return candidate;
+        return {
+            ...candidate,
+            outputArtifactId: artifact?.artifactId,
+            inputs: {
+                ...(candidate.inputs ?? {}),
+                state: artifact ? "completed" : "ready",
+            },
+        };
+    });
+    const edges = artifact
+        ? document.edges
+        : document.edges.filter((edge) => edge.target !== cellId);
+    return withCellExecution(markDescendantsStale({ ...document, cells, edges }, cellId), cellId, artifact ? "completed" : "ready");
+}
+export async function setNotebookMediaSlot(engine, input) {
+    if (input.expectedRevision
+        && input.expectedRevision !== engine.head) {
+        throw new Error(`Stale notebook revision: expected ${input.expectedRevision}`);
+    }
+    const artifact = input.artifactRef
+        ? engine.artifacts.get(input.artifactRef)
+        : null;
+    if (artifact && !artifact.ok)
+        throw new Error(artifact.error.message);
+    const resolved = artifact?.ok ? artifact.value : null;
+    const result = await mutateNotebook(engine, input.notebookId, resolved ? "set_notebook_media_slot" : "clear_notebook_media_slot", (notebook) => bindMediaSlot(notebook, input.cellId, resolved), {
+        cellId: input.cellId,
+        outputArtifactId: resolved?.artifactId ?? null,
+    });
+    if (!result.ok)
+        throw new Error(result.error.message);
+    if (resolved)
+        recordAssetUse(engine, resolved.artifactId);
+    return {
+        cellId: input.cellId,
+        outputArtifactId: resolved?.artifactId ?? null,
+        revision: result.value.hash,
+    };
+}
+function kindMatches(requested, kind) {
+    return requested.has(kind)
+        || (kind === "final" && requested.has("video"));
+}
+function searchRank(asset, query) {
+    if (!query)
+        return 3;
+    const label = asset.label?.toLowerCase() ?? "";
+    const book = asset.owning_book_name.toLowerCase();
+    const prompt = asset.prompt?.toLowerCase() ?? "";
+    if ((label && label === query) || book === query)
+        return 0;
+    if ((label && label.startsWith(query)) || book.startsWith(query))
+        return 1;
+    return prompt.startsWith(query) ? 2 : 3;
+}
+function matchesQuery(asset, query) {
+    if (!query)
+        return true;
+    return [
+        asset.id,
+        asset.label ?? "",
+        asset.owning_book_name,
+        asset.prompt ?? "",
+    ].some((value) => value.toLowerCase().includes(query));
+}
+function lastUsedAt(usedAt) {
+    return usedAt === undefined ? null : new Date(usedAt).toISOString();
+}
+function libraryAssetRecency(asset) {
+    const used = asset.last_used_at ? Date.parse(asset.last_used_at) : undefined;
+    return assetRecency(asset.created_at, used);
+}
+function compareRecentlyUsed(left, right) {
+    const recency = libraryAssetRecency(right) - libraryAssetRecency(left);
+    if (recency !== 0)
+        return recency;
+    const created = Date.parse(right.created_at) - Date.parse(left.created_at);
+    return created !== 0
+        ? created
+        : left.artifact_id.localeCompare(right.artifact_id);
+}
+export async function searchLibraryAssets(books, input) {
+    await books.ready();
+    const query = input.query?.trim().toLowerCase() ?? "";
+    const requested = new Set(input.kinds);
+    const prepared = input.referenceId
+        ? searchReferenceStore.get(input.referenceId).reference
+        : undefined;
+    const searching = Boolean(query || prepared);
+    const browseStatus = searching
+        ? "ready"
+        : (input.browseStatus ?? "ready");
+    const artifactKinds = [
+        ...(requested.has("audio") ? ["audio"] : []),
+        ...(requested.has("image") ? ["image"] : []),
+        ...(requested.has("video") ? ["video", "final"] : []),
+    ];
+    const summaries = books.list({ sort: "newest" });
+    const results = await Promise.allSettled(summaries.map(async (summary) => {
+        const book = books.get(summary.bookId);
+        if (!book.ok)
+            throw new Error(book.error.message);
+        const engine = book.value.engine;
+        const builtAssets = await engine.withLocalMedia(() => buildAssetList(engine, summary.bookId, "newest"));
+        const usage = readAssetUsage(engine);
+        const eligible = builtAssets
+            .filter((asset) => kindMatches(requested, asset.type)
+            && matchesTagFilter(asset.tags ?? undefined, input.tags))
+            .map((asset) => ({
+            ...asset,
+            owning_book_id: summary.bookId,
+            owning_book_name: summary.name,
+            last_used_at: lastUsedAt(usage.get(asset.artifact_id)),
+        }));
+        const statusCounts = countBrowseStatuses(eligible);
+        const readyAssets = eligible.filter((asset) => asset.status === "ready");
+        const assets = searching
+            ? readyAssets
+            : eligible.filter((asset) => matchesBrowseStatus(asset.status, browseStatus));
+        let hits = [];
+        let searchError;
+        let preparationJob;
+        if (searching) {
+            registerLocalClipSearchProvider(engine);
+            const searchQuery = {
+                ...(query ? { text: query } : {}),
+                modalities: query
+                    ? ["visual", "metadata"]
+                    : ["visual"],
+                artifactKinds,
+                sourceArtifactIds: readyAssets.map((asset) => asset.artifact_id),
+                limit: 100,
+            };
+            const result = prepared
+                ? await engine.temporalSearch.queryPrepared(searchQuery, prepared, input.referenceRange ? { range: input.referenceRange } : {})
+                : await engine.temporalSearch.query(searchQuery);
+            if (result.ok) {
+                hits = result.value.hits;
+            }
+            else if (result.error.code === "NOT_READY" && result.error.details?.requiresIndexPreparation) {
+                preparationJob = await enqueueTemporalSearchPreparation(summary.bookId);
+            }
+            else {
+                searchError = result.error.message;
+            }
+        }
+        return {
+            assets,
+            statusCounts,
+            hits,
+            searchError,
+            preparationJob,
+            unindexed: missingVisualIndexes(engine, readyAssets).length,
+        };
+    }));
+    const errors = [];
+    const assets = [];
+    let statusCounts = emptyStatusCounts();
+    const semanticHits = [];
+    results.forEach((result, index) => {
+        if (result.status === "fulfilled") {
+            assets.push(...result.value.assets);
+            statusCounts = addStatusCounts(statusCounts, result.value.statusCounts);
+            semanticHits.push(...result.value.hits.map((hit) => ({
+                key: `${summaries[index]?.bookId ?? "unknown"}:${hit.artifactId}`,
+                hit,
+            })));
+            if (result.value.searchError) {
+                errors.push({
+                    book_id: summaries[index]?.bookId ?? "unknown",
+                    message: result.value.searchError,
+                });
+            }
+            return;
+        }
+        const book = summaries[index];
+        errors.push({
+            book_id: book?.bookId ?? "unknown",
+            message: result.reason instanceof Error
+                ? result.reason.message
+                : String(result.reason),
+        });
+    });
+    const metadataRank = new Map(assets
+        .filter((asset) => !prepared && matchesQuery(asset, query))
+        .sort((left, right) => {
+        const rank = searchRank(left, query) - searchRank(right, query);
+        if (rank !== 0)
+            return rank;
+        const created = Date.parse(right.created_at) - Date.parse(left.created_at);
+        return created !== 0
+            ? created
+            : left.artifact_id.localeCompare(right.artifact_id);
+    })
+        .map((asset, index) => [
+        `${asset.owning_book_id}:${asset.artifact_id}`,
+        index + 1,
+    ]));
+    semanticHits.sort((left, right) => comparableHitScore(right.hit) - comparableHitScore(left.hit)
+        || left.key.localeCompare(right.key));
+    const semanticRank = new Map();
+    const semanticMatch = new Map();
+    for (const item of semanticHits) {
+        if (semanticRank.has(item.key))
+            continue;
+        semanticRank.set(item.key, semanticRank.size + 1);
+        semanticMatch.set(item.key, item.hit);
+    }
+    const ranked = assets
+        .flatMap((asset) => {
+        const key = `${asset.owning_book_id}:${asset.artifact_id}`;
+        const metadata = metadataRank.get(key);
+        const semantic = semanticRank.get(key);
+        if ((query || prepared) && metadata === undefined && semantic === undefined) {
+            return [];
+        }
+        const hit = semanticMatch.get(key);
+        return [{
+                asset: hit
+                    ? {
+                        ...asset,
+                        search_match: {
+                            score: comparableHitScore(hit),
+                            location: hit.location,
+                        },
+                    }
+                    : asset,
+                score: (metadata === undefined ? 0 : 1 / (60 + metadata))
+                    + (semantic === undefined ? 0 : 1 / (60 + semantic)),
+            }];
+    })
+        .sort((left, right) => {
+        const rank = right.score - left.score;
+        if (rank !== 0)
+            return rank;
+        const created = Date.parse(right.asset.created_at) - Date.parse(left.asset.created_at);
+        return created !== 0
+            ? created
+            : left.asset.artifact_id.localeCompare(right.asset.artifact_id);
+    })
+        .map((item) => item.asset);
+    if (!query && !prepared)
+        ranked.sort(compareRecentlyUsed);
+    const paged = pageLibraryAssets(ranked, {
+        offset: input.offset ?? 0,
+        limit: input.limit ?? 50,
+    });
+    return {
+        assets: paged.pageAssets,
+        tag_facets: tagFacetCounts(ranked),
+        unindexed_visual_assets: results.reduce((count, result) => count + (result.status === "fulfilled" ? result.value.unindexed : 0), 0),
+        preparationJobs: results.flatMap((result) => result.status === "fulfilled" && result.value.preparationJob
+            ? [result.value.preparationJob]
+            : []),
+        page: paged.page,
+        status_counts: statusCounts,
+        books_with_errors: errors,
+    };
+}
+export async function resolveBookReference(books, reference) {
+    await books.ready();
+    const byId = books.get(reference);
+    if (byId.ok)
+        return byId.value;
+    const byName = books.getByName(reference);
+    if (byName.ok)
+        return byName.value;
+    throw new Error(`Book not found: ${reference}`);
+}
+function copyableFile(name) {
+    return !name.endsWith(".part")
+        && !name.endsWith(".tmp")
+        && name !== "error.json"
+        && !name.endsWith("/error.json");
+}
+async function copyArtifactFiles(source, target, sourceArtifact, targetArtifact) {
+    const sourceManifest = await source.files.manifest(sourceArtifact.artifactId, { includeDotfiles: true });
+    if (!sourceManifest.ok)
+        throw new Error(sourceManifest.error.message);
+    const files = sourceManifest.value.files.filter((file) => copyableFile(file.name));
+    for (const file of files) {
+        const sourcePath = join(sourceManifest.value.path, ...file.name.split("/"));
+        const written = await target.files.writeFromPath(targetArtifact.artifactId, file.name, sourcePath);
+        if (!written.ok)
+            throw new Error(written.error.message);
+    }
+    const targetManifest = await target.files.manifest(targetArtifact.artifactId, { includeDotfiles: true });
+    if (!targetManifest.ok)
+        throw new Error(targetManifest.error.message);
+    const targetHashes = new Map(targetManifest.value.files.map((file) => [file.name, file.objectHash]));
+    for (const file of files) {
+        if (targetHashes.get(file.name) !== file.objectHash) {
+            throw new Error(`Copied file hash mismatch: ${file.name}`);
+        }
+    }
+}
+async function copyArtifactMetadata(source, target, sourceArtifact, targetArtifact, sourceBookId) {
+    const original = await source.metadata.artifacts.read(sourceArtifact.artifactId, "original");
+    const metadata = {
+        ...(original.ok ? original.value : {}),
+        origin: "library-copy",
+        source_book_id: sourceBookId,
+        source_artifact_id: sourceArtifact.artifactId,
+    };
+    const written = await target.metadata.artifacts.write(targetArtifact.artifactId, "original", metadata);
+    if (!written.ok)
+        throw new Error(written.error.message);
+    const waveform = await source.metadata.waveforms.read(sourceArtifact.artifactId);
+    if (waveform.ok) {
+        const waveformWrite = await target.metadata.waveforms.write(targetArtifact.artifactId, waveform.value.peaks);
+        if (!waveformWrite.ok)
+            throw new Error(waveformWrite.error.message);
+    }
+    const streams = source.streams.list(sourceArtifact.artifactId);
+    if (!streams.ok)
+        throw new Error(streams.error.message);
+    const manifest = await target.files.manifest(targetArtifact.artifactId);
+    if (!manifest.ok)
+        throw new Error(manifest.error.message);
+    const copiedHashes = new Map(manifest.value.files.map((file) => [file.name, file.objectHash]));
+    for (const stream of streams.value) {
+        if (copiedHashes.get(stream.sourcePath) !== stream.objectHash)
+            continue;
+        const registered = await target.streams.register({
+            artifactId: targetArtifact.artifactId,
+            sourcePath: stream.sourcePath,
+            objectHash: stream.objectHash,
+            streamIndex: stream.streamIndex,
+            kind: stream.kind,
+            timeBase: stream.timeBase,
+            durationTicks: stream.durationTicks,
+            codec: stream.codec,
+            ...(stream.video ? { video: stream.video } : {}),
+            ...(stream.audio ? { audio: stream.audio } : {}),
+        });
+        if (!registered.ok)
+            throw new Error(registered.error.message);
+    }
+}
+async function deleteCopiedArtifact(engine, artifactId) {
+    const deleted = await engine.artifacts.delete(artifactId, { deleteOwnedMedia: true });
+    return deleted.ok ? null : deleted.error.message;
+}
+export async function copyLibraryAsset(books, input) {
+    if (input.sourceBookId === input.targetBookId) {
+        throw new Error("Source and target books must be different");
+    }
+    const sourceBook = await resolveBookReference(books, input.sourceBookId);
+    const targetBook = await resolveBookReference(books, input.targetBookId);
+    if (sourceBook.bookId === targetBook.bookId) {
+        throw new Error("Source and target books must be different");
+    }
+    const sourceArtifactResult = sourceBook.engine.artifacts.get(input.sourceArtifactId);
+    if (!sourceArtifactResult.ok) {
+        throw new Error(sourceArtifactResult.error.message);
+    }
+    const sourceArtifact = sourceArtifactResult.value;
+    if (sourceArtifact.kind !== "audio"
+        && sourceArtifact.kind !== "image"
+        && sourceArtifact.kind !== "video"
+        && sourceArtifact.kind !== "final") {
+        throw new Error(`Artifact kind is not reusable media: ${sourceArtifact.kind}`);
+    }
+    const targetKind = sourceArtifact.kind === "final"
+        ? "video"
+        : sourceArtifact.kind;
+    const label = input.newName ?? sourceArtifact.label;
+    const created = await targetBook.engine.artifacts.create({
+        kind: targetKind,
+        ...(label ? { label } : {}),
+    });
+    if (!created.ok)
+        throw new Error(created.error.message);
+    const targetArtifact = created.value;
+    let lease = null;
+    try {
+        await copyArtifactFiles(sourceBook.engine, targetBook.engine, sourceArtifact, targetArtifact);
+        await copyArtifactMetadata(sourceBook.engine, targetBook.engine, sourceArtifact, targetArtifact, sourceBook.bookId);
+        // After the bytes, so the destination engine can validate the source's
+        // automatic evidence against the content the copy actually carries.
+        await transferAssetTags({ engine: sourceBook.engine, artifactId: sourceArtifact.artifactId }, { engine: targetBook.engine, artifactId: targetArtifact.artifactId });
+        lease = targetBook.engine.jobs.artifactWork.begin(targetArtifact.artifactId, {
+            kind: "upload",
+            ownerKind: "job",
+            durationMs: 15 * 60_000,
+        });
+        if (!lease) {
+            throw new Error("Could not claim the copied Library artifact");
+        }
+        if (!targetBook.engine.jobs.artifactWork.complete(targetArtifact.artifactId, lease.ownerId)) {
+            throw new Error("Could not complete the copied Library artifact");
+        }
+        await enqueueSearchIndex(targetBook.engine, targetArtifact.artifactId);
+        return {
+            sourceBookId: sourceBook.bookId,
+            sourceArtifactId: sourceArtifact.artifactId,
+            targetBookId: targetBook.bookId,
+            targetArtifactId: targetArtifact.artifactId,
+        };
+    }
+    catch (cause) {
+        if (lease) {
+            await targetBook.engine.jobs.artifactWork.fail(targetArtifact.artifactId, lease.ownerId, {
+                message: cause instanceof Error ? cause.message : String(cause),
+            });
+        }
+        const cleanupError = await deleteCopiedArtifact(targetBook.engine, targetArtifact.artifactId);
+        const message = cause instanceof Error ? cause.message : String(cause);
+        throw new Error(cleanupError
+            ? `${message}; orphan ${targetArtifact.artifactId}: ${cleanupError}`
+            : message);
+    }
+}
+function assertAttachableCell(document, input, artifact) {
+    const cell = assertMediaCell(document, input.cellId);
+    const currentOutput = cell.outputArtifactId ?? null;
+    if (currentOutput !== input.expectedOutputArtifactId) {
+        throw new Error("The media slot changed while the Library asset was copying");
+    }
+    if (document.edges.some((edge) => edge.target === input.cellId)) {
+        throw new Error("The media slot was connected while the Library asset was copying");
+    }
+    if (!compatibleArtifact(cell, artifact)) {
+        throw new Error(`A ${cell.type} cell cannot use a ${artifact.kind} artifact`);
+    }
+}
+export async function copyAndAttachLibraryAsset(books, input) {
+    const sourceBook = await resolveBookReference(books, input.sourceBookId);
+    const targetBook = await resolveBookReference(books, input.targetBookId);
+    const sourceArtifact = sourceBook.engine.artifacts.get(input.sourceArtifactId);
+    if (!sourceArtifact.ok)
+        throw new Error(sourceArtifact.error.message);
+    const before = targetBook.engine.notebooks.read(input.notebookId);
+    if (!before.ok)
+        throw new Error(before.error.message);
+    assertAttachableCell(before.value, input, sourceArtifact.value);
+    const copied = await copyLibraryAsset(books, input);
+    const targetArtifact = targetBook.engine.artifacts.get(copied.targetArtifactId);
+    if (!targetArtifact.ok) {
+        await deleteCopiedArtifact(targetBook.engine, copied.targetArtifactId);
+        throw new Error(targetArtifact.error.message);
+    }
+    try {
+        const result = await mutateNotebook(targetBook.engine, input.notebookId, "attach_library_asset", (notebook) => {
+            assertAttachableCell(notebook, input, targetArtifact.value);
+            return bindMediaSlot(notebook, input.cellId, targetArtifact.value);
+        }, {
+            sourceBookId: copied.sourceBookId,
+            sourceArtifactId: copied.sourceArtifactId,
+            targetArtifactId: copied.targetArtifactId,
+            cellId: input.cellId,
+        });
+        if (!result.ok)
+            throw new Error(result.error.message);
+        recordAssetUse(sourceBook.engine, copied.sourceArtifactId);
+        recordAssetUse(targetBook.engine, copied.targetArtifactId);
+        return {
+            ...copied,
+            notebookId: input.notebookId,
+            cellId: input.cellId,
+            revision: result.value.hash,
+        };
+    }
+    catch (cause) {
+        const cleanupError = await deleteCopiedArtifact(targetBook.engine, copied.targetArtifactId);
+        const message = cause instanceof Error ? cause.message : String(cause);
+        throw new Error(cleanupError
+            ? `${message}; orphan ${copied.targetArtifactId}: ${cleanupError}`
+            : message);
+    }
+}

package/dist/media-output-path.js

@@ -0,0 +1,33 @@
+import { extname } from "node:path";
+import { normalizeFilePath } from "videobook-engine";
+export async function withMediaOutputLock(engine, assetDir, signal, fn) {
+    signal.throwIfAborted();
+    const lock = await engine.jobs.locks.acquire(assetDir, { durationMs: 120_000 });
+    if (!lock.ok)
+        throw new Error(`Asset is locked: ${lock.error.message}`);
+    try {
+        signal.throwIfAborted();
+        return await fn();
+    }
+    finally {
+        engine.jobs.locks.release(assetDir, lock.value.ownerId);
+    }
+}
+export async function validateMediaOutputPaths(engine, assetId, filenames, extension) {
+    const paths = filenames.map(normalizeFilePath);
+    const manifest = await engine.files.manifest(assetId, { includeDotfiles: true });
+    if (!manifest.ok)
+        throw new Error(`Destination asset ${assetId} not found: ${manifest.error.message}`);
+    const occupied = new Set(manifest.value.files.map((file) => file.name.normalize("NFC").toLowerCase()));
+    for (const filename of paths) {
+        const key = filename.normalize("NFC").toLowerCase();
+        if ([...occupied].some((existing) => existing === key || existing.startsWith(`${key}/`) || key.startsWith(`${existing}/`))) {
+            throw new Error(`Destination already contains ${filename} or a conflicting path. Refusing silent overwrite.`);
+        }
+        if (extname(filename).toLowerCase() !== extension) {
+            throw new Error(`Destination filename must end in ${extension}: ${filename}`);
+        }
+        occupied.add(key);
+    }
+    return paths;
+}