Selection engine adapter contract
CA-A1 architecture record. Updated: 2026-10-05. Vendor-neutral conceptual contract CA-CONTRACT-SEL-001. OpenDLP / sortition-algorithms are candidate implementations (CA-R3); this phase does not code the adapter.
Invocation
executeSelection(specRef, specDigest, poolRef, poolDigest,
seedArtefact, algorithmId, algorithmVersion) → SelectionResult | SelectionError
| Field | Meaning |
|---|
specRef | SelectionSpecification id + version (authorised/locked) |
specDigest | digest of the spec payload actually supplied |
poolRef + poolDigest | anonymised respondent pool — IDs + permitted attributes only |
seedArtefact | entropy record produced by ceremony layer (public draw, committed randomness, etc.) |
algorithmId + algorithmVersion | engine + exact version — recorded in run metadata |
Outputs
| Field | Meaning |
|---|
selectedIds | ordered/unordered per spec policy |
reserveOrder | ranked reserves within exhaustion rules |
metrics | quota fulfilment / optimisation objective values where available |
runMetadata | timestamps, iterations, engine version, config actually used |
reproArtefacts | input digest, output digest, full parameter echo — sufficient for independent re-run |
errors | structured failures (infeasible quotas, undersupplied strata, bad fields) |
Behavioural contract
- Determinism: identical (spec digest, pool digest, seed, algorithm id+version) must yield identical output — the basis of CA-REQ-014.
- Idempotency: repeated invocation with identical inputs is a no-op verification, not a new run record. A new run requires new ceremony artefacts.
- Schema/versioning: inputs and outputs carry contract version; engine must echo the contract version it executed.
- Failure: infeasible quota/pool errors are returned, never silently relaxed — spec change requires re-authorisation at Layer 1.
- Retry: retries must reuse the same seed artefact (a retry is the same run), or open a new ceremony (a new run).
- Privacy boundary: engine input is the permitted-fields projection — identity, contact and disallowed attributes never cross the seam. The engine never receives names/addresses.
- No side-channel decisions: engine returns candidates only; Cicada records selected/reserve status as institutional events with authority.
Candidate mapping (evidence)
| Contract element | sortition-algorithms | OpenDLP | Panelot |
|---|
| strata/quotas input | category matrix + targets | target CSV | hosted form |
| seed handling | caller-supplied | engine-internal (undocumented) | opaque |
| output | selected + metrics | run records + report | CSV panel |
| repro artefacts | deterministic re-run | DB records (no export bundle) | none public |
| reserves | remaining pool | first-class replacement runs | hosted |
Gap visible: nobody emits a portable witness bundle — the adapter output packaging is Cicada’s.
Sources