Skip to content

EXPLAINME.adoc

Latest commit

 

History

History
105 lines (75 loc) · 4.7 KB

EXPLAINME.adoc

File metadata and controls

105 lines (75 loc) · 4.7 KB
Raw

KRL — Show Me The Receipts

Table of Contents

The README makes claims. This file backs them up with concrete implementation pointers.

KRL is the resolution DSL for QuandleDB

KRL (pronounced "curl") is the resolution language for QuandleDB. This repository holds its normative specification; the implementation lives in QuandleDB.

— README

KRL provides four operation families: construct, transform, resolve, retrieve. The grammar is specified in spec/grammar.ebnf (114 lines, v0.1.0 draft). The executable fragment (retrieval/candidate) is implemented in quandledb/server/krl/ as a Julia lexer, parser, AST and evaluator.

Caveat: This repository does not contain a parser or evaluator. It holds the normative spec, Idris2 ABI, Zig FFI, examples, and proof obligations. Execution requires a QuandleDB checkout.

Four Operations Are Distinct Surfaces

KRL has four operation families. The four-verb shape is deliberate: it stops "querying" from becoming the whole identity of the language.

— README

The construction/resolution draft uses | as tensor composition; the retrieval/candidate fragment uses | as stage separator. These are incompatible and must not be concatenated. spec/SURFACES.adoc distinguishes them explicitly.

Idris2 ABI + Zig FFI

Idris2 ABI declarations, Zig FFI shim over the C ABI.

— README

The ABI is declared in Idris2 with 4 %foreign declarations (src/interface/abi/). The Zig FFI compiles to libkrl.a with 3/3 unit tests passing. Any language can call via C ABI.

Caveat: ABI primitives are declared but not yet load-bearing — KR-5 is pending decision.

Grammar Smoke Tests

Four .krl programs, lexically checked against the grammar by tests/smoke/grammar_smoke.sh (20 checks)

— README

Lexical-level checking ensures examples conform to spec/grammar.ebnf without executing them.

  • Implementation: tests/smoke/grammar_smoke.sh, examples/*.krl

Conformance Suite

Executable retrieval-fragment acceptance/rejection corpus in tests/conformance/retrieval_fragment.jl

— README

Cross-repository corpus runs against a supplied QuandleDB checkout, testing filtered retrieval, heuristic candidate metadata, stronger-assurance refusal, and preservation of empty selections.

  • Implementation: tests/conformance/retrieval_fragment.jl

  • Run: julia --startup-file=no tests/conformance/retrieval_fragment.jl /path/to/quandledb

Dogfooded Across The Account

These aren’t one-off choices — they’re patterns used across hyperpolymath repos:

Technology Also Used In

Idris2 ABI

https://github.com/hyperpolymath/tangle, https://github.com/hyperpolymath/quandledb, https://github.com/hyperpolymath/echo-types

Zig FFI

https://github.com/hyperpolymath/tangle, https://github.com/hyperpolymath/quandledb

Groove Protocol

https://github.com/hyperpolymath/groove, https://github.com/hyperpolymath/verisimdb, https://github.com/hyperpolymath/panic-attack

RSR Template

All hyperpolymath repos — Rhodium Standard Repository compliance

File Map

Path Proves

spec/grammar.ebnf

Normative grammar v0.1.0 draft (114 lines)

spec/SURFACES.adoc

Distinguishes construction/resolution draft vs retrieval fragment

src/interface/Abi/

Idris2 ABI declarations (Types, Layout, Foreign)

src/interface/abi/

Lowercase alias for RSR compliance (same content)

src/interface/ffi/

Zig FFI shim, compiles to libkrl.a

src/interface/generated/abi/

Generated C headers (gitkeep placeholder)

examples/*.krl

Example KRL programs (4 known)

tests/smoke/grammar_smoke.sh

Lexical smoke checks (20 checks)

tests/conformance/retrieval_fragment.jl

Retrieval fragment conformance corpus

tests/e2e.sh

E2E suite (FFI build, ABI correspondence, grammar smoke)

.machine_readable/anchors/ANCHOR.a2ml

Canonical semantic anchor

.machine_readable/integrations/groove.a2ml

Groove manifest, port 6462

Containerfile

Chainguard Wolfi multi-stage build, digest-pinned