Domain model on Katalyst Documentation

Bases

Mon, 01 Jan 0001 00:00:00 +0000

Bases#

A base is how Katalyst reaches a backend source and maps that source into the domain model.

Every base must include configuration for raw access. Raw access gives Katalyst a stable way to locate content in the source. For a filesystem, that can be a root directory. For SQL, that can be connection information for a specific instance.

A collectionized base keeps that raw access and adds collection definitions. Those definitions map base-native references into named collections and item identities that Katalyst commands can address directly. This is where two-way mapping applies.

Collections

Mon, 01 Jan 0001 00:00:00 +0000

Collections#

The internal/project loader (loader.go) is the orchestration hub: it loads a project’s .katalyst/ directory, resolves named schemas, and assembles bases and their collections. Each object type parses its own config: the base registry validates a declared type, and a collection parses its own block in storage/collection. It decides which schema applies to a given item, and the check lifecycle is driven from here.

This page is the model and the why; for the key-by-key surface see the configuration reference.

Checks

Mon, 01 Jan 0001 00:00:00 +0000

Checks#

A check asserts one condition on an item and reports a violation when the item fails it. The check engine turns a collection’s configuration into a verdict on each item: it resolves the checks that apply, runs them, and collects their violations. This page explains the model the engine is built on, how check libraries supply and run checks, and why the pieces are shaped the way they are. For the per-type catalog see the check types reference; for the end-to-end data flow of one check invocation see the domain model.

Inspectors

Mon, 01 Jan 0001 00:00:00 +0000

Inspectors#

An inspector profiles content and returns evidence: counts and distributions, never recommendations. Inspectors are the descriptive dual of checks - a check asserts a predicate and reports violations; an inspector reports the distribution that predicate would be tested against. They drive the inspect command. For the per-inspector catalog see the inspectors reference; this page is the model and the rationale behind it.

Terms#

Term	Meaning
Inspector	A read-only operation that profiles content and returns evidence.
Evidence	The measured counts, distributions, classes, or summaries an inspector reports. Evidence is not a recommendation or verdict.
Raw base layer	Inspectors that measure a base directly before collection configuration.
Collection layer	Inspectors that measure configured collection items by domain identity.
Measurement primitive	A reusable profiler such as `objectFields`, `markdownBody`, `fileMetadata`, or content-shape parsing that inspectors point at a specific input.

Model#

Inspectors come in two layers, distinguished by how they reference the data:

Fix

Mon, 01 Jan 0001 00:00:00 +0000

Fix#

Why katalyst fix rewrites frontmatter the opinionated way it does. The parser and encoder live in internal/codec/markdownbodytext; the transform that drives the canonical form, and the backend write that persists it, live in internal/fix and internal/storage/collection/filesystem respectively.

Terms#

Term	Meaning
Fix	A command that rewrites existing content into Katalyst’s canonical form when a check can supply a safe transformation.
Canonical form	The deterministic output format `fix` writes: preserved frontmatter syntax, sorted top-level keys, native encoder style, preserved body bytes, and one trailing newline.
Report-only check	A check that can report violations but cannot safely rewrite content.
Check mode	The `--check` form of `fix`: print what would change, write nothing, and exit 1 if any item is non-canonical.

Design rationale#

Fix is deliberately opinionated.