@forgeax/engine-pack 0.0.0-dev.8d955ade1c79

package/schema/pack.schema.json

@@ -0,0 +1,232 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/ForgeaXGame/forgeax-engine/packages/pack/schema/pack.schema.json",
+  "title": "InternalTextPackage",
+  "description": "Schema for authored and cooked internal text packages.",
+  "$comment": "The ordinary durable consumer matrix is SCRIPTABLE_PACK_ASSET_KINDS in @forgeax/engine-pack/source. Pack kind fields remain open for registered producer extensions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "assets"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "enum": ["1.0.0", "2.0.0"]
+    },
+    "kind": {
+      "type": "string",
+      "const": "internal-text-package"
+    },
+    "packageId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable producer-owned package identity. It survives package moves; path is only a locator."
+    },
+    "provenance": {
+      "$ref": "#/$defs/provenance"
+    },
+    "revision": {
+      "$ref": "#/$defs/revision"
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/diagnostic" }
+    },
+    "assets": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/asset"
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "required": ["packageId"],
+        "properties": {
+          "packageId": {},
+          "schemaVersion": { "const": "2.0.0" }
+        }
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "assets": {
+            "type": "array",
+            "items": {
+              "allOf": [
+                { "$ref": "#/$defs/assetV2" },
+                {
+                  "type": "object",
+                  "properties": { "execution": {} },
+                  "required": ["execution"]
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "guid36": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "asset": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["guid", "kind", "payload", "refs"],
+      "properties": {
+        "guid": {
+          "$ref": "#/$defs/guid36",
+          "description": "Unique GUID for this asset entry."
+        },
+        "kind": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Asset kind identifier, e.g. 'MaterialAsset'."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional display name for this asset. Add-only field for backward compatibility with old pack files that lack it."
+        },
+        "sourceKey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Producer-owned stable key used to match imported output topology."
+        },
+        "sourceIndex": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Producer-declared output position; not an identity key when sourceKey is present."
+        },
+        "execution": {
+          "type": "string",
+          "enum": ["direct", "cooked"],
+          "description": "Explicit authoring execution mode; never inferred from package path."
+        },
+        "payload": {
+          "type": "object",
+          "description": "Serialized asset payload. Free-form object."
+        },
+        "refs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/guid36" }
+        },
+        "artifacts": { "$ref": "#/$defs/artifacts" }
+      }
+    },
+    "assetV2": {
+      "allOf": [
+        { "$ref": "#/$defs/asset" },
+        {
+          "type": "object",
+          "required": ["artifacts"],
+          "properties": {
+            "artifacts": { "$ref": "#/$defs/artifacts" }
+          }
+        }
+      ]
+    },
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[A-Za-z0-9][A-Za-z0-9._/-]*$": {
+          "$ref": "#/$defs/artifactDescriptor"
+        }
+      }
+    },
+    "artifactDescriptor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "mediaType"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "mediaType": { "type": "string", "minLength": 1 },
+        "assetCodec": { "$ref": "#/$defs/assetCodec" },
+        "contentEncoding": { "enum": ["identity", "zstd"] },
+        "byteLength": { "type": "integer", "minimum": 0 },
+        "integrity": { "$ref": "#/$defs/integrity" }
+      }
+    },
+    "assetCodec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "profile": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["algorithm", "digest"],
+      "properties": {
+        "algorithm": { "const": "sha256" },
+        "digest": { "type": "string", "minLength": 1 }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "version"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 }
+      }
+    },
+    "revision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["digest", "observedAt", "rootId"],
+      "properties": {
+        "digest": { "type": "string", "minLength": 1 },
+        "observedAt": { "type": "number" },
+        "rootId": { "type": "string", "minLength": 1 }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "severity": { "type": "string", "enum": ["info", "warning", "blocking"] },
+        "message": { "type": "string" },
+        "subject": { "$ref": "#/$defs/subject" },
+        "expected": { "type": "string", "minLength": 1 },
+        "actual": { "type": "string" },
+        "hint": { "type": "string", "minLength": 1 },
+        "authority": { "type": "string", "enum": ["producer", "pack", "catalog"] },
+        "evidence": { "type": "array", "items": { "type": "object" } },
+        "recoveryIntents": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "id"],
+      "properties": {
+        "type": { "type": "string", "enum": ["asset", "package", "resource"] },
+        "id": { "type": "string", "minLength": 1 }
+      }
+    },
+    "relation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "to", "type", "provenance"],
+      "properties": {
+        "from": { "$ref": "#/$defs/subject" },
+        "to": { "$ref": "#/$defs/subject" },
+        "type": { "type": "string", "minLength": 1 },
+        "policy": { "type": "object" },
+        "provenance": { "$ref": "#/$defs/provenance" }
+      }
+    }
+  }
+}

package/src/__tests__/ai-recovery.unit.test.ts

@@ -0,0 +1,114 @@
+import { readFileSync } from 'node:fs';
+import type {
+  CatalogEntry,
+  ImportedOutputDeclaration,
+  ProducerContractDiagnostic,
+} from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { validateProducerOutputs } from '../producer-contract.js';
+
+const DUPLICATE_GUID = '019e2cc6-0c86-79da-aa76-b0984c86d411';
+const OTHER_GUID = '019e2cc6-0c86-79da-aa76-b0984c86d412';
+
+interface RecoverySignal {
+  readonly authority: 'authoritative' | 'degraded';
+  readonly diagnostic?: {
+    readonly code: string;
+    readonly hint?: string;
+    readonly subject?: { readonly id?: string };
+  };
+}
+
+interface RecoveryDecision {
+  readonly action: 'repair-input' | 'rollback-verified-revision' | 'reject-update';
+  readonly code: string;
+  readonly hint: string;
+}
+
+function decideRecovery(result: RecoverySignal): RecoveryDecision {
+  const diagnostic = result.diagnostic;
+  if (diagnostic === undefined || diagnostic.hint === undefined) {
+    return { action: 'reject-update', code: 'unknown', hint: 'keep the last verified result' };
+  }
+  if (result.authority === 'degraded' && diagnostic.code === 'catalog-revision-stale') {
+    return {
+      action: 'rollback-verified-revision',
+      code: diagnostic.code,
+      hint: diagnostic.hint,
+    };
+  }
+  if (diagnostic.code === 'duplicate-source-key') {
+    return { action: 'repair-input', code: diagnostic.code, hint: diagnostic.hint };
+  }
+  return { action: 'reject-update', code: diagnostic.code, hint: diagnostic.hint };
+}
+
+function repairDuplicateKey(
+  entries: readonly CatalogEntry[],
+  diagnostic: ProducerContractDiagnostic,
+): readonly CatalogEntry[] {
+  return entries.map((entry) =>
+    entry.guid === diagnostic.subject?.id
+      ? { ...entry, sourceKey: `${entry.sourceKey ?? 'output'}/repaired` }
+      : entry,
+  );
+}
+
+describe('AI recovery from canonical catalog fields', () => {
+  it('keeps every non-current lifecycle on a safe recovery path', () => {
+    const schema = JSON.parse(
+      readFileSync(new URL('../../../../asset-authority.schema.json', import.meta.url), 'utf8'),
+    ) as {
+      'x-forgeax-audit': {
+        aiOperations: string[];
+        recoveryByLifecycle: Record<string, string[]>;
+      };
+    };
+    const { aiOperations, recoveryByLifecycle } = schema['x-forgeax-audit'];
+    for (const lifecycle of ['missing', 'cooking', 'current', 'stale', 'failed']) {
+      const actions = recoveryByLifecycle[lifecycle];
+      expect(actions?.every((action) => aiOperations.includes(action))).toBe(true);
+      if (lifecycle !== 'current') expect(actions?.length).toBeGreaterThan(0);
+    }
+    expect(aiOperations).toEqual(
+      expect.arrayContaining(['inspect', 'rebuild', 'cold-cook', 'preview-LKG', 'stop-publish']),
+    );
+  });
+
+  it('consumes the producer validator result and repairs a duplicate key', () => {
+    const outputs: ImportedOutputDeclaration[] = [
+      { guid: DUPLICATE_GUID, kind: 'nebula/fragment', sourceKey: 'fragment/main', sourceIndex: 0 },
+      { guid: OTHER_GUID, kind: 'nebula/fragment', sourceKey: 'fragment/main', sourceIndex: 1 },
+    ];
+    const contract = validateProducerOutputs(outputs);
+    expect(contract.ok).toBe(false);
+    if (contract.ok) return;
+
+    const decision = decideRecovery({ authority: 'degraded', diagnostic: contract.error });
+    expect(decision).toMatchObject({ action: 'repair-input', code: contract.error.code });
+    const entries: CatalogEntry[] = outputs.map((output) => ({
+      guid: output.guid,
+      packageUrl: '/duplicate/main.pack.json',
+      sourcePath: 'duplicate.pack.json',
+      kind: output.kind,
+      packageId: 'pkg/ai-recovery',
+      ...(output.sourceKey === undefined ? {} : { sourceKey: output.sourceKey }),
+      sourceIndex: output.sourceIndex,
+    }));
+    const repairedEntries = repairDuplicateKey(entries, contract.error);
+    expect(new Set(repairedEntries.map((entry) => entry.sourceKey)).size).toBe(2);
+    expect(decision.hint).toBe(contract.error.hint);
+    const repaired = repairedEntries.map((entry) => {
+      if (entry.sourceKey === undefined || entry.sourceIndex === undefined) {
+        throw new Error(`repaired catalog row ${entry.guid} lost output topology`);
+      }
+      return {
+        guid: entry.guid,
+        kind: entry.kind,
+        sourceKey: entry.sourceKey,
+        sourceIndex: entry.sourceIndex,
+      };
+    });
+    expect(validateProducerOutputs(repaired)).toMatchObject({ ok: true });
+  });
+});

package/src/__tests__/artifact-path.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest';
+import { validateArtifactPath } from '../artifact-path.js';
+
+const context = {
+  packageRoot: '/packages/hero',
+  guid: '11111111-1111-4111-8111-111111111111',
+  artifactKey: 'mesh',
+};
+
+describe('artifact locator validation', () => {
+  it('accepts a normalized package-relative locator', () => {
+    const result = validateArtifactPath('artifacts/hero.bin', context);
+
+    expect(result).toEqual({ ok: true, value: 'artifacts/hero.bin' });
+  });
+
+  it.each([
+    ['parent traversal', '../outside.bin'],
+    ['encoded traversal', '%2e%2e%2foutside.bin'],
+    ['double encoded traversal', '%252e%252e%252foutside.bin'],
+    ['backslash traversal', '..\\outside.bin'],
+    ['absolute POSIX path', '/tmp/outside.bin'],
+    ['absolute Windows path', 'C:\\tmp\\outside.bin'],
+    ['remote URL', 'https://example.test/outside.bin'],
+  ])('rejects %s before any file read', (_label, locator) => {
+    const readFile = vi.fn((_path: string) => new Uint8Array());
+    const result = validateArtifactPath(locator, context);
+
+    if (result.ok) {
+      readFile(result.value);
+    }
+
+    expect(result.ok).toBe(false);
+    expect(readFile).not.toHaveBeenCalled();
+    if (!result.ok) {
+      expect(result.error.code).toBe('asset-artifact-path-invalid');
+      expect(result.error.detail.guid).toBe(context.guid);
+      expect(result.error.detail.artifactKey).toBe(context.artifactKey);
+    }
+  });
+});

package/src/__tests__/asset-evidence-error-hints.test.ts

@@ -0,0 +1,46 @@
+import { ASSET_EVIDENCE_ERROR_HINTS, projectAssetEvidence } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+const guid = '11111111-1111-4111-8111-111111111111';
+
+describe('AssetEvidence structured recovery hints', () => {
+  it('provides non-empty hints for every closed evidence error code', () => {
+    const codes = [
+      'asset-evidence-capability-missing',
+      'asset-evidence-source-conflict',
+      'asset-evidence-locator-conflict',
+      'asset-evidence-receipt-conflict',
+      'asset-evidence-digest-mismatch',
+    ] as const;
+
+    for (const code of codes) {
+      expect(ASSET_EVIDENCE_ERROR_HINTS[code]).toBeTruthy();
+      expect(ASSET_EVIDENCE_ERROR_HINTS[code]).not.toContain('message');
+      expect(ASSET_EVIDENCE_ERROR_HINTS[code]).toMatch(
+        /inspect|repair|retry|refresh|capability|rerun|source|rebuild|verify|catalog|package/,
+      );
+    }
+  });
+
+  it('keeps mismatch errors distinct from unknown capability', () => {
+    const result = projectAssetEvidence({
+      guid,
+      source: { origin: 'sourceMeta', inputFingerprint: 'fp-1' },
+      locator: { packageUrl: '/assets/data.pack.json' },
+      receipt: {
+        guid,
+        origin: 'sourceMeta',
+        status: 'succeeded',
+        inputFingerprint: 'fp-1',
+        outputDigest: 'receipt-digest',
+      },
+      packageVerification: { status: 'passed', digest: 'package-digest' },
+      artifacts: {},
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('asset-evidence-digest-mismatch');
+    expect(result.error.detail).toMatchObject({ guid });
+  });
+});

package/src/__tests__/asset-evidence-lifecycle.test.ts

@@ -0,0 +1,104 @@
+import { projectAssetEvidence } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+const guid = '11111111-1111-4111-8111-111111111111';
+const receipt = {
+  guid,
+  origin: 'sourceMeta' as const,
+  status: 'succeeded' as const,
+  inputFingerprint: 'fp-1',
+  outputDigest: 'digest-1',
+};
+const descriptor = {
+  path: 'artifacts/data.bin',
+  mediaType: 'application/octet-stream',
+};
+
+function input(overrides: Record<string, unknown> = {}) {
+  return {
+    guid,
+    source: { origin: 'sourceMeta' as const, inputFingerprint: 'fp-1' },
+    locator: { packageUrl: '/assets/data.pack.json' },
+    artifacts: { data: descriptor },
+    runtime: { status: 'unknown' as const },
+    ...overrides,
+  };
+}
+
+describe('AssetEvidence lifecycle', () => {
+  it('distinguishes authored, uncooked, failed, current, stale, and shipped states', () => {
+    const authored = projectAssetEvidence(
+      input({
+        source: { origin: 'authoredPack' },
+        receipt: { ...receipt, origin: 'authoredPack' },
+      }),
+    );
+    const uncooked = projectAssetEvidence(input());
+    const failed = projectAssetEvidence(
+      input({
+        receipt: {
+          ...receipt,
+          status: 'failed',
+          error: {
+            code: 'import-failed',
+            expected: 'source imports',
+            hint: 'fix source and recook',
+          },
+        },
+      }),
+    );
+    const current = projectAssetEvidence(input({ receipt }));
+    const stale = projectAssetEvidence(
+      input({
+        source: { origin: 'sourceMeta', inputFingerprint: 'fp-2' },
+        receipt,
+      }),
+    );
+    const shipped = projectAssetEvidence(input({ source: undefined, receipt }));
+
+    expect(authored.ok && authored.value.cook.status).toBe('notRequired');
+    expect(uncooked.ok && uncooked.value.cook.status).toBe('notCooked');
+    expect(failed.ok && failed.value.cook.status).toBe('failed');
+    expect(current.ok && current.value.cook.freshness).toBe('current');
+    expect(stale.ok && stale.value.cook.freshness).toBe('stale');
+    expect(shipped.ok && shipped.value.cook.freshness).toBe('unknown');
+  });
+
+  it('returns a structured conflict instead of masking contradictory evidence', () => {
+    const conflict = projectAssetEvidence(
+      input({
+        locators: [{ packageUrl: '/assets/a.pack.json' }, { packageUrl: '/assets/b.pack.json' }],
+      }),
+    );
+
+    expect(conflict.ok).toBe(false);
+    if (conflict.ok) return;
+    expect(conflict.error.code).toBe('asset-evidence-locator-conflict');
+    expect(conflict.error.expected).toContain('one package locator');
+    expect(conflict.error.hint).toBeTruthy();
+    expect(conflict.error.detail).toMatchObject({ guid });
+  });
+
+  it('does not treat a failed recook as current evidence', () => {
+    const failed = projectAssetEvidence(
+      input({
+        source: { origin: 'sourceMeta', inputFingerprint: 'fp-2' },
+        receipt: {
+          ...receipt,
+          inputFingerprint: 'fp-1',
+          status: 'failed',
+          error: {
+            code: 'producer-failed',
+            expected: 'a validated output',
+            hint: 'repair the source and recook',
+          },
+        },
+      }),
+    );
+
+    expect(failed.ok).toBe(true);
+    if (!failed.ok) return;
+    expect(failed.value.cook.status).toBe('failed');
+    expect(failed.value.cook.freshness).not.toBe('current');
+  });
+});

package/src/__tests__/asset-evidence-schema.test.ts

@@ -0,0 +1,86 @@
+import { projectAssetEvidence } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { parsePackV2 } from '../index.js';
+
+const guid = '11111111-1111-4111-8111-111111111111';
+
+describe('AssetEvidence pack projection schema', () => {
+  it('retains a package locator and asset-local artifact facts separately', () => {
+    const pack = parsePackV2({
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      assets: [
+        {
+          guid,
+          kind: 'host-config',
+          payload: { value: 1 },
+          refs: [],
+          artifacts: {
+            source: {
+              path: 'artifacts/source.json',
+              mediaType: 'application/json',
+              assetCodec: { name: 'json' },
+            },
+          },
+        },
+      ],
+    });
+
+    expect(pack.ok).toBe(true);
+    if (!pack.ok) return;
+    const asset = pack.value.assets[0];
+    expect(asset).toBeDefined();
+    if (asset === undefined) return;
+    const evidence = projectAssetEvidence({
+      guid,
+      source: { origin: 'sourceMeta', sourcePath: 'assets/config.json', inputFingerprint: 'fp-1' },
+      locator: { packageUrl: '/assets/config.pack.json' },
+      receipt: {
+        guid,
+        origin: 'sourceMeta',
+        status: 'succeeded',
+        inputFingerprint: 'fp-1',
+        outputDigest: 'digest-1',
+      },
+      packageVerification: { status: 'passed', digest: 'digest-1' },
+      artifacts: asset.artifacts,
+      runtime: { status: 'unknown' },
+    });
+
+    expect(evidence.ok).toBe(true);
+    if (!evidence.ok) return;
+    expect(evidence.value.packageUrl).toBe('/assets/config.pack.json');
+    const sourceArtifact = evidence.value.artifacts.source;
+    expect(sourceArtifact).toBeDefined();
+    if (sourceArtifact === undefined) return;
+    expect(sourceArtifact.verification).toBe('notChecked');
+  });
+
+  it('rejects evidence projection when receipt GUID or digest is not the product GUID', async () => {
+    const { projectCookProductEvidence } = await import('@forgeax/engine-types');
+    const result = projectCookProductEvidence({
+      guid,
+      payload: { kind: 'host-config', value: 1 },
+      refs: [],
+      artifacts: {
+        source: {
+          path: 'artifacts/source.json',
+          mediaType: 'application/json',
+        },
+      },
+      digest: 'digest-1',
+      receipt: {
+        guid: '22222222-2222-4222-8222-222222222222',
+        origin: 'sourceMeta',
+        status: 'succeeded',
+        inputFingerprint: 'fp-1',
+        outputDigest: 'digest-2',
+      },
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: { code: 'asset-evidence-receipt-conflict' },
+    });
+  });
+});