@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/asset-workflow/asset-materialization-report.ts

@@ -0,0 +1,140 @@
+/**
+ * The FAILURE CHANNEL for declared-asset-pack materialization (D-AP4):
+ * *"Failure = loud degradation, not fabrication. ... the missing asset is
+ * reported in the editor console + status surface with a retry affordance, and
+ * dependent features degrade honestly."*
+ *
+ * `materializeDeclaredAssetPacks` already fails closed per entry — it never
+ * writes placeholder bytes and never blocks the other entries — but it only
+ * RETURNS a `failed` array, and an array with no reader is the hazard: a seed
+ * that lands without its clips would look like a working editor with a
+ * mysteriously dead animation, which is the worst possible outcome and
+ * precisely what the anti-shim rule forbids.
+ *
+ * This module is that reader, and it is deliberately TWO channels, because
+ * neither alone is enough — D-AP4's own words, *"reported in the editor
+ * console + status surface with a retry affordance"*:
+ *
+ *   1. `editorConsole.error` — one line per failed entry, subsystem `assets`,
+ *      naming the library key, the destination path, the reason, and what
+ *      degrades.
+ *   2. A module-level report slot the status bar's `asset-materialization`
+ *      contribution reads (`../components/status-contributions.tsx`),
+ *      carrying the RETRY affordance. Retry re-runs materialization against
+ *      the active backend, which is safe and cheap by construction: the
+ *      materializer skips every entry already in the ledger, so a retry only
+ *      refetches what is still missing.
+ *
+ * That status item used to be a red banner across the top of the shell. The
+ * editor has ONE error home — console line, bottom-left status item, the
+ * Console utility behind it — and a second one only taught users two places
+ * to look, so the banner is gone.
+ *
+ * Same plain module-singleton + own-`subscribe` shape as
+ * `../authoring/mount-failure-report.ts`.
+ */
+
+import { editorConsole } from '@volter/sdk/kit/editor-console';
+import type { StorageBackend } from '@volter/sdk/kit/storage-types';
+import type { AssetPackMaterializationResult } from './hosted-asset-materialization';
+
+/** One declared pack entry that did not materialize — the exact fields both
+ *  channels show. Flattened out of `AssetPackMaterializationFailure` so the
+ *  banner never has to know the materializer's own types. */
+export interface AssetMaterializationFailure {
+  /** Library key, `source:id` (e.g. `local:a7c5288306d9e98cb7dbdbd2`). */
+  readonly key: string;
+  /** Project-relative destination the bytes were meant to land at. */
+  readonly dest: string;
+  /** Declaring pack name from `asset-manifest.json`. */
+  readonly pack: string;
+  /** The materializer's own reason string — never fabricated, never softened. */
+  readonly reason: string;
+}
+
+let _failures: readonly AssetMaterializationFailure[] = [];
+const _listeners = new Set<() => void>();
+
+/** `useSyncExternalStore`-compatible subscribe for the banner. */
+export function subscribeToAssetMaterializationFailures(callback: () => void): () => void {
+  _listeners.add(callback);
+  return () => _listeners.delete(callback);
+}
+
+/** Every declared entry that failed to materialize, in declaration order. */
+export function getAssetMaterializationFailures(): readonly AssetMaterializationFailure[] {
+  return _failures;
+}
+
+/** Clear the slot (the banner's dismiss). Does not retry. */
+export function clearAssetMaterializationFailures(): void {
+  _failures = [];
+  notify();
+}
+
+function notify(): void {
+  for (const listener of _listeners) listener();
+}
+
+/**
+ * The message BOTH channels use, so the console line and the banner row can
+ * never drift apart. Names the key, the destination and the reason, then says
+ * what degrades — a reader who sees only this line knows what is broken and
+ * what it costs them.
+ */
+export function formatAssetMaterializationFailure(failure: AssetMaterializationFailure): string {
+  return (
+    `Starter asset "${failure.key}" (pack "${failure.pack}") did not materialize into ` +
+    `${failure.dest}: ${failure.reason} Nothing was written for it — features that read ` +
+    'that file degrade (a missing clips GLB leaves the character standing without ' +
+    'locomotion clips). Use Retry once the cause is fixed.'
+  );
+}
+
+/**
+ * Report a materialization result through both channels. Called by every
+ * production materialization site (today: `../storage/seed.ts`'s
+ * `seedIfEmpty`) so no caller can forget to read `failed`.
+ *
+ * A result with no failures CLEARS the slot: that is what makes a successful
+ * retry dismiss its own banner.
+ */
+export function reportAssetMaterialization(result: AssetPackMaterializationResult): void {
+  const failures = result.failed.map((failure) => ({
+    key: failure.entry.key,
+    dest: failure.entry.dest,
+    pack: failure.entry.pack,
+    reason: failure.reason,
+  }));
+  for (const failure of failures) {
+    editorConsole.error(formatAssetMaterializationFailure(failure), 'assets');
+  }
+  _failures = failures;
+  notify();
+}
+
+/**
+ * Re-run materialization against `backend` and re-report. Retry-safe by
+ * construction (the materializer skips ledger-present entries), so this
+ * refetches only what is still missing.
+ *
+ * A THROW here is the manifest itself being unreadable/invalid — not a
+ * per-entry failure — so it degrades through the console too rather than
+ * becoming an unhandled rejection in a click handler.
+ */
+export async function retryAssetMaterialization(backend: StorageBackend): Promise<void> {
+  try {
+    // Lazy for the same reason the seed's call is: the materializer is the
+    // heaviest thing this report knows, and only the retry needs it.
+    const { materializeDeclaredAssetPacks } = await import('./hosted-asset-materialization');
+    const result = await materializeDeclaredAssetPacks(backend);
+    reportAssetMaterialization(result);
+  } catch (error) {
+    editorConsole.error(
+      `Retrying asset materialization failed before any entry was attempted: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      'assets',
+    );
+  }
+}

package/src/kit/asset-workflow/asset-pack-manifest.ts

@@ -0,0 +1,320 @@
+/**
+ * Asset packs — `asset-manifest.json` (D-AP1) and the pure sync/check planner
+ * behind `npm run asset-packs:sync` (D-AP2)..
+ *
+ * A PACK is a named list of `{ key, dest }`: library asset keys and the
+ * project-relative paths their bytes are copied to. It is an INPUT TO
+ * MATERIALIZATION, never a runtime concept — nothing in a running game or a
+ * scaffolded project resolves a pack. It is deliberately NOT a `volter.project.json`
+ * field: the manifest says what a project IS, a pack says how its reference
+ * material was PRODUCED.
+ *
+ * The file lives beside `volter.project.json` in `packages/game-editor/template/` and each
+ * `examples/<id>/`. A scaffolded user project does not carry it; its record is
+ * the ledger (`asset-ledger.ts`, D-AP3).
+ *
+ * The binaries stay COMMITTED — creating a project must work offline and CI must stay
+ * hermetic (D-AP2/D-AP6). What the pack adds is that they are now GENERATED: the
+ * library is the origin, and `--check` re-verifies the committed bytes against
+ * the library's own `sourceHash` without touching the network.
+ *
+ * On KEYS: a key is `source:id`, the same identity as `onlineAssetKey`. For the
+ * SSD/cloud catalog the source name is `local`, and the id is a VARIANT id
+ * (`local:a7c5288306d9e98cb7dbdbd2`), not a family id — a family has several
+ * format variants, so only the variant pins bytes. `findLocalAsset` /
+ * `findCloudAsset` both resolve variant ids, so this is an ordinary library key.
+ */
+
+import { z } from 'zod';
+
+export const AssetPackEntrySchema = z
+  .object({
+    /** `source:id` — the library's identity for the asset (variant-precise). */
+    key: z.string().regex(/^[^:]+:.+$/, 'An asset key must be "source:id"'),
+    /** Project-relative destination for the asset's main file. */
+    dest: z.string().min(1),
+    /**
+     * The PIN: sha256 of the bytes this entry declares, bare lowercase hex.
+     *
+     * Required, and the reason is trust-on-first-use. A materializer that
+     * learns the expected digest from the same response that delivers the
+     * bytes has authenticated nothing on the first fetch — a bad or moved
+     * answer is self-consistent, gets written, and its digest becomes the
+     * project's permanent `sourceHash` in the ledger. A pin is a CHECKED-IN
+     * fact reviewed in a diff, so the first fetch is verified like every
+     * later one. `asset-packs:sync --check` cross-checks it against
+     * `catalog/cloud/manifest.json` (hermetic — both sides are repo files),
+     * and `asset-pack-manifest.test.ts` asserts no in-repo pin was invented.
+     */
+    sha256: z
+      .string()
+      .regex(
+        /^[a-f0-9]{64}$/,
+        'A pack entry must pin the sha256 of its bytes as 64 lowercase hex digits',
+      ),
+  })
+  .strict();
+
+export const AssetPackManifestSchema = z
+  .object({
+    packs: z.record(z.string().min(1), z.array(AssetPackEntrySchema)),
+  })
+  .strict();
+
+export type AssetPackEntry = z.infer<typeof AssetPackEntrySchema>;
+export type AssetPackManifest = z.infer<typeof AssetPackManifestSchema>;
+
+/** Parse an `asset-manifest.json`. Throws loudly — a half-read pack
+ *  declaration would silently stop guarding the files it dropped. */
+export function parseAssetPackManifest(input: unknown): AssetPackManifest {
+  return AssetPackManifestSchema.parse(input);
+}
+
+export interface FlattenedPackEntry extends AssetPackEntry {
+  readonly pack: string;
+}
+
+/** Flatten every pack to a single entry list, rejecting two packs that claim
+ *  the same destination (whichever ran last would silently win). */
+export function flattenAssetPacks(manifest: AssetPackManifest): FlattenedPackEntry[] {
+  const flattened: FlattenedPackEntry[] = [];
+  const byDest = new Map<string, string>();
+  for (const [pack, entries] of Object.entries(manifest.packs)) {
+    for (const entry of entries) {
+      const owner = byDest.get(entry.dest);
+      if (owner !== undefined) {
+        throw new Error(
+          `Two packs declare the same destination "${entry.dest}": "${owner}" and "${pack}".`,
+        );
+      }
+      byDest.set(entry.dest, pack);
+      flattened.push({ ...entry, pack });
+    }
+  }
+  return flattened;
+}
+
+/**
+ * Build the library index `planAssetPackSync` needs from a parsed
+ * `catalog/cloud/manifest.json`.
+ *
+ * That file has TWO shapes on disk and both are live. v1 is a flat `assets`
+ * array; v2 is the canonical `families` graph whose `variants` are the assets
+ * (a family holds several format variants, and only a variant pins bytes).
+ * The checked-in snapshot is still v1 while `scripts/cloud-asset-library.ts`
+ * already emits v2, so the FIRST regeneration of that file — which ingesting
+ * anything into the library requires — flips the shape under this reader.
+ * `packages/cloud-asset-library/src/worker.ts` accepts both for exactly this
+ * reason; so does this. A reader that understood only the shape it happened to
+ * be born with would turn `asset-packs:sync --check` red on a correct tree.
+ *
+ * Throws on anything else rather than returning an empty index: an index that
+ * silently came back empty would report every declared asset as an unknown key.
+ */
+export function libraryIndexFromCloudManifest(
+  manifest: unknown,
+  source: string,
+): Map<string, LibraryAsset> {
+  const root = manifest as {
+    version?: unknown;
+    assets?: unknown;
+    families?: unknown;
+  } | null;
+  const flat = Array.isArray(root?.families)
+    ? (root.families as ManifestFamily[]).flatMap((family) =>
+        (family.variants ?? []).map((variant) => ({ ...family, ...variant })),
+      )
+    : Array.isArray(root?.assets)
+      ? (root.assets as ManifestAsset[])
+      : null;
+  if (!flat) {
+    throw new Error(
+      'A cloud asset manifest must have a v1 "assets" array or a v2 "families" array; ' +
+        `this one has neither (version ${JSON.stringify(root?.version)}).`,
+    );
+  }
+
+  const index = new Map<string, LibraryAsset>();
+  for (const asset of flat) {
+    const file = asset.files?.[0];
+    if (!file) continue;
+    const key = `${source}:${asset.id}`;
+    index.set(key, {
+      key,
+      name: asset.name,
+      license: asset.license,
+      sourceSha256: file.main.sha256,
+      sizeBytes: file.main.sizeBytes,
+      relativePath: file.main.relativePath,
+      dependencyCount: file.dependencies.length,
+    });
+  }
+  return index;
+}
+
+interface ManifestObject {
+  sha256: string;
+  sizeBytes: number;
+  relativePath: string;
+}
+interface ManifestAsset {
+  id: string;
+  name: string;
+  license: string;
+  files?: { main: ManifestObject; dependencies: ManifestObject[] }[];
+}
+interface ManifestFamily extends Omit<ManifestAsset, 'id' | 'files'> {
+  variants?: Omit<ManifestAsset, 'name' | 'license'>[];
+}
+
+/** One asset as the LIBRARY describes it — the only source of `sourceSha256`. */
+export interface LibraryAsset {
+  readonly key: string;
+  readonly name: string;
+  readonly license: string;
+  readonly sourceSha256: string;
+  readonly sizeBytes: number;
+  /** The library's own filename for the main file. */
+  readonly relativePath: string;
+  /** Sibling files the main file needs. See `unsupported-dependencies` below. */
+  readonly dependencyCount: number;
+}
+
+export type AssetPackDecision =
+  /** Committed bytes are the library's bytes. Nothing to do. */
+  | { readonly status: 'match'; readonly entry: FlattenedPackEntry }
+  /** Declared but not committed — materialize it. */
+  | { readonly status: 'missing'; readonly entry: FlattenedPackEntry; readonly asset: LibraryAsset }
+  /** Committed but not the library's bytes — hand-edited, or the library moved. */
+  | {
+      readonly status: 'stale';
+      readonly entry: FlattenedPackEntry;
+      readonly asset: LibraryAsset;
+      readonly committedSha256: string;
+    }
+  /** The key names nothing in the library. Never guessed around. */
+  | { readonly status: 'unresolved-key'; readonly entry: FlattenedPackEntry }
+  /**
+   * The declaration's pin and the library index disagree about the asset's
+   * bytes. Two independent CHECKED-IN facts contradict each other, so neither
+   * can be assumed: copying library bytes would silently overrule a reviewed
+   * pin, and trusting the pin would hide a library that moved. A human
+   * resolves it; sync never does.
+   */
+  | {
+      readonly status: 'pin-mismatch';
+      readonly entry: FlattenedPackEntry;
+      readonly asset: LibraryAsset;
+    }
+  /** Multi-file assets are not expressible as one `dest`; refuse rather than
+   *  silently drop the siblings the main file needs. */
+  | {
+      readonly status: 'unsupported-dependencies';
+      readonly entry: FlattenedPackEntry;
+      readonly asset: LibraryAsset;
+    };
+
+export interface AssetPackSyncInputs {
+  /** Library index by `source:id`. */
+  readonly library: ReadonlyMap<string, LibraryAsset>;
+  /** sha256 of each declared dest as committed, or null when absent. */
+  readonly committed: ReadonlyMap<string, string | null>;
+}
+
+/**
+ * Decide what each declared entry needs. Pure: the caller supplies the library
+ * index and the committed hashes, so this is testable without fs or network.
+ */
+export function planAssetPackSync(
+  entries: readonly FlattenedPackEntry[],
+  inputs: AssetPackSyncInputs,
+): AssetPackDecision[] {
+  return entries.map((entry) => {
+    const asset = inputs.library.get(entry.key);
+    if (!asset) return { status: 'unresolved-key', entry } as const;
+    if (asset.dependencyCount > 0) {
+      return { status: 'unsupported-dependencies', entry, asset } as const;
+    }
+    // The pin is checked BEFORE anything about the committed copy: while the
+    // two checked-in facts disagree there is no defensible expected digest to
+    // judge the copy against.
+    if (entry.sha256 !== asset.sourceSha256) {
+      return { status: 'pin-mismatch', entry, asset } as const;
+    }
+    const committedSha256 = inputs.committed.get(entry.dest) ?? null;
+    if (committedSha256 === null) return { status: 'missing', entry, asset } as const;
+    return committedSha256 === entry.sha256
+      ? ({ status: 'match', entry } as const)
+      : ({ status: 'stale', entry, asset, committedSha256 } as const);
+  });
+}
+
+/** Decisions `--check` must fail on. A `missing`/`stale` copy means the
+ *  committed tree no longer matches what the library says it is. */
+export function assetPackCheckFailures(
+  decisions: readonly AssetPackDecision[],
+): AssetPackDecision[] {
+  return decisions.filter((decision) => decision.status !== 'match');
+}
+
+/**
+ * Decisions sync can NEITHER accept nor repair — it must stop on them.
+ *
+ * Derived, not hand-listed: anything that is not already correct (`match`) and
+ * is not a work item is by definition a refusal. The hand-written version of
+ * this list silently omitted `pin-mismatch` the day that status was added, and
+ * the consequence was not a missed error but a FABRICATED one — sync would
+ * have gone on to record a `sourceHash` for bytes it never fetched or
+ * verified, which is exactly what the anti-shim rule forbids.
+ */
+export function assetPackBlockingDecisions(
+  decisions: readonly AssetPackDecision[],
+): AssetPackDecision[] {
+  const repairable = new Set<AssetPackDecision>(assetPackWorkItems(decisions));
+  return decisions.filter((decision) => decision.status !== 'match' && !repairable.has(decision));
+}
+
+/** Decisions `assets:sync` can fix by copying library bytes in. */
+export function assetPackWorkItems(
+  decisions: readonly AssetPackDecision[],
+): Extract<AssetPackDecision, { status: 'missing' | 'stale' }>[] {
+  return decisions.flatMap((decision) =>
+    decision.status === 'missing' || decision.status === 'stale' ? [decision] : [],
+  );
+}
+
+/** One line explaining a decision, for both `--check` failures and sync logs. */
+export function describeAssetPackDecision(decision: AssetPackDecision): string {
+  const where = `${decision.entry.dest} (pack "${decision.entry.pack}", key ${decision.entry.key})`;
+  switch (decision.status) {
+    case 'match':
+      return `ok        ${where}`;
+    case 'missing':
+      return `MISSING   ${where} — declared but not committed`;
+    case 'stale':
+      return (
+        `STALE     ${where} — committed bytes are sha256:${decision.committedSha256.slice(0, 12)}…, ` +
+        `the library has sha256:${decision.asset.sourceSha256.slice(0, 12)}… ` +
+        '(either the copy was hand-edited or the library moved)'
+      );
+    case 'unresolved-key':
+      return `UNKNOWN   ${where} — no such asset in the library index`;
+    case 'pin-mismatch':
+      return (
+        `PIN       ${where} — the declaration pins sha256:${decision.entry.sha256.slice(0, 12)}… ` +
+        `but the library index says sha256:${decision.asset.sourceSha256.slice(0, 12)}… ` +
+        '(re-pin the declaration only after confirming the library moved deliberately; ' +
+        'nothing is fetched or copied while these disagree)'
+      );
+    case 'unsupported-dependencies':
+      return (
+        `MULTIFILE ${where} — the library asset has ${decision.asset.dependencyCount} ` +
+        'dependency file(s); a pack entry declares exactly one destination file'
+      );
+  }
+}
+
+/** Where a project declares its library asset packs. Lives here, beside the
+ *  manifest's shape, so a reader of the PATH (the seed) does not carry the
+ *  materializer (the cloud client, the ledger, its locks). */
+export const ASSET_MANIFEST_PATH = 'asset-manifest.json';

package/src/kit/asset-workflow/asset-types.ts

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+
+export type AssetHealthCode =
+  | 'healthy'
+  | 'source-only'
+  | 'missing-file'
+  | 'missing-dependency'
+  | 'missing-thumbnail'
+  | 'unsupported-format'
+  | 'invalid-metadata'
+  | 'conversion-failed'
+  | 'missing-attribution'
+  | 'broken-asset-reference';
+
+export interface AssetHealth {
+  readonly status: 'healthy' | 'warning' | 'error';
+  readonly codes: readonly AssetHealthCode[];
+}
+
+export const AssetFileSchema = z
+  .object({
+    label: z.string().min(1),
+    path: z.string().min(1),
+    format: z.string().min(1),
+    sizeBytes: z.number().int().nonnegative(),
+    dependencies: z.array(z.string().min(1)).optional(),
+    sha256: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/)
+      .optional(),
+  })
+  .strict();
+
+export const AssetDeliverySchema = z
+  .object({
+    id: z.string().min(1),
+    kind: z.enum(['local-ssd', 'cloud', 'remote']),
+    available: z.boolean(),
+    fileIndexes: z.array(z.number().int().nonnegative()).min(1),
+  })
+  .strict();
+
+export const AssetThumbnailSchema = z
+  .object({
+    path: z.string().min(1),
+    state: z.enum(['generated', 'upstream', 'fallback', 'unsupported', 'failed']),
+    profileVersion: z.string().min(1),
+    sourceHash: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/)
+      .optional(),
+    resultHash: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/)
+      .optional(),
+    issueCode: z.string().min(1).optional(),
+  })
+  .strict();
+
+export const AssetVariantSchema = z
+  .object({
+    id: z.string().regex(/^[a-f0-9]{24}$/),
+    label: z.string().min(1),
+    type: z.enum(['model', 'animation', 'source']),
+    files: z.array(AssetFileSchema).min(1),
+    deliveries: z.array(AssetDeliverySchema).min(1),
+    thumbnail: AssetThumbnailSchema,
+    animationCount: z.number().int().nonnegative().optional(),
+    clipNames: z.array(z.string()).optional(),
+  })
+  .strict();
+
+export const AssetFamilySchema = z
+  .object({
+    id: z.string().regex(/^[a-f0-9]{24}$/),
+    source: z.string().min(1),
+    name: z.string().min(1),
+    type: z.enum(['model', 'animation', 'source']),
+    categories: z.array(z.string()),
+    tags: z.array(z.string()),
+    license: z.string().min(1),
+    author: z.string().min(1),
+    sourceUrl: z.string().url(),
+    variants: z.array(AssetVariantSchema).min(1),
+  })
+  .strict();
+
+export const AssetCatalogEnvelopeSchema = z
+  .object({
+    version: z.literal(2),
+    generatedAt: z.string().datetime(),
+    families: z.array(z.unknown()),
+  })
+  .strict();
+
+export type AssetFile = z.infer<typeof AssetFileSchema>;
+export type AssetDelivery = z.infer<typeof AssetDeliverySchema>;
+export type AssetVariant = z.infer<typeof AssetVariantSchema>;
+export type AssetFamily = z.infer<typeof AssetFamilySchema>;
+
+export interface AssetCatalogIssue {
+  readonly familyIndex: number | null;
+  readonly familyId?: string;
+  readonly path: readonly (string | number)[];
+  readonly message: string;
+}
+
+export interface AssetCatalog {
+  readonly version: 2;
+  readonly generatedAt: string;
+  readonly families: readonly AssetFamily[];
+  readonly issues: readonly AssetCatalogIssue[];
+}
+
+export function parseAssetCatalog(input: unknown): AssetCatalog {
+  const envelope = AssetCatalogEnvelopeSchema.parse(input);
+  const families: AssetFamily[] = [];
+  const issues: AssetCatalogIssue[] = [];
+  for (const [familyIndex, candidate] of envelope.families.entries()) {
+    const result = AssetFamilySchema.safeParse(candidate);
+    if (result.success) {
+      families.push(result.data);
+      continue;
+    }
+    const familyId =
+      candidate &&
+      typeof candidate === 'object' &&
+      'id' in candidate &&
+      typeof candidate.id === 'string'
+        ? candidate.id
+        : undefined;
+    for (const issue of result.error.issues) {
+      issues.push({
+        familyIndex,
+        ...(familyId ? { familyId } : {}),
+        path: issue.path.map((part) => (typeof part === 'symbol' ? String(part) : part)),
+        message: issue.message,
+      });
+    }
+  }
+  return { version: 2, generatedAt: envelope.generatedAt, families, issues };
+}