@mean-weasel/lineage 0.1.14 → 0.1.16

package/dist/server.js

@@ -5,7 +5,7 @@ import { existsSync as existsSync14 } from "node:fs";
 import { join as join14 } from "node:path";
 
 // src/server/assetCore.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync5, readdirSync as readdirSync2, readFileSync as readFileSync4, unlinkSync, writeFileSync as writeFileSync3 } from "node:fs";
+import { chmodSync as chmodSync2, existsSync as existsSync6, mkdirSync as mkdirSync5, readdirSync as readdirSync2, readFileSync as readFileSync4, unlinkSync, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname as dirname4, join as join6, resolve as resolve4 } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -288,7 +288,7 @@ import { join as join5 } from "node:path";
 
 // src/server/profileWriterLease.ts
 import { createHash as createHash3, randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
-import { existsSync as existsSync4, lstatSync, mkdirSync as mkdirSync3, readFileSync as readFileSync3, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync4, lstatSync as lstatSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync3, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname3, join as join4, resolve as resolve3 } from "node:path";
 
 // src/server/lineageProfiles.ts
@@ -296,13 +296,18 @@ import { createHash as createHash2, randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import {
   chmodSync,
+  closeSync,
   constants as fsConstants,
   copyFileSync as copyFileSync2,
   existsSync as existsSync3,
+  fsyncSync,
   linkSync,
+  lstatSync,
   mkdirSync as mkdirSync2,
+  openSync,
   readFileSync as readFileSync2,
   realpathSync,
+  renameSync,
   rmSync,
   statSync as statSync3,
   writeFileSync
@@ -344,13 +349,13 @@ function profileManifestPath(selector) {
   if (!profileIdPattern.test(value)) throw new Error(`Invalid profile ID: ${value}`);
   return { manifestPath: join3(lineageProfileRoot(), value, "profile.json"), namedProfileId: value };
 }
-function requiredString(record, key) {
-  const value = record[key];
+function requiredString(record2, key) {
+  const value = record2[key];
   if (typeof value !== "string" || !value.trim()) throw new Error(`Profile manifest requires a non-empty ${key}`);
   return value.trim();
 }
-function optionalString(record, key) {
-  const value = record[key];
+function optionalString(record2, key) {
+  const value = record2[key];
   if (value === void 0) return void 0;
   if (typeof value !== "string" || !value.trim()) throw new Error(`Profile manifest ${key} must be a non-empty string`);
   return value.trim();
@@ -401,15 +406,15 @@ function resolveLineageProfile(selector) {
     throw new Error(`Could not parse profile manifest ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
   }
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Profile manifest must be a JSON object");
-  const record = raw;
-  const schemaVersion = requiredString(record, "schema_version");
+  const record2 = raw;
+  const schemaVersion = requiredString(record2, "schema_version");
   if (schemaVersion !== lineageProfileSchemaVersion) throw new Error(`Unsupported profile schema_version: ${schemaVersion}`);
-  const profileId = requiredString(record, "profile_id");
+  const profileId = requiredString(record2, "profile_id");
   if (!profileIdPattern.test(profileId)) throw new Error(`Invalid profile ID: ${profileId}`);
   if (namedProfileId && namedProfileId !== profileId) {
     throw new Error(`Named profile ${namedProfileId} does not match immutable manifest profile_id ${profileId}`);
   }
-  const expectedRaw = record.expected_runtime;
+  const expectedRaw = record2.expected_runtime;
   if (expectedRaw !== void 0 && (!expectedRaw || typeof expectedRaw !== "object" || Array.isArray(expectedRaw))) {
     throw new Error("Profile expected_runtime must be an object");
   }
@@ -418,18 +423,18 @@ function resolveLineageProfile(selector) {
   const expectedVersion = expected ? optionalString(expected, "version") : void 0;
   const expectedCodeFingerprint = validateFingerprint(expected ? optionalString(expected, "code_fingerprint") : void 0, "expected_runtime.code_fingerprint");
   const expectedCodeOrigin = validateCodeOrigin(expected?.code_origin);
-  const migrationsRaw = record.required_schema_migrations;
+  const migrationsRaw = record2.required_schema_migrations;
   if (migrationsRaw !== void 0 && (!Array.isArray(migrationsRaw) || migrationsRaw.some((value) => typeof value !== "string" || !value.trim()))) {
     throw new Error("Profile required_schema_migrations must be an array of non-empty strings");
   }
-  const environment = validateEnvironment(requiredString(record, "environment"));
+  const environment = validateEnvironment(requiredString(record2, "environment"));
   const expectedChannel = validateChannel(expected?.channel);
   if (expectedChannel && expectedChannel !== environmentChannel(environment)) {
     throw new Error(`Profile environment ${environment} conflicts with expected runtime channel ${expectedChannel}`);
   }
   const manifest = {
-    asset_root: resolveManifestPath(manifestPath, requiredString(record, "asset_root")),
-    database_path: resolveManifestPath(manifestPath, requiredString(record, "database_path")),
+    asset_root: resolveManifestPath(manifestPath, requiredString(record2, "asset_root")),
+    database_path: resolveManifestPath(manifestPath, requiredString(record2, "database_path")),
     environment,
     ...expected ? {
       expected_runtime: {
@@ -443,7 +448,7 @@ function resolveLineageProfile(selector) {
     profile_id: profileId,
     ...migrationsRaw ? { required_schema_migrations: migrationsRaw.map((value) => value.trim()) } : {},
     schema_version: lineageProfileSchemaVersion,
-    service_origin: validateServiceOrigin(requiredString(record, "service_origin"))
+    service_origin: validateServiceOrigin(requiredString(record2, "service_origin"))
   };
   return { ...manifest, manifest_path: manifestPath, profile_fingerprint: lineageProfileFingerprint(manifest) };
 }
@@ -693,7 +698,7 @@ function errorCode(error) {
   return error && typeof error === "object" && "code" in error ? String(error.code) : void 0;
 }
 function readOwner(lockPath) {
-  const stat = lstatSync(lockPath);
+  const stat = lstatSync2(lockPath);
   if (!stat.isDirectory() || stat.isSymbolicLink()) {
     throw new Error(`Writer lease path is not a safe directory: ${lockPath}; manual inspection is required`);
   }
@@ -742,7 +747,7 @@ function reclaimDeadOwner(lockPath, owner) {
   const tokenFence = createHash3("sha256").update(owner.token).digest("hex").slice(0, 24);
   const tombstone = `${lockPath}.stale-${owner.pid}-${tokenFence}`;
   try {
-    renameSync(lockPath, tombstone);
+    renameSync2(lockPath, tombstone);
   } catch (error) {
     if (errorCode(error) === "ENOENT") return;
     throw error;
@@ -914,6 +919,10 @@ function lineageDb() {
       child_asset_id text not null references assets(id),
       relation_type text not null check (relation_type in ('derived_from')),
       created_at text not null,
+      summary text,
+      summary_created_by text check (summary_created_by in ('human', 'agent', 'system')),
+      summary_updated_by text check (summary_updated_by in ('human', 'agent', 'system')),
+      summary_updated_at text,
       unique (project_id, parent_asset_id, child_asset_id, relation_type)
     );
     create index if not exists edges_parent on asset_edges(project_id, parent_asset_id);
@@ -1197,6 +1206,7 @@ function lineageDb() {
       imported_asset_id text not null references assets(id),
       parent_asset_id text not null references assets(id),
       imported_at text not null,
+      edge_summary text,
       unique(job_id, output_index),
       unique(job_id, file_path)
     );
@@ -1285,6 +1295,11 @@ function lineageDb() {
     );
     create index if not exists agent_claim_events_claim_created on agent_claim_events(claim_id, created_at);
   `);
+  ensureColumn(database, "asset_edges", "summary", "text");
+  ensureColumn(database, "asset_edges", "summary_created_by", "text check (summary_created_by in ('human', 'agent', 'system'))");
+  ensureColumn(database, "asset_edges", "summary_updated_by", "text check (summary_updated_by in ('human', 'agent', 'system'))");
+  ensureColumn(database, "asset_edges", "summary_updated_at", "text");
+  ensureColumn(database, "generation_job_outputs", "edge_summary", "text");
   migrateAssetSelections(database);
   dropLegacyAssetSelectionRootUnique(database);
   ensureColumn(database, "asset_selections", "notes", "text");
@@ -1638,8 +1653,8 @@ function syncLedgerPlacement(project, assetId, placement) {
 function placeholders(values) {
   return values.map(() => "?").join(",");
 }
-function assetIdsForRecord(record, sources) {
-  return [.../* @__PURE__ */ new Set([record.canonical_asset_id, ...sources.map((source) => source.asset_id).filter(Boolean)])];
+function assetIdsForRecord(record2, sources) {
+  return [.../* @__PURE__ */ new Set([record2.canonical_asset_id, ...sources.map((source) => source.asset_id).filter(Boolean)])];
 }
 function reviewFromRow(row) {
   return {
@@ -1673,7 +1688,7 @@ function selectionFromRow(row) {
   };
 }
 function ledgerWorkflowStates(database, project, records, sources) {
-  const recordAssets = new Map(records.map((record) => [record.id, assetIdsForRecord(record, sources.filter((source) => source.record_id === record.id))]));
+  const recordAssets = new Map(records.map((record2) => [record2.id, assetIdsForRecord(record2, sources.filter((source) => source.record_id === record2.id))]));
   const assetIds = [...new Set([...recordAssets.values()].flat())];
   if (assetIds.length === 0) return {};
   const marker = placeholders(assetIds);
@@ -1692,11 +1707,11 @@ function ledgerWorkflowStates(database, project, records, sources) {
     from asset_selections
     where project_id = ? and asset_id in (${marker})
   `).all(project, ...assetIds);
-  return Object.fromEntries(records.map((record) => {
-    const ids = recordAssets.get(record.id) || [];
+  return Object.fromEntries(records.map((record2) => {
+    const ids = recordAssets.get(record2.id) || [];
     const review = reviews.find((row) => ids.includes(row.asset_id));
     const selection = selections.find((row) => ids.includes(row.asset_id));
-    return [record.id, {
+    return [record2.id, {
       review: review ? reviewFromRow(review) : void 0,
       placements: placements.filter((row) => ids.includes(row.asset_id)).map(placementFromRow),
       selection: selection ? selectionFromRow(selection) : void 0
@@ -2105,7 +2120,8 @@ function deleteObjectGuarded(project, assetId, confirmation) {
 }
 function ensureUploadDir() {
   const dir = join6(repoRoot, ".asset-scratch", "studio-uploads");
-  mkdirSync5(dir, { recursive: true });
+  mkdirSync5(dir, { recursive: true, mode: 448 });
+  chmodSync2(dir, 448);
   return dir;
 }
 function cleanupUploadedTemp(file) {
@@ -2148,6 +2164,32 @@ function lookupAssets(project, assetIds) {
 // src/server/assetLineage.ts
 import { join as join7 } from "node:path";
 
+// src/shared/edgeSummary.ts
+var edgeSummaryWordLimit = 2;
+var EdgeSummaryValidationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "EdgeSummaryValidationError";
+  }
+  code;
+};
+function normalizeEdgeSummary(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "string") throw new EdgeSummaryValidationError("not_text", "Edge summary must be text");
+  const words = value.trim().split(/\s+/u).filter(Boolean);
+  if (words.length === 0) return void 0;
+  if (words.length > edgeSummaryWordLimit) {
+    throw new EdgeSummaryValidationError("too_many_words", `Edge summary must contain at most ${edgeSummaryWordLimit} words`);
+  }
+  return words.join(" ");
+}
+function requireEdgeSummary(value) {
+  const summary = normalizeEdgeSummary(value);
+  if (!summary) throw new EdgeSummaryValidationError("required", "Edge summary is required");
+  return summary;
+}
+
 // src/server/assetLineageSelection.ts
 var LINEAGE_NEXT_VARIATION_LIMIT = 3;
 function selectionId(project, root, assetId) {
@@ -3578,6 +3620,41 @@ function rerollRequestId(project, root, node, timestamp) {
 function rowString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
+function lineageEdgeFromRow(row) {
+  const summary = rowString(row.summary);
+  const summaryCreatedBy = rowString(row.summary_created_by);
+  const summaryUpdatedBy = rowString(row.summary_updated_by);
+  const summaryUpdatedAt = rowString(row.summary_updated_at);
+  return {
+    id: String(row.id),
+    parent_asset_id: String(row.parent_asset_id),
+    child_asset_id: String(row.child_asset_id),
+    relation_type: row.relation_type,
+    created_at: String(row.created_at),
+    ...summary ? { summary } : {},
+    ...summaryCreatedBy ? { summary_created_by: summaryCreatedBy } : {},
+    ...summaryUpdatedBy ? { summary_updated_by: summaryUpdatedBy } : {},
+    ...summaryUpdatedAt ? { summary_updated_at: summaryUpdatedAt } : {}
+  };
+}
+function nextEdgeSummaryTimestamp(current) {
+  const currentMillis = current ? Date.parse(current) : Number.NaN;
+  const nextMillis = Number.isFinite(currentMillis) ? Math.max(Date.now(), currentMillis + 1) : Date.now();
+  return new Date(nextMillis).toISOString();
+}
+function expectedEdgeSummaryTimestamp(value) {
+  if (value === null) return null;
+  if (typeof value === "string" && value.length > 0) return value;
+  throw new LineageError("Edge summary update requires expectedSummaryUpdatedAt as a timestamp or null");
+}
+function validatedHumanEdgeSummary(value) {
+  try {
+    return requireEdgeSummary(value);
+  } catch (error) {
+    if (error instanceof EdgeSummaryValidationError) throw new LineageError(error.message);
+    throw error;
+  }
+}
 function rerollRequestFrom(row) {
   return {
     id: String(row.id),
@@ -3677,6 +3754,9 @@ function localPreviewUrl(project, localPath) {
   return `/api/assets/local-preview?${params.toString()}`;
 }
 function linkLineageAssets(project, fields) {
+  const summary = normalizeEdgeSummary(fields.summary);
+  if (summary && !fields.summaryActor) throw new LineageError("Lineage edge summary requires an explicit author");
+  if (!summary && fields.summaryActor) throw new LineageError("Lineage edge summary author requires a summary");
   const database = lineageDb();
   requireAsset3(database, project, fields.parentAssetId);
   requireAsset3(database, project, fields.childAssetId);
@@ -3695,25 +3775,135 @@ function linkLineageAssets(project, fields) {
     database.close();
     throw error;
   }
+  const createdAt = nowIso();
   const edge = {
     id: edgeId(project, fields.parentAssetId, fields.childAssetId),
     parent_asset_id: fields.parentAssetId,
     child_asset_id: fields.childAssetId,
     relation_type: "derived_from",
-    created_at: nowIso()
+    created_at: createdAt,
+    ...summary ? {
+      summary,
+      summary_created_by: fields.summaryActor,
+      summary_updated_by: fields.summaryActor,
+      summary_updated_at: createdAt
+    } : {}
   };
   if (!fields.confirmWrite) {
     database.close();
     return { ok: true, dryRun: true, edge };
   }
-  database.prepare(`
-    insert into asset_edges (id, project_id, parent_asset_id, child_asset_id, relation_type, created_at)
-    values (?, ?, ?, ?, 'derived_from', ?)
+  const inserted = database.prepare(`
+    insert into asset_edges (
+      id, project_id, parent_asset_id, child_asset_id, relation_type, created_at,
+      summary, summary_created_by, summary_updated_by, summary_updated_at
+    )
+    values (?, ?, ?, ?, 'derived_from', ?, ?, ?, ?, ?)
     on conflict(project_id, parent_asset_id, child_asset_id, relation_type) do nothing
-  `).run(edge.id, project, edge.parent_asset_id, edge.child_asset_id, edge.created_at);
+  `).run(
+    edge.id,
+    project,
+    edge.parent_asset_id,
+    edge.child_asset_id,
+    edge.created_at,
+    edge.summary || null,
+    edge.summary_created_by || null,
+    edge.summary_updated_by || null,
+    edge.summary_updated_at || null
+  );
+  if (inserted.changes === 0) {
+    const existingRow = database.prepare(`
+      select id, parent_asset_id, child_asset_id, relation_type, created_at,
+        summary, summary_created_by, summary_updated_by, summary_updated_at
+      from asset_edges
+      where project_id = ? and parent_asset_id = ? and child_asset_id = ? and relation_type = 'derived_from'
+    `).get(project, edge.parent_asset_id, edge.child_asset_id);
+    if (!existingRow) {
+      database.close();
+      throw new LineageError("Lineage edge conflict could not be resolved", 409);
+    }
+    const existingEdge = lineageEdgeFromRow(existingRow);
+    if (summary && (existingEdge.summary !== summary || existingEdge.summary_created_by !== fields.summaryActor || existingEdge.summary_updated_by !== fields.summaryActor || !existingEdge.summary_updated_at)) {
+      database.close();
+      throw new LineageError("Lineage edge already exists with a different summary or provenance", 409);
+    }
+    database.close();
+    return {
+      ok: true,
+      idempotent: true,
+      message: `Already linked ${existingEdge.child_asset_id} from ${existingEdge.parent_asset_id}`,
+      edge: existingEdge
+    };
+  }
   database.close();
   return { ok: true, message: `Linked ${edge.child_asset_id} from ${edge.parent_asset_id}`, edge };
 }
+function updateLineageEdgeSummary(project, fields) {
+  if (!fields.confirmWrite) throw new LineageError("Edge summary updates require confirmWrite=true");
+  if (fields.action !== "set" && fields.action !== "clear") throw new LineageError("Edge summary action must be set or clear");
+  const expectedUpdatedAt = expectedEdgeSummaryTimestamp(fields.expectedSummaryUpdatedAt);
+  const summary = fields.action === "set" ? validatedHumanEdgeSummary(fields.summary) : void 0;
+  if (fields.action === "clear" && fields.summary !== void 0) throw new LineageError("Clear edge summary must not include summary text");
+  const database = lineageDb();
+  try {
+    const row = database.prepare(`
+      select id, parent_asset_id, child_asset_id, relation_type, created_at,
+        summary, summary_created_by, summary_updated_by, summary_updated_at
+      from asset_edges
+      where project_id = ? and id = ?
+    `).get(project, fields.edgeId);
+    if (!row) throw new LineageError(`Unknown lineage edge: ${fields.edgeId}`, 404);
+    const current = lineageEdgeFromRow(row);
+    const currentUpdatedAt = current.summary_updated_at || null;
+    if (currentUpdatedAt !== expectedUpdatedAt) {
+      throw new LineageError("Edge summary changed since it was opened; refresh and retry", 409);
+    }
+    if (fields.action === "clear" && !current.summary) throw new LineageError("Edge summary is already clear");
+    if (fields.action === "set" && summary === current.summary) throw new LineageError("Edge summary is unchanged");
+    const claimContext = lineageWriteClaimContext(database, project, current.parent_asset_id);
+    requireLineageWorkspaceClaimForWrite({
+      channel: claimContext.channel,
+      claimToken: fields.claimToken,
+      confirmWrite: fields.confirmWrite,
+      project,
+      rootAssetId: claimContext.rootAssetId,
+      writeKind: "lineage_edge_summary"
+    });
+    const updatedAt = nextEdgeSummaryTimestamp(current.summary_updated_at);
+    const createdBy = fields.action === "set" ? current.summary ? current.summary_created_by || "human" : "human" : current.summary_created_by || "human";
+    const result = database.prepare(`
+      update asset_edges
+      set summary = ?, summary_created_by = ?, summary_updated_by = 'human', summary_updated_at = ?
+      where project_id = ? and id = ?
+        and ((summary_updated_at is null and ? is null) or summary_updated_at = ?)
+    `).run(
+      summary || null,
+      createdBy,
+      updatedAt,
+      project,
+      fields.edgeId,
+      expectedUpdatedAt,
+      expectedUpdatedAt
+    );
+    if (Number(result.changes) !== 1) {
+      throw new LineageError("Edge summary changed since it was opened; refresh and retry", 409);
+    }
+    const updatedRow = database.prepare(`
+      select id, parent_asset_id, child_asset_id, relation_type, created_at,
+        summary, summary_created_by, summary_updated_by, summary_updated_at
+      from asset_edges
+      where project_id = ? and id = ?
+    `).get(project, fields.edgeId);
+    const edge = lineageEdgeFromRow(updatedRow);
+    return {
+      ok: true,
+      edge,
+      message: fields.action === "clear" ? "Cleared edge label" : `Saved edge label \u201C${edge.summary}\u201D`
+    };
+  } finally {
+    database.close();
+  }
+}
 function descendants(database, project, root) {
   const edges = [];
   const queue = [root];
@@ -3722,7 +3912,13 @@ function descendants(database, project, root) {
     const parent = queue.shift();
     if (seen.has(parent)) continue;
     seen.add(parent);
-    const rows = database.prepare("select id, parent_asset_id, child_asset_id, relation_type, created_at from asset_edges where project_id = ? and parent_asset_id = ? order by created_at").all(project, parent);
+    const rows = database.prepare(`
+      select id, parent_asset_id, child_asset_id, relation_type, created_at,
+        summary, summary_created_by, summary_updated_by, summary_updated_at
+      from asset_edges
+      where project_id = ? and parent_asset_id = ?
+      order by created_at
+    `).all(project, parent).map(lineageEdgeFromRow);
     edges.push(...rows);
     queue.push(...rows.map((row) => row.child_asset_id));
   }
@@ -4333,7 +4529,7 @@ function lineageCommand(command, project, rootAssetId) {
   return `${lineagePublicPackageCommand()} ${command} --project ${shellQuote(project)} --root ${shellQuote(rootAssetId)} ${lineageRuntimeSelector()} --json`;
 }
 function linkChildCommand(project, rootAssetId) {
-  return `${lineagePublicPackageCommand()} link-child --project ${shellQuote(project)} --root ${shellQuote(rootAssetId)} --child <asset-id> --confirm-write ${lineageRuntimeSelector()} --json`;
+  return `${lineagePublicPackageCommand()} link-child --project ${shellQuote(project)} --root ${shellQuote(rootAssetId)} --child <asset-id> --summary "<one-or-two-words>" --confirm-write ${lineageRuntimeSelector()} --json`;
 }
 function rerollImportGuidance(rootAssetId, targetAssetId) {
   return `Use lineage reroll plan --root ${rootAssetId} --target ${targetAssetId} and lineage reroll import instead.`;
@@ -4382,6 +4578,7 @@ function getLineageBrief(project, rootAssetId) {
   };
 }
 function linkSelectedLineageChild(project, fields) {
+  const summary = fields.summaryActor ? requireEdgeSummary(fields.summary) : fields.summary;
   const next = getLineageNextAsset(project, fields.rootAssetId);
   if (!next.next_asset) throw new LineageError("Cannot link child until a next base is selected or unambiguous");
   const rerollRequests = listLineageRerollRequests(project, next.root_asset_id).requests;
@@ -4410,7 +4607,9 @@ function linkSelectedLineageChild(project, fields) {
     childAssetId: fields.childAssetId,
     confirmWrite: fields.confirmWrite,
     claimToken: fields.claimToken,
-    parentAssetId: next.next_asset.asset_id
+    parentAssetId: next.next_asset.asset_id,
+    summary,
+    summaryActor: fields.summaryActor
   });
   return {
     ...result,
@@ -4586,8 +4785,8 @@ function recordId(project, asset) {
   const checksum = asset.local?.checksum_sha256 || asset.s3?.checksum_sha256;
   return checksum ? `${project}:sha256:${checksum}` : `${project}:asset:${asset.asset_id}`;
 }
-function sourceId(project, record, sourceType, key) {
-  return `${project}:${record}:${sourceType}:${key}`;
+function sourceId(project, record2, sourceType, key) {
+  return `${project}:${record2}:${sourceType}:${key}`;
 }
 function upsertProject2(database, project) {
   const timestamp = nowIso();
@@ -4642,9 +4841,9 @@ function upsertAssetLedgerAsset(database, project, asset, context = {}) {
   if (asset.s3) upsertSource(database, project, id, "s3", asset, asset.s3.key, context);
   upsertLedgerPlacementsForAsset(database, project, asset);
 }
-function upsertSource(database, project, record, sourceType, asset, key, context = {}) {
+function upsertSource(database, project, record2, sourceType, asset, key, context = {}) {
   const timestamp = context.seenAt || nowIso();
-  const id = sourceId(project, record, sourceType, key);
+  const id = sourceId(project, record2, sourceType, key);
   database.prepare(`
     insert into asset_ledger_sources (
       id, project_id, record_id, source_type, asset_id, local_path, s3_bucket, s3_region,
@@ -4667,7 +4866,7 @@ function upsertSource(database, project, record, sourceType, asset, key, context
   `).run(
     id,
     project,
-    record,
+    record2,
     sourceType,
     asset.asset_id,
     sourceType === "local" ? asset.local?.relative_path || null : null,
@@ -4776,13 +4975,13 @@ function getAssetLedgerSnapshot(project = defaultProject) {
   const totals = sourceCounts(database, project);
   const lastIndexRun = latestIndexRun(database, project);
   const sourceRecords = sources.map(toSource);
-  const baseRecords = records.map((record) => toRecord(record, sourceRecords.filter((source) => source.record_id === record.id)));
+  const baseRecords = records.map((record2) => toRecord(record2, sourceRecords.filter((source) => source.record_id === record2.id)));
   const workflows = ledgerWorkflowStates(database, project, baseRecords, sourceRecords);
   database.close();
   return {
     project,
     database: lineageDbPath(),
-    records: baseRecords.map((record) => ({ ...record, workflow: workflows[record.id] || { placements: [] } })),
+    records: baseRecords.map((record2) => ({ ...record2, workflow: workflows[record2.id] || { placements: [] } })),
     last_index_run: lastIndexRun,
     totals: {
       records: records.length,
@@ -4823,22 +5022,22 @@ function toIndexRun(row) {
     error: row.error || void 0
   };
 }
-function toRecord(record, sources) {
+function toRecord(record2, sources) {
   return {
-    id: record.id,
-    project: record.project_id,
-    canonical_asset_id: record.canonical_asset_id,
-    checksum_sha256: record.checksum_sha256 || void 0,
-    media_type: record.media_type,
-    title: record.title,
-    status: record.status,
-    channel: record.channel || void 0,
-    campaign: record.campaign || void 0,
-    audience: record.audience || void 0,
-    updated_at: record.updated_at,
-    first_seen_at: record.first_seen_at || void 0,
-    last_seen_at: record.last_seen_at,
-    indexed_by_run_id: record.indexed_by_run_id || void 0,
+    id: record2.id,
+    project: record2.project_id,
+    canonical_asset_id: record2.canonical_asset_id,
+    checksum_sha256: record2.checksum_sha256 || void 0,
+    media_type: record2.media_type,
+    title: record2.title,
+    status: record2.status,
+    channel: record2.channel || void 0,
+    campaign: record2.campaign || void 0,
+    audience: record2.audience || void 0,
+    updated_at: record2.updated_at,
+    first_seen_at: record2.first_seen_at || void 0,
+    last_seen_at: record2.last_seen_at,
+    indexed_by_run_id: record2.indexed_by_run_id || void 0,
     sources,
     workflow: { placements: [] }
   };
@@ -4872,26 +5071,26 @@ var selectionFilters = /* @__PURE__ */ new Set(["all", "selected", "not-selected
 function normalizeFilter(value, allowed, fallback) {
   return typeof value === "string" && allowed.has(value) ? value : fallback;
 }
-function sourceTypes(record) {
-  return new Set(record.sources.map((source) => source.source_type));
+function sourceTypes(record2) {
+  return new Set(record2.sources.map((source) => source.source_type));
 }
-function matchesStorage(record, storage) {
-  const types = sourceTypes(record);
+function matchesStorage(record2, storage) {
+  const types = sourceTypes(record2);
   if (storage === "local-only") return types.has("local") && !types.has("s3");
   if (storage === "s3-backed") return types.has("s3");
   if (storage === "local-and-s3") return types.has("local") && types.has("s3");
   if (storage === "catalog-only") return types.has("catalog") && !types.has("local") && !types.has("s3");
   return true;
 }
-function matchesPlacement(record, placement) {
-  if (placement === "not-scheduled") return record.workflow.placements.length === 0;
-  if (placement === "not-posted") return !record.workflow.placements.some((item) => item.status === "posted");
+function matchesPlacement(record2, placement) {
+  if (placement === "not-scheduled") return record2.workflow.placements.length === 0;
+  if (placement === "not-posted") return !record2.workflow.placements.some((item) => item.status === "posted");
   if (placement === "all") return true;
-  return record.workflow.placements.some((item) => item.status === placement);
+  return record2.workflow.placements.some((item) => item.status === placement);
 }
-function matchesSelection(record, selection) {
-  if (selection === "selected") return Boolean(record.workflow.selection);
-  if (selection === "not-selected") return !record.workflow.selection;
+function matchesSelection(record2, selection) {
+  if (selection === "selected") return Boolean(record2.workflow.selection);
+  if (selection === "not-selected") return !record2.workflow.selection;
   return true;
 }
 function filterLedgerRecords(records, options = {}) {
@@ -4900,21 +5099,21 @@ function filterLedgerRecords(records, options = {}) {
   const selection = normalizeFilter(options.selection, selectionFilters, "all");
   const storage = normalizeFilter(options.storage, storageFilters, "all");
   const query = options.query?.trim().toLowerCase() || "";
-  return records.filter((record) => {
-    if (!matchesStorage(record, storage)) return false;
-    if (review !== "all" && (record.workflow.review?.review_state || "unreviewed") !== review) return false;
-    if (!matchesPlacement(record, placement)) return false;
-    if (!matchesSelection(record, selection)) return false;
+  return records.filter((record2) => {
+    if (!matchesStorage(record2, storage)) return false;
+    if (review !== "all" && (record2.workflow.review?.review_state || "unreviewed") !== review) return false;
+    if (!matchesPlacement(record2, placement)) return false;
+    if (!matchesSelection(record2, selection)) return false;
     if (!query) return true;
     return [
-      record.canonical_asset_id,
-      record.title,
-      record.status,
-      record.channel,
-      record.campaign,
-      record.audience,
-      record.workflow.review?.review_state,
-      ...record.workflow.placements.map((item) => `${item.channel} ${item.status}`)
+      record2.canonical_asset_id,
+      record2.title,
+      record2.status,
+      record2.channel,
+      record2.campaign,
+      record2.audience,
+      record2.workflow.review?.review_state,
+      ...record2.workflow.placements.map((item) => `${item.channel} ${item.status}`)
     ].join(" ").toLowerCase().includes(query);
   });
 }
@@ -6994,7 +7193,141 @@ function contentBatchRouter(projectFrom2) {
 import { existsSync as existsSync9, realpathSync as realpathSync2, statSync as statSync4 } from "node:fs";
 import { relative as relative4, resolve as resolve5 } from "node:path";
 import { randomUUID as randomUUID3 } from "node:crypto";
-var adapterVersion = "generation-receipts-v1";
+
+// src/shared/generationOutputManifest.ts
+var generationOutputManifestSchemaVersion = "lineage.generation_output_manifest.v1";
+var GenerationOutputManifestError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GenerationOutputManifestError";
+  }
+};
+function record(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new GenerationOutputManifestError(`${label} must be an object`);
+  }
+  return value;
+}
+function exactKeys(value, allowed, label) {
+  const allowedKeys = new Set(allowed);
+  const unsupported = Object.keys(value).filter((key) => !allowedKeys.has(key)).sort();
+  if (unsupported.length > 0) {
+    throw new GenerationOutputManifestError(`${label} contains unsupported field: ${unsupported[0]}`);
+  }
+}
+function nonEmptyText(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new GenerationOutputManifestError(`${label} is required`);
+  return value.trim();
+}
+function expectedGenerationOutputParents(job) {
+  if (!Number.isInteger(job.expected_output_count) || job.expected_output_count <= 0) {
+    throw new GenerationOutputManifestError("Generation job expected output count must be a positive integer");
+  }
+  const parents = job.inputs.filter((input) => input.role === "lineage_next_base").sort((left, right) => left.position - right.position);
+  if (parents.length === 0) throw new GenerationOutputManifestError("Generation job has no lineage_next_base input");
+  const parentIds = /* @__PURE__ */ new Set();
+  const parentPositions = /* @__PURE__ */ new Set();
+  for (const parent of parents) {
+    if (typeof parent.asset_id !== "string" || !parent.asset_id || parent.asset_id.trim() !== parent.asset_id) {
+      throw new GenerationOutputManifestError("Generation job has invalid lineage parent asset id");
+    }
+    if (!Number.isInteger(parent.position) || parent.position < 0 || parentPositions.has(parent.position)) {
+      throw new GenerationOutputManifestError("Generation job has invalid lineage parent positions");
+    }
+    if (parentIds.has(parent.asset_id)) throw new GenerationOutputManifestError(`Generation job has duplicate lineage parent: ${parent.asset_id}`);
+    parentIds.add(parent.asset_id);
+    parentPositions.add(parent.position);
+  }
+  if (job.expected_output_count % parents.length !== 0) {
+    throw new GenerationOutputManifestError("Generation job has invalid parent mapping");
+  }
+  const outputsPerParent = job.expected_output_count / parents.length;
+  return Array.from({ length: job.expected_output_count }, (_value, outputIndex) => {
+    return parents[Math.floor(outputIndex / outputsPerParent)].asset_id;
+  });
+}
+function createGenerationOutputManifestDraft(job) {
+  return {
+    schema_version: generationOutputManifestSchemaVersion,
+    job_id: job.id,
+    outputs: expectedGenerationOutputParents(job).map((parentAssetId, outputIndex) => ({
+      output_index: outputIndex,
+      file_path: "",
+      parent_asset_id: parentAssetId,
+      edge_summary: ""
+    }))
+  };
+}
+function parseGenerationOutputManifest(value, job, options) {
+  if (!options || typeof options.resolveFilePath !== "function") {
+    throw new GenerationOutputManifestError("Generation output manifest requires a file-path resolver");
+  }
+  const manifest = record(value, "Generation output manifest");
+  exactKeys(manifest, ["schema_version", "job_id", "outputs"], "Generation output manifest");
+  if (manifest.schema_version !== generationOutputManifestSchemaVersion) {
+    throw new GenerationOutputManifestError(`Generation output manifest schema_version must be ${generationOutputManifestSchemaVersion}`);
+  }
+  if (manifest.job_id !== job.id) throw new GenerationOutputManifestError(`Generation output manifest job_id must be ${job.id}`);
+  if (!Array.isArray(manifest.outputs)) throw new GenerationOutputManifestError("Generation output manifest outputs must be an array");
+  const expectedParents = expectedGenerationOutputParents(job);
+  if (manifest.outputs.length !== expectedParents.length) {
+    throw new GenerationOutputManifestError(`Generation output manifest requires ${expectedParents.length} outputs, received ${manifest.outputs.length}`);
+  }
+  const seenIndexes = /* @__PURE__ */ new Set();
+  const outputs = manifest.outputs.map((value2, position) => {
+    const output = record(value2, `Generation output at position ${position}`);
+    exactKeys(output, ["output_index", "file_path", "parent_asset_id", "edge_summary"], `Generation output at position ${position}`);
+    const outputIndex = output.output_index;
+    if (!Number.isInteger(outputIndex) || Number(outputIndex) < 0) {
+      throw new GenerationOutputManifestError(`Generation output at position ${position} requires a non-negative integer output_index`);
+    }
+    const normalizedIndex = Number(outputIndex);
+    if (seenIndexes.has(normalizedIndex)) throw new GenerationOutputManifestError(`Duplicate generation output_index: ${normalizedIndex}`);
+    seenIndexes.add(normalizedIndex);
+    const expectedParent = expectedParents[normalizedIndex];
+    if (!expectedParent) throw new GenerationOutputManifestError(`Unknown generation output_index: ${normalizedIndex}`);
+    const filePath = nonEmptyText(output.file_path, `Generation output ${normalizedIndex} file_path`);
+    const parentAssetId = nonEmptyText(output.parent_asset_id, `Generation output ${normalizedIndex} parent_asset_id`);
+    if (parentAssetId !== expectedParent) {
+      throw new GenerationOutputManifestError(`Generation output ${normalizedIndex} must use parent_asset_id ${expectedParent}`);
+    }
+    let edgeSummary;
+    try {
+      edgeSummary = requireEdgeSummary(output.edge_summary);
+    } catch (error) {
+      if (error instanceof EdgeSummaryValidationError) {
+        throw new GenerationOutputManifestError(`Generation output ${normalizedIndex}: ${error.message}`);
+      }
+      throw error;
+    }
+    return {
+      output_index: normalizedIndex,
+      file_path: filePath,
+      parent_asset_id: parentAssetId,
+      edge_summary: edgeSummary
+    };
+  });
+  for (const outputIndex of expectedParents.keys()) {
+    if (!seenIndexes.has(outputIndex)) throw new GenerationOutputManifestError(`Missing generation output_index: ${outputIndex}`);
+  }
+  outputs.sort((left, right) => left.output_index - right.output_index);
+  const seenPaths = /* @__PURE__ */ new Set();
+  const resolvedOutputs = outputs.map((output) => {
+    const filePath = nonEmptyText(options.resolveFilePath(output.file_path), `Generation output ${output.output_index} resolved file_path`);
+    if (seenPaths.has(filePath)) throw new GenerationOutputManifestError(`Duplicate generation output file_path: ${filePath}`);
+    seenPaths.add(filePath);
+    return { ...output, file_path: filePath };
+  });
+  return {
+    schema_version: generationOutputManifestSchemaVersion,
+    job_id: job.id,
+    outputs: resolvedOutputs
+  };
+}
+
+// src/server/generationReceipts.ts
+var legacyAdapterVersion = "generation-receipts-v1";
+var manifestAdapterVersion = "generation-receipts-v2";
 var provider = "codex-handoff";
 var GenerationReceiptError = class extends Error {
   constructor(message, status = 400) {
@@ -7016,6 +7349,70 @@ function parseJson(value, fallback) {
   if (!value) return fallback;
   return JSON.parse(value);
 }
+function positiveInteger(value) {
+  return Number.isInteger(value) && Number(value) > 0;
+}
+function resolveLineageSelection(project) {
+  const rootAssetId = activeLineageWorkspaceRoot(project);
+  if (!rootAssetId) throw new GenerationReceiptError("No active lineage workspace for generation planning");
+  const next = getLineageNextAsset(project, rootAssetId);
+  if (!next.next_asset) throw new GenerationReceiptError(`No clear lineage next asset: ${next.reason}`);
+  if (next.strategy !== "selected") throw new GenerationReceiptError("Generation v1 requires an explicit selected lineage next base");
+  if (next.selection_mode !== "multiple" && next.selection?.asset_id !== next.next_asset.asset_id) throw new GenerationReceiptError("Generation v1 requires one explicit selected lineage next base");
+  return next;
+}
+function selectedParents(next) {
+  const parents = next.next_assets.length > 0 ? next.next_assets : next.next_asset ? [next.next_asset] : [];
+  if (parents.length === 0) throw new GenerationReceiptError("Missing lineage next base");
+  return parents;
+}
+function parentMappings(next, perBaseCount) {
+  return selectedParents(next).map((parent, parentIndex) => ({
+    parent,
+    output_indexes: Array.from({ length: perBaseCount }, (_value, index) => parentIndex * perBaseCount + index)
+  }));
+}
+function buildHandoff(project, id, prompt, count, perBaseCount, next, inputs) {
+  const parent = next.next_asset;
+  if (!parent) throw new GenerationReceiptError("Missing lineage next base");
+  const parents = parentMappings(next, perBaseCount);
+  const outputManifest = createGenerationOutputManifestDraft({ id, expected_output_count: count, inputs });
+  const importCommand = `${lineagePublicPackageCommand()} generate image import --project ${quote(project)} --job-id ${quote(id)} --manifest ${quote(".asset-scratch/generation-output-manifest.json")} --confirm-write ${lineageRuntimeSelector()} --json`;
+  return {
+    schema_version: "lineage.generation_handoff.v2",
+    provider,
+    project,
+    job_id: id,
+    prompt,
+    expected_output_count: count,
+    per_base_count: next.selection_mode === "multiple" ? perBaseCount : void 0,
+    lineage: {
+      root_asset_id: next.root_asset_id,
+      parent_asset_id: parent.asset_id,
+      selection_strategy: next.strategy,
+      parent_title: parent.title,
+      parent_local_path: parent.local_path,
+      parent_s3_key: parent.s3_key,
+      parents: parents.length > 1 ? parents.map((mapping) => ({
+        parent_asset_id: mapping.parent.asset_id,
+        parent_title: mapping.parent.title,
+        parent_local_path: mapping.parent.local_path,
+        parent_s3_key: mapping.parent.s3_key,
+        output_indexes: mapping.output_indexes
+      })) : void 0
+    },
+    instructions: [
+      "Use Codex image generation outside Lineage server code.",
+      "Write generated output files under .asset-scratch before import.",
+      "Do not call live provider APIs from the CLI or server.",
+      "Fill every output_manifest entry with its generated file path and a one- or two-word edge summary.",
+      "Import the completed manifest with --confirm-write to persist every lineage child."
+    ],
+    import_command: importCommand,
+    output_manifest: outputManifest,
+    guardrails: { live_generation: false, external_services: false, output_root: ".asset-scratch", confirm_write_required: true }
+  };
+}
 function buildRerollHandoff(project, id, prompt, rootAssetId, target, request) {
   const importCommand = `${lineagePublicPackageCommand()} reroll import --project ${quote(project)} --job-id ${quote(id)} --file <.asset-scratch-file> --confirm-write ${lineageRuntimeSelector()} --json`;
   return {
@@ -7044,6 +7441,19 @@ function buildRerollHandoff(project, id, prompt, rootAssetId, target, request) {
     guardrails: { live_generation: false, external_services: false, output_root: ".asset-scratch", confirm_write_required: true }
   };
 }
+function inputsFrom(jobIdValue, project, next) {
+  return selectedParents(next).map((parent, position) => ({
+    id: `${jobIdValue}:input:${position}`,
+    job_id: jobIdValue,
+    project_id: project,
+    asset_id: parent.asset_id,
+    root_asset_id: next.root_asset_id,
+    role: "lineage_next_base",
+    position,
+    selection_strategy: next.strategy,
+    selection_snapshot: next
+  }));
+}
 function receiptFrom(row) {
   return {
     id: String(row.id),
@@ -7056,6 +7466,7 @@ function receiptFrom(row) {
   };
 }
 function outputFrom(row) {
+  const edgeSummary = typeof row.edge_summary === "string" && row.edge_summary.length > 0 ? row.edge_summary : void 0;
   return {
     id: String(row.id),
     job_id: String(row.job_id),
@@ -7067,7 +7478,8 @@ function outputFrom(row) {
     content_type: String(row.content_type),
     imported_asset_id: String(row.imported_asset_id),
     parent_asset_id: String(row.parent_asset_id),
-    imported_at: String(row.imported_at)
+    imported_at: String(row.imported_at),
+    ...edgeSummary ? { edge_summary: edgeSummary } : {}
   };
 }
 function loadGenerationJob(database, project, id) {
@@ -7113,6 +7525,72 @@ function insertReceipt(database, id, type, command, payload) {
     values (?, ?, ?, 'ok', ?, ?, ?)
   `).run(`${id}:receipt:${type}:${Date.now()}`, id, type, command, JSON.stringify(payload), nowIso());
 }
+function planImageGeneration(project = defaultProject, fields) {
+  const prompt = fields.prompt.trim();
+  if (!prompt) throw new GenerationReceiptError("Missing --prompt");
+  if (!fields.fromLineageSelection) throw new GenerationReceiptError("Generation v1 requires --from-lineage-selection");
+  const next = resolveLineageSelection(project);
+  const parentCount = selectedParents(next).length;
+  if (parentCount > 1 && !positiveInteger(fields.perBaseCount)) throw new GenerationReceiptError("Multi-parent generation requires --per-base-count");
+  const perBaseCount = parentCount > 1 ? Number(fields.perBaseCount) : Number(fields.count ?? fields.perBaseCount);
+  const count = parentCount * perBaseCount;
+  if (!positiveInteger(perBaseCount)) throw new GenerationReceiptError("Generation count must be a positive integer");
+  if (fields.count !== void 0 && fields.count !== count) throw new GenerationReceiptError(`Generation count mismatch: expected ${count} from selected bases, received ${fields.count}`);
+  const id = jobId();
+  const inputs = inputsFrom(id, project, next);
+  const handoff3 = buildHandoff(project, id, prompt, count, perBaseCount, next, inputs);
+  const mappings = parentMappings(next, perBaseCount).map((mapping) => ({ parent_asset_id: mapping.parent.asset_id, output_indexes: mapping.output_indexes }));
+  const timestamp = nowIso();
+  const preview = {
+    id,
+    project_id: project,
+    provider,
+    adapter_version: manifestAdapterVersion,
+    source_mode: "lineage_selection",
+    root_asset_id: next.root_asset_id,
+    prompt,
+    expected_output_count: count,
+    status: "planned",
+    output_dir: ".asset-scratch",
+    handoff: handoff3,
+    created_at: timestamp,
+    updated_at: timestamp,
+    inputs,
+    outputs: [],
+    receipts: [{
+      id: `${id}:receipt:plan:preview`,
+      job_id: id,
+      receipt_type: "plan",
+      status: "ok",
+      command: "generate image plan",
+      payload: { prompt, expected_output_count: count, per_base_count: parentCount > 1 ? perBaseCount : void 0, lineage: handoff3.lineage, parent_mappings: mappings },
+      created_at: timestamp
+    }]
+  };
+  if (fields.dryRun) return { ok: true, command: "generate image plan", project, dryRun: true, wouldWrite: true, job: preview };
+  const database = lineageDb();
+  try {
+    database.exec("BEGIN IMMEDIATE");
+    try {
+      database.prepare(`
+        insert into generation_jobs (
+          id, project_id, provider, adapter_version, source_mode, root_asset_id, prompt,
+          expected_output_count, status, output_dir, handoff_json, created_at, updated_at
+        ) values (?, ?, ?, ?, 'lineage_selection', ?, ?, ?, 'planned', ?, ?, ?, ?)
+      `).run(id, project, provider, manifestAdapterVersion, next.root_asset_id, prompt, count, ".asset-scratch", JSON.stringify(handoff3), timestamp, timestamp);
+      const insertInput = database.prepare("insert into generation_job_inputs (id, job_id, project_id, asset_id, root_asset_id, role, position, selection_strategy, selection_snapshot_json) values (?, ?, ?, ?, ?, ?, ?, ?, ?)");
+      for (const input of inputs) insertInput.run(input.id, id, project, input.asset_id, input.root_asset_id, input.role, input.position, input.selection_strategy, JSON.stringify(next));
+      insertReceipt(database, id, "plan", "generate image plan", preview.receipts[0].payload);
+      database.exec("COMMIT");
+    } catch (error) {
+      database.exec("ROLLBACK");
+      throw error;
+    }
+    return { ok: true, command: "generate image plan", project, job: loadGenerationJob(database, project, id) };
+  } finally {
+    database.close();
+  }
+}
 function planImageReroll(project = defaultProject, fields) {
   const prompt = fields.prompt.trim();
   if (!prompt) throw new GenerationReceiptError("Missing --prompt");
@@ -7157,7 +7635,7 @@ function planImageReroll(project = defaultProject, fields) {
     id,
     project_id: project,
     provider,
-    adapter_version: adapterVersion,
+    adapter_version: legacyAdapterVersion,
     source_mode: "lineage_reroll",
     root_asset_id: snapshot.root_asset_id,
     prompt,
@@ -7189,7 +7667,7 @@ function planImageReroll(project = defaultProject, fields) {
           id, project_id, provider, adapter_version, source_mode, root_asset_id, prompt,
           expected_output_count, status, output_dir, handoff_json, created_at, updated_at
         ) values (?, ?, ?, ?, 'lineage_reroll', ?, ?, 1, 'planned', ?, ?, ?, ?)
-      `).run(id, project, provider, adapterVersion, snapshot.root_asset_id, prompt, ".asset-scratch", JSON.stringify(handoff3), timestamp, timestamp);
+      `).run(id, project, provider, legacyAdapterVersion, snapshot.root_asset_id, prompt, ".asset-scratch", JSON.stringify(handoff3), timestamp, timestamp);
       database.prepare("insert into generation_job_inputs (id, job_id, project_id, asset_id, root_asset_id, role, position, selection_strategy, selection_snapshot_json) values (?, ?, ?, ?, ?, ?, ?, ?, ?)").run(input.id, id, project, input.asset_id, input.root_asset_id, input.role, input.position, input.selection_strategy, JSON.stringify(input.selection_snapshot));
       insertReceipt(database, id, "plan", "reroll plan", preview.receipts[0].payload);
       database.exec("COMMIT");
@@ -7202,14 +7680,66 @@ function planImageReroll(project = defaultProject, fields) {
     database.close();
   }
 }
+function parentForOutput(job, outputIndex) {
+  const inputs = job.inputs.filter((input) => input.role === "lineage_next_base");
+  if (inputs.length === 0) throw new GenerationReceiptError("Generation job has no lineage_next_base input");
+  if (inputs.length === 1) return inputs[0].asset_id;
+  if (job.expected_output_count % inputs.length !== 0) throw new GenerationReceiptError("Generation job has invalid parent mapping");
+  return inputs[Math.floor(outputIndex / (job.expected_output_count / inputs.length))]?.asset_id || inputs[inputs.length - 1].asset_id;
+}
+function parentInputs(job) {
+  const inputs = job.inputs.filter((input) => input.role === "lineage_next_base");
+  if (inputs.length === 0) throw new GenerationReceiptError("Generation job has no lineage_next_base input");
+  return inputs;
+}
+function parentFilesFor(job, parentFiles) {
+  const inputs = parentInputs(job);
+  const expectedPerParent = job.expected_output_count / inputs.length;
+  if (!Number.isInteger(expectedPerParent)) throw new GenerationReceiptError("Generation job has invalid parent mapping");
+  const allowedParents = new Set(inputs.map((input) => input.asset_id));
+  const seenParents = /* @__PURE__ */ new Set();
+  const mapped = [];
+  for (const parentAssetId of Object.keys(parentFiles)) {
+    if (!allowedParents.has(parentAssetId)) throw new GenerationReceiptError(`Unknown generation parent mapping: ${parentAssetId}`);
+    if (seenParents.has(parentAssetId)) throw new GenerationReceiptError(`Duplicate generation parent mapping: ${parentAssetId}`);
+    seenParents.add(parentAssetId);
+  }
+  for (const input of inputs) {
+    const files = (parentFiles[input.asset_id] || []).map((file) => file.trim()).filter(Boolean);
+    if (files.length === 0) throw new GenerationReceiptError(`Missing generation parent mapping for ${input.asset_id}`);
+    if (files.length !== expectedPerParent) throw new GenerationReceiptError(`Parent ${input.asset_id} requires ${expectedPerParent} output file${expectedPerParent === 1 ? "" : "s"}, received ${files.length}`);
+    for (const file of files) mapped.push({ file, parentAssetId: input.asset_id });
+  }
+  return mapped;
+}
+function orderedFilesFor(job, files) {
+  return files.map((file, index) => ({ file, parentAssetId: parentForOutput(job, index) }));
+}
+function inspectImageGeneration(project = defaultProject, jobIdValue) {
+  if (!jobIdValue) throw new GenerationReceiptError("Missing --job-id");
+  const database = lineageDb();
+  try {
+    return { ok: true, command: "generate image inspect", project, job: loadGenerationJob(database, project, jobIdValue) };
+  } finally {
+    database.close();
+  }
+}
 function isPathInside2(child, parent) {
   const rel = relative4(parent, child);
   return Boolean(rel) && !rel.startsWith("..") && !rel.startsWith("/");
 }
-function resolveScratchFile(file) {
+function scratchCandidate(file) {
   const scratchRoot = resolve5(repoRoot, ".asset-scratch");
   const candidate = file.startsWith(".asset-scratch/") || resolve5(file).startsWith(scratchRoot) ? resolve5(repoRoot, file) : resolve5(scratchRoot, file);
   if (!isPathInside2(candidate, scratchRoot)) throw new GenerationReceiptError(`Import file must be under .asset-scratch: ${file}`);
+  return { candidate, scratchRoot };
+}
+function resolveScratchManifestPath(file) {
+  const { candidate, scratchRoot } = scratchCandidate(file);
+  return relative4(scratchRoot, candidate);
+}
+function resolveScratchFile(file) {
+  const { candidate, scratchRoot } = scratchCandidate(file);
   if (!existsSync9(candidate)) throw new GenerationReceiptError(`Missing import file: ${file}`, 404);
   const realScratchRoot = realpathSync2(scratchRoot);
   const realCandidate = realpathSync2(candidate);
@@ -7225,6 +7755,165 @@ function resolveScratchFile(file) {
     assetId: `local-${checksum.slice(0, 12)}`
   };
 }
+function generationManifestConflict() {
+  throw new GenerationReceiptError("Generation import already exists with different output, summary, or provenance", 409);
+}
+function confirmManifestRetry(project, job, manifest) {
+  if (job.outputs.length !== manifest.outputs.length) generationManifestConflict();
+  const database = lineageDb();
+  try {
+    for (const expected of manifest.outputs) {
+      const recorded = job.outputs.find((output) => output.output_index === expected.output_index);
+      if (!recorded || recorded.file_path !== expected.file_path || recorded.parent_asset_id !== expected.parent_asset_id || recorded.edge_summary !== expected.edge_summary) generationManifestConflict();
+      const edge = database.prepare(`
+        select summary, summary_created_by, summary_updated_by, summary_updated_at
+        from asset_edges
+        where project_id = ? and parent_asset_id = ? and child_asset_id = ? and relation_type = 'derived_from'
+      `).get(project, recorded.parent_asset_id, recorded.imported_asset_id);
+      if (!edge || edge.summary !== expected.edge_summary || edge.summary_created_by !== "agent" || edge.summary_updated_by !== "agent" || typeof edge.summary_updated_at !== "string" || edge.summary_updated_at.length === 0) generationManifestConflict();
+    }
+    return { ok: true, command: "generate image import", project, job, imported: job.outputs, idempotent: true };
+  } finally {
+    database.close();
+  }
+}
+function importImageGenerationOutputs(project = defaultProject, fields) {
+  if (!fields.jobId) throw new GenerationReceiptError("Missing --job-id");
+  if (!fields.confirmWrite) throw new GenerationReceiptError("Generation import requires --confirm-write");
+  const database = lineageDb();
+  let job;
+  try {
+    job = loadGenerationJob(database, project, fields.jobId);
+  } finally {
+    database.close();
+  }
+  if (job.source_mode !== "lineage_selection") throw new GenerationReceiptError(`Generation job is not an image-selection job: ${job.source_mode}`);
+  const hasManifestInput = fields.manifest !== void 0;
+  const hasParentFilesInput = fields.parentFiles !== void 0;
+  const hasFilesInput = fields.files !== void 0;
+  if (hasManifestInput && (hasParentFilesInput || hasFilesInput)) {
+    throw new GenerationReceiptError("Use --manifest or legacy --files/--parent-files, not both");
+  }
+  if (hasParentFilesInput && hasFilesInput) throw new GenerationReceiptError("Use --files or --parent-files, not both");
+  let manifest;
+  let parentFileRows;
+  let mappingStrategy;
+  if (job.adapter_version === manifestAdapterVersion) {
+    if (!hasManifestInput) throw new GenerationReceiptError("New generation jobs require --manifest");
+    manifest = parseGenerationOutputManifest(fields.manifest, job, { resolveFilePath: resolveScratchManifestPath });
+    if (job.status === "imported") return confirmManifestRetry(project, job, manifest);
+    if (job.status !== "planned") throw new GenerationReceiptError(`Generation job is not importable from status: ${job.status}`);
+    parentFileRows = manifest.outputs.map((output) => ({
+      edgeSummary: output.edge_summary,
+      file: output.file_path,
+      parentAssetId: output.parent_asset_id
+    }));
+    mappingStrategy = "generation_output_manifest_v1";
+  } else if (job.adapter_version === legacyAdapterVersion) {
+    if (hasManifestInput) throw new GenerationReceiptError("Already-planned legacy generation jobs require --files or --parent-files");
+    if (job.status !== "planned") throw new GenerationReceiptError(`Generation job is not importable from status: ${job.status}`);
+    const hasExplicitParentFiles = Boolean(fields.parentFiles && Object.keys(fields.parentFiles).length > 0);
+    parentFileRows = hasExplicitParentFiles ? parentFilesFor(job, fields.parentFiles || {}) : orderedFilesFor(job, (fields.files || []).map((file) => file.trim()).filter(Boolean));
+    mappingStrategy = hasExplicitParentFiles ? "explicit_parent_files" : "ordered_per_base";
+  } else {
+    throw new GenerationReceiptError(`Unsupported generation adapter version: ${job.adapter_version}`);
+  }
+  if (parentFileRows.length === 0) throw new GenerationReceiptError("Generation import requires --files or --parent-files");
+  if (parentFileRows.length !== job.expected_output_count) {
+    throw new GenerationReceiptError(`Output count mismatch: expected ${job.expected_output_count}, received ${parentFileRows.length}`);
+  }
+  const resolved = parentFileRows.map((row) => ({ ...resolveScratchFile(row.file), edgeSummary: row.edgeSummary, parentAssetId: row.parentAssetId }));
+  const uniquePaths = new Set(resolved.map((file) => file.relativePath));
+  if (uniquePaths.size !== resolved.length) throw new GenerationReceiptError("Generation import files must be unique");
+  cancelLineageIterateTasksForAssets(project, {
+    actor: "system",
+    confirmWrite: false,
+    rootAssetId: job.root_asset_id
+  });
+  indexLineageAssets(project);
+  const writeDb = lineageDb();
+  try {
+    const timestamp = nowIso();
+    writeDb.exec("BEGIN IMMEDIATE");
+    try {
+      for (const [index, file] of resolved.entries()) {
+        const assetRow = writeDb.prepare("select id from assets where project_id = ? and id = ?").get(project, file.assetId);
+        if (!assetRow) throw new GenerationReceiptError(`Indexed local asset was not found: ${file.relativePath}`);
+        const outputId = `${fields.jobId}:output:${index}`;
+        writeDb.prepare(`insert into generation_job_outputs (
+          id, job_id, project_id, output_index, file_path, checksum_sha256, size_bytes, content_type,
+          imported_asset_id, parent_asset_id, imported_at, edge_summary
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+          outputId,
+          fields.jobId,
+          project,
+          index,
+          file.relativePath,
+          file.checksum,
+          file.size,
+          file.contentType,
+          file.assetId,
+          file.parentAssetId,
+          timestamp,
+          file.edgeSummary || null
+        );
+        const insertedEdge = writeDb.prepare(`insert into asset_edges (
+          id, project_id, parent_asset_id, child_asset_id, relation_type, created_at,
+          summary, summary_created_by, summary_updated_by, summary_updated_at
+        ) values (?, ?, ?, ?, 'derived_from', ?, ?, ?, ?, ?)
+        on conflict(project_id, parent_asset_id, child_asset_id, relation_type) do nothing`).run(
+          `${project}:${file.parentAssetId}:derived_from:${file.assetId}`,
+          project,
+          file.parentAssetId,
+          file.assetId,
+          timestamp,
+          file.edgeSummary || null,
+          file.edgeSummary ? "agent" : null,
+          file.edgeSummary ? "agent" : null,
+          file.edgeSummary ? timestamp : null
+        );
+        if (file.edgeSummary && insertedEdge.changes === 0) {
+          const edge = writeDb.prepare(`
+            select summary, summary_created_by, summary_updated_by, summary_updated_at
+            from asset_edges
+            where project_id = ? and parent_asset_id = ? and child_asset_id = ? and relation_type = 'derived_from'
+          `).get(project, file.parentAssetId, file.assetId);
+          if (!edge || edge.summary !== file.edgeSummary || edge.summary_created_by !== "agent" || edge.summary_updated_by !== "agent" || typeof edge.summary_updated_at !== "string" || edge.summary_updated_at.length === 0) generationManifestConflict();
+        }
+      }
+      writeDb.prepare(`
+        update generation_jobs
+        set status = 'imported', imported_at = ?, updated_at = ?
+        where project_id = ? and id = ?
+      `).run(timestamp, timestamp, project, fields.jobId);
+      insertReceipt(writeDb, fields.jobId, "import", "generate image import", {
+        mapping_strategy: mappingStrategy,
+        files: resolved.map((file, index) => ({
+          output_index: index,
+          file_path: file.relativePath,
+          imported_asset_id: file.assetId,
+          parent_asset_id: file.parentAssetId,
+          ...file.edgeSummary ? { edge_summary: file.edgeSummary } : {}
+        })),
+        selection_reset: { root_asset_id: job.root_asset_id, cleared: true }
+      });
+      writeDb.prepare("delete from asset_selections where project_id = ? and root_asset_id = ?").run(project, job.root_asset_id);
+      writeDb.exec("COMMIT");
+    } catch (error) {
+      writeDb.exec("ROLLBACK");
+      throw error;
+    }
+    cancelLineageIterateTasksForAssets(project, {
+      actor: "system",
+      confirmWrite: true,
+      rootAssetId: job.root_asset_id
+    });
+    const importedJob = loadGenerationJob(writeDb, project, fields.jobId);
+    return { ok: true, command: "generate image import", project, job: importedJob, imported: importedJob.outputs };
+  } finally {
+    writeDb.close();
+  }
+}
 function importImageRerollOutput(project = defaultProject, fields) {
   if (!fields.jobId) throw new GenerationReceiptError("Missing --job-id");
   if (!fields.confirmWrite) throw new GenerationReceiptError("Generation import requires --confirm-write");
@@ -8158,7 +8847,7 @@ function registerLineageWorkspaceRoutes(app2, projectFrom2, asyncRoute2) {
 import { createHash as createHash6 } from "node:crypto";
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { createRequire as createRequire4 } from "node:module";
-import { existsSync as existsSync11, lstatSync as lstatSync2, readFileSync as readFileSync7, readdirSync as readdirSync4, readlinkSync, realpathSync as realpathSync3, statSync as statSync5 } from "node:fs";
+import { existsSync as existsSync11, lstatSync as lstatSync3, readFileSync as readFileSync7, readdirSync as readdirSync4, readlinkSync, realpathSync as realpathSync3, statSync as statSync5 } from "node:fs";
 import { dirname as dirname6, isAbsolute as isAbsolute2, join as join12, resolve as resolve6 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
@@ -8224,7 +8913,7 @@ function untrackedFingerprint(root, status) {
     hash.update(relativePath);
     const path = join12(root, relativePath);
     try {
-      const stat = lstatSync2(path);
+      const stat = lstatSync3(path);
       if (stat.isSymbolicLink()) hash.update(readlinkSync(path));
       else if (stat.isFile()) hash.update(readFileSync7(path));
       else hash.update(`[${stat.mode}:${stat.size}]`);
@@ -9086,6 +9775,26 @@ function readOptions(args, name) {
   }
   return values;
 }
+function readJsonFile(path, label) {
+  try {
+    return JSON.parse(readFileSync8(resolve8(path), "utf8"));
+  } catch (error) {
+    throw new Error(`${label} must be a readable JSON file: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+function parentFilesOption(value) {
+  if (value === void 0) return void 0;
+  const mappings = {};
+  for (const rawMapping of value.split(";")) {
+    const separator = rawMapping.indexOf("=");
+    const parent = separator >= 0 ? rawMapping.slice(0, separator).trim() : "";
+    const files = separator >= 0 ? rawMapping.slice(separator + 1).split(",").map((file) => file.trim()).filter(Boolean) : [];
+    if (!parent || files.length === 0) throw new Error("lineage generate image import --parent-files requires parent=file[,file][;parent=file]");
+    if (Object.hasOwn(mappings, parent)) throw new Error(`Duplicate generation parent mapping: ${parent}`);
+    mappings[parent] = files;
+  }
+  return mappings;
+}
 function resolveCliAssetRoot(args) {
   return resolve8(readOption(args, "--asset-root") || process.env.LINEAGE_ASSET_ROOT || packageRoot);
 }
@@ -9117,7 +9826,8 @@ function resolveDataCommandOptions(args) {
     dbPath: readOption(args, "--db"),
     json: args.includes("--json"),
     project: readOption(args, "--project") || process.env.LINEAGE_DEFAULT_PRODUCT || defaultProduct,
-    rootAssetId: readOption(args, "--root")
+    rootAssetId: readOption(args, "--root"),
+    summary: readOption(args, "--summary")
   };
   if (options.dbPath) process.env.LINEAGE_DB = options.dbPath;
   return options;
@@ -9160,13 +9870,57 @@ function runLineageDataCommand(command, args) {
   }
   if (command === "link-child") {
     if (!options.childAssetId) throw new Error("lineage link-child requires --child");
+    const summary = requireEdgeSummary(options.summary);
     return linkSelectedLineageChild(options.project, {
       childAssetId: options.childAssetId,
       claimToken: options.claimToken,
       confirmWrite: options.confirmWrite,
-      rootAssetId: options.rootAssetId || options.assetId
+      rootAssetId: options.rootAssetId || options.assetId,
+      summary,
+      summaryActor: "agent"
     });
   }
+  if (command === "generate") {
+    const [resource, subcommand] = positionalArgs(args);
+    if (resource !== "image") throw new Error(`Unknown generate command: ${resource}`);
+    if (subcommand === "plan") {
+      const prompt = readOption(args, "--prompt");
+      const rawCount = readOption(args, "--count");
+      const rawPerBaseCount = readOption(args, "--per-base-count");
+      if (!prompt) throw new Error("lineage generate image plan requires --prompt");
+      return planImageGeneration(options.project, {
+        count: rawCount === void 0 ? void 0 : Number(rawCount),
+        dryRun: args.includes("--dry-run"),
+        fromLineageSelection: args.includes("--from-lineage-selection"),
+        perBaseCount: rawPerBaseCount === void 0 ? void 0 : Number(rawPerBaseCount),
+        prompt
+      });
+    }
+    if (subcommand === "inspect") {
+      const jobId2 = readOption(args, "--job-id");
+      if (!jobId2) throw new Error("lineage generate image inspect requires --job-id");
+      return inspectImageGeneration(options.project, jobId2);
+    }
+    if (subcommand === "import") {
+      const jobId2 = readOption(args, "--job-id");
+      const manifestPath = readOption(args, "--manifest");
+      const filesValue = readOption(args, "--files");
+      const parentFilesValue = readOption(args, "--parent-files");
+      if (!jobId2) throw new Error("lineage generate image import requires --job-id");
+      if (manifestPath !== void 0 && (filesValue !== void 0 || parentFilesValue !== void 0)) {
+        throw new Error("Use --manifest or legacy --files/--parent-files, not both");
+      }
+      if (filesValue !== void 0 && parentFilesValue !== void 0) throw new Error("Use --files or --parent-files, not both");
+      return importImageGenerationOutputs(options.project, {
+        confirmWrite: options.confirmWrite,
+        files: filesValue === void 0 ? void 0 : filesValue.split(",").map((file) => file.trim()).filter(Boolean),
+        jobId: jobId2,
+        manifest: manifestPath === void 0 ? void 0 : readJsonFile(manifestPath, "Generation output manifest"),
+        parentFiles: parentFilesOption(parentFilesValue)
+      });
+    }
+    throw new Error(`Unknown generate image command: ${subcommand}`);
+  }
   if (command === "reroll") {
     const subcommand = positionalArgs(args)[0] || "";
     if (subcommand === "list") {
@@ -9285,8 +10039,10 @@ function rerollRequestedBy(value) {
   throw new Error(`Invalid re-roll requester: ${value}`);
 }
 function lineageCliCanDelegateMutation(command, args) {
-  const subcommand = positionalArgs(args)[0] || "";
+  const positions = positionalArgs(args);
+  const subcommand = positions[0] || "";
   if (command === "link-child") return true;
+  if (command === "generate") return positions[0] === "image" && ["plan", "import"].includes(positions[1] || "");
   if (command === "reroll") return ["mark", "cancel", "plan", "import"].includes(subcommand);
   if (command === "tasks") return ["claim", "start", "comment", "cancel", "override", "instructions"].includes(subcommand);
   if (command === "agent") return ["claim", "heartbeat", "release", "revoke", "transfer"].includes(subcommand);
@@ -9562,6 +10318,16 @@ app.post(
     );
   })
 );
+app.post("/api/lineage/edges/:edgeId/summary", asyncRoute((req, res) => {
+  res.json(updateLineageEdgeSummary(projectFrom(req), {
+    edgeId: req.params.edgeId,
+    action: req.body.action,
+    summary: req.body.summary,
+    expectedSummaryUpdatedAt: req.body.expectedSummaryUpdatedAt,
+    confirmWrite: req.body.confirmWrite === true,
+    claimToken: claimTokenFromRequest(req)
+  }));
+}));
 app.post("/api/lineage/remove-node", asyncRoute((req, res) => {
   res.json(removeLineageNode(projectFrom(req), { assetId: String(req.body.assetId || ""), rootAssetId: typeof req.body.rootAssetId === "string" ? req.body.rootAssetId : void 0, confirmWrite: req.body.confirmWrite === true, claimToken: claimTokenFromRequest(req) }));
 }));