@forgeax/engine-pack 0.1.31 → 0.1.33

package/src/__tests__/pack-authoring-gateway.unit.test.ts

@@ -1,4 +1,4 @@
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
@@ -146,6 +146,30 @@ describe('Pack authoring gateway', () => {
       ok: true,
       value: { sources: [{ packageId: SOURCE_PACKAGE, sourcePath: 'assets/source.pack.ts' }] },
     });
+    const verified = await gateway.execute({
+      operation: 'asset.verify',
+      requestId: 'verify-source',
+    });
+    expect(verified).toMatchObject({
+      ok: true,
+      value: {
+        schemaVersion: 'asset-verification-v1',
+        scope: {
+          sourceCount: 1,
+          assetCount: 0,
+          scriptablePackSourceCount: 1,
+          scriptablePackSources: [
+            {
+              sourcePath: expect.stringContaining('assets/source.pack.ts'),
+              packageId: SOURCE_PACKAGE,
+              output: 'unproduced',
+            },
+          ],
+        },
+        assets: [],
+        summary: { unmaterializedScriptablePackCount: 1 },
+      },
+    });
 
     const instance = await gateway.execute({
       operation: 'asset-source.create-instance',
@@ -246,4 +270,99 @@ describe('Pack authoring gateway', () => {
     const result = await gateway.execute({ operation: 'asset.list', requestId: 'bad-callback' });
     expect(result).toMatchObject({ ok: false, error: { code: 'pack-parameter-invalid' } });
   });
+
+  it('accepts references to published assets owned by another producer', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-external-ref-'));
+    roots.push(root);
+    const externalGuid = '01900000-0000-7000-8000-000000000099';
+    const gateway = createFileSystemPackAuthoringGateway({
+      gameRoot: root,
+      additionalKnownGuids: () => [externalGuid],
+    });
+    await gateway.execute({
+      operation: 'asset-source.create',
+      requestId: 'create-external-ref',
+      targetPath: 'assets/direct.pack.json',
+      format: 'pack.json',
+      packageId: DIRECT_PACKAGE,
+      initialAssets: {
+        'material/main': { kind: 'material', payload: {}, refs: [externalGuid] },
+      },
+    });
+    const verified = await gateway.execute({
+      operation: 'asset.verify',
+      requestId: 'verify-external-ref',
+    });
+    expect(verified).toMatchObject({ ok: true, value: { summary: { assetCount: 1 } } });
+  });
+});
+
+it('inspects the exact source revision used by rebuild conflict checks', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'forgeax-inspect-revision-'));
+  roots.push(root);
+  const outputs = [
+    {
+      packageId: SOURCE_PACKAGE,
+      sourceKey: 'mesh/main',
+      guid: AssetGuid.format(AssetGuid.derive(packageId(SOURCE_PACKAGE), 'mesh/main')),
+      kind: 'mesh',
+      sourcePath: 'assets/source.pack.ts',
+      ready: true,
+    },
+  ];
+  let published = false;
+  const gateway = createFileSystemPackAuthoringGateway({
+    gameRoot: root,
+    materialized: () => (published ? outputs : []),
+    rebuild: async () => ({ ok: true, value: undefined }),
+  });
+  const created = await gateway.execute({
+    operation: 'asset-source.create',
+    requestId: 'create',
+    targetPath: 'assets/source.pack.ts',
+    format: 'pack.ts',
+    packageId: SOURCE_PACKAGE,
+  });
+  expect(created.ok).toBe(true);
+  if (!created.ok) return;
+  published = true;
+  const inspected = await gateway.execute({
+    operation: 'asset.inspect',
+    subject: 'assets/source.pack.ts',
+    requestId: 'inspect',
+  });
+  expect(inspected).toMatchObject({
+    ok: true,
+    value: {
+      revision: created.value.revision,
+      sourcePath: 'assets/source.pack.ts',
+      assets: outputs,
+    },
+  });
+  const rebuilt = await gateway.execute({
+    operation: 'asset-source.rebuild',
+    sourcePath: 'assets/source.pack.ts',
+    expectedRevision: created.value.revision,
+    requestId: 'rebuild',
+  });
+  expect(rebuilt).toMatchObject({
+    ok: true,
+    value: { assets: outputs, revision: created.value.revision },
+  });
+  const path = join(root, 'assets/source.pack.ts');
+  await writeFile(path, `${await readFile(path, 'utf8')}\n// source edit\n`);
+  const changed = await gateway.execute({
+    operation: 'asset.inspect',
+    subject: 'assets/source.pack.ts',
+    requestId: 'inspect-edited',
+  });
+  expect(changed.ok).toBe(true);
+  if (changed.ok) expect(changed.value.revision).not.toBe(created.value.revision);
+  const stale = await gateway.execute({
+    operation: 'asset-source.rebuild',
+    sourcePath: 'assets/source.pack.ts',
+    expectedRevision: created.value.revision,
+    requestId: 'stale',
+  });
+  expect(stale).toMatchObject({ ok: false, error: { code: 'pack-source-revision-conflict' } });
 });

package/src/__tests__/pack.unit.test.ts

@@ -540,7 +540,7 @@ const V1_WHITELIST = new Set([
           cwd: tempDir,
         });
         expect(code).toBe(0);
-        expect(io.stdout).toContain('material-validated: 1');
+        expect(JSON.parse(io.stdout[0] as string).summary.materialCount).toBe(1);
       });
 
       it('CLI verify prints material-validated: 0 when no material assets', async () => {
@@ -559,7 +559,7 @@ const V1_WHITELIST = new Set([
           cwd: tempDir,
         });
         expect(code).toBe(0);
-        expect(io.stdout).toContain('material-validated: 0');
+        expect(JSON.parse(io.stdout[0] as string).summary.materialCount).toBe(0);
       });
 
       it('CLI verify reports material payloads for later cook validation', async () => {
@@ -579,7 +579,7 @@ const V1_WHITELIST = new Set([
         });
         expect(code).toBe(0);
         expect(io.stderr).toEqual([]);
-        expect(io.stdout).toContain('material-validated: 1');
+        expect(JSON.parse(io.stdout[0] as string).summary.materialCount).toBe(1);
       });
 
       it('CLI verify counts only material assets among multiple kinds', async () => {
@@ -603,7 +603,7 @@ const V1_WHITELIST = new Set([
           cwd: tempDir,
         });
         expect(code).toBe(0);
-        expect(io.stdout).toContain('material-validated: 1');
+        expect(JSON.parse(io.stdout[0] as string).summary.materialCount).toBe(1);
       });
     });
   });
@@ -1572,7 +1572,7 @@ const V1_WHITELIST = new Set([
         });
         expect(exitCode).toBe(0);
         expect(stderrParts).toEqual([]);
-        expect(stdoutParts).toContain('material-validated: 0');
+        expect(JSON.parse(stdoutParts[0] as string).summary.materialCount).toBe(0);
       });
 
       it('accepts shader sidecar with missing paramSchema', async () => {
@@ -1606,7 +1606,7 @@ const V1_WHITELIST = new Set([
         });
         expect(exitCode).toBe(0);
         expect(stderrParts).toEqual([]);
-        expect(stdoutParts).toContain('material-validated: 0');
+        expect(JSON.parse(stdoutParts[0] as string).summary.materialCount).toBe(0);
       });
 
       it('ignores legacy shader paramSchema types', async () => {

package/src/__tests__/runtime-publication.unit.test.ts

@@ -1,5 +1,9 @@
 import { expect, it } from 'vitest';
-import { createRuntimePackPublication } from '../runtime-publication.js';
+import {
+  bindRuntimePackScope,
+  createRuntimePackPublication,
+  stripRuntimePackLifecycle,
+} from '../runtime-publication.js';
 
 it('preserves declared source keys in derived publication rows and their digest', () => {
   const input = {
@@ -34,3 +38,25 @@ it('preserves declared source keys in derived publication rows and their digest'
   });
   expect(explicit.publication.outputs).toEqual(after.publication.outputs);
 });
+
+it('separates immutable Pack content from the runtime publication tuple', () => {
+  const publication = createRuntimePackPublication({
+    pack: { assets: [{ guid: 'MESH-GUID', kind: 'mesh', payload: { vertexCount: 3 } }] },
+    scopeId: 'old-scope',
+    sourcePath: 'mesh.pack.ts',
+    sourceRevision: 'source-1',
+    packageUrl: '/mesh.pack.json',
+  });
+  const semantic = stripRuntimePackLifecycle(publication.pack) as Record<string, unknown>;
+  expect(semantic).not.toHaveProperty('scopeId');
+  expect(semantic).not.toHaveProperty('generation');
+  expect(bindRuntimePackScope(semantic, 'new-scope', 23)).toMatchObject({
+    scopeId: 'new-scope',
+    generation: 23,
+    digest: publication.pack.digest,
+  });
+  expect(bindRuntimePackScope(publication.pack, 'new-scope', 23)).toMatchObject({
+    scopeId: 'new-scope',
+    generation: 23,
+  });
+});

package/src/build.ts

@@ -119,12 +119,14 @@ export { validateProducerContract, validateProducerOutputs } from './producer-co
 export { resolveAssetSource } from './resolve-asset-source.js';
 export { parsePackV2, validateMeta, validatePack, validatePackV2 } from './runtime.js';
 export {
+  bindRuntimePackScope,
   createRuntimePackPublication,
   type RuntimePackAssetInput,
   type RuntimePackEnvelope,
   type RuntimePackInput,
   type RuntimePackPublication,
   type RuntimePackPublicationInput,
+  stripRuntimePackLifecycle,
 } from './runtime-publication.js';
 export {
   type InventoryDeclaration,

package/src/cli-asset.ts

@@ -23,7 +23,7 @@ import {
 import { readSourceInventory } from './evidence/source-inventory.js';
 import { isValidAssetGuidString } from './guid.js';
 import { parsePackV2 } from './index.js';
-import { projectScriptablePackMeta } from './pack-authoring.js';
+import { parsePackSourceJson, projectScriptablePackMeta } from './pack-authoring.js';
 import { type ScanSourceDeclaration, scanInventory } from './scanner.js';
 import { loadScriptablePack } from './scriptable-pack-node.js';
 
@@ -36,8 +36,70 @@ export interface PackEntry {
   readonly kind: string;
   readonly sourcePath: string;
   readonly name?: string;
+  readonly sourceKey?: string;
+  readonly sourceIndex?: number;
+  readonly sourceRevision?: string;
 }
 
+export interface AssetVerificationReport {
+  readonly schemaVersion: 'asset-verification-v1';
+  readonly root: string;
+  /** The bounded source scope used for this read-only report. */
+  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 assets: readonly {
+    readonly guid: string;
+    readonly type: string;
+    readonly source: {
+      readonly path: string;
+      readonly format: 'meta.json' | 'pack.json' | 'pack.ts';
+      readonly revision?: string;
+      readonly role: 'author';
+    };
+    readonly output: {
+      readonly status: 'produced' | 'unproduced' | 'unknown';
+      readonly availability: 'available' | 'missing' | 'unknown';
+      readonly freshness: 'unknown';
+      readonly packagePath?: string;
+      readonly artifactPaths?: readonly string[];
+    };
+    readonly dependencies: readonly string[];
+    readonly producer: { readonly state: 'not-run' | 'published' | 'unknown' };
+    readonly name?: string;
+    readonly sourceKey?: string;
+    readonly sourceIndex?: number;
+  }[];
+  readonly summary: {
+    readonly assetCount: number;
+    readonly emittedAssetCount: number;
+    readonly materialCount: number;
+    readonly unproducedAssetCount: number;
+    readonly unknownAssetCount: number;
+    readonly unmaterializedScriptablePackCount: number;
+  };
+}
+
+const ASSET_VERIFY_LIMIT = 256;
+
+type VerificationFacts = Pick<
+  AssetVerificationReport['assets'][number],
+  'dependencies' | 'output' | 'producer'
+>;
+
 interface AssetCtx {
   readonly stdoutWrite: (line: string) => void;
   readonly stderrWrite: (line: string) => void;
@@ -70,7 +132,10 @@ function emitError(ctx: AssetCtx, err: ScanErrShape): number {
 export async function scanEntries(
   roots: readonly string[],
   ctx: AssetCtx,
-): Promise<{ ok: true; value: PackEntry[] } | { ok: false }> {
+): Promise<
+  | { ok: true; value: PackEntry[]; declarations: ReadonlyMap<string, ScanSourceDeclaration> }
+  | { ok: false }
+> {
   const result = await scanInventory(roots);
   if (!result.ok) {
     emitError(ctx, {
@@ -102,6 +167,8 @@ export async function scanEntries(
         guid: asset.guid,
         kind: asset.kind,
         sourcePath,
+        sourceIndex: asset.sourceIndex,
+        sourceRevision: declaration.sourceRevision,
         ...(name === undefined ? {} : { name }),
       });
     }
@@ -137,6 +204,11 @@ export async function scanEntries(
       guid: inventoryEntry.guid,
       kind: inventoryEntry.kind,
       sourcePath: inventoryEntry.sourcePath,
+      sourceRevision: inventoryEntry.sourceRevision,
+      ...(inventoryEntry.sourceKey === undefined ? {} : { sourceKey: inventoryEntry.sourceKey }),
+      ...(inventoryEntry.sourceIndex === undefined
+        ? {}
+        : { sourceIndex: inventoryEntry.sourceIndex }),
       ...(name === undefined ? {} : { name }),
       ...(declaration?.format === 'pack.json' &&
       declaration.value.schemaVersion === '3.0.0' &&
@@ -149,7 +221,7 @@ export async function scanEntries(
   entries.sort((left, right) =>
     `${left.sourcePath}:${left.guid}`.localeCompare(`${right.sourcePath}:${right.guid}`),
   );
-  return { ok: true, value: entries };
+  return { ok: true, value: entries, declarations: result.value.declarations };
 }
 
 function helpBody(): string {
@@ -160,6 +232,7 @@ function helpBody(): string {
     '  forgeax asset list --root <project> --json',
     '  forgeax asset inspect --subject <guid> --root <project> --json',
     '  forgeax asset verify --root <project> --json',
+    '    output is bounded to 256 assets and includes the scanned source scope',
     '  forgeax asset inspect --subject <source.pack.ts> --root <project> --json',
     '  forgeax asset atlas --input <glob> --name <prefix> --root <project> [--output <dir>]',
     '',
@@ -342,6 +415,89 @@ async function runLookup(rest: string[], ctx: AssetCtx): Promise<number> {
   return 0;
 }
 
+function artifactPaths(value: unknown): readonly string[] {
+  if (!isRecord(value)) return [];
+  return Object.values(value).flatMap((descriptor) =>
+    isRecord(descriptor) && typeof descriptor.path === 'string' ? [descriptor.path] : [],
+  );
+}
+
+function unknownVerificationFacts(): VerificationFacts {
+  return {
+    dependencies: [],
+    output: {
+      status: 'unknown',
+      availability: 'unknown',
+      freshness: 'unknown',
+    },
+    producer: { state: 'unknown' },
+  };
+}
+
+function sourceVerificationFacts(
+  entry: PackEntry,
+  declaration: ScanSourceDeclaration | undefined,
+): VerificationFacts {
+  if (declaration === undefined) return unknownVerificationFacts();
+  if (declaration.format === 'meta.json' || declaration.format === 'pack.ts') {
+    return {
+      dependencies: [],
+      output: {
+        status: 'unproduced',
+        availability: 'unknown',
+        freshness: 'unknown',
+      },
+      producer: { state: 'not-run' },
+    };
+  }
+
+  if (declaration.value.schemaVersion === '3.0.0') {
+    const parsed = parsePackSourceJson(declaration.value);
+    if (!parsed.ok || parsed.value.format !== 'direct' || entry.sourceKey === undefined) {
+      return {
+        dependencies: [],
+        output: {
+          status: 'unproduced',
+          availability: 'unknown',
+          freshness: 'unknown',
+        },
+        producer: { state: 'not-run' },
+      };
+    }
+    const asset = parsed.value.assets[entry.sourceKey];
+    return {
+      dependencies: asset?.refs ?? [],
+      output: {
+        status: 'unproduced',
+        availability: 'unknown',
+        freshness: 'unknown',
+      },
+      producer: { state: 'not-run' },
+    };
+  }
+
+  const asset = declaration.value.assets.find(
+    (candidate) => candidate.guid.toLowerCase() === entry.guid.toLowerCase(),
+  );
+  if (asset === undefined || (asset.execution !== 'direct' && asset.execution !== 'cooked')) {
+    return unknownVerificationFacts();
+  }
+  return {
+    dependencies: asset.refs,
+    output: {
+      // A validated legacy package row is the only published evidence this
+      // offline command reads. Artifact bytes and cook receipts remain
+      // producer-owned, so availability/freshness stay explicitly unknown.
+      status: 'produced',
+      availability: 'unknown',
+      freshness: 'unknown',
+      packagePath: entry.sourcePath,
+      ...(asset.artifacts === undefined ? {} : { artifactPaths: artifactPaths(asset.artifacts) }),
+    },
+    producer: { state: 'published' },
+  };
+}
+
 async function runVerify(rest: string[], ctx: AssetCtx): Promise<number> {
   if (rest.some((value) => value === '--guid')) return runEvidence(rest, ctx);
   try {
@@ -363,10 +519,76 @@ async function runVerify(rest: string[], ctx: AssetCtx): Promise<number> {
   const cwd = ctx.cwd ?? process.cwd();
   const result = await scanEntries([cwd], ctx);
   if (!result.ok) return 1;
+  ctx.stdoutWrite(JSON.stringify(createAssetVerificationReport(cwd, result)));
+  return 0;
+}
 
+/** Build the bounded provenance projection from one validated scanner pass. */
+export function createAssetVerificationReport(
+  root: string,
+  result: {
+    readonly value: readonly PackEntry[];
+    readonly declarations: ReadonlyMap<string, ScanSourceDeclaration>;
+  },
+): AssetVerificationReport {
+  const declarations = result.declarations;
+  const sourcePaths = [...declarations.keys()].sort();
+  const scriptablePackSources = [...declarations.values()]
+    .filter(
+      (declaration): declaration is Extract<ScanSourceDeclaration, { format: 'pack.ts' }> =>
+        declaration.format === 'pack.ts',
+    )
+    .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
+  const emittedEntries = result.value.slice(0, ASSET_VERIFY_LIMIT);
+  const facts = emittedEntries.map((entry) =>
+    sourceVerificationFacts(entry, declarations.get(entry.sourcePath)),
+  );
   const materialCount = result.value.filter((e) => e.kind === 'material').length;
-  ctx.stdoutWrite(`material-validated: ${materialCount}`);
-  return 0;
+  return {
+    schemaVersion: 'asset-verification-v1',
+    root,
+    scope: {
+      sourceCount: sourcePaths.length,
+      assetCount: result.value.length,
+      sourcePaths: sourcePaths.slice(0, ASSET_VERIFY_LIMIT),
+      omittedSourceCount: Math.max(0, sourcePaths.length - ASSET_VERIFY_LIMIT),
+      assetLimit: ASSET_VERIFY_LIMIT,
+      truncated: result.value.length > ASSET_VERIFY_LIMIT,
+      scriptablePackSourceCount: scriptablePackSources.length,
+      scriptablePackSources: scriptablePackSources.slice(0, ASSET_VERIFY_LIMIT).map((source) => ({
+        sourcePath: source.sourcePath,
+        packageId: source.value.packageId,
+        output: 'unproduced' as const,
+        reason: 'producer-not-run' as const,
+      })),
+      omittedScriptablePackSourceCount: Math.max(
+        0,
+        scriptablePackSources.length - ASSET_VERIFY_LIMIT,
+      ),
+    },
+    assets: emittedEntries.map((entry, index) => ({
+      guid: entry.guid,
+      type: entry.kind,
+      source: {
+        path: entry.sourcePath,
+        format: declarations.get(entry.sourcePath)?.format ?? 'pack.json',
+        role: 'author' as const,
+        ...(entry.sourceRevision === undefined ? {} : { revision: entry.sourceRevision }),
+      },
+      ...(facts[index] as VerificationFacts),
+      ...(entry.name === undefined ? {} : { name: entry.name }),
+      ...(entry.sourceKey === undefined ? {} : { sourceKey: entry.sourceKey }),
+      ...(entry.sourceIndex === undefined ? {} : { sourceIndex: entry.sourceIndex }),
+    })),
+    summary: {
+      assetCount: result.value.length,
+      emittedAssetCount: emittedEntries.length,
+      materialCount,
+      unproducedAssetCount: facts.filter((value) => value.output.status === 'unproduced').length,
+      unknownAssetCount: facts.filter((value) => value.output.status === 'unknown').length,
+      unmaterializedScriptablePackCount: scriptablePackSources.length,
+    },
+  };
 }
 
 interface EvidenceCliOptions {

package/src/native-cooker-registry.ts

@@ -93,6 +93,19 @@ function transactionFailure(key: string, reason: string): Result<never, AssetSta
   return failure(key, { guid: 'unknown', producer: reason });
 }
 
+function thrownProducer(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  if (error !== null && typeof error === 'object') {
+    try {
+      return JSON.stringify(error);
+    } catch {
+      return Object.prototype.toString.call(error);
+    }
+  }
+  return String(error);
+}
+
 function recovered<P>(
   key: string,
   previous: NativeCookTransactionSnapshot<P>,
@@ -142,7 +155,7 @@ export class NativeCookerRegistry {
       const typedInput = cooker.discover === undefined ? input : await cooker.discover(input);
       draft = await cooker.cook(typedInput);
     } catch (error) {
-      return failure(key, { guid: 'unknown', producer: String(error) });
+      return failure(key, { guid: 'unknown', producer: thrownProducer(error) });
     }
     if (
       draft.guid.length === 0 ||