# Public API
```rust
use std::{path::Path, sync::Arc};
pub use kcode_k1_canonical_chain::{SubmitError, TxId};
pub use kcode_k1_transaction::{GENESIS_PARENT, SubsystemId};
pub type TestSigner = Box<dyn FnOnce(&[u8]) -> Result<[u8; 64], String> + Send + 'static>;
pub type TestQueuePropagation = Box<dyn FnOnce(&[u8]) -> Result<(), String> + Send + 'static>;
pub trait TestSubsystem: Send + Sync + 'static {
fn submit_txn(&self, id: TxId, payload: &[u8]) -> Result<(), String>;
fn reorg(&self) -> Result<(), String>;
}
pub trait OrderingCandidate: Send + Sync + 'static {
fn register_subsystem(&self, subsystem: SubsystemId, after: Option<TxId>, handler: Arc<dyn TestSubsystem>) -> Result<(), String>;
fn submit_txn(&self, transaction: &[u8]) -> Result<(), SubmitError>;
fn submit_local_txn(&self, timestamp: u64, creator: [u8; 32], subsystem: SubsystemId, payload: &[u8], signer: TestSigner, queue_propagation: TestQueuePropagation) -> Result<Vec<u8>, String>;
fn contains(&self, id: TxId) -> bool;
fn tip(&self) -> Option<TxId>;
fn between_txids(&self, older: TxId, newer: TxId) -> Result<Vec<TxId>, String>;
fn get_txn(&self, id: TxId) -> Result<Option<Vec<u8>>, String>;
}
pub trait OrderingHarness: Send + Sync {
fn open(&self, root: &Path) -> Result<Arc<dyn OrderingCandidate>, String>;
}
pub fn verify_queue_before_callback(harness: &dyn OrderingHarness) -> Result<(), String>;
pub fn verify_independent_subsystem_lanes(harness: &dyn OrderingHarness) -> Result<(), String>;
pub fn verify_signing_commit_exclusion(harness: &dyn OrderingHarness) -> Result<(), String>;
pub fn verify_replay_live_handoff(harness: &dyn OrderingHarness) -> Result<(), String>;
pub fn verify_callback_failure_isolation(harness: &dyn OrderingHarness) -> Result<(), String>;
pub fn verify_reorganization_isolation(harness: &dyn OrderingHarness) -> Result<(), String>;
pub fn verify_unrelated_callback_reentry(harness: &dyn OrderingHarness) -> Result<(), String>;
pub fn verify_restart_duplicates_and_queries(harness: &dyn OrderingHarness) -> Result<(), String>;
```
# Adapter and fixture contract
This is a development and test conformance package. An `OrderingHarness` opens the supplied candidate directly at the requested private root; adapters forward candidate behavior rather than emulate ordering, delivery, persistence, errors, or synchronization. Each open returns one independently usable candidate instance.
`OrderingCandidate` mirrors the operations exercised by the scenarios. `submit_local_txn` forwards each boxed signer and queue closure exactly once and returns the complete signed transaction bytes. `register_subsystem` treats `after` as the last successfully integrated transaction and replays matching canonical transactions strictly after it. A consumer adapter may bridge `TestSubsystem` to its public callback trait but adds no scheduling, retry, locking, persistence, or panic handling.
`contains` reports canonical membership. `tip` reports the canonical tip. `between_txids` returns canonical transaction IDs strictly after `older` and strictly before `newer`, in canonical order. `get_txn` returns the complete stored bytes for a canonical ID.
Postcommit queue, subsystem, and panic failures contain the literal text `was committed`, `TxId`, and that ID's `Debug` representation. Peer callback failures use `SubmitError::Other`. These exact strings let the testkit distinguish an already committed outcome from a retryable precommit failure without adding a public error type.
Each verifier owns its roots, threads, callbacks, gates, transactions, assertions, and cleanup. Calls share no package-wide lock and may run concurrently; only an atomic root-name counter is shared. Deliberately blocked fixture callbacks are isolated by candidate resource.
Cross-thread progress waits fail after two seconds, and known-blocked checks observe a 50-millisecond quiet interval. Those durations are test-hang boundaries, not candidate latency promises. Direct in-process candidate calls cannot be forcibly cancelled and a candidate that never returns from one may hang its verifier.
A verifier returns `Ok(())` only after all assertions pass. Assertion failures, escaped panics, bounded-wait failures, worker panics, and candidate errors become a descriptive `Err`. Callback failures and panics intentionally injected by a scenario must be caught and reported by the candidate according to this contract.
# Verifiers
## `verify_queue_before_callback`
Submits local transactions with a failing queue closure and a panicking queue closure.
Each matching callback observes that its queue closure already completed.
Both transactions remain committed and integrated, with committed `TxId` errors.
The registration then successfully integrates a third local transaction.
## `verify_independent_subsystem_lanes`
Blocks the first callback for subsystem A and commits a second A transaction concurrently.
The second A queue closure completes, but its callback and caller wait behind the first ticket.
Canonical queries and a complete local submission for B finish while A remains blocked.
After release, A callbacks appear in commit order and B has its independent payload.
## `verify_signing_commit_exclusion`
Blocks a local signer before its transaction can commit.
A second local writer and a canonical tip query are started while signing is blocked.
Neither may finish before the signer is released.
Both writers and the query finish after signing and commit complete.
## `verify_replay_live_handoff`
Starts subsystem A replay with its first callback blocked.
Registration, local submission, and callback work for B complete independently.
A new A peer transaction commits during blocked replay without live delivery.
Replay then delivers both A payloads exactly once before registration returns.
## `verify_callback_failure_isolation`
Queues two A submissions behind a blocked callback that returns an error.
Both callers wake with their own committed `TxId`; the later callback is not invoked.
A can be re-registered after quiescence, and an injected callback panic is reported as committed.
Only A faults, while B remains usable before and after the panic.
## `verify_reorganization_isolation`
Creates a winning sibling that removes A's latest canonical transaction and installs a B replacement.
A's reorganization callback is blocked while the replacement is already the canonical tip.
B delivery, queries, and another B local submission complete outside the blocked A lane.
After release, only a new A registration receives subsequent A work.
## `verify_unrelated_callback_reentry`
Registers an A callback that synchronously submits a local transaction to B.
The outer A submission finishes without deadlock or caller-managed coordination.
The nested B transaction is committed and delivered before the outer callback returns.
The scenario verifies the exact nested payload at B.
## `verify_restart_duplicates_and_queries`
Submits peer transactions and a concurrent duplicate while the original callback is blocked.
The duplicate does not redeliver, and tip, membership, retrieval, and exclusive-between queries agree.
A fresh candidate reopened on the same root replays both payloads once and ignores a duplicate.
Opening a caller-created empty root also succeeds with an empty canonical tip.