QODIQA Reference Implementation
Specification

#Executive Overview

The QODIQA Reference Implementation Specification defines a minimal, self-contained enforcement stack that demonstrates the behavioral properties required by the QODIQA Core Standard. It is not a production deployment blueprint. It is a structured reference: a concrete instantiation of the enforcement model in its simplest correct form, against which production implementations can be calibrated.

The reference stack addresses a specific validation gap. Specifications describe what a system must do; reference implementations demonstrate how those requirements are satisfied in practice. Without a concrete reference, specification conformance is assessed against documentation alone, which is insufficient for systems whose correctness properties must be mechanically verifiable.

This document covers the complete enforcement pipeline from request ingestion to decision artifact generation. Each component is defined with explicit inputs, outputs, responsibilities, and failure behaviors. The enforcement flow is defined step by step with no ambiguous transitions. All failure modes resolve to denial. No component is permitted to infer, assume, or fall back silently.

The scope of this specification is deliberately bounded. It covers runtime consent validation, deterministic policy evaluation, fail-closed enforcement at the inference boundary, and append-only audit logging. It does not cover distributed deployment, high-availability configurations, advanced identity systems, cryptographic proof generation, or full production security controls. These are addressed in companion specifications within the QODIQA corpus.

The reference implementation serves three functions. First, it validates that the QODIQA enforcement model is implementable in a minimal configuration. Second, it provides a concrete behavioral reference for teams building production systems. Third, it enables conformance testing by defining validation scenarios against which any implementation can be assessed.

#System Scope and Constraints

The boundary of this reference implementation is explicitly defined. Conformant behavior is only required within the stated scope. Behaviors outside this scope are not evaluated by this specification and must be addressed by production-specific architecture decisions and companion QODIQA documents.

#Architectural Overview

#Core Components

Each component in the enforcement stack is defined below with its precise responsibility, input contract, output contract, and failure behavior. Components must not exceed their defined responsibilities. Cross-component calls must follow the defined flow sequence specified in Section 5.

#Deterministic Enforcement Flow

The enforcement flow is a linear, sequential pipeline. No step may be skipped, reordered, or parallelized in a manner that allows execution to proceed without a completed prior step. Each step is defined with its preconditions and the failure behavior that applies if the step cannot be completed successfully.

Step 1 — Request Ingestion

The Enforcement Gateway receives the raw inbound request. It validates the structural envelope: required fields present, payload within size bounds, content type declared. Requests that fail structural validation are rejected immediately with DENY and reason code MALFORMED_REQUEST. Conformant requests are passed as structured objects to the Request Validator.

Step 2 — Identity and Context Extraction

The Request Validator extracts and validates the following fields from the structured request: subject identifier (who is acting), declared purpose (why the action is performed), requested scope (what data or capability is targeted), and request timestamp. All fields are mandatory. Any absent or malformed field causes the validator to return a validation failure with the corresponding reason code.

Step 3 — Consent Lookup

The Decision Engine queries the Consent Registry using the composite key: subject identifier, scope identifier, purpose identifier. The registry returns the consent object if a valid, non-expired, scope-matched record exists. Any other response, including absence, expiry, scope mismatch, or registry error, is treated as a denial condition. The Decision Engine does not proceed to policy evaluation if consent is not positively confirmed.

Step 4 — Policy Evaluation

The Policy Engine is invoked with the validated request context and the current policy version identifier. It evaluates all applicable policy rules from the immutable policy snapshot. The result is PERMITTED only if all applicable rules are satisfied. If any rule is not satisfied, if any rule produces an undefined result, or if the policy snapshot cannot be loaded, the result is NOT_PERMITTED.

Step 5 — Decision Synthesis

The Decision Engine synthesizes the final enforcement decision. ALLOW requires: a valid consent object returned from the Consent Registry, and a PERMITTED result from the Policy Engine, and no validation failures from the Request Validator. If any of these conditions is not met, the decision is DENY. The decision record is produced with a complete evaluation trace including all inputs, their resolution, and the final outcome.

Step 6 — Enforcement at Inference Boundary

The Enforcement Gateway applies the decision at the inference boundary. If the decision is ALLOW, the decision artifact is attached to the execution context and inference execution is permitted. If the decision is DENY, inference execution is blocked and the denial reason is returned to the caller. The inference environment must verify the artifact before accepting any execution request.

Step 7 — Logging and Artifact Generation

All enforcement decisions, including denials, are written to the Audit Log before the response is returned to the caller. ALLOW decisions additionally trigger artifact generation. The artifact contains the decision record, consent record identifier, policy version, and evaluation timestamp. If the Audit Log write fails, the Enforcement Gateway returns DENY regardless of the decision outcome.

#Fail-Closed Guarantees

Fail-closed behavior is a core invariant of the QODIQA enforcement model. It is not a configuration option or a default setting. It is a structural property that must hold unconditionally across all operating conditions.

Explicit Denial Conditions

The following conditions must each individually produce DENY with the corresponding reason code:

System Failure Handling

System failures, including process crashes, memory exhaustion, network timeouts between components, and unhandled exceptions, must all resolve to DENY. No component is permitted to swallow exceptions and proceed. No component is permitted to produce an ambiguous or partial result that allows downstream components to interpret the outcome as ALLOW. Every error boundary must terminate the request with DENY.

No Silent Fallback

Silent fallback, defined as any behavior that permits execution to proceed without a positive enforcement decision, is categorically prohibited. This includes: treating an absent consent record as implied consent; applying a default policy when a named policy is unavailable; proceeding with inference when the Audit Log is unavailable; or returning ALLOW when evaluation is incomplete. Any such behavior constitutes a conformance failure.

#Audit and Evidence Model

What Is Logged

Every enforcement event must be logged. The following event types must each produce a log entry:

• Request received by Enforcement Gateway (structural outcome: accepted / rejected)
• Validation result from Request Validator (outcome and reason code)
• Consent lookup result (outcome, consent record identifier if found, reason code if not)
• Policy evaluation result (outcome, policy version, applicable rule identifiers)
• Final decision from Decision Engine (ALLOW or DENY, complete reason chain)
• Audit Log write confirmation or failure
• Artifact generation outcome (for ALLOW decisions)

Log Entry Format

Each log entry must include at minimum: event type identifier; timestamp (ISO 8601, UTC); request identifier; subject identifier; decision outcome; reason code; policy version identifier; consent record identifier (if applicable). Log entries must be structured and machine-parseable. Free-form text fields are prohibited in mandatory fields.

{
  "event_type":        string,      // GATEWAY_RECEIVED | VALIDATION_RESULT | CONSENT_LOOKUP
                                    // POLICY_EVAL | DECISION | ARTIFACT_GENERATED
  "timestamp":         ISO8601/UTC,
  "request_id":        uuid,
  "subject_id":        string,
  "decision":          "ALLOW" | "DENY",
  "reason_code":       string,      // from Denial Condition Registry
  "policy_version":    string,
  "consent_record_id": string | null,
  "artifact_id":       string | null  // present on ALLOW decisions only
}

Immutability Assumptions

In the minimal reference implementation, append-only immutability is implemented by prohibiting any delete, update, or overwrite operation on the log store. Log entries are written sequentially with a monotonically increasing sequence number. In production systems, cryptographic immutability guarantees must be applied; this is specified in the QODIQA Security and Cryptographic Profile.

Evidence Generation Triggers

Decision artifacts are generated only for ALLOW decisions. Artifacts are not generated for DENY decisions; the Audit Log entry for a DENY decision constitutes the full evidence record. Artifact generation is triggered immediately after the Decision Engine issues an ALLOW decision and before the decision is returned to the Enforcement Gateway.

#Minimal Data Model

{
  "consent_id":       uuid,          // unique record identifier
  "subject_id":       string,        // data subject or acting entity identifier
  "scope":            string[],      // list of authorized scope identifiers
  "purpose":          string[],      // list of authorized purpose identifiers
  "granted_at":       ISO8601/UTC,   // timestamp of consent grant
  "expires_at":       ISO8601/UTC,   // hard expiry; null not permitted
  "revoked":          boolean,       // true if consent has been revoked
  "revoked_at":       ISO8601/UTC | null,
  "grantor_id":       string         // identity of consent-granting entity
}

{
  "request_id":     uuid,          // unique request identifier, caller-supplied
  "subject_id":     string,        // identity of the acting entity
  "declared_purpose": string,      // single purpose identifier for this request
  "requested_scope":  string,      // single scope identifier for this request
  "timestamp":      ISO8601/UTC,   // request creation timestamp
  "caller_context": {
    "source_ip":    string | null,
    "agent_id":     string | null   // optional upstream agent identifier
  }
}

{
  "policy_id":      string,        // unique policy identifier
  "version":        string,        // semver or monotonic version string
  "effective_at":   ISO8601/UTC,
  "rules": [
    {
      "rule_id":    string,
      "scope":      string,        // scope this rule applies to
      "purpose":    string,        // purpose this rule applies to
      "condition":  object,        // structured condition expression (no free text)
      "effect":     "PERMIT" | "DENY"
    }
  ]
}

{
  "decision_id":        uuid,
  "request_id":         uuid,
  "subject_id":         string,
  "decision":           "ALLOW" | "DENY",
  "reason_code":        string,
  "consent_record_id":  uuid | null,
  "policy_version":     string,
  "evaluation_trace": {
    "validation_result":  "VALID" | "INVALID",
    "consent_result":     "FOUND" | string,    // reason code if not FOUND
    "policy_result":      "PERMITTED" | string // reason code if not PERMITTED
  },
  "decided_at":         ISO8601/UTC,
  "artifact_id":        uuid | null            // populated for ALLOW decisions only
}

#Deployment Model

The reference implementation is designed for single-node deployment. All components run within a single process or within a single trusted host environment. No distributed coordination, consensus protocol, or network-separated component topology is required or assumed.

The Consent Registry may be implemented as an in-memory key-value store seeded from a static file at startup. The Audit Log may be implemented as a local append-only file with sequential write semantics. The Policy Engine loads policy snapshots from a local filesystem path at initialization. No external service dependencies are required for baseline operation.

The runtime boundary is defined as: the enforcement stack process, the consent registry data source, the policy snapshot store, and the audit log destination. All must be present and operational before the Enforcement Gateway accepts any inbound requests. A startup check must verify all component availability and must refuse to accept requests if any component is unavailable.

Network exposure of the enforcement stack is outside the scope of this specification. In production deployments, the enforcement stack must be protected from unauthorized access; this is addressed in the QODIQA Security and Cryptographic Profile.

#Non-Goals

The following are explicitly outside the scope of this specification. An implementation that addresses these areas is not prohibited, but conformance with this specification does not require them and does not assess them.

#Conformance Alignment

This reference implementation is designed to demonstrate compliance with the QODIQA Core Standard and the 68-Point Enforcement Framework. The following table maps key implementation behaviors to their governing framework principles.

#Validation Scenarios

The following scenarios constitute the minimal conformance test suite for this reference implementation. Any conformant implementation must produce the specified outcome for each scenario. These scenarios may be executed as automated tests against a running implementation.

Scenario 1 — Valid Consent, Permitted Policy: ALLOW

Expected outcome: Decision Engine issues ALLOW. Decision artifact is generated. Audit Log entry written with decision ALLOW. Inference execution is permitted.

Scenario 2 — Missing Consent: DENY

Expected outcome: Consent Registry returns CONSENT_NOT_FOUND. Decision Engine issues DENY with reason code CONSENT_NOT_FOUND. No artifact is generated. Audit Log entry written with decision DENY. Inference execution is blocked.

Scenario 3 — Invalid Scope: DENY

Expected outcome: Decision Engine issues DENY with reason code CONSENT_SCOPE_MISMATCH. No artifact is generated. Audit Log entry written with decision DENY. Inference execution is blocked.

Scenario 4 — System Failure: DENY

Expected outcome: Decision Engine issues DENY with reason code CONSENT_UNAVAILABLE. No artifact is generated. System does not fall back to implicit consent or default-allow. Audit Log entry written if log is available; if Audit Log is also unavailable, DENY is still returned and system records the failure in its internal error state.

Scenario 5 — Expired Consent: DENY

Expected outcome: Consent Registry returns CONSENT_EXPIRED. Decision Engine issues DENY with reason code CONSENT_EXPIRED. Inference execution is blocked.

#Conclusion

This specification defines a minimal, self-contained reference implementation of the QODIQA enforcement model. It is not a production system. It is the smallest correct instantiation of the enforcement properties required by the QODIQA Core Standard, expressed in concrete component definitions, data structures, flow sequences, and validation scenarios.

The reference implementation demonstrates that deterministic runtime consent enforcement is achievable in a minimal configuration. Seven components are sufficient to implement the complete enforcement pipeline: a gateway, a validator, a consent registry, a policy engine, a decision engine, an audit log, and an artifact generator. Each has a precisely bounded responsibility. The interaction between them is fully specified. All failure modes resolve to denial. No ambiguity is permitted at any stage.

This specification serves as the bridge between the QODIQA Core Standard's normative requirements and the operational realities of production deployment. Teams building production enforcement systems should use this reference as their behavioral baseline, validating each component against the scenarios defined in Section 12 before extending the stack with production-grade capabilities: distributed deployment, cryptographic proof generation, high-availability configurations, and advanced identity integration.

The enforcement model defined here is intentionally minimal, but it is not simplified. Every component and every constraint is present because removing it would compromise the correctness of the enforcement guarantee. Fail-closed behavior, audit unconditionally, consent-before-policy, and binary decisioning are not optional features; they are the properties that make the enforcement model trustworthy. Production implementations may add capabilities above this baseline, but they must not remove any of its behavioral guarantees.

Runtime consent enforcement represents a structural shift in how AI systems are governed: from documentation and retrospective accountability toward execution-layer control and verifiable authorization. This reference implementation is a concrete demonstration that the shift is achievable and that its core properties can be implemented, tested, and validated with precision.

#Document Status and Corpus Alignment