promptkit/docs/roadmap/implementation.md

# Structured Capacity Errors Implementation Plan

**Status:** Ready for implementation.

## Purpose

This document is the decision-complete implementation plan for
[structured capacity errors](capacity-errors.md). It is written for a
gpt-5.6-terra coding agent that will implement each stage in order.

The feature roadmap owns the motivation, public intent, compatibility policy,
security boundary, non-goals, and target end state. This plan owns the fixed
design, file-level work, implementation sequence, test ownership,
documentation updates, validation commands, and completion gates.

## Implementation Rules

- Complete the stages in order. Keep the repository compiling and the focused
  tests passing at every stage boundary.
- Preserve unrelated working-tree changes. In particular, retain the accepted
  feature roadmap and its existing future-catalog and downstream-wishlist
  edits.
- Follow every policy under `docs/policy/`, the task-specific reading guide in
  `docs/development.md`, and the accepted behavior in
  `capacity-errors.md`.
- Keep the supported error API in the root `promptkit` package. Internal
  capacity and use-case error values must not become consumer dependencies.
- Do not parse error strings. Carry the selected backend ID in an internal
  typed error and translate it explicitly at the root facade.
- Do not change capacity policy, admission ordering, limits, queueing, FIFO
  generation scheduling, lease lifetime, cancellation behavior, backend
  selection, prepared-handle lifecycle, or model-client classification.
- Do not classify provider throttling, HTTP 429 responses, quota failures, or
  injected-client errors as engine admission rejection.
- Preserve `errors.Is(err, ErrCapacityExceeded)` while adding discovery as
  `*CapacityError` through `errors.As`.
- Return a fresh public typed error for each rejected operation. Do not retain
  a request, pool, registry, endpoint, credential, execution target, or live
  capacity state in either typed error.
- Add only `BackendID` to the public type. Do not add limits, counts, queue
  depth, retry timing, retryability, transport status, provider state, or
  stable JSON.
- Keep tests lean and behavior-focused. Extend the existing internal admission,
  public capacity, prepared-execution, and root error-boundary tests instead of
  creating a parallel test framework.
- Update exact public contracts in declarations and GoDoc. Update current-state
  consumer and internal documentation only after the implementation exists.
- Do not add release notes, change a module version, create a release, commit,
  or tag as part of this work.

## Fixed Design

### Internal Admission Error

Add `internal/usecase/capacity_error.go` with this internal boundary type:

```go
// CapacityError identifies bounded admission rejected for one selected
// backend.
type CapacityError struct {
	BackendID string
}

func (e *CapacityError) Error() string
func (e *CapacityError) Unwrap() error
```

Although exported from an `internal` package so the root facade can recognize
it, this is not a public consumer API. Its methods have these fixed semantics:

- `Error` returns concise diagnostic wording that includes a quoted nonblank
  backend ID and the generic internal capacity classification;
- a nil receiver or blank `BackendID` produces only the generic internal
  capacity wording and does not panic;
- `Unwrap` always returns `capacity.ErrCapacityExceeded`, including for a nil
  receiver; and
- the value contains no cause field, request reference, capacity-manager
  reference, or other structured data.

Update `Runner.admitRun` in `internal/usecase/runner.go`:

1. retain the existing nil-admitter unlimited fallback;
2. call `RunAdmitter.Admit` exactly once with the selected backend ID;
3. when the returned error matches `capacity.ErrCapacityExceeded` and
   `backendID` is nonblank, return a newly allocated
   `&CapacityError{BackendID: backendID}`;
4. when a capacity error is returned for a blank backend ID by an invalid or
   test-only collaborator, pass that error through rather than manufacturing a
   structured value that violates the nonblank-ID guarantee;
5. pass every non-capacity error through unchanged; and
6. preserve the release function unchanged on success.

Do not move structured identity into `internal/capacity.Manager`. The use-case
boundary already knows the effective selected backend used by both `Run` and
`RunPrepared`, and it also normalizes any conforming `RunAdmitter`
implementation into the same error contract. The capacity package continues
to own only its generic internal sentinel and scheduling state.

Both ordinary and prepared execution already call `admitRun`; do not add
separate wrapping logic to `Run` or `RunPrepared`.

### Public Error Type

Add a root file named `capacity_error.go` containing:

```go
// CapacityError reports bounded admission rejected for a selected backend.
type CapacityError struct {
	BackendID string
}

func (e *CapacityError) Error() string
func (e *CapacityError) Unwrap() error
```

The declaration and method GoDoc must establish:

- engine-produced values identify only rejection at Promptkit's bounded
  `Run` or `RunPrepared` admission boundary;
- `BackendID` is the normalized registered backend ID used for routing and
  capacity, and endpoint overrides do not change it;
- every engine-produced value is nonnil and has a nonblank `BackendID`;
- provider errors, active-generation waiting, and caller cancellation are not
  represented by this type;
- `Error` wording is diagnostic and not a parsing contract;
- `Unwrap` returns `ErrCapacityExceeded`, so `errors.Is` and `errors.As` can be
  used together;
- a nil receiver and the zero value remain safe and unwrap to
  `ErrCapacityExceeded`, but a consumer-constructed value is not evidence that
  an engine rejected work;
- the type and its default Go encoding have no stable JSON contract; and
- consumers own returned values and may mutate `BackendID` without affecting
  engine state or another error.

Implement `Error` without exposing anything other than the public field and
the generic sentinel wording. For a nil receiver or blank field, return
`ErrCapacityExceeded.Error()`. Otherwise include the backend ID with `%q`.
Implement `Unwrap` as an unconditional return of `ErrCapacityExceeded`.

Do not add an exported constructor, custom formatter, `Is` method, JSON tags,
`MarshalJSON`, or `UnmarshalJSON`. Direct equality with
`ErrCapacityExceeded` is not a supported contract.

### Root Translation

Update `mapPublicError` in `errors.go` before its general
`publicErrorFor` mapping:

1. use `errors.As` to find an internal `*usecase.CapacityError`;
2. require the matched pointer to be nonnil and its `BackendID` to be
   nonblank;
3. return a newly allocated public
   `&CapacityError{BackendID: internalCapacityError.BackendID}` directly; and
4. otherwise continue through the existing general mapping.

Returning the public value directly is deliberate. It prevents the internal
typed error and internal sentinel from remaining in the returned error chain,
while the public value's `Unwrap` supplies the supported public sentinel.
Copy only the string field; do not retain the internal error.

Leave the existing `capacity.ErrCapacityExceeded` case in `publicErrorFor`.
It remains a defensive compatibility fallback for an unstructured internal
capacity error. No valid `Run` or `RunPrepared` capacity rejection should take
that fallback after this feature is implemented.

Do not reorder unrelated error categories. In particular, generation failures
remain `ErrLLMGenerate`, and the mapper must not infer admission rejection from
public sentinel text, provider errors, status codes, or arbitrary errors that
happen to expose a backend field.

### Operation Contracts

Update the existing declarations and GoDoc without duplicating the full type
contract:

- the `ErrCapacityExceeded` GoDoc in `engine.go` remains the broad
  classification contract and points consumers to `CapacityError` for the
  selected backend ID;
- `Engine.Run` states that engine admission rejection is discoverable as
  `*CapacityError` and still matches `ErrCapacityExceeded`;
- `Engine.RunPrepared` states the same and retains its one-attempt handle
  semantics;
- `doc.go` adds error values to its unstable-JSON category, lists
  `CapacityError` there, and notes that returned structured errors are
  caller-owned; and
- no operation other than `Run` and `RunPrepared` claims it can return this
  type.

Do not change method signatures or add the type to any stable JSON list.

### Error And Identity Boundaries

The implementation must preserve all of these distinctions:

| Condition | `errors.Is` identity | `errors.As` to `*CapacityError` |
| --- | --- | --- |
| Limited selected backend has no admission slot | `ErrCapacityExceeded` | Yes, with selected backend ID |
| Context is already done when admission checks it | Context error | No |
| Waiting for an active generation permit is canceled | `ErrLLMGenerate` and context error | No |
| Provider or injected client returns throttling or quota failure | `ErrLLMGenerate` and documented collaborator identity | No |
| Invalid request, profile, credential, artifact, render, or validation failure | Existing category | No |
| Unlimited backend or endpoint-only profile | No admission rejection | No |

For an ordinary `Run`, the ID is the effective registered backend selected
during preparation. For `RunPrepared`, it is the backend frozen in the claimed
handle. An endpoint override changes only the endpoint and must not change the
reported ID.

### Test Ownership

Extend existing tests at their current ownership boundaries.

`internal/capacity/manager_test.go` continues to own admission mechanics.
Strengthen `TestManagerAdmissionHonorsContextAndUnlimitedBackends` so the
limited pool is full before the canceled admission attempt. This protects the
existing rule that cancellation wins over capacity rejection without adding a
new overlapping test.

`internal/usecase/runner_test.go` owns attachment of selected identity.
Update `TestRunnerAdmissionFailureSkipsCompletionCollaborators` so:

- the capacity case uses `errors.As` to obtain the internal
  `*CapacityError`;
- its `BackendID` is exactly `"custom"`;
- the error still matches `capacity.ErrCapacityExceeded`;
- cancellation does not produce an internal `*CapacityError`; and
- the existing assertions about no partial result, no recategorization, the
  admitted backend ID, and skipped collaborators remain.

Replace the current string-content assertion with the structured assertion.
Do not test exact diagnostic wording.

`errors_internal_test.go` owns root translation. Add a focused test that maps
an internal `*usecase.CapacityError` and proves:

- the result is a public `*CapacityError` with the copied backend ID;
- it matches public `ErrCapacityExceeded`;
- it does not match unrelated public categories;
- it no longer exposes the internal typed error through `errors.As`; and
- mutating the source internal error after mapping does not alter the public
  value.

Retain the existing cancellation-preservation test.

`capacity_contract_test.go` owns assembled public `Run` behavior. Extend
`TestEngineRejectsRunBeforeCompletionWhenAdmissionIsFull` to prove:

- no partial result is returned;
- `errors.Is(err, promptkit.ErrCapacityExceeded)` still succeeds;
- `errors.As` obtains a nonnil `*promptkit.CapacityError`;
- `BackendID` is `"limited"` even though the rejected request overrides its
  endpoint;
- unrelated public categories do not match;
- mutating the returned error cannot alter a subsequent independently
  rejected call or its backend ID; and
- no completion collaborator or model client is invoked for rejected calls.

In the same established full-pool setup, add a canceled-context assertion
before releasing the admitted run. It must match `context.Canceled`, must not
match `ErrCapacityExceeded`, and must not be discoverable as
`*promptkit.CapacityError`. This is the root contract counterpart to the
manager precedence test.

Extend `TestCapacityExceededSentinelContract` to cover the public type's zero
and nil receiver behavior without asserting exact diagnostic wording:

- both safely match `ErrCapacityExceeded`;
- an ordinary populated value is discoverable by `errors.As`; and
- neither the sentinel nor the typed value matches unrelated categories.

`prepared_execution_contract_test.go` owns the public `RunPrepared` boundary.
In the capacity-rejection section of
`TestPreparedExecutionCredentialCapacityAndTimingBoundaries`, assert that
`errors.As` obtains `*promptkit.CapacityError` with backend ID `"limited"`.
Retain the existing assertions that the result is nil, the public sentinel
matches, the handle is consumed, and details remain available.

Do not duplicate manager limit matrices, generation FIFO tests, backend
registration tests, or provider-client failure matrices. Existing tests
already own those behaviors.

### Documentation Ownership

After the code and contract tests pass:

- update `docs/consumers/pkg-promptkit.md` in **Handle Errors** with a concise
  `errors.As` example that extracts `BackendID` while retaining the existing
  `errors.Is` guidance and application-owned retry policy;
- update `docs/internal/runner.md` to describe the internal typed attachment
  and root translation without reproducing the public API contract;
- update `docs/internal/capacity.md` to clarify that the manager still emits
  only its internal sentinel, while the runner attaches selected identity and
  the facade translates it;
- update `docs/internal/overview.md` only enough to include the root typed
  capacity error in the facade responsibility; and
- update `doc.go` and `engine.go` with the exact public contract described
  above.

Do not update `docs/formats.md`, the OpenAI-compatible integration contract,
backend configuration GoDoc, README, or release notes. This feature changes no
file format, provider wire request, backend configuration, project
orientation, or released-version record.

When implementation is complete:

- change `docs/roadmap/capacity-errors.md` to `**Status:** Complete.`;
- change `docs/roadmap/future.md` so it no longer describes structured
  capacity errors as active planning and simply records that no ideas await
  selection;
- change both downstream wishlist dispositions from accepted planning to
  implemented behavior, linking to the consumer guide's **Handle Errors**
  section rather than duplicating the contract; and
- change this document to `**Status:** Complete.`

The feature roadmap already contains no staged or prompt-level implementation
language. Do not add such language to it when changing its status.

## Stage 1: Carry Structured Identity Across Internal Admission

### Objective

Replace diagnostic-string-only backend context with a typed internal
admission error while preserving capacity mechanics and cancellation
precedence.

### Implementation Prompt

Implement only Stage 1 of
`docs/roadmap/implementation.md`.

1. Add `internal/usecase/capacity_error.go` with the exact internal type and
   method semantics in **Fixed Design**.
2. Update `Runner.admitRun` to create one fresh internal typed error for a
   nonblank selected backend when the admitter returns the internal capacity
   sentinel.
3. Update the existing runner admission-failure test to assert typed identity
   instead of inspecting diagnostic text.
4. Strengthen the existing capacity-manager context test so cancellation is
   checked while the limited pool is already full.
5. Run the focused formatting and validation below.

Do not modify the root public API, root mapper, capacity-manager production
code, public contract tests, or current-state documentation in this stage.

### Focused Validation

Run from the repository root:

```sh
gofmt -w internal/usecase/capacity_error.go \
  internal/usecase/runner.go \
  internal/usecase/runner_test.go \
  internal/capacity/manager_test.go
go test ./internal/capacity ./internal/usecase
git diff --check
```

### Completion Gate

Stage 1 is complete only when:

- capacity rejection from `admitRun` is discoverable as the internal
  `*usecase.CapacityError`;
- its ID comes from the effective backend passed to admission;
- both `Run` and `RunPrepared` use the shared boundary without duplicate
  wrapping;
- `errors.Is` still reaches `capacity.ErrCapacityExceeded`;
- cancellation and other admission errors remain untyped and unchanged;
- capacity scheduling production code is untouched; and
- focused tests and whitespace checks pass.

## Stage 2: Expose And Protect The Public Error Contract

### Objective

Add the minimal public typed error, translate the internal value without
leaking it, and protect ordinary and prepared consumer behavior.

### Implementation Prompt

Implement only Stage 2 of
`docs/roadmap/implementation.md` after Stage 1 satisfies its completion gate.

1. Add root `capacity_error.go` with the exact public type, methods, and GoDoc
   in **Fixed Design**.
2. Update `errors.go` to translate a nonblank internal typed error into a
   fresh public value before general sentinel mapping.
3. Preserve the existing unstructured capacity fallback and all unrelated
   error-mapping order.
4. Update `engine.go` and `doc.go` with the exact operation, ownership, and
   unstable-JSON contracts.
5. Add the focused root translation test.
6. Extend the existing external-package `Run`, sentinel, cancellation, and
   `RunPrepared` contract assertions described under **Test Ownership**.
7. Run the focused formatting and validation below.

Do not change admission policy, add provider classification, introduce a
constructor or serialization contract, or update durable prose documentation
in this stage.

### Focused Validation

Run from the repository root:

```sh
gofmt -w capacity_error.go errors.go engine.go doc.go \
  errors_internal_test.go capacity_contract_test.go \
  prepared_execution_contract_test.go
go test . -run \
  'TestMapPublicError|TestEngineRejectsRunBeforeCompletionWhenAdmissionIsFull|TestCapacityExceededSentinelContract|TestPreparedExecutionCredentialCapacityAndTimingBoundaries'
go test .
git diff --check
```

### Completion Gate

Stage 2 is complete only when:

- every assembled `Run` and `RunPrepared` admission rejection is discoverable
  as a public `*CapacityError` with the selected backend ID;
- the public error unwraps only to `ErrCapacityExceeded` and does not retain
  the internal typed error;
- existing broad `errors.Is` handling remains valid;
- endpoint overrides do not change the reported ID;
- cancellation at a full pool remains a context error and not a capacity
  error;
- caller mutation cannot affect another rejection or engine state;
- provider, generation, and unrelated error mappings remain unchanged; and
- focused and complete root-package tests pass.

## Stage 3: Update Canonical Documentation And Validate

### Objective

Make the implemented structured error discoverable, reconcile temporary
planning state, and complete repository-wide validation.

### Implementation Prompt

Implement only Stage 3 of
`docs/roadmap/implementation.md` after Stages 1 and 2 satisfy their completion
gates.

1. Update the consumer and internal documents listed under
   **Documentation Ownership**. Keep exact API guarantees in GoDoc and use
   prose documents for task guidance and implementation boundaries.
2. Update the feature-roadmap, future-catalog, implementation-plan, and
   downstream-wishlist statuses and links exactly as specified above.
3. Follow every added or changed Markdown link and confirm its file and
   heading target.
4. Run the full validation sequence.
5. Inspect the complete diff for scope, sensitive data, and repository
   hygiene.
6. Only after every check passes, leave both roadmap statuses as `Complete`
   and rerun `git diff --check`.

Do not add a release document, new example, new public package, retry policy,
transport mapping, or duplicate API reference.

### Full Validation

Run from the repository root:

```sh
gofmt -w internal/usecase/capacity_error.go \
  internal/usecase/runner.go \
  internal/usecase/runner_test.go \
  internal/capacity/manager_test.go \
  capacity_error.go errors.go engine.go doc.go \
  errors_internal_test.go capacity_contract_test.go \
  prepared_execution_contract_test.go
gofmt -l $(git ls-files '*.go')
go test ./...
go test -race ./...
go vet ./...
go build ./...
go run ./examples/go-library/prepare
git diff --check
git status --short
```

The `gofmt -l` command must print no paths. The maintained example must remain
offline and require no real credential or provider.

Inspect the final state and confirm:

- only files required by this feature and pre-existing user changes are
  present;
- no credential, private source content, endpoint, workspace file, local
  replacement, generated binary, or unrelated formatting change was added;
- the root declaration and GoDoc own the exact public contract;
- consumer guidance summarizes the workflow and links to the canonical API;
- internal documents describe responsibility without redefining the public
  contract;
- no current-state document claims Promptkit owns retry, backoff, transport,
  logging, or metrics policy;
- no roadmap retains staged language outside this implementation plan; and
- no release, commit, or tag was created.

### Completion Gate

Implementation is complete only when:

- every Stage 1 and Stage 2 gate remains satisfied;
- ordinary and race-enabled tests pass;
- vet, build, formatting, the offline example, Markdown links, and whitespace
  checks pass;
- public, consumer, and internal documentation agree on the implemented
  boundary;
- future-catalog and downstream-wishlist dispositions no longer describe the
  feature as pending;
- both roadmap statuses are `Complete`;
- the working tree contains no unintended files or changes; and
- the repository is ready for maintainer review without a commit or release
  having been created by this plan.

## Open Questions

None. The accepted feature roadmap and fixed design above fully specify the
implementation boundary.