Ecosystem abstraction (for Solana support)

CLAUDE.md

@@ -0,0 +1,29 @@
+# Repository conventions for coding agents
+
+Guidance for AI coding agents (and humans) working in this repo. Keep changes consistent
+with these unless a maintainer says otherwise.
+
+## Python
+
+### Do NOT use `from __future__ import annotations`
+
+Never add `from __future__ import annotations` to a module. If you touch a file that has it
+and it's reasonable to do so, remove it.
+
+Why:
+- It's a dead-end feature. PEP 563 (the string-annotations behaviour this import enables) was
+  never made the default and has effectively been superseded by PEP 649 / PEP 749 (lazy
+  evaluation) from Python 3.14 on. Relying on the `__future__` behaviour is betting on a path
+  the language is moving away from — it will change/break under you in future versions.
+- It doesn't actually solve the problem it's reached for. Stringizing *all* annotations breaks
+  anything that introspects them at runtime — pydantic, dataclasses, `typing.get_type_hints`,
+  and our own annotation-driven graph wiring (see `composer/rustapp/_llm_agent.py`, which had
+  to stay eager precisely because stringized `NotRequired[T]` broke pydantic unwrapping). It
+  trades one set of problems for a subtler set.
+
+What to do instead (we target Python 3.12+):
+- Modern syntax works at runtime without the future import: `X | None`, `list[str]`,
+  `dict[str, int]`, `tuple[int, ...]`, PEP 695 generics (`class Foo[T]:` / `def f[T]()`).
+- For a genuine forward reference (a name not yet defined where the annotation is evaluated —
+  e.g. a dataclass field typed as a class defined later in the file), quote just that one
+  annotation: `backend: "RustBackend"`. Quote the specific ref; don't stringize the whole module.

composer/foundry/pipeline.py

@@ -78,7 +78,7 @@
 system (a uint256 being non-negative, etc.) are also uninteresting.
 """
 from composer.spec.system_model import (
-    ContractComponentInstance, SourceApplication,
+    ContractComponentInstance, ContractInstance, SourceApplication,
 )
 
 from composer.io.multi_job import HandlerFactory
@@ -106,7 +106,7 @@ class FoundryPhase(enum.Enum):
     TEST_GENERATION = "test_generation"
     REPORT = "report"
 
-class FoundryFormalizer(Formalizer[GeneratedFoundryTest]):
+class FoundryFormalizer(Formalizer[GeneratedFoundryTest, ContractComponentInstance]):
     def __init__(self, conf: _ForgeRunConfig):
         super().__init__(GeneratedFoundryTest, "foundry")
         self.conf = conf
@@ -138,11 +138,11 @@ async def fetch_verdicts(self, inp: ReportComponentInput[GeneratedFoundryTest])
         return await _foundry_verdicts(inp)
 
 @dataclass
-class FoundrySystem(PreparedSystem[GeneratedFoundryTest]):
+class FoundrySystem(PreparedSystem[GeneratedFoundryTest, ContractComponentInstance, ContractInstance]):
     form: FoundryFormalizer
 
     @override
-    async def prepare_formalization(self, run: PipelineRun) -> Formalizer[GeneratedFoundryTest]:
+    async def prepare_formalization(self, run: PipelineRun) -> Formalizer[GeneratedFoundryTest, ContractComponentInstance]:
         return self.form
 
 @dataclass
@@ -166,7 +166,7 @@ async def prepare_system(
         self,
         analyzed: SourceApplication,
         run: PipelineRun[FoundryPhase, None]
-    ) -> PreparedSystem[GeneratedFoundryTest]:
+    ) -> PreparedSystem[GeneratedFoundryTest, ContractComponentInstance, ContractInstance]:
         return FoundrySystem(
             main_instance(
                 analyzed, run.source

composer/pipeline/cli.py

@@ -20,6 +20,7 @@
     CorePipelineResult
 )
 from composer.spec.artifacts import ArtifactIdentifier
+from composer.spec.system_model import FeatureUnit
 from composer.spec.service_host import ModelProvider
 from composer.spec.system_analysis import SolidityIdentifier
 from .core import PipelineBackend, run_pipeline
@@ -113,10 +114,10 @@ class StagedPipeline:
     root_key: str
 
 class Continuation[P: enum.Enum, H](Protocol):
-    async def __call__[FormT: BackendResult, A: ArtifactIdentifier](
+    async def __call__[FormT: BackendResult, A: ArtifactIdentifier, U: FeatureUnit, Main](
         self,
         env: ServiceHost,
-        backend: PipelineBackend[P, FormT, H, A]
+        backend: PipelineBackend[P, FormT, H, A, U, Main]
     ) -> CorePipelineResult[FormT]:
         ...
 
@@ -249,9 +250,9 @@ async def cli_pipeline[P: enum.Enum, H](
                 relative_path=init_source.relative_path
             )
 
-            async def cont[FormT: BackendResult, A: ArtifactIdentifier](
+            async def cont[FormT: BackendResult, A: ArtifactIdentifier, U: FeatureUnit, Main](
                 env: ServiceHost,
-                backend: PipelineBackend[P, FormT, H, A]
+                backend: PipelineBackend[P, FormT, H, A, U, Main]
             ) -> CorePipelineResult[FormT]:
                 full_ctx = WorkflowContext.create(
                     services=conns.memory,