(definition: OntologyFaceDefinition

): OntologyFaceDefinition

` - `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` - `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` - `interface Lexicon` - `function loadDeclaredChecks(file: string): readonly DeclaredCheck[] | null` - `function nameKeyOf(phrase: string): string` - `const ONTOLOGY_FACES: readonly OntologyFaceDefinition[]` - `const ONTOLOGY_SCHEMA: ReadonlyMap>>` - `const PAG_FACE: import("../../types/ontology.types.js").OntologyFaceDefinition` - `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` - `interface ReasonNode` - `const REF_COLLECTIONS: ReadonlySet` - `const RELATION_RANGES: Record>` - `function resolvePagTemplate(template: TemplateRecord, slots: Record): TemplateResolveResult` - `const SEVERITY_LEVEL_VALUES: readonly ("mandatory" | "recommended" | "contextual" | "discouraged")[]` - `const SEVERITY_LEVELS: ReadonlySet` - `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` - `function verdictOf(source: DocumentSource, text: string): DocumentVerdict` ## 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. ## Dependencies - `@govlab/argv` - `@govlab/canonical-write` - `@govlab/constants` - `@ssot/paths` ## 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` 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: `. 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//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:` and `tension:-vs-` 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. ## 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 ## 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. ## 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_ ## 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`). --- stable · 74 exports · 4 deps · 4 principles · 4 concepts