@terminals-tech/hierarchy

Typed DAG primitive for the Terminals ecosystem. Encodes tier, scope, primitive signature, and causal frame across every artifact.

Why

The Terminals ecosystem spans a concept (terminals), a domain (terminals.tech), a runtime (terminals-os), a network (terminals-network), an npm org (@terminals-tech/*), and N platforms (pathfind.tech, journeys.sh, resonant.sh, intuition, carl.camp, ...). Every artifact in this graph declares one terminals block in its package.json. This package gives you the types, the runtime validator, and a CLI to walk that graph.

Install

npm i -D @terminals-tech/hierarchy

CLI

The package ships tt (and terminals as an alias):

tt where                       # current node from cwd
tt walk --root <dir>           # full discovered DAG
tt validate                    # run invariants I1, I3, I7, I2-soft
tt diff <concept-A> <concept-B># primitive signature delta
tt render                      # emit Mermaid of the discovered DAG
tt codegen --out <path>        # emit deterministic typed .gen.ts module

Codegen

tt codegen walks the local DAG and emits a single self-contained TypeScript file with no runtime imports. Consumers (e.g. carl.camp /app/cabin) can import the constants directly without depending on node:fs or the walker:

npx tt codegen --root . --out src/lib/hierarchy.gen.ts --no-timestamp

import { NODES, ANCESTORS, TIER, type PackageName } from "./hierarchy.gen";

const myAncestors = ANCESTORS["@terminals/carlcamp"]; // type-safe
const tier = TIER["@terminals/carlcamp"];             // "platform"

Output is byte-stable: the same input always produces the same bytes (keys sorted alphabetically, no embedded timestamp when --no-timestamp is set). Snapshot tests in CI guard against accidental drift; refresh intentionally via CODEGEN_UPDATE_SNAPSHOTS=1 npm test.

Library

import {
  parseNode,
  signatureFromPrimitives,
  walkRepo,
  ancestors,
} from "@terminals-tech/hierarchy";

Subpath imports for tighter installs:

import type { Node } from "@terminals-tech/hierarchy/types";
import { walkNodeModules } from "@terminals-tech/hierarchy/walker";

Schema

Every participating package.json declares a terminals block:

{
  "terminals": {
    "concept": "carl",
    "tier": "platform",
    "parent": "domain",
    "scope": "camp",
    "primitive_signature": [true, true, true, true, true, false, false],
    "causal": { "progenitor": "tej", "emergent": "genesis" }
  }
}

Tier ladder (MECE):

concept → domain → { runtime | network | package | platform }

Per-concept scope is declared in ConceptScopes (see src/types.ts). Adding a new bifurcated platform is one line in that registry.

primitive_signature is a fixed-length 7-tuple of booleans, one bit per SDK primitive: [brain, machine, interface, interaction, session, period, routine].

Invariants

| # | Name | Enforcement | |---|---|---| | I1 | Tier adjacency | parseNode (runtime) + type system | | I2 | Scope correctness | type system; soft cap of 4 scopes warned at validate | | I3 | Primitive conservation under projection | tt validate (subset check across DAG) | | I4 | Causal frame literal identity | type system + zod literal | | I5 | Sibling-primitive union re-export | CI lint (separate workflow) | | I6 | Readout contraction over bifurcation | signatureSimilarity helper | | I7 | Concept↔SDK coupling | tt validate (union check) |

See docs/terminals-topology-spec-2026-04-24.md (carlcamp repo) for the full contract.

License

BUSL-1.1. © 2026 Intuition Labs LLC. Patent Pending.