README.md

README.md is a file in GovLab Context. 211 lines of code and 0 definitions.

<!-- Auto-generated 2026-10-04T19:04Z v13 -->

# @govlab/context

<!-- concern:overview -->

## Purpose

One queryable-ontology framework spanning knowledge collections over a shared kernel.

The kernel under `core/` holds the concerns every ontology repeats:

- a walk-free loader over each collection's `configuration/<collection>/data/` folder with a `{ category, records }` fold (`core/loaders/ontology.loader.ts`)
- the JSON coercion primitives (`core/normalizers/field.normalizer.ts`) and one `slugify`
- a generic `createOntology<R>` engine, and the `BaseOntology<R, F>` base class a record collection extends for its retrieval surface
- a `defineOntologyFace` self-registration contract with a dependency-ordered `foldFaces` runner
- the canonical force vocabulary, and the closed vocabularies each collection declares

Each collection is data plus a thin specialization that registers itself:

- `arch` holds principle records with a typed relationship graph (`requires`, `reinforces`, `enables`, `conflicts_with`, `tensions_with`) and `resolve` and refactor recipes.
- `algo` holds contract-based algorithms with intent, invariant, flow, BNF, `composes` and `force`. They resolve by closure, cluster and force, and join to arch by `principleRef`.
- `pag` holds the Pattern Abstract Grammar: the keyword ontology, the document-type contracts, a regex-free structural parser, a well-formedness validator and the meta-templates.
- `lex` holds the lexicon, whose `Term` records `{ id, name, kind, definition, aliases }` give every arch relationship edge a resolvable, kind-typed, defined home.
- `reason` is a non-record reasoning meta-ontology: the derivation-loop procedure with its mandatory teleology, verification and termination gates, the domain-agnostic pattern reasoning-space, and a governed test-surface sub-collection under `configuration/reason/data/`. Every algorithm grammar grounds its gates in a reason axis through `grounds`.

The kind vocabulary has one source of truth in `configuration/constants/kind.constants.ts`. `KIND_TAXONOMY` is the ordered decision procedure with a per-kind discriminator and definition signatures, and `RELATION_RANGES` and the gate derive from it.

`createGovlabContext()` folds the registered collections, wires the cross-ontology joins, exposes `kindTaxonomy()`, and adds a self-validating resolution gate (`validateResolution()` and `runtime/entrypoints/ontology.entrypoint.ts`). The gate checks that every arch edge resolves to a Principle or Term, the polarity law (anti-patterns only through `conflicts_with`), kind membership, kind↔definition-signature consistency, and closure across every collection.

The context also owns the composition-root-only layer and tension join (`core/factories/layer.factory.ts` over `core/resolvers/layer.resolver.ts`). The execution-model layers of the principle architecture reuse the algo cluster ids as nodes. With a universal category→layer membership map, they turn every arch `tensions_with` edge into a resolved `TensionResolution`. The resolution is `scope-separation` only between two principles in different layers, `irreducible-tradeoff` otherwise, or a hand-authored override. The `unresolvedTensions` and `deadResolutionSeeds` axes gate it, and `layerOf`, `layers`, `resolveTension` and `resolutions` query it. The package root exports each collection's factory.
<!-- /concern:overview -->

<!-- concern:use -->

## When to use

- Deriving compositional context for the model. Retrieve the principles, algorithms and grammar relevant to a force, concern or document type, and inject them as structured context instead of prose.
- Reasoning at compose or refactor time over the principle graph: what a change touches, what it conflicts with, and how a violation is refactored.
- Walking an algorithm's composition closure or clustering the catalog by force, and joining the algorithm layer to the principle graph by `principleRef`.
- Composing or linting a PAG document (agent, workflow, checklist) with `contextFor(type)`, `parse`, `validate` and `resolvePagTemplate`.
- Resolving a concept to its definition, kind and the principles that reference it through the `lexicon` collection, and classifying a concept by the `kindTaxonomy()` decision procedure.
- Composing a cross-face relationship graph from a seed principle, term or algorithm, which yields the node plus its resolved neighborhood across arch, algo, pag, lex and quality, through the consumer's `compose` surface.
- Validating the ontology. The self-validating resolution gate proves every edge resolves (Principle ∪ Term), the polarity law, kind membership, and kind↔definition consistency.
- Reasoning about how a codebase names and places its files. The `Taxonomy / Classification / Naming` arch category, its lexicon terms and the `taxonomy` algo grammar hold the concern-taxonomy standard as queryable ontology instead of prose. The standard covers the closed vocabulary, positional slot resolution, concern and folder correspondence, the depth cap and its sideways-overflow slots, the classification law, and the manual identity-migration reshape.
- Resolving an apparent principle conflict. `resolveTension(a, b)` returns how a `tensions_with` pair resolves, with the layer each occupies and whether the fix separates scopes or accepts an intrinsic tradeoff. `layerOf` and `layers` place any principle or concept in the execution-model layer topology.

## When NOT to use

- As a linter or code scanner. It holds the knowledge the quality tooling (`@govlab/quality`) reasons from, not the tooling.
- For the ecosystem-knob quality-gate mapping from canonical linter concepts to per-tool knobs, which is `@govlab/quality`.
- As a compilable grammar or a PAG interpreter. The BNF productions are descriptive contracts, `parse` is a shallow structural parser, and nothing here executes PAG.

<!-- /concern:use -->

<!-- concern:charts -->

## Architecture charts

The structure, logical-flow and dependency diagrams derived from the source AST live in [_code.info.generated/mermaid-charts.generated.md](./_code.info.generated/mermaid-charts.generated.md).
<!-- /concern:charts -->

<!-- concern:install -->

## Install

A private workspace package resolved through the root `package.json` `workspaces` glob `govlab.root/govlab.*`. A consumer declares it as a dependency and imports the bare specifier `@govlab/context`. It is authored in TypeScript and resolved directly from its `.ts` barrel under Node, with no build step between a consumer and the source.

## Quick start

```ts EXAMPLE: Compose the whole retrieval surface with the cross-ontology joins wired
import { createGovlabContext } from "@govlab/context";
const ctx = createGovlabContext();
ctx.arch.resolve(["single-responsibility"]);
ctx.algo.joinConcerns();
ctx.pag.contextFor("AGENT");
```

```ts EXAMPLE: Build one collection on its own
import { createArchRelations } from "@govlab/context";
const arch = createArchRelations();
arch.validateOntology();
```

```ts EXAMPLE: Resolve the lexicon, classify by the kind taxonomy, and prove the ontology validates itself
import { createGovlabContext } from "@govlab/context";
const ctx = createGovlabContext();
ctx.lex.resolve("<concept-name>");
ctx.kindTaxonomy();
ctx.validateResolution();
```

<!-- /concern:install -->

<!-- concern:api -->

## API

- `const ALGO_FACE: import("../../types/ontology.types.js").OntologyFaceDefinition<AlgoGrammar>`
- `interface AlgoGrammar`
- `const ARCH_FACE: import("../../types/ontology.types.js").OntologyFaceDefinition<ArchRelations>`
- `interface ArchRelations`
- `class BaseOntology`
- `function buildSymbolIndex(contracts: readonly ContractSymbolView[]): SymbolEntry[]`
- `const CANONICAL_KINDS: ReadonlySet<string>`
- `interface CheckDeclaration`
- `interface CheckedRecord`
- `interface CheckFacet`
- `const CLOSED_VOCABULARIES: readonly ClosedVocabulary[]`
- `interface Concept`
- `const CONCEPTS: readonly Concept[]`
- `const CONDITIONAL_SEVERITY: "mandatory" | "recommended" | "contextual" | "discouraged"`
- `interface Contract`
- `interface ContractCategory`
- `function createAlgoGrammar(options?: AlgoGrammarOptions): AlgoGrammar`
- `function createArchRelations(options?: ArchRelationsOptions): ArchRelations`
- `function createGovlabContext(options?: GovlabContextOptions): GovlabContext`
- `function createLexicon(options?: LexiconOptions): Lexicon`
- `function createPagGrammar(options?: PagGrammarOptions): PagGrammar`
- `function createReason(options?: ReasonOntologyOptions): ReasonOntology`
- `function debugLogger(enabled: boolean): Logger`
- `interface DeclaredCheck`
- `function defineCheck(declaration: CheckDeclaration): CheckDeclaration`
- `function defineCheck(declaration: CheckDeclaration): CheckDeclaration`
- `function defineOntologyFace<P>(definition: OntologyFaceDefinition<P>): OntologyFaceDefinition<P>`
- `const EDGE_RELATIONS: readonly EdgeRelation[]`
- `const EXAMPLE_SHAPE_VALUES: readonly ("placed-file" | "renamed-file")[]`
- `const EXAMPLE_SHAPE_VOCABULARY: readonly [{ … }, { … }]`
- `const EXAMPLE_SHAPES: { readonly placed: "placed-file"; readonly renamed: "renamed-file";}`
- `function executableDocuments(): DocumentSource[]`
- `interface Exemplar`
- `interface FieldSpec`
- `function foldFaces(definitions: readonly OntologyFaceDefinition[], context: FaceContext): Map<string, unknown>`
- `interface GovlabContext`
- `function keywordIdOf(record: KeywordRecord): string`
- `const KIND_DECISION_ORDER: readonly string[]`
- `const KIND_TAXONOMY: readonly KindDefinition[]`
- `interface Lens`
- `const LEX_FACE: import("../../types/ontology.types.js").OntologyFaceDefinition<Lexicon>`
- `interface Lexicon`
- `function loadDeclaredChecks(file: string): readonly DeclaredCheck[] | null`
- `function nameKeyOf(phrase: string): string`
- `const ONTOLOGY_FACES: readonly OntologyFaceDefinition<unknown>[]`
- `const ONTOLOGY_SCHEMA: ReadonlyMap<string, Readonly<Record<string, import("#types/field.types").FieldSpec>>>`
- `const PAG_FACE: import("../../types/ontology.types.js").OntologyFaceDefinition<PagGrammar>`
- `const PAG_KINDS: { … }`
- `function pagBlockOf(text: string): PagText | null`
- `function pagTextOf(source: DocumentSource, text: string): PagText | null`
- `function parse(text: string): PagDocument`
- `function patternVocabularyOf(reason: ReasonOntology): PatternVocabulary`
- `interface Principle`
- `interface PrincipleCategory`
- `interface PrincipleRecord`
- `const REASON_FACE: import("../../types/ontology.types.js").OntologyFaceDefinition<ReasonOntology>`
- `interface ReasonNode`
- `const REF_COLLECTIONS: ReadonlySet<string>`
- `const RELATION_RANGES: Record<EdgeRelation, ReadonlySet<string>>`
- `function resolvePagTemplate(template: TemplateRecord, slots: Record<string, string>): TemplateResolveResult`
- `const SEVERITY_LEVEL_VALUES: readonly ("mandatory" | "recommended" | "contextual" | "discouraged")[]`
- `const SEVERITY_LEVELS: ReadonlySet<string>`
- `const SEVERITY_TAXONOMY: readonly [{ … }, { … }, { … }, { … }]`
- `function slugify(name: string): string`
- `function symbolIndexesMatch(committed: readonly SymbolEntry[], generated: readonly SymbolEntry[]): boolean`
- `function templateRefsOf(text: string): TemplateRef[]`
- `interface Term`
- `interface TestSurface`
- `function unresolvedTemplateRefsOf(text: string, members: KindMembers): TemplateRef[]`
- `function validate(text: string): ValidateResult`
- `function validateDocuments(sources: readonly DocumentSource[]): DocumentVerdict[]`
- `function valuesAt(record: unknown, path: string): string[]`
- `const VARIANTS: ReadonlyMap<string, string>`
- `function verdictOf(source: DocumentSource, text: string): DocumentVerdict`

<!-- /concern:api -->

<!-- concern:config -->

## Configuration

Every collection and the orchestrator accept an options object with injected cross-cutting concerns: a `logger` defaulting to a no-op and, at the collection level, the cross-ontology resolvers. `createGovlabContext(options)` supplies those resolvers internally, so a consumer gets the joins without wiring them. They resolve the arch principles for a force, the arch principle for an algo `principleRef`, and the algo `pag`-domain contracts for a pag document type. The canonical force and concern vocabulary the collections validate against lives in `configuration/constants/vocabulary.constants.ts`. The resolution entry point takes `--debug` to write each collection's load notes to stderr.
<!-- /concern:config -->

<!-- concern:deps -->

## Dependencies

- `@govlab/argv`
- `@govlab/canonical-write`
- `@govlab/constants`
- `@ssot/paths`

<!-- /concern:deps -->

<!-- concern:ai-context -->

## AI context

- The framework is one composed port. `createGovlabContext()` returns the collections (`arch`, `algo`, `pag`, `lex`, `reason`) with the cross-ontology joins wired, plus `kindTaxonomy()` and the self-validating `validateResolution()` gate. Each collection's factory (`createArchRelations`, `createAlgoGrammar`, `createPagGrammar`, `createLexicon`, `createReason`) is exported from the package root.
- The `reasoning` collection is the reasoning meta-ontology, the root truth every algorithm grammar is an instance of. It is a non-record collection over `configuration/reason/data/`, shaped like `pag`. It holds the derivation loop (`orient → intent → see → derive → project → act → constrain → verify → commit → terminate`) with its mandatory-always gates (`reasoning:tel-priority`, `reasoning:ver-evidence`, `reasoning:ter-stop`), the typed axis nodes, and the domain-agnostic pattern reasoning-space. The reasoning-space holds dimensions, lenses, modes and representations, one canonical set the loop nodes reference by `concept`. `validateResolution()` validates its cross-face `edges` into algo and pag and every algo record's `grounds` reference, so a grammar gate references the canonical loop gate instead of defining it again. Reason ids sit outside canon reconciliation, like `pag`, and carry no kind `type`.
- The `reasoning` collection carries a governed test-surface sub-collection, the agnostic model of what a system can be wrong about. `reason.testSurfaces()`, `techniques()` and `invariants()` expose the records under `configuration/reason/data/`. Each `TestSurface` is a `dimension`·`lens` cell mapped to an `invariant` (the assertion) that `techniques[]` obtain. Its `predicate` is grounded into `ver-ground-truth` and its `evidence` into `ver-evidence`. Its `verdictDomain` is closed to `pass`, `fail` and `unknown`, where `unknown` is an empty evidence set, the coverage-gap state.
- `validateResolution()` resolves every test-surface reference and closed value: the dimension, lens, techniques, invariant, predicate and evidence groundings and technique mode, plus the verdict, source and predicate-type vocabularies. It also gates cardinality: no surface with zero techniques, an empty verdict domain, a blank predicate, or a colliding `(dimension,lens)` cell. `reason.uncoveredCells()` derives the grid complement (dimensions × lenses − covered) instead of storing it.
- The coverage-derivation methodology that walks the catalog is the `algo` `test-coverage` domain, a typed derivation-loop instance grounding `reasoning:derivation-loop`. A consumer module declares `coversSurfaces: string[]` in its `_manifest.json`, and the `covers-surfaces` docs plugin validates it against `reason.testSurfaces()`.
- The `lexicon` collection is the declarative 'what-is' layer that completes the ontology. A `Term { id=slugify(name), name, kind, definition, aliases }` gives every arch relationship-edge target a resolvable, kind-typed, defined home, so the relationship graph is traversable with no dangling edges. The canonical kinds are governed by `KIND_TAXONOMY` in `configuration/constants/kind.constants.ts`, an ordered first-match decision procedure with a per-kind discriminator and definition signatures. `RELATION_RANGES` in `configuration/constants/architecture.constants.ts`, which holds the polarity law, and the gate derive their kind set from it.
- The self-validating gate (`validateResolution()` and `runtime/entrypoints/ontology.entrypoint.ts`, wired into verify) fails on any unresolved edge, any polarity violation, any non-canonical kind, and any definition that opens with a foreign kind's signature. A polarity violation is an anti-pattern referenced by a relation other than `conflicts_with`.
- The shared kernel under `core/` is the single implementation of the concerns every ontology repeats. It holds JSON coercion (`core/normalizers/field.normalizer.ts`: `asString`, `asStringArray`, `asExemplar`, and `asClosed` for closed vocabularies), a walk-free loader that reads each collection's data folder through its paths key, and one `slugify`. It also holds the `createOntology<R>` engine (id-index, `query`, the duplicate-id and dangling-edge validate primitives, `deepFreeze`) and the `defineOntologyFace` contract with its `foldFaces` runner.
- A record collection (arch, algo, lex) extends `BaseOntology`, which owns the `get`, `all`, `ids` and `query` surface and runs the collection's injected `matches` predicate. A non-record collection with no single `idOf` (pag) implements the port directly. Collections supply their own record schema, `idOf` and `edgesOf`, and their own `validateOntology` output shape, so the shapes are not unified. Arch canonicalizes edge targets, algo scans `composes` raw, and pag reports `danglingSlots`.
- Concern taxonomy, meaning how a codebase names and places its files, is a first-class ontology domain, not a convention living only in prose. It spans the arch, lex and algo collections on one category slug (`taxonomy-classification-naming`).
- `configuration/principle/data/taxonomy.data.json` holds the taxonomy principles: closed vocabulary, positional slot resolution, concern and folder correspondence, declared jurisdiction, bounded nesting depth with sideways overflow, one concern per file, the narrowest concern with the domain-ward layer tie-break, agnostic-first vocabulary, guided vocabulary refusal, the derived naming registry, and manual identity migration.
- `configuration/lexicon/data/` holds the slot and role vocabulary and the anti-patterns those principles conflict with: vocabulary inflation, ignore-list silencing, the depth-relief container, downward nesting, the saturated role tag, the concern-swallowing compound, automated reshape, unguided refusal and borrowed synonymy.
- `configuration/algorithm/data/taxonomy.data.json` is the typed derivation-loop instance that operationalizes the taxonomy principles, with its kernel grounding `reasoning:derivation-loop` and its data file declaring the `process` tier. Its stages are orient→jurisdiction, intent→reshape-risk-priority grounding `tel-priority`, see→path-role-walk, derive→concern-classification, project→name-projection, act→container-reshape, constrain→vocabulary-admission-gate, verify→discovery-verification grounding `ver-evidence`, commit→ledger, and terminate→completion grounding `ter-stop`.
- `configuration/layer/data/index.data.json` maps the taxonomy category to `structural-core`, so `layerOf` and `resolveTension` place these principles in the same layer space as every other. The project's own closed word-lists and jurisdiction declarations stay out of the ontology as per-project registry data. The ontology carries the agnostic standard those declarations instantiate, so its exemplars use placeholder subjects and only declared concern words.
- Coordination between parties that share a written surface is a second ontology domain on one category slug (`coordination-surfaces`) across the arch and lex collections. The algo `coordination` grammar sits at the `process` tier. The arch records hold the classes a coordination model states: derived record state, write barriers, independent lifetime axes, write scope and read population, read-time joins, period-decided disposition, and the anti-patterns they conflict with. The lex terms hold the surface, reader, lifetime, invocation, copy and allocation vocabulary. `configuration/layer/data/index.data.json` maps the category to `execution-core`.
- Every record carries, or inherits from its category or data file, a `check` facet stating how a codebase is checked against the concept it names. Each answer is a value or `none: <reason>`. It answers `population` (the set the check runs over), `freshness` (what makes a verdict stale), `refusal` (where the check blocks before a write) and `observation` (what locates a violation at runtime). It also answers `evidence`, the sign of what the check has shown (`fires`, `fires-and-accepts`, `contradicted` or `none`) followed by what shows it, and `authority`, the side that is the source when the check and its subject disagree. The check itself comes from the field that already names it: `enforced_by` on an architecture record, the architecture edges that name a lexicon term (with any `enforcedBy` the term adds), and `check.by` in the collections that have no such field.
- The lexicon's check facet is one collection declaration, `configuration/lexicon/data/check.data.json`. `checkGaps()` measures the coverage per collection and per question, and `checkedRecords()` returns each record with its merged facet. `validateResolution()` reports every record that lacks a check, every check or dependency reference that resolves to no record, every data key a loader never reads, and every required field left without a value.
- Canonical data stays JSON under each `configuration/<collection>/data/`, a portable substrate that tooling in other languages reads directly. The TypeScript is the typed binding, never the source of truth. Ids are `slugify(name)`, derived and stable keys, and the id space is namespaced per face.
- The cross-ontology joins are identity-based. Algo `force` and arch `scope` validate against the kernel's canonical vocabulary, algo→arch resolves by `principleRef`, and algo's `pag`-domain document types bind to pag's `document-types` records. `createGovlabContext` supplies these resolvers, so the joins are live.
- The layer and tension join (`core/factories/layer.factory.ts`) is a composition-root concern, not a per-record collection. A tension resolution is a 2-ary hyperedge (two concepts and a rule), so it lives beside `crossValidate` and `joinConcerns` in `createGovlabContext`. Layer nodes reuse the algo cluster ids (`computation-core`, `structural-core`, the cross-cutting `*-core`), and `configuration/layer/data/graph.data.json` only references them, never overloading the clusters' `composes` or `force`.
- `configuration/layer/data/index.data.json` maps every arch and lex category slug to a layer, with per-term overrides for the split `quality-attributes` terms. `layerOf` therefore places both a principle, through its category, and a lex quality-attribute term in the same layer space.
- `resolveTension(a, b)` consults the overrides in `configuration/layer/data/tension.data.json` first, keyed by canonical id so an alias like `dry` matches the edge `duplicate-code`. It then derives `scope-separation` only when both endpoints are genuine principles in different layers, and `irreducible-tradeoff` otherwise, because a principle cannot be scope-separated from a quality, metric or cost it competes with, nor from a same-layer peer. The `unresolvedTensions` axis checks that every `tensions_with` edge resolves, and `deadResolutionSeeds` checks that every override matches a live edge. Query through `layer:<id>` and `tension:<a>-vs-<b>` refs.
- The pag collection names no host's tool surface. Its `semantic_operation` category is the vocabulary an adapter binding maps a host's tools onto, and every keyword outside `contextual` grounds into a reason record. The `configuration/grammar/data/` grammar content is PAG, the Pattern Abstract Grammar created by Bane's Lab (`https://banes-lab.com/pag`), and the module stays `private` for publication.

<!-- /concern:ai-context -->

<!-- concern:domains -->

## Domains

This package serves these software domains, which `_manifest.json` declares in `domains` from the two-tier software-domain vocabulary (`meta → sub`):

- **ai** — prompt-engineering

<!-- /concern:domains -->

<!-- concern:principles -->

## Architecture principles

The principle ontology resolves the architectural principles that govern this package, which `_manifest.json` declares in `governance.principles`:

- **Self-Describing Architecture** — _Metadata / Self-Description / Declarative Systems_ · contextual. Reinforces Discoverability, Runtime Discovery. Enables Plugin Architecture, Automation. Tensions with Metadata Drift. Conflicts with Hidden Runtime Behavior.
- **Manifest-Based Design** — _Metadata / Self-Description / Declarative Systems_ · contextual. Reinforces Self-Describing Architecture, Runtime Discovery. Enables Plugin Loading, Capability Declaration. Tensions with Manifest Drift. Conflicts with Hardcoded Registration.
- **Metadata-Driven Design** — _Metadata / Self-Description / Declarative Systems_ · contextual. Reinforces Declarative Configuration, Runtime Discovery. Enables Code Generation, Plugins. Tensions with Debuggability. Conflicts with Hardcoded Behavior.
- **Convention over Configuration** — _Metadata / Self-Description / Declarative Systems_ · contextual. Reinforces Pattern Consistency, Predictability. Enables Reduced Boilerplate. Tensions with Explicitness. Conflicts with Excessive Configuration.

<!-- /concern:principles -->

<!-- concern:quality-governance -->

## Quality governance

The canonical quality catalog resolves the quality concepts that govern this package. `_manifest.json` declares them in `governedBy`, and a lint package derives them from the concepts its own rules enforce. Each maps to the custom lint rules that enforce it:

- **immutability** — _best-practice_
- **serialization** — _best-practice_
- **separation-of-concerns** — _complexity_
- **type-safety** — _correctness_

<!-- /concern:quality-governance -->

<!-- concern:disposal -->

## Disposal

- Remove `govlab.root/govlab.context/`.
- Drop `govlab.root/govlab.*` from the root `package.json` `workspaces` if no lab package remains.
- Remove every import of `@govlab/context` in consumers, which are the `@govlab/docs` manifest plugins, the `@govlab/quality` canon gate, and the build and content members.
- Repoint the data-dir keys of the canon gate `@govlab/quality/runtime/entrypoints/canon.entrypoint.ts`, then regenerate the catalog (`npm run catalog:regenerate`) and the documents (`npm run docs:generate`).

<!-- /concern:disposal -->

<!-- concern:metrics -->

---

stable · 74 exports · 4 deps · 4 principles · 4 concepts
<!-- /concern:metrics -->