ACME Pharma: A Complete Worked Example

Figures, tables and listings

14 code listings

Reproduced in full, in the order they appear in the published chapter. The reasoning that connects them is in the book.

apiVersion: ea.codex/v1
kind: EnterpriseIntent
metadata:
  id: INTENT-ACME-INTEGRATED-001
  name: acme-pharma-regulated-digital-backbone
  domain: enterprise
  status: approved
  version: "1.0"
  owners:
    enterpriseArchitect: ea.enterprise@acmepharma.eu
    chiefMedicalOfficer: cmo@acmepharma.eu
    chiefDigitalOfficer: cdo@acmepharma.eu
spec:
  outcome: >
    Operate ACME Pharma as a regulated digital backbone that carries
    evidence, product, and control data without semantic loss across
    clinical development, regulatory product registration, quality and
    manufacturing oversight, supply continuity, and pharmacovigilance,
    while keeping AI assistance within explicit permission envelopes
    that preserve human medical and regulated decision authority.
  affectedCapabilities:
    - ClinicalStudyDesignAndStartup
    - RegulatoryProductRegistration
    - QualityAndManufacturingOversight
    - SupplyContinuity
    - AdverseEventIntake
    - SafetyCaseNormalization
    - HumanMedicalReview
    - RegulatorySubmissionPreparation
  childIntents:
    - INTENT-PV-001                # Pharmacovigilance intake (worked in depth)
  openDecisionBacklog:
    - choose-clinical-study-identity-authority
    - choose-regulatory-product-master-authority
    - bind-cdmo-batch-event-schema-version
    - select-serialization-partner-onboarding-pattern
    - bind-ai-runtime-permission-envelope-by-domain
  constraints:
    - regulated-state-must-live-in-validated-systems-of-record
    - ai-may-extract-classify-summarize-route-but-not-finalize-regulated-decision
    - partner-boundaries-are-architectural-boundaries-not-only-contractual
    - master-data-is-issued-once-by-the-named-authority

Figure 15.1: Parent enterprise intent.

apiVersion: ea.codex/v1
kind: EnterpriseIntent
metadata:
  id: INTENT-PV-001
  name: ai-assisted-pharmacovigilance-intake
  domain: pharmacovigilance
  status: approved
  version: "1.0"
  owners:
    enterpriseArchitect: ea.pharmacovigilance@acmepharma.eu
    chiefMedicalOfficer: cmo@acmepharma.eu
    pharmacovigilanceLead: pv.lead@acmepharma.eu
spec:
  outcome: >
    Accelerate adverse-event intake across all regions and intake channels
    using AI-assisted extraction and triage, while preserving regulatory
    traceability, human medical review, and authoritative case management
    in the validated pharmacovigilance platform.
  value: >
    Reporting volume is rising and intake latency directly affects
    regulatory reporting timeliness. Manual extraction across heterogeneous
    intake channels is the dominant bottleneck. AI-assisted extraction and
    triage are now operationally feasible at the quality required, provided
    the AI layer is bounded by an explicit permission envelope and bound
    to the validated case-management surface as the system of record.
  successMeasures:
    - name: average-intake-processing-time
      target: "<= 8 hours"
      measurementMethod: "median across intake channels in pilot window; baseline 48 hours"
    - name: serious-event-recall
      target: ">= 1.0"
      measurementMethod: "per FDA 21 CFR 314.80 and EMA GVP Module VI"
    - name: extraction-accuracy-on-patient-reference-and-product-name
      target: ">= 0.95"
      measurementMethod: "per ICH E2A; weekly ScenarioPack validation run"
    - name: persistent-regulated-state-outside-app-pv
      target: "0 instances"
      measurementMethod: "structurally enforced via gateway and policy"
  constraints:
    - app-pv-must-remain-authoritative-system-of-record
    - ai-may-extract-classify-summarize-route-but-not-finalize-regulated-decision
    - patient-identifying-information-must-not-persist-in-ai-runtime-memory
    - regional-intake-workflows-may-localize-but-may-not-hold-case-authority
  affectedCapabilities:
    - AdverseEventIntake
    - SafetyCaseNormalization
    - HumanMedicalReview
    - RegulatorySubmissionPreparation
  decisionObligations:
    - choose-system-of-record-and-action-boundary
    - bind-ai-extraction-and-triage-to-permission-envelope
    - select-regional-variant-architecture-within-bounded-product-line
  stakeholders:
    - global-pharmacovigilance-operations
    - quality-and-regulatory
    - data-protection-office
    - enterprise-architecture-council

Figure 15.2: Intent record for the pharmacovigilance intake capability.

apiVersion: ea.codex/v1
kind: DecisionRecord
metadata:
  id: DEC-PV-001
  title: Pharmacovigilance platform as adverse-event system of record
  status: accepted
  date: "2026-02-15"
  owner: enterprise-architecture-council
spec:
  trigger:
    type: internal-strategic
    source: INTENT-PV-001
  context: >
    INTENT-PV-001 introduces the architectural concern of AI-assisted
    adverse-event intake across multiple channels and regions. Without an
    explicit authority decision, adverse-event case state may be fragmented
    across the customer interaction platform, AI services, regional
    workflow tools, and document processing components. This decision
    closes the data-authority question before further design proceeds.
  decision: >
    The pharmacovigilance platform is the authoritative system of record
    for all suspected adverse-event cases. The customer interaction
    platform, regional workflow tools, document processing services, and
    AI agents may assist intake, routing, extraction, and summarization,
    but must not create persistent adverse-event case records outside the
    pharmacovigilance platform.
  rationale: >
    Regulatory traceability requires a single authoritative case record
    from the point at which a suspected adverse event is identified.
    AI-assisted intake and regional workflow coordination are acceptable
    only if they remain subordinate to validated pharmacovigilance case
    management. Fragmenting case authority is the failure mode that this
    decision is designed to prevent.
  rejectedAlternatives:
    - option: Customer interaction platform as temporary case repository
      reason: >
        The customer interaction platform is an intake channel, not a
        validated pharmacovigilance case system. Allowing it to hold even
        provisional case state breaks the single-authority invariant.
    - option: Regional workflow tools as local suspected-case stores
      reason: >
        This would create fragmented case authority and inconsistent
        auditability across regions.
    - option: AI Triage Service holding provisional case state
      reason: >
        This would give the AI layer persistent regulated case state
        without validated case-management controls.
  consequences:
    - AI agents may extract evidence and suggest triage, but may not
      create case records.
    - Regional workflow tools may manage work queues, but may not hold
      case authority.
    - Intake evidence must be linked to the authoritative case identifier
      before it is used in triage or human review.
    - Regulated case decisions must be approved by authorized
      pharmacovigilance reviewers.
  reviewTriggers:
    - Regional regulation prevents centralized case registration.
    - A new validated pharmacovigilance platform is introduced.
    - Repeated intake delays show that the current system-of-record
      boundary is too restrictive.
    - AI triage becomes part of a validated operating procedure.

Figure 15.3: Decision record DEC-PV-001 fixing the system-of-record boundary.

apiVersion: ea.codex/v1
kind: DecisionRecord
metadata:
  id: DEC-PV-002
  title: AI agent action boundary for adverse-event intake
  status: accepted
  date: "2026-02-15"
  owner: enterprise-architecture-council
spec:
  trigger:
    type: internal-strategic
    source: INTENT-PV-001
  context: >
    The AI Triage Service operates in a regulated context. The architecture
    has to draw an explicit line between actions the agent may take and
    actions it may not, and the line must be enforced at the gateway
    rather than in the agent's own logic.
  decision: >
    The AI Triage Service may perform extraction, triage suggestion,
    summarization, and routing for human review. It may not perform any
    action that finalizes a regulated decision. Permitted and prohibited
    actions are enumerated in the ArchitecturePackage and enforced
    by a Rego policy at the runtime gateway.
  rationale: >
    Drawing the boundary in the gateway rather than in the agent makes the
    boundary independent of the agent's specific implementation, model
    version, or prompt. A boundary enforced only inside the agent is a
    boundary that lasts only until the next prompt change.
  consequences:
    - Permitted and prohibited actions are explicitly listed in
      AP-PV-001 and reproduced as Rego rules.
    - The runtime gateway evaluates every tool call against the policy
      before execution.
    - Any prohibited action attempt produces a blocked-action audit event
      that flows back into the architecture function as a feedback signal.
  reviewTriggers:
    - A new permitted action is proposed.
    - The blocked-action rate exceeds the agreed threshold over a
      sustained window.
    - A model or prompt change introduces actions outside the documented
      vocabulary.
apiVersion: ea.codex/v1
kind: DecisionRecord
metadata:
  id: DEC-PV-003
  title: Patient-identifying information retention in the AI layer
  status: accepted
  date: "2026-02-15"
  owner: enterprise-architecture-council
spec:
  trigger:
    type: internal-strategic
    source: INTENT-PV-001
  context: >
    Patient-identifying information processed by the AI layer during
    extraction and triage must be subject to an explicit retention
    boundary. The default for AI runtime systems is to retain inputs and
    embeddings for performance and observability purposes. That default is
    incompatible with patient data minimization expectations.
  decision: >
    Patient-identifying information must not persist in AI runtime memory,
    embedding stores, prompt caches, or observability logs beyond the
    duration of a single intake. Persistence beyond that point is
    permitted only in approved validated stores with explicit retention
    windows defined in the relevant data product contract.
  consequences:
    - The AI Triage Service must run with redaction at intake and
      eviction at end-of-session.
    - Observability and tracing systems must redact patient-identifying
      fields before storage.
    - The runtime gateway must reject any tool call that would persist
      patient-identifying fields outside an approved validated store.
  reviewTriggers:
    - Regulatory revision tightens or relaxes minimization expectations.
    - A new analytics use case proposes retention beyond the single-intake
      window.

Figure 15.4: Decisions DEC-PV-002 and DEC-PV-003 extending the AI action and patient-data retention boundaries.

apiVersion: ea.codex/v1
kind: ArchitecturePackage
id: AP-PV-001
name: ai-assisted-adverse-event-intake
title: AI-assisted Adverse-Event Intake Architecture Package
domain: Pharmacovigilance
status: approved-with-controls
version: "1.0"
owners:
  enterpriseArchitect: ea.pharmacovigilance@acmepharma.eu
  capabilityOwner: pv.operations@acmepharma.eu
brief:
  intent:
    outcome: >
      Deliver AI-assisted extraction and triage of adverse-event reports
      across regions while preserving regulatory traceability, human
      medical review, and authoritative case management in APP-PV.
    value: >
      Reduce intake processing time and reviewer cognitive load while
      preserving the inspection-readiness posture the enterprise depends on.
  capabilityScope:
    - AdverseEventIntake
    - SafetyCaseNormalization
    - HumanMedicalReview
    - RegulatorySubmissionPreparation
  decisionObligations:
    - choose-system-of-record-and-action-boundary
    - bind-ai-runtime-to-permission-envelope
    - select-regional-variant-within-product-line
map:
  familyBinding:
    productLine: PLS-ACME-PV-INTAKE-001
    variant: EU-Pilot-V1
    permittedVariationPoints:
      - intake_channel
      - language_pipeline
      - regulatory_adapter
      - regional_workflow_surface
      - agent_runtime_region
    forbiddenVariationPoints:
      - case-state-machine
      - audit-event-schema
      - human-review-gate-on-regulated-decisions
      - system-of-record-boundary
  designDecisions:
    - id: DEC-PV-001
      topic: pv-platform-as-system-of-record
      option: app-pv-as-only-authoritative-store
      rationale: >
        Authoritative case state lives only in the validated PV platform;
        no other store may persist regulated state.
    - id: DEC-PV-002
      topic: ai-action-boundary
      option: extraction-and-triage-only
      rationale: >
        AI may extract, classify, summarize, and route; AI may not finalize
        a regulated decision. Boundary enforced by gateway and contract.
    - id: DEC-PV-003
      topic: patient-identifier-handling
      option: tokenize-before-model-invocation
      rationale: >
        Patient identifiers are tokenized before any model call; AI runtime
        memory contains tokens only.
  referencedKinds:
    - BusinessObject:BO-PV-ADVERSE-EVENT-CASE
    - DataProductContract:DP-PV-TRIAGE-OUTPUT-V1
    - DataProductContract:DP-PV-CASE-LOG-V3
    - AgentContract:SPEC-AGENT-PV-TRIAGE-001
    - AgentInteractionContract:AIC-PV-001
    - SovereigntySpecification:ACP-SOV-PV-001
act:
  codexAssets:
    - template: pv-ai-triage-service-template
    - policy: REGO-PV-EVIDENCE-AND-REDACTION
    - policy: REGO-SAP-API-POLICY
    - pipeline: pv-intake-ci.yaml
    - runtime: validated-pv-runtime-profile
doubleCheck:
  fitnessFunctionRefs:
    - FF-SAP-001
    - FF-SAP-002
    - FF-PV-HUMAN-REVIEW-001
    - FF-PV-PHI-MINIMIZATION-001
  scenarioPackRef: SCN-ACME-PV-INTAKE-V1
  expectedEvidenceType: EvidenceRecord
  approvalConditions:
    - all-blocking-scenarios-pass
    - policy-check-passes
    - named-pv-qc-role-signature-required
    - no-forbidden-autonomy-events

Figure 15.5: ArchitecturePackage AP-PV-001, the canonical v1.1.0 BMAD-shaped artifact for the AI-assisted adverse-event intake architecture.

apiVersion: ea.codex/v1
kind: AgentContract
metadata:
  id: SPEC-AGENT-PV-TRIAGE-001
  name: pv-ai-triage-service
  title: AI Triage Service AgentContract
  domain: pharmacovigilance
  status: approved-with-controls
  version: "1.0"
  owners:
    enterpriseArchitect: ea.pharmacovigilance@acmepharma.eu
    pharmacovigilanceAiGovernance: pv.ai.gov@acmepharma.eu
spec:
  intent:
    capability: AdverseEventTriage
    objective: >
      Receive raw adverse-event reports from heterogeneous intake channels,
      extract structured facts with verifiable source-document references,
      suggest a triage priority within ICH E2D timing, and route every
      candidate for qualified human review before regulated case creation.
    delegationLevel: L2
    serviceBoundaries:
      allowed:
        - extract structured fields from intake documents
        - suggest a triage priority with confidence
        - route candidates to expedited or routine reviewer queues
        - emit summary suggestion for human approval
      forbidden:
        - finalize seriousness classification
        - finalize causality assessment
        - finalize regulatory reportability
        - persist case state outside APP-PV
        - retain unredacted patient identifiers in agent runtime memory
        - bypass the SAP Published API gateway
  semanticModel:
    entities:
      - AdverseEventCase
      - Product
      - Reporter
      - SeriousnessClassification
      - CausalityAssessment
    references:
      businessObjects:
        - BO-PV-ADVERSE-EVENT-CASE
      capabilityRefs:
        - eatool:bc.pv.adverse-event-intake
  dataSources:
    - name: SAP Adverse Event Inbox
      system:
        vendor: SAP
        product: S/4HANA (safety module)
      accessMechanism: published-api
      apiEndpoint: api.sap.com/safety/v2/adverse-events
      complianceRefs: [DEC-SAP-API-001]
    - name: Email and Portal Intake
      system:
        vendor: ACME
        product: pv-intake-portal
      accessMechanism: internal-api
  designDecisions:
    decisionPack: AP-PV-001
  controls:
    intake:
      - source-system-allowlist
      - schema-validation-on-ingest
    design:
      - prin-ai-005-human-in-loop
      - prin-int-002-sap-approved-data-access
      - prin-data-007-phi-minimization
    delivery:
      - golden-set-evaluation
      - shadow-deployment-period
      - blocking-gate-on-extraction-accuracy
      - blocking-gate-on-serious-event-recall
    runtime:
      - per-case-confidence-floor
      - clinical-reviewer-routing-on-low-confidence
      - patient-identifier-tokenization-before-model-call
      - audit-trail-on-every-suggestion
    humanReview:
      requiredBefore:
        - any-seriousness-classification-finalization
        - any-case-validity-confirmation
        - any-regulatory-reporting-readiness-assertion
  evaluation:
    scenarioPackRef: SCN-ACME-PV-INTAKE-V1
    blockingGates:
      - extraction-accuracy-patient-reference
      - extraction-accuracy-seriousness-indicator
      - serious-event-recall
    regressionPolicy:
      maxAllowedDegradation:
        triage-priority-agreement: 0.02
        extraction-accuracy-product-name: 0.01
    evidenceItems:
      - SCN-ACME-PV-INTAKE-V1#SCN-PV-001-03
  feedback:
    evaluateOn:
      - extractionAccuracy
      - triagePriorityAgreement
      - seriousEventRecall
      - aiOverrideRate
      - blockedActionCount
      - intakeLatencyP50
    cadence: weekly
    revisionTriggers:
      - sustained metric breach
      - regulatory revision
      - introduction of new intake channel
  governance:
    designAuthorityBodyRef: PV-AI-GOV-BOARD-001
    governanceRole: evaluator
    delegationLevelsHandled: [L1, L2]
    skills:
      - id: skill.extract-intake-evidence
        level: L2
        skillType: assessment
        description: >
          Extract adverse-event facts from a single intake source document
          and bind them to canonical pharmacovigilance entities.
      - id: skill.suggest-triage-priority
        level: L2
        skillType: assessment
        description: >
          Suggest triage priority on the four-point scale with confidence
          and rationale, conditioned on extracted evidence.

Figure 15.6: AgentContract for the AI Triage Service (canonical v1.1.0 shape).

package pv.runtime.gateway
# Default to deny.
default allow := false
# Allow only if the proposed action is in the contract's permitted tool set
# and the input meets all guardrails.
permitted_action(action) if {
    some tool in data.contract.tools.permitted
    action == tool.id
}
allow if {
    permitted_action(input.action)
    not action_prohibited
    input_guardrails_ok
    output_rules_satisfiable
}
action_prohibited if {
    some prohibited in data.contract.tools.prohibited
    input.action == prohibited.id
}
action_prohibited if {
    # Closed-world enforcement: any action not permitted is denied.
    not permitted_action(input.action)
}
input_guardrails_ok if {
    input.payload.sourceDocumentRef != ""
    input.payload.purposeBinding != ""
}
output_rules_satisfiable if {
    # Every extracted fact must carry source URI and offset.
    every fact in input.payload.extractedFacts {
        fact.sourceDocumentURI != ""
        fact.sourceDocumentOffset != ""
    }
}
# Patient identifier retention boundary.
deny[reason] if {
    input.action in {"persist-to-vector-store", "write-to-cache",
                     "write-to-observability-log"}
    # Helper supplied by the patient-data inspection policy library.
    contains_patient_identifier(input.payload)
    not input.payload.target.isApprovedValidatedStore
    reason := sprintf("RULE-PV-005 violation: %v on %v",
                      [input.action, input.payload.target.name])
}
# System-of-record boundary.
deny[reason] if {
    input.action == "write"
    input.payload.target.kind == "AdverseEventCase"
    not input.payload.target.application == "APP-PV"
    reason := sprintf("RULE-PV-001 violation: write to %v outside system of record",
                      [input.payload.target.application])
}
# Regulated-decision boundary.
deny[reason] if {
    input.action in {"approve-seriousness", "confirm-case-validity",
                     "close-case", "update-regulatory-reporting-status"}
    input.actor.kind == "AI"
    reason := sprintf("RULE-PV-002 violation: AI actor attempted %v",
                      [input.action])
}
# SAP egress pattern compliance.
deny[reason] if {
    input.action == "fetch"
    input.payload.target.system.vendor == "SAP"
    not input.payload.target.accessMechanism in
        {"published-api", "bdc", "cds-view-extraction",
         "slt", "data-services", "exception"}
    reason := sprintf("DEC-SAP-API-001 violation: non-compliant SAP access mechanism %v",
                      [input.payload.target.accessMechanism])
}

Figure 15.7: Rego policy enforcing the AI action boundary at the runtime gateway.

apiVersion: ea.codex/v1
kind: AgentInteractionContract
metadata:
  id: AIC-PV-001
  name: triage-to-case-quality-handoff
  domain: pharmacovigilance
  status: approved-with-controls
  version: "1.0"
  owners:
    enterpriseArchitect: ea.pharmacovigilance@acmepharma.eu
    pharmacovigilanceAiGovernance: pv.ai.gov@acmepharma.eu
spec:
  sourceAgent:
    agentContractRef: SPEC-AGENT-PV-TRIAGE-001
    role: emitter
    identity:
      verificationMethod: signed-agent-card
      trustAnchor: acme-internal-root-ca
  targetAgent:
    agentContractRef: SPEC-AGENT-PV-CASE-QUALITY-001
    role: receiver
    identity:
      verificationMethod: signed-agent-card
      trustAnchor: acme-internal-root-ca
  protocol:
    name: A2A
    version: "1.0"
    transport: https-mutual-tls
  purpose: >
    Hand off triaged adverse-event candidates to the case quality review
    agent for completeness validation before pharmacovigilance case
    creation.
  capabilityRef: eatool:bc.pv.adverse-event-intake
  messageControls:
    - purpose-bound-message
    - data-minimization
    - patient-identifier-redaction
    - source-document-reference-required
    - model-and-prompt-version-attribution
    - signed-message-on-every-exchange
    - jurisdiction-aware-routing
  exchangeRules:
    permittedMessageTypes:
      - triaged-adverse-event-candidate
      - completeness-feedback-request
      - completeness-feedback-response
    prohibitedMessageTypes:
      - patient-identifying-information-without-redaction-marker
      - regulated-decision-finalization
    payloadConstraints:
      - all-patient-identifiers-must-be-tokenized-or-redacted
      - source-document-references-required
      - model-and-prompt-version-required
  autonomyBoundary:
    autonomousActions:
      - exchange-of-permitted-message-types
      - completeness-flag-with-reason-code
    escalationTriggers:
      - case-quality-review-flags-incompleteness-twice-on-same-intake
      - patient-identifier-appears-unredacted-in-payload
      - source-document-reference-missing
    terminationConditions:
      - reviewer-takes-over-the-intake
      - escalation-trigger-fired
      - retry-budget-exhausted
  evidence:
    obligations:
      - signed-message-on-every-exchange
      - audit-trail-entry-for-every-handoff
    storage: pharmacovigilance-case-log
  governance:
    primaryAuthority: pharmacovigilance-ai-governance-board
    reviewCadence: monthly

Figure 15.8: AgentInteractionContract between AI Triage and Case Quality Review services (canonical v1.1.0 shape).

apiVersion: ea.codex/v1
kind: DataProductContract
metadata:
  id: DP-PV-TRIAGE-OUTPUT-V1
  name: pv-triaged-adverse-event-candidate
  title: Triaged adverse-event candidate data product
  domain: pharmacovigilance
  status: approved
  version: "1.0"
  owners:
    enterpriseArchitect: ea.pharmacovigilance@acmepharma.eu
    dataProductOwner: pv.data.product@acmepharma.eu
spec:
  businessObject: BO-PV-ADVERSE-EVENT-CASE
  owner:
    role: pharmacovigilance-ai-governance
    contact: pv.ai.gov@acmepharma.eu
  purposes:
    - case-quality-review-handoff
    - regulated-case-creation-input
    - pv-analytics-on-triaged-candidates
  jurisdiction:
    primary: EU
    additional:
      - US
      - APAC
    residencyRules:
      - eu-data-stays-in-eu-approved-regions
      - us-data-stays-in-us-approved-regions
      - apac-data-mediated-through-eu-with-partner-redaction
  allowedConsumers:
    - APP-CASE-QUALITY
    - APP-PV-INTAKE-ADAPTER
    - pharmacovigilance-analytics-surface
  allowedTransformations:
    - aggregation-by-region-and-product
    - tokenization-of-patient-identifiers
    - schema-projection-for-downstream-consumers
  permittedDerivedOutputs:
    - completeness-feedback-message
    - case-quality-summary
  requiredProofs:
    - patient-identifier-tokenization
    - source-document-reference-completeness
    - model-and-prompt-version-attribution
    - audit-trail-on-every-emit
  qualityAttributes:
    freshness:
      target: "< 30 seconds from intake completion"
    availability:
      target: "99.9%"
    completeness:
      target: ">= 99.5% over rolling 24h window"
      enforcedBy: soda-core
    schemaValidity:
      target: "100%"
      enforcedBy: schema-registry
  interfaces:
    - pattern: event-stream
      transport: kafka-mtls
      schemaRef: schemas/pv-triaged-candidate-v1.avsc
    - pattern: governed-api
      transport: graphql-readonly
      schemaRef: schemas/pv-triaged-candidate-query-v1.graphql

Figure 15.9: DataProductContract for triaged adverse-event candidates (canonical v1.1.0 shape; realizes BO-PV-ADVERSE-EVENT-CASE).

apiVersion: ea.codex/v1
kind: DecisionRecord
metadata:
  id: DEC-SAP-API-001
  title: SAP API Policy Compliance for SAP-Bound Pharmacovigilance Integrations
  status: accepted
  date: "2026-04-28"
  owner: enterprise-architecture-council
spec:
  trigger:
    type: external-vendor-policy
    source: SAP API Policy (April 2026)
  context: >
    SAP issued a formal API Policy in April 2026, restricting use to SAP
    Published APIs (api.sap.com) and SAP-endorsed mechanisms used only for
    their documented purposes. The AI Triage Service ingests adverse-event
    signals from a SAP-backed safety inbox, which places it in scope.
  decision: >
    All AI Triage Service integrations that read from or write to a SAP
    system of record MUST use one of:
      (a) an API published on api.sap.com, used for its documented purpose
      (b) SAP Business Data Cloud sharing for analytics or AI consumption
      (c) an SAP-delivered extraction mechanism (CDS view marked for
          extraction, SLT, Data Services) for the use case SAP documents.
    Direct RFC or BAPI calls from third-party tools, ODP-via-RFC, and any
    function-module use outside its documented purpose are NON-COMPLIANT
    and require a time-boxed exception with a named risk owner.
  relatedPrinciples:
    - INT-002        # SAP-Approved Data Access
    - DAT-002        # Vendor Policy Compliance
    - AI-008         # Tool / MCP Governance
  relatedStandards:
    - STD-SAP-INT-001
  relatedSpecs:
    - SPEC-AGENT-PV-TRIAGE-001
  affectedFactSheetTypes:
    - Application
    - Interface
    - DataObject
    - AgentContract
  doubleCheck:
    fitnessFunctions:
      - id: FF-SAP-001
        rule: |
          AgentContract.dataSources[].system.vendor == "SAP"
            => accessMechanism in {published-api, bdc, cds-view-extraction,
                                   slt, data-services, exception}
        check: OPA / Rego policy in CI
      - id: FF-SAP-002
        rule: DecisionRecord.exceptions[*].sunsetDate <= today + 12 months
        check: GitHub Actions weekly scan

Figure 15.10: Decision record DEC-SAP-API-001 capturing the SAP API Policy as a typed delta.

# In SPEC-AGENT-PV-TRIAGE-001 (AgentContract)
# BEFORE
spec:
  dataSources:
    - name: SAP Adverse Event Inbox
      system: SAP S/4HANA (safety module)
      # accessMechanism not specified
# AFTER (delta introduced by DEC-SAP-API-001)
spec:
  dataSources:
    - name: SAP Adverse Event Inbox
      system:
        vendor: SAP
        product: S/4HANA (safety module)
      accessMechanism: published-api
      apiEndpoint: api.sap.com/safety/v2/adverse-events
      complianceRefs: [DEC-SAP-API-001]
  evaluation:
    evidenceItems:
      - EVAL-PV-001#sap-egress-pattern-compliant
  roadmap:
    additions:
      - milestone: Validate SAP egress pattern compliance
        before: go-live
        ref: ROADMAP-AIAGENT-PV-001

Figure 15.11: AgentContract delta applied after DEC-SAP-API-001.

apiVersion: ea.codex/v1
kind: ArchitecturePackage
id: AP-REGULATORY-PRODUCT-FAMILY-001
name: regulatory-product-family-template
title: Regulatory Product Family ArchitecturePackage
domain: RegulatoryAffairs
status: approved-with-controls
version: "1.0"
owners:
  enterpriseArchitect: ea.regulatory@acmepharma.eu
  capabilityOwner: regulatory.operations@acmepharma.eu
brief:
  intent:
    outcome: >
      Deliver jurisdiction extensions, serialization partner onboardings,
      and submission assemblies for marketed and pipeline products
      without re-deciding the structural questions for each instance.
    value: >
      Industrialize bounded regulatory work so the architecture function
      governs the family once and bounded variants are realized through
      delegated ArchitectureChangePackets.
  capabilityScope:
    - RegulatoryProductRegistration
    - LabelingArtifactProduction
    - SerializationPartnerIntegration
    - SubmissionAssembly
map:
  familyBinding:
    productLine: PLS-ACME-REGULATORY-PRODUCT-001
    variant: family-template
    permittedVariationPoints:
      - jurisdiction_specific_labeling
      - country_regulatory_document_set
      - serialization_partner_event_schema
      - jurisdictional_submission_format_adapter
      - language_pipeline
    forbiddenVariationPoints:
      - medicinal-product-identity
      - substance-identity
      - canonical-batch-lineage
      - regulated-decision-authority
  designDecisions:
    - id: DEC-REG-PRODUCT-AUTHORITY-001
      topic: regulatory-product-authority
      option: regulatory-hub-as-only-master
    - id: DEC-REG-PARTNER-ONBOARDING-001
      topic: serialization-partner-onboarding
      option: schema-version-pinned-with-validation-gate
    - id: DEC-SAP-API-001
      topic: sap-api-policy-compliance
      option: published-api-or-endorsed-mechanism-only
act:
  codexAssets:
    - template: jurisdiction-extension-template
    - template: serialization-partner-onboarding-template
    - policy: REGO-REG-MEDICINAL-PRODUCT-IDENTITY
    - policy: REGO-REG-PARTNER-EVENT-SCHEMA
    - pipeline: regulatory-product-ci.yaml
doubleCheck:
  fitnessFunctionRefs:
    - FF-REG-MEDICINAL-PRODUCT-IDENTITY-001
    - FF-REG-PARTNER-EVENT-SCHEMA-001
    - FF-SAP-001
    - FF-SAP-002
  scenarioPackRef: SCN-REG-JURIS-EXTENSION-V1
  expectedEvidenceType: EvidenceRecord
  approvalConditions:
    - all-blocking-scenarios-pass
    - all-hidden-holdout-scenarios-pass
    - policy-check-passes
    - named-regulatory-affairs-role-signature-required

Figure 15.12: AP-REGULATORY-PRODUCT-FAMILY-001, the family-level ArchitecturePackage that templates every regulatory product instance.

apiVersion: ea.codex/v1
kind: ArchitectureChangePacket
metadata:
  id: ACP-REG-JURIS-EU-OCEAN-001
  name: jurisdiction-extension-eu-ocean
  title: Jurisdiction extension for a new EU-adjacent jurisdiction
  domain: RegulatoryAffairs
  status: in-execution
  version: "1.0"
  date: "2026-04-12"
  owner: regulatory-architecture-team
spec:
  parentPackage: AP-REGULATORY-PRODUCT-FAMILY-001
  parentProductLine: PLS-ACME-REGULATORY-PRODUCT-001
  workType: jurisdiction-extension
  scope:
    boundedWork: >
      Register the jurisdiction-specific medicinal product variant for
      one marketed oncology asset in one new EU-adjacent jurisdiction,
      generate the country labeling artifact, attach the serialization
      partner profile, and assemble the initial submission dossier.
  delegation:
    designAuthorityBodyRef: REG-ARCH-COUNCIL-001
    delegationPolicyRef: DELEG-REG-FAMILY-001
    delegationLevel: L2
    approvalPolicy:
      autoProgressUntil: submission-dossier-assembled
      humanApprovalRequiredFor:
        - first-jurisdictional-label-release
        - regulated-submission-filing
        - any-holdout-scenario-failure
  inheritedDecisions:
    - DEC-REG-PRODUCT-AUTHORITY-001
    - DEC-REG-PARTNER-ONBOARDING-001
    - DEC-SAP-API-001
  variationPointBindings:
    jurisdiction_specific_labeling: eu-ocean-labeling-profile-v1
    country_regulatory_document_set: eu-ocean-document-set-v1
    serialization_partner_event_schema: partner-X-event-schema-v2
    jurisdictional_submission_format_adapter: eu-ocean-submission-adapter-v1
  doubleCheck:
    scenarioPackRef: SCN-REG-JURIS-EXTENSION-V1
    fitnessFunctionRefs:
      - FF-REG-MEDICINAL-PRODUCT-IDENTITY-001
      - FF-REG-PARTNER-EVENT-SCHEMA-001
      - FF-SAP-001
    expectedEvidenceRecord: EVD-REG-JURIS-EU-OCEAN-001
  evidence:
    obligations:
      - blocking-scenario-pass-report
      - hidden-holdout-pass-report
      - policy-check-report
      - human-approval-records-for-required-steps
    storage: regulatory-evidence-vault

Figure 15.13: ACP-REG-JURIS-EU-OCEAN-001, one bounded jurisdiction-extension packet instantiating the family template.

apiVersion: ea.codex/v1
kind: EvidenceRecord
metadata:
  id: EVD-REG-JURIS-EU-OCEAN-001
  status: produced
  date: "2026-04-19"
  domain: regulatory-affairs
spec:
  category: per-execution
  source:
    architectureChangePacket: ACP-REG-JURIS-EU-OCEAN-001
    scenarioPack: SCN-REG-JURIS-EXTENSION-V1
  observations:
    holdoutScenarios:
      - id: HLD-REG-JURIS-001
        outcome: pass
      - id: HLD-REG-JURIS-002
        outcome: fail
        detail: >
          The bound serialization partner declared an event schema
          version that is not on the supported list, and no waiver
          exists. The packet has been paused for human approval.
    fitnessFunctions:
      - id: FF-REG-PARTNER-EVENT-SCHEMA-001
        outcome: fail
  outcome: blocked-pending-amendment
  feedbackUp:
    cadence: per-execution
    aggregatedInto: EVD-REG-PATTERN-2026-Q1

Figure 15.14: EVD-REG-JURIS-EU-OCEAN-001, the per-execution evidence record produced by the packet, with one failed holdout.