@yiaany/ghostapi 0.1.6 → 0.1.8

package/docs/hosted-pilot.md

@@ -0,0 +1,111 @@
+# Hosted Pilot Architecture
+
+## Scope And Truthful Guarantees
+
+The hosted pilot is a separate Bun/Elysia application under `hosted/`. The existing Node.js local runtime remains account-free and does not communicate with the hosted service by default.
+
+The design targets 1,000 sustained and 5,000 peak API requests per second, with CI report ingestion and scenario reads as the first workflows. These are capacity targets to prove with production-shaped load tests, not current guarantees.
+
+Supabase read replicas are asynchronous and read-only. All writes use one primary region, and immediate reads after a write also use that primary. Fly may run stateless API instances near clients later, but it must not claim multi-region writes while Supabase has one writable primary. Supabase PITR supports fine-grained recovery, but restoration takes the project offline and duration depends on database size; this stack does not prove RPO under one minute or RTO under five minutes until a vendor-supported configuration and repeated DR drills demonstrate both.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  CI[CI runner or agent] -->|ingest key + idempotency key| API[Bun + Elysia write API]
+  Agent[Agent] -->|session| API
+  API --> Primary[(Supabase PostgreSQL primary)]
+  API --> Redis[Upstash Redis: rate limits + cache only]
+  Primary --> Outbox[Transactional outbox]
+  Dispatcher[Outbox dispatcher] --> QStash[Upstash QStash]
+  QStash --> Worker[Elysia internal worker]
+  Worker --> Primary
+  Reader[Scenario reader] --> API
+  API --> Primary
+```
+
+Redis is deliberately not the source of truth for reports, authorizations, idempotency, or job completion. QStash is at-least-once transport only. PostgreSQL owns durable acceptance, idempotency, outbox state, job receipts, scenario registry, report state, and audit data.
+
+The migration enables RLS on the application tables. The hosted API uses a dedicated least-privilege `service_role` database role with explicit policies; browsers never receive that connection string. Tenant filtering remains explicit in every API query, so authorization does not rely on a future client-side `set_config` convention.
+
+## Request Paths
+
+### Report Intake
+
+`POST /v1/projects/:projectId/reports` requires:
+
+- `Authorization: Bearer <CI ingest secret>`
+- `X-GhostAPI-Ingest-Key-Id: <public UUID>`
+- `Idempotency-Key: <16-256 character key>`
+
+The API hashes the canonical request. In one primary-Postgres transaction it validates the key, creates or resolves the idempotency ledger entry, writes the bounded sanitized report, and writes an outbox event. Only then does it respond with `202 Accepted`.
+
+If the API crashes after commit but before replying, the CI runner retries with the same idempotency key and receives the original report id. If the same key has a different body, it receives `409`.
+
+### CI Ingest Keys
+
+Project developers provision a key with `POST /v1/projects/:projectId/ingest-keys` and an `expiresInDays` value from 1 to 90. The response returns an id, non-sensitive prefix, expiry, and a plaintext secret exactly once. Only the SHA-256 digest is written to PostgreSQL. Developers revoke a key with `POST /v1/projects/:projectId/ingest-keys/:keyId/revoke`; create and revoke actions write tenant audit events. The dashboard/client must not persist, log, or re-display the plaintext secret.
+
+### Scenario Reads
+
+Scenario versions are immutable. Publishing creates a new `{ scenario_key, version }` row. CI runs pin a scenario version; agents read by key/version or a selected current version. Cursor pagination and a read cache belong at the API edge only after primary-query correctness is load-tested.
+
+Read endpoints that must observe a preceding write go to the primary and return `X-Consistency: primary`. A future replica endpoint may return `X-Consistency: eventual`; it cannot back read-your-writes behavior.
+
+### Workers
+
+Outbox dispatch uses `FOR UPDATE SKIP LOCKED`, leases a bounded batch, then publishes an event id to QStash. The QStash receiver verifies the request signature before parsing its body. The worker transaction creates a permanent `job_receipts` record and performs report processing atomically. Redelivery returns a duplicate success without duplicating scenario results.
+
+The dispatcher can publish the same event more than once after an ambiguous network outcome. That is intentional: QStash deduplication has a limited window, so the permanent PostgreSQL receipt is the correctness boundary. A redelivery while an unexpired worker lease is active returns a retryable `503`; a stale lease can be safely acquired again. A completed receipt returns success without duplicating results.
+
+## PostgreSQL Data Model
+
+`hosted/migrations/001_core.sql` creates:
+
+| Table | Purpose |
+| --- | --- |
+| `app.organizations`, `app.organization_memberships`, `app.projects` | Tenant hierarchy and membership. |
+| `app.scenario_versions` | Immutable shared scenario definitions with checksum. |
+| `app.ci_ingest_keys` | Public id plus SHA-256-only CI secret digest and scope. |
+| `app.reports` | Bounded sanitized CI report payload and processing state. |
+| `app.idempotency_ledger` | Durable `(project_id, key)` replay contract. |
+| `app.outbox_events` | Transactional event publication source. |
+| `app.job_receipts`, `app.scenario_run_results` | At-least-once worker deduplication and results. |
+| `app.audit_events` | Hosted control-plane audit metadata. |
+
+Better Auth manages its own `auth` schema/tables through its migration CLI. Configure `AUTH_DATABASE_URL` with `search_path=auth`; application `DATABASE_URL` should use `search_path=app`. Keep application memberships separate from Better Auth accounts so a later SAML/OIDC identity mapping does not rewrite tenant authorization.
+
+## Queue And Rate Limits
+
+- Queue only identifiers and schema version, never raw report JSON, authorization headers, cookies, or provider credentials.
+- Do not use a single FIFO queue. Shard flow-control keys by report/project as needed; workers make every handler idempotent.
+- Verify QStash signatures on every internal job request.
+- Redis keys are opaque non-secret project/principal identifiers, not bearer tokens, email addresses, or raw session ids. The default CI key budget is 300,000 requests per minute per project only as a pilot starting point; derive final limits from tenant budgets and load tests.
+- Rate limits must cover unauthenticated auth routes, CI ingest key id, user/organization, project, and QStash worker endpoint separately.
+- Do not enable automatic retries for non-idempotent external effects. Scenario processing remains local metadata until a typed action gateway exists.
+
+## Capacity Plan
+
+At 1,000 sustained writes per second, report size and retention determine cost and storage more than framework choice. Before accepting pilot load, measure actual p50/p95/p99 report bytes, write/read ratio, tenant count, retention requirements, index growth, WAL throughput, database pool waits, QStash backlog, and worker drain rate.
+
+Initial deployment is one API write region co-located with the Supabase primary, with at least two Fly machines. Use bounded database pools per machine and Supavisor transaction pooling. Add read replicas only after primary query/index behavior is correct and clients tolerate eventual consistency.
+
+## Required Pre-Launch Tests
+
+1. Kill the API after Postgres commit but before response; retry must return one report id and one outbox event.
+2. Force QStash redelivery and worker failure; expect one job receipt and one scenario result per report/version.
+3. Soak 1,000 sustained RPS and burst 5,000 peak RPS using production p99 payloads; verify intake p95/p99, pool waits, WAL, queue depth, worker drain, and zero lost accepted report ids.
+4. Verify primary read-your-writes and clearly labeled replica staleness.
+5. Run a production-equivalent DR drill. Reject the stated RPO/RTO target until observed accepted-data loss is below 60 seconds and restored write availability is below 5 minutes.
+6. Run authorization tests for every organization/project boundary, disabled/revoked ingest key, expired session, body/key mismatch, and direct worker invocation without a valid QStash signature.
+
+## Identity
+
+The hosted app mounts Better Auth for Google OAuth and email/password. Better Auth owns authentication accounts/sessions; GhostAPI owns organization membership and authorization. A later enterprise identity layer maps a verified OIDC/SAML subject to an internal user id. It must not accept arbitrary issuer, email-domain, or client-provided role claims.
+
+## Sources Checked 2026-08-08
+
+- Elysia validation and handler status behavior: official Elysia documentation.
+- Better Auth PostgreSQL and Elysia integration: official Better Auth documentation.
+- Supabase read replicas and PITR recovery limits: official Supabase documentation.
+- QStash deduplication, publish, receiver verification, and at-least-once guidance: official Upstash documentation.

package/docs/mcp.md

@@ -1,50 +1,52 @@
-# GhostAPI MCP Setup
-
-GhostAPI ships with a local stdio MCP server so coding agents can inspect and control the local API world.
-
-## Start MCP
-
-```bash
-npx @yiaany/ghostapi mcp
-```
-
-## Universal Config
-
-```json
-{
-  "mcpServers": {
-    "ghostapi": {
-      "command": "npx",
-      "args": ["-y", "@yiaany/ghostapi", "mcp"]
-    }
-  }
-}
-```
-
-## Generate Client Snippets
-
-```bash
-npx @yiaany/ghostapi setup --write
-```
-
-This writes copy-ready local snippets under `.ghostapi/agent-configs/` and project instructions for supported agent clients.
-
-## Tools
-
-| Tool | Purpose |
-| --- | --- |
-| `inspect_state` | Read local API objects from `.ghostapi/state.json`. |
-| `get_traffic_logs` | Inspect recent captured API traffic. |
-| `set_api_behavior` | Force a deterministic local response for `method + path`. |
-| `toggle_chaos_mode` | Enable or disable local latency and error injection. |
-
-## Agent Prompt
-
-```text
-Use the GhostAPI MCP server.
-
-Keep all third-party API calls local on http://127.0.0.1:8080.
-Do not call real providers.
-
-Use GhostAPI MCP tools to inspect state, read traffic logs, configure deterministic responses, and test failure scenarios.
-```
+# GhostAPI MCP Setup
+
+GhostAPI ships with a local stdio MCP server so coding agents can inspect and control the local API world.
+
+## Start MCP
+
+```bash
+npx @yiaany/ghostapi mcp
+```
+
+## Universal Config
+
+```json
+{
+  "mcpServers": {
+    "ghostapi": {
+      "command": "npx",
+      "args": ["-y", "@yiaany/ghostapi", "mcp"]
+    }
+  }
+}
+```
+
+## Generate Client Snippets
+
+```bash
+npx @yiaany/ghostapi setup --write
+```
+
+This writes copy-ready local snippets under `.ghostapi/agent-configs/` and project instructions for supported agent clients.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `inspect_state` | Read sanitized local API objects from the configured GhostAPI data directory. |
+| `get_traffic_logs` | Inspect recent captured API traffic. |
+| `set_api_behavior` | Force a deterministic local response for `method + path`. |
+| `toggle_chaos_mode` | Enable or disable local latency and error injection. |
+
+The HTTP server and MCP process must use the same `GHOSTAPI_DATA_DIR` to share state, behaviors, and persisted Fault Lab configuration. Updates use local inter-process locking; this is not distributed coordination for network filesystems.
+
+## Agent Prompt
+
+```text
+Use the GhostAPI MCP server.
+
+Keep all third-party API calls local on http://127.0.0.1:8080.
+Do not call real providers.
+
+Use GhostAPI MCP tools to inspect state, read traffic logs, configure deterministic responses, and test failure scenarios.
+```

package/docs/operations/disaster-recovery-runbook.md

@@ -0,0 +1,81 @@
+# Disaster-Recovery Runbook
+
+Local backup and restore for the GhostAPI data directory (`GHOSTAPI_DATA_DIR`, default `.ghostapi/`).
+
+## When To Use This
+
+- You are replacing or moving the local data directory and need a verified copy.
+- A store is corrupt (`ghostapi` reports a degraded runtime health) and you want to restore from a known-good backup.
+- You are running a quarterly DR drill: back up, destroy, restore, verify.
+
+## Before You Start
+
+- Run `ghostapi start` is NOT required. Backup and restore work on a stopped or running instance, but restoring over a running instance is not supported — stop the instance first.
+- Backups are local directory copies with sha256 manifests. They are not encrypted, do not contain upstream secrets (the credential broker persists metadata only), and are not a substitute for object-storage or offsite backup.
+- The default backup destination is `.ghostapi/reliability/backups/backup-<timestamp>-<id>/`. Because the `backups` directory is excluded from future backups, backups never recursively include one another.
+
+## Backup
+
+Backup is available programmatically:
+
+```ts
+import { backupRuntime } from "@yiaany/ghostapi";
+const result = await backupRuntime({ destinationDir: ".ghostapi/reliability/backups/manual-drill" });
+// result: { backupId, path, fileCount, totalBytes, verified: true, createdAt }
+```
+
+The backup verifies every copied file (size + sha256 + JSON structure for `.json` entries) and refuses to overwrite an existing destination. `result.verified` is only true after full verification.
+
+## Restore
+
+```ts
+import { restoreRuntimeBackup } from "@yiaany/ghostapi";
+await restoreRuntimeBackup({ sourceDir: ".ghostapi/reliability/backups/manual-drill", targetDir: ".ghostapi-restored" });
+```
+
+Then point the runtime at the restored directory:
+
+```bash
+export GHOSTAPI_DATA_DIR=/absolute/path/to/.ghostapi-restored
+ghostapi doctor
+```
+
+Restore refuses:
+
+- A backup whose manifest was not verified at creation time.
+- Any manifest entry path that escapes the backup root (path traversal).
+- A target that is the backup source itself or inside it.
+- A target directory that is not empty (restore copies into a fresh directory).
+- Any entry whose bytes no longer match the manifest (tamper detection).
+
+## Verification Steps After Restore
+
+1. `ghostapi doctor` reports healthy.
+2. `curl http://127.0.0.1:8080/health` returns `{ "ok": true, "ready": true }`.
+3. `curl http://127.0.0.1:8080/health/readiness` returns HTTP 200 with a `ready: true` report. A 503 means the restored directory has a degraded store — do not continue.
+4. Spot-check state: list actions (`ghostapi actions` or the equivalent CLI), run a reconciliation run, and confirm SLO sample counts are non-zero.
+
+## Destroy-The-World Drill (Non-Destructive)
+
+1. `backupRuntime` into `.ghostapi/reliability/backups/drill-<date>`.
+2. `Remove-Item -Recurse -Force .ghostapi` (or `rm -rf`) to simulate data loss.
+3. `restoreRuntimeBackup` into a fresh directory.
+4. Point `GHOSTAPI_DATA_DIR` at the restored directory and run the verification steps above.
+5. Confirm the backup directory still exists untouched (restore copies out of it; it never deletes).
+
+## Failure Modes
+
+| Symptom | Meaning | Action |
+| --- | --- | --- |
+| "Backup destination already exists" | Refusing to overwrite | Use a new destination or remove the old backup deliberately |
+| "Backup source entry is not valid JSON" | A `.json` file in the data dir is corrupt | Find and fix/delete the corrupt store, then re-back up |
+| "Backup file content changed during copy" | Concurrent write during backup | Stop writers, re-run backup |
+| "failed integrity verification" on restore | Backup was tampered or the disk changed | Do not restore; find the original source or a different backup |
+| "path escapes its root directory" | Crafted/tampered manifest | Reject the backup as untrusted |
+| `/health/readiness` returns 503 | A restored store is corrupt | Inspect the `degraded` store in the report and repair/delete it, then re-check |
+
+## Retention Guidance
+
+- Keep at least two rotating backups: the previous known-good and the current.
+- Back up before any release or before switching `GHOSTAPI_DATA_DIR`.
+- The 64 MiB backup cap covers the bounded local stores; if your worlds/actions exceed it, prune old synthetic data first.

package/docs/operations/kill-switch-runbook.md

@@ -0,0 +1,32 @@
+# Kill Switch Runbook
+
+## Detection
+
+Use this procedure when policy violations, abnormal action velocity, budget exhaustion, reconciliation mismatch, latency/failure circuit opening, or suspected agent compromise is observed. An alert is evidence only; it is not a stop. Verify the affected organization, project, environment, agent/workload, provider, operation, or risk class before selecting scope.
+
+## Stop
+
+1. Use an independently authenticated emergency operator with `safety.stop`.
+2. Call the local `LocalSafetyController.stop({ identity, scope, reason })` API with the narrowest safe scope. Use `global` when the scope cannot be established quickly.
+3. Record a bounded factual reason without credentials, raw requests, personal data, or provider payloads.
+4. Confirm the persisted switch is enabled and examine the safety audit chain. Matching queued records must be in the dead-letter queue, not still pending.
+5. Treat actions that passed their final commit check as potentially completed. Do not retry unknown outcomes; investigate or reconcile them first.
+
+## Investigation
+
+1. Preserve the local safety, action, approval, and credential-broker state files as evidence under the existing local trust model.
+2. Inspect action receipt status, controller audit records, budget ledger, circuit reason, and dead letters.
+3. Identify the exact idempotency key and action hash. A changed action must be submitted as a new reviewed action, never forced through a prior reservation.
+4. For any future provider integration, reconcile against the provider before retrying or compensating. This local synthetic controller cannot prove external outcome.
+
+## Recovery
+
+1. Correct the policy/configuration or isolate the compromised workload.
+2. Review budgets, circuit thresholds, and the root cause. Do not clear audit, ledger, or dead-letter state to make a control appear healthy.
+3. Require a separately authenticated operator with `safety.reenable`; the stop permission alone is insufficient.
+4. Call `reenable({ identity, scope, reason })` and confirm the audit record and persisted switch state.
+5. Re-admit only a reviewed action. Approved artifacts still require current policy, identity, idempotency, budget, circuit, kill-switch, and final-commit checks.
+
+## Game Day
+
+The `GhostAPI Kill Switch Game Day` workflow runs at `03:17 UTC` each Monday and can be started manually. It executes only the local synthetic controller test. Investigate a failed drill before trusting the control: a successful alert without a verified blocked action is not sufficient.

package/docs/policy.md

@@ -0,0 +1,61 @@
+# Policy As Code
+
+GhostAPI reads one local, versioned YAML policy. It has no remote includes, environment-variable interpolation, templates, or executable expressions.
+
+Copy [`examples/policy/ghostapi.policy.yaml`](../examples/policy/ghostapi.policy.yaml) into a project as `ghostapi.policy.yaml`, then validate it:
+
+```bash
+ghostapi policy validate
+ghostapi policy explain network api.stripe.com --provider stripe
+ghostapi policy explain stripe.card_declined
+ghostapi policy explain report 0 0 0
+```
+
+`ghostapi run --policy ghostapi.policy.yaml -- <command>` loads and validates the file once before any namespace preflight or target spawn. The run evidence records only the policy SHA-256 and required scenario IDs, not policy file content or command arguments. Policy changes during a run do not reload or alter that run.
+
+`ghostapi evidence generate --policy ghostapi.policy.yaml --ci` evaluates required scenarios and report thresholds against the generated evidence artifact. Pass `--contract-baseline` and `--contract-candidate` to include contract drift. CI mode exits non-zero when required scenarios are missing, production-egress, forbidden-credential, or breaking-contract thresholds are exceeded, or other fail findings are present.
+
+## Schema V1
+
+```yaml
+version: 1
+network:
+  default: deny
+  allow:
+    - host: localhost
+    - provider: stripe
+  deny:
+    - host: api.stripe.com
+  productionHosts:
+    - '*.stripe.com'
+credentials:
+  forbid:
+    - sk_live_*
+requiredScenarios:
+  - stripe-payment-intent-card-declined
+enforcement:
+  allowedModes:
+  - linux-network-namespace
+reports:
+  maxProductionEgressAttempts: 0
+  maxForbiddenCredentialMatches: 0
+  maxBreakingContractChanges: 0
+```
+
+- `network.default`: `allow` or `deny` when no rule matches.
+- `network.allow` and `network.deny`: rules contain exactly one `host` or `provider` field.
+- `network.productionHosts`: classifies hostnames for decision traces and CI/report evaluation.
+- `credentials.forbid`: bounded `*` globs matched against an explicit input; GhostAPI never expands environment variables in policy.
+- `requiredScenarios`: scenario IDs the evidence report must mark complete.
+- `enforcement.allowedModes`: currently `linux-network-namespace` or `proxy-guidance`.
+- `reports`: maximum allowed production-egress attempts, forbidden-credential matches, and breaking contract changes for a report decision. `maxBreakingContractChanges` defaults to `0` when omitted by an existing policy.
+
+## Precedence And Limits
+
+For a network decision, a matching `network.deny` rule always wins over a matching `network.allow` rule. Otherwise `network.default` decides. `ghostapi policy explain` prints the selected rule and decision trace.
+
+Policies are limited to 128 KiB and list fields to 200 entries. Unknown fields, duplicate YAML keys, unsupported versions, anchors/aliases, interpolation syntax, path traversal, symlink policy files and multiple YAML documents are rejected with a path-aware error.
+
+## Migration
+
+Schema versions are exact. GhostAPI does not coerce or silently upgrade an unknown version. A future version must add an explicit migration command that reads one known old version, emits a new file for review, and requires a separate validation step. It must never rewrite a policy while `ghostapi run` is active.

package/docs/providers/authoring-packs.md

@@ -0,0 +1,175 @@
+# Authoring Provider Packs
+
+Provider packs are the versioned contract layer for provider-specific behavior in GhostAPI. Resend and Stripe are migrated built-in packs. Twilio, GitHub, Discord, and OpenAI remain on the legacy adapter path until they can be migrated in small reviewed changes. Generic REST remains the fallback.
+
+## Scope And Trust Boundary
+
+Provider packs are built-in TypeScript modules compiled with GhostAPI. GhostAPI does not load uploaded, downloaded, or third-party executable provider code.
+
+A pack receives only explicit inputs:
+
+- detection receives a normalized path only;
+- parsing, validation, and handling receive the sanitized `NormalizedRequest`;
+- clock, ID generation, and a read-only state snapshot require explicit runtime capabilities;
+- no network, filesystem, environment, or secret capability is available to a pack.
+
+The source regression test rejects pack modules that import Node network/filesystem modules or access `process.env` or `fetch`. This is a maintenance boundary, not a secure JavaScript sandbox. Do not advertise arbitrary plugin isolation.
+
+## Public Interfaces
+
+The stable authoring surface is exported from `src/index.ts`:
+
+- `ProviderPack`;
+- `ProviderPackManifest`;
+- `ProviderConformanceFixture`;
+- `ProviderRuntime` and `ProviderRuntimeCapabilities`;
+- `ProviderScenario` and `ProviderScenarioStep`;
+- `ProviderWebhookHook`;
+- `createProviderRuntime()`;
+- `runProviderPackConformance()`.
+
+The request pipeline, registry lookup, prepared execution object, response headers, state persistence, cache, Fault Lab, dashboard events, and scenario persistence are internal interfaces. Packs must not import stores or server modules directly.
+
+## Required Contract
+
+Every pack declares:
+
+```ts
+export const examplePack: ProviderPack = {
+  name: "example",
+  displayName: "Example",
+  manifest: {
+    schemaVersion: 1,
+    name: "example",
+    displayName: "Example",
+    implementation: "pack",
+    packVersion: "1.0.0",
+    apiVersions: { default: "v1", supported: ["v1"] },
+    capabilities: {
+      detection: true,
+      requestParsing: true,
+      validation: true,
+      deterministicResponses: true,
+      stateTransitions: true,
+      providerErrors: true,
+      scenarios: false,
+      webhooks: false,
+      conformanceFixtures: true
+    }
+  },
+  detection: { priority: 100, matches: ({ path }) => path.startsWith("/example") },
+  parseRequest: (request) => request.body,
+  selectApiVersion: () => ({ version: "v1" }),
+  validate: () => null,
+  handleDeterministic: ({ runtime }) => ({
+    status: 200,
+    headers: { "content-type": "application/json" },
+    body: { id: runtime.requireCapability("idGenerator").create("example_mock") }
+  }),
+  createResponseHeaders: () => ({}),
+  transitionState: () => null,
+  stateful: false,
+  formatError: (details) => ({ error: { message: details.message } }),
+  promptHints: [],
+  scenarios: [],
+  conformanceFixtures: []
+};
+```
+
+The manifest is returned by `GET /api/providers`, shown in dashboard provider filters, and printed by `ghostapi providers list` and `ghostapi providers inspect <name>`.
+
+## API Version Selection
+
+Pack API versions are GhostAPI compatibility versions, not an automatic claim of full parity with a provider's live API. A pack must:
+
+1. declare one default version and all supported versions;
+2. select a version before request validation;
+3. return a provider-shaped `ProviderErrorDetails` for unsupported explicit versions;
+4. include version-sensitive request headers in cache identity;
+5. change `packVersion` when pack behavior changes and add a new API version when the simulated contract changes incompatibly.
+
+The Resend pack accepts `x-ghostapi-api-version: v1`. Successful responses include:
+
+```text
+x-ghostapi-provider-pack: resend@1.0.0
+x-ghostapi-api-version: v1
+```
+
+## Determinism
+
+Do not call `Date.now()`, `new Date()`, random generators, environment variables, or external services inside a pack. Request runtime capabilities explicitly:
+
+```ts
+const now = runtime.requireCapability("clock").now();
+const id = runtime.requireCapability("idGenerator").create("item_mock");
+```
+
+Tests must inject fixed implementations with `createProviderRuntime()`. `createResponseHeaders()` can add deterministic provider headers such as Stripe request IDs to successful or early-error responses. Asking for an undeclared capability fails with `Unknown provider capability: <name>`.
+
+## Validation And Errors
+
+`parseRequest()` converts the sanitized normalized request into the provider's internal request shape. `validate()` returns `null` or `ProviderErrorDetails`. Core formats the details through the registered provider error formatter.
+
+Keep validation order stable when migrating a public route. Error status, field names, messages, and provider shape are observable behavior.
+
+## State Transitions
+
+`transitionState()` describes persistence but does not write it. Core owns storage and requires keys to stay in the exact `<provider>:<id>` namespace. A pack that declares `stateful: true` executes under one atomic local-state transaction and can inspect the injected read-only snapshot while deciding its response. It still cannot access a store directly.
+
+A transition must be derived from the handled response and must not read ambient state. The conformance fixture should assert both the key and value. Core rejects cross-provider or empty keys before persistence.
+
+## Scenarios And Webhooks
+
+Pack scenarios use the shared `ProviderScenario` shape and are merged into the existing scenario registry. Scenario replay still installs deterministic method/path behaviors and runs before faults, validation, state, cache, and generation.
+
+`ProviderWebhookHook` is part of the authoring vocabulary, but no built-in pack currently advertises webhook capability. Do not set `webhooks: true` until event synthesis, signing, delivery timing, retries, and failure semantics have tests.
+
+## Conformance Fixtures
+
+Every migrated pack must provide at least one fixture that exercises its main mutation or read flow. Run it through the common harness:
+
+```ts
+const runtime = createProviderRuntime({
+  clock: { now: () => new Date("2026-08-06T12:00:00.000Z") },
+  idGenerator: { create: (prefix) => `${prefix}_fixture` }
+});
+
+runProviderPackConformance(examplePack, runtime);
+```
+
+The harness:
+
+1. selects an API version;
+2. parses and validates the fixture request;
+3. generates a deterministic response;
+4. runs the fixture response assertion;
+5. computes and validates the state transition;
+6. runs the fixture transition assertion.
+
+Malformed responses and wrong state keys must fail the harness.
+
+## Adding Or Migrating A Pack
+
+1. Add one pack under `src/providers/packs/`.
+2. Register it in the ordered built-in pack list in `src/providers/registry.ts`.
+3. Remove only that provider's legacy detection, validation, generation, prompt, and scenario branches.
+4. Preserve route detection precedence and generic REST fallback.
+5. Add conformance, provider regression, manifest API, state, cache, and provider-shaped error tests.
+6. Run `npm run typecheck`, `npm test`, and `npm run build`.
+7. Inspect built CLI output and package contents before release.
+
+## Migration Plan
+
+The remaining providers should move one at a time:
+
+| Order | Provider | Migration focus | Deferred risk |
+| --- | --- | --- | --- |
+| 1 | Twilio | Form parsing, validation, SID generation, error shape | Message status transitions and callbacks |
+| 2 | GitHub | Version header, deterministic issue/repository shapes, scenarios | Pagination and conditional requests |
+| 3 | OpenAI | API version policy, typed response families, list state | Streaming and token accounting |
+| 4 | Discord | Route/body detection and message shapes | Webhook and interaction semantics |
+| Done | Stripe | Core pack for customers, payment intents, payment methods, checkout sessions, refunds, pagination, and idempotency | Webhooks, subscriptions, invoices, disputes, and broader state-machine parity |
+
+Stripe now demonstrates the deeper stateful pack path. See [`stripe-core-pack.md`](stripe-core-pack.md) for the supported contract and limits.
+
+Generic REST should not become a provider pack. It remains the explicit fallback so unknown APIs continue to work without pretending to have a provider contract.

package/docs/providers/stripe-core-pack.md

@@ -0,0 +1,82 @@
+# Stripe Core Pack
+
+The built-in Stripe core pack is a deterministic local simulation for the most common payment workflows. It is not full Stripe compatibility and it never makes outbound network requests.
+
+## Version And Verification
+
+- Verified against Stripe's official API reference and Stripe Node SDK behavior on 2026-08-06.
+- GhostAPI compatibility API version: `2026-02-25.clover`.
+- Pack version: `1.1.0`.
+- Successful pack responses include `x-ghostapi-provider-pack: stripe@1.1.0`, `stripe-version: 2026-02-25.clover`, and a deterministic `request-id`.
+
+The version is an explicit GhostAPI compatibility contract, not a claim that all live Stripe endpoints or fields are supported.
+
+## Supported Operations
+
+| Resource | Operations |
+| --- | --- |
+| Customers | Create, retrieve, update, delete, list |
+| Payment Intents | Create, retrieve, update, confirm, list |
+| Payment Methods | Create minimal `card` method, retrieve, list |
+| Checkout Sessions | Create, retrieve, list |
+| Refunds | Create, retrieve, list |
+| Products | Create, retrieve, update, list |
+| Prices | Create recurring or one-time prices, retrieve, update, list |
+| Subscriptions | Create, retrieve, update, cancel, local `renew` control, list |
+| Invoices | Retrieve, pay, void, list |
+| Events | List, retrieve, and local signed delivery |
+
+List endpoints return Stripe-shaped `{ object: "list", data, has_more, url }` responses and accept `limit`, `starting_after`, and `ending_before` cursors.
+
+The pack accepts form-encoded nested parameters such as `metadata[source]=sdk` and `line_items[0][price_data][unit_amount]=2500`, as emitted by the Stripe Node SDK. JSON bodies are accepted for direct local clients.
+
+## Determinism And State
+
+Objects receive deterministic IDs, timestamps, and request IDs when a fixed runtime clock and ID generator are injected in tests. Normal runtime IDs remain unique across requests. Stateful requests run under GhostAPI's local atomic state transaction; the pack does not access storage itself.
+
+`Idempotency-Key` is represented only by a SHA-256-derived local digest in events and state. A repeated mutation with the same key and parameters returns the original response with `x-ghostapi-idempotency: REPLAY`. Reusing the key with different parameters returns a Stripe-shaped `idempotency_error`. Receipts expire after 24 hours, allowing a new mutation for the same key after the local retention window.
+
+## Billing Lifecycle
+
+Subscriptions use one recurring Price. Creating with `trial_period_days` creates a `trialing` subscription; `POST /v1/subscriptions/:id/renew` is a GhostAPI-only local test control that advances it. A normal renewal produces an Invoice, succeeded Payment Intent, and `active` subscription. `pm_card_chargeDeclined` produces a Stripe `card_error`, preserves an open Invoice, and sets the subscription to `past_due`; `POST /v1/invoices/:id/pay` can recover it. Cancellation marks the subscription `canceled`. Refunds create a `charge.refunded` event and update the local Payment Intent refund total.
+
+## Webhook Testing
+
+State transitions create persisted Stripe-shaped Events for subscription, invoice, payment-intent, and refund lifecycle changes. GhostAPI deliberately does not accept arbitrary webhook target URLs and never sends outbound webhook HTTP requests. Instead, tests pull a raw signed payload from:
+
+```text
+GET /v1/events/:event_id/deliver?delivery_mode=normal|duplicate|delayed|out_of_order|invalid_signature
+```
+
+The response includes `stripe-signature`, generated with HMAC-SHA256 over `timestamp.rawPayload`. The default local-only secret is `whsec_ghostapi_local_test_secret`; set `GHOSTAPI_STRIPE_WEBHOOK_SECRET` to use another test secret. The secret is not stored in state, events, scenarios, or responses. `duplicate` reliably returns the same event ID and payload on repeat calls, `delayed` accepts bounded `delay_ms` (0-10000), `out_of_order` reverses the event-list ordering, and `invalid_signature` corrupts the signature. Use the official `stripe.webhooks.constructEvent` verifier against the raw response body.
+
+Rate-limit (`429` + `Retry-After`), bounded delay/timeout simulation, and `5xx` behavior remain controlled through GhostAPI Fault Lab. These are injected before pack execution, so a client retry with an idempotency key exercises the normal atomic replay path after the fault is disabled.
+
+## Test Card Outcomes
+
+Use the Stripe test payment-method identifier `pm_card_chargeDeclined` (or legacy `tok_chargeDeclined`) when creating or confirming a Payment Intent to receive:
+
+```json
+{
+  "error": {
+    "type": "card_error",
+    "code": "card_declined",
+    "decline_code": "generic_decline"
+  }
+}
+```
+
+No PAN or CVC is required. If a direct client submits card-like fields, GhostAPI masks them before event or snapshot persistence. The returned synthetic Payment Method exposes only fixed non-sensitive card metadata such as `last4`.
+
+## Deliberate Limits
+
+- Disputes, Connect, payment links, Setup Intents, hosted Checkout, tax, proration, dunning, smart retries, and most Stripe APIs remain unsupported.
+- Unsupported operations return a diagnostic `invalid_request_error`; GhostAPI does not generate a fake success.
+- Checkout Sessions are local objects. Their returned URL is a local placeholder and not a hosted checkout page.
+- Payment Intent confirmation has a simplified state model: normal confirmation succeeds; the documented decline token fails.
+- Refunds support `payment_intent` or `charge` input, but only validate a referenced Payment Intent when one is supplied.
+- No live keys, PANs, CVCs, provider credentials, or real network traffic are retained or used.
+
+## Runnable SDK Example
+
+Start GhostAPI and run `examples/stripe-node/checkout-flow.mjs`. The example configures the official Node SDK with its documented host, port, protocol, and API-version client options, then verifies a locally delivered webhook using the SDK; no SDK source patch is required.