@forgeax/engine-pack 0.1.21 → 0.1.24

package/src/__tests__/inventory-schema.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import { type AuthorInventory, validateAuthorInventory } from '../inventory/declaration.js';
+
+const guid = '00000000-0000-0000-0000-000000000010';
+
+describe('author inventory declaration contract', () => {
+  it('requires one semantic sourceKey for every author row', () => {
+    const result = validateAuthorInventory({
+      declarations: [{ guid, kind: 'mesh', payload: {}, refs: [] }],
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('inventory-source-key-missing');
+      expect(result.error.detail.sourceKey).toBeUndefined();
+      expect(result.error.expected).toContain('sourceKey');
+    }
+  });
+
+  it('rejects duplicate GUID and sourceKey before projection', () => {
+    const rows: AuthorInventory = {
+      declarations: [
+        { guid, sourceKey: 'hero/body', kind: 'mesh', payload: {}, refs: [] },
+        { guid, sourceKey: 'hero/body', kind: 'material', payload: {}, refs: [] },
+      ],
+    };
+    const result = validateAuthorInventory(rows);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(['inventory-guid-duplicate', 'inventory-source-key-duplicate']).toContain(
+        result.error.code,
+      );
+      expect(result.error.detail).toHaveProperty('guid');
+      expect(result.error.hint).toContain('rename');
+    }
+  });
+
+  it('rejects GUID duplicates regardless of hex casing and padded source keys', () => {
+    const result = validateAuthorInventory({
+      declarations: [
+        { guid, sourceKey: 'hero/body', kind: 'mesh', payload: {}, refs: [] },
+        {
+          guid: guid.toUpperCase(),
+          sourceKey: 'hero/other',
+          kind: 'mesh',
+          payload: {},
+          refs: [],
+        },
+      ],
+    });
+    expect(result).toMatchObject({ ok: false, error: { code: 'inventory-guid-duplicate' } });
+
+    const padded = validateAuthorInventory({
+      declarations: [{ guid, sourceKey: ' hero/body', kind: 'mesh', payload: {}, refs: [] }],
+    });
+    expect(padded).toMatchObject({ ok: false, error: { code: 'inventory-source-key-missing' } });
+  });
+
+  it('projects declared scene binding keys without using display names', () => {
+    const result = validateAuthorInventory({
+      declarations: [
+        {
+          guid,
+          sourceKey: 'world/main',
+          kind: 'scene',
+          payload: {
+            kind: 'scene',
+            entities: [
+              { localId: 0, bindingKey: 'player', components: { Name: { value: 'Renamed' } } },
+              { localId: 1, bindingKey: 'camera', components: {} },
+            ],
+          },
+          refs: [],
+        },
+      ],
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+      value: { declarations: [{ sceneBindings: ['player', 'camera'] }] },
+    });
+  });
+
+  it('allows decorative scene entities without a gameplay binding', () => {
+    const result = validateAuthorInventory({
+      declarations: [
+        {
+          guid,
+          sourceKey: 'world/decorative',
+          kind: 'scene',
+          payload: {
+            kind: 'scene',
+            entities: [
+              { localId: 0, components: { Transform: { position: [0, 0, 0] } } },
+              { localId: 1, bindingKey: 'player', components: {} },
+            ],
+          },
+          refs: [],
+        },
+      ],
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+      value: { declarations: [{ sceneBindings: ['player'] }] },
+    });
+  });
+});

package/src/__tests__/material-cook-receipt-layer-plan.unit.test.ts

@@ -0,0 +1,16 @@
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+describe('material cook receipt layer identity', () => {
+  it('derives one stable identity from the published parameter contract', () => {
+    const parameters = [
+      { name: 'baseColor', type: 'color' as const },
+      { name: 'metallic', type: 'f32' as const },
+      { name: 'roughness', type: 'f32' as const },
+    ];
+    const first = deriveStandardLayerPlan(parameters);
+    const second = deriveStandardLayerPlan(parameters);
+    expect(first.identity).toBe(second.identity);
+    expect(first.passFamily).toEqual(['forward', 'deferred', 'shadow']);
+  });
+});

package/src/__tests__/material-cook-schema.unit.test.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import {
   type CookedMaterialRecord,
@@ -149,4 +150,65 @@ describe('cooked material schema', () => {
       error: { code: 'material-cook-record-invalid' },
     });
   });
+
+  it('rejects a Standard record whose receipt layer plan is stale', () => {
+    const standardPass = { name: 'forward', program: { module: 'forgeax::default-standard-pbr' } };
+    const standardPlan = deriveStandardLayerPlan(record.resolved.parameters, [standardPass]);
+    const standardRecord = {
+      ...record,
+      resolved: { ...record.resolved, passes: [standardPass] },
+      receipt: {
+        ...record.receipt,
+        derivedInterface: {
+          layoutIdentity: 'sha256:layout',
+          layerPlanIdentity: standardPlan.identity,
+        },
+      },
+    };
+    expect(validateCookedMaterialRecord(standardRecord)).toMatchObject({ ok: true });
+    expect(
+      validateCookedMaterialRecord({
+        ...standardRecord,
+        receipt: {
+          ...standardRecord.receipt,
+          derivedInterface: { layoutIdentity: 'sha256:layout', layerPlanIdentity: 'stale' },
+        },
+      }),
+    ).toMatchObject({
+      ok: false,
+      error: {
+        detail: { field: 'receipt.derivedInterface.layerPlanIdentity' },
+      },
+    });
+  });
+
+  it('rejects a Standard record whose receipt omits the layer plan identity', () => {
+    const standardPass = { name: 'forward', program: { module: 'forgeax::default-standard-pbr' } };
+    const standardPlan = deriveStandardLayerPlan(record.resolved.parameters, [standardPass]);
+    const standardRecord = {
+      ...record,
+      resolved: { ...record.resolved, passes: [standardPass] },
+      receipt: {
+        ...record.receipt,
+        derivedInterface: {
+          layoutIdentity: 'sha256:layout',
+          layerPlanIdentity: standardPlan.identity,
+        },
+      },
+    };
+    expect(
+      validateCookedMaterialRecord({
+        ...standardRecord,
+        receipt: {
+          ...standardRecord.receipt,
+          derivedInterface: { layoutIdentity: 'sha256:layout' },
+        },
+      }),
+    ).toMatchObject({
+      ok: false,
+      error: {
+        detail: { field: 'receipt.derivedInterface.layerPlanIdentity' },
+      },
+    });
+  });
 });

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

@@ -0,0 +1,249 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { AssetGuid, PackageId } from '../guid.js';
+import { createFileSystemPackAuthoringGateway } from '../pack-authoring-node.js';
+
+const DIRECT_PACKAGE = '01900000-0000-7000-8000-000000000070';
+const CLONE_PACKAGE = '01900000-0000-7000-8000-000000000071';
+const SOURCE_PACKAGE = '01900000-0000-7000-8000-000000000072';
+const INSTANCE_PACKAGE = '01900000-0000-7000-8000-000000000073';
+
+const roots: string[] = [];
+
+function packageId(value: string) {
+  const parsed = PackageId.parse(value);
+  if (!parsed.ok) throw parsed.error;
+  return parsed.value;
+}
+
+afterEach(async () => {
+  const root = roots.pop();
+  if (root !== undefined) await rm(root, { recursive: true, force: true });
+});
+
+describe('Pack authoring gateway', () => {
+  it('writes guid-less direct JSON, derives identity, and makes mutations idempotent', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-direct-'));
+    roots.push(root);
+    const gateway = createFileSystemPackAuthoringGateway({ gameRoot: root });
+    const operation = {
+      operation: 'asset-source.create' as const,
+      requestId: 'create-direct',
+      targetPath: 'assets/direct.pack.json',
+      format: 'pack.json' as const,
+      packageId: DIRECT_PACKAGE,
+      initialAssets: {
+        'mesh/main': { kind: 'mesh', payload: { vertices: [] }, refs: [] },
+      },
+    };
+
+    const created = await gateway.execute(operation);
+    expect(created).toMatchObject({
+      ok: true,
+      value: { packageId: DIRECT_PACKAGE, format: 'pack.json', targetPath: operation.targetPath },
+    });
+    const raw = JSON.parse(await readFile(join(root, operation.targetPath), 'utf8')) as Record<
+      string,
+      unknown
+    >;
+    expect(raw).toEqual({
+      schemaVersion: '3.0.0',
+      packageId: DIRECT_PACKAGE,
+      assets: { 'mesh/main': { kind: 'mesh', payload: { vertices: [] }, refs: [] } },
+    });
+    expect(JSON.stringify(raw)).not.toContain('guid');
+
+    const replay = await gateway.execute(operation);
+    expect(replay).toEqual(created);
+    const conflictingReplay = await gateway.execute({ ...operation, initialAssets: {} });
+    expect(conflictingReplay).toMatchObject({
+      ok: false,
+      error: { code: 'pack-source-revision-conflict' },
+    });
+
+    const unresolved = await gateway.execute({
+      operation: 'asset.resolve',
+      requestId: 'resolve-direct',
+      packageId: DIRECT_PACKAGE,
+      sourceKey: 'mesh/main',
+      require: 'ready',
+    });
+    expect(unresolved).toMatchObject({ ok: false, error: { code: 'asset-not-ready' } });
+
+    const publishedGateway = createFileSystemPackAuthoringGateway({
+      gameRoot: root,
+      materialized: () => [
+        {
+          packageId: DIRECT_PACKAGE,
+          sourceKey: 'mesh/main',
+          guid: AssetGuid.format(AssetGuid.derive(packageId(DIRECT_PACKAGE), 'mesh/main')),
+          kind: 'mesh',
+          sourcePath: 'dist/pack.json',
+          ready: true,
+          artifactsReady: true,
+        },
+      ],
+    });
+    const resolved = await publishedGateway.execute({
+      operation: 'asset.resolve',
+      requestId: 'resolve-direct-published',
+      packageId: DIRECT_PACKAGE,
+      sourceKey: 'mesh/main',
+      require: 'ready',
+    });
+    expect(resolved).toMatchObject({
+      ok: true,
+      value: {
+        packageId: DIRECT_PACKAGE,
+        sourceKey: 'mesh/main',
+        status: 'ready',
+        guid: AssetGuid.format(AssetGuid.derive(packageId(DIRECT_PACKAGE), 'mesh/main')),
+      },
+    });
+
+    const clone = await gateway.execute({
+      operation: 'asset-source.clone',
+      requestId: 'clone-direct',
+      sourcePath: operation.targetPath,
+      targetPath: 'assets/clone.pack.json',
+      packageId: CLONE_PACKAGE,
+    });
+    expect(clone).toMatchObject({ ok: true, value: { packageId: CLONE_PACKAGE } });
+    const cloneResolved = await gateway.execute({
+      operation: 'asset.resolve',
+      requestId: 'resolve-clone',
+      packageId: CLONE_PACKAGE,
+      sourceKey: 'mesh/main',
+      require: 'identity',
+    });
+    expect(cloneResolved).toMatchObject({ ok: true, value: { status: 'identity' } });
+  });
+
+  it('creates ScriptablePack source and Pack instance documents with CAS-protected value edits', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-instance-'));
+    roots.push(root);
+    const gateway = createFileSystemPackAuthoringGateway({ gameRoot: root });
+    const source = await gateway.execute({
+      operation: 'asset-source.create',
+      requestId: 'create-source',
+      targetPath: 'assets/source.pack.ts',
+      format: 'pack.ts',
+      packageId: SOURCE_PACKAGE,
+      parameters: [{ name: 'count', type: 'u32', default: 1, minimum: 1 }],
+    });
+    expect(source).toMatchObject({
+      ok: true,
+      value: { packageId: SOURCE_PACKAGE, format: 'pack.ts' },
+    });
+    const sourceText = await readFile(join(root, 'assets/source.pack.ts'), 'utf8');
+    expect(sourceText).toContain(`definePackageId("${SOURCE_PACKAGE}")`);
+    expect(sourceText).not.toContain('assets:');
+
+    const listed = await gateway.execute({ operation: 'asset.list', requestId: 'list-source' });
+    expect(listed).toMatchObject({
+      ok: true,
+      value: { sources: [{ packageId: SOURCE_PACKAGE, sourcePath: 'assets/source.pack.ts' }] },
+    });
+
+    const instance = await gateway.execute({
+      operation: 'asset-source.create-instance',
+      requestId: 'create-instance',
+      targetPath: 'assets/instance.pack.json',
+      packageId: INSTANCE_PACKAGE,
+      parentPackageId: SOURCE_PACKAGE,
+      values: { count: 4 },
+    });
+    expect(instance).toMatchObject({
+      ok: true,
+      value: {
+        packageId: INSTANCE_PACKAGE,
+        parentPackageId: SOURCE_PACKAGE,
+        effectiveValues: { count: 4 },
+      },
+    });
+    if (!instance.ok) return;
+    const instanceRevision = instance.value.revision;
+    if (instanceRevision === undefined)
+      throw new Error('create-instance did not return a revision');
+    const applied = await gateway.execute({
+      operation: 'asset-source.apply-values',
+      requestId: 'apply-values',
+      sourcePath: 'assets/instance.pack.json',
+      expectedRevision: instanceRevision,
+      values: { count: 5 },
+    });
+    expect(applied).toMatchObject({ ok: true, value: { effectiveValues: { count: 5 } } });
+    const stale = await gateway.execute({
+      operation: 'asset-source.apply-values',
+      requestId: 'apply-stale',
+      sourcePath: 'assets/instance.pack.json',
+      expectedRevision: instanceRevision,
+      values: { count: 6 },
+    });
+    expect(stale).toMatchObject({ ok: false, error: { code: 'pack-source-revision-conflict' } });
+  });
+
+  it('fails closed when the current materialized projection violates derived identity', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-projection-'));
+    roots.push(root);
+    const gateway = createFileSystemPackAuthoringGateway({
+      gameRoot: root,
+      materialized: () => [
+        {
+          packageId: DIRECT_PACKAGE,
+          sourceKey: 'mesh/main',
+          guid: AssetGuid.format(AssetGuid.derive(packageId(DIRECT_PACKAGE), 'mesh/other')),
+          kind: 'mesh',
+          ready: true,
+        },
+      ],
+    });
+
+    const result = await gateway.execute({ operation: 'asset.list', requestId: 'bad-projection' });
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'pack-guid-collision',
+        detail: {
+          expectedGuid: AssetGuid.format(AssetGuid.derive(packageId(DIRECT_PACKAGE), 'mesh/main')),
+        },
+      },
+    });
+  });
+
+  it('does not fall back from a missing sourcePath to another package locator', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-locator-'));
+    roots.push(root);
+    const gateway = createFileSystemPackAuthoringGateway({ gameRoot: root });
+    await gateway.execute({
+      operation: 'asset-source.create',
+      requestId: 'create-locator-source',
+      targetPath: 'assets/direct.pack.json',
+      format: 'pack.json',
+      packageId: DIRECT_PACKAGE,
+      initialAssets: {},
+    });
+    const result = await gateway.execute({
+      operation: 'asset.inspect',
+      requestId: 'inspect-missing-locator',
+      sourcePath: 'assets/missing.pack.json',
+      packageId: DIRECT_PACKAGE,
+    });
+    expect(result).toMatchObject({ ok: false, error: { code: 'pack-source-not-found' } });
+  });
+
+  it('converts a broken materialized projection callback into a structured error', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-gateway-projection-callback-'));
+    roots.push(root);
+    const gateway = createFileSystemPackAuthoringGateway({
+      gameRoot: root,
+      materialized: () => {
+        throw new Error('projection unavailable');
+      },
+    });
+    const result = await gateway.execute({ operation: 'asset.list', requestId: 'bad-callback' });
+    expect(result).toMatchObject({ ok: false, error: { code: 'pack-parameter-invalid' } });
+  });
+});