Add provider-neutral asset and task role contracts

[yuecideng]

Description

Define immutable asset descriptions, candidates, prepared snapshots and the external Provider protocol. Task Program owns role requirements, explicit category aliases and geometric relations; contracts do not fetch assets or instantiate simulation.

Refs #810. This is layer 1/5 of the currently authorized asset-generalization implementation. PR6 online generation is deferred; no generation service is invoked by this stack.

Stack

• Layer: 1/5
• Base: main
• Depends on: none
• Followed by: Prepare local and explicit asset catalogs #812

Validation

Provider-neutral data and role-contract tests cover invalid numeric values, unknown fields, JSON ownership and semantic references. New routed context and API reference entries describe the ownership boundary.

Tests use the repository-pinned DexSim 0.5.1rc1 and its matching Warp 1.17.0 via a process-local dependency path. The workstation's default editable DexSim build has an unrelated import failure; no shared environment installation was modified.

Black 26.3.1 formatting passed. Final-stack API coverage is 2640/2640 exports; the Sphinx dummy build completed with warnings/errors originating in unchanged documentation/docstrings and no diagnostics for the new asset modules. Context review adds the asset-generalization topic and updates component/semantic ownership where behavior changed. Existing data download and scene acceptance guidance remains applicable.

Type of change

• New feature (non-breaking change which adds functionality)

Checklist

• I have run the black . command to format the code base.
• I reviewed affected documentation and agent context, updated it where needed, or explained why no update was needed.
• Public API changes are reflected in the API docs (python docs/scripts/check_api_docs.py).
• I have added tests that prove the feature works.
• Dependencies reviewed; no new package requirements.

CI collection fix

The asset-catalog tests now form an explicit Python package, avoiding the top-level test_contracts module collision with existing scene-expansion tests under pytest's default import mode. The original two-file collection failure was reproduced before the fix. Combined asset, role, matcher and scene-contract validation passed 94 tests at the third layer; runtime APIs are unchanged. CI passed and PRs #811–#813 were squash-merged together into main. Higher layers remain drafts.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge with PR #812's region-within-bounds check included.

Summary

Adds immutable, provider-neutral asset records and task-owned role requirements.

• Asset providers can describe candidates and prepare local assets.
• Task roles keep their identity while assets change.

This assessment depends on PR #812, which adds checks that usable regions stay inside object bounds. That fix is not present in this PR.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Q[AssetQuery] --> P[AssetProvider]
  P --> C[AssetCandidate]
  C --> M[Provider materialize]
  M --> A[PreparedAsset]
  D[AssetDescriptor] --> A
  R[Task-owned AssetRequirements] --> Q

Loading

_{Reviews (1) · Last reviewed commit: "fix(tests): isolate asset catalog test m..." · Reviewed by Greptile}