# ChatGPT operations incremental delivery

audience: AI coding agents first.

## Decision

Ship smallest safe vertical slice first. NEVER wait for project execution, delivery, cluster operations, and break glass to mature together.

First release MUST be read-only and useful: authenticated ChatGPT Web can call gateway context, list registered projects, and retrieve its own audit receipts. No repository content, mutation, job launch, Git, deployment, cluster mutation, secrets, shell, or break glass.

## Why this slice

- Uses current trust-plane WIP instead of discarding it.
- Exercises complete public path: edge/app identity → raw-body validation → admission → typed route → adapter → authenticated audit → opaque response.
- Carries no execution credential and creates no host/cluster mutation risk.
- Provides deployable Action contract and production wiring needed by every later release.
- Keeps every deferred capability absent, not hidden behind flags.

## Release ladder

Stop at first unsafe or red rung. Each release MUST be independently deployable, observable, reversible, and useful.

### R0 — Gateway trust-plane canary

External operations:

- `getOperatorContext`
- `listProjects`
- `getAuditReceipt`

Required behavior:

1. Accept raw `Uint8Array` request body only.
2. Measure intrinsic typed-array byte length before decode/parse. Caller-defined properties MUST NOT affect limits.
3. Verify edge identity and independent application credential.
4. Route every request through expiry, nonce, idempotency, rate, and concurrency admission before adapter dispatch.
5. Make durable settlement retryable for same chosen outcome; conflicting settlement MUST fail.
6. Append accepted/rejected/terminal audit receipt; one terminal receipt per operation.
7. Return opaque registered IDs only. NEVER return host paths, credentials, environment, arbitrary metadata, or repository content.
8. Expose only R0 routes in OpenAPI and runtime registry.

R0 carries no project, Git, deployment, cluster, workstation, or break-glass credential.

Acceptance:

- focused contract/auth/admission/audit tests pass;
- package tests and typecheck pass without warnings;
- adversarial tests prove parsed-object bypass, typed-array length spoof, replay, idempotency conflict, expired request, rate excess, concurrency excess, adapter bypass, settlement retry, cross-caller audit isolation, and secret/path absence;
- installed endpoint and GPT Action schema smoke pass through real authentication path;
- required `gpt-5.6-sol/low` review approves.

### R1 — Read-only project inspection

Add registered workspace listing, bounded file read/search, status, and diff. No mutation. Use opaque project/workspace IDs, canonical-path confinement, symlink escape rejection, output bounds, and no ignored/secret files.

### R2 — Isolated build and test

Add fixed registered workflows in restricted k3s Jobs. No arbitrary command, Git credential, deployment credential, cluster administration, or host mount.

### R3 — Compare-and-swap edit

Add bounded read/write/patch with expected content hash and worktree lease. No shared-main mutation.

### R4 — Task-branch Git delivery

Add commit and exact-repository task-branch push with operation-scoped credential. No landing or deployment.

### R5 — Guarded landing and local deployment

Add guarded landing, landed-commit-only local deployment, installed proof, and recorded known-good rollback.

### R6 — Read-only cluster visibility

Add typed health, resources, logs, and usage with narrow read-only RBAC.

### R7 — Typed cluster mutation

Add registered restart, rollback, scale, release, node, and recovery operations. Require external exact approval for high-impact actions.

### R8 — Break glass

Add externally activated, expiring, scoped exceptional authority only after routine typed operations are proven.

## Components and seams

### Public request boundary

`dispatch(identity, rawBody: Uint8Array): Promise<OpaqueResponse>`

- derives intrinsic byte length from typed-array internal slots;
- rejects before JSON parsing when oversized;
- exact envelope schema only;
- passes parsed request to admission internally; no public parsed-request overload.

### Admission-wrapped route

Every registered route owns schema, rate, concurrency, and adapter. Registry MUST call admission before adapter. Adapter MUST receive only validated payload plus opaque identity/operation context.

### Settlement

Accepted request chooses exactly one terminal action: complete with canonical outcome or abandon. First durable attempt may fail. Same chosen action MUST retry safely; different action MUST fail. Lease release MUST be idempotent and retryable.

### Audit

Global and per-operation authenticated chains. Storage compare-and-append MUST atomically verify both heads and terminal uniqueness. Retrieval MUST prove scope, signatures, roots, ordering, continuity, and bounds while allowing global interleaving.

## Error handling

Use stable opaque error codes. Authentication, malformed body, oversize body, replay, idempotency conflict, expired request, rate/capacity exhaustion, unavailable storage, and unknown operation MUST fail closed. Responses and receipts MUST NOT include raw backend errors, paths, secrets, or internal service names.

## Testing strategy

1. Unit-test each boundary and race deterministically.
2. Integration-test public raw-body dispatch through admission, adapter, settlement, and audit. Direct adapter tests do not satisfy R0.
3. Test negative authority: every deferred route is absent and returns stable `operation_not_found`.
4. Test installed endpoint with real service configuration and authentication.
5. Run package tests/typecheck plus required independent review before deploy.

## Architecture decisions

- Collapse first release to one read-only vertical slice; broad architecture remains roadmap, not release gate.
- Keep trust plane shared because every public route requires identical security controls.
- Do not add feature flags for deferred authority. Absent code/routes are safer and easier to prove.
- Do not ship repository read in R0; registry metadata is enough to validate end-to-end operation without filesystem authority.