harn-canon

Seed invariant libraries for Harn Flow. Each pack defines review predicates, evidence, and fixtures that projects can opt into by language or stack.

What lives here

Per-language and per-stack predicate packs. Each pack is a directory containing:

• invariants.harn — Harn functions annotated with @invariant and either @deterministic (pure, 50 ms budget) or @semantic(fallback: predicate_name) (one cheap LLM judge call, 2 s budget, evidence pre-baked at authoring time, plus a same-pack deterministic fallback for replay/runtime discovery).
• README.md — purpose, stack assumptions, evidence sources, coverage examples, known false positives.
• fixtures/ — small atom/slice fixtures the predicates are expected to allow or block, used by CI.

canon-packs.json is the canonical pack manifest for tools that need stable pack discovery without scraping the repository layout. It also owns pack routing metadata: lowercase file extensions and exact lowercase basenames such as dockerfile. Harn and product hosts should infer harn-canon packs from that manifest instead of carrying their own language-routing tables. The validator treats eval-critical language routes as a contract so convergence packs cannot silently disappear from Harn/Burin discovery.

When this repo is installed as a Harn package, harn.toml exposes the same canon-packs.json file as a harn.canon contribution. Package consumers should read that contribution and still treat canon-packs.json as the single source of pack routing truth.

Predicate files use Harn attributes to carry evidence:

let _EVIDENCE_FLOATING_PROMISES = [
  "https://typescript-eslint.io/rules/no-floating-promises/",
  "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch",
]

@invariant
@deterministic
@archivist(evidence: _EVIDENCE_FLOATING_PROMISES, confidence: 0.9, source_date: "2026-04-24")
pub fn no_floating_promises(slice, _ctx, _repo_at_base) {
  // Predicate body omitted.
}

The predicate runtime lives in the Harn repo. This repo tests packs against the Harn release pinned in .harn-version; update that file when validating a new runtime.

Packs

• C — v0 draft predicates for plain C source and headers covering memory, string-handling, format-string, and tempfile footguns.
• C# — v0 draft predicates for plain C# and .NET library or application code.
• C++ — v0 draft predicates for plain C++ application and library code covering memory safety, header hygiene, and special-member discipline.
• CSS — v0 draft predicates for CSS, Sass, and Less stylesheets covering cascade hygiene, internationalization, and accessibility.
• Dart — v0 draft predicates for Dart application, package, and Flutter source covering null safety, public-API hygiene, async correctness, and widget immutability.
• Dockerfile — v0 draft predicates for Dockerfile and Containerfile build recipes.
• Elixir — v0 draft predicates for Elixir application and library code on the BEAM.
• Go — v0 draft predicates for Go modules, command packages, and reusable libraries.
• GraphQL — v0 draft predicates for GraphQL schema files and the server wiring that hosts them.
• Harn — v0 draft predicates for .harn scripts, Flow workflows, and agent-facing Harn modules.
• Haskell — v0 draft predicates for plain Haskell application and library code.
• HTML — v0 draft predicates for plain HTML markup, accessibility, and safe new-window navigation.
• Java — v0 draft predicates for plain Java application and library code.
• JavaScript — v0 draft predicates for plain JavaScript source, async handling, dynamic-code hazards, and untrusted data boundaries.
• JSON — v0 draft predicates for strict JSON conformance, encoding hygiene, declared-schema respect, and untrusted-data boundaries.
• Kotlin — v0 draft predicates for Kotlin JVM, Android, and Multiplatform source.
• Lua — v0 draft predicates for general-purpose Lua application and library code targeting Lua 5.2+ and LuaJIT.
• Markdown — v0 draft predicates for prose Markdown files used for documentation, READMEs, and design notes.
• PHP — v0 draft predicates for plain PHP application and library code.
• Protocol Buffers — v0 draft predicates for .proto files covering syntax versioning, package hygiene, field numbering, and compatibility.
• Python — v0 draft predicates for Python application and library code.
• R — v0 draft predicates for R analysis scripts, R Markdown / Quarto documents, and R packages.
• Ruby — v0 draft predicates for Ruby application and library code.
• Rust — v0 draft predicates for Rust application and library code.
• Scala — v0 draft predicates for Scala 2 and Scala 3 source covering null safety, immutability, effect-system hygiene, and pattern-match exhaustiveness.
• Shell — v0 draft predicates for POSIX shell and Bash scripts covering strict mode, cleanup traps, eval hazards, and ShellCheck discipline.
• SQL — v0 draft predicates for schema, migration, and query safety.
• Swift — v0 draft predicates for Swift application and UI code.
• Terraform — v0 draft predicates for Terraform configurations across AWS, Azure, and GCP providers.
• TOML — v0 draft predicates for TOML configuration documents (Cargo.toml, pyproject.toml, tool configs).
• TypeScript — v0 draft predicates for TypeScript and TSX code.
• XML — v0 draft predicates for XML payloads, XSD schemas, XSLT stylesheets, and related XML-shaped formats.
• YAML — v0 draft predicates for plain YAML configuration covering parser footguns and unsafe deserialization tags.
• Zig — v0 draft predicates for Zig application and library code covering error handling, allocator lifetimes, build metadata, and explicit low-level operations.

Status

Runtime-backed seed library. This package contributes its pack manifest through harn.canon. Harn owns root discovery, changed-slice evaluation, and feedback delivery; product hosts consume that Harn contract instead of copying predicate routing or policy.

The packs remain v0: each predicate must earn its place with current evidence and a fixture-backed behavior contract. Use this repository to improve pack quality and coverage without recreating the runtime layer.

Contributing

See CONTRIBUTING.md. In short: one language per PR, cite evidence ≤18 months old with at least two independent sources (prefer official language/framework docs), and include fixtures.

License

Dual-licensed under Apache-2.0 and MIT, matching the harn repo.