@homericintelligence/athena-opencode 0.5.0 → 0.5.2

package/skills/_support/docs/principles/details/p037-idempotency-before-retry.md

@@ -0,0 +1,139 @@
+# P037 — Idempotency Before Retry
+
+## Definition
+
+An operation that can occur more than one time must have one intended effect for equivalent
+requests. An equivalent control can give this guarantee.
+
+Such controls include an idempotency key, duplicate detection, a conditional write, or
+reconciliation. After a timeout, the first try outcome is unknown. The try can change state.
+
+**Aliases:** retry safety, idempotent operation, duplicate suppression
+
+## Provenance
+
+**Classification:** established principle.
+
+Mathematics and protocol design have used idempotence for many years. Athena puts idempotency first.
+Retry occurs after idempotency. Athena cannot identify one source for that phrase.
+
+## Decision rule
+
+If an operation has side effects and duplicate execution is safe, automatic retry can occur. A
+different request identifier for each logical operation lets the system detect duplicate execution
+and recover from it.
+
+## How to apply
+
+- Classify the operation effect. Record semantic equivalence for requests.
+- If a requested-state operation satisfies domain rules, select that design.
+- Accept an idempotency key for resource writes, charges, message sends, or publications. Connect the key to caller
+  identity and normalized request data.
+- When possible, record the key and state change in one atomic operation. Record a stable duplicate
+  response.
+- Record key scope, retention, conflict behavior, and treatment of late or concurrent duplicates.
+- If results do not show that the operation is safe, do not retry. Give status queries or
+  reconciliation procedures.
+- Do tests with duplicate requests, concurrent requests, timeouts, late requests, and key conflicts.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Receive a request with a stable key"] --> B{"Is there a recorded key?"}
+    B -- Yes --> C{"Is the request equivalent?"}
+    C -- No --> D["Return a conflict"]
+    C -- Yes --> E["Return the recorded result"]
+    B -- No --> F["Commit the effect and key in one atomic operation"]
+    F --> E
+```
+
+## Language examples
+
+Each example returns one job for each equivalent key and payload pair.
+
+### Python
+
+```python
+def create_job(store, key, payload):
+    outcome = store.atomic_get_or_create(key, payload)
+    if outcome.kind is CreateKind.CONFLICT:
+        raise Conflict(key)
+    return outcome.job_id
+```
+
+### Rust
+
+```rust
+fn create_job(store: &Store, key: Key, payload: Payload) -> Result<JobId, Error> {
+    match store.atomic_get_or_create(&key, &payload)? {
+        CreateResult::Created(job) | CreateResult::Replayed(job) => Ok(job.id),
+        CreateResult::Conflict => Err(Error::Conflict(key)),
+    }
+}
+```
+
+## Boundaries and tensions
+
+Idempotency decreases duplicate risk. A finite try count is also necessary. Apply
+[P038](p038-bounded-retry.md) and [P039](p039-bounded-waiting.md). These controls have different
+functions.
+
+If the idempotency record and state change use different transactions, the state change can occur
+only in part. If one transaction can contain the two effects, use [P044](p044-atomicity-where-possible.md).
+
+If one transaction cannot contain the two effects, use reconciliation and
+[P045](p045-compensation-where-atomicity-is-impossible.md). A key with a nonequivalent request is a conflict.
+
+## Examples
+
+### Positive application
+
+A job API accepts a client request identifier. The server uses one atomic operation to record the
+normalized payload, job identifier, and response. Equivalent requests return the same job.
+
+A request with the same key and a different payload receives a conflict response.
+
+### Misuse or counterexample
+
+A client retries `charge-card` after each timeout without a request key. The first try can
+succeed before the timeout. The retry can charge the customer two times.
+
+### Athena or agent workflow
+
+An Athena workflow does not receive the response from an issue creation request. Before a retry, it
+examines issues for the specified title and marker. It can also use the host idempotency control.
+
+The workflow has no results that show that the first request failed.
+
+## Related principles
+
+- [P033 — State-Safe Failure Semantics](p033-state-safe-failure-semantics.md)
+- [P038 — Bounded Retry](p038-bounded-retry.md)
+- [P039 — Bounded Waiting](p039-bounded-waiting.md)
+- [P044 — Atomicity Where Possible](p044-atomicity-where-possible.md)
+- [P045 — Compensation Where Atomicity Is Impossible](p045-compensation-where-atomicity-is-impossible.md)
+
+## References
+
+### Source information
+
+- [RFC 2068, HTTP/1.1 section 9.1.2 (1997)](https://www.rfc-editor.org/rfc/rfc2068.html#section-9.1.2)
+  — a 1997 HTTP standards-track definition of idempotent methods and duplicate request effects.
+  HTTP is not the source of idempotence.
+
+### Applicable information
+
+- [RFC 9110 section 9.2.2, Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2)
+  — applicable HTTP semantics for requests that the client automatically sends again.
+- [AWS Builders' Library, Making retries safe with idempotent APIs](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/)
+  — practitioner guidance for client request identifiers, semantic equivalence, late requests, and
+  atomic idempotency records.
+
+### More information
+
+- [Microsoft Azure, Retry pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/retry)
+  — shows why a response can fail after work succeeds. It also shows why retry policy must
+  include idempotency.
+
+[Back to the engineering principles catalog](../README.md#p037)

package/skills/_support/docs/principles/details/p038-bounded-retry.md

@@ -0,0 +1,145 @@
+# P038 — Bounded Retry
+
+## Definition
+
+Retry only a transient failure from a category in the dependency contract. If a specified try
+limit, elapsed-time limit, or shared deadline expires, stop.
+
+When callers can retry at the same time, put time between tries and wait for a random time. Obey
+server guidance that controls retry. A retry policy must not cause an unlimited wait or load amplification.
+
+**Aliases:** retry budget, limited retry, backoff and jitter
+
+## Provenance
+
+**Classification:** established principle.
+
+Network and production systems have used finite retry and random backoff for many years. Athena
+cannot identify one source for this rule.
+
+## Decision rule
+
+If the contract classifies the result as a transient failure and the operation is safe, retry. The caller
+budget must also have capacity for a new try. If not, return the failure.
+
+## How to apply
+
+- Use the dependency contract to select retryable error categories. Do not use a catch-all error
+  category.
+- Give one layer ownership of one total retry budget for nested calls.
+- Use a finite try count or deadline. When many callers can retry at the same time, use an
+  exponential wait and random variation.
+- Before the caller deadline, obey protocol signals such as `Retry-After`.
+- Apply [P037](p037-idempotency-before-retry.md) to operations with side effects.
+- After cancellation, permanent failure, or budget exhaustion, stop. If the next try cannot complete
+  in the remaining time, stop.
+- Record try count and last outcome as correlated telemetry. Do tests of the policy during
+  overload.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Try the operation"] --> B{"Did the operation succeed?"}
+    B -- Yes --> C["Return success"]
+    B -- No --> D{"Is this a transient failure, and is the operation safe?"}
+    D -- No --> E["Return the failure"]
+    D -- Yes --> F{"Does the shared budget have capacity for a new try?"}
+    F -- No --> E
+    F -- Yes --> G["Wait for a bounded random time"]
+    G --> A
+```
+
+## Language examples
+
+Each example limits a transient read failure to three tries.
+
+### Python
+
+```python
+def fetch(client):
+    for attempt in range(3):
+        result = client.fetch()
+        if result.ok or not result.transient:
+            return result
+        if attempt < 2:
+            sleep(jitter(2**attempt))
+    return result
+```
+
+### Rust
+
+```rust
+fn fetch(client: &Client) -> Result<Data, Error> {
+    for attempt in 0..3 {
+        match client.fetch() {
+            Err(error) if error.is_transient() && attempt < 2 => delay(jitter(2_u64.pow(attempt))),
+            result => return result,
+        }
+    }
+    unreachable!()
+}
+```
+
+## Boundaries and tensions
+
+A circuit breaker from [P043](p043-circuit-breakers.md) prevents more calls during continuous
+dependency failure. Use retry for an isolated transient failure. A clear sequence and one budget are necessary for
+the combination.
+
+Retries at each stack layer increase the number of tries and violate the single-owner error policy. The first
+retry can occur immediately and correct a connection race. If more retries occur immediately, they
+can add load at the same time.
+
+Retry wait must obey [P039](p039-bounded-waiting.md). A retry queue stays subject to
+[P040](p040-bounded-resources.md).
+
+## Examples
+
+### Positive application
+
+An idempotent read receives a specified transient status. The client makes at most three tries
+before the request deadline. It uses a random exponential wait and obeys `Retry-After`.
+
+The client returns the last failure after budget exhaustion.
+
+### Misuse or counterexample
+
+An SDK retries five times. Its service wrapper retries each SDK call five times. A job worker also
+retries without a limit. One request causes a retry storm.
+
+### Athena or agent workflow
+
+A coordinator retries a transient transport failure from a subagent only while its iteration
+budget and time budget permit the retry. It immediately gives a validation-failure or
+permission-denial result.
+
+## Related principles
+
+- [P037 — Idempotency Before Retry](p037-idempotency-before-retry.md)
+- [P039 — Bounded Waiting](p039-bounded-waiting.md)
+- [P040 — Bounded Resources](p040-bounded-resources.md)
+- [P043 — Circuit Breakers](p043-circuit-breakers.md)
+
+## References
+
+### Source information
+
+- [Marc Brooker, “Exponential Backoff and Jitter” (2015)](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)
+  — practitioner analysis of contention from retries at the same time and random retry wait. Athena
+  is not the source of retry limits.
+
+### Applicable information
+
+- [AWS Builders' Library, Timeouts, retries, and backoff with jitter](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/)
+  — production guidance for timeouts, retry multiplication, token budgets, wait, and random
+  variation.
+- [Microsoft Azure Well-Architected Framework, transient faults](https://learn.microsoft.com/en-us/azure/well-architected/design-guides/handle-transient-faults)
+  — applicable guidance that gives finite retries and random exponential wait.
+
+### More information
+
+- [Google SRE, Addressing Cascading Failures](https://sre.google/sre-book/addressing-cascading-failures/)
+  — shows how retries increase overload and cause cascade failure.
+
+[Back to the engineering principles catalog](../README.md#p038)

package/skills/_support/docs/principles/details/p039-bounded-waiting.md

@@ -0,0 +1,151 @@
+# P039 — Bounded Waiting
+
+## Definition
+
+Each external wait must have termination behavior that satisfies its risk policy. This rule is for
+operations, locks, queues, processes, asynchronous results, and delegated tasks.
+
+Use a deadline, timeout, cancellation signal, or other bound from measurements. The caller must
+show the difference between success, cancellation, timeout, and failure.
+
+**Aliases:** deadlines, timeouts, finite blocking, wait budget
+
+## Provenance
+
+**Classification:** established principle.
+
+Concurrent systems and distributed systems used timeouts and deadlines for many years. Athena
+cannot identify one source for this rule.
+
+## Decision rule
+
+When a different actor controls the operation end or different actors use a resource, set the
+maximum wait.
+Specify the safe outcome for budget expiration.
+
+## How to apply
+
+- Use one end-to-end deadline that all downstream calls inherit. Do not use a different timeout
+  construction for each hop.
+- Select budgets from service objectives, measured latency, operation value, and cleanup cost.
+- Send cancellation and remaining time to child operations.
+- After timeout, if an ownership contract gives permission, stop work or let it continue
+  independently. A timeout does not show that remote effects stopped.
+- Release locks, slots, and temporary resources on each terminal path.
+- Do tests of deadline expiration, cancellation races, slow dependencies, and success near each
+  side of the boundary.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Get the cancellation signal before the wait"] --> B["Set the deadline"]
+    B --> C["Pass the signal to the operation"]
+    C --> D{"What occurs?"}
+    D -- Success --> E["Keep the completed result"]
+    D -- "Cancellation request" --> F["Send the cancellation signal"]
+    F --> G["Keep the cancellation result"]
+    D -- "Deadline expires" --> H["Send the cancellation signal"]
+    H --> I["Keep the timeout result"]
+    D -- Failure --> J["Keep the failure result"]
+    E --> K["Release the owned resources"]
+    G --> K
+    I --> K
+    J --> K
+    K --> L["Return the terminal result"]
+```
+
+## Language examples
+
+Each example uses a specified cancellation contract, limits the wait, and returns a different
+result for each terminal result.
+
+### Python
+
+```python
+def await_result(future):
+    try:
+        return Completed(future.result(timeout=2.0))
+    except CancelledError:
+        return Cancelled()
+    except TimeoutError:
+        return TimedOut()
+    except OperationError as error:
+        return Failed(error)
+```
+
+### Rust
+
+```rust
+fn await_result(rx: Receiver<WorkerEvent>) -> Outcome {
+    match rx.recv_timeout(Duration::from_secs(2)) {
+        Ok(WorkerEvent::Completed(value)) => Outcome::Completed(value),
+        Ok(WorkerEvent::Cancelled) => Outcome::Cancelled,
+        Ok(WorkerEvent::Failed(error)) => Outcome::Failed(error),
+        Err(RecvTimeoutError::Timeout) => Outcome::TimedOut,
+        Err(RecvTimeoutError::Disconnected) => Outcome::Unavailable,
+    }
+}
+```
+
+## Boundaries and tensions
+
+A timeout limits the caller wait. Callee execution can continue without a bound. Before a retry of
+work with side effects, use [P037](p037-idempotency-before-retry.md), status reconciliation, or
+compensation.
+
+Very short timeouts cause failure that is not necessary. Systems without timeouts can cause resource leaks and
+failure cascades. Use measurements to set the budget.
+
+Use the budget with [P040](p040-bounded-resources.md). Many finite waits must not use all system
+capacity.
+
+## Examples
+
+### Positive application
+
+A request has a two-second deadline. Each downstream call receives the remaining budget. After
+cancellation, each call stops owned child work and returns a different deadline result.
+
+### Misuse or counterexample
+
+A worker calls an external process without a timeout. The stalled process holds a concurrency slot
+without a limit. The finite queue cannot continue.
+
+### Athena or agent workflow
+
+A coordinator gives delegated research a specified deadline and examines the result status. After a
+timeout, it records the missing results. It obeys the host contract for task termination or
+release.
+
+It does not wait without a limit or give a result that it did not receive.
+
+## Related principles
+
+- [P037 — Idempotency Before Retry](p037-idempotency-before-retry.md)
+- [P038 — Bounded Retry](p038-bounded-retry.md)
+- [P040 — Bounded Resources](p040-bounded-resources.md)
+- [P043 — Circuit Breakers](p043-circuit-breakers.md)
+
+## References
+
+### Source information
+
+- Athena does not identify one source. Deadline and timeout controls were in use before RPC
+  systems and occur in literature about operating systems, concurrency, and networks.
+
+### Applicable information
+
+- [gRPC, Deadlines](https://grpc.io/docs/guides/deadlines/) — official guidance for deadline
+  selection, deadline propagation, and server work termination after expiration.
+- [gRPC, Cancellation](https://grpc.io/docs/guides/cancellation/) — official guidance for a client
+  that sends cancellation when it no longer wants an RPC result. It gives guidance for cancellation
+  propagation. Some language handlers must implement this propagation.
+
+### More information
+
+- [Google SRE, Addressing Cascading Failures](https://sre.google/sre-book/addressing-cascading-failures/)
+  — gives information about expired client deadlines, server work that cannot give a result to the
+  client, resource exhaustion, and failure cascades.
+
+[Back to the engineering principles catalog](../README.md#p039)

package/skills/_support/docs/principles/details/p040-bounded-resources.md

@@ -0,0 +1,138 @@
+# P040 — Bounded Resources
+
+## Definition
+
+Each resource with changing demand must have a specified limit or a physical bound from measurements.
+Examples are queues, buffers, concurrency, recursion, batches, memory, disk, work that the system did not complete, agent
+iterations, tokens, and tool calls.
+
+The system must give a controlled response at the bound.
+
+**Aliases:** resource limits, finite capacity, quotas
+
+## Provenance
+
+**Classification:** established principle.
+
+Operating systems, queueing theory, and safe design use resource limits. Athena does not identify
+one source for this language-neutral rule.
+
+## Decision rule
+
+For each work unit that can occur more than one time, find the capacity owner. Set a limit from
+measurements. Set admission, rejection, cleanup, and recovery behavior at that limit.
+
+## How to apply
+
+- Make a resource inventory for each request, tenant, process, and dependency.
+- If item costs have large differences, limit the item count and total item cost.
+- Use platform quotas, finite executors, and finite queues. If the platform has no applicable
+  control, use a custom counter.
+- Reserve capacity or use different pools for very important work. Low-value demand must not use all
+  capacity.
+- Make rejection cost less than admitted work. Give a clear overload signal.
+- Monitor saturation, rejected work, queue age, and time at the limit. After workload changes,
+  change limits.
+- Do tests of the system at each important limit and at values more than that limit. Make sure that
+  the system releases all temporary resources and operates correctly after the limit condition.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["A request uses a finite resource"] --> B{"Is capacity available?"}
+    B -- Yes --> C["Admit the request"]
+    C --> D["Use and release the resource"]
+    B -- No --> E["Reject with an overload result"]
+    E --> F["Keep capacity for admitted work"]
+```
+
+## Language examples
+
+The examples limit queue capacity and reject new work at capacity.
+
+### Python
+
+```python
+queue = Queue(maxsize=100)
+
+def submit(task):
+    try:
+        queue.put_nowait(task)
+        return Accepted()
+    except Full:
+        return Overloaded()
+```
+
+### Rust
+
+```rust
+fn task_queue() -> (SyncSender<Task>, Receiver<Task>) {
+    sync_channel(100)
+}
+
+fn submit(tx: &SyncSender<Task>, task: Task) -> Outcome {
+    match tx.try_send(task) {
+        Ok(()) => Outcome::Accepted,
+        Err(TrySendError::Full(_)) => Outcome::Overloaded,
+        Err(TrySendError::Disconnected(_)) => Outcome::Unavailable,
+    }
+}
+```
+
+## Boundaries and tensions
+
+A large finite limit does not help if available capacity is less than the limit. A small limit can
+cause incorrect results or low availability when it does not admit bursts that satisfy the contract.
+
+Use measurements and service objectives to select limits. Do not use constants without measurements.
+
+[P041](p041-backpressure-and-load-shedding.md) gives the demand response at capacity.
+[P042](p042-fault-isolation-bulkheads.md) prevents one consumer from exhaustion of capacity for a
+different consumer. [P039](p039-bounded-waiting.md) limits resource retention time. Bounded
+Resources limits resource count and capacity.
+
+## Examples
+
+### Positive application
+
+A worker pool limits active tasks and queue depth. At capacity, it rejects new work with a retryable
+overload response. It records queue age and reserves capacity for health operations.
+
+### Misuse or counterexample
+
+An API keeps each request in an unlimited memory queue during a downstream outage. The API uses more
+memory until the process stops. The process then has no backlog data.
+
+### Athena or agent workflow
+
+A swarm workflow sets limits on concurrent specialists, iterations, tool calls, and tokens. At a
+limit, it returns an accurate result for completed work or a failure. It does not make more work.
+
+## Related principles
+
+- [P039 — Bounded Waiting](p039-bounded-waiting.md)
+- [P041 — Backpressure and Load Shedding](p041-backpressure-and-load-shedding.md)
+- [P042 — Fault Isolation / Bulkheads](p042-fault-isolation-bulkheads.md)
+- [P043 — Circuit Breakers](p043-circuit-breakers.md)
+
+## References
+
+### Source information
+
+- Athena does not identify one primary source. Operating systems and network services used quotas
+  and capacity limits for many years. Athena applies the practice to software and agent resources.
+
+### Applicable information
+
+- [CWE List 4.20, CWE-770: Allocation of Resources Without Limits or Throttling](https://cwe.mitre.org/data/definitions/770.html)
+  — applicable weakness definition, effects, and controls for unlimited resource allocation.
+- [Google SRE, Addressing Cascading Failures](https://sre.google/sre-book/addressing-cascading-failures/)
+  — production guidance for queue, memory, thread, CPU, and file-descriptor exhaustion.
+
+### More information
+
+- [Microsoft Azure, Throttling pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/throttling)
+  — guidance for limits for the first saturated resource and for admission control.
+
+[Back to the engineering principles catalog](../README.md#p040)