@emulates/ecs 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — @emulates/ecs
+
+## 0.1.1 (2026-10-06)
+
+Initial release.
+
+### Dependencies
+
+- `@emulates/sqlite`

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/ecs discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/ecs/`; no repository checkout is needed to discover the emulator's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `emulates.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **Fargate task acceptance, failures and container overrides**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- ecs`.
+- Evidence model: Run from an Emulates checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Emulates
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-emulates-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/emulators/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `ecs`.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @emulates/ecs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Part of [Emulates](https://github.com/crvouga/emulators): high-fidelity, in-process emulators for APIs and databases.
+
+WIP AWS ECS Fargate RunTask control-plane emulator. It records task acceptance; it never starts
+containers. Wire contract follows [RunTask](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html).
+
+## Install
+
+`bun add @emulates/ecs`
+
+## Usage
+
+```ts
+import { createServer } from "@emulates/ecs/server"
+const server = await createServer()
+// boto3.client("ecs", endpoint_url=server.url, region_name="us-east-1",
+//              aws_access_key_id="fixture", aws_secret_access_key="fixture")
+await server.close()
+```
+
+CLI: `emulates-ecs serve --port 12129`. Point the application factory's endpoint_url or
+AWS_ENDPOINT_URL_ECS at the server. POST / with X-Amz-Target
+AmazonEC2ContainerServiceV20141113.RunTask accepts AWS JSON 1.1.
+The default fixtures are cluster default and task definition fixture:1 with container app.
+Send launchType FARGATE, taskDefinition, count (1–10), networkConfiguration.awsvpcConfiguration
+and optional overrides.containerOverrides. Responses separate tasks from failures.
+Cluster name/ARN and task-definition ARN/family:revision/latest active family resolve seeded resources.
+Missing clusters return ClusterNotFoundException; absent definitions return ClientException.
+Overrides are retained only in task state, not the request journal. Use synthetic fixture values only.
+
+## Controls and state
+
+Options clusters and taskDefinitions replace the default fixtures. Their records are the exported
+Cluster and TaskDefinition types. The shared /__admin/state routes also seed these collections.
+Read accepted tasks from tasks and request metadata (network configuration, task ARNs, failures)
+from requests. Seed placementFailures with AWS Failure objects to script partial placement:
+each RunTask takes up to count failures in insertion order and accepts the remaining task count.
+Failures persist until deleted/reset; this is a test control, not a capacity simulator.
+Tasks remain PROVISIONING with desiredStatus RUNNING; createdAt uses the emulator clock.
+Identical clientToken retries within a cluster return the same result for 24 hours;
+changed parameters return ConflictException with associated resourceIds. Tokens are resettable state.
+
+Shared /__admin provides health, UI, state, reset, Timeline checkpoints, clock, journal and metrics.
+Namespace carriers: x-emulates-namespace, /__admin/ns/name and SigV4 access-key mappings via
+PUT /__admin/credentials. Signature verification and IAM policy evaluation are not performed.
+Journal entries omit bodies and credentials. No webhooks are emitted.
+Presets: access_denied (AWS 400), throttled (400), rate_limited (explicit HTTP 429 test fault),
+internal_error (500), connection_drop. Shared faults also support deterministic latency.
+
+## Verification
+
+`bun test` runs acceptance and OpenAPI-driven self-parity with divergence detection.
+`bun scripts/sdk.ts` uses uv to install and run exact boto3 1.43.56 against the served emulator:
+successful RunTask, preserved overrides, idempotency, missing resources and SDK exceptions.
+This proves SDK compatibility, not live AWS equivalence. `bun run parity` exits 2 because this
+package only models a billable compute-creating operation; no live request is issued implicitly.
+Live validation needs an authorized isolated ECS account/cluster and explicit execution approval.
+
+## Deliberately not modelled
+
+Real container execution, task lifecycle progression, eventual consistency, network provisioning,
+IAM/signature evaluation, infrastructure deployment, EC2/EXTERNAL/capacity-provider launch modes,
+task-definition or cluster mutations and other ECS operations. Nested overrides outside names,
+commands and environment are passed through, not comprehensively validated. No subnet reachability,
+image validity or resource-capacity simulation. Fargate is the only modeled launch type.
+Task ids and platformVersion LATEST are local stand-ins, not exact AWS-generated ids/resolved versions.
+The idempotency lifetime is 24 hours while emulator tasks remain uncompleted; shorter post-stop expiry
+and task-stop response rewriting are outside this surface.
+
+## API
+
+Main runtime exports: ECSAPI, ECS_NAMESPACE, DEFAULT_CLUSTER, DEFAULT_TASK_DEFINITION,
+createRuntime, ECS_PRESETS, document, operationIds, supportedOperationIds.
+Types: Cluster, TaskDefinition, Failure, Task, ECSAPIOptions, ECSRuntimeOptions, ECSRuntime.
+Server entry: createServer, DEFAULT_PORT, serveTarget; type ECSServerOptions.
+CLI entry executes serve and exports no runtime values.

package/SUPPORT.md

@@ -0,0 +1,11 @@
+# AWS ECS Fargate RunTask — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **1**
+- supported by the emulator: **1**
+- parity enabled: **1**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `RunTask` | `POST /` | ✅ supported | ⚠️ unsafe (opt-in) |  |