@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/database/generation-service.mjs

@@ -15,10 +15,12 @@ import {
   pollTripoTask,
   runProvider,
 } from './providers.mjs';
+import { PATINA_MAP_TYPES } from './fal-patina.mjs';
 
 const IMAGE_KINDS = new Set(['image', 'texture_image', 'concept_image']);
 const MODEL_KINDS = new Set(['text_to_model', 'image_to_model', 'multiview_to_model', 'model_segment']);
-const RESOLUTIONS = new Set(['1k', '2k', '4k']);
+const MATERIAL_KINDS = new Set(['material']);
+const RESOLUTIONS = new Set(['1k', '2k', '4k', '8k']);
 const ASPECT_RATIOS = new Set(['1:1', '16:9', '9:16', '4:3', '3:4']);
 
 function publicFile(file) {
@@ -42,6 +44,17 @@ export function publicGenerationJob(job) {
         ...(job.result.file ? { file: publicFile(job.result.file) } : {}),
         ...(job.result.previewFile ? { previewFile: publicFile(job.result.previewFile) } : {}),
         ...(job.result.conceptFile ? { conceptFile: publicFile(job.result.conceptFile) } : {}),
+        ...(job.result.materialBundle ? {
+          materialBundle: {
+            ...job.result.materialBundle,
+            ...(job.result.materialBundle.manifestFile ? { manifestFile: publicFile(job.result.materialBundle.manifestFile) } : {}),
+            variants: (job.result.materialBundle.variants ?? []).map((variant) => ({
+              ...variant,
+              preview: publicFile(variant.preview),
+              maps: Object.fromEntries(Object.entries(variant.maps ?? {}).map(([key, file]) => [key, publicFile(file)])),
+            })),
+          },
+        } : {}),
       }
     : job.result;
   return {
@@ -58,11 +71,13 @@ function configuredImageModel(id, configuration) {
 /** Pure request planner shared by MCP validation and regression tests. */
 export function resolveGenerationPlan(args, configuration = providerConfiguration()) {
   const kind = String(args.kind ?? '');
-  if (!IMAGE_KINDS.has(kind) && !MODEL_KINDS.has(kind)) {
+  if (!IMAGE_KINDS.has(kind) && !MODEL_KINDS.has(kind) && !MATERIAL_KINDS.has(kind)) {
     throw new Error(`Unsupported generation kind "${kind}".`);
   }
   const resolution = String(args.resolution ?? '1k').toLowerCase();
-  if (!RESOLUTIONS.has(resolution)) throw new Error(`Unsupported resolution "${resolution}".`);
+  if (!RESOLUTIONS.has(resolution) || (resolution === '8k' && !MATERIAL_KINDS.has(kind))) {
+    throw new Error(`Unsupported resolution "${resolution}".`);
+  }
   const aspectRatio = String(args.aspect_ratio ?? '1:1');
   if (!ASPECT_RATIOS.has(aspectRatio)) throw new Error(`Unsupported aspect ratio "${aspectRatio}".`);
   const modelProvider = String(args.model_provider ?? 'meshy');
@@ -91,7 +106,7 @@ export function resolveGenerationPlan(args, configuration = providerConfiguratio
   if (kind === 'model_segment' && !args.source_job_id) {
     throw new Error('model_segment requires source_job_id.');
   }
-  const provider = IMAGE_KINDS.has(kind) ? imageModel.provider : modelProvider;
+  const provider = MATERIAL_KINDS.has(kind) ? 'fal' : IMAGE_KINDS.has(kind) ? imageModel.provider : modelProvider;
   if (!configuration.providers[provider]) throw new Error(`${provider} is not configured.`);
   if (textViaImage && !configuration.providers[imageModel.provider]) {
     throw new Error(`${imageModel.provider} is not configured for the selected image model.`);
@@ -106,6 +121,70 @@ export function resolveGenerationPlan(args, configuration = providerConfiguratio
   };
 }
 
+function extensionFor(contentType, fallbackName = '') {
+  if (contentType === 'image/jpeg') return 'jpg';
+  if (contentType === 'image/webp') return 'webp';
+  if (contentType === 'image/png') return 'png';
+  const extension = String(fallbackName).split('.').pop()?.toLowerCase();
+  return ['jpg', 'jpeg', 'png', 'webp'].includes(extension) ? extension : 'png';
+}
+
+/** Download every ephemeral Fal output and persist one grouped material bundle locally. */
+export async function storeManagedMaterial(workspacePath, jobId, providerResult) {
+  const material = providerResult?.material;
+  if (!material || !Array.isArray(material.images)) throw new Error('Fal Patina returned no material bundle.');
+  const stored = [];
+  for (let index = 0; index < material.images.length; index += 1) {
+    const remote = material.images[index];
+    const downloaded = await downloadProviderAsset(remote.url, { maxBytes: 256 * 1024 * 1024 });
+    if (!downloaded.contentType.startsWith('image/')) throw new Error('Fal Patina returned a non-image material file.');
+    const role = remote.mapType ?? 'preview';
+    const file = publicFile(await saveObject(workspacePath, downloaded.bytes, {
+      contentType: downloaded.contentType,
+      kind: remote.mapType ? 'generated-material-map' : 'generated-material-preview',
+      name: `${role}-${index + 1}.${extensionFor(downloaded.contentType, downloaded.name)}`,
+    }));
+    stored.push({ file, mapType: remote.mapType });
+  }
+  const previews = stored.filter((entry) => entry.mapType === null).map((entry) => entry.file);
+  const variantsByMap = Object.fromEntries(PATINA_MAP_TYPES.map((map) => [
+    map,
+    stored.filter((entry) => entry.mapType === map).map((entry) => entry.file),
+  ]));
+  const variantCount = Math.max(previews.length, ...Object.values(variantsByMap).map((files) => files.length), 1);
+  const variants = Array.from({ length: variantCount }, (_, outputIndex) => ({
+    outputIndex,
+    preview: previews[outputIndex] ?? null,
+    maps: Object.fromEntries(PATINA_MAP_TYPES.flatMap((map) => (
+      variantsByMap[map][outputIndex] ? [[map, variantsByMap[map][outputIndex]]] : []
+    ))),
+  }));
+  const manifest = {
+    schema: 'toonlab-pbr-material-v1',
+    generationJobId: jobId,
+    model: 'fal-ai/patina/material',
+    provider: 'fal',
+    request: material.input,
+    generatedPrompt: material.prompt,
+    seed: material.seed,
+    timings: material.timings,
+    variants,
+  };
+  const manifestFile = publicFile(await saveObject(workspacePath, new TextEncoder().encode(JSON.stringify(manifest, null, 2)), {
+    contentType: 'application/json',
+    kind: 'generated-material-manifest',
+    name: `material-${jobId}.json`,
+  }));
+  const primary = variants[0]?.maps?.basecolor ?? variants[0]?.preview ?? Object.values(variants[0]?.maps ?? {})[0];
+  if (!primary) throw new Error('Fal Patina material bundle has no usable output.');
+  return {
+    file: primary,
+    previewFile: variants[0]?.preview ?? primary,
+    materialBundle: { ...manifest, manifestFile },
+    provider: 'fal',
+  };
+}
+
 async function referenceImage(workspacePath, relativePath) {
   const file = await readObject(workspacePath, relativePath);
   if (!String(file.mimeType).startsWith('image/')) throw new Error('Generation references must be images.');
@@ -143,6 +222,23 @@ export async function startManagedGeneration(workspacePath, args) {
     style: args.style ?? 'stylized',
     textViaImage: plan.textViaImage,
     views: Array.isArray(args.view_paths) ? args.view_paths.slice(0, 4) : [],
+    ...(plan.kind === 'material' ? {
+      enablePromptExpansion: args.enable_prompt_expansion,
+      enableSafetyChecker: args.enable_safety_checker,
+      imageSize: args.image_size,
+      imageUrl: args.image_url,
+      maps: args.maps,
+      maskUrl: args.mask_url,
+      numImages: args.num_images,
+      numInferenceSteps: args.num_inference_steps,
+      outputFormat: args.output_format,
+      seed: args.seed,
+      strength: args.strength,
+      tileSize: args.tile_size,
+      tileStride: args.tile_stride,
+      tilingMode: args.tiling_mode,
+      upscaleFactor: args.upscale_factor,
+    } : {}),
   };
   const job = await createGenerationJob(plan.provider, plan.kind, request);
   try {
@@ -182,6 +278,7 @@ export async function startManagedGeneration(workspacePath, args) {
       });
     } else {
       providerResult = await runProvider(plan.provider, {
+        ...(plan.kind === 'material' ? request : {}),
         aspectRatio: plan.aspectRatio,
         kind: plan.kind,
         model: plan.imageModel?.model,
@@ -200,6 +297,10 @@ export async function startManagedGeneration(workspacePath, args) {
         ...(conceptFile ? { conceptFile, pipeline: 'concept_image -> meshy-7' } : {}),
       }));
     }
+    if (providerResult.material) {
+      const result = await storeManagedMaterial(workspacePath, job.id, providerResult);
+      return publicGenerationJob(await finishGenerationJob(job.id, { result }));
+    }
     if (providerResult.bytes instanceof Uint8Array) {
       const file = await storeInlineImage(workspacePath, job.id, providerResult);
       return publicGenerationJob(await finishGenerationJob(job.id, {
@@ -296,8 +397,8 @@ export async function saveManagedGeneration(id, { label } = {}) {
   const job = await getGenerationJob(id);
   if (!job) throw new Error('Generation job not found.');
   if (job.status !== 'succeeded') throw new Error(`Generation job is ${job.status}, not succeeded.`);
-  if (!['text_to_model', 'image_to_model', 'multiview_to_model'].includes(job.kind) || !job.result?.file) {
-    throw new Error('Only succeeded 3D model jobs can be saved as prop assets.');
+  if (!['text_to_model', 'image_to_model', 'multiview_to_model', 'material'].includes(job.kind) || !job.result?.file) {
+    throw new Error('Only succeeded 3D model or material jobs can be saved.');
   }
   const entry = {
     aiGenerated: true,
@@ -308,7 +409,7 @@ export async function saveManagedGeneration(id, { label } = {}) {
     provider: job.provider,
     result: job.result,
     source: 'generate',
-    type: 'generated-model',
+    type: job.kind === 'material' ? 'generated-material' : 'generated-model',
   };
   return saveLibraryEntry(entry);
 }

package/database/migrations/0007_creation_revisions.sql

@@ -0,0 +1,80 @@
+create table if not exists creation_revisions (
+  id uuid primary key default gen_random_uuid(),
+  creation_id uuid not null references creations(id) on delete cascade,
+  revision_number integer not null check (revision_number > 0),
+  label text not null,
+  description text,
+  tags text[] not null default '{}',
+  document jsonb not null,
+  ai_generated boolean not null default false,
+  content_hash text not null,
+  save_source text not null default 'manual',
+  dependency_snapshot jsonb not null default '{}',
+  restored_from_revision_id uuid references creation_revisions(id) on delete set null,
+  version_name text,
+  version_tags text[] not null default '{}',
+  version_note text,
+  pinned boolean not null default false,
+  annotation_updated_at timestamptz,
+  created_at timestamptz not null default now(),
+  unique (creation_id, revision_number),
+  check (version_name is null or char_length(version_name) between 1 and 120),
+  check (version_note is null or char_length(version_note) <= 2000),
+  check (cardinality(version_tags) <= 10)
+);
+
+create index if not exists creation_revisions_creation_created
+  on creation_revisions (creation_id, revision_number desc);
+create index if not exists creation_revisions_pinned
+  on creation_revisions (creation_id, pinned, revision_number desc);
+create unique index if not exists creation_revisions_unique_name
+  on creation_revisions (creation_id, lower(version_name))
+  where version_name is not null;
+
+alter table creations
+  add column if not exists current_revision_id uuid references creation_revisions(id) on delete set null;
+
+with inserted as (
+  insert into creation_revisions (
+    creation_id, revision_number, label, description, tags, document,
+    ai_generated, content_hash, save_source
+  )
+  select
+    c.id,
+    1,
+    c.label,
+    c.description,
+    c.tags,
+    c.document,
+    c.ai_generated,
+    encode(digest(convert_to(jsonb_build_object(
+      'label', c.label,
+      'description', c.description,
+      'tags', c.tags,
+      'document', c.document,
+      'aiGenerated', c.ai_generated,
+      'dependencies', '{}'::jsonb
+    )::text, 'UTF8'), 'sha256'), 'hex'),
+    'migration'
+  from creations c
+  where c.current_revision_id is null
+    and not exists (
+      select 1 from creation_revisions r where r.creation_id = c.id
+    )
+  returning id, creation_id
+)
+update creations c
+set current_revision_id = inserted.id
+from inserted
+where c.id = inserted.creation_id;
+
+update creations c
+set current_revision_id = (
+  select r.id
+  from creation_revisions r
+  where r.creation_id = c.id
+  order by r.revision_number desc
+  limit 1
+)
+where c.current_revision_id is null
+  and exists (select 1 from creation_revisions r where r.creation_id = c.id);

package/database/migrations/0008_creation_revision_hardening.sql

@@ -0,0 +1,98 @@
+-- Repair creations imported after 0007 ran but before the import path began
+-- committing its initial snapshot.
+with inserted as (
+  insert into creation_revisions (
+    creation_id, revision_number, label, description, tags, document,
+    ai_generated, content_hash, save_source
+  )
+  select
+    c.id,
+    1,
+    c.label,
+    c.description,
+    c.tags,
+    c.document,
+    c.ai_generated,
+    encode(digest(convert_to(jsonb_build_object(
+      'label', c.label,
+      'description', c.description,
+      'tags', c.tags,
+      'document', c.document,
+      'aiGenerated', c.ai_generated,
+      'dependencies', '{}'::jsonb
+    )::text, 'UTF8'), 'sha256'), 'hex'),
+    'hardening-backfill'
+  from creations c
+  where c.current_revision_id is null
+    and not exists (select 1 from creation_revisions r where r.creation_id = c.id)
+  returning id, creation_id
+)
+update creations c
+set current_revision_id = inserted.id
+from inserted
+where c.id = inserted.creation_id;
+
+create or replace function toonlab_guard_creation_revision_snapshot()
+returns trigger
+language plpgsql
+as $$
+begin
+  if new.creation_id is distinct from old.creation_id
+    or new.revision_number is distinct from old.revision_number
+    or new.label is distinct from old.label
+    or new.description is distinct from old.description
+    or new.tags is distinct from old.tags
+    or new.document is distinct from old.document
+    or new.ai_generated is distinct from old.ai_generated
+    or new.content_hash is distinct from old.content_hash
+    or new.save_source is distinct from old.save_source
+    or new.dependency_snapshot is distinct from old.dependency_snapshot
+    or new.restored_from_revision_id is distinct from old.restored_from_revision_id
+    or new.created_at is distinct from old.created_at then
+    raise exception 'creation revision snapshots are immutable';
+  end if;
+  return new;
+end;
+$$;
+
+create trigger creation_revisions_immutable_snapshot
+before update on creation_revisions
+for each row execute function toonlab_guard_creation_revision_snapshot();
+
+create or replace function toonlab_guard_creation_revision_links()
+returns trigger
+language plpgsql
+as $$
+begin
+  if new.restored_from_revision_id is not null and not exists (
+    select 1 from creation_revisions r
+    where r.id = new.restored_from_revision_id and r.creation_id = new.creation_id
+  ) then
+    raise exception 'restored revision must belong to the same creation';
+  end if;
+  return new;
+end;
+$$;
+
+create trigger creation_revisions_same_creation_restore
+before insert or update of restored_from_revision_id, creation_id on creation_revisions
+for each row execute function toonlab_guard_creation_revision_links();
+
+create or replace function toonlab_guard_current_creation_revision()
+returns trigger
+language plpgsql
+as $$
+begin
+  if new.current_revision_id is not null and not exists (
+    select 1 from creation_revisions r
+    where r.id = new.current_revision_id and r.creation_id = new.id
+  ) then
+    raise exception 'current revision must belong to the same creation';
+  end if;
+  return new;
+end;
+$$;
+
+create trigger creations_same_current_revision
+before insert or update of current_revision_id, id on creations
+for each row execute function toonlab_guard_current_creation_revision();

package/database/migrations/0009_creation_revision_delete_integrity.sql

@@ -0,0 +1,11 @@
+-- A revision snapshot must never be rewritten merely because its source
+-- revision is deleted. NO ACTION also permits a whole creation (and all of
+-- its mutually-related revisions) to be removed by the parent cascade.
+alter table creation_revisions
+  drop constraint creation_revisions_restored_from_revision_id_fkey;
+
+alter table creation_revisions
+  add constraint creation_revisions_restored_from_revision_id_fkey
+  foreign key (restored_from_revision_id)
+  references creation_revisions(id)
+  on delete no action;

package/database/migrations/0010_external_catalog_assets.sql

@@ -0,0 +1,28 @@
+-- Catalog-only entries intentionally retain an upstream or independently
+-- mirrored public URL. They have no release-owned byte payload, so storing a
+-- fabricated SHA-256, byte count, or content type would be misleading.
+alter table catalog_assets
+  alter column sha256 drop not null,
+  alter column byte_size drop not null,
+  alter column content_type drop not null;
+
+alter table catalog_assets
+  drop constraint if exists catalog_assets_integrity_matches_scope;
+
+alter table catalog_assets
+  add constraint catalog_assets_integrity_matches_scope
+  check (
+    (
+      redistribution_scope = 'external-only'
+      and sha256 is null
+      and byte_size is null
+      and content_type is null
+    )
+    or
+    (
+      redistribution_scope <> 'external-only'
+      and sha256 is not null
+      and byte_size is not null
+      and content_type is not null
+    )
+  );