Damaros is a protocol-driven clinical trial screening system that evaluates eligibility across site-approved patient populations using site-approved FHIR access patterns. This is the same mental model Epic already uses for registry, population health, and research cohort tooling (scheduled, system-level, auditable access), not discretionary per-user chart mining or external SaaS analytics.

Population-level evaluation is required because inclusion and exclusion logic must be applied consistently across every potentially eligible patient attached to an approved cohort, not triggered ad hoc one patient at a time. That is why Bulk FHIR $export sits in the architecture as an optional, site-gated complement to iterative REST reads: it aligns with Epic's population-level access model (read-only, explicitly enabled, bounded jobs), not continuous streaming or open-ended replication.

System identity (deterministic core): a deterministic eligibility evaluation engine operating on FHIR-native inputs with full audit traceability. Protocol definitions supply versioned logic; REST and optional Bulk supply normalized facts; the engine executes the same rules on the same inputs for the same outcome class (PASS / REVIEW / FAIL); outputs are criterion-level decisions plus evidence and sync provenance, with no generative verdict on the screening path.

Reproducibility (non-stochastic on PHI): eligibility evaluation is deterministic and reproducible. Given the same protocol version and the same normalized inputs, the system produces identical criterion-level outcomes, and evaluations can be replayed for audit with full provenance. There is no stochastic "AI" behavior on patient-identifiable clinical data in the screening execution path.

Evaluation boundary: All eligibility evaluation occurs on normalized, protocol-scoped data within the execution environment.

Operationally, the product converts versioned trial protocols into structured evaluation rules, applies them to cohorts synchronized from FHIR (REST bundle pulls and, when enabled, Bulk export), and records PASS, REVIEW, or FAIL at criterion granularity with evidence references for coordinators, QA, and audit.

The production Epic connector is SMART on FHIR Backend Services: the API/worker exchanges a signed JWT for an access token (client_credentials + private_key_jwt, RFC 7523). Access is read-only for screening ingest. Epic tokens live server-side in process memory only, not in browsers or end-user SMART sessions for this path. End-user SMART on FHIR EHR launch is a separate integration pattern and is outside this Backend Services submission unless explicitly scoped elsewhere.

The API builds a signed JWT (iss/sub = Epic client id, aud = token URL, jti = UUID, bounded exp), POSTs to the Epic token endpoint with grant_type=client_credentials, and caches the access token in process memory for FHIR HTTP clients. Failures surface to operators; there is no silent fallback to unauthenticated reads.

OAuth system/*.read floor (per-patient hot path): when DAMAROS_EPIC_FETCH_MEDICATION_STATEMENT is not enabled (default), token scope must cover exactly what EpicFhirClient.fetch_patient_bundle (see connectors/epic_fhir.py, ~345 to 398) plus cohort GET Group/{id} via search_patients_from_group need: eight resource families below, with no write scopes. Epic's literal strings may use .r vs .read; DAMAROS_EPIC_SCOPE carries the agreed list at token time.

Never request FHIR Binary: product Python has zero HTTP calls to Binary (no GET Binary/, no Binary search). The only "binary" string hits in the repo are unrelated psycopg[binary] dependency markers in persistence modules. Do not register Binary.Read / Binary.Search (any Epic line-item variant): it is not derivable from code and would contradict DocumentReference handling in ingest/fhir_normalize.py (metadata only, see §02D).

Not on the per-patient OAuth floor (separate tracks): system/MedicationStatement.read only with §03 flag plus Epic amendment; Bulk Data $export scopes only when §03B gates and Epic line-items for kick-off, status, and file are approved (not "Bulk Data Delete Request": there is no delete implementation in FhirBulkExporter); all write scopes (§03C).

Scope and call parity: keep DAMAROS_EPIC_SCOPE aligned with traffic. With MedStatement flag off, fetch_patient_bundle does GET Patient/{id}; search_observations_lab_capped_variants for lab-tuned Observation searches; paginated search_type_all_pages for Condition, MedicationRequest, Procedure, AllergyIntolerance, DocumentReference; optional MedicationStatement when flag on. Cohort IDs use GET Group/{id} only, not Group search.

Epic's App Orchard / USCDI UI lists granular Read vs Search line items. OAuth system/*.read strings are a second contract, and both layers must map to the same HTTP calls. Register only line items with a traceable path in this codebase.

Bulk FHIR is how Epic already frames population work: read-only, site-controlled, scheduled, bounded cohort refresh. Not defensive experimentation, but correct use of Epic's population-level access model. Architectural shape in code: tenant isolation per deployment and org-scoped sync (run_sync_into_db(…, org_id=…) in ingest/cohort_sync.py); no default activation (bulk is an explicit integration path, not the REST per-patient default); read-only FHIR with resource sets bounded by Epic grants plus normalizer contract.

Bounded job lifecycle (FhirBulkExporter, connectors/fhir_bulk.py): each export is a finite job: kick-off (POST Group/{id}/$export), async status polling with explicit polling limits (max_poll_attempts × poll_interval_sec), then file download and NDJSON parse. That design prevents unbounded or continuous extraction; it is not a streaming tap on the EHR.

Operational summary: Bulk export supports scheduled, bounded cohort refresh in a site-controlled, read-only manner. Export bytes are processed through fhir_bundle_to_normalized into protocol-scoped structured rows and auditable eligibility outputs inside the hospital-approved deployment boundary, not exfiltrated as an unmanaged secondary clinical record store.

Deterministic handling of extra NDJSON types: bulk exports may include additional resource types depending on site configuration and optional _type on FhirBulkExporter.kick_off. The normalization layer (fhir_bundle_to_normalized in fhir_normalize.py) deterministically maps only resources covered by explicit type branches into normalized cohort fields tied to the normalized contract. Non-mapped resources are not persisted in normalized storage and are not included in downstream evaluation outputs. Eligibility execution consumes the normalized facts under versioned protocol logic, not open-ended ML interpretation of raw PHI on the hot path.

The live patient bundle pull for eligibility ingest is built in EpicFhirClient.fetch_patient_bundle (connectors/epic_fhir.py, ~345 to 398): GET Patient/{pid}; search_observations_lab_capped_variants for capped lab Observation searches; then paginated type searches for Condition, MedicationRequest, Procedure, AllergyIntolerance, and DocumentReference (with MedicationStatement inserted in that loop when DAMAROS_EPIC_FETCH_MEDICATION_STATEMENT is on). There are no Binary calls. This list must stay in lockstep with §02C OAuth scopes and flags.

Bulk Data $export is disabled by default and runs only when a deployment explicitly executes scheduled, bounded cohort refresh (or operator-triggered bulk refresh) with Epic-granted bulk line-items and institutional approval (see §00 and §02D). This is how Bulk is intended to be used for population-level evaluation, not opportunistic per-request chart access.

FhirBulkExporter (connectors/fhir_bulk.py) implements kick-off, async status polling with explicit job lifecycle bounds (max_poll_attempts × poll_interval_sec), and gzip-aware file download, not Bulk Data Delete. Optional _type narrows exported types when supplied; when omitted, NDJSON may include resource types beyond §03. Ingest passes through fhir_bundle_to_normalized per §02D. Non-mapped resources are not persisted in normalized storage and are not included in downstream evaluation outputs.

Patient.$match (EpicFhirClient.patient_match): out of default submission scope. Omit from Epic line-item selection unless the site explicitly enables external-list or cross-system identity workflows that call this operation; it is not part of fetch_patient_bundle cohort screening.

Initial Epic registration and production go-live do not request FHIR write scopes. Eligibility screening, evidence display, and audit replay operate entirely on reads plus application database state. The product codebase retains optional POST helpers (e.g. Observation create, Subscription create) for rare site-specific workflows; those paths are hard-disabled unless multiple environment attestations are set, and are out of scope for the first hospital deployment package.

The following may appear on an Epic scope worksheet for anticipated workflows. They are not part of the default patient bundle fetch today. Enable retrieval only when the protocol engine and site authorization require it.

Eligibility execution is the deterministic engine on normalized FHIR facts already ingested into the trial boundary, consistent with §00. External assistance and protocol text never sit on that hot path (see below).

Representative examples for security / App Orchard review only. Dummy or truncated values; production YAML, keys, CIDRs, and log schemas are environment-specific. Not a substitute for your tenant's live config. Canonical live JWKS: jwks-prod.json / jwks-nonprod.json.

Two questions decide whether a clinical-trial eligibility decision survives audit. (1) Run the same screen again — do you get the same answer? (2) Show the specific evidence behind PASS / REVIEW / FAIL.

Stacks that put a generative model on the patient-screening hot path do not answer either question by construction. Stochastic decoding produces output variance even with identical inputs; a free-text rationale is not the same as a pointer to a FHIR Observation with a normalized fact. Pinning a model to greedy decoding does not make the rationale traceable; it just makes the variance smaller.

That gap is not cosmetic. It is the difference between a screening decision a coordinator can sign off on, and one a sponsor or IRB pulls at audit because it cannot be reconstructed.

The Damaros eligibility evaluation engine is non-stochastic on patient-identifiable data in the screening execution path (see Documentation §00). For any patient × criterion pair, the outcome class and its rationale are fully determined by four pinned inputs:

Same four inputs ⇒ same criterion outcome class (PASS / REVIEW / FAIL) ⇒ same structured rationale ⇒ same evidence references. This is the invariant the engine is built to enforce, not a property of any particular run.

A screening run identifier is not an opaque random UUID minted at execution start. It is a content-addressable identifier derived from the canonical fingerprint of the four pinned inputs above. Two evaluations with identical inputs collapse to the same run.

The practical consequence: if nothing has moved, "screen this cohort again" is a record lookup, not a re-execution. The hospital does not pay an Epic API tax to reproduce a decision the coordinator already saw, and the audit trail does not accumulate spurious near-duplicate runs that have to be diffed later.

If any pinned input moves — a protocol amendment lands, a cohort refresh promotes new patients, a lab result normalizes, the evaluation timestamp advances — the run identifier changes. Old runs remain immutable; the new run is a separately addressable record. There is no in-place mutation of a prior decision, even when the underlying facts have evolved.

Replay against an existing run is idempotent: it returns the same outputs as the original run, with the same criterion-level rationale and the same evidence references. Replay does not re-fetch FHIR; it re-executes the versioned protocol logic against the pinned, already-normalized evidence. Epic is not in the replay path.

Replay against a different reference run is a structured comparison. The engine classifies agreement, divergence, or new criterion outcomes, and the run lineage shows which of the four pinned inputs moved (see Documentation §05: "Replay classifies agreement or divergence; no opaque 'model decided' eligibility."). Divergence is always attributable to a named delta on a named input.

Each (patient × criterion) pair is recorded as its own audit unit (see Documentation §05). The engine never collapses to a single eligibility flag with a generative explanation appended.

This is the unit a sponsor or IRB reviewer asks for: "Show me criterion 4.2.1 for this patient on this run." The answer is a deterministic record with sources, not a regenerated narrative.

"Replayability" is the operational form of the long-standing FDA expectation that decisions affecting clinical-trial conduct be reconstructable. Academic medical centers translate this to a concrete question at audit: "With the protocol that was in force on the screen date, against the cohort and evidence as they stood, do we get the same set of eligible patients?"

A deterministic engine answers this in O(1) on stored runs. A generative engine cannot, because identical inputs are not guaranteed to map to identical outputs — that is a property of how generative decoding works, not a tunable.

For hospital IT the question is narrower and harder: "Can we produce, at audit, a bit-identical reconstruction of the decision the coordinator acted on?" Damaros answers yes by construction. The engine semantics in §01–§04 are the property; the rest of the integration documentation is the implementation.

Determinism is an architectural property. It has to be enforced from the protocol-compile step through normalization to evaluation, and it has to hold for every patient × criterion pair, not just the ones a reviewer happens to spot-check.

A generative model on the screening hot path has two doors. (a) Tolerate output variance — replay is best-effort, the audit gap above stands, and the model is one upstream change away from re-deciding screens that have already been signed. (b) Pin the model to deterministic decoding plus a templated formatter — at which point the "rationale" is no longer the model's reasoning; it is a deterministic transform of structured inputs. Damaros built the deterministic transform natively, without the model on the hot path.

Damaros uses generative assistance only outside the screening execution path, on non-PHI protocol or synopsis text, behind deployment flags and pattern guards (see Documentation §04). The screening verdict is deterministic; the optional protocol-comprehension layer is clearly separated and never carries patient identifiers.