Canonical Smoke Suite
Forge Verification is built on maintained execution examples.
These examples are collectively referred to as the Canonical Smoke Suite.
Unlike illustrative documentation examples, smoke suites are executable runtime artifacts that are continuously maintained alongside the platform.
Every Verification guide references this suite instead of inventing standalone payloads.
Purpose
The Canonical Smoke Suite serves four purposes.
- Verify that a capability executes successfully.
- Detect regressions in execution contracts.
- Provide reproducible examples for evaluators.
- Keep documentation synchronized with the runtime.
Smoke suites are part of the platform verification process—not merely documentation assets.
Design Principles
Every canonical smoke should satisfy the following principles.
Executable
Every example must execute against the current runtime.
Documentation examples should never diverge from maintained smoke payloads.
Deterministic
Where a primitive supports deterministic execution, the smoke should define an explicit seed.
This allows replay and comparison across executions.
Observable
A smoke should expose enough runtime evidence for an evaluator to understand what happened.
Typical observations include:
- execution identity
- runtime metadata
- execution status
- artifacts
- result summary
- replay metadata
Minimal
A smoke should demonstrate one capability clearly.
Avoid combining multiple verification objectives into a single example.
Stable
Smoke payloads should evolve only when the execution contract evolves.
Routine documentation changes should never introduce payload drift.
Smoke Categories
Forge organizes canonical smoke suites by verification objective rather than by implementation.
Canonical Execution
Confirms that a capability executes successfully using a representative production payload.
Expected outcome:
- accepted request
- completed execution
- observable result
Artifact Verification
Confirms that requested runtime artifacts are generated.
Typical artifacts include:
- summary
- histogram
- samples.preview
- timeline
- cascade_paths
- critical_nodes
- confidence
- disagreement maps
Deterministic Replay
Runs the same payload multiple times using an identical seed.
Expected outcome:
- stable statistical outputs
- equivalent replay surface
- reproducible execution evidence
Negative Validation
Intentionally submits an invalid payload.
Expected outcome:
- validation failure
- no execution
- no runtime artifacts
Compatibility
Verifies alias handling and backward-compatible execution contracts where supported.
Capability Coverage
The maintained smoke suite currently covers representative workloads from multiple execution families.
| Execution Family | Representative Verification |
|---|---|
| Monte Carlo | Canonical execution, replay, validation |
| Search | Ranking, evidence generation, artifacts |
| Graph | Propagation, topology, cascade analysis |
| Ensemble | Multi-model deterministic comparison |
| Climate | Environmental simulation workloads |
| Finance | Financial modeling workloads |
| Energy | Infrastructure and grid analysis |
| Insurance | Loss modeling workloads |
| Reinsurance | Treaty and portfolio analysis |
Additional workloads may be added without changing the Verification methodology.
Canonical Smoke Structure
Every maintained smoke should contain:
- execution context
- operation identity
- profile
- arguments
- execution policy
- verification mode
- requested artifacts
- expected verification outcome
This structure allows documentation, automation, and runtime verification to reference the same execution contract.
Documentation Policy
Verification documentation should reference canonical smoke suites instead of embedding independent execution payloads.
This ensures that:
- runtime examples remain executable
- documentation remains synchronized
- reviewers evaluate real workloads
- examples evolve together with execution contracts
When a smoke payload changes, the associated Verification documentation should be updated as part of the same change.
Choosing a Smoke
Select a smoke according to the verification objective.
| Goal | Recommended Smoke |
|---|---|
| First successful execution | Canonical execution |
| Inspect runtime artifacts | Artifact verification |
| Verify deterministic behavior | Deterministic replay |
| Verify validation boundaries | Negative validation |
| Verify compatibility | Alias / compatibility smoke |
Relationship to Other Verification Documents
The Canonical Smoke Suite provides the executable foundation for the remainder of the Verification documentation.
Subsequent documents build directly on these maintained examples.
- First Verified Execution walks through a canonical execution.
- Inspect Result explains the returned runtime evidence.
- Replay & Determinism compares repeated executions.
- Negative Validation examines controlled validation failures.
- Artifact Inspection explains generated execution artifacts.
Final Principle
A Forge Verification example is considered canonical only when it originates from a maintained smoke suite.
Smoke suites are the authoritative source for executable documentation.