{"_id":"@airtrafficcontrol/errors","name":"@airtrafficcontrol/errors","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@airtrafficcontrol/errors","version":"0.0.1","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","dependencies":{"@airtrafficcontrol/types":"0.0.1"},"scripts":{"build":"tsc --build"},"_id":"@airtrafficcontrol/errors@0.0.1","description":"Structured error hierarchy for the ATC domain. Every error class extends `AtcError` and carries the `RULE-*` identifier of the violated specification rule. No external dependencies.","_integrity":"sha512-1/BJ9RvPhtWoZJaKIEmTQoIwbmkAfrBZaRxQ7azS1gmJIErHkEpQsjkV2kiYincJ1x+2wt0h6PWVdyLKs3WBLQ==","_resolved":"/private/var/folders/n5/tzqmrds50218kyrpz8166v3w0000gn/T/ab5615d8dac3234565ea84a1e886b72b/airtrafficcontrol-errors-0.0.1.tgz","_from":"file:airtrafficcontrol-errors-0.0.1.tgz","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-1/BJ9RvPhtWoZJaKIEmTQoIwbmkAfrBZaRxQ7azS1gmJIErHkEpQsjkV2kiYincJ1x+2wt0h6PWVdyLKs3WBLQ==","shasum":"81f1a6d3f9e2cd35fb4d4237d596b46685ce77c1","tarball":"https://registry.npmjs.org/@airtrafficcontrol/errors/-/errors-0.0.1.tgz","fileCount":107,"unpackedSize":80081,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFeApccO2LZnyytZ0ns9mCY1CRNapCwLnmbi6f24V+2+AiAH+eVIN99KEMhlHylzBVjt8aLixuyj+nc6QZNX6nwKog=="}]},"_npmUser":{"name":"mfoulks200","email":"mfoulks1@gmail.com"},"directories":{},"maintainers":[{"name":"mfoulks200","email":"mfoulks1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/errors_0.0.1_1776908431225_0.6115470282147732"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-23T01:40:31.111Z","0.0.1":"2026-04-23T01:40:31.362Z","modified":"2026-04-23T01:40:31.617Z"},"maintainers":[{"name":"mfoulks200","email":"mfoulks1@gmail.com"}],"description":"Structured error hierarchy for the ATC domain. Every error class extends `AtcError` and carries the `RULE-*` identifier of the violated specification rule. No external dependencies.","readme":"# @airtrafficcontrol/errors\n\nStructured error hierarchy for the ATC domain. Every error class extends `AtcError` and carries the `RULE-*` identifier of the violated specification rule. No external dependencies.\n\n## Installation\n\n```bash\npnpm add @airtrafficcontrol/errors\n```\n\nThis is an internal workspace package (`workspace:*`).\n\n## Error Hierarchy\n\n```\nAtcError (base)\n  ├── CraftError             RULE-CRAFT-*\n  ├── SeatAssignmentError    RULE-SEAT-*\n  ├── ControlsError          RULE-CTRL-*\n  ├── BlackBoxError          RULE-BBOX-*\n  ├── LifecycleError         RULE-LIFE-*\n  ├── VectorError            RULE-VEC-*, RULE-VRPT-*\n  ├── ChecklistError         RULE-LCHK-*\n  ├── EmergencyError         RULE-EMER-*\n  ├── TowerError             RULE-TOWER-*, RULE-TMRG-*\n  ├── ConfigValidationError  RULE-CFG-1 (placeholder)\n  └── UnknownConfigKeyError  RULE-CFG-1 (placeholder)\n```\n\n## API Reference\n\n### `AtcError`\n\nBase error class for all ATC rule violations. Extends `Error`.\n\n```typescript\nnew AtcError(message: string, ruleId: string)\n```\n\n| Property | Type | Description |\n|---|---|---|\n| `message` | `string` | Human-readable description of what went wrong |\n| `ruleId` | `string` | The `RULE-*` identifier that was violated |\n| `name` | `string` | `\"AtcError\"` (overridden by subclasses) |\n\n### `CraftError`\n\nThrown when a `RULE-CRAFT-*` invariant is violated. Covers craft creation and property constraints: unique callsign, required cargo, required category, required captain.\n\n### `SeatAssignmentError`\n\nThrown when a `RULE-SEAT-*` invariant is violated. Covers seat assignment constraints: certification requirements, captain cardinality, jumpseat restrictions.\n\n### `ControlsError`\n\nThrown when a `RULE-CTRL-*` invariant is violated. Covers control handoff and modification constraints: jumpseat exclusion, modification without controls, control transfer protocol violations.\n\n### `BlackBoxError`\n\nThrown when a `RULE-BBOX-*` invariant is violated. Covers append-only log constraints: mutating existing entries, missing black box on lifecycle events.\n\n### `LifecycleError`\n\nThrown when a `RULE-LIFE-*` invariant is violated. Covers lifecycle transition constraints: invalid transitions, transitions from terminal states, missing preconditions.\n\n```typescript\nnew LifecycleError(message: string, ruleId: string, context?: LifecycleErrorContext)\n```\n\n#### `LifecycleErrorContext`\n\n| Property | Type | Description |\n|---|---|---|\n| `from` | `string?` | The state the craft was transitioning from |\n| `to` | `string?` | The state the craft was transitioning to |\n\n### `VectorError`\n\nThrown when a `RULE-VEC-*` or `RULE-VRPT-*` invariant is violated. Covers vector sequencing, reporting, and flight plan constraints.\n\n### `ChecklistError`\n\nThrown when a `RULE-LCHK-*` invariant is violated. Covers landing checklist constraints: execution authority, item failures, go-around triggers.\n\n### `EmergencyError`\n\nThrown when a `RULE-EMER-*` invariant is violated. Covers emergency declaration constraints: captain-only authority, required black box entry, return-to-origin protocol.\n\n### `TowerError`\n\nThrown when a `RULE-TOWER-*` or `RULE-TMRG-*` invariant is violated. Covers tower merge coordination: vector report verification, branch freshness, merge sequencing.\n\n### `ConfigValidationError`\n\nThrown when a config payload fails schema validation. Used by the daemon's layered config stores to surface Zod issues to REST and WebSocket clients.\n\n```typescript\nnew ConfigValidationError(scope: ConfigScope, issues: readonly ConfigIssue[], message?: string)\n```\n\n| Property | Type | Description |\n|---|---|---|\n| `scope` | `ConfigScope` | Which configuration tier failed validation (`\"global\" \\| \"profile\" \\| \"project\" \\| \"agent\"`) |\n| `issues` | `readonly ConfigIssue[]` | Zod-compatible issue list describing each failure |\n\nTagged with the placeholder rule id `RULE-CFG-1` pending a formal rule family in `docs/specification.md`.\n\n### `UnknownConfigKeyError`\n\nThrown when `LayeredConfigStore.unset()` or a `DELETE /config/.../:key` call names a key that is not part of the target scope's declared schema.\n\n```typescript\nnew UnknownConfigKeyError(scope: ConfigScope, key: string)\n```\n\n| Property | Type | Description |\n|---|---|---|\n| `scope` | `ConfigScope` | Which configuration tier owns the unknown key |\n| `key` | `string` | The offending key |\n\nTagged with the placeholder rule id `RULE-CFG-1`.\n\n### `ConfigScope`\n\nType alias — `\"global\" | \"profile\" | \"project\" | \"agent\"`. Matches the tiers in the layered config system.\n\n### `ConfigIssue`\n\nMinimal `{ code, path, message }` shape compatible with Zod issues. Declared locally so this package remains free of a runtime `zod` dependency.\n\n## Usage\n\n```typescript\nimport { AtcError, CraftError, LifecycleError } from \"@airtrafficcontrol/errors\";\n\n// Throwing a domain error\nthrow new CraftError(\"Craft callsign is required\", \"RULE-CRAFT-1\");\n\n// Catching domain errors by type\ntry {\n  transitionCraft(craft, CraftStatus.InFlight);\n} catch (error) {\n  if (error instanceof LifecycleError) {\n    console.error(`Lifecycle violation: ${error.ruleId} — ${error.message}`);\n  }\n}\n\n// Catching any ATC error\ntry {\n  someOperation();\n} catch (error) {\n  if (error instanceof AtcError) {\n    console.error(`ATC rule violated: ${error.ruleId}`);\n  }\n}\n```\n\n## Source Files\n\n| File | Contents |\n|---|---|\n| `src/base.ts` | `AtcError` base class |\n| `src/craft.ts` | `CraftError` |\n| `src/seat.ts` | `SeatAssignmentError` |\n| `src/controls.ts` | `ControlsError` |\n| `src/black-box.ts` | `BlackBoxError` |\n| `src/lifecycle.ts` | `LifecycleError`, `LifecycleErrorContext` |\n| `src/vector.ts` | `VectorError` |\n| `src/checklist.ts` | `ChecklistError` |\n| `src/emergency.ts` | `EmergencyError` |\n| `src/tower.ts` | `TowerError` |\n| `src/config.ts` | `ConfigValidationError`, `UnknownConfigKeyError`, `ConfigScope`, `ConfigIssue` |\n\n## Related Packages\n\n- [`@airtrafficcontrol/types`](../types/) — Domain types referenced in error messages\n- [`@airtrafficcontrol/core`](../core/) — Throws these errors when rules are violated\n- [`@airtrafficcontrol/validation`](../validation/) — Throws `SeatAssignmentError` on invalid assignments\n- [`@airtrafficcontrol/tower`](../tower/) — Throws `TowerError` and `EmergencyError`\n- [`@airtrafficcontrol/daemon`](../daemon/) — Throws `ConfigValidationError` and `UnknownConfigKeyError` from its layered config stores\n","readmeFilename":"README.md","_rev":"1-319cb623c718aaa0d31b60440c6d3875"}