@forgeax/engine-pack 0.1.2

package/src/__tests__/offline-evidence-artifact-verification-owner.test-d.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import type {
+  ArtifactDescriptor,
+  ArtifactVerificationStatus,
+  AssetEvidenceArtifact,
+  AssetEvidencePackageInput,
+} from '@forgeax/engine-types';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { OfflineArtifactInput, OfflinePackageInput } from '../evidence/offline-evidence.js';
+import type { buildOfflineAssetEvidence } from '../index.js';
+
+const guid = '11111111-1111-4111-8111-111111111111';
+const projectionSource = readFileSync(
+  new URL('../evidence/offline-evidence.ts', import.meta.url),
+  'utf8',
+);
+
+type SharedOptionalVerification = AssetEvidencePackageInput['artifacts'][string]['verification'];
+type PublicOfflineArtifact = NonNullable<
+  Parameters<typeof buildOfflineAssetEvidence>[0]['package']
+>['artifacts'][string];
+
+describe('offline artifact verification owner', () => {
+  it('derives the optional offline projection from the shared status owner', () => {
+    expectTypeOf<ArtifactVerificationStatus>().toEqualTypeOf<'notChecked' | 'passed' | 'failed'>();
+    expectTypeOf<OfflineArtifactInput['verification']>().toEqualTypeOf<
+      ArtifactVerificationStatus | undefined
+    >();
+    expectTypeOf<
+      OfflineArtifactInput['verification']
+    >().toEqualTypeOf<SharedOptionalVerification>();
+    expectTypeOf<
+      AssetEvidenceArtifact['verification']
+    >().toEqualTypeOf<ArtifactVerificationStatus>();
+    expectTypeOf<PublicOfflineArtifact['verification']>().toEqualTypeOf<
+      ArtifactVerificationStatus | undefined
+    >();
+    expectTypeOf<'unknown'>().not.toExtend<ArtifactVerificationStatus>();
+  });
+
+  it('keeps artifact verification optional at the offline input boundary', () => {
+    const descriptor = {
+      path: 'artifacts/data.bin',
+      mediaType: 'application/octet-stream',
+    } satisfies ArtifactDescriptor;
+    const input = {
+      guid,
+      artifacts: { data: descriptor },
+    } satisfies OfflinePackageInput;
+    const publicInput = {
+      guid,
+      package: input,
+    } satisfies Parameters<typeof buildOfflineAssetEvidence>[0];
+    void publicInput;
+  });
+
+  it('keeps the source projection tied to the shared type instead of a second ledger', () => {
+    expect(projectionSource).toContain('ArtifactVerificationStatus');
+    expect(projectionSource).toContain('readonly verification?: ArtifactVerificationStatus;');
+    expect(projectionSource).not.toContain(
+      "readonly verification?: 'notChecked' | 'passed' | 'failed';",
+    );
+  });
+});

package/src/__tests__/offline-evidence.integration.test.ts

@@ -0,0 +1,106 @@
+import { readFile } from 'node:fs/promises';
+import { describe, expect, it } from 'vitest';
+import { buildOfflineAssetEvidence } from '../evidence/offline-evidence.js';
+
+const guid = '11111111-1111-4111-8111-111111111111';
+
+describe('offline evidence adapter', () => {
+  it('joins source inventory, catalog, receipt, and package verification', async () => {
+    const result = await buildOfflineAssetEvidence({
+      guid,
+      source: { origin: 'sourceMeta', inputFingerprint: 'fp-1' },
+      locator: { packageUrl: '/assets/config.pack.json', cookReceiptUrl: '/receipts/config.json' },
+      receipt: {
+        guid,
+        origin: 'sourceMeta',
+        status: 'succeeded',
+        inputFingerprint: 'fp-1',
+        outputDigest: 'digest-1',
+      },
+      package: {
+        guid,
+        digest: 'digest-1',
+        artifacts: {
+          data: {
+            path: 'artifacts/data.bin',
+            mediaType: 'application/octet-stream',
+          },
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.packageUrl).toBe('/assets/config.pack.json');
+    expect(result.value.cook.freshness).toBe('current');
+    expect(result.value.package?.status).toBe('passed');
+  });
+
+  it('keeps runtime and WS outside the offline adapter boundary', () => {
+    expect(buildOfflineAssetEvidence.toString()).not.toContain('assets.load');
+    expect(buildOfflineAssetEvidence.toString()).not.toContain('WebSocket');
+    expect(buildOfflineAssetEvidence.toString()).not.toContain('AssetRegistry');
+  });
+
+  it('keeps the static Pack boundary gate live for runtime package imports', async () => {
+    const gate = await readFile(
+      new URL('../../../../packages/pack/scripts/check-no-assets-load.mjs', import.meta.url),
+      'utf8',
+    );
+
+    expect(gate).toContain('@forgeax/engine-(assets-runtime|runtime)');
+    expect(gate).toContain(String.raw`engine\\.assets\\.load(`);
+    expect(gate).not.toContain("registry.load('");
+  });
+
+  it('projects a verified cook product without requiring DDC storage', async () => {
+    const result = await buildOfflineAssetEvidence({
+      guid,
+      product: {
+        guid,
+        payload: { kind: 'direct-asset' },
+        refs: [],
+        artifacts: {
+          data: { path: 'assets/data.bin', mediaType: 'application/octet-stream' },
+        },
+        digest: 'digest-direct',
+        receipt: {
+          guid,
+          origin: 'authoredPack',
+          status: 'succeeded',
+          inputFingerprint: 'direct-input',
+          outputDigest: 'digest-direct',
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.cook.freshness).toBe('notApplicable');
+    expect(result.value.package?.status).toBe('passed');
+  });
+
+  it('keeps a failed artifact in the offline evidence boundary', async () => {
+    const result = await buildOfflineAssetEvidence({
+      guid,
+      source: { origin: 'sourceMeta', inputFingerprint: 'fp-failed' },
+      locator: { packageUrl: '/assets/failed.pack.json' },
+      package: {
+        guid,
+        digest: 'digest-failed',
+        artifacts: {
+          data: {
+            path: 'assets/data.bin',
+            mediaType: 'application/octet-stream',
+            verification: 'failed',
+          },
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.package?.status).toBe('failed');
+    expect(result.value.cook.freshness).toBe('unknown');
+  });
+});

package/src/__tests__/pack-v2-fixture-migration.test.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { parsePackV2 } from '../index.js';
+
+const root = resolve(import.meta.dirname, '../../../../');
+
+const fixtures = [
+  {
+    path: 'apps/hello/cube/assets/cube-mesh.pack.json',
+    assets: [{ guid: 'cbe42beb-8975-5096-b3a1-3dda4cb4c077', refs: [] }],
+  },
+  {
+    path: 'apps/hello/room/assets/room.pack.json',
+    assets: [
+      {
+        guid: '019e2808-d3ba-735f-811f-ae7bbb465392',
+        refs: [
+          'cbe42beb-8975-5096-b3a1-3dda4cb4c077',
+          'f6af7007-158f-4d92-9e47-93bf2f213e1f',
+          '008e4f75-e7a3-4715-b05b-b93a9ec12074',
+        ],
+      },
+    ],
+  },
+  {
+    path: 'apps/hello/scene-nesting/assets/outer-scene.pack.json',
+    assets: [
+      {
+        guid: 'd07a7b8e-9c12-4f6b-a8e1-3d4f5a6b7c8d',
+        refs: ['f47ac10b-58cc-4372-a567-0e02b2c3d479', '008e4f75-e7a3-4715-b05b-b93a9ec12074'],
+      },
+    ],
+  },
+];
+
+describe('Pack v2 fixture migration', () => {
+  it('preserves logical GUID and refs while requiring local artifact maps', () => {
+    for (const fixture of fixtures) {
+      const parsed = parsePackV2(JSON.parse(readFileSync(resolve(root, fixture.path), 'utf8')));
+      expect(parsed.ok, fixture.path).toBe(true);
+      if (!parsed.ok) continue;
+      expect(
+        parsed.value.assets.map(({ guid, refs, artifacts }) => ({ guid, refs, artifacts })),
+      ).toEqual(
+        fixture.assets.map((asset) => ({ guid: asset.guid, refs: asset.refs, artifacts: {} })),
+      );
+    }
+  });
+
+  it('rejects the empty legacy envelope and package-global payload arms', () => {
+    expect(
+      parsePackV2({ schemaVersion: '1.0.0', kind: 'internal-text-package', assets: [] }).ok,
+    ).toBe(false);
+    expect(
+      parsePackV2({
+        schemaVersion: '2.0.0',
+        kind: 'internal-text-package',
+        assets: [],
+        artifacts: [{ path: 'shared.bin', bytes: 'base64' }],
+      }).ok,
+    ).toBe(false);
+  });
+});

package/src/__tests__/pack-v2-schema.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+import { validatePack, validatePackV2 } from '../schema-compiled.js';
+import { SCRIPTABLE_PACK_ASSET_KINDS } from '../scriptable-pack.js';
+
+const GUID_A = '11111111-1111-4111-8111-111111111111';
+const GUID_B = '22222222-2222-4222-8222-222222222222';
+
+function validPack() {
+  return {
+    schemaVersion: '2.0.0',
+    kind: 'internal-text-package',
+    packageId: 'pkg/fixture',
+    assets: [
+      {
+        guid: GUID_A,
+        kind: 'texture',
+        execution: 'cooked',
+        payload: { kind: 'texture', width: 1, height: 1 },
+        refs: [GUID_B],
+        artifacts: {
+          image: {
+            path: 'artifacts/texture.bin',
+            mediaType: 'image/ktx2',
+            assetCodec: { name: 'basis', profile: 'uastc', version: '1' },
+            contentEncoding: 'zstd',
+            byteLength: 4,
+            integrity: {
+              algorithm: 'sha256',
+              digest: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=',
+            },
+          },
+        },
+      },
+      {
+        guid: GUID_B,
+        kind: 'material',
+        execution: 'cooked',
+        payload: { kind: 'material' },
+        refs: [],
+        artifacts: {},
+      },
+    ],
+  };
+}
+
+function mutablePack() {
+  return JSON.parse(JSON.stringify(validPack())) as {
+    schemaVersion: string;
+    kind: string;
+    assets: Array<Record<string, unknown>>;
+  };
+}
+
+describe('Pack v2 schema', () => {
+  it('accepts a v2 envelope with asset-local artifacts and separated encoding facts', () => {
+    const pack = validPack();
+
+    expect(validatePack(pack)).toBe(true);
+    expect(validatePackV2(pack)).toBe(true);
+  });
+
+  it('rejects a non-v2 schema version', () => {
+    const pack = { ...validPack(), schemaVersion: '1.0.0' };
+
+    expect(validatePackV2(pack)).toBe(false);
+  });
+
+  it('rejects an artifact descriptor without required content facts', () => {
+    const pack = mutablePack();
+    const asset = pack.assets[0];
+    if (!asset) throw new Error('fixture asset is missing');
+    const artifacts = asset.artifacts as Record<string, Record<string, unknown>>;
+    const image = artifacts.image;
+    if (!image) throw new Error('fixture artifact is missing');
+    delete image.mediaType;
+
+    expect(validatePackV2(pack)).toBe(false);
+  });
+
+  it('rejects integrity that is not a structured algorithm and digest object', () => {
+    const pack = mutablePack();
+    const asset = pack.assets[0];
+    if (!asset) throw new Error('fixture asset is missing');
+    const artifacts = asset.artifacts as Record<string, Record<string, unknown>>;
+    const image = artifacts.image;
+    if (!image) throw new Error('fixture artifact is missing');
+    image.integrity = 'sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=';
+
+    expect(validatePackV2(pack)).toBe(false);
+  });
+
+  it('rejects duplicate asset GUIDs and duplicate artifact keys', () => {
+    const duplicateGuidPack = mutablePack();
+    const secondAsset = duplicateGuidPack.assets[1];
+    if (!secondAsset) throw new Error('fixture asset is missing');
+    secondAsset.guid = GUID_A;
+
+    const duplicateArtifactKeyPack = mutablePack();
+    const firstAsset = duplicateArtifactKeyPack.assets[0];
+    if (!firstAsset) throw new Error('fixture asset is missing');
+    const imageArtifact = (firstAsset.artifacts as Record<string, unknown>).image as Record<
+      string,
+      unknown
+    >;
+    firstAsset.artifacts = [
+      { key: 'image', ...imageArtifact },
+      { key: 'image', ...imageArtifact },
+    ];
+
+    expect(validatePackV2(duplicateGuidPack)).toBe(false);
+    expect(validatePackV2(duplicateArtifactKeyPack)).toBe(false);
+  });
+
+  it('rejects missing descriptor fields instead of silently skipping the asset', () => {
+    const pack = mutablePack();
+    const asset = pack.assets[0];
+    if (!asset) throw new Error('fixture asset is missing');
+    delete asset.refs;
+
+    expect(validatePackV2(pack)).toBe(false);
+  });
+
+  it('rejects a v2 asset with no explicit execution mode', () => {
+    const pack = mutablePack();
+    const asset = pack.assets[0];
+    if (!asset) throw new Error('fixture asset is missing');
+    delete asset.execution;
+
+    expect(validatePackV2(pack)).toBe(false);
+  });
+
+  it('accepts every published durable kind without closing producer extensions', () => {
+    for (const kind of SCRIPTABLE_PACK_ASSET_KINDS) {
+      const pack = validPack();
+      const asset = pack.assets[0];
+      if (!asset) throw new Error('fixture asset is missing');
+      asset.kind = kind;
+      asset.payload = { kind };
+      expect(validatePackV2(pack), kind).toBe(true);
+    }
+  });
+});