videobook-engine 4.2.0 → 5.3.2

package/docs/temporal-search-performance.md

@@ -0,0 +1,260 @@
+# Temporal search scale measurements
+
+Run the performance fixture through the public engine API:
+
+```bash
+npm run benchmark:temporal -- --output /tmp/temporal-search.json --assert
+```
+
+The default workload creates 1,000 synthetic video artifacts and 100,000
+one-second moments with deterministic normalized 512-dimensional vectors.
+Each artifact has indexed description text as well as visual embeddings.
+The fixture uses synthetic bytes and declared stream metadata; it does not
+run media probing or model inference and cannot measure indexing-model
+throughput, recall, relevance, multilingual quality, or boundary accuracy.
+Those release gates require the separate frozen, rights-cleared corpus.
+
+Indexing uses batches of at most 30 moments by default. After every batch,
+the harness reads the public index plan and verifies cumulative coverage
+and its persisted next cursor. It activates the first partial batch and
+checks that a reference query retrieves the source before indexing finishes.
+After indexing, the engine closes and reopens the catalog and checks the
+stored moment and indexed-artifact counts.
+Each committed batch also calls `temporalSearch.prepare` with periodic
+checkpointing, so native graph construction is included in indexing time.
+
+The report records the first query for each mode, then repeats that query
+outside the timing samples to check deterministic results. It measures
+50 further queries per mode, varying the source across the book, and checks
+that image and ordered-video queries retrieve their own source. Hybrid
+queries combine indexed text matching, injected text vectors, ranking,
+overlap collapse, and coverage reporting. No remote providers or embedding
+models are loaded. Query timings include the complete public search call.
+A first query is not a cold OS page-cache measurement, and the modes run
+in image, video, hybrid order.
+
+`peakRssBytes` is the process high-water RSS reported by Node, converted from
+KiB, including the engine, index creation, and queries in a fresh fixture
+run. Reusing a fixture measures query-process RSS without the original
+seeding process. The report keeps these runs distinct and records actual
+CPU, memory, Node version, source commit, dirty state, dimensions, raw timing
+samples, coverage cadence, and whether the full-size repeated workload ran.
+The PRD reference device is an M2 Pro with 16 GB RAM; measurements on another
+device must retain that qualification.
+
+For a short harness check:
+
+```bash
+npm run benchmark:temporal -- --moments 100 --artifacts 5 --reads 3
+```
+
+To compare retrieval implementations without recreating the fixture, use
+`--retain-fixture` on the first run and `--fixture <printed-path>` on later
+runs. Only fixtures with this harness's marker and manifest are accepted.
+Reused fixture seeding metrics describe the original build, not the later
+measurement. A short run intentionally fails the `fullScale` assertion.
+
+## Initial 100,000-moment baseline
+
+The [recorded baseline](../benchmarks/results/temporal-100k-baseline.json)
+measured engine commit `c151c6e` on September 5, 2026, using an Apple M1 Pro
+with 16 GB RAM and Node 24.10.0. Five warm queries per mode were sufficient
+to establish a large performance failure; this is diagnostic evidence, not
+the required 50-query acceptance run.
+
+| Mode | Warm p50 | Warm p95 |
+| --- | ---: | ---: |
+| Prepared image | 2,475 ms | 2,515 ms |
+| Prepared eight-second video | 14,344 ms | 14,425 ms |
+| Hybrid text and visual | 2,800 ms | 2,851 ms |
+
+Indexing took 138.8 seconds in 4,000 batches, each covering at most 30 seconds
+of source time. First searchable coverage appeared after 49 ms. All 4,000
+persisted resume cursors were verified. Open plus book/search summary took
+963 ms, and the process peak RSS was 2.83 GiB.
+
+This baseline did not meet the latency requirement. Its query path loaded all
+segments and embeddings and evaluated every possible video window. Faster
+timings alone cannot satisfy VE-NFR-012 if every query still scans the full
+vector collection.
+
+
+## Indexed candidate retrieval
+
+The engine now caches segment metadata and vectors for the active generations
+and uses a USearch HNSW index with F16 storage to select visual/audio/text
+vector candidates. It recomputes shortlisted cosine scores from the original
+F32 vectors before reciprocal-rank fusion. Each modality contributes up to
+1,000 vector candidates, independently of the requested page size or cursor.
+Pagination traverses the combined ranked candidate set, including lexical and
+exact/near-fingerprint evidence. Restrictive filters are applied to candidate
+eligibility; small eligible subsets are scored directly, and broader filters
+expand the ANN shortlist until enough eligible candidates are found.
+
+Ordered video searches use timed neighbors from every reference sample,
+propose nearby start positions, then score bounded windows with timestamp
+alignment and temporal coherence. At most 512 neighbor seeds produce at most
+1,536 start positions. Each window uses at most 16 target samples; cached
+query interpolation and prefix sums of continuity keep long-window scoring
+bounded without treating skipped samples as gaps. Duration filters apply to
+the resulting window. Still-image neighbors cannot displace timed candidates.
+
+Committed indexing batches refresh only affected cache entries. Semantic
+changes refresh metadata and remove deleted sources while preserving native
+vectors, so a rename does not rebuild the graph. Generation changes and engine
+close discard the relevant in-memory state. Regression tests cover native ANN
+pagination across page sizes, vector/text replacement, source and label
+filters, rename/deletion, ordered action, differing sampling densities, bounded
+durations, and a long video reference surrounded by matching still images.
+
+The [full indexed run](../benchmarks/results/temporal-100k-indexed.json) measures
+the source committed as `db996f2` on the same M1 Pro/16 GB machine, with a newly
+created 1,000-artifact/100,000-moment fixture and 50 warm queries per mode:
+
+| Mode | Warm p50 | Warm p95 |
+| --- | ---: | ---: |
+| Prepared image | 54 ms | 63 ms |
+| Prepared eight-second video | 105 ms | 140 ms |
+| Hybrid text and visual | 284 ms | 331 ms |
+
+This run passed all harness gates. Process peak RSS, including fixture
+creation and index/query structures, was 3.26 GiB. It committed 4,000 batches
+covering at most 30 source seconds each, verified every resume cursor, and
+published the first searchable partial coverage after 45 ms. Open plus
+book/search summary after closing the newly built fixture took 1.35 seconds.
+
+Two limitations remained in that run. First, creating the native graph on the
+first query took 139 seconds; warm-query success does not make that suitable
+for an interactive request. `ve-s84.4` tracks preparing and persisting the
+index through indexing work and validating fast query readiness after reopen.
+Publication depends on that issue. Second, independent fresh-process opens
+have spent over four seconds in automatic catalog GC; `ve-ovz.2` tracks that
+cost, which the same-process reopen measurement does not consistently expose.
+These measurements also do not replace the frozen corpus quality gate.
+
+## Persisted preparation
+
+Activate a generation after committing its first partial batch, then prepare
+its search index inside a cancellable indexing job:
+
+```ts
+const activated = engine.temporalSearch.activate(manifestId, generation);
+if (!activated.ok) throw new Error(activated.error.message);
+const prepared = await engine.temporalSearch.prepare({
+  manifestId,
+  generation,
+  signal,
+  checkpoint: "periodic",
+});
+if (!prepared.ok) throw new Error(prepared.error.message);
+```
+
+Preparation yields between bounded native insertions. Already prepared
+indexes update incrementally as committed batches are consumed. Periodic
+checkpoints write after 5,000 changes; the default preparation mode and engine
+close flush outstanding changes. Omitting the manifest and generation
+prepares every active index, which supports background recovery of old books.
+Collections of at most 1,000 vectors use direct scoring without a native graph.
+
+Disposable snapshots live under `data/runtime-search`. Their identity includes
+the full manifest, generation, modality, dimensions, native version, and index
+configuration. A SHA-256 checksum protects the native bytes before loading;
+stable vector keys and content digests validate the mapping against committed
+vectors. Metadata is published by rename after a complete graph is saved.
+A stale checkpoint can be reconciled from changed vectors; a corrupt or
+incompatible checkpoint is rebuilt. Cancellation never publishes a partial
+graph. The source vectors remain in the catalog.
+
+Deleted keys are filtered from queries immediately but retain occupied native
+slots until preparation rebuilds a fresh graph. Preparation compacts when more
+than one quarter of native keys are inactive. This avoids a USearch 2.26.0
+crash reproduced by saving a graph with removed slots, reopening it, and adding
+replacement vectors. Changed vectors replace their native slots immediately;
+a failed replacement discards the in-memory graph. Snapshot format v2 rejects
+older, potentially unsafe graphs before loading them. Old books therefore need
+one background preparation before large-index searches can resume.
+
+An interactive query loads a snapshot containing all current vectors, but never
+constructs a missing large graph. It returns `NOT_READY` with
+`error.details.requiresIndexPreparation === true` when preparation is needed.
+Consumers should queue preparation, show its progress, and retry after the job
+finishes. The index's preparation result separates loaded indexes, changed
+vectors, and persisted indexes. `--prepare-existing` in the benchmark measures
+explicit recovery before closing and reopening a retained older fixture.
+
+The [safe-cache regression run](../benchmarks/results/temporal-100k-safe-cache.json)
+rebuilt the retained 100,000-vector fixture from the old format in 152.6 seconds.
+After reopening, the first image query took 3.03 seconds; warm p95 was 72 ms for
+image, 151 ms for video, and 371 ms for hybrid. Peak process RSS was 2.27 GiB and
+all harness gates passed. This run measures cache rebuilding and queries; its
+indexing fields are inherited from the retained fixture, not a new indexing run.
+
+The [full persisted run](../benchmarks/results/temporal-100k-persisted.json)
+measured the preparation implementation committed as `a7c3703` on the same
+M1 Pro/16 GB device. Indexing and preparation took 291.4 seconds across 4,000
+batches; preparation accounted for 148.3 seconds of that total. Initial
+searchable coverage appeared after 40 ms, and every resume cursor passed.
+After close/reopen, open plus summary took 919 ms and the first image query,
+including verified graph loading, took 2.90 seconds. The 50-query warm p95s
+were 62 ms (image), 162 ms (video), and 361 ms (hybrid); peak RSS was 3.58 GiB.
+All harness gates passed. This includes incremental construction and persisted
+reopen, but does not remove the separate fresh-process catalog GC or corpus
+quality release gates.
+
+## Healthy catalog reopen in a fresh process
+
+The [fresh-process run](../benchmarks/results/temporal-100k-fresh-process.json)
+reuses the persisted 100,000-moment fixture after recording successful catalog
+compaction. It runs in a new Node process on the same M1 Pro/16 GB device.
+Open plus book/search summary took 1.14 seconds, compared with 4.76 seconds
+when the same fixture first required compaction. The first image query took
+4.14 seconds including vector and verified graph loading. Fifty warm queries
+per mode passed with p95s of 95 ms (image), 154 ms (video), and 378 ms (hybrid).
+This query process peaked at 2.02 GiB and passed all harness gates; its indexing
+metrics describe the earlier fixture creation, not new indexing work.
+
+The store now skips size-triggered GC only when its disposable compaction
+record matches the catalog file. Writes invalidate the record, and missing or
+damaged metadata falls back to GC. This resolves the repeated healthy-catalog
+compaction measured above; frozen-corpus quality remains a separate gate.
+
+## Current-source acceptance runs
+
+Two runs on September 6, 2026 measure the working tree on top of engine
+`8b235f2` (the NFR measurement changes touch only benchmarks, tests and docs)
+on the same M1 Pro/16 GB device with Node 24.10.0. The
+[fresh build](../benchmarks/results/temporal-100k-current-source.json) created
+a new 1,000-artifact/100,000-moment fixture: indexing plus incremental
+preparation took 332.8 seconds across 4,000 batches of at most 30 source
+seconds, every resume cursor passed, first searchable coverage appeared after
+45 ms, and open plus summary in the same process took 206 ms. Fifty warm
+queries per mode measured p50/p95 of 62/67 ms (image), 117/159 ms (video) and
+333/391 ms (hybrid); peak RSS was 2.43 GiB. The
+[fresh-process reopen](../benchmarks/results/temporal-100k-current-source-reopen.json)
+of that retained fixture took 960 ms for open plus summary, with warm p50/p95
+of 58/62 ms (image), 115/148 ms (video) and 322/359 ms (hybrid) and a 2.32 GiB
+peak. Both runs passed every harness gate. The first image query after reopen
+took 3.1 seconds including verified snapshot loading; the M2 Pro reference
+device measurement remains outstanding.
+
+## DoltLite 0.50.6 candidate
+
+Engine `c4f1d89` (5.3.2) was measured from a clean committed tree on an Apple
+M1 Pro with 16 GB RAM and Node 24.10.0. The
+[fresh build](../benchmarks/results/temporal-100k-doltlite-0506.json) and
+[fresh-process reopen](../benchmarks/results/temporal-100k-doltlite-0506-reopen.json)
+retain all samples for 100,000 moments, 1,000 artifacts, 512 dimensions, and
+50 warm queries per mode. Every harness gate passes.
+
+| Run | Open + summary | Image p50 / p95 | Video p50 / p95 | Hybrid p50 / p95 | Peak RSS |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Fresh build, same-process reopen | 171 ms | 59 / 66 ms | 113 / 165 ms | 332 / 411 ms | 3.03 GiB |
+| Fresh process, retained fixture | 1,714 ms | 60 / 73 ms | 117 / 179 ms | 310 / 388 ms | 2.08 GiB |
+
+Fresh indexing and preparation take 319.9 seconds in 4,000 batches of at most
+30 source seconds. All durable resume cursors are verified, and first searchable
+coverage appears after 47 ms. The first query after reopen includes snapshot
+loading: 3.03 seconds in the build process and 3.12 seconds in the fresh process;
+these are separate from warm query latency. The reused fixture inherits indexing
+metrics and does not measure another build. The reference M2 Pro measurement
+remains `ve-ovz.22`; the synthetic vectors do not replace the frozen quality corpus.

package/docs/v4-migration.md

@@ -0,0 +1,83 @@
+# Copy-forward migration from schema v4
+
+Keep the legacy book closed while migrating. `dryRunV4Migration(root)` and
+`readV4BookIdentity(root)` inspect a disposable copy of its catalog. Migration
+also reads a copy, leaving the original catalog and content bytes untouched.
+The destination must be separate, including through symbolic-link aliases.
+
+```ts
+const preview = dryRunV4Migration(sourceRoot);
+if (!preview.ok) throw new Error(preview.error.message);
+
+const result = await migrateV4({
+  sourceRoot,
+  destinationRoot,
+  dryRun: false,
+  expectedSourceBookId: preview.value.sourceBookId,
+  expectedSourceHead: preview.value.sourceHeadRevision,
+  expectedMigrationKey: preview.value.migrationKey,
+  signal: controller.signal,
+  onProgress: ({ phase, completed, total }) => reportProgress(phase, completed, total),
+});
+```
+
+The migration key covers the converter version, destination schema, source
+head, and current semantic rows. It detects uncommitted changes even when IDs
+and row counts are unchanged. The source is checked again before publication.
+Dry runs report missing files, incorrect object sizes, invalid references,
+unrepresentable notebook state, unsupported media, and required probing and
+reindexing. Full object hashes and media probes are verified during migration
+before a destination can be published. Timed conversion requires `ffprobe` on
+PATH, or an explicit `ffprobePath`; it does not require model downloads.
+
+Current artifact/file hashes, entities, notebook IDs, cell IDs, edge IDs, run
+records, prompts, messages, waveforms, and compatible metadata are preserved.
+Notebook canvas coordinates become deterministic row-major slots, ordered by
+Y, X, and cell ID. A notebook exceeding the 64-by-8 grid is rejected. Legacy
+scene cells become prompt cells with their entity references intact; asset
+cells use their referenced artifact's current media type. Legacy `image` and
+`video` cells were generation nodes; they become `generate_image` and
+`generate_video`, with their existing output artifact IDs and edges intact.
+Their model strings are retained as explicit tool selections. When no model
+was configured, migration records the legacy GPT Image 2 text-to-image or
+Wan 2.7 text-to-video default, rather than changing to the application's current
+default. Retired or unavailable tools remain visible for user reconfiguration;
+migration never submits generation jobs. The report includes original model
+values, resolved tool names, and whether each choice was explicit or defaulted.
+Compatible notebook
+fields and execution state are restored through the engine API. Original
+coordinates, cell types, and all legacy notebook properties remain in the
+machine-readable report.
+
+Image slots retain the legacy three-second duration. Video slots use probed
+stream duration and follow legacy `(ordinal, slot_id)` order on the first video
+track. Audio clips retain their 30-fps start and duration on the first audio
+track, including overlaps. They play at native speed, trimming the source when
+the requested clip is shorter; a longer placement retains the legacy trailing
+silence. Percentage volume becomes gain in dB, zero volume becomes mute, and
+millisecond fades become frame counts. Fades exceeding the clip duration are
+rejected instead of being silently shortened. Render orientation sets the
+primary sequence dimensions. Every generated placement passes edit preview
+and commit validation.
+
+The report records source-head and current-table digests, conversion decisions,
+new stream profiles, and the legacy source location. Legacy action/operation
+history remains in that source; it is not injected into current Dolt history.
+Legacy terminal job records remain part of the source audit, while current
+runtime job IDs start fresh. Old similarity rows are discarded. The application
+must queue indexing under its configured current manifests after switching.
+
+Migration builds in a uniquely named sibling temporary directory and publishes
+by rename only after its catalog, objects, notebook state, timeline, report,
+and audit commit have succeeded. Cancellation or an ordinary failure removes
+that temporary directory. Process termination can leave an unpublished
+`<destination>.migrating-*` directory; retry safely creates a fresh candidate
+and cannot duplicate destination rows. An identical completed migration returns
+its verified receipt. Unrelated or incompatible nonempty destinations are never
+overwritten. Migration itself never switches the application's book root.
+
+Tests use the pinned schema from engine commit `580fc0e`, real JPEG/H.264/AAC/WAV
+media, an empty book, a 1,001-media-artifact catalog with 1,536 notebook cells,
+missing/corrupt objects, cancellation, process termination, source changes,
+and repeated completed requests. Source catalog preservation is checked byte
+for byte as well as through its head and semantic-state digest.

package/fixtures/v5/contract-fixtures.json

@@ -1,7 +1,7 @@
 {
   "compatibility": {
     "contractVersion": 1,
-    "schemaVersion": 18,
+    "schemaVersion": 24,
     "minimumReaderContractVersion": 1,
     "legacySchemaVersions": [
       4,
@@ -1378,7 +1378,7 @@
     "hits": [
       {
         "artifactId": "0197-artifact-video",
-        "artifactSlug": "vid-red-van",
+        "artifactLabel": "Red Van",
         "artifactKind": "video",
         "location": {
           "kind": "timed",
@@ -1481,7 +1481,7 @@
   "migrationDryRun": {
     "contractVersion": 1,
     "sourceSchemaVersion": 4,
-    "destinationSchemaVersion": 18,
+    "destinationSchemaVersion": 24,
     "sourceBookId": "0197-book-v4",
     "sourceHeadRevision": "dolt-v4-head",
     "artifactCount": 8,
@@ -1503,7 +1503,7 @@
   "migrationResult": {
     "contractVersion": 1,
     "sourceSchemaVersion": 4,
-    "destinationSchemaVersion": 18,
+    "destinationSchemaVersion": 24,
     "sourceBookId": "0197-book-v4",
     "sourceHeadRevision": "dolt-v4-head",
     "artifactCount": 8,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "videobook-engine",
-  "version": "4.2.0",
+  "version": "5.3.2",
   "description": "Dolt-native local-first storage engine for Videobook",
   "type": "module",
   "exports": {
@@ -20,6 +20,18 @@
       "import": "./dist/edit-policy.js",
       "types": "./dist/edit-policy.d.ts"
     },
+    "./notebook-grid": {
+      "import": "./dist/notebook-grid.js",
+      "types": "./dist/notebook-grid.d.ts"
+    },
+    "./notebook-media-artifact": {
+      "import": "./dist/notebook-media-artifact.js",
+      "types": "./dist/notebook-media-artifact.d.ts"
+    },
+    "./notebook-mentions": {
+      "import": "./dist/notebook-mentions.js",
+      "types": "./dist/notebook-mentions.d.ts"
+    },
     "./package.json": "./package.json",
     "./fixtures/v5": "./fixtures/v5/contract-fixtures.json"
   },
@@ -31,29 +43,33 @@
     "fixtures"
   ],
   "scripts": {
+    "test:package": "node scripts/package-smoke.mjs",
     "benchmark:api": "tsx benchmarks/run-api-benchmark.ts",
     "benchmark:api:smoke": "tsx benchmarks/run-api-benchmark.ts --quick",
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && tsc",
+    "build": "npm run clean && tsc && node scripts/build-transformers.mjs",
     "prepare": "npm run build",
     "prepack": "npm run build",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.benchmarks.json",
     "lint": "knip",
+    "pretest": "node scripts/patch-transformers.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "example:basic": "npm run build && tsx examples/basic-usage.ts",
-    "examples": "npm run example:basic"
+    "examples": "npm run example:basic",
+    "benchmark:temporal": "tsx benchmarks/run-temporal-benchmark.ts",
+    "benchmark:edits": "tsx benchmarks/run-edit-benchmark.ts"
   },
   "engines": {
     "node": ">=22"
   },
   "dependencies": {
-    "@dolthub/doltlite": "^0.11.37",
-    "@huggingface/transformers": "4.2.0",
+    "@dolthub/doltlite": "0.50.6",
     "node-gyp": "12.1.0",
-    "sharp": "0.35.3",
+    "sharp": "0.35.4",
     "usearch": "2.26.0",
-    "uuid": "^14.0.0"
+    "uuid": "^14.0.0",
+    "onnxruntime-node": "1.29.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -61,20 +77,22 @@
     "knip": "^6.11.0",
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.8",
+    "@huggingface/transformers": "4.2.0",
+    "esbuild": "0.28.1"
   },
   "overrides": {
-    "adm-zip": "0.6.0",
     "esbuild": "0.28.1",
     "postcss": "^8.5.23",
-    "sharp": "0.35.3"
+    "sharp": "$sharp",
+    "onnxruntime-node": "$onnxruntime-node"
   },
   "allowScripts": {
-    "@dolthub/doltlite@0.11.37": true,
+    "@dolthub/doltlite@0.50.6": true,
     "esbuild@0.28.1": true,
     "fsevents@2.3.3": true,
-    "onnxruntime-node@1.24.3": true,
     "protobufjs@7.6.5": true,
-    "usearch@2.26.0": true
+    "usearch@2.26.0": true,
+    "onnxruntime-node@1.29.0": true
   }
 }

package/dist/artifact-names.d.ts

@@ -1,6 +0,0 @@
-import type { ArtifactKind } from "./engine-types.js";
-export declare function isArtifactNameStopWord(word: string): boolean;
-export declare function artifactKindPrefix(kind: ArtifactKind): string;
-export declare function artifactNameSlug(kind: ArtifactKind, name: string, maxWords?: number): string;
-export declare function humanizeArtifactSlug(slug: string): string;
-//# sourceMappingURL=artifact-names.d.ts.map

package/dist/artifact-names.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"artifact-names.d.ts","sourceRoot":"","sources":["../src/artifact-names.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAyBtD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAE7D;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,QAAQ,SAAI,GACX,MAAM,CAiBR;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASzD"}

package/dist/artifact-names.js

@@ -1,56 +0,0 @@
-const STOP_WORDS = new Set([
-    "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for", "of",
-    "with", "by", "from", "as", "is", "was", "are", "were", "been", "be",
-    "have", "has", "had", "do", "does", "did", "will", "would", "could",
-    "should", "may", "might", "must", "shall", "can", "need", "this", "that",
-    "these", "those", "it", "its", "my", "your", "his", "her", "our", "their",
-    "what", "which", "who", "whom", "whose", "where", "when", "why", "how",
-    "all", "each", "every", "both", "few", "more", "most", "other", "some",
-    "such", "no", "nor", "not", "only", "own", "same", "so", "than", "too",
-    "very", "just", "also",
-]);
-const KIND_PREFIXES = {
-    video: "vid",
-    image: "img",
-    audio: "aud",
-    script: "script",
-    character: "char",
-    prompt: "prompt",
-    scene: "scene",
-    final: "final",
-};
-export function isArtifactNameStopWord(word) {
-    return STOP_WORDS.has(word.toLowerCase());
-}
-export function artifactKindPrefix(kind) {
-    return KIND_PREFIXES[kind];
-}
-export function artifactNameSlug(kind, name, maxWords = 4) {
-    if (kind === "final")
-        return "final";
-    const prefix = artifactKindPrefix(kind);
-    const words = name
-        .toLowerCase()
-        .replace(/[^a-z0-9\s-]/g, "")
-        .split(/[\s-]+/)
-        .filter((word) => word.length > 0
-        && word !== prefix
-        && !isArtifactNameStopWord(word));
-    const deduped = [];
-    for (const word of words) {
-        if (deduped.at(-1) !== word)
-            deduped.push(word);
-    }
-    const slug = deduped.slice(0, Math.max(1, maxWords)).join("-");
-    return `${prefix}-${slug || "untitled"}`;
-}
-export function humanizeArtifactSlug(slug) {
-    return slug
-        .replace(/^[a-z]+-/, "")
-        .split("-")
-        .map((word) => word.length === 0
-        ? word
-        : word.charAt(0).toUpperCase() + word.slice(1))
-        .join(" ");
-}
-//# sourceMappingURL=artifact-names.js.map

package/dist/artifact-names.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"artifact-names.js","sourceRoot":"","sources":["../src/artifact-names.ts"],"names":[],"mappings":"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"}

package/dist/resolver.d.ts

@@ -1,15 +0,0 @@
-import type { EngineError, ResolvedArtifact, Result } from "./engine-types.js";
-import { EngineContext } from "./context.js";
-export declare function createResolverApi(context: EngineContext): {
-    parseTags: typeof parseArtifactTags;
-    resolveAll: (text: string) => Promise<Result<{
-        resolved: ResolvedArtifact[];
-        unresolved: string[];
-    }, EngineError>>;
-    expandSlotRefs: typeof expandSlotRefs;
-};
-export declare function parseArtifactTags(text: string): string[];
-export declare function expandSlotRefs(text: string, slots: Array<{
-    slug: string;
-}>): string;
-//# sourceMappingURL=resolver.d.ts.map

package/dist/resolver.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EAChB,MAAM,EACP,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,aAAa,EAAY,MAAM,cAAc,CAAC;AAOvD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa;;uBAI5C,MAAM,KACX,OAAO,CACR,MAAM,CACJ;QAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,EACtD,WAAW,CACZ,CACF;;EAGJ;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMxD;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7B,MAAM,CAKR"}

package/dist/resolver.js

@@ -1,81 +0,0 @@
-import * as path from "node:path";
-import { ok } from "./engine-types.js";
-import { resultOf } from "./context.js";
-import { createFilesApi } from "./files.js";
-import { findPrimaryMediaFile } from "./media.js";
-const TAG_PATTERN = /@([a-zA-Z0-9]+-[a-zA-Z0-9_-]+)/g;
-const SLOT_PATTERN = /@s(\d{2})/g;
-export function createResolverApi(context) {
-    return {
-        parseTags: parseArtifactTags,
-        resolveAll: (text) => resolveAllArtifacts(context, text),
-        expandSlotRefs,
-    };
-}
-export function parseArtifactTags(text) {
-    const tags = [];
-    for (const match of text.matchAll(TAG_PATTERN)) {
-        if (match[1])
-            tags.push(match[1]);
-    }
-    return [...new Set(tags)];
-}
-export function expandSlotRefs(text, slots) {
-    return text.replace(SLOT_PATTERN, (match, digits) => {
-        const slot = slots[Number.parseInt(digits, 10) - 1];
-        return slot?.slug ? `@${slot.slug}` : match;
-    });
-}
-async function resolveAllArtifacts(context, text) {
-    return resultOf(async () => {
-        const tags = parseArtifactTags(text);
-        if (tags.length === 0) {
-            return ok({ resolved: [], unresolved: [] });
-        }
-        const rows = context.store.db
-            .prepare(`SELECT artifact_id, slug, kind, created_at
-         FROM artifacts`)
-            .all();
-        const bySlug = new Map(rows.map((row) => [row.slug, row]));
-        const files = createFilesApi(context);
-        const resolved = [];
-        const unresolved = [];
-        for (const tag of tags) {
-            const candidates = [
-                tag,
-                `img-${tag}`,
-                `vid-${tag}`,
-                `aud-${tag}`,
-                `script-${tag}`,
-                `char-${tag}`,
-                `prompt-${tag}`,
-                `scene-${tag}`,
-            ];
-            const row = candidates
-                .map((candidate) => bySlug.get(candidate))
-                .find((candidate) => candidate !== undefined);
-            if (!row) {
-                unresolved.push(tag);
-                continue;
-            }
-            const manifest = await files.manifest(row.artifact_id);
-            if (!manifest.ok)
-                return manifest;
-            const primary = findPrimaryMediaFile(manifest.value.files, row.slug) ??
-                manifest.value.files[0] ??
-                null;
-            resolved.push({
-                tag: `@${tag}`,
-                artifactId: row.artifact_id,
-                artifactSlug: row.slug,
-                artifactType: row.kind,
-                filePath: primary
-                    ? path.join(manifest.value.path, primary.name)
-                    : null,
-                workspacePath: manifest.value.path,
-            });
-        }
-        return ok({ resolved, unresolved });
-    });
-}
-//# sourceMappingURL=resolver.js.map

package/dist/resolver.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"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"}