@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/skills/_support/docs/principles/details/p041-backpressure-and-load-shedding.md

@@ -0,0 +1,141 @@
+# P041 — Backpressure and Load Shedding
+
+## Definition
+
+When demand is near capacity or is more than capacity, prevent system overload with a clear control response.
+**Backpressure** tells producers to decrease rate or concurrency.
+
+**Load shedding** rejects or removes selected work to decrease admitted work. The
+two controls prevent unlimited queues and resource exhaustion during overload.
+
+**Aliases:** flow control, overload signaling, admission shedding
+
+## Provenance
+
+**Classification:** established principle.
+
+Flow-control and data-stream systems give specified meanings to backpressure. Practitioners use
+load shedding in overload control. Athena uses these tools but does not give them the same
+meaning.
+
+## Decision rule
+
+Before saturation, limit upstream demand to sustainable capacity. If demand is more than capacity,
+reject work with low cost and a clear result. Do not accept unlimited work because there is a queue.
+
+## How to apply
+
+- Find the bottleneck. Examples are concurrency, queue depth, CPU, memory, and downstream
+  quota.
+- Give standard overload signals. Examples are demand pause, finite credits, HTTP 429 or 503,
+  and safe retry guidance.
+- Send downstream backpressure to producers. After a backpressure signal, do not retry with no wait.
+- Before overload stops the system, reject work. When requests have different value or cost, apply
+  specified priority and fairness rules.
+- Make rejection cost less than admitted work. If input parsing has a high cost, admit or reject
+  the request before parsing.
+- Monitor saturation, rejection rate, principals that receive rejections, tail latency, and recovery.
+- Do tests of continuous overload, bursts, callers with retry policies, and recovery after load
+  decreases.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Demand is near capacity"] --> B{"Can the producer decrease demand?"}
+    B -- Yes --> C["Send a backpressure signal"]
+    C --> D["Set demand to sustainable capacity"]
+    B -- No --> E["Apply priority and fairness rules"]
+    E --> F["When demand is more than capacity, reject work with low cost"]
+    F --> G["Keep service for admitted work"]
+```
+
+## Language examples
+
+Each example rejects work at capacity and gives a retry signal.
+
+### Python
+
+```python
+def admit(request, slots):
+    if not slots.acquire(blocking=False):
+        return Response(status=503, headers={"Retry-After": "1"})
+    try:
+        return serve(request)
+    finally:
+        slots.release()
+```
+
+### Rust
+
+```rust
+fn admit(request: Request, slots: &Semaphore) -> Response {
+    let Ok(_permit) = slots.try_acquire() else {
+        return Response::retry_after(503, 1);
+    };
+    serve(request)
+}
+```
+
+## Boundaries and tensions
+
+A buffer can absorb a short demand mismatch. If the buffer has no limit or producers receive no
+capacity signal, it gives no backpressure. Apply [P040](p040-bounded-resources.md) to all queues.
+
+If callers apply [P038](p038-bounded-retry.md), a retry response can help. If callers do not apply
+it, rejection can cause a retry storm.
+
+Load shedding is a control that rejects selected work. [P036](p036-graceful-degradation.md) gives a
+reduced but correct result. A system can use the two controls together.
+
+The two controls cannot operate without security controls or change a necessary correctness
+contract without a report.
+
+## Examples
+
+### Positive application
+
+A service is near its active request limit. It returns HTTP 503 with finite retry guidance for new
+refresh requests with low priority. It keeps reserved capacity for very important writes.
+
+After latency becomes stable, the service makes admission available again in steps.
+
+### Misuse or counterexample
+
+A consumer acknowledges messages immediately and keeps them in an unlimited local list. The
+producer receives no pressure signal. The process uses more memory until it stops.
+
+### Athena or agent workflow
+
+A coordinator at its concurrency limit keeps only a finite task queue. It defers or rejects
+low-priority tasks and tells the user about the constraint. It does not use all host or token capacity.
+
+## Related principles
+
+- [P036 — Graceful Degradation](p036-graceful-degradation.md)
+- [P038 — Bounded Retry](p038-bounded-retry.md)
+- [P040 — Bounded Resources](p040-bounded-resources.md)
+- [P042 — Fault Isolation / Bulkheads](p042-fault-isolation-bulkheads.md)
+
+## References
+
+### Source information
+
+- [Reactive Manifesto 2.0 (2014)](https://www.reactivemanifesto.org/) — practitioner statement that
+  connects message-based flow control, queue observation, and backpressure. It is
+  not the source of flow control.
+
+### Applicable information
+
+- [Reactive Streams 1.0.4](https://www.reactive-streams.org/) — specification and compatibility
+  kit for asynchronous stream operations with nonblocking backpressure.
+- [Google SRE, Addressing Cascading Failures](https://sre.google/sre-book/addressing-cascading-failures/)
+  — production guidance for load shedding, overload signals, finite queues, and reduced results.
+
+### More information
+
+- [Microsoft Azure, Throttling pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/throttling)
+  — guidance for load shedding before saturation, caller signals, fairness, and backpressure in a
+  call chain.
+
+[Back to the engineering principles catalog](../README.md#p041)

package/skills/_support/docs/principles/details/p042-fault-isolation-bulkheads.md

@@ -0,0 +1,140 @@
+# P042 — Fault Isolation / Bulkheads
+
+## Definition
+
+Partition workloads, dependencies, tenants, and resource pools. Failure or exhaustion in one
+partition must not use capacity or corrupt state for a different partition.
+
+Isolation limits a system-wide failure to a finite local failure.
+
+**Aliases:** bulkhead pattern, failure domains, cell-based isolation, blast-radius containment
+
+## Provenance
+
+**Classification:** established principle.
+
+Ship design is the source of the name. Michael Nygard's *Release It!* made the bulkhead pattern
+known to many software engineers. Fault isolation was available before this pattern name.
+
+## Decision rule
+
+Before components share resources, compare their failure risks, criticality, owners, and consumers.
+If shared failure can violate an objective, use isolated capacity and state boundaries.
+
+## How to apply
+
+- Set failure domains from business criticality and dependency paths. Do not use only
+  deployment topology.
+- If shared exhaustion can violate objectives, use different concurrency pools, queues, connection
+  pools, quotas, processes, accounts, regions, or credentials.
+- Reserve sufficient capacity for health, recovery, and very important traffic in each applicable
+  partition.
+- Isolate the data plane from control-plane failure. Do not let one tenant use all shared
+  capacity.
+- Monitor each partition independently. Keep an aggregate view of system health.
+- Do tests of exhaustion and failure in one partition. Make sure that different partitions continue.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Classify the failure risk of each workload"] --> B["Give each workload an isolated resource pool with finite capacity"]
+    B --> C1["Partition A serves its workload"]
+    B --> C2["Partition B serves its workload"]
+    C1 --> D{"Does Partition A have a failure or use all pool capacity?"}
+    D -- Yes --> E["Contain the failure in Partition A"]
+    D -- No --> G["Continue service in Partition A"]
+    E --> F["Partition B keeps capacity and state"]
+```
+
+## Language examples
+
+Each example uses a different concurrency pool for each dependency.
+
+### Python
+
+```python
+pools = {"search": Semaphore(8), "billing": Semaphore(2)}
+
+def call(name, request):
+    pool = pools[name]
+    if not pool.acquire(blocking=False):
+        return IsolatedOverload(name)
+    try:
+        return clients[name].send(request)
+    finally:
+        pool.release()
+```
+
+### Rust
+
+```rust
+fn call(kind: Kind, services: &Services, request: Request) -> Result<Response, Error> {
+    let partition = match kind {
+        Kind::Search => &services.search,
+        Kind::Billing => &services.billing,
+    };
+    let permit = partition.pool.try_acquire().map_err(|_| Error::IsolatedOverload)?;
+    let result = partition.client.send(request);
+    drop(permit);
+    result
+}
+```
+
+## Boundaries and tensions
+
+Isolation decreases available capacity and adds work to system operation. It can also decrease efficiency. If there is
+no specified failure mode or service objective, do not make a partition.
+
+A logical label is not a bulkhead when all partitions share one unlimited queue, connection pool,
+or credential.
+
+[P040](p040-bounded-resources.md) sets a limit for each pool. [P041](p041-backpressure-and-load-shedding.md)
+controls admission at capacity, and [P043](p043-circuit-breakers.md) stops calls to a dependency that failed.
+Use these controls together. They do not replace each other.
+
+## Examples
+
+### Positive application
+
+Calls to three downstream services use different connection pools and concurrency pools. One service
+stalls and uses all capacity in its pool. Health checks and calls to other services stay available.
+
+### Misuse or counterexample
+
+Tenants have different labels but share one executor and an unlimited queue. One tenant sends
+work with high cost and uses all capacity. The labels give no fault isolation.
+
+### Athena or agent workflow
+
+Different subagents receive finite task scopes and different write targets. One specialist that fails
+does not use all delegation slots or corrupt a different specialist result.
+
+## Related principles
+
+- [P036 — Graceful Degradation](p036-graceful-degradation.md)
+- [P040 — Bounded Resources](p040-bounded-resources.md)
+- [P041 — Backpressure and Load Shedding](p041-backpressure-and-load-shedding.md)
+- [P043 — Circuit Breakers](p043-circuit-breakers.md)
+
+## References
+
+### Source information
+
+- [Michael T. Nygard, *Release It!*, second edition](https://pragprog.com/titles/mnee2/release-it-second-edition/)
+  — a source that made bulkheads and other stability patterns known to many software engineers. Physical
+  bulkheads are older than computers.
+
+### Applicable information
+
+- [Microsoft Azure, Bulkhead pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/bulkhead)
+  — applicable guidance for different service instances and resource pools that isolate failure
+  cascades.
+
+### More information
+
+- [Microsoft Azure Well-Architected reliability patterns](https://learn.microsoft.com/en-us/azure/well-architected/reliability/design-patterns)
+  — includes bulkheads, throttles, retries, and circuit breakers as related reliability
+  controls.
+
+[Back to the engineering principles catalog](../README.md#p042)

package/skills/_support/docs/principles/details/p043-circuit-breakers.md

@@ -0,0 +1,148 @@
+# P043 — Circuit Breakers
+
+## Definition
+
+A circuit breaker monitors calls to a dependency. After measurements show continuous failure, it opens
+and rejects new calls without contact with that dependency.
+
+After a controlled recovery interval, it admits a finite probe set in a half-open state. A failed
+probe opens the breaker again. The breaker closes only after sufficient probes succeed.
+
+**Aliases:** dependency circuit breaker, open/half-open/closed breaker
+
+## Provenance
+
+**Classification:** established principle.
+
+Michael Nygard made the software pattern known to many engineers in *Release It!*. The electrical
+circuit breaker is the source of the software-pattern name. Related failure controls were available
+before the software pattern.
+
+## Decision rule
+
+If calls use resources without a caller result or overload a dependency, stop calls for a finite
+interval. If calls can cause system failure, use the same control. Do a recovery test with
+a finite probe set.
+
+## How to apply
+
+- Put the breaker at a failure-prone dependency boundary. If local business logic does not have
+  that failure risk, do not put the breaker at its boundary.
+- Use the dependency contract and measurements to select failure signals, observation
+  window, threshold, open time, and recovery criteria.
+- Give breaker state the correct scope. A global breaker can disable available partitions. A
+  breaker for one request does not have sufficient data from previous calls.
+- While the breaker is open, immediately return a clear failure or a specified fallback.
+- While the breaker is in the half-open state, use only a finite probe set. Prevent a recovery surge.
+- Record state transitions, rejected calls, probe results, and dependency identity.
+- Do tests of state oscillation, slow calls, recovery of only some calls, and interactions with retries.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    A["Closed: let calls continue"] -->|"Failure threshold met"| B["Open: reject calls"]
+    B -->|"Recovery interval expires"| C["Half-open: use finite probes"]
+    C -->|"Recovery criteria met"| A
+    C -->|"A probe fails"| B
+```
+
+## Language examples
+
+Each example records dependency failures and calls that succeed, but does not include permanent
+request errors in breaker state.
+
+### Python
+
+```python
+def call(breaker, client):
+    if (permit := breaker.try_acquire()) is None:
+        return Unavailable()
+    result = client.request()
+    if result.ok:
+        outcome = BreakerOutcome.SUCCESS
+    elif result.is_dependency_failure:
+        outcome = BreakerOutcome.FAILURE
+    else:
+        outcome = BreakerOutcome.IGNORED
+    permit.complete(outcome)
+    return result
+```
+
+### Rust
+
+```rust
+fn call(breaker: &Breaker, client: &Client) -> Result<Response, Error> {
+    let permit = breaker.try_acquire().ok_or(Error::Unavailable)?;
+    let result = client.request();
+    let outcome = match &result {
+        Ok(_) => BreakerOutcome::Success,
+        Err(error) if error.is_dependency_failure() => BreakerOutcome::Failure,
+        Err(_) => BreakerOutcome::Ignored,
+    };
+    permit.complete(outcome);
+    result
+}
+```
+
+## Boundaries and tensions
+
+A breaker is not a retry policy. Use [P038](p038-bounded-retry.md) for isolated transient errors.
+The breaker prevents more calls during continuous failure. A timeout from
+[P039](p039-bounded-waiting.md) limits the time for each call after breaker approval.
+
+If a small number of failures opens a breaker, the breaker can cause unavailability that is not necessary. If
+too many failures occur before it opens, it can cause a failure cascade.
+
+[P042](p042-fault-isolation-bulkheads.md) limits the effect before the breaker opens.
+Use [P036](p036-graceful-degradation.md) for each fallback response.
+
+## Examples
+
+### Positive application
+
+A client records timeouts in an observation window. At its tested threshold, the
+dependency-specific breaker opens. It rejects calls for a finite interval.
+
+Before the breaker makes traffic available again, it uses a small number of probes.
+
+### Misuse or counterexample
+
+One validation error opens an application-wide breaker for all tenants and endpoints. The error is
+a permanent request defect, not a dependency failure. The breaker disables available traffic.
+
+### Athena or agent workflow
+
+A dependency tool returns measured service-failure results. After a finite threshold, an Athena workflow
+stops calls to that tool and gives an unavailable-capability result.
+
+It does not use more tool calls or give a success result for a missing result.
+
+## Related principles
+
+- [P036 — Graceful Degradation](p036-graceful-degradation.md)
+- [P038 — Bounded Retry](p038-bounded-retry.md)
+- [P039 — Bounded Waiting](p039-bounded-waiting.md)
+- [P042 — Fault Isolation / Bulkheads](p042-fault-isolation-bulkheads.md)
+
+## References
+
+### Source information
+
+- [Michael T. Nygard, *Release It!*, second edition](https://pragprog.com/titles/mnee2/release-it-second-edition/)
+  — a source that made the circuit-breaker pattern known to many production-software engineers.
+- [Martin Fowler, “Circuit Breaker” (2014)](https://martinfowler.com/bliki/CircuitBreaker.html)
+  — practitioner information that identifies Nygard as the source and shows the state model.
+
+### Applicable information
+
+- [Microsoft Azure, Circuit Breaker pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker)
+  — applicable guidance for thresholds, open and half-open states, recovery probes, and retry
+  interaction.
+
+### More information
+
+- [Google SRE, Addressing Cascading Failures](https://sre.google/sre-book/addressing-cascading-failures/)
+  — context for how continuous calls, timeouts, and retries propagate failure.
+
+[Back to the engineering principles catalog](../README.md#p043)

package/skills/_support/docs/principles/details/p044-atomicity-where-possible.md

@@ -0,0 +1,141 @@
+# P044 — Atomicity Where Possible
+
+## Definition
+
+When state changes are one logical operation and share a supported transaction boundary, make the
+result all-or-none. All changes commit, or no change commits.
+
+If concurrent observers must not see state between steps, select the isolation level or atomic
+publication control independently.
+
+**Aliases:** all-or-nothing update, transactional commit, failure atomicity
+
+## Provenance
+
+**Classification:** established principle.
+
+Engineers used atomic transactions before the ACID acronym. Sources connect the ACID terms to a
+1983 paper. Härder and Reuter wrote that paper. It is not the source of all atomic-update types.
+
+## Decision rule
+
+If only some effects can commit and violate an invariant, use one supported transaction boundary
+for all effects.
+If the boundary cannot contain all effects, use custom reversal or compensation.
+
+If visibility of only some effects can violate an invariant, select isolation or atomic publication
+independently.
+
+## How to apply
+
+- Find the logical operation, applicable state, invariants, and observers.
+- Use supported transaction controls from the data store, file system, message broker, or platform.
+  Use an all-or-none commit.
+- Select an isolation level or atomic publication control that satisfies the visibility contract.
+- Limit transaction scope and time. While the transaction holds resources, do not make network
+  calls or wait for users.
+- Before the transaction, validate prerequisites. After reversible work, start irreversible
+  external effects.
+- If the system does not receive the commit acknowledgment, use a status query to resolve the unknown outcome.
+- Do tests of failures before commit, during commit, and after loss of the commit acknowledgment.
+  Do an isolation test with concurrent observation.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Find one logical operation"] --> B{"Can one supported transaction contain all effects?"}
+    B -- No --> C["Use durable completed-step data and compensation"]
+    B -- Yes --> D["Start the transaction"]
+    D --> E["Apply all state changes"]
+    E --> F{"Did all changes succeed?"}
+    F -- Yes --> G["Commit all changes"]
+    F -- No --> H["Abort without a committed change"]
+```
+
+## Language examples
+
+Each example commits the order, items, and inventory reservation as one transaction.
+
+### Python
+
+```python
+def place_order(db, order, items):
+    with db.transaction() as tx:
+        tx.insert_order(order)
+        tx.insert_items(order.id, items)
+        tx.reserve_inventory(items)
+```
+
+### Rust
+
+```rust
+fn place_order(db: &mut Database, order: &Order, items: &[Item]) -> Result<(), Error> {
+    let mut tx = db.transaction()?;
+    tx.insert_order(order)?;
+    tx.insert_items(order.id, items)?;
+    tx.reserve_inventory(items)?;
+    tx.commit()
+}
+```
+
+## Boundaries and tensions
+
+Atomicity has a specified scope. A database transaction does not include an email,
+remote API, file system, or second data store.
+
+If its effects are not in its boundary, do not identify a local transaction as an end-to-end atomic operation.
+
+When one supported boundary cannot contain the workflow, apply
+[P045](p045-compensation-where-atomicity-is-impossible.md) and durable completed-step data. Do not make a
+distributed transaction without platform support.
+
+[P033](p033-state-safe-failure-semantics.md) gives the failure requirement for all operations.
+Atomicity does not guarantee isolation, durability, or business correctness. Record these guarantees
+independently.
+
+## Examples
+
+### Positive application
+
+A database transaction inserts an order and its line items. It also updates the inventory
+reservation. All changes commit together, or no change commits.
+
+Readers with a contract for a stable multi-object view use an isolation level that supplies this view.
+
+### Misuse or counterexample
+
+Code commits an order and then publishes an event. It identifies the pair as one atomic operation. A failure
+between those steps causes committed state without its necessary event.
+
+### Athena or agent workflow
+
+An Athena workflow assembles and validates a document before target replacement. It keeps all
+related repository edits in one patch. It records validation failure before external publication.
+
+## Related principles
+
+- [P033 — State-Safe Failure Semantics](p033-state-safe-failure-semantics.md)
+- [P037 — Idempotency Before Retry](p037-idempotency-before-retry.md)
+- [P045 — Compensation Where Atomicity Is Impossible](p045-compensation-where-atomicity-is-impossible.md)
+- [P083 — Irreversible Actions Last](../README.md#p083)
+
+## References
+
+### Source information
+
+- [Härder and Reuter, “Principles of Transaction-Oriented Database Recovery” (1983)](https://doi.org/10.1145/289.291)
+  — a source for the ACID terms and transaction recovery framework.
+
+### Applicable information
+
+- [PostgreSQL 18, Transactions](https://www.postgresql.org/docs/18/tutorial-transactions.html)
+  — database documentation with examples of all-or-none updates, visibility, commit, and
+  reversal.
+
+### More information
+
+- [AWS Builders' Library, Making retries safe with idempotent APIs](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/)
+  — shows when an idempotency token and its related state change must use one atomic operation.
+
+[Back to the engineering principles catalog](../README.md#p044)