@uluops/taxonomy

The UluOps failure taxonomy — 4 domains, 28 modes, 5 severities — as a single importable artifact, generated from the canonical root in uluops-specifications.

Data and predicates only. No filesystem, no network, no node: imports.

Install

Requires Node >= 20. Public — no npm auth needed, unlike most of the @uluops scope.

npm install @uluops/taxonomy

Ships dual ESM/CJS with per-condition type declarations, so import and require both resolve correctly under moduleResolution node16/nodenext and bundler.

import { MODES, DOMAINS, SEVERITIES, isCanonicalMode, parseFailureCode } from '@uluops/taxonomy';

isCanonicalMode('STR-OMI');              // true
isCanonicalMode('SEM-VAL');              // false — well-formed, correct-looking, not a member
parseFailureCode('SEM-INC/H');           // { domain: 'SEM', mode: 'INC', severity: 'H' }

Why this package exists

The mode set was reimplemented in 40 hard-coded regexes across 9 repos, in three shapes, and none of them checked membership. Format-checking accepts any well-formed string, so 242 invented codes reached the datastore. This package is the one place the mode set lives in runtime code, and isCanonicalMode is the question the regexes could not ask.

Exports

| Export | Notes | |---|---| | TAXONOMY_VERSION | "1.1.0" — the taxonomy's version, not this package's | | DOMAINS / MODES / SEVERITIES | frozen arrays; every entity carries code, name, label | | FAILURE_CODE_PATTERN | format only. Accepts STR-ZZZ/C. Use for shape, not membership | | STRICT_MODE_PATTERN | membership-exact. The 28 modes alternated literally | | isCanonicalMode(code) | membership. Takes the fully-qualified STR-OMI form | | parseFailureCode(s) | splits SEM-INC/H; format-only; returns null, never throws | | deriveDomain(modeCode) | systems spec §5.2. Fully-qualified form only — see below | | severityFromCode(letter) | 'H' → 'high' | | modeDescription(code) | canonical prose for a member, null otherwise |

name and label are both shipped, on purpose

name is the canonical lowercase/kebab form the root and ops-uluops-api hold (type-error). label is title-case, derived by one rule — title-case each hyphen-separated word — and is what ops-uluops-dashboard renders (Type Error). The two consumer groups disagree beyond casing and neither can be silently migrated, so both are exported. There is no override table; the plain rule reproduces the factory's existing labels for all 28 modes, including the two that read as irregular.

SEVERITIES is ordered, and the order is the contract

[C, H, M, L, I], most severe first. There is deliberately no weight field: the one in ops-uluops-api is row.sort_order renamed, and no consumer reads it. Ordering by array position says the same thing without freezing a misnomer into a 1.0.0 contract.

deriveDomain requires the fully-qualified code

INC is both STR-INC (inconsistency) and SEM-INC (incorrectness), so a bare three-letter mode cannot derive a domain. This matters in practice: the wire field named failure_mode in ops-uluops-api and both MCP servers carries the bare form, while systems spec §5.2 derives from the qualified form. Same word, two things. Passing a bare mode returns null rather than guessing.

Building

The package holds no committed copy of the mode set. src/generated.ts is gitignored and emitted at build time from uluops-specifications/specs/systems/failure-taxonomy-schema-defs-v1_1_0.json, located by marker search. Without that checkout the build exits 2 and says why — a committed fallback would make this a second canonical source, which is the condition the package exists to end.

A standalone clone of this repo cannot build, test, or verify. build, test and verify all route through generate, so all three exit 2 without the sibling checkout. That is the designed tradeoff, not a bug — but it means contributing requires the workspace, not just this repo. npm install alone is unaffected.

The workspace layout the marker search looks for is a directory containing both uluops-specifications/ and packages/:

uluops/                        <- this is what --root means
├── uluops-specifications/
└── packages/
    └── -uluops-taxonomy/      <- you are here

If your checkout lives elsewhere, pass --root=<that directory> — the parent, not the uluops-specifications checkout itself:

node scripts/generate.mjs --root=/path/to/uluops     # correct
node scripts/generate.mjs --root=/path/to/uluops/uluops-specifications   # wrong; the error says so

npm run build            # generate → tsc ESM → tsc CJS → stamp type markers
npm test                 # 19 assertions; every acceptance paired with a rejection
npm run verify:tarball   # gate §5.5 — pack, install, import BY NAME as ESM and as CJS
npm run verify           # all three

verify:tarball installs the tarball into a throwaway project and imports '@uluops/taxonomy' by name. It does not import the unpacked directory: a directory import bypasses the exports map, so it would pass with a broken exports map — which is exactly what the first version of that check did.

It also typechecks the installed tarball from three consumer configurations (cjs+node16, esm+node16, esm+bundler), because runtime resolution and type resolution are different resolvers. 1.0.0 shipped with require() working perfectly and tsc rejecting the same call; every runtime probe was green.

Publishing requires the sibling checkout too. prepublishOnly runs verify, which runs generate — so npm publish only works from the workspace. A CI-based publish needs a uluops-specifications checkout step or a --root= argument, not just the npm script.

Adding a mode

Edit the canonical root, then rebuild. Never edit src/generated.ts, and never add an entry here that the root does not have. The generator refuses to emit when the root is internally inconsistent — a mode in the enum with no description, a domain with no description, a mode whose prefix is not a declared domain, an empty set, or a taxonomy version that disagrees across the three places it is written.

Scope

Tools that scan, verify, or rewrite the workspace live in ulu-scripts taxonomy, not here. ops-uluops-dashboard is a Next.js app and @uluops/core is a client SDK; neither can absorb a corpus scanner.

Licence

Two parts, and the distinction is deliberate — see LICENSE.

• The taxonomy data (MODES, DOMAINS, SEVERITIES, TAXONOMY_VERSION and anything derived from them) is CC BY-NC-SA 4.0, © Ulu Labs Inc. — the same terms it carries in Uluops/failure-taxonomy and at uluops.ai/schemas/failure-taxonomy/.
• The software (the five predicates, the types, the build tooling) is MIT, © UluOps, Inc.

In practice: importing this package and calling its predicates in commercial software is fine. Redistributing the mode set as a work — republishing it, shipping it as your own reference, building a competing taxonomy from it — is NonCommercial and ShareAlike.