@forgeax/engine-pack 0.1.2

package/src/schema/material-cook.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ForgeaX cooked material record",
+  "type": "object",
+  "required": ["schemaVersion", "guid", "resolved", "refs", "artifact", "receipt"],
+  "properties": {
+    "schemaVersion": { "const": "material-cook/2" },
+    "guid": { "type": "string", "minLength": 1 },
+    "materialGuid": { "type": "string", "minLength": 1 },
+    "publicationGeneration": { "type": "integer", "minimum": 1 },
+    "specializationKey": { "type": "string", "minLength": 1 },
+    "artifactDigest": { "type": "string", "pattern": "^sha256:" },
+    "sourceClosure": { "type": "array", "items": { "type": "string" } },
+    "parameterContract": {
+      "type": "object",
+      "required": ["parameters", "values"],
+      "properties": {
+        "parameters": { "type": "array" },
+        "values": { "type": "object" }
+      },
+      "additionalProperties": false
+    },
+    "authored": { "type": "object", "required": ["kind"] },
+    "resolved": { "type": "object", "required": ["passes", "parameters", "values"] },
+    "refs": {
+      "type": "object",
+      "required": ["parent", "textures", "samplers", "modules"],
+      "properties": {
+        "parent": { "type": "array", "items": { "type": "string" } },
+        "textures": { "type": "array", "items": { "type": "string" } },
+        "samplers": { "type": "array", "items": { "type": "string" } },
+        "modules": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "artifact": {
+      "type": "object",
+      "required": ["mediaType", "path", "digest", "bytes"],
+      "properties": {
+        "mediaType": { "type": "string" },
+        "path": { "type": "string" },
+        "digest": { "type": "string", "pattern": "^sha256:" },
+        "bytes": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 255 } }
+      },
+      "additionalProperties": false
+    },
+    "receipt": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "sourceClosure",
+        "profile",
+        "compilerVersion",
+        "inputDigest",
+        "outputDigest",
+        "layoutIdentity",
+        "derivedInterface"
+      ],
+      "properties": {
+        "schemaVersion": { "const": "material-cook/2" },
+        "sourceClosure": { "type": "array", "items": { "type": "string" } },
+        "profile": { "type": "string" },
+        "compilerVersion": { "type": "string" },
+        "inputDigest": { "type": "string" },
+        "outputDigest": { "type": "string" },
+        "layoutIdentity": { "type": "string", "minLength": 1 },
+        "derivedInterface": {
+          "type": "object",
+          "required": ["layoutIdentity"],
+          "properties": { "layoutIdentity": { "type": "string", "minLength": 1 } },
+          "additionalProperties": false
+        },
+        "publicationGeneration": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/src/schema-compiled.ts

@@ -0,0 +1,238 @@
+import type { PackV2 } from '@forgeax/engine-types';
+import Ajv, { type ValidateFunction } from 'ajv';
+import addFormats from 'ajv-formats';
+import metaSchemaJson from '../schema/meta.schema.json' with { type: 'json' };
+import packSchemaJson from '../schema/pack.schema.json' with { type: 'json' };
+
+const ajv = new Ajv({ strict: true, allErrors: false });
+addFormats(ajv, ['uuid']);
+
+// Module-top-level compiled validators - compiled once on import, never recreated.
+export const validateMeta = ajv.compile(metaSchemaJson);
+export const validatePack = ajv.compile(packSchemaJson);
+
+export function validatePackV2(value: unknown): value is PackV2 {
+  if (!validatePack(value) || !isPackV2Shape(value)) return false;
+
+  const seenGuids = new Set<string>();
+  for (const asset of value.assets) {
+    if (seenGuids.has(asset.guid)) return false;
+    seenGuids.add(asset.guid);
+  }
+  return true;
+}
+
+function isPackV2Shape(value: unknown): value is PackV2 {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'schemaVersion' in value &&
+    value.schemaVersion === '2.0.0'
+  );
+}
+
+// === SceneAsset payload validator factory (feat-20260514 w5 / D-P4) =============
+//
+// Decision anchors:
+//   - plan-strategy §D-P4 (per-component additionalProperties:false, path a;
+//     path b "extend PackErrorDetail" rejected to keep the 8-member
+//     PackErrorCode closed union frozen)
+//   - requirements §AC-08(b) (typo field name fail-fast through ajv with the
+//     verbatim 'additional properties' message wording)
+//   - requirements §AC-10 (no new SceneErrorCode / PackErrorCode introduced)
+//
+// `buildSceneAssetValidator(componentSchemas)` returns a fresh ajv
+// `ValidateFunction` whose JSON Schema sub-tree describes:
+//   {
+//     kind: 'scene',
+//     nodes: SceneEntity[]
+//   }
+// where each SceneEntity has the closed shape
+//   { localId: integer, components: <closed map keyed by registered tokens> }
+// and the per-component sub-schema is composed verbatim from the caller's
+// `componentSchemas[name]` entry. `additionalProperties: false` is applied
+// at three layers: top-level SceneAsset, SceneEntity, and SceneEntity.components,
+// so ajv emits an `additional properties` ajvError on any typo or unknown
+// component token (AC-08(b)).
+//
+// The runtime layer feeds `componentSchemas` from the live `defineComponent`
+// registry; this factory itself stays ECS-free (charter proposition 5
+// consistent abstraction: pack package is layered below ecs and runtime,
+// the per-component schemas arrive as plain ajv-compatible JSON Schema
+// objects).
+export function buildSceneAssetValidator(
+  componentSchemas: Readonly<Record<string, object>>,
+): ValidateFunction {
+  // Use a separate ajv instance so the dynamically registered closed map of
+  // component sub-schemas does not pollute the module-top-level validators
+  // above (they may be re-built across test fixtures with different
+  // component sets).
+  const localAjv = new Ajv({ strict: true, allErrors: false });
+  addFormats(localAjv, ['uuid']);
+
+  const componentsProperties: Record<string, object> = {};
+  for (const [name, sub] of Object.entries(componentSchemas)) {
+    componentsProperties[name] = sub;
+  }
+
+  // MountOverride schema (feat-20260608-scene-nesting-ecs-fication M1 / w11;
+  // feat-20260713-mount-override-component-add-and-shared-ref-round M1 / w3;
+  // requirements §S-10 / AC-03): validates each entry in mounts[].overrides[].
+  // `field` is optional — it is a component-granular add-or-patch discriminant
+  // (present -> patch one field with `value`; absent -> add/upsert the whole
+  // `comp` with `value` as its per-field map). `localId` / `comp` / `value`
+  // stay required; `additionalProperties: false` rejects any `op`-tag
+  // discriminant so downstream consumers never branch on it. Field-level type
+  // validation (matching the schema vocab) is enforced at runtime via
+  // setSceneOverride (D-9 / EcsErrorCode 'scene-override-type-mismatch').
+  const mountOverrideSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['localId', 'comp', 'value'],
+    properties: {
+      localId: { type: 'integer', minimum: 0 },
+      comp: { type: 'string', minLength: 1 },
+      field: { type: 'string', minLength: 1 },
+      value: {},
+    },
+  };
+
+  // SceneInstanceMount schema (feat-20260608-scene-nesting-ecs-fication
+  // M1 / w11; requirements §S-10): validates each mounts[] entry. parent /
+  // components / overrides are optional; cross-mount window collision and
+  // mount.source / mount.memberCount agreement with referenced child
+  // SceneAsset are checked at the build-time scanner (D-1, w14), not here.
+  const mountSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['localId', 'source', 'memberFirst', 'memberCount'],
+    properties: {
+      localId: { type: 'integer', minimum: 0 },
+      source: { type: 'integer', minimum: 0 },
+      memberFirst: { type: 'integer', minimum: 0 },
+      memberCount: { type: 'integer', minimum: 0 },
+      parent: { type: 'integer', minimum: 0 },
+      components: {
+        type: 'object',
+        additionalProperties: false,
+        properties: componentsProperties,
+      },
+      overrides: {
+        type: 'array',
+        items: mountOverrideSchema,
+      },
+      publicationFence: {
+        type: 'object',
+        additionalProperties: false,
+        required: [
+          'schemaVersion',
+          'sourcePath',
+          'sourceRevision',
+          'publicationGeneration',
+          'outputDigest',
+          'outputSetDigest',
+          'receiptIdentity',
+        ],
+        properties: {
+          schemaVersion: { type: 'string', const: 'scene-publication-fence/1' },
+          sourcePath: { type: 'string', minLength: 1 },
+          sourceRevision: { type: 'string', minLength: 1 },
+          publicationGeneration: { type: 'integer', minimum: 1 },
+          outputDigest: { type: 'string', minLength: 1 },
+          outputSetDigest: { type: 'string', minLength: 1 },
+          receiptIdentity: { type: 'string', minLength: 1 },
+        },
+      },
+    },
+  };
+
+  const sceneSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['kind', 'entities'],
+    properties: {
+      kind: { type: 'string', const: 'scene' },
+      entities: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['localId', 'components'],
+          properties: {
+            localId: { type: 'integer', minimum: 0 },
+            components: {
+              type: 'object',
+              additionalProperties: false,
+              properties: componentsProperties,
+            },
+          },
+        },
+      },
+      // Optional top-level mounts[] (feat-20260608-scene-nesting-ecs-fication
+      // M1 / w11). Missing mounts is semantically equivalent to mounts: []
+      // (plan-strategy §6.3 back-compat); ajv default produces the empty
+      // array on absent input.
+      mounts: {
+        type: 'array',
+        items: mountSchema,
+      },
+    },
+  };
+
+  return localAjv.compile(sceneSchema);
+}
+
+// === MaterialAsset payload validator factory (feat-20260523-shader-template-instance-split M1-T06) ===
+//
+// Decision anchors:
+//   - plan-strategy D-PackKind (factory pattern, same shape as buildSceneAssetValidator)
+//   - plan-strategy D-ParamTypeWhitelist (paramTypeWhitelist consumed here)
+//   - requirements AC-04 (v1 type set SSOT; validator covers all param type boundaries)
+//
+// `buildMaterialAssetValidator(paramTypeWhitelist)` returns an ajv
+// `ValidateFunction` that validates:
+//   {
+//     materialShader: string,
+//     paramSchema: ParamSchemaEntry[],
+//     values: object
+//   }
+// Each ParamSchemaEntry.type must be in the whitelist (D-ParamTypeWhitelist).
+// `additionalProperties: false` at top level so ajv rejects unknown fields.
+// values is free-form (object) — the runtime layer does deeper validation.
+//
+// Uses a separate ajv instance per call so different whitelists across
+// test fixtures do not pollute the module-top-level validators.
+export function buildMaterialAssetValidator(
+  paramTypeWhitelist: ReadonlySet<string>,
+): ValidateFunction {
+  const localAjv = new Ajv({ strict: true, allErrors: false });
+
+  const whitelistEnum = Array.from(paramTypeWhitelist);
+
+  const paramSchemaEntry = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['name', 'type'],
+    properties: {
+      name: { type: 'string', minLength: 1 },
+      type: { type: 'string', enum: whitelistEnum },
+      default: {},
+    },
+  };
+
+  const materialSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['materialShader', 'paramSchema', 'values'],
+    properties: {
+      materialShader: { type: 'string', minLength: 1 },
+      paramSchema: {
+        type: 'array',
+        items: paramSchemaEntry,
+      },
+      values: { type: 'object' },
+    },
+  };
+
+  return localAjv.compile(materialSchema);
+}