Skip to content

HQL design status

HQL remains in language design. These cards are the current state of that design and the source of truth for it. Where an implementation is narrower than the design, the card says so.

Card Scope
hql/core Small typed functional core and domain vocabulary
hql/collections Set, Seq, Map and cards : Set<Card>
pipes Ordinary functions, composition and data-parallel execution
hql/knowledge Semantic universe, the card family and presentation
hql/extensions The extension registry, import, and the unbuilt module loader
doc-type Doc, the header, format, sections, links and embeds
card-type Card and its two kinds, the vault, and the cards keyword
data-type Data, the tree type of headers and structured payloads
type-system :, generic parameters and progressive type refinement
fields Optional ? fields, partial schemas, and the two metadata layers
link-op Doc references and the [[..]] -> [[..]] {..} link operator
graph-type Graph<N, E>, Edge<S, T>, and the document and knowledge graphs
orderable Orderable, the card's own key, and the take contract
option-type Option<T>, absence, and the optional-by-type doc reference
hql/presentation Terminal presenters and the host default
hql/error-reporting Severities, the report queue, strict and collect
hql/semantic-search semantic, Hit, Ranking and the read path of memory
hql/std-lib Placeholder for the standard library; a bootstrap non-goal

Current direction

Prefer ordinary functions, bare bindings and fundamental pipe syntax. SQL clauses and Rust-like trait machinery stay out of the design. A trait is a host mechanism an extension may use internally and it never reaches HQL's surface; what would be asked of it splits into ancestry (:), capability (an extension registers a function) and a partial schema over Data — see type-system. Extensions supply external capabilities and may be written in Rust. That registration is now implemented: collection steps are the core's, graph and present are a prelude a vault may decline, and retrieval is imported where it is used — see hql/extensions. Module resolution is not, so optional namespace init.hql files remain design.

Generic types are written with angle brackets — Set<Card>, fn first<T>(xs: Seq<T>) : T? — and square brackets are reserved for sequence values and indexing. cards is a Set<Card> in the current vault or namespace, and a prefix of it is reproducible because a card carries its own ordering key — see orderable. knowledge comprises concepts, relations, propositions and evidence. Knowledge retains conflicting claims and provenance; a graph is only one projection. Programs return typed values, persistence is explicit, and presentation belongs to a separate layer.

Card is the base representation type of the knowledge domain, with two kinds: ConceptCard : {Card, Concept} occupies a node position, and RelationCard : Card represents an edge without becoming a node. The kind is declared by metadata.knowledge.type and must be checked, not trusted.

HQL has no field visibility: no pub, protected or private. Values are data and declared fields are queryable data, so there is no privileged inside for a modifier to protect, and a subtype neither hides nor re-exposes what it inherits. What a type may declare instead is that a field is optional, metadata? : Data, and that it constrains only the paths it knows about — a partial schema over an otherwise open Data tree.

doc.header is required; doc.header.metadata is optional, because authoring metadata is a choice. card.metadata is a different field, assembled when a document becomes a card from the authored block, system metadata, extension contributions, .hmd/** vault state and other derived information, under precedence rules card-type owns and has not settled. The card family is recorded in type-system and fields in fields.

Decisions still needed

  • Function/declaration grammar, bound syntax, variance, inference and pipe argument placement — see type-system.
  • Collection equality, Card identity, mapping duplicates and ordering contracts.
  • Document schemas and error carriers; an explicit match in place of the implicit lifting of absence — see option-type.
  • Semantic constructors, derivation rules and constraint/satisfaction types.
  • The name and type boundary between graph projection and graph presentation — see hql/presentation.
  • Module resolution, namespace inheritance and init.hql initialization policy.
  • Extension transport, and whether an extension may supply anything beyond steps — a type, a renderer or a document source.
  • The reduce side of the pipeline vocabulary and the execution backend that runs a program — drafted in HQL-0004.

The implemented slice is now larger than the literal core: statements and bindings, strings and data literals, document references, the link operator, pipelines with lambdas, a vault of Markdown and HyperMarkDown documents, the card family checked at load, semantic retrieval, graph traversal, an extension registry with import, and a reporting queue. The signed 64-bit and double-precision representations, the absence of Int-to-Float widening, and the addition-chain limit remain provisional implementation choices rather than settled language requirements. What the parser accepts is recorded in the grammar; what it deliberately does not is in the bootstrap requirements.

Which findings the implemented slice settled is tracked in consolidation and inconsistencies; this card records the outcome, not the history.

Architecture sources

The sources these cards were drawn from:

Read those sources before changing language design. Keep unresolved alternatives visible until a decision is made; illustrative syntax is not implementation evidence.