QNTX Glossary & Definitive Terms

This glossary defines the core concepts and symbols used throughout QNTX. For a conceptual overview, see Understanding QNTX. For system architecture patterns, see Two-Phase Jobs.

Core Concepts

ATS (Attestation Type System)

Both a type system AND storage system for attestations. For storage details, see Bounded Storage. It defines:

The data model for attestations (type system)
Storage and retrieval mechanisms (storage system)
The query language for accessing attestations (ax)
The foundational primitive: "subject is predicate of context by actor at time"

Attestation

A verifiable claim in the form: [Subject] is [Predicate] of [Context] by [Actor] at [Time]

Not a fact, but a claim that can be verified
Immutable and append-only
Has an ASID (Attestation System ID) for unique identification

Example: USER-123 is member of TEAM-ENGINEERING by hr-system@company at 2025-01-06T09:45:00Z

ASID (Attestation System ID)

Unique identifier for attestations. Always random for uniqueness, ensuring no collisions.

Symbol System

Primary SEG Operators (UI/Command Symbols)

These symbols have UI components and keyboard shortcuts (user-configurable):

Symbol	Command	Meaning	Usage
`⍟`	i	Self	Your vantage point into QNTX - the current user/session
`≡`	am	Configuration	System settings and state
`⨳`	ix	Ingest	Import external data
`⋈`	ax	Expand	Query and surface related context
`⌬`	by	Actor	All forms: creator, source, authenticated user
`✦`	at	Temporal	Time marker/moment
`⟶`	so	Therefore	Consequent action/trigger

Attestation Building Blocks

Fundamental components of attestations (not UI elements):

Symbol	Concept	Role in Attestation
`+`	as	Assert - emit an attestation
`=`	is	Identity/equivalence in "subject IS predicate"
`∈`	of	Membership in "predicate OF context"

Note: Consider alternative typeable symbol for ∈ (of) for better keyboard accessibility

System Symbols

Infrastructure and lifecycle markers:

Symbol	Name	Purpose
`꩜`	Pulse	Async operations, always prefix Pulse-related logs. See API
`✿`	PulseOpen	Graceful startup with orphaned job recovery
`❀`	PulseClose	Graceful shutdown with checkpoint preservation
`⊔`	DB	Database/storage layer
`▣`	Prose	Documentation and prose content

Configuration

Configuration Files

Canonical name: Either am.toml (preferred) or config.toml (compatibility)
Future standard: Consider qntx.toml
UI config: ~/.qntx/config_from_ui.toml (auto-generated, never in project)

Configuration Precedence (Pluggable)

System (/etc/qntx/config.toml) - lowest
User (~/.qntx/config.toml)
User UI (~/.qntx/config_from_ui.toml)
Project (./config.toml)
Environment (QNTX_*) - highest

Always shows source in UI to debug precedence issues.

Configuration Philosophy

Empty values are invalid (not "use default")
Sensitive config supports multiple options with clear precedence
Logger verbosity lives in am package configuration
QNTX works out of the box without configuration

Architecture

Core vs Plugins

Core is minimal, containing only:

ATS (attestation system)
Database (db)
Configuration (am)
Async jobs (Pulse)
Query system (ax)

Everything else is a plugin communicating via gRPC for isolation.

Package Relationships

ai/tracker → pulse/budget

The ai/tracker records API calls and feeds data to pulse/budget for centralized budget management.

Web UI ↔ Backend

Uses both REST API and WebSocket:

REST for CRUD operations
WebSocket for real-time updates and streaming

Async Job System

JobMetadata exists for phase tracking in two-phase jobs
Supports parent-child job relationships
Phases: "ingest" (process data) and "aggregate" (combine results)

Data Model

Bounded Storage

Hard limits with oldest deletion by default. Future versions will support user-defined retention policies.

Temporal Representation

Flexible based on predicate - can be single timestamp, range, or point-in-time with duration.

Database Schema

Versioned with migrations using the migration system in db/sqlite/migrations/

Development Philosophy

Documentation Standards

Package READMEs: Philosophy first, then usage
Code comments: Focus on "why" not "what"
Broken features: Document honestly as broken
Future vision: Goes in GitHub issues, not documentation
Deprecated features: Mark deprecated, remove next version

Error Messages

No symbol prefixes (too confusing)
Use errors.Wrap() for context
Always provide hints for user guidance

Testing

Use qntxtest.CreateTestDB(t) for all database tests
Never create schemas inline
Migrations are the single source of truth

Terminology Notes

Simplified Terms

Use "database" or "storage" as primary terms
"Material retention substrate" can be used as secondary description
Avoid unnecessary abstraction

Honest Documentation

Mark WIP features as "heavily WIP and currently broken" when true
Don't hide complexity - show it and make it comprehensible
Document reality, not aspiration

Common Patterns

Query Pattern

ax contact                    # Find all attestations about contacts
ax is member of TEAM-ENGINEERING  # Find team members

Ingestion Pattern

ix https://api.example.com/data   # Ingest from API
ix file://./data.json             # Ingest from local file

Configuration Check

qntx am show                      # Show all configuration with sources
qntx am get pulse.workers         # Get specific value