build(runtime-loader): add strict packaged runtime asset loader

ToolboxAid · ToolboxAid · commit cbd4e229e575 · 2026-04-04T14:44:37.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,29 +2,28 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Execute this atomic Level 12 package in order.
+Execute this atomic Level 13 package in order.
 
 Step 1:
-Treat docs/pr/PLAN_PR_PROJECT_PACKAGING_SYSTEM.md as the governing architecture contract.
+Treat docs/pr/PLAN_PR_RUNTIME_ASSET_LOADER.md as the governing architecture contract.
 
 Step 2:
-Create BUILD_PR_PROJECT_PACKAGING_SYSTEM.
+Create BUILD_PR_RUNTIME_ASSET_LOADER.
 
 BUILD requirements:
-- Implement a strict project packaging and export system
-- Generate deterministic package manifests and dependency-resolved asset inclusion plans
-- Enforce strict validation gating before guarded packaging/export
-- Use registry as source of truth for asset identity
-- Use dependency graph for dependency traversal
-- Produce readable, stable packaging reports
-- Support Sprite Editor, Tile Map Editor, and Parallax Editor packaging participation as needed
+- Implement a strict runtime asset loader for packaged project output
+- Consume package manifest as runtime entry authority
+- Enforce deterministic load sequencing
+- Produce stable loader status/reporting
+- Fail fast on invalid packaged input or missing required packaged assets
+- Provide runtime bootstrap handoff for packaged projects
 - Do not modify engine core APIs
 
 Step 3:
-Validate BUILD against docs/pr/BUILD_PR_PROJECT_PACKAGING_SYSTEM.md.
+Validate BUILD against docs/pr/BUILD_PR_RUNTIME_ASSET_LOADER.md.
 
 Step 4:
-Treat docs/pr/APPLY_PR_PROJECT_PACKAGING_SYSTEM.md as the acceptance boundary and package results.
+Treat docs/pr/APPLY_PR_RUNTIME_ASSET_LOADER.md as the acceptance boundary and package results.
 
 Package:
-HTML-JavaScript-Gaming/tmp/LEVEL_12_PROJECT_PACKAGING_SYSTEM_STRICT_ATOMIC_PACKAGE_delta.zip
+HTML-JavaScript-Gaming/tmp/LEVEL_13_RUNTIME_ASSET_LOADER_STRICT_ATOMIC_PACKAGE_delta.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-build(packaging): add strict project packaging and export system
+build(runtime-loader): add strict packaged runtime asset loader
diff --git a/docs/dev/change_summary.txt b/docs/dev/change_summary.txt
@@ -1,3 +1,3 @@
-Single atomic Level 12 package containing PLAN, BUILD, and APPLY documentation for a strict
-project packaging and export system. This bundle is docs-first and Codex-ready, with implementation
+Single atomic Level 13 package containing PLAN, BUILD, and APPLY documentation for a strict
+packaged runtime asset loader. This bundle is docs-first and Codex-ready, with implementation
 ownership delegated to Codex.
diff --git a/docs/dev/file_tree.txt b/docs/dev/file_tree.txt
@@ -1,6 +1,6 @@
-docs/pr/PLAN_PR_PROJECT_PACKAGING_SYSTEM.md
-docs/pr/BUILD_PR_PROJECT_PACKAGING_SYSTEM.md
-docs/pr/APPLY_PR_PROJECT_PACKAGING_SYSTEM.md
+docs/pr/PLAN_PR_RUNTIME_ASSET_LOADER.md
+docs/pr/BUILD_PR_RUNTIME_ASSET_LOADER.md
+docs/pr/APPLY_PR_RUNTIME_ASSET_LOADER.md
 docs/dev/codex_commands.md
 docs/dev/commit_comment.txt
 docs/dev/change_summary.txt
diff --git a/docs/dev/reports/runtime_asset_loader_validation.txt b/docs/dev/reports/runtime_asset_loader_validation.txt
@@ -0,0 +1,19 @@
+BUILD_PR_RUNTIME_ASSET_LOADER validation
+
+Files:
+- tools/shared/runtimeAssetLoader.js
+- tests/tools/RuntimeAssetLoader.test.mjs
+- tests/run-tests.mjs
+
+Checks passed:
+- node --check tools/shared/runtimeAssetLoader.js
+- node --check tests/tools/RuntimeAssetLoader.test.mjs
+- node ./scripts/run-node-tests.mjs
+
+Behavior confirmed:
+- package manifest is the runtime authority for packaged asset enumeration
+- deterministic packaged asset order drives repeatable runtime load sequencing
+- invalid packaged manifests fail before runtime readiness
+- missing required packaged assets fail fast with stable reporting
+- successful loads produce bootstrap handoff data for packaged projects
+- no engine core API changes
diff --git a/docs/dev/validation_checklist.txt b/docs/dev/validation_checklist.txt
@@ -1,8 +1,7 @@
 - PLAN, BUILD, and APPLY docs are all present
 - codex_commands.md and commit_comment.txt are under docs/dev
-- Strict validation gating is explicit for packaging/export
-- Registry remains source of truth
-- Dependency graph remains traversal source
-- Output determinism is required
+- Strict packaged runtime contracts are explicit
+- Packaged manifest is runtime entry authority
+- Fail-fast behavior is explicit for invalid packaged input
 - No engine core API changes are authorized
 - APPLY remains docs-only acceptance boundary
diff --git a/docs/pr/APPLY_PR_RUNTIME_ASSET_LOADER.md b/docs/pr/APPLY_PR_RUNTIME_ASSET_LOADER.md
@@ -0,0 +1,33 @@
+# APPLY_PR_RUNTIME_ASSET_LOADER
+
+## Purpose
+Apply the completed strict runtime asset loader system as a docs-only acceptance boundary.
+
+## Apply Scope
+- Confirm PLAN and BUILD are complete
+- Confirm strict runtime loader behavior remains within approved scope
+- Confirm APPLY introduces no implementation expansion
+- Lock strict runtime asset loading as accepted project architecture baseline
+
+## Verification Summary
+- BUILD artifact exists and matches scoped runtime loader implementation
+- APPLY remains docs-only
+- Runtime loader consumes strict packaged output only
+- Fail-fast behavior remains limited to invalid packaged runtime input
+- No engine core API changes are required by APPLY
+
+## Accepted Baseline
+- Project owns a strict packaged runtime loader
+- Valid packages can load deterministically to ready state
+- Invalid packages fail fast with readable reports
+- Runtime bootstrap can rely on packaged manifest authority
+
+## Manual Validation Checklist
+1. Confirm BUILD artifact exists in repo tmp path.
+2. Confirm APPLY bundle only contains docs/pr and docs/dev files.
+3. Confirm accepted scope does not exceed BUILD scope.
+4. Confirm no new implementation files are introduced by APPLY.
+5. Confirm next planning work can build on strict runtime baseline.
+
+## Approved Commit Comment
+build(runtime-loader): add strict packaged runtime asset loader
diff --git a/docs/pr/BUILD_PR_RUNTIME_ASSET_LOADER.md b/docs/pr/BUILD_PR_RUNTIME_ASSET_LOADER.md
@@ -0,0 +1,48 @@
+# BUILD_PR_RUNTIME_ASSET_LOADER
+
+## Goal
+Implement the strict runtime asset loader defined in `PLAN_PR_RUNTIME_ASSET_LOADER` without changing engine core APIs.
+
+## Implemented Scope
+- Added shared strict packaged runtime loader in `tools/shared/runtimeAssetLoader.js`
+  - validates the packaged manifest contract before runtime load begins
+  - treats the package manifest as the runtime authority for asset enumeration
+  - executes deterministic sequential loading using packaged asset order
+  - returns stable `idle/loading/ready/failed` runtime loader state
+  - fails fast on invalid manifests, missing packaged assets, or loader failures
+  - produces runtime bootstrap handoff data for packaged project startup
+- Added automated coverage in `tests/tools/RuntimeAssetLoader.test.mjs`
+  - valid packaged runtime load reaches ready state
+  - repeated loads preserve deterministic order
+  - missing packaged asset fails fast with stable reporting
+  - invalid packaged manifest fails before runtime readiness
+- Registered the new runtime loader coverage in `tests/run-tests.mjs`
+
+## Manual Validation Checklist
+1. Valid packaged project loads successfully. `PASS`
+2. Repeated loads of unchanged package produce stable load order. `PASS`
+3. Missing required packaged asset fails fast. `PASS`
+4. Invalid manifest/package contract fails fast. `PASS`
+5. Ready state only occurs after all required startup dependencies resolve. `PASS`
+6. Loader reports clearly identify failure boundaries. `PASS`
+7. Engine core APIs remain unchanged. `PASS`
+
+## Validation Summary
+- Syntax checks passed:
+  - `node --check tools/shared/runtimeAssetLoader.js`
+  - `node --check tests/tools/RuntimeAssetLoader.test.mjs`
+- Full Node test suite passed:
+  - `node ./scripts/run-node-tests.mjs`
+
+## Scope Guard
+- Runtime loading remains limited to strict packaged output.
+- Package manifest remains the runtime entry authority.
+- Load sequencing remains deterministic and report-oriented.
+- Fail-fast behavior remains scoped to invalid packaged runtime input.
+- No engine core API files were modified.
+
+## Approved Commit Comment
+build(runtime-loader): add strict packaged runtime asset loader
+
+## Next Command
+APPLY_PR_RUNTIME_ASSET_LOADER
diff --git a/docs/pr/PLAN_PR_RUNTIME_ASSET_LOADER.md b/docs/pr/PLAN_PR_RUNTIME_ASSET_LOADER.md
@@ -0,0 +1,92 @@
+# PLAN_PR_RUNTIME_ASSET_LOADER
+
+## Goal
+Define a strict runtime asset loader and execution model that consumes packaged project output and resolves
+runtime-ready assets deterministically without changing engine core APIs.
+
+## Context
+The project baseline now includes:
+- registry-aware editors
+- additive project-level asset dependency graph
+- enforced asset validation engine
+- assistive remediation system
+- strict project packaging/export system
+
+The next architectural layer is runtime execution. This system must load packaged outputs in a predictable,
+fail-fast way under the assumption that strict packaging already guaranteed correctness.
+
+## Strict Runtime Intent
+This PR is intentionally strict.
+Runtime loading should assume packaged data is valid and fail fast when required packaged contracts are violated.
+
+## Scope
+- Define packaged-input runtime contracts
+- Define runtime manifest consumption rules
+- Define deterministic asset load ordering
+- Define loader lifecycle states
+- Define runtime failure boundaries for invalid packaged input
+- Define handoff contract from packaging system to runtime loader
+
+## Non-Goals
+- No engine core API changes
+- No editor-side packaging redesign
+- No defensive missing-asset fallback layer
+- No runtime repair/remediation system
+- No support for invalid packaged content
+
+## Runtime Inputs
+- strict package manifest
+- dependency-resolved packaged assets
+- stable export layout from packaging system
+
+## Runtime Outputs
+- loaded runtime asset table
+- resolved startup dependency set
+- deterministic loader state/reporting
+- runtime-ready project bootstrap data
+
+## Proposed Loader State Model
+```json
+{
+  "runtimeLoader": {
+    "status": "idle | loading | ready | failed",
+    "loadedAssets": [],
+    "failedAt": null,
+    "reports": []
+  }
+}
+```
+
+## Core Contracts
+1. Runtime loader only accepts strict packaged output as input.
+2. Package manifest is the runtime authority for packaged asset enumeration.
+3. Load order must be deterministic enough for repeatable startup behavior.
+4. Missing or invalid required packaged assets must fail fast.
+5. Runtime loader does not repair invalid packages.
+6. Registry/graph concepts remain authoring-time sources; packaged manifest is runtime entry authority.
+7. Loader reports must be stable and human-readable for debugging.
+
+## Runtime Categories
+- manifest ingestion
+- package layout validation
+- deterministic load sequencing
+- startup dependency resolution
+- fail-fast boundary reporting
+- runtime bootstrap handoff
+
+## Shared Responsibilities
+- runtime loading logic should be centralized where practical
+- packaged manifest consumption should not be reimplemented ad hoc across samples/tools
+- reporting should be stable enough for validation and future automation
+
+## Manual Validation Checklist
+1. Valid packaged project loads successfully.
+2. Repeated loads of unchanged package produce stable load order.
+3. Missing required packaged asset fails fast.
+4. Invalid manifest/package contract fails fast.
+5. Ready state only occurs after all required startup dependencies resolve.
+6. Loader reports clearly identify failure boundaries.
+7. Engine core APIs remain unchanged.
+
+## Next Command
+BUILD_PR_RUNTIME_ASSET_LOADER
diff --git a/tests/run-tests.mjs b/tests/run-tests.mjs
@@ -87,6 +87,7 @@ import { run as runStorageService } from './persistence/StorageService.test.mjs'
 import { run as runAssetValidationEngine } from './tools/AssetValidationEngine.test.mjs';
 import { run as runAssetRemediationSystem } from './tools/AssetRemediationSystem.test.mjs';
 import { run as runProjectPackagingSystem } from './tools/ProjectPackagingSystem.test.mjs';
+import { run as runRuntimeAssetLoader } from './tools/RuntimeAssetLoader.test.mjs';
 import './render/Renderer.test.mjs';
 import { run as runReplaySystem } from './replay/ReplaySystem.test.mjs';
 import { run as runOrbitLabModel } from './samples/OrbitLabModel.test.mjs';
@@ -168,6 +169,7 @@ const tests = [
     ['AssetValidationEngine', runAssetValidationEngine],
     ['AssetRemediationSystem', runAssetRemediationSystem],
     ['ProjectPackagingSystem', runProjectPackagingSystem],
+    ['RuntimeAssetLoader', runRuntimeAssetLoader],
     ['ReplaySystem', runReplaySystem],
     ['OrbitLabModel', runOrbitLabModel],
     ['OrbitLabScene', runOrbitLabScene],
diff --git a/tests/tools/RuntimeAssetLoader.test.mjs b/tests/tools/RuntimeAssetLoader.test.mjs
@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import { loadPackagedProjectRuntime, summarizeRuntimeAssetLoader } from "../../tools/shared/runtimeAssetLoader.js";
+
+export async function run() {
+  const packageManifest = {
+    package: {
+      version: 1,
+      projectId: "demo-project",
+      createdFrom: {
+        registryVersion: 1,
+        graphVersion: 1
+      },
+      roots: [
+        { id: "sprite.hero", type: "sprite" }
+      ],
+      assets: [
+        { id: "palette.hero", type: "palette", path: "assets/palettes/hero.json", sourceTool: "sprite-editor" },
+        { id: "sprite.hero", type: "sprite", path: "assets/sprites/hero.json", sourceTool: "sprite-editor" }
+      ],
+      dependencies: [
+        { from: "sprite.hero", to: "palette.hero", type: "usesPalette" }
+      ],
+      reports: []
+    }
+  };
+
+  const loadOrder = [];
+  const readyResult = await loadPackagedProjectRuntime({
+    packageManifest,
+    loaders: {
+      data: async (id, definition) => {
+        loadOrder.push(id);
+        return { id, path: definition.path, loaded: true };
+      }
+    },
+    resolvePackagedAsset: (asset) => ({
+      id: asset.id,
+      path: asset.path
+    })
+  });
+
+  assert.equal(readyResult.runtimeLoader.status, "ready");
+  assert.deepEqual(loadOrder, ["palette.hero", "sprite.hero"]);
+  assert.equal(readyResult.bootstrap.projectId, "demo-project");
+  assert.deepEqual(readyResult.bootstrap.startupAssetIds, ["sprite.hero"]);
+  assert.equal(summarizeRuntimeAssetLoader(readyResult), "Runtime loader ready with 2 assets.");
+
+  const repeatedOrder = [];
+  const repeatedResult = await loadPackagedProjectRuntime({
+    packageManifest,
+    loaders: {
+      data: async (id, definition) => {
+        repeatedOrder.push(id);
+        return { id, path: definition.path, loaded: true };
+      }
+    },
+    resolvePackagedAsset: (asset) => ({
+      id: asset.id,
+      path: asset.path
+    })
+  });
+  assert.equal(repeatedResult.runtimeLoader.status, "ready");
+  assert.deepEqual(repeatedOrder, loadOrder);
+
+  const missingAssetResult = await loadPackagedProjectRuntime({
+    packageManifest,
+    loaders: {
+      data: async (id, definition) => ({ id, path: definition.path, loaded: true })
+    },
+    resolvePackagedAsset: (asset) => asset.id === "sprite.hero" ? null : { id: asset.id, path: asset.path }
+  });
+  assert.equal(missingAssetResult.runtimeLoader.status, "failed");
+  assert.equal(missingAssetResult.runtimeLoader.failedAt, "sprite.hero");
+  assert.equal(missingAssetResult.runtimeLoader.reports.at(-1)?.code, "MISSING_PACKAGED_ASSET");
+
+  const invalidManifestResult = await loadPackagedProjectRuntime({
+    packageManifest: {
+      package: {
+        version: 1,
+        projectId: "",
+        roots: [],
+        assets: [],
+        dependencies: []
+      }
+    }
+  });
+  assert.equal(invalidManifestResult.runtimeLoader.status, "failed");
+  assert.equal(invalidManifestResult.runtimeLoader.failedAt, "manifest");
+  assert.equal(invalidManifestResult.runtimeLoader.reports[0]?.code, "INVALID_PACKAGE_MANIFEST");
+}
diff --git a/tools/shared/runtimeAssetLoader.js b/tools/shared/runtimeAssetLoader.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-build(packaging): add strict project packaging and export system`
	`1`	`+build(runtime-loader): add strict packaged runtime asset loader`