Appearance
Adapter Lifecycle
Overview
The adapter lifecycle defines how input is received, processed, optionally executed through Forge primitives, and transformed into output.
Not all adapters implement all stages.
The lifecycle is modular and composable.
Canonical Flow
Input → Validate → Transform → Plan → Execute → Aggregate → Finalize → OutputEach stage is optional depending on adapter type.
Lifecycle Stages
1. Input
The adapter receives input from an external source:
- API request
- File / stream
- Internal system trigger
This is the raw entry point into the adapter.
2. Validate
The adapter verifies input correctness:
- Schema validation
- Required fields
- Type checking
- Domain constraints
Invalid input should fail early.
3. Transform
Input is normalized into a usable internal structure:
- Mapping external formats → internal schema
- Enriching missing values
- Standardizing units / formats
This stage prepares data for execution or further processing.
4. Plan (Optional)
If the adapter orchestrates compute:
- Defines which primitives will be used
- Sets execution parameters
- Establishes ordering or dependencies
Example:
- Monte Carlo simulation plan
- Multi-stage execution graph
- Batch processing setup
5. Execute (Optional)
The adapter delegates execution to Forge primitives.
Characteristics:
- No direct compute inside adapter
- All heavy computation is externalized
- Execution is distributed and managed by Forge
Adapters may:
- Call a single primitive
- Trigger multiple executions
- Execute sequentially or in parallel
6. Aggregate (Optional)
If multiple execution results exist:
- Combine outputs
- Merge datasets
- Compute summary metrics
- Apply post-processing logic
Example:
- Ensemble aggregation
- Risk metrics consolidation
- Multi-run statistics
7. Finalize
Final transformation before output:
- Format response
- Attach metadata
- Prepare domain-specific structures
This stage ensures output is usable by the target system.
8. Output
Return result to:
- API client
- External system
- Storage layer
Output should clearly represent:
- Result data
- Execution context (if applicable)
- Any relevant metadata
Lifecycle Variants
Different adapter types use different subsets of the lifecycle.
Ingestion Adapter
Input → Validate → Transform → Output- No compute
- Focus on normalization and validation
Execution Adapter
Input → Validate → Transform → Plan → Execute → Finalize → Output- Calls one or more primitives
- Produces direct results
Aggregation Adapter
Input → Validate → Transform → Execute → Aggregate → Finalize → Output- Combines multiple execution outputs
Export Adapter
Input → Transform → Finalize → Output- No compute
- Focus on formatting and delivery
Failure Handling
Failures can occur at any stage:
| Stage | Failure Type |
|---|---|
| Validate | Invalid input |
| Transform | Mapping / parsing errors |
| Plan | Invalid execution plan |
| Execute | Primitive failure |
| Aggregate | Inconsistent results |
| Finalize | Formatting issues |
Adapters must:
- Fail explicitly
- Preserve error context
- Avoid masking execution failures
Idempotency
Adapters should aim for idempotent behavior when possible:
- Same input → same output (if deterministic)
- Controlled randomness via seeds
- Safe retries
Observability
Adapters should expose:
- Execution steps
- Inputs and outputs (where applicable)
- References to primitive executions
- Error traces
This enables:
- Debugging
- Auditing
- Replay
Composition Across Adapters
Adapters can be chained:
Adapter A → Adapter B → Adapter CThis enables:
- Complex workflows
- Modular pipelines
- Domain-specific systems
Mental Model
The adapter lifecycle is:
- A structured flow of responsibility
- Not a rigid pipeline
- Not all stages are required
Adapters implement only what they need —
but must respect execution boundaries.
Key Insight
Adapters do not define how computation works.
They define how computation is requested, coordinated, and delivered.