videobook 0.0.0-stage → 0.2.0

package/dist/archive-store.js

@@ -0,0 +1,169 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { getEngineRoot } from "./queue.js";
+import { archiveKey, clipPrefix, createArchiveB2, getArchiveConfig, getJson, getText, listObjects, missingArchiveConfigKeys, objectExists, putJson, putText, uploadFileToB2, } from "./archive-b2.js";
+/**
+ * The global archive is outside every forkable book catalog. Its indexes and
+ * marker objects are derived from immutable media, transcript, and ingest
+ * objects; book-owned archive links remain canonical artifact metadata.
+ */
+export const ARCHIVE_STORE_BOUNDARY = {
+    role: "rebuildable-app-cache",
+    bookAuthority: "artifact-metadata",
+    derivedObjects: ["index", "topic-marker", "person-marker"],
+};
+export function localArchiveDir() {
+    const fromEnv = process.env.VIDEOBOOK_ARCHIVE_DIR;
+    if (fromEnv)
+        return resolve(fromEnv);
+    return join(resolve(getEngineRoot()), "archive");
+}
+function isArchiveB2Configured() {
+    return missingArchiveConfigKeys().length === 0;
+}
+export function getArchiveStore() {
+    if (isArchiveB2Configured())
+        return createB2ArchiveStore();
+    return createLocalArchiveStore(localArchiveDir());
+}
+function createB2ArchiveStore(config = getArchiveConfig()) {
+    const b2 = createArchiveB2(config);
+    return {
+        kind: "b2",
+        prefix: config.prefix,
+        exists: (key) => objectExists(b2, config.bucket, key),
+        putJson: (key, value) => putJson(b2, config.bucket, key, value),
+        putText: (key, value) => putText(b2, config.bucket, key, value),
+        getJson: (key) => getJson(b2, config.bucket, key),
+        getText: (key) => getText(b2, config.bucket, key),
+        getBytes: async (key) => {
+            try {
+                const response = await b2.objects.get({ bucket: config.bucket, key });
+                return new Uint8Array(response.body);
+            }
+            catch (error) {
+                if (error?.status === 404)
+                    return null;
+                throw error;
+            }
+        },
+        list: (prefix) => listObjects(b2, config.bucket, prefix),
+        uploadFile: (key, filePath, contentType) => uploadFileToB2(b2, config.bucket, key, filePath, contentType),
+        presignGet: (key, expiresInSeconds) => {
+            const signed = b2.presign.getObject({ bucket: config.bucket, key, expiresIn: expiresInSeconds });
+            return signed?.url ? { url: signed.url, expiresAt: signed.expiresAt ?? null } : null;
+        },
+    };
+}
+function localPathForKey(rootDir, key) {
+    const segments = key.split("/").filter(Boolean);
+    if (segments.length === 0 || segments.some((segment) => segment === "." || segment === "..")) {
+        throw new Error(`Invalid archive key: ${key}`);
+    }
+    const fullPath = join(rootDir, ...segments);
+    if (fullPath !== rootDir && !fullPath.startsWith(rootDir + sep)) {
+        throw new Error(`Invalid archive key: ${key}`);
+    }
+    return fullPath;
+}
+function isFsNotFound(error) {
+    return error?.code === "ENOENT";
+}
+async function readLocalFile(rootDir, key) {
+    try {
+        return await readFile(localPathForKey(rootDir, key));
+    }
+    catch (error) {
+        if (isFsNotFound(error))
+            return null;
+        throw error;
+    }
+}
+async function writeLocalFile(rootDir, key, body) {
+    const fullPath = localPathForKey(rootDir, key);
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, body);
+}
+async function walkLocalKeys(rootDir, dir, out) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isFsNotFound(error))
+            return;
+        throw error;
+    }
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walkLocalKeys(rootDir, fullPath, out);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const fileStat = await stat(fullPath);
+        out.push({
+            key: fullPath.slice(rootDir.length + 1).split(sep).join("/"),
+            size: fileStat.size,
+            lastModified: fileStat.mtime.toISOString(),
+        });
+    }
+}
+export function localArchiveMediaUrl(key) {
+    return `/archive-files/${key.split("/").map(encodeURIComponent).join("/")}`;
+}
+export function createLocalArchiveStore(rootDir) {
+    const root = resolve(rootDir);
+    return {
+        kind: "local",
+        prefix: "",
+        exists: async (key) => {
+            try {
+                const fileStat = await stat(localPathForKey(root, key));
+                return fileStat.isFile();
+            }
+            catch (error) {
+                if (isFsNotFound(error))
+                    return false;
+                throw error;
+            }
+        },
+        putJson: (key, value) => writeLocalFile(root, key, JSON.stringify(value, null, 2)),
+        putText: (key, value) => writeLocalFile(root, key, value),
+        getJson: async (key) => {
+            const body = await readLocalFile(root, key);
+            return body === null ? null : JSON.parse(body.toString("utf8"));
+        },
+        getText: async (key) => {
+            const body = await readLocalFile(root, key);
+            return body === null ? null : body.toString("utf8");
+        },
+        getBytes: async (key) => {
+            const body = await readLocalFile(root, key);
+            return body === null ? null : new Uint8Array(body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength));
+        },
+        list: async (prefix) => {
+            const out = [];
+            await walkLocalKeys(root, root, out);
+            return out
+                .filter((item) => item.key.startsWith(prefix))
+                .sort((a, b) => a.key.localeCompare(b.key));
+        },
+        uploadFile: async (key, filePath) => {
+            const fullPath = localPathForKey(root, key);
+            await mkdir(dirname(fullPath), { recursive: true });
+            await pipeline(createReadStream(filePath), createWriteStream(fullPath));
+        },
+        presignGet: (key) => ({ url: localArchiveMediaUrl(key), expiresAt: null }),
+    };
+}
+export async function readArchiveIngests(store, sha256) {
+    const keys = (await store.list(archiveKey(store, clipPrefix(sha256))))
+        .map((item) => item.key)
+        .filter((key) => /\/ingest-[^/]+\.json$/.test(key));
+    const ingests = await Promise.all(keys.map((key) => store.getJson(key)));
+    return ingests.filter((ingest) => ingest !== null);
+}

package/dist/artifact-label.js

@@ -0,0 +1,36 @@
+/**
+ * Display labels for generated artifacts.
+ *
+ * Labels are free text: never parsed, never matched, never a lookup key.
+ * They exist so a person scanning the library can tell one render from
+ * another, so they read as prose rather than as the hyphenated identifiers
+ * the old slug scheme required.
+ */
+const MAX_SUMMARY_CHARS = 60;
+/** Collapse a prompt to a short, readable fragment. */
+export function promptSummary(prompt, maxChars = MAX_SUMMARY_CHARS) {
+    const text = (prompt ?? "").replace(/\s+/gu, " ").trim();
+    if (text.length <= maxChars)
+        return text;
+    const clipped = text.slice(0, maxChars);
+    const lastSpace = clipped.lastIndexOf(" ");
+    return `${(lastSpace > maxChars / 2 ? clipped.slice(0, lastSpace) : clipped).trimEnd()}…`;
+}
+/**
+ * Label for a generation output, e.g.
+ * `kling-3.0/video — a cat dancing in the rain`.
+ * Falls back to the model alone when there is no prompt to summarize.
+ */
+export function generationLabel(model, prompt) {
+    const summary = promptSummary(prompt);
+    return summary ? `${model} — ${summary}` : model;
+}
+/**
+ * Label for an artifact derived from another one, e.g.
+ * `upscaled — beach sunset`. `source` is the upstream artifact's label,
+ * falling back to its id when it has none.
+ */
+export function derivedLabel(operation, source) {
+    const stem = (source ?? "").trim();
+    return stem ? `${operation} — ${stem}` : operation;
+}

package/dist/artifact-refs.js

@@ -0,0 +1,49 @@
+import { findPrimaryMediaFile } from "videobook-engine";
+// Post-resolution prompts and tool args reference media as @<artifact-id>
+// tokens (grid addresses are resolved to artifact ids before any tool or
+// payload sees them).
+const ARTIFACT_ID_TAG_PATTERN = /@([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?![\w-])/giu;
+// `@s01`-`@s99` address the primary sequence's slots by ordinal; they expand
+// to the artifact id occupying that slot before any other resolution runs.
+const SLOT_TAG_PATTERN = /@s(\d{1,2})(?![\w-])/giu;
+export function expandSlotRefs(text, slotArtifactIds) {
+    return text.replace(SLOT_TAG_PATTERN, (match, ordinal) => {
+        const artifactId = slotArtifactIds[Number(ordinal) - 1];
+        return artifactId ? `@${artifactId}` : match;
+    });
+}
+/** Bare artifact ids mentioned in the text, in first-mention order. */
+export function parseArtifactIdTags(text) {
+    const tags = [];
+    for (const match of text.matchAll(ARTIFACT_ID_TAG_PATTERN)) {
+        const id = (match[1] ?? "").toLowerCase();
+        if (id && !tags.includes(id))
+            tags.push(id);
+    }
+    return tags;
+}
+export async function resolveArtifactRefs(engine, references) {
+    const resolved = [];
+    const unresolved = [];
+    for (const reference of references) {
+        const artifactId = reference.replace(/^@/u, "").toLowerCase();
+        const artifact = engine.artifacts.get(artifactId);
+        if (!artifact.ok) {
+            unresolved.push(`@${artifactId}`);
+            continue;
+        }
+        const manifest = await engine.files.manifest(artifactId);
+        const primary = manifest.ok
+            ? findPrimaryMediaFile(manifest.value.files, artifact.value.kind)
+            : null;
+        resolved.push({
+            tag: `@${artifactId}`,
+            artifactId,
+            ...(artifact.value.label ? { artifactLabel: artifact.value.label } : {}),
+            artifactType: artifact.value.kind,
+            filePath: primary ? primary.name : null,
+            workspacePath: artifact.value.path,
+        });
+    }
+    return { resolved, unresolved };
+}

package/dist/asset-tag-extraction.js

@@ -0,0 +1,169 @@
+/**
+ * Turning analysis a book already paid for into editorial tags.
+ *
+ * Nothing here calls a provider. Image analysis, video analysis and
+ * transcripts are produced elsewhere and cached on the artifact; this module
+ * reads that evidence and decides what it actually supports. Two rules shape
+ * every extractor:
+ *
+ * 1. An unsupported claim is omitted, not softened. Evenly spaced frames can
+ *    show a setting and a framing; they cannot establish that the camera
+ *    tracked, so no extractor offers movement from them.
+ * 2. Absence of evidence is a state, not an empty tag set to hide. Callers get
+ *    an outcome they can report, so "we found nothing useful" never looks the
+ *    same as "we never looked".
+ */
+import { canonicalizeTag, isFrameTag, matchVocabularyTerms, selectEditorialTags, } from "./tag-vocabulary.js";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function strings(value) {
+    if (typeof value === "string")
+        return value.trim() ? [value] : [];
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap(strings);
+}
+function result(tags) {
+    const selected = selectEditorialTags(tags);
+    return {
+        tags: selected,
+        outcome: selected.length > 0 ? "tagged" : "no_useful_evidence",
+    };
+}
+function structuredCandidates(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        const row = record(entry);
+        const facet = typeof row?.facet === "string" ? row.facet : null;
+        const label = typeof row?.label === "string" ? row.label : null;
+        if (!facet || !label)
+            return [];
+        const canonical = canonicalizeTag(facet, label, {
+            allowUnlisted: true,
+        });
+        return canonical ? [canonical] : [];
+    });
+}
+/**
+ * Images: the describe_image response carries structured tags alongside the
+ * reproduction prompt, so tagging costs no extra request. A cached analysis
+ * written before tags existed simply yields nothing — the shot/pose fields
+ * are prompt vocabulary, not grouping terms, and mining them would invent
+ * claims the model never made.
+ */
+export function tagsFromImageAnalysis(analysis) {
+    const document = record(analysis);
+    if (!document || !Array.isArray(document.tags)
+        || (document.tags.length > 0 && !document.tags.some((entry) => {
+            const tag = record(entry);
+            return typeof tag?.facet === "string" && ["people", "places", "editing"].includes(tag.facet)
+                && typeof tag.label === "string";
+        })))
+        return { tags: [], outcome: "no_evidence" };
+    return result(structuredCandidates(document.tags).filter(isFrameTag));
+}
+/**
+ * Video and final renders: analyze_video's cached document. Its `tags`,
+ * `setting`, `subjects` and scene tags are free text written for search, so
+ * every term goes through the vocabulary and most are discarded. A fallback
+ * document — the empty shape the analyzer writes when the provider failed —
+ * is not evidence at all.
+ */
+export function tagsFromVideoAnalysis(analysis) {
+    const document = record(analysis);
+    if (!document)
+        return { tags: [], outcome: "no_evidence" };
+    if (isFallbackAnalysis(document))
+        return { tags: [], outcome: "no_evidence" };
+    if (Array.isArray(document.editorialTags)) {
+        return result(structuredCandidates(document.editorialTags).filter(isFrameTag));
+    }
+    const scenes = Array.isArray(document.scenes) ? document.scenes : [];
+    const sceneTags = scenes.flatMap((scene) => strings(record(scene)?.tags));
+    // Setting first: where something happens is the most reliable grouping
+    // signal a frame sample supports, then who is in it, then the analyzer's
+    // own top-level terms, then per-scene detail.
+    const settings = strings(document.setting);
+    const freeText = [
+        ...strings(document.tags),
+        ...sceneTags,
+    ];
+    const candidates = [
+        // The setting field holds a place and nothing else, so a concrete term it
+        // names is kept even when the vocabulary has never seen it.
+        ...settings.flatMap((phrase) => {
+            const listed = matchVocabularyTerms("places", phrase);
+            if (listed.length > 0)
+                return listed;
+            const unlisted = canonicalizeTag("places", phrase, { allowUnlisted: true });
+            return unlisted ? [unlisted] : [];
+        }),
+        ...freeText.flatMap((phrase) => ["places", "people", "editing"].flatMap((facet) => {
+            const exact = canonicalizeTag(facet, phrase);
+            return exact ? [exact] : [];
+        })),
+        ...strings(document.subjects).flatMap((phrase) => {
+            const exact = canonicalizeTag("people", phrase);
+            return exact ? [exact] : [];
+        }),
+    ];
+    return result(candidates.filter(isFrameTag));
+}
+/**
+ * An analyze_video run that failed writes a document with every field empty.
+ * Blessing that as "analyzed, nothing found" would fence the artifact against
+ * a later successful run, so it counts as no evidence.
+ */
+export function isFallbackAnalysis(document) {
+    const summary = typeof document.summary === "string" ? document.summary.trim() : "";
+    const scenes = Array.isArray(document.scenes) ? document.scenes.length : 0;
+    const tags = Array.isArray(document.tags) ? document.tags.length : 0;
+    const subjects = Array.isArray(document.subjects) ? document.subjects.length : 0;
+    const setting = typeof document.setting === "string" ? document.setting.trim() : "";
+    return summary === "" && scenes === 0 && tags === 0 && subjects === 0 && setting === "";
+}
+/**
+ * Audio: what a transcript can honestly support is whether the recording
+ * carries speech and whether more than one person speaks. Topic and genre are
+ * not editing decisions, and a name in a transcript identifies nobody on
+ * screen, so neither becomes a tag.
+ */
+export function tagsFromTranscript(evidence) {
+    if (!evidence)
+        return { tags: [], outcome: "no_evidence" };
+    const candidates = [];
+    if (evidence.wordCount > 0)
+        candidates.push({ facet: "editing", label: "dialogue" });
+    return result(candidates);
+}
+/**
+ * Text-bearing artifacts. A script's sluglines are the one place stored text
+ * genuinely encodes place and time — "INT. KITCHEN - NIGHT" is a structured
+ * statement, not a keyword that happens to appear. Everything else in a
+ * document is dialogue and direction, which say nothing about how the footage
+ * that may one day exist was shot, so nothing else is read.
+ */
+export function tagsFromScriptText(text) {
+    if (!text || !text.trim())
+        return { tags: [], outcome: "no_evidence" };
+    const candidates = [];
+    const sluglines = text.match(/^\s*(INT|EXT)[.\s][^\n]*/gimu) ?? [];
+    for (const line of sluglines) {
+        const upper = line.toUpperCase();
+        if (/^\s*INT/u.test(upper))
+            candidates.push({ facet: "places", label: "interior" });
+        if (/^\s*EXT/u.test(upper))
+            candidates.push({ facet: "places", label: "exterior" });
+        if (/[-\s]DAY\b/u.test(upper))
+            candidates.push({ facet: "places", label: "day" });
+        if (/[-\s]NIGHT\b/u.test(upper))
+            candidates.push({ facet: "places", label: "night" });
+    }
+    if (candidates.length === 0)
+        return { tags: [], outcome: "no_useful_evidence" };
+    return result(candidates);
+}

package/dist/asset-tags.js

@@ -0,0 +1,228 @@
+/**
+ * Asset tag projection: the one place that turns engine tag state into the
+ * snake_case records MCP payloads carry, and the one place that decides
+ * whether an asset matches a tag filter.
+ *
+ * The engine owns storage, normalization and provenance; this module owns
+ * presentation and the exact-match filter the Library and list_assets share,
+ * so a tag reads the same way in an asset payload, a search result and a
+ * filter argument.
+ */
+import { createHash } from "node:crypto";
+import { resolveTagInput } from "./tag-vocabulary.js";
+import { TAG_FACETS, TAG_READ_BATCH_MAX, isTagFacet, normalizeTagIdentity, tagCanonicalKey, } from "videobook-engine";
+export const EMPTY_TAG_SUMMARY = Object.freeze({
+    effective: [],
+    manual: [],
+    automatic: [],
+    dismissed: [],
+    analysis: null,
+    fingerprint: "",
+});
+function tagRecord(tag) {
+    const identity = normalizeTagIdentity(resolveTagInput(tag));
+    return {
+        facet: tag.facet,
+        key: identity.key,
+        label: identity.label,
+        origin: tag.origin,
+        entity_id: tag.entityId ?? null,
+    };
+}
+function dismissedRecord(tag) {
+    return normalizeTagIdentity(resolveTagInput(tag));
+}
+function automaticRecord(tag) {
+    return tagRecord(tag);
+}
+/**
+ * Identity-only digest: labels and timestamps are display detail, so a
+ * re-analysis that returns the same identities leaves the fingerprint alone
+ * and the client skips a needless asset refresh.
+ */
+function tagFingerprint(state) {
+    const parts = [
+        ...state.effective.map((tag) => `e:${tag.facet}/${tag.key}/${tag.origin}`),
+        ...state.dismissed.map((tag) => `d:${tag.facet}/${tag.key}`),
+    ].sort();
+    if (parts.length === 0)
+        return "";
+    return createHash("sha256").update(parts.join("\n")).digest("hex").slice(0, 16);
+}
+export function assetTagSummary(state) {
+    const unique = (tags) => [...new Map(tags.map((tag) => [`${tag.facet}/${tag.key}`, tag])).values()];
+    const manual = unique(state.manual.map(tagRecord));
+    const automatic = unique(state.automatic.map(automaticRecord));
+    const dismissed = unique(state.dismissed.map(dismissedRecord));
+    const suppressed = new Set(dismissed.map((tag) => `${tag.facet}/${tag.key}`));
+    const effective = unique([
+        ...state.effective.filter((tag) => tag.origin === "automatic").map(tagRecord)
+            .filter((tag) => !suppressed.has(`${tag.facet}/${tag.key}`)),
+        ...manual,
+    ]).sort((left, right) => left.facet.localeCompare(right.facet) || left.key.localeCompare(right.key));
+    return {
+        effective,
+        manual,
+        automatic,
+        dismissed,
+        analysis: state.snapshot
+            ? {
+                source_hash: state.snapshot.sourceHash,
+                generator: state.snapshot.generator,
+                model: state.snapshot.model ?? null,
+                extractor_version: state.snapshot.extractorVersion,
+                tag_count: state.snapshot.tagCount,
+                generation: state.snapshot.generation,
+                analyzed_at: state.snapshot.analyzedAt,
+                stale: state.snapshot.stale,
+            }
+            : null,
+        fingerprint: tagFingerprint(state),
+    };
+}
+/**
+ * Batched tag read for a list of artifacts. Reads are chunked to the engine's
+ * documented batch ceiling, and an artifact the engine cannot read (a
+ * synthetic notebook row, say) simply has no entry.
+ */
+export function readAssetTagSummaries(engine, artifactIds) {
+    const summaries = new Map();
+    for (let start = 0; start < artifactIds.length; start += TAG_READ_BATCH_MAX) {
+        const batch = artifactIds.slice(start, start + TAG_READ_BATCH_MAX);
+        const result = engine.tags.readMany(batch);
+        if (!result.ok)
+            continue;
+        for (const state of result.value) {
+            summaries.set(state.artifactId, assetTagSummary(state));
+        }
+    }
+    return summaries;
+}
+/**
+ * Parses one filter term. A bare label matches the identity in any facet,
+ * which is what a user typing "kitchen" into a filter box means; a
+ * facet-qualified term keeps `people/handheld` and `editing/handheld` apart.
+ */
+function normalizeSelector(selector) {
+    if (selector.facet !== undefined) {
+        if (!isTagFacet(selector.facet)) {
+            throw new Error(`Unknown tag facet "${selector.facet}"; expected one of ${TAG_FACETS.join(", ")}`);
+        }
+        const identity = normalizeTagIdentity(resolveTagInput({
+            facet: selector.facet,
+            label: selector.label,
+        }));
+        return { facet: identity.facet, key: identity.key };
+    }
+    const key = tagCanonicalKey(selector.label);
+    if (!key)
+        throw new Error("Tag label is required");
+    return { facet: null, key };
+}
+function matchesSelector(tags, selector) {
+    return tags.some((tag) => tagCanonicalKey(resolveTagInput(tag).label) === tagCanonicalKey(resolveTagInput({
+        facet: tag.facet, label: selector.key,
+    }).label)
+        && (selector.facet === null || tag.facet === selector.facet));
+}
+/** True when no term was supplied — an absent filter matches everything. */
+function isEmptyTagFilter(filter) {
+    return !filter
+        || ((filter.all?.length ?? 0) === 0 && (filter.any?.length ?? 0) === 0);
+}
+/**
+ * Exact identity matching against the effective set only: a dismissed tag
+ * must not match, and neither may a transcript that merely mentions the word
+ * — that is what semantic search is for.
+ */
+export function matchesTagFilter(summary, filter) {
+    if (isEmptyTagFilter(filter))
+        return true;
+    const tags = summary?.effective ?? [];
+    const all = (filter?.all ?? []).map(normalizeSelector);
+    const any = (filter?.any ?? []).map(normalizeSelector);
+    if (!all.every((selector) => matchesSelector(tags, selector)))
+        return false;
+    if (any.length > 0 && !any.some((selector) => matchesSelector(tags, selector))) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Facet counts over an already-filtered result set, so a caller can offer the
+ * groups that actually narrow what it is looking at rather than every tag in
+ * the book.
+ */
+export function tagFacetCounts(assets, limit = 50) {
+    const counts = new Map();
+    for (const asset of assets) {
+        const seen = new Set();
+        for (const tag of asset.tags?.effective ?? []) {
+            const identity = `${tag.facet}/${tag.key}`;
+            if (seen.has(identity))
+                continue;
+            seen.add(identity);
+            const existing = counts.get(identity);
+            if (existing) {
+                existing.assets += 1;
+                continue;
+            }
+            counts.set(identity, {
+                facet: tag.facet,
+                key: tag.key,
+                label: tag.label,
+                assets: 1,
+            });
+        }
+    }
+    return [...counts.values()]
+        .sort((left, right) => right.assets - left.assets
+        || left.facet.localeCompare(right.facet)
+        || left.key.localeCompare(right.key))
+        .slice(0, limit);
+}
+export const EMPTY_TRANSFER_SUMMARY = {
+    imported_manual: 0,
+    imported_dismissals: 0,
+    imported_automatic: 0,
+    skipped_automatic: false,
+};
+/**
+ * Moves one artifact's tag state onto a copy, in either the same engine or
+ * another book's. The engine re-normalizes every label into destination-local
+ * identities and validates automatic evidence against the destination's own
+ * files, so this never hand-copies rows. Copying nothing is not a write: an
+ * untagged source leaves the destination catalog untouched.
+ */
+export async function transferAssetTags(source, destination) {
+    const exported = source.engine.tags.export(source.artifactId);
+    if (!exported.ok)
+        throw new Error(exported.error.message);
+    const snapshot = exported.value;
+    const empty = snapshot.manual.length === 0
+        && snapshot.dismissed.length === 0
+        && snapshot.automatic === undefined;
+    if (empty)
+        return EMPTY_TRANSFER_SUMMARY;
+    const imported = await destination.engine.tags.import(destination.artifactId, snapshot);
+    if (!imported.ok)
+        throw new Error(imported.error.message);
+    return {
+        imported_manual: imported.value.importedManual,
+        imported_dismissals: imported.value.importedDismissals,
+        imported_automatic: imported.value.importedAutomatic,
+        skipped_automatic: imported.value.skippedAutomatic,
+    };
+}
+/**
+ * The effective tag labels as one indexable string. Search indexing consumes
+ * this rather than the raw analysis sidecar, so a dismissed tag stays out of
+ * the lexical index even while the description that mentioned it remains
+ * searchable as evidence.
+ */
+export function effectiveTagText(engine, artifactId) {
+    const state = engine.tags.read(artifactId);
+    if (!state.ok)
+        return "";
+    return state.value.effective.map((tag) => tag.label).join(" ");
+}

package/dist/asset-usage.js

@@ -0,0 +1,23 @@
+const SETTINGS_KEY = "asset-last-used";
+const MAX_ENTRIES = 500;
+function usageEntries(stored) {
+    if (!stored || typeof stored !== "object" || Array.isArray(stored))
+        return [];
+    return Object.entries(stored).filter((entry) => typeof entry[1] === "number" && Number.isFinite(entry[1]));
+}
+export function readAssetUsage(engine) {
+    return new Map(usageEntries(engine.settings.get(SETTINGS_KEY)));
+}
+export function recordAssetUse(engine, artifactId, usedAt = Date.now()) {
+    const entries = usageEntries(engine.settings.get(SETTINGS_KEY))
+        .filter(([id]) => id !== artifactId);
+    const next = [[artifactId, usedAt], ...entries]
+        .sort((left, right) => right[1] - left[1])
+        .slice(0, MAX_ENTRIES);
+    return engine.settings.set(SETTINGS_KEY, Object.fromEntries(next)).ok;
+}
+export function assetRecency(createdAt, lastUsedAt) {
+    const created = Date.parse(createdAt);
+    const createdMs = Number.isFinite(created) ? created : 0;
+    return Math.max(createdMs, lastUsedAt ?? 0);
+}