---
name: failure
description: Run copy-only CARBON failure-injection and error-condition testing against an app, API, service, build, configuration, dataset, or artifact. Use when the user asks to inject faults, force errors, break a copy, test resilience or recovery, simulate dependency failures, corrupt inputs, remove files, or see how a system handles failure without modifying the original.
user-invocable: false
---

# CARBON Failure

Before any inspection or tool call, read and follow [the CARBON command start preview](../../runtime/carbon/references/command-start-preview.md). Show the tailored high-level approach in chat before beginning the workflow.

Exercise failure behavior in an isolated copy. Never modify an original artifact or use a live/shared system as the fault target.

Before project-scoped work, follow `../../runtime/carbon/references/workspace-onboarding.md`. Call `carbon_set_preferences` with no arguments and honor the returned execution context without exposing credentials.

## Establish the safety boundary

1. Identify the exact artifact scope, expected environment, recovery oracle, and user-visible behavior under failure.
2. Treat the user's invocation as authorization for reversible fault injection **inside the generated CARBON sandbox only**. It does not authorize production traffic, shared-data mutation, real notifications, real charges, denial of service, privilege escalation, destructive external calls, or third-party writes.
3. Default to local synthetic identities, fixtures, stubs, loopback services, browser request routing, and test-only configuration. If the only available target is live, shared, or production, stop after producing a planned failure matrix.
4. Never simulate disk exhaustion by filling a disk, simulate network stress with unbounded load, or revoke real credentials. Model those conditions with quotas, mocks, resource limits, or test doubles.

## Make an isolated copy

Create a baseline and working sandbox before any injection:

```bash
../../bin/carbon-runtime failure prepare --root <project-root> --scope "<feature or artifact>"
```

Use one or more `--artifact <relative-path>` arguments when the scope is narrower than the project. CARBON stores the run under `.carbon/failure/`, excludes VCS metadata, dependencies, caches, secrets, and prior CARBON output, skips symlinks, and hashes the originals.

Only read or change files beneath the returned `sandboxDir`. Do not edit through symlinks, bind mounts, shared volumes, or paths that resolve outside it. Install dependencies and start services from the sandbox, using non-production configuration and isolated ports/data stores.

## Design and inject failures

Capture a clean baseline first. Then inject one primary fault at a time and reset the sandbox between cases:

```bash
../../bin/carbon-runtime failure reset --run-dir <run-dir>
../../bin/carbon-runtime failure inject --run-dir <run-dir> --kind <kind> --path <sandbox-relative-path>
```

Supported deterministic file faults include `delete`, `empty`, `truncate`, `invalid-json`, `corrupt`, `malformed-utf8`, `permission-denied`, `replace-text`, and `rename`. Supply the required kind-specific arguments shown by `failure inject --help`.

For runtime and integration conditions, register a scenario and implement it with a local stub, proxy, browser route, test double, sandbox environment override, or process control:

```bash
../../bin/carbon-runtime failure scenario --run-dir <run-dir> --type <type> --target <dependency-or-boundary> --method "<local injection method>"
```

Cover the relevant families:

- invalid, empty, truncated, oversized, corrupted, wrong-type, Unicode, and missing inputs;
- missing configuration, expired test credentials, denied permissions, read-only storage, quota limits, and interrupted writes;
- HTTP 4xx/5xx/429, latency, timeout, connection reset, malformed or partial responses, offline transitions, dependency loss, retry exhaustion, stale caches, and incompatible contracts;
- startup failure, process restart, partial initialization, concurrency interruption, clock skew, and recovery after the fault clears;
- UI loading, empty, error, retry, offline, expired-session, partial-render, and interrupted-submit states.

Do not count a registered scenario as executed. Run the copied app/API, observe actual behavior, and record the result:

```bash
../../bin/carbon-runtime failure observe --run-dir <run-dir> --scenario-id <id> --status <passed|failed|blocked|partial> --actual "<observed behavior>" --evidence "<path or reference>"
```

For every case assess containment, correctness, user message, retry behavior, idempotency, partial mutation, cleanup, observability, sensitive disclosure, data integrity, recovery, and behavior after restart. Distinguish product defects from test-double, environment, or automation failures.

## Prove the original stayed unchanged

After every major batch and before reporting, run:

```bash
../../bin/carbon-runtime failure verify --run-dir <run-dir>
../../bin/carbon-runtime failure complete --run-dir <run-dir>
```

If verification reports any original change, stop, identify the exact path, label the run unsafe, and do not claim copy-only execution. Never overwrite the stored baseline to hide drift.

## Report

Publish the baseline, copied artifacts, exclusions, skipped symlinks, injected faults, observed handling, recovery results, original-integrity verification, unexecuted scenarios, defects, and residual risk. Planned or blocked cases remain explicit.

Follow [command result reporting](../../runtime/carbon/references/command-result-reporting.md). Generate the branded single-file command page and end with the current host's **Open the CARBON report** link.
