# Test Driver Concept Model > Current scope, 2026-09-28: TD-WP-0003 removes speculative lifecycle scoring > and declared Temperature. See [settlement and compatibility](TestDriverGeneralisationReview.md). **Status:** v0.1 Draft **Framework:** `test-driver` ## 1. Purpose `test-driver` is a use-case-driven verification framework for software systems that are developed under increasingly fluid, fast-moving and agentic development conditions. Its core premise is that verification should evolve together with the behavior and implementation it protects: > Tests begin fluid and exploratory when software is changing quickly, adapt with agentic assistance while behavior stabilizes, and crystallize into deterministic test code when implementation and expected behavior become sufficiently mature. The framework is intended to support, from one coherent conceptual model: - integration testing, - end-to-end and user-journey testing, - multi-user interaction testing, - authorization and security testing, - resilience and failure testing, - later, scale and performance testing. The framework treats a test not primarily as source code, but as a **verification asset** that connects intended behavior to observed implementation behavior over time. --- ## 2. Core Principles ### 2.1 Intent precedes implementation Tests ultimately protect intended behavior, not incidental implementation details. A user-facing capability should therefore be described first in terms of purpose, actors, expected outcomes, claims and invariants rather than UI clicks or protocol calls. ### 2.2 Use cases are the primary behavioral source The core source object is a **UseCase**. A use case describes purposeful behavior involving one or more actors and a system under test. Integration, journey, multi-user and security tests are projections or transformations of that same use case rather than unrelated test suites. ### 2.3 Agenticity is a means, not the source of truth Agents are particularly useful for: - interpreting intent, - navigating unstable interaction surfaces, - discovering alternative paths, - generating scenario variations, - exploring adversarial behavior, - adapting tests to legitimate mechanical changes, - investigating and minimizing failures. The ultimate verdict should, wherever possible, come from explicit and independent oracles rather than from an actor agent judging its own success. ### 2.4 Exploration precedes crystallization Agentic tests should not remain agentic merely because they started that way. As behavior and implementation become stable, agentic realizations are progressively hardened and finally crystallized into deterministic tests. ### 2.5–2.6 Evidence, not lifecycle scores Retain observations and verdicts. Asset selection and retirement remain explicit maintainer choices; there is no energy score or automated retirement policy. ### 2.7 Implementation is not the truth When a test and an implementation disagree, the framework must not automatically adapt the test to the implementation. The disagreement may indicate: 1. an implementation defect, 2. an intentional requirement change, 3. a defective or outdated test, 4. an ambiguous condition requiring investigation. --- ## 3. Conceptual Layers The concept model is organized into five layers: 1. **Intent** — what should be true. 2. **Situation** — under what circumstances it should be true. 3. **Variation** — how behavior should be explored. 4. **Execution** — what actually happened. 5. **Evolution** — how verification changes over time. --- # 4. Intent Layer ## 4.1 UseCase A **UseCase** describes purposeful interaction with a system from the perspective of one or more actors. A use case should primarily describe: - intent, - participating actor roles, - preconditions, - relevant outcomes, - behavioral claims, - invariants. It should avoid encoding unnecessary implementation mechanics. Example: ```text Alice wants to share document D with Bob so that Bob can read it while Carol remains unable to access it. ``` ## 4.2 Claim A **Claim** is an expected behavior that should hold within a use case or scenario. Examples: ```text Bob can read document D. Bob cannot modify document D. The sharing operation appears in the audit history. ``` Claims are typically local to a use case or capability. ## 4.3 Invariant An **Invariant** is a property expected to remain true across many scenarios, implementations or use cases. Examples: ```text Tenant isolation must be preserved. Unauthorized actors must not obtain document contents. Read permission must not imply write permission. Audit records must not be silently omitted. ``` Security requirements are often best represented as invariants. --- # 5. Situation Layer ## 5.1 Actor An **Actor** is an independently acting user, system or external participant. An actor has an epistemic and execution boundary containing at least: - identity, - role, - tenant or organizational context, - credentials, - session, - permissions, - private memory, - known resources, - available interaction surfaces, - allowed communication channels. Actors in multi-user tests must not implicitly share knowledge unless the use case explicitly allows it. ## 5.2 Cast A **Cast** is the set of actors participating in a scenario. Example: ```text Alice — owner Bob — intended recipient Carol — unrelated user ``` ## 5.3 World A **World** is the relevant initial state in which a scenario begins. It may contain: - users and identities, - tenants, - resources, - permissions, - configuration, - external services, - clocks, - feature flags, - fixtures, - dependency state. ## 5.4 Surface A **Surface** is a mechanism through which an actor interacts with the system. Examples: - browser UI, - HTTP API, - CLI, - mobile UI, - message queue, - email, - webhook, - external integration API. ## 5.5 Scenario A **Scenario** is a concrete realization of a use case. Conceptually: ```text Scenario = UseCase + Cast + World + Schedule + Surfaces + Variant ``` A scenario determines enough context for one or more actors to execute purposeful behavior. ## 5.6 Schedule A **Schedule** defines causal and temporal relationships between actions. Instead of assuming every scenario is a linear sequence, the framework should support a causal graph including relationships such as: - must happen before, - caused by, - wait until, - concurrent with, - within time T, - must never occur during interval T. Schedules are central to multi-user and concurrency testing. --- # 6. Variation Layer ## 6.1 Lens A **Lens** is the verification perspective applied to a use case. Initial lens canon: ### Integration Lens Do participating components communicate correctly? ### Journey Lens Can an actor achieve the intended outcome through the complete system? ### Interaction Lens Does the system remain correct when multiple independent actors interact with shared state? ### Security Lens Do claims and invariants survive unauthorized, manipulated, adversarial or logically invalid behavior? ### Resilience Lens Does the use case remain valid under component, dependency or network failures? ### Scale Lens Does the behavior remain correct and useful under realistic populations and load? ## 6.2 Variant A **Variant** is an alternative realization of a scenario that preserves enough identity with its originating use case to be meaningfully compared. Variants may differ in: - actor roles, - data, - sequence, - timing, - interaction surface, - environment, - dependency state. ## 6.3 Mutation A **Mutation** is a deliberate transformation of a scenario intended to probe robustness, correctness or security. Initial mutation canon: ```text actor-substitution resource-substitution tenant-substitution sequence-reordering step-skipping replay repetition concurrency surface-substitution invalid-state privilege-mutation dependency-failure time-shift ``` Security scenarios should preferentially be derived as transformations of ordinary business use cases rather than maintained as a disconnected testing universe. --- # 7. Execution Layer ## 7.1 Driver A **Driver** exposes an interaction surface to an actor or deterministic test implementation. Examples: ```text BrowserDriver HttpDriver CliDriver MailDriver QueueDriver ``` Drivers should support both agentic and deterministic realizations where practical. ## 7.2 Semantic Action A **Semantic Action** describes a meaningful action independently of the mechanics needed to perform it. Examples: ```text open_resource(R) grant_access(Bob, READ) revoke_access(Bob) approve_invoice(I) ``` Semantic actions form an important bridge between agentic exploration and deterministic crystallization. An agent may initially discover how a semantic action is performed through an unstable interface. Later the driver may provide a stable deterministic implementation of the same semantic action. ## 7.3 Actor Runtime The **Actor Runtime** executes actor behavior while preserving actor isolation. It is responsible for: - identity/session isolation, - agent or deterministic execution, - memory isolation, - surface access, - action recording, - evidence correlation. ## 7.4 Orchestrator The **Orchestrator** coordinates: - actors, - scenario state, - barriers, - schedules, - clocks, - world setup and teardown, - run lifecycle. The orchestrator may know the complete world state even when individual actors do not. ## 7.5 Observer An **Observer** captures facts about what happened without being the actor responsible for producing the behavior. Observers may inspect: - externally visible outcomes, - API responses, - domain state, - logs, - traces, - metrics, - audit records, - messages, - UI state. ## 7.6 Observation An **Observation** is a captured fact produced during a run. ## 7.7 Evidence **Evidence** is persisted observation material supporting later judgment, diagnosis and lineage. A run should be able to produce an evidence pack containing, where applicable: - run identifier, - use-case and scenario version, - system/component versions, - environment, - actor identities and roles, - agent/runtime versions, - random seeds, - action timeline, - screenshots or UI traces, - requests and responses, - domain-state observations, - logs, - metrics, - distributed traces, - oracle evaluations, - verdict. ## 7.8 Oracle An **Oracle** evaluates evidence against a claim or invariant. Initial oracle categories: - outcome oracle, - state oracle, - authorization oracle, - invariant oracle, - interaction oracle, - temporal oracle, - negative temporal oracle, - audit oracle, - telemetry oracle, - semantic oracle. Deterministic oracles are preferred where possible. ## 7.9 Verdict A **Verdict** summarizes the result of an oracle or scenario execution. Initial verdict canon: ```text PASS FAIL SUSPICIOUS INCONCLUSIVE ``` The non-Boolean states are important for exploratory and agentic testing where uncertainty may be real and should not be hidden. ## 7.10 Finding A **Finding** is a meaningful detected discrepancy, defect, risk or unexpected behavior that warrants persistence and possible investigation. Findings may later generate new or hardened verification assets. ## 7.11 Investigator An **Investigator** attempts to understand a finding and may: - reproduce it, - minimize the scenario, - identify relevant evidence, - distinguish product defect from test defect, - propose a deterministic regression test. The investigator may itself be agentic. --- # 8. Verification Asset A **Verification Asset** is the central managed object of test-driver. It represents something the framework has reason to verify over time. A verification asset connects: ```text UseCase / Requirement | v Verification Asset | +--> Agentic Scenario | +--> Adaptive Scenario | +--> Hardened Scenario | +--> Deterministic Test Implementation ``` The identity of the verification asset should survive changes in its test implementation. A verification asset may contain: ```yaml id: document-share-read usecase: document/share protects: claims: - recipient-can-read - recipient-cannot-write invariants: - tenant-isolation - least-privilege maturity: adaptive execution: mode: agentic surfaces: - browser lineage: created_from: usecase ``` --- # 9. Evolution Layer ## 9.1 Test Maturity Test-driver uses a progressive maturity model: ```text T0 Exploratory T1 Agentic T2 Adaptive T3 Specified T4 Hardened T5 Deterministic ``` ### T0 — Exploratory The framework knows the intent but little about the stable realization. ### T1 — Agentic An agent can pursue the intended outcome through available surfaces. ### T2 — Adaptive The scenario has acquired partial structure and can adapt to legitimate implementation change. ### T3 — Specified Expected behavior, actions and oracles are increasingly explicit. ### T4 — Hardened The scenario is tightly constrained and should require little interpretation. ### T5 — Deterministic The verification executes as conventional deterministic test code without agentic involvement. ## 9.2 Use-Case Maturity Use-case maturity is independent from test maturity. Initial model: ```text U0 Hypothesis U1 Emerging U2 Established U3 Stable U4 Contractual ``` A stable use case may temporarily require agentic tests when a new implementation is introduced. ## 9.3 Measured stability Declared Temperature was removed on 2026-09-28 (F-0008). Crystallization uses observed trajectory stability through `assess_stability`, not a temperature label. ## 9.4 Adaptation **Adaptation** modifies a test realization while attempting to preserve the intent being verified. Adaptations must be classified. Initial adaptation canon: ```text A0 selector A1 navigation A2 protocol A3 data-shape A4 workflow A5 semantic A6 invariant ``` A0-A2 may commonly be eligible for automatic adaptation. A4-A6 should normally produce review, investigation or an explicit requirement change rather than silent mutation. ## 9.5 Hardening **Hardening** reduces ambiguity and increases explicitness. Hardening may introduce: - explicit preconditions, - explicit semantic actions, - stronger oracles, - controlled fixtures, - stable selectors or APIs, - bounded timing, - deterministic data, - reduced agent discretion. ## 9.6 Crystallization **Crystallization** is the transition from learned agentic or adaptive execution into deterministic verification. Canonical lifecycle: ```text Explore -> Discover -> Reproduce -> Minimize -> Specify -> Harden -> Crystallize -> Deterministic Regression ``` Crystallization is not necessarily permanent. A major implementation change may temporarily move an asset back toward adaptive or agentic execution. ## 9.7–9.8 Removed lifecycle scores Energy and Confidence are removed from the current concept set. Neither was used in a decision across the three reference use cases. H-005 is dormant-indefinite; there is no capture-only energy subsystem. ## 9.9 Lineage **Lineage** records why a verification asset exists and how it evolved. Example: ```text UseCase | +--> exploratory Test A | +--> Finding F17 | +--> Regression Test A.1 | +--> deterministic implementation ``` Lineage should make it possible to answer: > Why does this test exist? ## 9.10 Asset removal Maintainers may remove obsolete tests with an explicit review of the protected claims. No computed Retirement concept or policy is implemented or scheduled. --- # 10. Triadic Verification The framework continuously reconciles three evolving systems: ```text Use Cases <-> Implementations <-> Verification Assets ``` This is called **Triadic Verification**. A verification asset is valid only insofar as it continues to meaningfully connect intended behavior with observed implementation behavior. When one side changes, the framework evaluates whether the other relationships remain valid. --- # 11–12. Removed planning abstractions Metabolism and Campaign were removed from the current concept set on 2026-09-28. The experiments choose explicit scenario and mutation lists. No evidence justifies a planner or score-driven scheduling; these are not deferred implementation promises. --- # 13. Reference Scenario The first reference scenario for test-driver should intentionally exercise multi-user state and security semantics. ## Use case > Alice owns resource R. Alice grants Bob read access. Bob can access R. Carol cannot access R. Alice revokes Bob's access. Bob can no longer access R. ## Actors ```text Alice — owner Bob — recipient Carol — unrelated user ``` ## Claims ```text Bob can read R after grant. Bob cannot modify R with read-only permission. Bob cannot read R after revocation. ``` ## Invariants ```text Carol never gains access to R. Tenant isolation remains intact. Authorization must be consistent across surfaces. ``` ## Derived security mutations ```text Carol attempts direct access to R. Bob attempts write access. Bob substitutes another resource identifier. Bob retries access immediately after revocation. Bob attempts access through another surface. Grant and revoke are executed concurrently. ``` This scenario is intended as the first vertical slice because it exercises: - multiple actors, - identity isolation, - shared state, - authorization, - positive and negative behavior, - temporal transitions, - mutation, - deterministic oracles, - eventual crystallization. --- # 14. Initial Architecture Boundaries The initial implementation should preserve the following logical components: ```text UseCase Parser | v Scenario Planner | v Actor Runtime | v Drivers | v System Under Test Observers --> Evidence --> Oracle Engine --> Verdict Metadata Store: maturity lineage ``` The conceptual components may initially share a process or codebase. Their separation is semantic before it is architectural. --- # 15. Initial Development Sequence > **Superseded.** This section previously carried its own `M0`–`M3` sequence, > which conflicted with the sequences in `INTENT.md` and > `TestDriverInitialMilestones.md`. The canonical milestone sequence is > **`TestDriverInitialMilestones.md` (M0–M10)**. Recorded as framework finding > `F-0001` (CONCEPT_DRIFT), 2026-08-22. The former M0–M3 corresponded to canonical M1, M4, M5–M7 and M9 respectively. See the mapping table in `INTENT.md` § Initial Milestones. Execution order is *not* the canonical order — see `workplans/TD-WP-0002-vertical-spike-crystallization.md`. --- # 16. Canonical Concept Set v0.1 The initial test-driver vocabulary is: ```text UseCase Claim Invariant Actor Cast World Surface Scenario Schedule Lens Variant Mutation Driver SemanticAction ActorRuntime Orchestrator Observer Observation Evidence Oracle Verdict Finding Investigator VerificationAsset Maturity Adaptation Hardening Crystallization Lineage TriadicVerification ``` --- # 17. Summary The defining model of test-driver is: ```text INTENT | UseCase | v Verification Asset | +----------+----------+ | | | Lens Mutation Schedule | | | +----------+----------+ | Scenario | Actors + Drivers | v System Under Test | v Evidence | Oracles | v Verdict | Finding Repeated stable trajectories --> crystallization --> deterministic regression ``` The fundamental promise is: > **test-driver keeps verification useful while software changes rapidly, then turns learned behavior into cheap deterministic confidence as the system stabilizes.**