studiograph 1.3.48-next.21 → 1.3.48-next.211

package/dist/services/asset-import-service.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Asset Import Service — the asset-as-embed core (Phase B).
+ *
+ * Replaced the old "upload as a self-owning `asset` entity, convert later"
+ * flow (the `uploadAsset` primitive + a `convertAsset` orchestrator, both
+ * removed in Phase B2/E). An import now:
+ *
+ *   1. Stores the binary as a FREE-STANDING asset owned by the FOLDER (the
+ *      repo), via graph.uploadAsset's `owner` override (Phase A). The blob +
+ *      assets.db row belong to the folder, never to any entity — so deleting
+ *      the entity that embeds it leaves the asset intact + re-embeddable.
+ *   2. Seeds a properly-TYPED graph entity whose BODY embeds the asset, exactly
+ *      as a user would type it — the reference lives in the markdown, not the
+ *      frontmatter:
+ *        image                 → `material`, body `![name](url)` (inline embed)
+ *        opaque binary         → `material`, body `[name](url)` (download link)
+ *        docx / pdf            → `document`, body = a `[name](url)` source link
+ *                                (extraction is lossy) + an "Extracted text"
+ *                                heading + the extracted text
+ *        xlsx                  → `dataset` × N (pure-CSV body; the CSV is a
+ *                                faithful translation so no body reference —
+ *                                the source xlsx is invisible `asset_ref`
+ *                                provenance in frontmatter, the lone exception)
+ *
+ * Decisions (see ~/.claude/plans/asset-as-embed.md; body-embed model 2026-06-01):
+ *   - NO asset-text sidecar is written. Extraction runs in-memory ONLY to seed
+ *     the body, which the vector indexer indexes natively.
+ *   - Body embeds point at the FREE-STANDING, folder-owned asset (Phase A/B
+ *     storage is unchanged → still delete-safe, re-embeddable, many-to-many).
+ *     A broken/missing embed renders as a compact inline note via the editor's
+ *     image-render layer (live-preview.ts), NOT detail-page chrome.
+ *   - On entity-create failure AFTER the blob is stored, roll back with the same
+ *     3-step compensating delete asset-finalize-service uses: delete any created
+ *     entity (keepAssets) → delete the blob → delete the index row. (Relaxes to
+ *     "leave the folder-owned asset" once Phase D surfaces ownerless assets.)
+ *   - xlsx with more than XLSX_SHEET_CAP sheets does NOT fan out — it falls back
+ *     to a single `material` (the binary is preserved; no unbounded entity churn).
+ *
+ *   IMPORT(file, folder)
+ *     ├─ store bytes  → {assetId}/{filename}   owner = { folder, repo }
+ *     ├─ seed body (in-memory; NO sidecar) — embed/link in the markdown
+ *     └─ create typed entity(ies)
+ *          image/opaque → material · docx/pdf → document · xlsx → dataset×N
+ *   FAIL after store  → delete created entities (keepAssets) → delete blob → delete index row
+ */
+import type { BaseGraphManager } from '../core/graph.js';
+import type { EntityType } from '../core/validation.js';
+import type { GitUser } from './git.js';
+export interface ImportAssetAsEntityOptions {
+    graph: BaseGraphManager;
+    /** Original filename from the client. Only the basename is used. */
+    filename: string;
+    buffer: Buffer;
+    /** Repo-relative subfolder for the new entity's .md file(s). */
+    folderPath?: string;
+    /** Override entity name; defaults to the title-cased filename stem. */
+    name?: string;
+    user?: GitUser;
+    /** Defer the git commit so the caller can batch (multi-file import). */
+    skipCommit?: boolean;
+    /** Auth user id of the uploader (web). Recorded in assets.db for the
+     *  uploader+owner delete rule. Null for CLI/import/agent. */
+    uploaderUserId?: string | null;
+}
+/** One typed entity created by the import (1 for doc/material, N for xlsx). */
+export interface ImportedEntity {
+    entityId: string;
+    entityType: EntityType;
+    /** Absolute path of the created `.md` file (for the batched commit). */
+    filePath: string;
+}
+export interface ImportAssetAsEntityResult {
+    /** The free-standing asset's immutable storage UUID. */
+    assetId: string;
+    /** Canonical serving URL for the stored asset. */
+    asset_url: string;
+    /** Every typed entity created (body embeds the asset; only `dataset` carries
+     *  `asset_ref` frontmatter — see seedUnits). */
+    entities: ImportedEntity[];
+}
+/**
+ * Import a binary as a typed graph entity that embeds a free-standing,
+ * folder-owned asset. Returns the assetId + every created entity. Throws on
+ * unsupported extension / empty buffer / unconfigured asset storage, and on
+ * entity-create failure (after rolling back the stored blob + index row).
+ */
+export declare function importAssetAsEntity(opts: ImportAssetAsEntityOptions): Promise<ImportAssetAsEntityResult>;
+export interface CreateEntityFromAssetOptions {
+    graph: BaseGraphManager;
+    /** Immutable id of an EXISTING free-standing asset (assets.db row + blob). */
+    assetId: string;
+    /** Override entity name; defaults to the asset's stored name / filename stem. */
+    name?: string;
+    /** Repo-relative subfolder; defaults to the asset's own folder (repo root). */
+    folderPath?: string;
+    user?: GitUser;
+    skipCommit?: boolean;
+}
+/**
+ * The second import "door": create a properly-TYPED entity that embeds an asset
+ * ALREADY in the store — by its assetId — instead of fresh bytes. This is what
+ * makes deletion reversible: delete an entry, the free-standing asset survives
+ * in the manager, and this re-embeds it into a new entry. Same body-seeding as
+ * the import door (auto-derived type, re-extracted text for docs/sheets), but
+ * NO upload and NO asset-rollback — the asset pre-exists and may be embedded
+ * elsewhere, so a create failure only rolls back the new entities.
+ *
+ * Throws if the asset doesn't exist, storage isn't configured, or the stored
+ * bytes can't be read back for extraction.
+ */
+export declare function createEntityFromAsset(opts: CreateEntityFromAssetOptions): Promise<ImportAssetAsEntityResult>;

package/dist/services/asset-import-service.js

@@ -0,0 +1,394 @@
+/**
+ * Asset Import Service — the asset-as-embed core (Phase B).
+ *
+ * Replaced the old "upload as a self-owning `asset` entity, convert later"
+ * flow (the `uploadAsset` primitive + a `convertAsset` orchestrator, both
+ * removed in Phase B2/E). An import now:
+ *
+ *   1. Stores the binary as a FREE-STANDING asset owned by the FOLDER (the
+ *      repo), via graph.uploadAsset's `owner` override (Phase A). The blob +
+ *      assets.db row belong to the folder, never to any entity — so deleting
+ *      the entity that embeds it leaves the asset intact + re-embeddable.
+ *   2. Seeds a properly-TYPED graph entity whose BODY embeds the asset, exactly
+ *      as a user would type it — the reference lives in the markdown, not the
+ *      frontmatter:
+ *        image                 → `material`, body `![name](url)` (inline embed)
+ *        opaque binary         → `material`, body `[name](url)` (download link)
+ *        docx / pdf            → `document`, body = a `[name](url)` source link
+ *                                (extraction is lossy) + an "Extracted text"
+ *                                heading + the extracted text
+ *        xlsx                  → `dataset` × N (pure-CSV body; the CSV is a
+ *                                faithful translation so no body reference —
+ *                                the source xlsx is invisible `asset_ref`
+ *                                provenance in frontmatter, the lone exception)
+ *
+ * Decisions (see ~/.claude/plans/asset-as-embed.md; body-embed model 2026-06-01):
+ *   - NO asset-text sidecar is written. Extraction runs in-memory ONLY to seed
+ *     the body, which the vector indexer indexes natively.
+ *   - Body embeds point at the FREE-STANDING, folder-owned asset (Phase A/B
+ *     storage is unchanged → still delete-safe, re-embeddable, many-to-many).
+ *     A broken/missing embed renders as a compact inline note via the editor's
+ *     image-render layer (live-preview.ts), NOT detail-page chrome.
+ *   - On entity-create failure AFTER the blob is stored, roll back with the same
+ *     3-step compensating delete asset-finalize-service uses: delete any created
+ *     entity (keepAssets) → delete the blob → delete the index row. (Relaxes to
+ *     "leave the folder-owned asset" once Phase D surfaces ownerless assets.)
+ *   - xlsx with more than XLSX_SHEET_CAP sheets does NOT fan out — it falls back
+ *     to a single `material` (the binary is preserved; no unbounded entity churn).
+ *
+ *   IMPORT(file, folder)
+ *     ├─ store bytes  → {assetId}/{filename}   owner = { folder, repo }
+ *     ├─ seed body (in-memory; NO sidecar) — embed/link in the markdown
+ *     └─ create typed entity(ies)
+ *          image/opaque → material · docx/pdf → document · xlsx → dataset×N
+ *   FAIL after store  → delete created entities (keepAssets) → delete blob → delete index row
+ */
+import { extname, basename } from 'path';
+import { resolveFormat } from '../core/format-registry.js';
+import { isAssetUploadExtension, safeFilename } from './assets/base.js';
+import { publicUrlForAssetId } from './assets/index.js';
+import { createWithCollisionRetry } from './import-service.js';
+import { extractSidecarText } from './asset-sidecar-service.js';
+import { convertDocxToMarkdown, convertPdfToNoteText, convertXlsxToDatasets, XLSX_SHEET_CAP, CONVERT_MAX_BYTES, } from './convert-service.js';
+import { log } from '../utils/log.js';
+const slugify = (str) => str.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const formatName = (slug) => slug.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+/** Map a file's format extractor to the typed entity it imports to. */
+function targetTypeFor(extractor) {
+    if (extractor === 'pdf' || extractor === 'docx')
+        return 'document';
+    if (extractor === 'xlsx')
+        return 'dataset';
+    // image-caption (images) + null (opaque: zip/fig/video/audio/psd/ai/sketch)
+    return 'material';
+}
+/**
+ * Import a binary as a typed graph entity that embeds a free-standing,
+ * folder-owned asset. Returns the assetId + every created entity. Throws on
+ * unsupported extension / empty buffer / unconfigured asset storage, and on
+ * entity-create failure (after rolling back the stored blob + index row).
+ */
+export async function importAssetAsEntity(opts) {
+    const { graph, buffer, folderPath, user, skipCommit = false } = opts;
+    const onlyName = basename(opts.filename);
+    const ext = extname(onlyName).toLowerCase();
+    if (!isAssetUploadExtension(onlyName)) {
+        throw new Error(`Unsupported asset extension: ${ext || '(none)'}`);
+    }
+    if (!buffer || buffer.length === 0) {
+        throw new Error('Asset import received an empty buffer');
+    }
+    // Probe asset storage before mutating anything — a clear error beats a
+    // half-stored asset with nowhere to point at (mirrors uploadAsset).
+    try {
+        await graph.listAssets('asset', '__check__');
+    }
+    catch (err) {
+        if (err.message?.includes('not configured')) {
+            throw new Error('Asset storage is not configured for this workspace.');
+        }
+        // entity-not-found etc. just means storage IS configured.
+    }
+    // The asset-as-embed model requires the immutable-key index (assets.db): the
+    // body points at the stored binary by assetId. Verify it's wired BEFORE
+    // uploading — otherwise uploadAsset could store a legacy blob and return no
+    // assetId, and the post-upload guard would throw with the bytes orphaned.
+    if (!graph.getAssetIndex()) {
+        throw new Error('Asset import requires the immutable-key asset index (assets.db).');
+    }
+    const format = resolveFormat(onlyName);
+    const targetType = targetTypeFor(format.extractor);
+    const stem = onlyName.replace(/\.[^.]+$/, '');
+    const baseId = (slugify(stem).slice(0, 80).replace(/-$/, '')) || `asset-${Date.now()}`;
+    const name = opts.name ?? formatName(baseId);
+    const now = new Date().toISOString();
+    const userHandle = user?.email?.split('@')[0] ?? user?.name ?? 'import';
+    // ── 1. Store the binary FOLDER-OWNED (free-standing). ──────────────────────
+    // entityType/entityId args are ignored for ownership when `owner` is set;
+    // we pass the target type + baseId as harmless metadata. The immutable-key
+    // path returns the assetId + the index filename we need for rollback.
+    const storedFilename = `${Date.now()}-${safeFilename(onlyName)}`;
+    const uploaded = await graph.uploadAsset(targetType, baseId, storedFilename, buffer, undefined, {
+        uploaderUserId: opts.uploaderUserId ?? null,
+        owner: { type: 'folder', id: graph.repoName },
+    });
+    const assetId = uploaded.assetId;
+    if (!assetId) {
+        // No immutable-key index wired — the asset-as-embed model requires it.
+        throw new Error('Asset import requires the immutable-key asset index (assets.db).');
+    }
+    const asset_url = uploaded.publicUrl;
+    const indexedFilename = uploaded.filename;
+    // ── 2–3. Seed the body/bodies (in-memory, NO sidecar) + create the typed
+    // entity(ies). On ANY failure, roll back the entities (inside the helper)
+    // AND the blob we just stored (here) — the import owns the new asset, so an
+    // aborted import must leave nothing behind. ────────────────────────────────
+    const isImage = format.extractor === 'image-caption';
+    let created;
+    try {
+        created = await seedAndCreateEntities(graph, {
+            buffer, ext, targetType, baseId, name, assetId, assetUrl: asset_url, isImage,
+            folderPath, user, now, userHandle,
+        });
+    }
+    catch (err) {
+        await graph.deleteAssetById(assetId, indexedFilename);
+        throw err instanceof Error ? err : new Error('Asset import failed');
+    }
+    if (!skipCommit) {
+        const git = graph.getGitService();
+        if (git) {
+            const commitUser = user ?? { id: 'import', name: 'Import', email: 'import@studiograph' };
+            git.commitAll(`Import ${onlyName} → ${created.length} ${created.length === 1 ? 'entry' : 'entries'}`, commitUser);
+        }
+    }
+    return { assetId, asset_url, entities: created };
+}
+/**
+ * The second import "door": create a properly-TYPED entity that embeds an asset
+ * ALREADY in the store — by its assetId — instead of fresh bytes. This is what
+ * makes deletion reversible: delete an entry, the free-standing asset survives
+ * in the manager, and this re-embeds it into a new entry. Same body-seeding as
+ * the import door (auto-derived type, re-extracted text for docs/sheets), but
+ * NO upload and NO asset-rollback — the asset pre-exists and may be embedded
+ * elsewhere, so a create failure only rolls back the new entities.
+ *
+ * Throws if the asset doesn't exist, storage isn't configured, or the stored
+ * bytes can't be read back for extraction.
+ */
+export async function createEntityFromAsset(opts) {
+    const { graph, assetId, folderPath, user, skipCommit = false } = opts;
+    const index = graph.getAssetIndex();
+    if (!index) {
+        throw new Error('Asset operations require the immutable-key asset index (assets.db).');
+    }
+    const row = index.get(assetId);
+    if (!row)
+        throw new Error(`Asset ${assetId} not found`);
+    const service = graph.getAssetService();
+    if (!service)
+        throw new Error('Asset storage is not configured for this workspace.');
+    // Derive the type + extractor from the STORED filename (carries the original
+    // extension), exactly as import derives them from the upload filename.
+    const ext = extname(row.filename).toLowerCase();
+    const format = resolveFormat(row.filename);
+    const targetType = targetTypeFor(format.extractor);
+    const isImage = format.extractor === 'image-caption';
+    // Only documents/datasets read the bytes (to re-extract text for the body);
+    // images/opaque materials seed their body from the URL alone. And an
+    // oversized doc/sheet would fall back to a download-only material anyway, so
+    // skip the (potentially large) blob fetch + force the material seed — using
+    // the size recorded in the index. This avoids streaming bytes we'd discard.
+    const oversized = row.size != null && row.size > CONVERT_MAX_BYTES;
+    const needsExtraction = (targetType === 'document' || targetType === 'dataset') && !oversized;
+    let buffer = Buffer.alloc(0);
+    if (needsExtraction) {
+        try {
+            buffer = await service.download(`${assetId}/${row.filename}`);
+        }
+        catch (err) {
+            throw new Error(`Could not read stored asset ${assetId}: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // Without extraction (image/opaque, or an oversized doc/sheet) the body is a
+    // material embed/link built from the URL — matches the import door's fallback.
+    const seedType = needsExtraction ? targetType : 'material';
+    const asset_url = publicUrlForAssetId(assetId, row.filename);
+    // Prefer the asset's stored name; fall back to a title-cased filename stem.
+    const stem = basename(row.filename).replace(/^\d+-/, '').replace(/\.[^.]+$/, '');
+    const baseId = (slugify(stem).slice(0, 80).replace(/-$/, '')) || `asset-${assetId.slice(0, 8)}`;
+    const name = opts.name ?? row.name ?? formatName(baseId);
+    const now = new Date().toISOString();
+    const userHandle = user?.email?.split('@')[0] ?? user?.name ?? 'web';
+    const created = await seedAndCreateEntities(graph, {
+        buffer, ext, targetType: seedType, baseId, name, assetId, assetUrl: asset_url, isImage,
+        folderPath, user, now, userHandle,
+    });
+    if (!skipCommit) {
+        const git = graph.getGitService();
+        if (git) {
+            const commitUser = user ?? { id: 'web', name: 'Web', email: 'web@studiograph' };
+            git.commitAll(`Create ${created.length === 1 ? 'entry' : 'entries'} from asset ${name}`, commitUser);
+        }
+    }
+    return { assetId, asset_url, entities: created };
+}
+/**
+ * Build the typed-entity unit(s) for a stored asset, seeding the body with a
+ * markdown embed/link to the free-standing asset — exactly what a user would
+ * type. The reference lives in the BODY, never the frontmatter (the lone
+ * exception is dataset, see below). By kind:
+ *   - image  → `material`, body `![name](url)` (renders inline in the editor).
+ *   - opaque → `material`, body `[name](url)` (can't extract; a plain link).
+ *   - docx/pdf → `document`, body = a `[name](url)` source link + extracted text.
+ *   - xlsx → `dataset` × N (pure-CSV body, one per non-empty sheet). A CSV body
+ *     can't hold a markdown link, so the source xlsx is recorded as invisible
+ *     `asset_ref` provenance in frontmatter (added by the caller via extra),
+ *     NOT a body embed. Falls back to a single material when the sheet count
+ *     exceeds the cap / there are no usable sheets.
+ *
+ * Guiding principle: render a body reference only when the body can't faithfully
+ * hold the asset — image embed IS the asset, opaque needs a link, a document's
+ * extraction is lossy so it links the original, a dataset's CSV is faithful so
+ * it needs nothing visible.
+ */
+async function seedUnits(buffer, ext, targetType, baseId, name, assetId, assetUrl, isImage) {
+    // A single material wrapping the binary — the type when there's nothing to
+    // extract (image/opaque) AND the fallback when we choose NOT to parse a
+    // doc/sheet (oversized, too many sheets, no usable data). Its body is the
+    // asset itself: an inline image embed for images, a download link otherwise.
+    const materialBody = isImage ? `![${name}](${assetUrl})` : `[${name}](${assetUrl})`;
+    const materialFallback = () => [
+        { entityType: 'material', baseId, name, content: materialBody },
+    ];
+    if (targetType === 'document') {
+        // docx → structured markdown (mammoth→turndown); pdf → reflowed text.
+        // pdf/docx with no extractable text still seeds the download link (NOT an
+        // error — the original is reachable, the body just has no prose).
+        let text = '';
+        if (ext === '.docx') {
+            // DoS guard: mammoth parses docx synchronously on the request thread.
+            // A doc past CONVERT_MAX_BYTES is preserved as a material (download link)
+            // rather than parsed (same guard the convert + sidecar paths use). pdf is
+            // already size-capped inside extractSidecarText, so it needs no guard.
+            if (buffer.length > CONVERT_MAX_BYTES) {
+                log.info(`[asset-import] ${name}: ${buffer.length} bytes > ${CONVERT_MAX_BYTES} cap; importing as material (unparsed)`);
+                return materialFallback();
+            }
+            // mammoth throws on an encrypted / corrupt / non-OOXML .docx. Degrade to a
+            // download-only material rather than aborting the import (which would roll
+            // back the stored binary) — matches the pdf branch, where extractSidecarText
+            // swallows errors to '' and still produces a download-only document.
+            try {
+                text = await convertDocxToMarkdown(buffer);
+            }
+            catch (err) {
+                log.warn(`[asset-import] ${name}: docx parse failed (${err instanceof Error ? err.message : err}); importing as material`);
+                return materialFallback();
+            }
+        }
+        else {
+            const extracted = await extractSidecarText(buffer, 'pdf', baseId);
+            text = convertPdfToNoteText(extracted.text);
+        }
+        // Body layout: the source file FIRST (renders as a download chip — the
+        // original is one click away since extraction is lossy), then a heading
+        // that frames the body as machine-extracted (not authored) text, then the
+        // text itself. An empty-text pdf seeds just the chip (no empty heading).
+        // The link text is the file's name (same as the material/opaque chips), so
+        // every imported asset chip reads alike; the chip's own ↓-button carries
+        // the download affordance, so the label needn't repeat it.
+        const sourceLink = `[${name}](${assetUrl})`;
+        const parts = text ? [sourceLink, '## Extracted text', text] : [sourceLink];
+        const body = parts.join('\n\n');
+        return [{ entityType: 'document', baseId, name, content: body }];
+    }
+    if (targetType === 'dataset') {
+        // DoS guard: SheetJS decompresses + parses the whole workbook synchronously
+        // before the sheet cap can apply, so bound the input bytes first.
+        if (buffer.length > CONVERT_MAX_BYTES) {
+            log.info(`[asset-import] ${name}: ${buffer.length} bytes > ${CONVERT_MAX_BYTES} cap; importing as material (unparsed)`);
+            return materialFallback();
+        }
+        // SheetJS throws on an encrypted / corrupt workbook. Degrade to a
+        // download-only material rather than aborting the import + rolling back the
+        // stored binary (parity with the docx + empty-pdf fallbacks).
+        let conv;
+        try {
+            conv = convertXlsxToDatasets(buffer, name, { maxSheets: XLSX_SHEET_CAP });
+        }
+        catch (err) {
+            log.warn(`[asset-import] ${name}: xlsx parse failed (${err instanceof Error ? err.message : err}); importing as material`);
+            return materialFallback();
+        }
+        if (conv.exceededCap) {
+            // Too many sheets to fan out safely — keep the binary as a material.
+            log.info(`[asset-import] ${name}: ${conv.totalSheets} sheets > cap ${XLSX_SHEET_CAP}; importing as material`);
+            return materialFallback();
+        }
+        if (conv.totalSheets === 0) {
+            // No non-empty sheets — nothing to tabulate; keep the binary as material.
+            return materialFallback();
+        }
+        // One dataset per sheet. The CSV body is a FAITHFUL translation of the data
+        // so it needs no visible source reference; asset_ref (added by the caller)
+        // records the source xlsx as invisible provenance, source_sheet the sheet.
+        return conv.sheets.map(s => ({
+            entityType: 'dataset',
+            baseId: slugify(s.name) || `${baseId}-sheet`,
+            name: s.name,
+            content: s.csv,
+            extra: { source_sheet: s.sheetName, asset_ref: assetId },
+        }));
+    }
+    // material — image or opaque binary. The body IS the asset (inline image
+    // embed, or a download link for opaque binaries). No text extraction.
+    return materialFallback();
+}
+/**
+ * Roll back entities created by a failed seed→create (mirrors
+ * asset-finalize-service). `keepAssets` so it NEVER touches the blob — the
+ * asset's lifecycle is the caller's concern: the import door rolls the blob
+ * back too (it just created it via graph.deleteAssetById); the
+ * create-from-asset door leaves the pre-existing, possibly-shared asset alone.
+ * Best-effort + isolated so the original error still surfaces.
+ */
+async function rollbackEntities(graph, created, user) {
+    for (const e of created) {
+        try {
+            await graph.delete(e.entityType, e.entityId, `Rollback failed asset import: ${e.entityId}`, user, { keepAssets: true });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!/not found/i.test(msg)) {
+                log.warn(`[asset-import] rollback delete of ${e.entityType}/${e.entityId} failed: ${msg}`);
+            }
+        }
+    }
+}
+/**
+ * Seed the typed-entity body/bodies for an ALREADY-STORED asset and create the
+ * entities. Shared by both doors — import (door 1, fresh upload) and
+ * create-from-asset (door 2, existing assetId). On any failure rolls back ONLY
+ * the entities it created (never the asset) and rethrows, so each door owns its
+ * own asset-rollback policy.
+ */
+async function seedAndCreateEntities(graph, p) {
+    const units = await seedUnits(p.buffer, p.ext, p.targetType, p.baseId, p.name, p.assetId, p.assetUrl, p.isImage);
+    const created = [];
+    try {
+        for (const unit of units) {
+            // No universal `asset_ref` frontmatter: under the body-embed model the
+            // reference lives IN THE BODY (image embed / download link), not the
+            // header. The ONE exception is `dataset` — its body must stay valid CSV,
+            // so it can't hold a body embed; it carries `asset_ref` (via unit.extra)
+            // as invisible provenance back to the source xlsx instead.
+            const data = {
+                entity_type: unit.entityType,
+                entity_id: unit.baseId,
+                name: unit.name,
+                created_at: p.now,
+                updated_at: p.now,
+                created_by: p.userHandle,
+                updated_by: p.userHandle,
+                ...(unit.extra ?? {}),
+            };
+            const { entityId, path } = await createWithCollisionRetry(graph, {
+                entityType: unit.entityType,
+                entityId: unit.baseId,
+                data,
+                content: unit.content,
+                folderPath: p.folderPath,
+                skipCommit: true,
+                user: p.user,
+            });
+            created.push({ entityId, entityType: unit.entityType, filePath: path });
+        }
+    }
+    catch (err) {
+        await rollbackEntities(graph, created, p.user);
+        throw err;
+    }
+    return created;
+}
+//# sourceMappingURL=asset-import-service.js.map

package/dist/services/asset-import-service.js.map

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

package/dist/services/asset-index-sweep.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Asset index sweep (asset-as-embed) — the boot/recovery trigger of the image
+ * caption / OCR pass.
+ *
+ * OV1: this is SEPARATE from the text/FTS reindex. The vector reindex (boot /
+ * git-pull / reconcile) only refreshes the FTS+embedding text for changed
+ * entries; it deliberately does NOT fire vision calls. This sweep is the one
+ * place that drives image captioning, so vision spend is intentional and
+ * bounded, never a side effect of a routine reindex.
+ *
+ * Asset-as-embed: derivation is keyed by the immutable assetId (the assets.db
+ * row), NOT an `asset` entity — that type was retired by Phase F. Per indexable
+ * IMAGE row (assets.db `media_type === 'image'`, non-SVG):
+ *  - PERF1: reads the unfinished set from the LanceDB index-state table (one
+ *    query) and skips rows already `full`/`failed` at the current version.
+ *  - Migration (Codex CRITICAL): a row with NO state, or a row at a STALE
+ *    `index_version`, is RE-derived — undefined is never treated as "done".
+ *    `failed` at the current version is terminal (don't re-bill every boot).
+ *  - Caption + OCR (bounded fan-out, A3). When captioning is unreachable
+ *    (gateway / disabled / non-vision model) the image is left honestly
+ *    `pending`, so flipping the gate or model later picks it up.
+ *  - SVG is skipped — transitional until sanitize-html is wired.
+ *
+ * On a successful caption the text is stored in `assets.db.caption` (decision
+ * D1 — DB column, NO sidecar; survives deletion of any embedding entry) and the
+ * entries that EMBED the asset are re-upserted so the caption folds into their
+ * search text (decision D2). The expensive work (vision, byte downloads) runs
+ * CONCURRENTLY (bounded); the LanceDB index-state + embedder writes run SERIALLY
+ * through `vectorService` (optimistic concurrency — racing mergeInserts conflict).
+ */
+import { type CaptionModelConfig, type CaptionCompleteFn } from './asset-caption-service.js';
+import { type VectorService } from './vector-service.js';
+import type { AssetIndexService } from './assets/asset-index-service.js';
+import type { EntityFile } from '../core/graph.js';
+/** Structural slice of a graph the sweep needs (avoids an import cycle). */
+interface SweepGraph {
+    /** All entities in the repo — scanned once per sweep to find the entries
+     *  that embed a freshly-captioned asset, for re-index. */
+    list(): EntityFile[];
+    /** Download an immutable-keyed asset's bytes by id + filename. */
+    downloadAssetById(assetId: string, filename: string): Promise<Buffer>;
+}
+/** Structural slice of the workspace manager the sweep needs. */
+export interface SweepWorkspaceManager {
+    vectorService?: VectorService;
+    getGraph(repoName: string): SweepGraph;
+    getAssetIndex(): AssetIndexService;
+}
+export interface AssetIndexSweepDeps {
+    workspaceManager: SweepWorkspaceManager;
+    repos: Array<{
+        name: string;
+        path?: string;
+    }>;
+    workspacePath: string;
+    /** Resolved inference coordinates for captioning; null when none configured. */
+    captionConfig: CaptionModelConfig | null;
+    /** Per-workspace gate (default-on). When false, images are left pending. */
+    captioningEnabled: boolean;
+}
+export interface AssetIndexSweepOptions {
+    log?: (msg: string) => void;
+    /** Bounded fan-out for vision + download (default 2 — vision is metered). */
+    concurrency?: number;
+    /** Test seam: inject the model call used for captioning. */
+    completeFn?: CaptionCompleteFn;
+    /** Safety cap on how many assets to derive in one sweep (default unlimited). */
+    maxAssets?: number;
+    /**
+     * Restrict the sweep to a specific set of assetIds. The live drain
+     * (AssetIndexQueue) passes the just-enqueued ids so a routine tick only
+     * touches new uploads, not the whole workspace; the boot recovery pass omits
+     * it and considers every image row. An empty set means "nothing to do" and
+     * the sweep returns immediately.
+     */
+    onlyAssets?: ReadonlySet<string>;
+}
+export interface AssetIndexSweepResult {
+    /** Indexable, in-scope image rows considered. */
+    scanned: number;
+    /** Captions freshly produced + stored. */
+    derived: number;
+    /** Assets that errored or produced no caption → recorded `failed`. */
+    failed: number;
+    /** Already-current (`full`/`failed` at current version) → untouched. */
+    skippedUpToDate: number;
+    /** Images we couldn't caption (gateway/disabled/non-vision) → left `pending`. */
+    leftPending: number;
+}
+/**
+ * Drive the caption / OCR pass for every image asset that needs it. Safe to
+ * call fire-and-forget at boot; resilient to per-asset failure.
+ */
+export declare function sweepAssetIndex(deps: AssetIndexSweepDeps, opts?: AssetIndexSweepOptions): Promise<AssetIndexSweepResult>;
+export {};