Compliance implementation plan¶

Status: Engineering baseline implemented; assurance work open | Last reviewed: 2026-08-30

This plan converts the standards readiness review and control gap register into code, infrastructure, operating controls, and assurance work. Read it before implementing a regulated deployment profile or selecting tasks from the implementation backlog.

Role owners appear in the validated control catalog. Named accountable people, executive approval, and assurance owners remain organization-level decisions.

Outcome¶

The program produces four enforceable deployment profiles:

Profile	Intended scope	Boundary rule
Commercial regulated	SOC 2, HIPAA, GDPR/CCPA, CSA STAR, ISO 27001, ISO 42001	Use isolated commercial AWS accounts and approved service/model/region combinations.
Privacy regional	GDPR and CCPA overlay	Add legal-role, residency, transfer, rights, retention, and processor restrictions to another profile.
PCI segmented	PCI DSS payment functions	Isolate payment capture and the vault from the general platform; let the assessor fix final scope.
Federal Class D	FedRAMP High/Class D	Run a separate AWS GovCloud product boundary with federal build, operations, evidence, and exact model eligibility.

Engineering readiness means the code enforces each declared profile and produces testable evidence. A CPA, QSA, certification body, recognized FedRAMP assessor, agency, counsel, or regulator still makes the applicable external determination.

Implementation state¶

The policy engines, profile store, assignment and exception controls, authoring and runtime enforcement, evidence chain, WORM exporter, privacy workflow, managed envelope encryption, payment boundary, AI governance gate, regulated AWS stack, hardened Helm overlay, supply-chain outputs, and dedicated CI gate are implemented. The implementation guide is now the operational source of truth.

The commercial profiles remain conditional on deploying and verifying a real environment. The federal profile remains planned and non-assignable because no GovCloud environment exists. Organizational controls, contracts, operating evidence, independent assessments, certifications, PCI validation, and FedRAMP authorization remain open.

Starting assumptions¶

AWS is the first regulated hosting target. Keep the policy contract cloud-neutral so Azure, GCP, and on-premises profiles can follow.
The existing multi-tenant product remains the commercial base. PCI and federal workloads use separate boundaries.
Existing CI and E2E work in the SaaS hardening plan remains the test foundation. This plan does not reopen completed hardening tasks.
Tenants without a regulated profile keep current behavior during migration. New regulated profiles fail closed.
Do not place PHI, cardholder data, or federal High data in a profile until its release gate passes.

Decisions required before code¶

The accountable leaders must record these decisions in architecture and compliance decision records:

Legal entity, product names, service commitments, regulatory roles, jurisdictions, data categories, customer responsibilities, and proposed claims.
System boundaries for commercial regulated, PCI, privacy, and federal profiles, including administrators, build systems, support paths, subprocessors, and interconnections.
Data residency, retention, backup, legal-hold, RTO/RPO, availability, and incident-notification commitments.
Approved providers, AWS accounts/regions, model families, telephony paths, observability systems, and contract requirements for each profile.
Assurance sequence, assessors, GRC system, evidence owners, and the authority that approves exceptions.

Code cannot compensate for an undefined claim or unsigned BAA/DPA.

Target architecture¶

The policy source controls what the product may publish and run. The deployment ceiling states what the environment can support. A tenant assignment may narrow that ceiling but cannot expand it.

flowchart LR
  subgraph Policy[Versioned policy source]
    Catalog[Control and provider catalog]
    Profiles[Commercial, privacy, PCI, and federal profiles]
    Ceiling[Deployment ceiling and policy hash]
  end
  subgraph Control[TrueServe control plane]
    Assignment[Tenant profile assignment]
    Authoring[Authoring validation]
    Publish[Publish gate and immutable snapshot]
    Exceptions[Approved, expiring exceptions]
  end
  subgraph Runtime[Data plane enforcement]
    Session[Session and workflow gate]
    Providers[Provider, model, region, and fallback gate]
    Data[Classified storage and lifecycle]
    Payment[Segmented payment vault]
  end
  subgraph Evidence[Evidence and operations]
    Outbox[Transactional audit outbox]
    Exporter[Audit exporter and reconciler]
    WORM[WORM audit archive]
    SIEM[Security lake, detection, and cases]
  end
  Catalog --> Profiles --> Assignment --> Authoring --> Publish --> Session
  Ceiling --> Assignment
  Ceiling --> Session
  Exceptions --> Publish
  Session --> Providers
  Session --> Data
  Session --> Payment
  Authoring --> Outbox
  Publish --> Outbox
  Session --> Outbox
  Providers --> Outbox
  Data --> Outbox
  Payment --> Outbox
  Outbox --> Exporter --> WORM
  Exporter --> SIEM

Source: compliance-target-architecture.mmd.

Architecture contracts¶

Policy source¶

Add a root compliance/ tree with JSON Schemas, signed profile manifests, provider/model eligibility records, control mappings, test vectors, and documentation templates. Build each release as an RFC 8785-canonical JSON bundle in a DSSE/in-toto envelope signed by the release identity. Pin the accepted signer and reject replay or revision downgrade. Keep secrets and collected customer/audit evidence outside Git.

Each profile revision contains:

Contract area	Required fields
Identity	Stable key, revision, policy hash, approvers, effective/expiry dates, target frameworks.
Deployment	Cloud, partition, accounts, regions, network class, FIPS requirement, service allowlist.
Data	Allowed classifications, purposes, residency, retention classes, recording rules, export rules.
Providers	Exact provider, service, API, model/inference-profile IDs, regions, features, contract requirements, fallback rules.
Security	Encryption/key class, audit class, workload class, vulnerability SLA, backup and recovery class.
Product	Allowed agent/workflow capabilities, tools, payment surfaces, guardrails, human-oversight rules.
Evidence	Required checks, evidence IDs, collection frequency, customer responsibilities, exception authority.

The provider catalog records its source URL and review/expiry dates. CI warns before expiry. An enforce-mode deployment rejects expired federal and PHI eligibility records. Runtime model discovery can confirm availability, but it cannot establish compliance eligibility.

Deployment ceiling¶

Terraform generates a deployment manifest with the environment profile, AWS partition/account/region, enabled controls, and admitted profile hashes. Helm mounts it read-only in the authoring control plane and runtime policy engine. Both independently require a verified matching environment and an admitted exact profile hash; Kubernetes RBAC, release review, and the signed image supply chain protect the mounted configuration.

A mismatch stops regulated traffic. Health endpoints expose the profile key, policy hash, and pass/fail state without revealing secrets.

Version and session snapshots¶

Add profile key, revision, policy hash, decision ID, and validation result to published agent/workflow versions. Copy that snapshot to conversation and workflow execution records. A later tenant-profile change cannot alter the rules for an existing published version.

The publish gate inspects all direct and hidden data paths: primary providers, remote analysis, fallbacks, knowledge stores, tools, MCP servers, speech/translation hops, recording, telemetry, and payment capabilities. The runtime repeats the check before starting work and before invoking a provider or fallback.

Exceptions¶

Replace free-text bypasses with typed exceptions. Each exception records scope, control, reason, compensating control, ticket, approver, start, expiry, and policy hash. Regulated profiles reject expired or unapproved exceptions. Federal and PCI profiles can prohibit exceptions for selected controls.

Audit and evidence¶

Replace best-effort general auditing with a transactional append-only event and outbox. A narrow audit-exporter sends events to KMS-encrypted WORM storage and the security platform. Reconciliation compares database sequence/checkpoints with exported objects and alerts on gaps.

Audit events contain identifiers, hashes, and reason codes instead of prompts, secrets, PAN, or unnecessary personal data. Store AI-generated summaries in a separate mutable projection.

Data lifecycle¶

Classify data when the product creates it. Pin a retention-policy revision to each conversation, workflow execution, archive, export, and audit stream. A rights/erasure orchestrator sends idempotent tasks to service-owned adapters and records receipts.

Keep audit evidence metadata separate from customer content. Legal holds suspend deletion through approved, expiring records. After a backup restore, replay the erasure ledger before reopening traffic.

Independent boundaries¶

Create distinct AWS accounts, state, keys, clusters, logs, administrators, and pipelines for PCI and federal scopes. Do not implement those scopes as tenant flags in the commercial cluster.

Codebase shape¶

Path	Purpose
`compliance/schemas/`	Profile, control-catalog, and deployment-manifest schemas. Database constraints define assignment, exception, evidence, privacy, and AI record contracts.
`compliance/profiles/`	Exact service/model/region eligibility plus data, feature, contract, control, review, and expiry rules.
`compliance/controls/`	Validated cross-framework control catalog with engineering state and external responsibilities.
`compliance/test-vectors/`	Shared allow/deny cases for TypeScript, Python, Terraform, and Helm checks.
`shared/compliance-policy/`	TypeScript loader, canonicalizer, hash verifier, decision engine, and types.
`libs/compliance/`	Python implementation of the same policy contract.
`scripts/compliance/`	Profile, catalog, deployment-ceiling, Helm, and database-invariant validation.
`apps/audit-exporter/`	Hash-chain verification, leased delivery state, deterministic WORM writes, and integrity receipts.
`apps/privacy-worker/`	Rights, legal-hold, preference, access/export, and erasure processing for managed conversation and object storage.
`infra/modules/aws/`	Hardened RDS, ElastiCache, S3, and exact-subject IRSA modules used by the boundary.
`infra/stacks/aws-regulated/`	Partition-aware commercial composition and an undeployed GovCloud planning input, with separate backend configuration required per boundary.

Delivery phases¶

The ranges assume a small dedicated platform/security team and allow parallel work. Treat them as sequencing guidance rather than certification commitments.

Phase	Current state	Exit gate
0. Scope and design	Technical catalog and role model implemented; named approvals open	Leaders approve boundaries, commitments, data flows, control catalog, and threat models.
1. Policy and evidence foundation	Implemented and locally verified	Authoring, publish, runtime, and deployment checks use the same signed policy and test vectors; append-only auditing exports without gaps.
2. Data and platform controls	Implemented for managed stores; live and processor tests open	Privacy lifecycle, envelope encryption, hardened workloads, least privilege, resilient AWS data tiers, and security telemetry pass fault and negative tests.
3. Specialized boundaries	PCI code implemented; commercial and GovCloud deployment work open	PCI boundary passes QSA pre-review; commercial regulated profile passes readiness testing; federal text-only boundary deploys in GovCloud.
4. AI and management systems	AI technical gate implemented; operating ISMS/AIMS open	AI inventory, risk, evaluation gates, and ISMS/AIMS evidence operate through at least one review cycle.
5. External assurance	Open	Applicable SOC, ISO, CSA, HIPAA, privacy, PCI, and FedRAMP evidence packages pass external review.

The implementation backlog defines PR-sized tasks and dependencies.

Migration and rollout¶

Add policy evaluation in report-only mode. Compare TypeScript and Python decisions on production-like sanitized configurations.
Create profile tables and snapshot columns without assigning regulated tenants. Backfill unregulated-v1 for existing versions and sessions.
Enable publish enforcement for internal tenants. Block new violations while existing published versions continue under their pinned profile.
Add runtime enforcement and deployment ceiling checks. Run shadow decisions first, then deny mismatches for regulated test tenants.
Migrate encryption with dual-read and new-format-only writes. Re-encrypt in bounded batches, verify counts/hashes, then remove legacy reads.
Move deletion to asynchronous jobs. Preserve the old API response shape during a compatibility window, then document 202 Accepted job semantics.
Deploy commercial regulated and PCI pre-production accounts. Use synthetic data until fault, recovery, deletion, logging, and penetration tests pass.
Build GovCloud from clean state. Import no commercial snapshots, credentials, images, or evidence until the transfer path passes the federal review.

Each rollout step needs a rollback condition, data backup, owner, customer-impact note, and recorded approval. Policy enforcement must fail closed without corrupting in-flight sessions.

Verification strategy¶

Layer	Required gate
Policy	Schema validation; signature/hash verification; expiry checks; cross-language golden vectors; sensitivity tests that prove denies trigger.
Database	Idempotent migration; baseline drift; RLS; append-only triggers; transaction rollback; backfill and restore tests.
Application	Unit and integration tests for publish/session/provider/exception decisions; route-auth audit; tenant-isolation tests; no-fallback tests.
Privacy	Data discovery, access, correction, deletion, legal hold, processor receipt, archive/object-version deletion, and restore/replay tests.
Infrastructure	Terraform validate/plan, policy-as-code, partition tests, encrypted/private endpoint checks, resilience/failover, and backup restore.
Kubernetes	Rendered-chart policy tests, non-root runtime probes, default-deny segmentation, service identity, secret rotation, disruption tests.
Supply chain	Full SAST/SCA/container/IaC/secret scans; SBOM; signed provenance; admission verification; scheduled re-scan and SLA metrics.
Assurance	Evidence completeness/reconciliation, access review, incident tabletop, DR exercise, penetration/segmentation tests, internal audit.

Maintain a negative-test tenant for each profile. Each tenant contains one prohibited provider, region, fallback, retention override, privilege path, and expired exception. CI or scheduled tests must prove that the platform rejects each case.

Framework coverage¶

Engineering capability	Framework outcomes supported
Signed profiles, scope, ownership, evidence	SOC 2, HIPAA, GDPR/CCPA, CSA STAR, ISO 27001, ISO 42001, FedRAMP, PCI
Identity, hardening, crypto, logging, SDLC	All nine scopes
Rights, retention, residency, processors	GDPR, CCPA, HIPAA, SOC 2 privacy, ISO 27001
Segmented payment capture	PCI DSS
GovCloud, FIPS, OSCAL, continuous monitoring	FedRAMP High/Class D
AI inventory, impacts, evaluations, oversight	ISO 42001 plus privacy, SOC 2, and federal risk controls

External work that remains outside code¶

Execute BAAs, DPAs, SCCs/transfer assessments, provider agreements, service commitments, and customer responsibility terms.
Establish policies, training, workforce controls, vendor reviews, risk registers, management review, internal audit, and corrective action.
Engage the CPA, QSA/acquirer, ISO certification body, CSA STAR route, privacy counsel, HIPAA assessor/counsel, FedRAMP recognized assessor, and authorizing agency as applicable.
Run the observation periods, independent tests, package review, authorization, and continuous assurance required for each claim.

Program definition of done¶

You may call a profile engineering-ready when:

Its signed policy and deployment ceiling match the deployed resources and deny all negative test vectors.
Published versions and runtime records pin the validated policy hash; unauthorized providers and fallbacks cannot start.
Audit export reconciles with no unexplained gaps; security alerts and cases show tested ownership.
Retention, rights, legal hold, erasure, backup replay, and processor receipts pass end-to-end tests.
Workload, network, IAM, key, backup, recovery, vulnerability, and supply-chain gates pass with approved evidence.
Control owners have operated and reviewed the controls for the required period.
The applicable independent party has issued the report, certificate, validation, or authorization needed for the external claim.