Glossary

Coming from React or other codegen tools

Analogues, not equivalences — landing pads for readers arriving with React or generic-codegen priors. Once a term lands, switch to the SKMTC-native definition below; the analogues lose detail.

SKMTC vocabulary — load-bearing terms

Every term in this list maps to a specific construct in @skmtc/core's exported surface. When writing about SKMTC, prefer these terms. Terms that don't appear here (and aren't in the alphabetized entries below) likely don't have a referent in the code.

---

A

affirmDefinition

The Driver-side integrity check on every cache hit: the cached Definition's generatorKey must match the caller's, else it throws "Registered definition mismatch". See files-and-dedup.

Agent-native operation modes

The three modes every state-touching CLI command supports: interactive (TTY + Ink UI), strict text (non-TTY plain stdout), and strict JSON (--json flag). See CLI overview.

B

basePath

The settings.basePath field in client.json: both the on-disk root for generated files and the bundler @ alias root in the consuming app. See projects-and-workspaces.

Bundle

bundle.js — the compiled JS file the SKMTC Worker loads, produced by deno bundle worker.ts -o bundle.js. See the-worker-runtime.

Bundle freshness

The invariant that bundle.js matches the current deno.json#imports. Drift triggers a refuse-with-recipe error in strict-mode generate; the skmtc doctor check project-bundle/<project> surfaces stale bundles.

C

Cache key

The (identifier.name, exportPath) pair that looks up a Definition in File.definitions; decides whether to reuse, while the Generator key decides that reuse is safe. See files-and-dedup.

Capability gate

A generator's isSupported({ operation }) predicate deciding whether it handles a given operation/model; false yields a notSupported manifest outcome. See anatomy of a generator.

Cascade pruning

The removeErroredItems mechanism that prunes consumers of a failed $ref from the parsed document, one hop deep. See error-handling-philosophy.

clone-to-customize

The design philosophy: stock generators ship hardcoded values that mark customization seams; users skmtc clone the generator and edit the source. See clone-vs-install.

ContentSettings

The settings instance property on Projection classes, computed by the Driver from the Projection's static methods; carries identifier, exportPath, and enrichments for the current item.

CustomValue

An escape-hatch Snippet wrapping an arbitrary TypeScript fragment not expressible through the OAS-derived schema model; the type: 'custom' branch of schemaToValueFn dispatch. See the CustomValue reference.

D

Definition

The export const NAME = VALUE; (or export type NAME = …;) wrapper around a Projection's output value, created by Drivers and carrying the generatorKey that feeds affirmDefinition. See files-and-dedup.

Deduplication

The behavior of register calls on the same File: imports dedup via Set.add, definitions via Map.has first-write-wins, reExports per module-and-entity-type. See files-and-dedup.

destinationPath

The file path a Snippet's imports or child definitions register against — the file being registered into right now, as opposed to exportPath. See stringable-composition.

Driver

The orchestrator class for inserting a Projection (OasOperationDriver, GqlOperationDriver, ModelDriver): computes settings, performs the cache lookup, instantiates on miss or affirms on hit, registers the Definition. See files-and-dedup §What Drivers do.

E

Eject / adopt

Taking ownership of a generated file (eject: rename to drop the generated suffix, record in settings.ejected, generators stop writing it) and returning it to generation (adopt). See eject and adopt.

Enrichment

User-supplied per-operation or per-model configuration declared in client.json and validated against the generator's Valibot schema from toEnrichmentSchema. See enrichments.

EnrichmentRequest

A generator-initiated request ({ prompt, enrichmentSchema, content }) for an LLM-fillable enrichment, returned by the optional toEnrichmentRequest(refName). See enrichments §AI-driven enrichments.

Entity type (TsIdentifier.type)

The per-language declaration discriminant on a language package's identifier subclass — TypeScript's vocabulary is 'variable' | 'type' | 'class' | 'interface' | 'namespace'. See stringable-composition.

exportPath

The file path where a Projection's Definition lives, returned by the static toExportPath; contrast destinationPath. See stringable-composition.

F

fallbackName

The name a Projection uses when the schema being normalized isn't a named $ref; passed to insertNormalizedModel for inline schemas. See cross-generator-coordination.

File (DSL class)

The in-memory representation of a generated file: three maps (imports, reExports, definitions), each with its own dedup rule; serialized by Render via file.toString(). See files-and-dedup.

G

Gen-map (anchors)

The attribution sidecar an opted-in run writes next to each generated file, mapping byte ranges of output back to the generator, schema location, and variant that produced them. Toggled by client.json#settings.anchors.enabled or --anchors / --no-anchors on generate.

Generator

A JSR package (or local TypeScript directory) implementing the generator protocol: exports an entry function via toOasOperationEntry, toGqlOperationEntry, or toModelEntry. See generators-as-packages.

Generator key

A branded composite identifier on every Definition — four shapes (OAS operation, GQL operation, model, generator-only) — used by affirmDefinition to detect cache-hit collisions. See files-and-dedup.

Global state

~/.skmtc/ — auth token, shadow project state, schema caches. Lives outside any project; check it when local state alone doesn't explain a failure.

H

Hub (skmtc-hub)

The hosted service behind login, publish, push, and pull: accounts (users or orgs) own published stacks and the projects that run them. See what-is-skmtc-hub.

I

Identifier

Neutral naming data (name + opaque per-language kind + exported + typeName), created via the language package's createVariable / createType factories. See stringable-composition.

include / skip filters

client.json#settings.include and .skip — operation/model allow-lists and deny-lists; filter order is isSupported → include → skip. See skip or include operations.

insertModel

The GenerateContext method that inserts a model Projection via ModelDriver and returns an Inserted. See how-generators-produce-output.

insertNormalizedModel

The GenerateContext method for inserting a Projection from an inline schema (no $ref); calls the projection's schemaToValueFn and registers the result under fallbackName. See the-type-system.

insertOperation

The GenerateContext method for inserting an operation Projection (OAS or GraphQL) via the appropriate Driver; returns an Inserted. See how-generators-produce-output.

Inserted

The return type of insertOperation and insertModel: carries the peer Projection's ContentSettings, its Definition, and helpers like .toName(). See cross-generator-coordination.

Integrity key

Synonym for Generator key in contexts contrasting it with the Cache key.

isSupported

A generator's capability-gate predicate. See Capability gate.

J

JsonFile

Sibling to File for JSON output: one content field, serialized with JSON.stringify, last-write-wins on conflicts. See files-and-dedup §JsonFile.

L

Lenient input, strict diagnostics

The error-handling philosophy: parse fails open (one bad item doesn't kill the run), but every dropped item and type inference is logged as a ParseIssue. See error-handling-philosophy.

List

The typed list-builder utility in @skmtc/lang-typescript (ListObject, ListArray, ListParams, ListLines, plus record and key-value helpers). See stringable-composition §The List builder.

M

Manifest

manifest.json — the canonical record of every generation run, written to .skmtc/<project>/.settings/manifest.json and overwritten per run. See the-manifest and the manifest-format reference.

MAX_LOOKUPS

The constant 10 in OasRef limiting $ref chain resolution depth; exceedance throws "Max lookups reached", catching cycles and pathologically deep chains.

modelDepth

The per-(generatorId, refName) counter on GenerateContext that detects self-referential schemas at generate time, letting a Ref Snippet render a deferred form instead of recursing. See the-type-system §Handling recursive types.

Modifiers

The { required?, nullable?, description? } triple on every TypeSystemValue; polarity is required, not optional. See the-type-system §Modifiers.

O

OasRef

The class representing an OpenAPI $ref; constructed during parse with a live reference to the in-progress document, resolves lazily. See refs-and-resolution.

OasSchema

The discriminated union of schema variant classes (OasObject, OasArray, OasUnion, the scalar variants, OasUnknown) — sibling classes with a .type discriminator, not a class hierarchy.

oasType

The runtime tag on parsed OAS items ('schema', 'parameter', 'response', etc.), used by OasRef.resolveOnce for the type-integrity check.

P

Parse phase

The first engine phase — converts SkmtcDocumentInput to SkmtcParsedDocument under lenient input, strict diagnostics. See the-three-phases.

ParseContext

The Parse-phase context class: parser state, the issue list, and the cascade-pruning maps. See the ParseContext reference.

ParseIssue

A structured diagnostic entry produced during parse. See error-codes and the manifest format.

Peer-pin check

The pre-flight verification on skmtc clone that the cloned generator's @skmtc/core version matches the project's pin; override with --force.

Preview (manifest)

A manifest entry pairing a PreviewModule with a source descriptor, produced by a generator's optional toPreviewModule hook for UI / IDE tooling. See the-manifest.

Projection

A named, file-level generated artifact, wrapped in Definition and cached by (identifier.name, exportPath); pull-based — instantiated only when an insert* call asks for it. See projections-and-snippets.

R

Recipe error

A structured error from strict-mode CLI commands when a required argument is missing: Usage, Example, and a Discover line pointing at the follow-up command. Exit code 2.

refConsumers

ParseContext.#refConsumers — a map recording every $ref encounter, used during cascade pruning to identify consumers of a failed schema. See the StackTrail reference.

refErrors

ParseContext.#refErrors — errors keyed by the $ref they invalidated, used during cascade pruning. See the StackTrail reference.

register

The lowest-level registration method on GenerateContext, mutating the file map at destinationPath; the only legitimate way to add imports. See how-generators-produce-output §register.

"Registered definition mismatch"

The runtime error thrown by affirmDefinition when two different generators land on the same cache key. See files-and-dedup §Reading a mismatch error.

Remote-only project

A SKMTC project whose deno.json#imports contains only JSR-installed generators (no local clones); bundles and generates like any other project.

Render phase

The third engine phase — serializes the file map to { path: content } artifacts; pure serialization, no formatter. See the-three-phases.

RenderContext

The Render-phase context class: a thin wrapper around file iteration and file.toString(). Does not format output.

ResultsHandler

The log handler that converts logger.warn / logger.error calls into manifest results leaves — a generator that logs an error contributes to the results tree without throwing. See the-manifest §results.

ResultType

The leaf-value type in the manifest's results tree ('success' | 'warning' | 'error' | 'skipped' | 'notSupported'); 'success' does not guarantee output — check files. See manifest-format.

S

Sandbox API

A hosted-execution alternative to the local Worker: the host posts the schema to a remote SKMTC service, which runs the engine and returns artifacts + manifest. Authenticated via a stored token.

Schema source

The OAS or GraphQL document SKMTC generates from — positional on skmtc generate <project> <source> or pinned in client.json#source.

schemaToValueFn

The static dispatch every ModelProjection class exposes: receives a schema-plus-context bag and returns a structurally matching TypeSystemValue. See the-type-system.

SkmtcDocumentInput

A discriminated union — { type: 'oas', value } or { type: 'gql', value } — that the Worker receives on the GENERATE message.

SkmtcParsedDocument

The parsed counterpart to SkmtcDocumentInput: { type: 'oas', value: OasDocument } or { type: 'gql', value: GqlDocument }.

Snippet

An anonymous, embeddable generated fragment: no settings, no exportPath, no cache participation; embedded via template-literal interpolation. See projections-and-snippets.

SnippetBase

The root class for all DSL elements — provides context, generatorKey, and register(); both Projections and Snippets extend it.

Stack (hub)

A published, immutable version of a SKMTC project on the hub — identity deno.json#name (@account/slug), addressed by semver. Produced by publish; hub projects pin one.

StackTrail

The mutable stack of string frames threaded through Parse that tracks the walker's position; stringifies as a colon-separated path. See the StackTrail reference.

Strict mode

CLI behavior when --no-input is passed (or stdout is non-TTY): no Ink UI, no prompts, required arguments up front; failures produce recipe errors on stderr.

Stringable

The structural type for anything with a toString(): string method — the DSL's composition mechanism via template-literal interpolation. See stringable-composition.

synthesizeArgsObject

Core helper that turns a GqlOperation's typed argument list into an OasObject schema; returns undefined for argument-less operations. See the-graphql-pipeline §synthesizeArgsObject.

T

transform

The per-item hook in a generator's mod.ts entry, called once per matched (operation | model, variant); returns void — output happens via side effects (register, insert*). See how-generators-produce-output.

tryParseAt

The per-item parse-isolation helper: runs a parser callback inside a stackTrail.trace, catches throws, logs an error issue, and returns undefined so the entry is omitted. See error-handling-philosophy §Tier 1.

TypeSystemValue

The discriminated-union intermediate representation a model generator produces from an OasSchema — twelve structural variants, each carrying Modifiers. See the-type-system.

V

Variant

A named axis below (operation, method) / (rootKind, fieldName) / refName along which one source item produces N Definitions instead of one (section-edit forms, wizard steps, mock scenarios). Defaults to 'main'. See variants.

verbatimModuleSyntax

The TypeScript compiler option requiring import { type X } for type-only imports; SKMTC's Identifier tracks entity types to render correct imports under it.

W

Webhook

The OpenAPI 3.1 subject for server-initiated calls: structurally an Operation Object keyed by name rather than URL path, with inverted request/response semantics — a distinct subject (OasWebhook), never routed through an operation generator. See webhook generators.

Worker

The sandboxed Deno Worker thread that runs the engine, one-shot per generate run. See the-worker-runtime.

worker.ts

A derived file in .skmtc/<project>/worker.ts, templated from deno.json#imports by skmtc bundle; regenerated, not hand-edited.

Cross-references

• The three phases — fuller treatment of most terms here
• Manifest format
• Error codes