@forgeax/engine-pack 0.1.31 → 0.1.33

package/src/pack-authoring-node.ts

@@ -3,6 +3,7 @@ import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
 import type { AssetGuid as EngineAssetGuid, Result } from '@forgeax/engine-types';
 import { err, ok } from '@forgeax/engine-types';
+import type { AssetVerificationReport } from './cli-asset.js';
 import { AssetGuid, isValidAssetGuidString, isValidPackSourceKey, PackageId } from './guid.js';
 import {
   type AnyScriptablePackDefinition,
@@ -42,6 +43,12 @@ export interface FileSystemPackAuthoringOptions {
   readonly materialized?: () =>
     | readonly PackAuthoringMaterializedAsset[]
     | Promise<readonly PackAuthoringMaterializedAsset[]>;
+  /**
+   * GUIDs published by non-Pack producers in the same Catalog projection.
+   * They are accepted as dependency identities but never exposed as Pack
+   * authoring assets.
+   */
+  readonly additionalKnownGuids?: () => readonly string[] | Promise<readonly string[]>;
   /** Build owner callback; the gateway itself does not own DDC or Catalog state. */
   readonly rebuild?: (
     sourcePath: string,
@@ -106,6 +113,8 @@ interface GatewaySnapshot {
   readonly knownGuids: ReadonlySet<string>;
 }
 
+const VERIFY_PROVENANCE_LIMIT = 256;
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -473,6 +482,58 @@ async function readMaterialized(
   return ok(materialized);
 }
 
+async function readAdditionalKnownGuids(
+  options: FileSystemPackAuthoringOptions,
+  operation: PackAuthoringOperation,
+): Promise<Result<readonly string[], PackAuthoringError>> {
+  let rawGuids: unknown;
+  try {
+    rawGuids = (await options.additionalKnownGuids?.()) ?? [];
+  } catch (cause) {
+    return err(
+      makeError(
+        'pack-parameter-invalid',
+        'the additionalKnownGuids callback to return current Catalog GUIDs',
+        'repair the build-owner Catalog projection callback, then retry the Pack operation',
+        {
+          requestId: operation.requestId,
+          cause: cause instanceof Error ? cause.message : String(cause),
+        },
+      ),
+    );
+  }
+  if (!Array.isArray(rawGuids)) {
+    return err(
+      makeError(
+        'pack-parameter-invalid',
+        'additionalKnownGuids to be an array of AssetGuid strings',
+        'repair the build-owner Catalog projection before querying Pack authoring',
+        { requestId: operation.requestId, actual: typeof rawGuids },
+      ),
+    );
+  }
+  const guids: string[] = [];
+  const seen = new Set<string>();
+  for (const candidate of rawGuids) {
+    if (typeof candidate !== 'string' || !isValidAssetGuidString(candidate)) {
+      return err(
+        makeError(
+          'pack-parameter-invalid',
+          'additionalKnownGuids to contain valid AssetGuid strings',
+          'repair the build-owner Catalog projection before querying Pack authoring',
+          { requestId: operation.requestId, guid: candidate },
+        ),
+      );
+    }
+    const guid = candidate.toLowerCase();
+    if (!seen.has(guid)) {
+      seen.add(guid);
+      guids.push(guid);
+    }
+  }
+  return ok(guids);
+}
+
 async function createSnapshot(
   options: FileSystemPackAuthoringOptions,
   operation: PackAuthoringOperation,
@@ -534,6 +595,8 @@ async function createSnapshot(
   }
   const materializedResult = await readMaterialized(options, operation);
   if (!materializedResult.ok) return materializedResult;
+  const additionalKnownGuidsResult = await readAdditionalKnownGuids(options, operation);
+  if (!additionalKnownGuidsResult.ok) return additionalKnownGuidsResult;
   const materialized = materializedResult.value;
   const guidOwners = new Map<string, string>();
   const directPairs = new Set<string>();
@@ -591,6 +654,7 @@ async function createSnapshot(
     ...scanned.value.inventory.map((entry) => entry.guid.toLowerCase()),
     ...directAssets.map((asset) => asset.guid),
     ...materialized.map((asset) => asset.guid),
+    ...additionalKnownGuidsResult.value,
   ]);
   return ok({ inventory: scanned.value, subjects, directAssets, materialized, knownGuids });
 }
@@ -753,6 +817,19 @@ async function inspectAsset(
   const selected = subjectFor(gameRoot, snapshot, operation);
   if (!selected.ok) return selected;
   const subject = selected.value;
+  const source = await readConfined({ gameRoot }, operation, subject.relativePath);
+  if (!source.ok) return source;
+  const inspectedSource = {
+    ...sourceResult(subject, operation),
+    revision: source.value.revision,
+    ...(subject.format === 'source'
+      ? {
+          assets: snapshot.materialized
+            .filter((asset) => asset.packageId === packageKey(subject.packageId))
+            .map((asset) => ({ ...asset })),
+        }
+      : {}),
+  };
   if (operation.sourceKey !== undefined) {
     if (!isValidPackSourceKey(operation.sourceKey)) {
       return err(
@@ -787,7 +864,7 @@ async function inspectAsset(
           candidate.sourceKey === operation.sourceKey,
       );
       return ok({
-        ...sourceResult(subject, operation),
+        ...inspectedSource,
         sourceKey: asset.sourceKey,
         guid: asset.guid,
         kind: asset.kind,
@@ -807,7 +884,7 @@ async function inspectAsset(
           candidate.sourceKey === operation.sourceKey,
       );
       return ok({
-        ...sourceResult(subject, operation),
+        ...inspectedSource,
         sourceKey: operation.sourceKey,
         guid,
         ...(materialized === undefined
@@ -833,7 +910,7 @@ async function inspectAsset(
     const resolved = await resolveInstance(snapshot, subject);
     if (!resolved.ok) return resolved;
     return ok({
-      ...sourceResult(subject, operation),
+      ...inspectedSource,
       parameters: resolved.value.parameters.map((parameter) => ({
         name: parameter.name,
         type: parameter.type,
@@ -847,7 +924,7 @@ async function inspectAsset(
       parentChain: resolved.value.parentChain,
     });
   }
-  return ok(sourceResult(subject, operation));
+  return ok(inspectedSource);
 }
 
 function listAssets(
@@ -1172,7 +1249,197 @@ async function resolveAsset(
   });
 }
 
+type VerificationAsset = AssetVerificationReport['assets'][number];
+
+function verificationSourceFormat(
+  gameRoot: string,
+  sourcePath: string | undefined,
+  fallback: VerificationAsset['source']['format'] = 'pack.ts',
+): VerificationAsset['source']['format'] {
+  if (sourcePath === undefined) return fallback;
+  const absolute = resolve(gameRoot, sourcePath);
+  if (absolute.endsWith('.meta.json')) return 'meta.json';
+  if (absolute.endsWith('.pack.json')) return 'pack.json';
+  if (absolute.endsWith('.pack.ts')) return 'pack.ts';
+  return fallback;
+}
+
+function verificationAuthorFacts(
+  snapshot: GatewaySnapshot,
+  entry: GatewaySnapshot['inventory']['inventory'][number],
+): { readonly name?: string; readonly dependencies: readonly string[] } {
+  const declaration = snapshot.inventory.declarations.get(entry.sourcePath);
+  if (declaration?.format === 'meta.json') {
+    const asset = declaration.value.subAssets.find(
+      (candidate) => candidate.guid.toLowerCase() === entry.guid.toLowerCase(),
+    );
+    return {
+      ...(asset?.name === undefined && asset?.sourceKey === undefined
+        ? {}
+        : { name: asset.name ?? asset.sourceKey }),
+      dependencies: [],
+    };
+  }
+  if (declaration?.format === 'pack.json') {
+    if (declaration.value.schemaVersion === '3.0.0') {
+      const parsed = parsePackSourceJson(declaration.value);
+      if (parsed.ok && parsed.value.format === 'direct' && entry.sourceKey !== undefined) {
+        const asset = parsed.value.assets[entry.sourceKey];
+        return {
+          ...(asset?.name === undefined ? {} : { name: asset.name }),
+          dependencies: asset?.refs ?? [],
+        };
+      }
+    } else {
+      const asset = declaration.value.assets.find(
+        (candidate) => candidate.guid.toLowerCase() === entry.guid.toLowerCase(),
+      );
+      return {
+        ...(asset?.name === undefined ? {} : { name: asset.name }),
+        dependencies: asset?.refs ?? [],
+      };
+    }
+  }
+  return { dependencies: [] };
+}
+
+function verificationOutput(
+  materialized: MaterializedAsset | undefined,
+  legacyPublished = false,
+): VerificationAsset['output'] {
+  if (materialized !== undefined) {
+    return {
+      status: materialized.ready ? 'produced' : 'unknown',
+      availability: materialized.ready ? 'available' : 'unknown',
+      freshness: 'unknown',
+    };
+  }
+  if (legacyPublished) {
+    return {
+      status: 'produced',
+      availability: 'unknown',
+      freshness: 'unknown',
+      // A legacy Pack row is a validated published declaration. The bytes
+      // remain outside this read-only gateway, so availability is unknown.
+    };
+  }
+  return { status: 'unproduced', availability: 'unknown', freshness: 'unknown' };
+}
+
+function createGatewayVerificationReport(
+  gameRoot: string,
+  snapshot: GatewaySnapshot,
+): AssetVerificationReport & Pick<PackAuthoringOperationResult, 'operation' | 'requestId'> {
+  const materializedByGuid = new Map(
+    snapshot.materialized.map((asset) => [asset.guid.toLowerCase(), asset] as const),
+  );
+  const rows = new Map<string, VerificationAsset>();
+  for (const entry of snapshot.inventory.inventory) {
+    const declaration = snapshot.inventory.declarations.get(entry.sourcePath);
+    const format = declaration?.format ?? verificationSourceFormat(gameRoot, entry.sourcePath);
+    const facts = verificationAuthorFacts(snapshot, entry);
+    const materialized = materializedByGuid.get(entry.guid.toLowerCase());
+    const legacyPublished =
+      declaration?.format === 'pack.json' && declaration.value.schemaVersion !== '3.0.0';
+    rows.set(entry.guid.toLowerCase(), {
+      guid: entry.guid,
+      type: entry.kind,
+      source: {
+        path: entry.sourcePath,
+        format,
+        role: 'author',
+        ...(entry.sourceRevision === undefined ? {} : { revision: entry.sourceRevision }),
+      },
+      output: verificationOutput(materialized, legacyPublished),
+      dependencies: facts.dependencies,
+      producer: {
+        state: materialized !== undefined ? 'published' : legacyPublished ? 'published' : 'not-run',
+      },
+      ...(facts.name === undefined ? {} : { name: facts.name }),
+      ...(entry.sourceKey === undefined ? {} : { sourceKey: entry.sourceKey }),
+      ...(entry.sourceIndex === undefined ? {} : { sourceIndex: entry.sourceIndex }),
+    });
+  }
+  for (const asset of snapshot.materialized) {
+    const key = asset.guid.toLowerCase();
+    if (rows.has(key)) continue;
+    const sourcePath =
+      asset.sourcePath === undefined ? undefined : resolve(gameRoot, asset.sourcePath);
+    const declaration =
+      sourcePath === undefined ? undefined : snapshot.inventory.declarations.get(sourcePath);
+    const format = declaration?.format ?? verificationSourceFormat(gameRoot, asset.sourcePath);
+    rows.set(key, {
+      guid: asset.guid,
+      type: asset.kind,
+      source: {
+        path: sourcePath ?? `${asset.packageId}/${asset.sourceKey}`,
+        format,
+        role: 'author',
+        ...(declaration === undefined ? {} : { revision: declaration.sourceRevision }),
+      },
+      output: verificationOutput(asset),
+      dependencies: asset.refs ?? [],
+      producer: { state: 'published' },
+      sourceKey: asset.sourceKey,
+    });
+  }
+  const assets = [...rows.values()].sort((left, right) =>
+    `${left.source.path}:${left.guid}`.localeCompare(`${right.source.path}:${right.guid}`),
+  );
+  const emitted = assets.slice(0, VERIFY_PROVENANCE_LIMIT);
+  const sourcePaths = [...snapshot.inventory.declarations.keys()].sort();
+  const scriptablePackSources = [...snapshot.inventory.declarations.values()]
+    .filter((declaration) => declaration.format === 'pack.ts')
+    .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
+  const unmaterializedScriptable = scriptablePackSources.filter(
+    (source) =>
+      !snapshot.materialized.some(
+        (asset) =>
+          asset.packageId === source.value.packageId.toLowerCase() ||
+          (asset.sourcePath !== undefined &&
+            resolve(gameRoot, asset.sourcePath) === source.sourcePath),
+      ),
+  );
+  return {
+    schemaVersion: 'asset-verification-v1',
+    root: resolve(gameRoot),
+    operation: 'asset.verify',
+    requestId: 'gateway',
+    scope: {
+      sourceCount: sourcePaths.length,
+      assetCount: assets.length,
+      sourcePaths: sourcePaths.slice(0, VERIFY_PROVENANCE_LIMIT),
+      omittedSourceCount: Math.max(0, sourcePaths.length - VERIFY_PROVENANCE_LIMIT),
+      assetLimit: VERIFY_PROVENANCE_LIMIT,
+      truncated: assets.length > VERIFY_PROVENANCE_LIMIT,
+      scriptablePackSourceCount: scriptablePackSources.length,
+      scriptablePackSources: unmaterializedScriptable
+        .slice(0, VERIFY_PROVENANCE_LIMIT)
+        .map((source) => ({
+          sourcePath: source.sourcePath,
+          packageId: source.value.packageId,
+          output: 'unproduced' as const,
+          reason: 'producer-not-run' as const,
+        })),
+      omittedScriptablePackSourceCount: Math.max(
+        0,
+        unmaterializedScriptable.length - VERIFY_PROVENANCE_LIMIT,
+      ),
+    },
+    assets: emitted,
+    summary: {
+      assetCount: assets.length,
+      emittedAssetCount: emitted.length,
+      materialCount: assets.filter((asset) => asset.type === 'material').length,
+      unproducedAssetCount: assets.filter((asset) => asset.output.status === 'unproduced').length,
+      unknownAssetCount: assets.filter((asset) => asset.output.status === 'unknown').length,
+      unmaterializedScriptablePackCount: unmaterializedScriptable.length,
+    },
+  };
+}
+
 async function verify(
+  gameRoot: string,
   snapshot: GatewaySnapshot,
   operation: PackAuthoringOperation,
 ): Promise<Result<PackAuthoringOperationResult, PackAuthoringError>> {
@@ -1220,14 +1487,8 @@ async function verify(
       );
     }
   }
-  return ok({
-    operation: operation.operation,
-    requestId: operation.requestId,
-    snapshot: {
-      sourceCount: snapshot.subjects.size,
-      assetCount: snapshotAssets(snapshot).length,
-    },
-  });
+  const report = createGatewayVerificationReport(gameRoot, snapshot);
+  return ok({ ...report, operation: operation.operation, requestId: operation.requestId });
 }
 
 function packageIdFromOperation(
@@ -1391,7 +1652,8 @@ async function executeRaw(
   if (!snapshot.ok) return snapshot;
   if (operation.operation === 'asset.resolve')
     return resolveAsset(options.gameRoot, snapshot.value, operation);
-  if (operation.operation === 'asset.verify') return verify(snapshot.value, operation);
+  if (operation.operation === 'asset.verify')
+    return verify(options.gameRoot, snapshot.value, operation);
 
   if (operation.operation === 'asset-source.create') {
     const path = confinedPath(
@@ -1939,6 +2201,9 @@ async function executeRaw(
       selected.value.packageId,
       {
         format: refreshed.value.relative.endsWith('.pack.json') ? 'pack.json' : 'pack.ts',
+        assets: refreshedSnapshot.value.materialized
+          .filter((asset) => asset.packageId === packageKey(selected.value.packageId))
+          .map((asset) => ({ ...asset })),
       },
     );
   }

package/src/pack-authoring.ts

@@ -1371,6 +1371,7 @@ export type PackAuthoringResolutionStatus = 'identity' | 'present' | 'ready';
 export interface PackAuthoringOperationResult {
   readonly operation: PackAuthoringOperationId;
   readonly requestId: string;
+  readonly schemaVersion?: 'asset-verification-v1';
   readonly sourcePath?: string;
   readonly targetPath?: string;
   readonly revision?: string;
@@ -1392,6 +1393,31 @@ export interface PackAuthoringOperationResult {
     readonly sourceCount: number;
     readonly assetCount: number;
   };
+  /** Bounded source/output facts for read-only verification consumers. */
+  readonly scope?: {
+    readonly sourceCount: number;
+    readonly assetCount: number;
+    readonly sourcePaths: readonly string[];
+    readonly omittedSourceCount: number;
+    readonly assetLimit: number;
+    readonly truncated: boolean;
+    readonly scriptablePackSourceCount: number;
+    readonly scriptablePackSources: readonly {
+      readonly sourcePath: string;
+      readonly packageId: string;
+      readonly output: 'unproduced';
+      readonly reason: 'producer-not-run';
+    }[];
+    readonly omittedScriptablePackSourceCount: number;
+  };
+  readonly summary?: {
+    readonly assetCount: number;
+    readonly emittedAssetCount: number;
+    readonly materialCount: number;
+    readonly unproducedAssetCount: number;
+    readonly unknownAssetCount: number;
+    readonly unmaterializedScriptablePackCount: number;
+  };
 }
 
 export interface PackAuthoringGatewayPort<TResult = unknown> {

package/src/runtime-publication.ts

@@ -53,6 +53,50 @@ export interface RuntimePackPublicationInput {
   readonly externalEvidence?: readonly AssetPublicationExternalEvidence[];
 }
 
+function isRuntimePackEnvelope(value: unknown): value is RuntimePackEnvelope {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    record.schemaVersion === '2.0.0' &&
+    record.kind === 'internal-text-package' &&
+    typeof record.scopeId === 'string' &&
+    record.scopeId.length > 0 &&
+    typeof record.generation === 'number' &&
+    Number.isSafeInteger(record.generation) &&
+    record.generation > 0 &&
+    Array.isArray(record.assets)
+  );
+}
+
+/**
+ * Return the immutable Pack content used by DDC identity.  Runtime scope and
+ * publication generation fence a live consumer, but do not change the
+ * cooked asset bytes represented by an immutable DDC key.
+ */
+export function stripRuntimePackLifecycle(value: unknown): unknown {
+  if (!isRuntimePackEnvelope(value)) return value;
+  const { scopeId: _scopeId, generation: _generation, ...semantic } = value;
+  return semantic;
+}
+
+/** Rehydrate a DDC Pack payload into the active runtime scope for transport. */
+export function bindRuntimePackScope(value: unknown, scopeId: string, generation: number): unknown {
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    (value as { readonly schemaVersion?: unknown }).schemaVersion !== '2.0.0' ||
+    (value as { readonly kind?: unknown }).kind !== 'internal-text-package' ||
+    !Array.isArray((value as { readonly assets?: unknown }).assets)
+  ) {
+    return value;
+  }
+  // The accepted Catalog tuple is authoritative for a live transport. This
+  // also repairs a legacy DDC body whose publication generation predates the
+  // current accepted candidate.
+  return { ...(value as Record<string, unknown>), scopeId, generation };
+}
+
 function stable(value: unknown): string {
   if (value instanceof Uint8Array) return `bytes:${Buffer.from(value).toString('base64')}`;
   if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;

package/src/scanner.ts

@@ -63,11 +63,11 @@ export interface ScriptablePackScanOptions {
 
 /** Stable default policy shared by inventory and production owners. */
 export const STANDARD_SCRIPTABLE_PACK_SCAN_OPTIONS = Object.freeze({
-  // Scriptable Packs execute in an isolated worker.  A cold worker must
-  // compile the authored source closure before it can return metadata;
-  // heavy procedural packs otherwise make the shared catalog fall back to
-  // an empty degraded projection at the old 15-second budget.
-  timeoutMs: 60_000,
+  // Scriptable Packs execute in an isolated worker. A cold worker must compile
+  // the authored source closure before it can return metadata. Keep the bound
+  // finite while allowing a heavy character/scene closure to complete on a
+  // busy host.
+  timeoutMs: 120_000,
 }) satisfies ScriptablePackScanOptions;
 
 export interface InventoryDeclaration {