@forgeax/engine-pack 0.1.2

package/src/scanner.ts

@@ -0,0 +1,716 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import type { ImportedOutputDeclaration, PackErrorCode } from '@forgeax/engine-types';
+import { PACK_ERROR_HINTS } from '@forgeax/engine-types';
+import { loadAssetConfig } from './config.js';
+import { PackError } from './errors.js';
+import { isValidAssetGuidString } from './guid.js';
+import { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
+import { resolveAssetSource } from './resolve-asset-source.js';
+import { validateMeta, validatePack } from './schema-compiled.js';
+import { projectScriptablePackMeta, type ScriptablePackMetaJson } from './scriptable-pack.js';
+import {
+  createScriptablePackModuleExecutorPool,
+  inventoryScriptablePackSource,
+  type LoadScriptablePackOptions,
+  loadScriptablePack,
+  type ScriptablePackSourceClosureEntry,
+} from './scriptable-pack-node.js';
+
+// Minimal Result<T, E> — structurally compatible with @forgeax/engine-rhi Result
+// but defined locally to avoid a heavy runtime dep in this build-time package.
+export type ScanResult<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+function ok<T>(value: T): ScanResult<T, never> {
+  return { ok: true, value };
+}
+
+function packErr<E>(error: E): ScanResult<never, E> {
+  return { ok: false, error };
+}
+
+/** Host-owned source paths that should not enter the Pack catalog. */
+export interface ScanOptions {
+  readonly ignorePath?: (path: string) => boolean;
+  /** Timeout/executor owner for ScriptablePack metadata loading. */
+  readonly scriptablePackLoad?: LoadScriptablePackOptions;
+}
+
+export type AssetInventoryProducerKind = 'direct-pack' | 'source-meta' | 'scriptable-pack';
+
+export interface AssetInventoryOutput {
+  readonly guid: string;
+  readonly sourceKey?: string;
+  readonly sourceIndex?: number;
+  readonly kind: string;
+  readonly name?: string;
+  readonly execution?: 'direct' | 'cooked';
+  readonly refs: readonly string[];
+}
+
+export interface AssetInventoryProjectedMeta {
+  readonly schemaVersion?: string;
+  readonly packageId?: string;
+  readonly importer?: string;
+  readonly source?: string;
+  readonly name?: string;
+  readonly outputs: readonly AssetInventoryOutput[];
+  readonly externalGuids: readonly string[];
+}
+
+export interface AssetInventoryDiagnostic {
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface AssetInventoryDeclaration {
+  readonly sourcePath: string;
+  readonly canonicalSourcePath: string;
+  readonly producer: AssetInventoryProducerKind;
+  readonly packageId?: string;
+  readonly projectedMeta: AssetInventoryProjectedMeta;
+  readonly outputs: readonly AssetInventoryOutput[];
+  readonly externalGuids: readonly string[];
+  readonly sourceClosure?: readonly ScriptablePackSourceClosureEntry[];
+  readonly diagnostics: readonly AssetInventoryDiagnostic[];
+}
+
+export interface AssetInventory {
+  readonly paths: readonly string[];
+  readonly scriptablePackMeta: ReadonlyMap<string, ScriptablePackMetaJson>;
+  /** One declaration record per authored package/source, keyed by source path. */
+  readonly declarations: readonly AssetInventoryDeclaration[];
+  readonly declarationsByPath: ReadonlyMap<string, AssetInventoryDeclaration>;
+  /** Producer ownership map used by Catalog, watcher, and demand cook. */
+  readonly sourceByGuid: ReadonlyMap<string, string>;
+  readonly metaByGuid: ReadonlyMap<string, string>;
+}
+
+/**
+ * Directory names that are skipped during recursive traversal unless
+ * explicitly provided as a root in the `roots` parameter (whitelist override).
+ * Requirements §3.4 + §5 blacklist.
+ *
+ * Re-exported as `SCANNER_BLACKLIST` for cross-package reuse: the
+ * `forgeax-engine-remote-asset import --check` traversal (M4 / w21 +
+ * plan-strategy section 2.8 path b) walks the same set of source-orphan
+ * candidates as the scanner, so we share the single SSOT here.
+ */
+const BLACKLIST = new Set([
+  'node_modules',
+  '.forgeax-harness',
+  '.forgeax',
+  '.git',
+  'dist',
+  '.forgeax-asset-cache',
+  'forgeax-engine-assets',
+  'coverage',
+]);
+
+export const SCANNER_BLACKLIST: ReadonlySet<string> = BLACKLIST;
+
+function makePackError(
+  code: PackErrorCode,
+  detail: ConstructorParameters<typeof PackError>[0]['detail'],
+): PackError {
+  return new PackError({
+    code,
+    expected: `pack error: ${code}`,
+    hint: PACK_ERROR_HINTS[code],
+    detail,
+  });
+}
+
+/**
+ * For scene assets with `payload.mounts[]`, return the lowercased GUID
+ * each `mount.source` integer resolves to via `asset.refs[]`. Returns an
+ * empty iterable for non-scene assets, scene assets without mounts, or
+ * mounts with malformed `source` (out-of-range integer / non-integer) —
+ * those are caught by ajv schema validation upstream. The yielded GUIDs
+ * feed scanner step-6's mount-asset cycle DFS (D-1, R10).
+ */
+function* extractMountSourceGuids(asset: {
+  kind?: unknown;
+  payload?: unknown;
+  refs: readonly string[];
+}): Generator<string> {
+  if (asset.kind !== 'scene') return;
+  const payload = asset.payload as { mounts?: unknown } | undefined;
+  if (!payload || !Array.isArray(payload.mounts)) return;
+  for (const rawMount of payload.mounts) {
+    const mount = rawMount as { source?: unknown };
+    const idx = mount.source;
+    if (typeof idx !== 'number' || !Number.isInteger(idx)) continue;
+    if (idx < 0 || idx >= asset.refs.length) continue;
+    const resolved = asset.refs[idx];
+    if (typeof resolved !== 'string') continue;
+    yield resolved.toLowerCase();
+  }
+}
+
+/**
+ * Scan one or more root directories for `.meta.json`, `.pack.json`, and `.pack.ts` files.
+ * Runs a 7-step fail-fast validation chain (w17 + M7-T01):
+ *   Step 1 - collect all .meta.json + .pack.json + .pack.ts paths (blacklist skipped)
+ *   Step 2 - schema validation (ajv strict)
+ *   Step 3 - GUID string format validation
+ *   Step 4 - GUID collision detection
+ *   Step 5 - orphan .meta.json detection
+ *   Step 6 - cyclic reference detection (hand-written DFS)
+ *   Step 7 - complete pack and source closure validation
+ *
+ * Returns one reusable `AssetInventory` or `Err(PackError)` on the first violation.
+ *
+ * NOTE: source files without a .meta.json are logged but not fatal (requirements §5).
+ */
+export async function scanInventory(
+  roots: readonly string[],
+  opts: ScanOptions = {},
+): Promise<ScanResult<AssetInventory, PackError>> {
+  // Step 1: collect all authored package declarations. ScriptablePack metadata
+  // is projected once through the trusted loader; the resulting inventory is
+  // shared by CLI, Catalog, watcher, and producer adapters.
+  const rawPaths: string[] = [];
+  const explicitRootSet = new Set(roots);
+
+  async function traverse(dir: string): Promise<void> {
+    let entries: import('node:fs').Dirent[];
+    try {
+      entries = (await readdir(dir, { withFileTypes: true })) as import('node:fs').Dirent[];
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+
+      if (opts.ignorePath?.(fullPath) === true) continue;
+
+      if (entry.isDirectory()) {
+        // Skip blacklisted subdirectories unless the subdir is itself an explicit root
+        if (BLACKLIST.has(basename(fullPath)) && !explicitRootSet.has(fullPath)) {
+          continue;
+        }
+        await traverse(fullPath);
+      } else if (entry.isFile()) {
+        const name = entry.name;
+        if (
+          name.endsWith('.meta.json') ||
+          name.endsWith('.pack.json') ||
+          name.endsWith('.pack.ts')
+        ) {
+          rawPaths.push(fullPath);
+        }
+      }
+    }
+  }
+
+  for (const root of roots) {
+    // Explicit file roots are useful when a host wants one source package
+    // from a larger asset tree without also scanning sibling packages. Keep
+    // directory-root behaviour unchanged; this is only an opt-in whitelist.
+    try {
+      const rootStat = await stat(root);
+      if (rootStat.isFile()) {
+        if (opts.ignorePath?.(root) === true) continue;
+        if (
+          root.endsWith('.meta.json') ||
+          root.endsWith('.pack.json') ||
+          root.endsWith('.pack.ts')
+        ) {
+          rawPaths.push(root);
+        }
+        continue;
+      }
+    } catch {
+      // The existing directory traversal treats missing roots as empty.
+    }
+    await traverse(root);
+  }
+
+  // Separate meta and pack paths
+  const metaPaths = rawPaths.filter((p) => p.endsWith('.meta.json'));
+  const packPaths = rawPaths.filter((p) => p.endsWith('.pack.json'));
+  const scriptablePaths = rawPaths.filter((p) => p.endsWith('.pack.ts'));
+
+  // Step 2 + 3: parse + schema validate + GUID format validate each pack file
+  // One normalized GUID map covers pack assets and meta subAssets. The source
+  // kind stays in the path/detail evidence; identity is the normalized GUID.
+  const guidToPath = new Map<string, string>();
+  const packRefs = new Map<string, string[]>(); // guid -> refs[]
+  const scriptablePackMeta = new Map<string, ScriptablePackMetaJson>();
+  const metaByGuid = new Map<string, string>();
+  const declarations: AssetInventoryDeclaration[] = [];
+
+  for (const packPath of packPaths) {
+    let parsed: unknown;
+    try {
+      const raw = await readFile(packPath, 'utf-8');
+      parsed = JSON.parse(raw);
+    } catch {
+      return packErr(
+        makePackError('pack-malformed-pack', {
+          path: packPath,
+          ajvErrors: [{ instancePath: '', message: 'JSON parse failed' }],
+        }),
+      );
+    }
+
+    const valid = validatePack(parsed);
+    if (!valid) {
+      return packErr(
+        makePackError('pack-malformed-pack', {
+          path: packPath,
+          ajvErrors: (validatePack.errors ?? []).map((e) => ({
+            instancePath: e.instancePath,
+            message: e.message ?? 'unknown ajv error',
+          })),
+        }),
+      );
+    }
+
+    const packageContract = validateProducerContract(parsed);
+    if (!packageContract.ok) {
+      return packErr(
+        makePackError('pack-malformed-pack', {
+          path: packPath,
+          ajvErrors: [{ instancePath: '', message: packageContract.error.code }],
+        }),
+      );
+    }
+
+    // Step 3: validate GUIDs in pack
+    const packObj = parsed as {
+      packageId?: string;
+      assets: {
+        guid: string;
+        kind: string;
+        execution?: 'direct' | 'cooked';
+        name?: string;
+        payload: unknown;
+        refs: string[];
+        artifacts?: Readonly<Record<string, unknown>>;
+        sourceKey?: string;
+        sourceIndex?: number;
+      }[];
+    };
+    for (const asset of packObj.assets) {
+      if (
+        asset.kind === 'particle-effect' &&
+        asset.execution === 'direct' &&
+        (asset.refs.length > 0 || Object.keys(asset.artifacts ?? {}).length > 0)
+      ) {
+        return packErr(
+          makePackError('pack-malformed-pack', {
+            path: packPath,
+            ajvErrors: [
+              {
+                instancePath: '/assets',
+                message:
+                  'authored particle-effect assets are source-only; refs and artifacts must be empty',
+              },
+            ],
+          }),
+        );
+      }
+    }
+    const producerAssets = packObj.assets.filter(
+      (asset) => asset.sourceKey !== undefined || asset.sourceIndex !== undefined,
+    );
+    if (producerAssets.length > 0) {
+      for (const asset of producerAssets) {
+        const assetContract = validateProducerContract(asset);
+        if (!assetContract.ok) {
+          return packErr(
+            makePackError('pack-malformed-pack', {
+              path: packPath,
+              ajvErrors: [{ instancePath: '/assets', message: assetContract.error.code }],
+            }),
+          );
+        }
+      }
+      const topologyContract = validateProducerOutputs(
+        producerAssets as unknown as readonly ImportedOutputDeclaration[],
+      );
+      if (!topologyContract.ok) {
+        return packErr(
+          makePackError('pack-malformed-pack', {
+            path: packPath,
+            ajvErrors: [{ instancePath: '/assets', message: topologyContract.error.code }],
+          }),
+        );
+      }
+    }
+    for (const asset of packObj.assets) {
+      if (!isValidAssetGuidString(asset.guid)) {
+        return packErr(
+          makePackError('pack-guid-malformed', {
+            raw: asset.guid,
+            reason: 'expected 36-char RFC 4122 dash-form UUID',
+          }),
+        );
+      }
+      for (const ref of asset.refs) {
+        if (!isValidAssetGuidString(ref)) {
+          return packErr(
+            makePackError('pack-guid-malformed', {
+              raw: ref,
+              reason: 'expected 36-char RFC 4122 dash-form UUID in refs[]',
+            }),
+          );
+        }
+      }
+
+      // Step 4: collision check
+      const normalizedGuid = asset.guid.toLowerCase();
+      const existing = guidToPath.get(normalizedGuid);
+      if (existing !== undefined) {
+        return packErr(
+          makePackError('pack-guid-collision', {
+            paths: [existing, packPath],
+            guid: normalizedGuid,
+          }),
+        );
+      }
+      guidToPath.set(normalizedGuid, packPath);
+
+      // Accumulate refs for cycle detection
+      const existingRefs = packRefs.get(normalizedGuid) ?? [];
+      for (const ref of asset.refs) {
+        existingRefs.push(ref.toLowerCase());
+      }
+
+      // feat-20260608-scene-nesting-ecs-fication M1 / w14 (D-1):
+      // mount-payload-extract — for scene assets, redundantly inject the
+      // mount.source -> resolved GUID edge into the cycle graph alongside
+      // asset.refs[]. By the .pack.json convention mount.source is an
+      // integer index into the same asset.refs[], so the resolved GUID is
+      // already present in `existingRefs`; this defensive pass guarantees
+      // that any author-supplied mounts[] references participate in the
+      // cycle DFS even if the schema-emitter forgot to mirror them into
+      // refs[]. The `kind: 'mount-asset'` tag on the resulting
+      // pack-cyclic-reference detail is set by the cycle producer below
+      // (R10).
+      for (const guid of extractMountSourceGuids(asset)) {
+        existingRefs.push(guid);
+      }
+      packRefs.set(normalizedGuid, existingRefs);
+    }
+    const outputs = packObj.assets.map((asset) => ({
+      guid: asset.guid,
+      ...(asset.sourceKey === undefined ? {} : { sourceKey: asset.sourceKey }),
+      ...(asset.sourceIndex === undefined ? {} : { sourceIndex: asset.sourceIndex }),
+      kind: asset.kind,
+      ...(asset.name === undefined ? {} : { name: asset.name }),
+      ...(asset.execution === undefined ? {} : { execution: asset.execution }),
+      refs: asset.refs,
+    }));
+    declarations.push({
+      sourcePath: packPath,
+      canonicalSourcePath: packPath.replace(/\\/g, '/'),
+      producer: 'direct-pack',
+      ...(packObj.packageId === undefined ? {} : { packageId: packObj.packageId }),
+      projectedMeta: {
+        schemaVersion: '2.0.0',
+        ...(packObj.packageId === undefined ? {} : { packageId: packObj.packageId }),
+        outputs,
+        externalGuids: outputs.flatMap((output) => output.refs),
+      },
+      outputs,
+      externalGuids: outputs.flatMap((output) => output.refs),
+      diagnostics: [],
+    });
+  }
+
+  // Step 2 + 3 + 5: parse + schema validate + GUID format validate + orphan check for meta files
+  const { paths: assetPaths } = loadAssetConfig(process.cwd());
+  for (const metaPath of metaPaths) {
+    let parsed: unknown;
+    try {
+      const raw = await readFile(metaPath, 'utf-8');
+      parsed = JSON.parse(raw);
+    } catch {
+      return packErr(
+        makePackError('pack-malformed-meta', {
+          path: metaPath,
+          ajvErrors: [{ instancePath: '', message: 'JSON parse failed' }],
+        }),
+      );
+    }
+
+    const valid = validateMeta(parsed);
+    if (!valid) {
+      return packErr(
+        makePackError('pack-malformed-meta', {
+          path: metaPath,
+          ajvErrors: (validateMeta.errors ?? []).map((e) => ({
+            instancePath: e.instancePath,
+            message: e.message ?? 'unknown ajv error',
+          })),
+        }),
+      );
+    }
+
+    const metaContract = validateProducerContract(parsed);
+    if (!metaContract.ok) {
+      return packErr(
+        makePackError('pack-malformed-meta', {
+          path: metaPath,
+          ajvErrors: [{ instancePath: '', message: metaContract.error.code }],
+        }),
+      );
+    }
+
+    // Step 3: validate GUIDs in meta subAssets
+    const metaObj = parsed as {
+      packageId?: string;
+      importer?: string;
+      source?: string;
+      name?: string;
+      importSettings?: {
+        readonly externalAssets?: readonly { readonly guid?: unknown }[];
+      };
+      subAssets: {
+        guid: string;
+        sourceIndex: number;
+        sourceKey?: string;
+        kind: string;
+        name?: string;
+      }[];
+      sourceOverrides?: unknown;
+    };
+    for (const sub of metaObj.subAssets) {
+      if (!isValidAssetGuidString(sub.guid)) {
+        return packErr(
+          makePackError('pack-guid-malformed', {
+            raw: sub.guid,
+            reason: 'expected 36-char RFC 4122 dash-form UUID in subAssets[].guid',
+          }),
+        );
+      }
+      const normalizedGuid = sub.guid.toLowerCase();
+      const existing = guidToPath.get(normalizedGuid);
+      if (existing !== undefined) {
+        return packErr(
+          makePackError('pack-guid-collision', {
+            paths: [existing, metaPath],
+            guid: normalizedGuid,
+          }),
+        );
+      }
+      guidToPath.set(normalizedGuid, metaPath);
+      metaByGuid.set(normalizedGuid, metaPath);
+    }
+    const producerSubAssets = metaObj.subAssets.length > 1 ? metaObj.subAssets : [];
+    if (producerSubAssets.length > 0) {
+      const topologyContract = validateProducerOutputs(
+        producerSubAssets as unknown as readonly ImportedOutputDeclaration[],
+      );
+      if (!topologyContract.ok) {
+        return packErr(
+          makePackError('pack-malformed-meta', {
+            path: metaPath,
+            ajvErrors: [{ instancePath: '/subAssets', message: topologyContract.error.code }],
+          }),
+        );
+      }
+    }
+
+    // Step 5: orphan .meta.json check — the source file declared in meta.source must exist.
+    // Uses resolveAssetSource for three-mode dispatch (undefined derivation / @name/ path table /
+    // relative path), replacing the former hardcoded join(metaDir, metaObj.source).
+    const sourceResolved = resolveAssetSource(metaPath, metaObj.source, assetPaths);
+    if (!sourceResolved.ok) {
+      return packErr(sourceResolved.error);
+    }
+    const expectedSourcePath = sourceResolved.value;
+    try {
+      await stat(expectedSourcePath);
+    } catch {
+      return packErr(
+        makePackError('pack-orphan-meta', {
+          metaPath,
+          expectedFile: expectedSourcePath,
+        }),
+      );
+    }
+    const outputs = metaObj.subAssets.map((sub) => ({
+      guid: sub.guid,
+      ...(sub.sourceKey === undefined ? {} : { sourceKey: sub.sourceKey }),
+      sourceIndex: sub.sourceIndex,
+      kind: sub.kind,
+      ...(sub.name === undefined ? {} : { name: sub.name }),
+      refs: [],
+    }));
+    const externalGuids = (metaObj.importSettings?.externalAssets ?? []).flatMap((entry) =>
+      typeof entry.guid === 'string' ? [entry.guid] : [],
+    );
+    declarations.push({
+      sourcePath: metaPath,
+      canonicalSourcePath: metaPath.replace(/\\/g, '/'),
+      producer: 'source-meta',
+      ...(metaObj.packageId === undefined ? {} : { packageId: metaObj.packageId }),
+      projectedMeta: {
+        ...(metaObj.packageId === undefined ? {} : { packageId: metaObj.packageId }),
+        ...(metaObj.importer === undefined ? {} : { importer: metaObj.importer }),
+        ...(metaObj.source === undefined ? {} : { source: metaObj.source }),
+        ...(metaObj.name === undefined ? {} : { name: metaObj.name }),
+        outputs,
+        externalGuids,
+      },
+      outputs,
+      externalGuids,
+      diagnostics: [],
+    });
+  }
+
+  // ScriptablePack identity enters the same topology and collision authority as JSON declarations.
+  const scriptablePackExecutorPool =
+    scriptablePaths.length === 0 || opts.scriptablePackLoad?.executor !== undefined
+      ? undefined
+      : createScriptablePackModuleExecutorPool();
+  try {
+    for (const sourcePath of scriptablePaths) {
+      const executor = await scriptablePackExecutorPool?.acquire();
+      const loaded = await loadScriptablePack(sourcePath, {
+        ...opts.scriptablePackLoad,
+        metadataOnly: true,
+        ...(executor === undefined ? {} : { executor }),
+      });
+      if (!loaded.ok) {
+        const diagnostic =
+          'diagnostic' in loaded.error.detail ? loaded.error.detail.diagnostic : undefined;
+        return packErr(
+          makePackError('pack-malformed-meta', {
+            path: sourcePath,
+            ajvErrors: [
+              {
+                instancePath: '',
+                message:
+                  diagnostic === undefined
+                    ? loaded.error.code
+                    : `${loaded.error.code}: ${diagnostic}`,
+              },
+            ],
+          }),
+        );
+      }
+      const meta = projectScriptablePackMeta(loaded.value, sourcePath);
+      scriptablePackMeta.set(sourcePath, meta);
+      const sourceClosure = await inventoryScriptablePackSource(sourcePath);
+      const topology = validateProducerOutputs(
+        meta.subAssets as unknown as readonly ImportedOutputDeclaration[],
+      );
+      if (!topology.ok) {
+        return packErr(
+          makePackError('pack-malformed-meta', {
+            path: sourcePath,
+            ajvErrors: [{ instancePath: '/subAssets', message: topology.error.code }],
+          }),
+        );
+      }
+      for (const sub of meta.subAssets) {
+        const guid = sub.guid.toLowerCase();
+        const existing = guidToPath.get(guid);
+        if (existing !== undefined) {
+          return packErr(
+            makePackError('pack-guid-collision', { paths: [existing, sourcePath], guid }),
+          );
+        }
+        guidToPath.set(guid, sourcePath);
+      }
+      const outputs = meta.subAssets.map((sub) => ({
+        guid: sub.guid,
+        sourceKey: sub.sourceKey,
+        sourceIndex: sub.sourceIndex,
+        kind: sub.kind,
+        ...(sub.name === undefined ? {} : { name: sub.name }),
+        refs: [],
+      }));
+      const externalGuids = meta.importSettings.externalAssets.map((entry) => entry.guid);
+      declarations.push({
+        sourcePath,
+        canonicalSourcePath: sourcePath.replace(/\\/g, '/'),
+        producer: 'scriptable-pack',
+        packageId: meta.packageId,
+        projectedMeta: {
+          schemaVersion: meta.schemaVersion,
+          packageId: meta.packageId,
+          importer: meta.importer,
+          source: meta.source,
+          ...(meta.name === undefined ? {} : { name: meta.name }),
+          outputs,
+          externalGuids,
+        },
+        outputs,
+        externalGuids,
+        sourceClosure,
+        diagnostics: [],
+      });
+    }
+  } finally {
+    await scriptablePackExecutorPool?.dispose();
+  }
+
+  // Step 6: cyclic reference detection via hand-written DFS (no graphlib dep)
+  // visited: nodes fully processed; recStack: nodes in current DFS path
+  const visited = new Set<string>();
+  const recStack = new Set<string>();
+
+  function dfs(guid: string, path: string[]): string[] | null {
+    visited.add(guid);
+    recStack.add(guid);
+
+    for (const ref of packRefs.get(guid) ?? []) {
+      if (!visited.has(ref)) {
+        const cycle = dfs(ref, [...path, ref]);
+        if (cycle !== null) return cycle;
+      } else if (recStack.has(ref)) {
+        // Found a back-edge: reconstruct cycle from the repeated node
+        const cycleStart = path.indexOf(ref);
+        return cycleStart >= 0 ? [...path.slice(cycleStart), ref] : [...path, ref];
+      }
+    }
+
+    recStack.delete(guid);
+    return null;
+  }
+
+  for (const guid of guidToPath.keys()) {
+    if (!visited.has(guid)) {
+      const cycle = dfs(guid, [guid]);
+      if (cycle !== null) {
+        return packErr(
+          makePackError('pack-cyclic-reference', {
+            code: 'pack-cyclic-reference',
+            kind: 'mount-asset',
+            cycle,
+          }),
+        );
+      }
+    }
+  }
+
+  const declarationsByPath = new Map(
+    declarations.map((declaration) => [declaration.sourcePath, declaration]),
+  );
+  return ok({
+    paths: rawPaths,
+    scriptablePackMeta,
+    declarations,
+    declarationsByPath,
+    sourceByGuid: new Map(guidToPath),
+    metaByGuid,
+  });
+}
+
+/** Compatibility projection for callers that only need discovered paths. */
+export async function scan(
+  roots: readonly string[],
+  opts: ScanOptions = {},
+): Promise<ScanResult<string[], PackError>> {
+  const inventory = await scanInventory(roots, opts);
+  return inventory.ok ? ok([...inventory.value.paths]) : inventory;
+}