motionloom 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motionloom",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "packageManager": "pnpm@11.20.0",
   "description": "MotionLoom: project-aware animation Skill with Agent interoperability, graph, provenance, Motion IR, runtime telemetry, Visual Truth, Remediation Learning, DSSE-compatible signed attestation, external evidence verification and Dev Lab review.",
@@ -40,7 +40,40 @@
     ".claude",
     ".codex",
     "AGENTS.md",
-    "agent-surfaces.json"
+    "agent-surfaces.json",
+    "scripts/asset-consistency.py",
+    "schemas/asset-identity.schema.json",
+    "schemas/action-set.schema.json",
+    "schemas/frame-geometry.schema.json",
+    "schemas/atlas-contract.schema.json",
+    "schemas/layered-map.schema.json",
+    "tests/scripts/test_asset_consistency.py",
+    "scripts/artifact-intake.py",
+    "schemas/generation-receipt.schema.json",
+    "schemas/control-track.schema.json",
+    "schemas/export-manifest.schema.json",
+    "schemas/artifact-adapter-registry.schema.json",
+    "artifact-adapter-registry.json",
+    "examples/agent-consumer/artifact-intake",
+    "tests/scripts/test_artifact_intake.py",
+    "scripts/runtime-candidate.py",
+    "schemas/runtime-candidate.schema.json",
+    "examples/agent-consumer/runtime-candidate",
+    "tests/scripts/test_runtime_candidate.py",
+    "scripts/rig-compatibility.py",
+    "schemas/rig-compatibility.schema.json",
+    "schemas/rig-adapter-registry.schema.json",
+    "rig-adapter-registry.json",
+    "examples/agent-consumer/rig-compatibility",
+    "tests/scripts/test_rig_compatibility.py",
+    "scripts/rive-package-gate.py",
+    "schemas/rive-package-manifest.schema.json",
+    "examples/agent-consumer/rive-package-gate",
+    "tests/scripts/test_rive_package_gate.py"
+    ,"scripts/build-ai-pilot.py"
+    ,"scripts/isolate-alpha-background.py"
+    ,"tests/scripts/test_ai_pilot_builder.py"
+    ,"tests/scripts/test_alpha_isolation.py"
   ],
   "keywords": [
     "animation",
@@ -61,7 +94,17 @@
     "dev-lab",
     "visual-truth",
     "remediation-learning",
-    "agent-interoperability"
+    "agent-interoperability",
+    "asset-consistency",
+    "sprite-atlas",
+    "layered-map",
+    "artifact-intake",
+    "generation-receipt",
+    "runtime-candidate",
+    "rig-compatibility",
+    "rive-package-gate",
+    "provider-neutral",
+    "agent-skills"
   ],
   "repository": {
     "type": "git",
@@ -83,6 +126,7 @@
     "test": "node bin/motionloom.mjs test",
     "validate": "npm run quality:attestation",
     "doctor": "node bin/motionloom.mjs doctor --json",
+    "init": "node bin/motionloom.mjs init",
     "setup": "node bin/motionloom.mjs setup",
     "setup:dry": "node bin/motionloom.mjs setup --dry-run",
     "status": "node bin/motionloom.mjs status",
@@ -125,7 +169,15 @@
     "discovery:show": "node bin/motionloom.mjs discovery show --root . --json",
     "install:matrix": "node bin/motionloom.mjs discovery install-matrix --root . --json",
     "asset-provenance:validate": "node bin/motionloom.mjs asset-provenance validate --input examples/agent-consumer/ai-generated-pilot-provenance.json --json",
-    "asset-provenance:check": "node bin/motionloom.mjs asset-provenance check --input examples/agent-consumer/ai-generated-pilot-provenance.json --root examples/agent-consumer --mode runtime --json"
+    "asset-provenance:check": "node bin/motionloom.mjs asset-provenance check --input examples/agent-consumer/ai-generated-pilot-provenance.json --root examples/agent-consumer --mode runtime --json",
+    "asset:consistency": "node bin/motionloom.mjs asset-consistency validate --kind frame-geometry --input examples/agent-consumer/asset-consistency/hero-walk-frame-geometry.json --root examples/agent-consumer/asset-consistency --json",
+    "asset:audit": "node bin/motionloom.mjs asset-consistency report --kind frame-geometry --input examples/agent-consumer/asset-consistency/hero-walk-frame-geometry.json --root examples/agent-consumer/asset-consistency --json",
+    "artifact:intake": "node bin/motionloom.mjs artifact-intake intake --root . --registry artifact-adapter-registry.json --receipt examples/agent-consumer/artifact-intake/hero-motion-receipt.json --controls examples/agent-consumer/artifact-intake/hero-motion-controls.json --export-manifest examples/agent-consumer/artifact-intake/hero-motion-export.json --json",
+    "runtime:candidate": "node bin/motionloom.mjs runtime-candidate validate --root . --input examples/agent-consumer/runtime-candidate/hero-walk-candidate.json --json",
+    "rig:compatibility": "node bin/motionloom.mjs rig-compatibility validate --root . --registry rig-adapter-registry.json --input examples/agent-consumer/rig-compatibility/hero-walk-fixture-rig.json --json",
+    "rive:gate": "node bin/motionloom.mjs rive-package-gate --help"
+    ,"pilot:build": "node bin/motionloom.mjs pilot-build --help"
+    ,"alpha:isolate": "node bin/motionloom.mjs alpha-isolate --help"
   },
   "dependencies": {
     "@lottiefiles/dotlottie-web": "^0.79.0",

package/references/browser-review-contract.md

@@ -13,9 +13,15 @@ Prepare a candidate with:
 ```bash
 python3 scripts/review-hook.py prepare \
   --task-dir artifacts/<task-id> \
-  --lab-url http://127.0.0.1:3300
+  --lab-url https://animdevlab-hcxnxr9c.manus.space/lab
 ```
 
+`--lab-url` là **browser review route thực tế**. Dev Lab React dùng
+`https://…/lab`; Dev Lab static cục bộ dùng `http://127.0.0.1:3300/`. Command
+tự gắn `scene`, `task_id`, `candidate_id`, `artifact_base` và `task_base` vào
+URL cùng origin; Dev Lab từ chối URL thiếu field, foreign origin hoặc path sai
+trước khi tải artifact.
+
 The command writes `browser-review.json` into the task bundle and scene output, records a deterministic `candidate_id`, binds the candidate to the context and animation source SHA-256, and emits JSON containing the exact URL and the next browser Agent action.
 
 The browser-capable Agent must open the emitted URL, inspect frames 0/50/100, scrub the timeline, check the quality checklist, record notes, and ask the user for approval. The page exposes `window.__lab.getReview()` so the Agent can capture the review payload without relying on a downloaded file. Persist the captured payload with:

package/references/intelligence-core.md

@@ -9,6 +9,10 @@ Use this reference when an Agent needs to understand or extend MotionLoom's task
 | `project-graph.json` | `python3 scripts/intelligence.py graph build --task-dir <task>` | Links project, intent, scene, context, artifacts and review with task identity and hashes. |
 | `provenance.json` | `python3 scripts/intelligence.py provenance build --task-dir <task>` | Records step actor, builder, materials, products, policy, result and parent chain hash. |
 | `asset-provenance.json` | `motionloom asset-provenance check --input <path> --root <scene-dir> --mode runtime|production` | Classifies asset origin/authority and effective readiness, binds file hashes and license/source metadata, and fails closed before production eligibility. It never grants `production_approved`. |
+| `asset-consistency-report` | `motionloom asset-consistency validate|analyze|report --kind <kind> --input <path> --root <asset-root> --json` | Measures declared identity, action timing, frame geometry, atlas ownership or layered-map bounds against real artifacts. It reports deterministic errors/warnings and never grants provenance authority or approval. |
+| `generation-receipt.json`, `control-track.json`, `export-manifest.json` | `motionloom artifact-intake intake --root <root> --registry <registry> --receipt <path> --controls <path> --export-manifest <path> --json` | Hash-binds an internal-skill/provider generation record, declared controls and emitted output to a provider-neutral adapter descriptor. It neither invokes a provider nor proves artist authority, runtime readiness or approval. |
+| `runtime-candidate.json` | `motionloom runtime-candidate validate --root <root> --input <path> --json` | Requires the intake bundle and referenced identity/action/geometry contracts to agree before allowing a `runtime_test_ready`, review-required candidate. |
+| `rig-compatibility.json` | `motionloom rig-compatibility validate --root <root> --registry <registry> --input <path> --json` | Checks adapter target/evidence, skeleton, sockets, action/event coverage and candidate binding. A pass is compatibility evidence, not a production-rig or approval claim. |
 | `capability-registry.json` | `python3 scripts/intelligence.py capabilities build --output <path>` | Describes verified/scaffold-only adapters, evidence freshness, compatibility, fallback and side effects. |
 | `motion-ir.json` | `python3 scripts/intelligence.py motion-ir build --task-dir <task>` | Binds framework-neutral tracks and accessibility policy to task, scene, context and source. |
 | `replay-bundle.json` | `python3 scripts/intelligence.py replay capture --root <root> --task-dir <task>` | Captures clean-root artifact hashes and environment metadata; verification fails on mutation or omission. |
@@ -29,6 +33,10 @@ Use this reference when an Agent needs to understand or extend MotionLoom's task
 
 The Agent must build the graph, Motion IR, step-level provenance, asset provenance, replay bundle, P1 feedback reports and semantic-lint benchmark after render and before the strict quality gate. For a strict observability run it must also capture runtime telemetry and run the external verifier before `--require-telemetry`. For a production trust run it must derive/sign `attestation.json`, copy or resolve a managed `trust-policy.json`, run the independent attestation verifier and use `--require-attestation` plus `--require-asset-provenance`. It must run the report completeness contract for changed scenes; that contract selects one deterministic passing task bundle and fails on ambiguous ties. It may use a verified capability only when the registry evidence is fresh, its hash matches the referenced file and the target environment is compatible. `scaffold_only` is a planning option, never a production acceptance result.
 
+When the task includes multi-frame, atlas or layered-map material, the Agent must also build the applicable consistency contract and preserve its JSON result in the task bundle. The Agent should use `--strict` for a production-bound check, but must keep warnings and measurements visible in the report. A consistency pass is evidence that declared artifact boundaries agree; it is not a claim about aesthetics, provenance, artist authorship or user consent.
+
+When the task begins with an internal skill such as ImageGen or an external generation provider, the Agent must additionally preserve a receipt/control/export intake bundle. The registry only describes audited adapter evidence; it does not make a network call and it cannot elevate a provider's claim. Build the runtime candidate only after Intake and the referenced consistency contracts pass, then validate rig compatibility for skeleton-based output. Preserve all three result files in the task bundle and Dev Lab handoff; any `scaffold`, `static-validated`, `blocked` or `review_required` result must remain visible through review.
+
 The graph and provenance are evidence indexes, not approval tokens. A valid graph cannot bypass source binding, runtime assertions, browser review, reviewer consent or the `OPEN_PR=0` default. A confidence or risk value can prioritize investigation but cannot replace a deterministic rule or human decision.
 
 All task-bound paths are resolved under their declared root and symlink traversal is rejected. Replay additionally binds `task_dir`, `task_id`, scene and every recorded file to the same task bundle. Browser-review and Dev Lab handoffs must use same-origin artifact/task bases and must agree on task, scene and candidate identity; expiry or mismatch is a review failure, not a warning to ignore.
@@ -73,11 +81,21 @@ python3 scripts/quality-gate.py \
   --scene <scene> \
   --context <project-context.json> \
   --task-dir artifacts/<task-id> \
-  --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation --require-asset-provenance
+  --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation --require-asset-provenance --require-asset-consistency
+motionloom asset-consistency validate \
+  --kind frame-geometry \
+  --input src/output/<scene>/hero-walk-frame-geometry.json \
+  --root src/output/<scene> --strict --json
 motionloom asset-provenance check \
   --input src/output/<scene>/asset-provenance.json \
   --root src/output/<scene> --mode production \
   --manifest src/output/<scene>/manifest.json --json
+motionloom artifact-intake intake --root . --registry artifact-adapter-registry.json \
+  --receipt <generation-receipt.json> --controls <control-track.json> \
+  --export-manifest <export-manifest.json> --json
+motionloom runtime-candidate validate --root . --input <runtime-candidate.json> --json
+motionloom rig-compatibility validate --root . --registry rig-adapter-registry.json \
+  --input <rig-compatibility.json> --json
 python3 scripts/remediation-learning.py validate --history artifacts/remediation-history.jsonl --json
 python3 scripts/remediation-learning.py summary --history artifacts/remediation-history.jsonl --output artifacts/remediation-summary.json --json
 python3 scripts/eval-intelligence.py
@@ -104,5 +122,8 @@ The replay policy excludes generated reports and manifests because `report.py co
 | `runtime telemetry verification failed` | Scrub-point evidence is stale, tampered, missing, cross-task, path-escaped or bound to different source/manifest/Motion IR bytes | Re-run the real runtime capture from the canonical scene/task bundle, then verify again; never treat the verifier as approval. |
 | `attestation verification failed` | Payload hash, DSSE signature, signer validity/revocation, policy lookup, path binding or expected task/scene binding failed | Regenerate the statement from current artifacts, re-run the external verifier against a managed policy and investigate signer lifecycle; never flip `approval` or bypass user review. |
 | `asset provenance is blocked` or `production_eligible: false` | Origin is unknown/AI-generated without the required review, a file hash/license/runtime/full-gate record is missing, or an Agent self-asserted artist authority/approval | Keep the candidate runtime-only, fix the provenance record or obtain the required human review; never rewrite the authority tier or set `production_approved` automatically. |
+| `asset consistency is blocked` | Declared frame, atlas or map geometry disagrees with the referenced bytes, or a required image/contract is missing | Inspect the measured path/code, regenerate only the affected asset/contract, rerun the deterministic check and return to Dev Lab review; never bypass the finding with provenance or attestation. |
+| `artifact intake is blocked` | Receipt, controls, export, provenance, adapter evidence or output hash is missing, escaped, unknown or disagrees with the declared bundle | Recreate the intake bundle from the actual generator/export output, preserve the correct provenance tier and rerun the check; never set an adapter to verified or grant approval by hand. |
+| `runtime candidate is blocked` or rig compatibility fails | Intake, identity/action/geometry refs, runtime evidence, adapter target, skeleton, socket or event coverage is missing or incompatible | Repair/re-export only the affected asset or adapter binding, regenerate runtime evidence and return to Dev Lab review; do not substitute a placeholder rig or override the result. |
 
 The public eval corpus is `tests/evals/intelligence-cases.json`. It covers positive verified selection plus scaffold-only, stale evidence, tampering, graph corruption, replay tamper and foreign-task candidate failures. P1 extends the acceptance surface with semantic warning preservation, generic-intent detection, multi-scene context drift, selective rerun binding, performance budget/frame-rate warnings, perceptual easing/reduced-motion warnings and benchmark execution time. The 1.9.0 slice adds runtime telemetry happy-path, state tamper, cross-task identity, stale evidence and symlink escape cases. The 2.0.0 slice adds clean attestation, payload tamper, binding mismatch, revoked signer and unknown signer cases without weakening the approval=false and human-review invariants.

package/rig-adapter-registry.json

@@ -0,0 +1,39 @@
+{
+  "schema_version": "0.1",
+  "registry_id": "motionloom-rig-adapters",
+  "generated_at": "2026-08-15T00:00:00Z",
+  "adapters": [
+    {
+      "adapter_id": "motionloom.sprite-frame-sequence",
+      "target": "sprite",
+      "framework": "sprite",
+      "status": "static_validated",
+      "evidence": [{"path": "scripts/runtime-candidate.py", "sha256": "ec292a902de12c14dcc53442e15f6d7b8a8f8d22fd2bcdd7e522c15ca9d20af1"}],
+      "limitations": ["Contract-only adapter; requires runtime evidence before runtime verification."]
+    },
+    {
+      "adapter_id": "motionloom.rive-runtime",
+      "target": "rive",
+      "framework": "rive",
+      "status": "project_integrated",
+      "evidence": [{"path": "scripts/runtime-adapters.mjs", "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89"}],
+      "limitations": ["Runtime harness evidence must be captured for the concrete scene and source bytes."]
+    },
+    {
+      "adapter_id": "motionloom.gsap-runtime",
+      "target": "gsap",
+      "framework": "gsap",
+      "status": "project_integrated",
+      "evidence": [{"path": "scripts/runtime-adapters.mjs", "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89"}],
+      "limitations": ["Runtime harness evidence must be captured for the concrete scene and source bytes."]
+    },
+    {
+      "adapter_id": "motionloom.framer-motion-runtime",
+      "target": "framer-motion",
+      "framework": "framer-motion",
+      "status": "project_integrated",
+      "evidence": [{"path": "scripts/runtime-adapters.mjs", "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89"}],
+      "limitations": ["Runtime harness evidence must be captured for the concrete scene and source bytes."]
+    }
+  ]
+}

package/schemas/action-set.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/action-set.schema.json",
+  "title": "MotionLoom Action Set Contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "asset_identity", "actions", "invariants"],
+  "properties": {
+    "schema_version": { "const": "0.1" },
+    "asset_identity": { "type": "string", "minLength": 1 },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["action_id", "fps", "frames", "loop"],
+        "properties": {
+          "action_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$" },
+          "fps": { "type": "number", "exclusiveMinimum": 0 },
+          "frames": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 },
+          "loop": { "type": "boolean" },
+          "events": { "type": "array", "items": { "type": "string" } },
+          "required_sockets": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "invariants": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["canvas_width", "canvas_height", "pivot_tolerance_px", "footline_tolerance_px", "bbox_drift_tolerance_px"],
+      "properties": {
+        "canvas_width": { "type": "integer", "minimum": 1 },
+        "canvas_height": { "type": "integer", "minimum": 1 },
+        "pivot_tolerance_px": { "type": "number", "minimum": 0 },
+        "footline_tolerance_px": { "type": "number", "minimum": 0 },
+        "bbox_drift_tolerance_px": { "type": "number", "minimum": 0 },
+        "min_alpha_pixels": { "type": "integer", "minimum": 1 }
+      }
+    }
+  }
+}

package/schemas/artifact-adapter-registry.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/lenhonbp/MotionLoom/blob/main/schemas/artifact-adapter-registry.schema.json",
+  "title": "MotionLoom artifact adapter registry",
+  "description": "Provider-neutral capability descriptors. Registry membership does not invoke a provider, transfer credentials or grant approval.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "registry_id", "generated_at", "selection_policy", "adapters"],
+  "properties": {
+    "schema_version": {"const": "0.1"},
+    "registry_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$"},
+    "generated_at": {"type": "string", "format": "date-time"},
+    "selection_policy": {"type": "object", "additionalProperties": false, "required": ["require_verified", "allow_scaffold_only"], "properties": {"require_verified": {"type": "boolean"}, "allow_scaffold_only": {"type": "boolean"}}},
+    "adapters": {"type": "array", "minItems": 1, "items": {"type": "object", "additionalProperties": false, "required": ["adapter_id", "kind", "status", "adapter_version", "invocation_mode", "cost_class", "inputs", "outputs", "compatibility", "evidence", "limitations", "risk_level", "side_effect_level"], "properties": {"adapter_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{2,127}$"}, "kind": {"type": "string", "enum": ["fixture", "internal_skill", "external_provider", "manual_import"]}, "status": {"type": "string", "enum": ["verified", "scaffold_only", "static_validated", "project_integrated", "disabled"]}, "adapter_version": {"type": "string", "minLength": 1}, "invocation_mode": {"type": "string", "enum": ["none", "manual", "agent-mediated", "api"]}, "cost_class": {"type": "string", "enum": ["included", "metered", "external", "unknown"]}, "inputs": {"type": "array", "items": {"type": "string"}}, "outputs": {"type": "array", "items": {"type": "string"}}, "compatibility": {"type": "object", "additionalProperties": false, "required": ["os"], "properties": {"os": {"type": "array", "items": {"type": "string"}}, "browsers": {"type": "array", "items": {"type": "string"}}}}, "evidence": {"type": "array", "minItems": 1, "items": {"type": "object", "additionalProperties": false, "required": ["path", "sha256", "kind"], "properties": {"path": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "kind": {"type": "string", "enum": ["runtime", "ci", "browser", "static"]}}}}, "limitations": {"type": "array", "items": {"type": "string"}}, "risk_level": {"type": "string", "enum": ["low", "medium", "high"]}, "side_effect_level": {"type": "string", "enum": ["read", "local_write", "user_review_required", "remote_write"]}}}}
+  }
+}

package/schemas/asset-identity.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/asset-identity.schema.json",
+  "title": "MotionLoom Asset Identity Contract",
+  "description": "Stable identity and derivation locks shared by generated or code-authored runtime variants.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "asset_id", "asset_kind", "identity", "derivation"],
+  "properties": {
+    "schema_version": { "const": "0.1" },
+    "asset_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._/-]{2,127}$" },
+    "asset_kind": {
+      "type": "string",
+      "enum": ["character", "prop", "effect", "background", "tile", "ui", "rig"]
+    },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["subject_id", "reference_hashes", "camera", "coordinate_system", "scale", "pivot", "palette_lock"],
+      "properties": {
+        "subject_id": { "type": "string", "minLength": 1 },
+        "reference_hashes": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "camera": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["projection", "width", "height", "focal_length"],
+          "properties": {
+            "projection": { "enum": ["orthographic", "perspective"] },
+            "width": { "type": "integer", "minimum": 1 },
+            "height": { "type": "integer", "minimum": 1 },
+            "focal_length": { "type": "number", "exclusiveMinimum": 0 }
+          }
+        },
+        "coordinate_system": { "enum": ["screen_y_down", "world_y_up"] },
+        "scale": { "type": "number", "exclusiveMinimum": 0 },
+        "pivot": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["x", "y", "space"],
+          "properties": {
+            "x": { "type": "number", "minimum": 0, "maximum": 1 },
+            "y": { "type": "number", "minimum": 0, "maximum": 1 },
+            "space": { "enum": ["normalized_canvas", "world"] }
+          }
+        },
+        "palette_lock": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["colors", "delta_e_tolerance"],
+          "properties": {
+            "colors": {
+              "type": "array",
+              "items": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "delta_e_tolerance": { "type": "number", "minimum": 0, "maximum": 100 }
+          }
+        },
+        "style_profile": { "type": "string", "minLength": 1 },
+        "lighting_profile": { "type": "string", "minLength": 1 }
+      }
+    },
+    "derivation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["origin", "source_refs"],
+      "properties": {
+        "origin": { "enum": ["ai_generated", "ai_assisted", "ai_assisted_human_reviewed", "artist_authored", "code_authored", "unknown"] },
+        "generator": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["model", "task_id", "prompt_hash"],
+          "properties": {
+            "model": { "type": "string", "minLength": 1 },
+            "task_id": { "type": "string", "minLength": 1 },
+            "prompt_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+            "seed": { "type": ["integer", "string"] },
+            "tool_version": { "type": "string" }
+          }
+        },
+        "source_refs": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1
+        },
+        "derivation_chain": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["step", "operation", "input_hashes", "output_hash"],
+            "properties": {
+              "step": { "type": "integer", "minimum": 0 },
+              "operation": { "type": "string", "minLength": 1 },
+              "input_hashes": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
+              "output_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+            }
+          }
+        }
+      }
+    },
+    "provenance_ref": { "type": "string", "minLength": 1 },
+    "notes": { "type": "string" }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"derivation": {"properties": {"origin": {"enum": ["ai_generated", "ai_assisted", "ai_assisted_human_reviewed"]}}, "required": ["origin"]}}, "required": ["derivation"]},
+      "then": {"properties": {"derivation": {"required": ["generator"]}}}
+    }
+  ]
+}

package/schemas/asset-provenance.schema.json

@@ -26,7 +26,7 @@
     },
     "authority": {
       "type": "string",
-      "enum": ["ai_generated", "ai_assisted", "ai_assisted_human_reviewed", "artist_authored", "unknown"]
+      "enum": ["ai_generated", "ai_assisted", "ai_assisted_human_reviewed", "artist_authored", "code_authored", "unknown"]
     },
     "readiness": {
       "type": "string",

package/schemas/atlas-contract.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/atlas-contract.schema.json",
+  "title": "MotionLoom Atlas Contract",
+  "description": "Deterministic atlas geometry and contamination boundary contract.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "image", "allow_rotation", "padding_px", "extrude_px", "regions"],
+  "properties": {
+    "schema_version": { "const": "0.1" },
+    "image": { "type": "string", "minLength": 1 },
+    "allow_rotation": { "const": false },
+    "padding_px": { "type": "integer", "minimum": 0 },
+    "extrude_px": { "type": "integer", "minimum": 0 },
+    "require_transparent_outside_regions": { "type": "boolean" },
+    "regions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["region_id", "frame_id", "rect", "trim", "pivot"],
+        "properties": {
+          "region_id": { "type": "string", "minLength": 1 },
+          "frame_id": { "type": "string", "minLength": 1 },
+          "rect": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["x", "y", "width", "height"],
+            "properties": {
+              "x": { "type": "integer", "minimum": 0 },
+              "y": { "type": "integer", "minimum": 0 },
+              "width": { "type": "integer", "minimum": 1 },
+              "height": { "type": "integer", "minimum": 1 }
+            }
+          },
+          "trim": { "type": "boolean" },
+          "pivot": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["x", "y"],
+            "properties": { "x": { "type": "number" }, "y": { "type": "number" } }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/control-track.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/lenhonbp/MotionLoom/blob/main/schemas/control-track.schema.json",
+  "title": "MotionLoom generation control track",
+  "description": "Hash-bound generation controls. It stores no prompt plaintext, API token or approval assertion.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "control_id", "asset_id", "references", "tracks", "output_profile", "created_at"],
+  "properties": {
+    "schema_version": {"const": "0.1"},
+    "control_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$"},
+    "asset_id": {"type": "string", "minLength": 1},
+    "created_at": {"type": "string", "format": "date-time"},
+    "references": {"type": "array", "minItems": 1, "items": {"type": "object", "additionalProperties": false, "required": ["id", "path", "sha256", "role"], "properties": {"id": {"type": "string", "minLength": 1}, "path": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "role": {"type": "string", "enum": ["identity", "style", "pose", "camera", "motion", "palette", "lighting", "other"]}}}},
+    "tracks": {"type": "array", "minItems": 1, "items": {"type": "object", "additionalProperties": false, "required": ["id", "kind", "binding", "value_hash"], "properties": {"id": {"type": "string", "minLength": 1}, "kind": {"type": "string", "enum": ["identity", "style", "camera", "motion", "pose", "seed", "negative_prompt", "lighting", "source"]}, "binding": {"type": "string", "enum": ["required", "advisory", "not_applicable"]}, "value_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "samples": {"type": "integer", "minimum": 0}}}},
+    "output_profile": {"type": "object", "additionalProperties": false, "required": ["kind"], "properties": {"kind": {"type": "string", "enum": ["image", "frame_sequence", "sprite_atlas", "layered_map", "video", "rigged_2d", "rigged_3d", "runtime_scene"]}, "fps": {"type": "number", "exclusiveMinimum": 0}, "expected_frame_count": {"type": "integer", "minimum": 1}, "loop": {"type": "boolean"}}}
+  }
+}

package/schemas/export-manifest.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/lenhonbp/MotionLoom/blob/main/schemas/export-manifest.schema.json",
+  "title": "MotionLoom artifact export manifest",
+  "description": "Binds an output set to its receipt and control track for downstream runtime and Dev Lab evidence. It does not certify production readiness.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "manifest_id", "asset_id", "receipt_ref", "control_track_ref", "outputs", "created_at"],
+  "properties": {
+    "schema_version": {"const": "0.1"},
+    "manifest_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$"},
+    "asset_id": {"type": "string", "minLength": 1},
+    "created_at": {"type": "string", "format": "date-time"},
+    "receipt_ref": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"},
+    "control_track_ref": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"},
+    "runtime_evidence_ref": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"},
+    "outputs": {"type": "array", "minItems": 1, "items": {"type": "object", "additionalProperties": false, "required": ["path", "role", "sha256", "bytes", "target"], "properties": {"path": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"}, "role": {"type": "string", "minLength": 1}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "bytes": {"type": "integer", "minimum": 0}, "target": {"type": "string", "enum": ["runtime_candidate", "preview", "archive"]}}}}
+  }
+}

package/schemas/frame-geometry.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/frame-geometry.schema.json",
+  "title": "MotionLoom Frame Geometry Contract",
+  "description": "Measured geometry for action frames; measurements are validated against pixels, not trusted from AI self-reporting.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "asset_identity", "canvas", "invariants", "frames"],
+  "properties": {
+    "schema_version": { "const": "0.1" },
+    "asset_identity": { "type": "string", "minLength": 1 },
+    "canvas": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["width", "height", "color_space", "alpha_mode"],
+      "properties": {
+        "width": { "type": "integer", "minimum": 1 },
+        "height": { "type": "integer", "minimum": 1 },
+        "color_space": { "enum": ["srgb", "linear-srgb"] },
+        "alpha_mode": { "enum": ["straight", "premultiplied"] }
+      }
+    },
+    "invariants": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pivot_tolerance_px", "footline_tolerance_px", "bbox_drift_tolerance_px", "min_alpha_pixels"],
+      "properties": {
+        "pivot_tolerance_px": { "type": "number", "minimum": 0 },
+        "footline_tolerance_px": { "type": "number", "minimum": 0 },
+        "bbox_drift_tolerance_px": { "type": "number", "minimum": 0 },
+        "min_alpha_pixels": { "type": "integer", "minimum": 1 },
+        "allow_external_opaque_pixels": { "type": "boolean" }
+      }
+    },
+    "frames": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["frame_id", "image", "rect", "alpha_bbox", "pivot", "footline_px", "safe_rect", "sha256"],
+        "properties": {
+          "frame_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$" },
+          "image": { "type": "string", "minLength": 1 },
+          "rect": { "$ref": "#/$defs/rect" },
+          "alpha_bbox": { "$ref": "#/$defs/rect" },
+          "pivot": { "$ref": "#/$defs/point" },
+          "footline_px": { "type": "number" },
+          "safe_rect": { "$ref": "#/$defs/rect" },
+          "bleed_margin_px": { "type": "integer", "minimum": 0 },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "rect": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y", "width", "height"],
+      "properties": {
+        "x": { "type": "integer", "minimum": 0 },
+        "y": { "type": "integer", "minimum": 0 },
+        "width": { "type": "integer", "minimum": 1 },
+        "height": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "point": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y", "space"],
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "space": { "enum": ["pixels", "normalized"] }
+      }
+    }
+  }
+}

package/schemas/generation-receipt.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/lenhonbp/MotionLoom/blob/main/schemas/generation-receipt.schema.json",
+  "title": "MotionLoom generation receipt",
+  "description": "Provider-neutral, hash-bound receipt for generated or imported visual artifacts. A receipt is evidence, never human approval.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "receipt_id", "asset", "authority", "provider", "control_track_ref", "provenance_ref", "outputs", "created_at"],
+  "properties": {
+    "schema_version": {"const": "0.1"},
+    "receipt_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$"},
+    "created_at": {"type": "string", "format": "date-time"},
+    "asset": {"type": "object", "additionalProperties": false, "required": ["id", "kind", "intended_use"], "properties": {"id": {"type": "string", "minLength": 1}, "kind": {"type": "string", "enum": ["image", "frame_sequence", "sprite_atlas", "layered_map", "video", "rigged_2d", "rigged_3d", "runtime_scene"]}, "intended_use": {"type": "string", "enum": ["pilot", "runtime_candidate", "reference_only"]}}},
+    "authority": {"type": "string", "enum": ["ai_generated", "ai_assisted", "ai_assisted_human_reviewed", "artist_authored", "code_authored", "unknown"]},
+    "provider": {"type": "object", "additionalProperties": false, "required": ["adapter_id", "kind", "invocation_mode", "task_id", "model", "generated_at", "cost_class"], "properties": {"adapter_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{2,127}$"}, "kind": {"type": "string", "enum": ["fixture", "internal_skill", "external_provider", "manual_import"]}, "invocation_mode": {"type": "string", "enum": ["none", "manual", "agent-mediated", "api"]}, "task_id": {"type": "string", "minLength": 1}, "model": {"type": "string", "minLength": 1}, "generated_at": {"type": "string", "format": "date-time"}, "cost_class": {"type": "string", "enum": ["included", "metered", "external", "unknown"]}, "prompt_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"}}},
+    "control_track_ref": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"},
+    "provenance_ref": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"},
+    "outputs": {"type": "array", "minItems": 1, "items": {"type": "object", "additionalProperties": false, "required": ["path", "role", "sha256", "bytes"], "properties": {"path": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"}, "role": {"type": "string", "minLength": 1}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "bytes": {"type": "integer", "minimum": 0}}}}
+  }
+}