AWS reference architecture

The proposed control and workload accounts, generation fences, connectors, access controls, and verification paths.

Technical foundation PDF Markdown source

Engineering review draft. The design, API, and AWS integrations described here are proposed; operating results and response-time commitments have not yet been validated.

On this page

Architecture decisions

Use a control account and a separate workload account in one Region for the reference sandbox. The public marketing website remains a separate system. Its browser demo is not a privileged operator console.

The control account owns operator authorization, the registry and quarantine latch, operation history, a durable dispatch outbox, Step Functions Standard workflows, verification, and evidence storage. The workload account owns the designated ECS cluster, private workload subnets, the enrolled launcher, gateway adapter, and narrow connector roles. Neither an agent's model nor its task role is a stop authority.

Standard workflows are a candidate for durable orchestration. Their execution semantics do not remove the need for application idempotency, connector retry handling, or reconciliation of calls with unknown outcomes. [S7]

Account and data-flow view

Proposed AWS account and enforcement boundaries. Pan horizontally on smaller screens.Download SVG

The diagram proposes components and trust boundaries; it does not assert a tested AWS configuration. The diagnostic probe is verification code controlled by the operator, not the agent's own report.

Quarantine and dispatch protocol

Validate the operator token and configured authentication assurance. Authorize the environment, workload, generation, and stop action from trusted mappings.
Reject a stale generation or an idempotency-key conflict. Resolve exact account, cluster, role, and task ARNs from the protected registry, never from arbitrary caller-supplied resource addresses.
In one regional DynamoDB transaction, latch the generation QUARANTINED, persist the stop operation, and create an outbox item. Acceptance is returned only after this transaction succeeds.
The dispatcher starts or resumes the operation's deterministic workflow. An outbox retry or dispatcher restart must find the same operation rather than produce a second independent stop.
In parallel, reconcile and stop owned tasks, quarantine the dedicated IAM task role, and account for controlled tool activity. Keep each connector's status and provenance separately.
Verify required outcomes. Deadline expiry leaves quarantine intact and publishes a partial, failed, or unknown result with continued reconciliation.

DynamoDB transactions can make the registry updates atomic within the chosen account and Region. They cannot make a separate ECS call or external tool action atomic with the fence. Strongly consistent base-table reads support current gate observations; GSIs are not the admission authority. [S8, S9]

Launch and tool-admission races

The trusted launcher records a reservation under a condition that the enrolled generation is ARMED before calling RunTask. A reservation ID supplies a stable client token for retries. A concurrent stop may occur after reservation and before ECS responds; that reservation remains part of the stop boundary until its result is reconciled. Late task ARNs must be registered and stopped. An unresolved launch reservation prevents VERIFIED_STOPPED. [S12]

The gateway maps its verified IAM caller to a workload generation. It transactionally records admission under the same generation's ARMED condition before dispatching a supported tool action. This distinguishes pre-fence admitted work from new requests that must be denied. Do not rely on a read-then-act check alone or on a cached positive authorization decision.

The mock adapter can account for its outstanding operations. External jobs, opaque streams, and untracked side effects need their own adapters and are outside this prototype. A request admitted before quarantine may already have caused an effect; neither a database transaction nor task termination reverses that effect.

Runtime and identity enforcement

The runtime connector stops registered exact task ARNs and checks their provider-reported terminal state. The verification record retains enrolled ownership independently of task tags. Task stopping has a signal/timeout lifecycle; a successful API response is not the final observation. [S1]

The identity connector attaches a fixed deny-all policy to the generation's dedicated task role, preserving the role's quarantine until retirement. Do not apply this policy to a shared role or service-linked role. Old-session cutoff revocation alone does not restrict all later sessions, and IAM propagation must be included in observation and retry behavior. [S2, S4]

To test effective denial independently, the sandbox includes a trusted probe task with an operator-controlled image digest. It can be launched with the enrolled generation's task role and attempt a previously allowed read of one harmless diagnostic object. Run it before and after quarantine, including with refreshed task credentials. Store only the result and request metadata, not the credentials. A connector with permission only to inspect a policy cannot claim that it has observed effective access denial.

The probe is separately inventoried as verification infrastructure and cannot execute business tools. Its launcher can pass only the approved diagnostic task/execution roles to the fixed probe definition. Review this permission boundary before deployment.

Network and gateway assumptions

Use private workload subnets without general-purpose NAT or public internet routes for the agent. The proposed tool entry is a private API Gateway REST API with IAM authorization, restricted VPC endpoint/resource policies, and a Lambda adapter. Validate endpoint, image-pull, logging, DNS, and diagnostic-object access explicitly. The task execution role is distinct from the agent task role. [S5, S10, S11]

Private placement alone does not establish isolation; IAM permissions and endpoint policies must also constrain the permitted destinations. The gateway must deny new admissions when it cannot obtain authoritative gate state. This choice favors containment over tool availability during a control-state failure.

Do not use a security-group replacement as the sole proof of an immediate cutoff. Connection tracking can preserve already established flows. The first claim is bounded to enrolled task termination, enforced admission denial, and tested role quarantine. [S6]

Permission boundaries to implement

Principal	Proposed permissions	Explicit boundary
Operator API	Scoped registry transaction and operation reads; configured JWT verification.	No direct general-purpose workload administration.
Dispatcher/workflow	Read outbox, start deterministic workflow, assume exact connector roles.	Cannot select arbitrary customer accounts or roles from request text.
Runtime connector	StopTask/DescribeTasks on enrolled task scope; narrow cluster discovery as required.	Does not stop unknown resources or clear quarantine.
Identity connector	Put the fixed quarantine policy on dedicated generation roles; read back configuration.	No general role creation, policy escalation, shared-role edits, or recovery unquarantine.
Trusted launcher	Run the enrolled definition and pass only approved task/execution roles.	Requires a valid launch reservation and generation fence.
Agent task role	Invoke its exact tool API and read the one harmless diagnostic object.	No IAM, RunTask, PassRole, alternate role assumption, control writes, or arbitrary data access.
Gateway adapter	Conditional admission and mock tool ledger operations for its environment.	Cannot approve recovery or reopen an old generation.
Verifier/probe runner	Provider reads, scoped probe launch, bounded diagnostic observations, evidence writes.	Cannot grant business permissions or trust agent-supplied success.
Provisioner/recovery operator	Create the reviewed next-generation resources under a single-use approval.	Keeps prior role and generation quarantined.

This is a design matrix, not deployable IAM JSON. Review resource-level action support, trust policies, PassRole conditions, and each unavoidable wildcard when writing infrastructure code.

Verification and status model

An operation progresses ACCEPTED -> ENFORCING -> VERIFYING. VERIFIED_STOPPED requires every mandatory check to pass for the enrolled generation: launch fence closed; launch reservations settled; registered tasks stopped; owned-task reconciliation complete; new gateway admissions denied; controlled in-flight actions accounted for; and effective role denial observed.

If required observations are unavailable, report UNKNOWN. If known enforcement is mixed with known failures or coverage gaps, report PARTIAL. If enforcement cannot proceed because of a known terminal failure, report FAILED. Results include per-check evidence and timestamps. The generation remains QUARANTINED in every incomplete case.

Verification is an observation over a defined boundary and time. Later contradictory evidence appends a new verification attempt and changes the current assessment; it does not erase historical records or preserve an outdated success banner.

Recovery and delivery gates

A recovery review binds the incident, workload, old generation, and intended next generation. Approval creates a single-use provisioning permit; it does not restart tasks. The provisioner prepares a fresh role, task definition, and enrollment. The new generation's tool gate opens only after its enrollment checks pass. The previous role's deny and historical records remain.

Before creating AWS resources, settle the account/Region, identity integration, actual resource policies, deployment budget, retention, endpoint design, and diagnostic probe. Before a pilot, execute the validation matrix and review all unknown or partial outcomes. Build a deterministic enforcement harness first, then connect a real model behind the same controlled gateway.