Metaprogramming & code rules
One CI gate over about eleven domains, a unification no peer has; trails on declarative rule authoring.
1 Strong · 7 Solid · 4 Partial · 0 Emerging
Measured against: semgrep · OPA · Folders: base/meta(opens in a new tab) · base/reflect(opens in a new tab) · base/refine(opens in a new tab) · base/governance(opens in a new tab) · For programmers: this area's reference
Rethought from first principles
What Softanza kept from what works, and what it rethought, as the library wrote it down in its design documents and narrations.
The Softanza wayA house rule is not folklore or a text pattern: it is an object checked over a model of the code, runnable by any programmer, human or machine.
Kept from the best practice
- Findings carry a severity: errors fail the build, warnings only advise. Existing checkers keep their old output shapes behind thin adapters, so nothing downstream breaks. source(opens in a new tab)
- Not everything belongs on a graph. A naming rule such as no-aggressive-verbs stays a plain text check; the aim is to stop pretending a text scan is a model. source(opens in a new tab)
- Rules that change behaviour roll out gently: constraint rules ship opt-in per domain, in validation mode first, with a migration window for existing callers. source(opens in a new tab)
Rethought
- Rules run over a code graph, not line by line. The graph tells a definition from a call and sees two methods colliding by case, which a line scan cannot. source(opens in a new tab)
- Guardrails become gates, not audits. A constraint rule refuses illegal wiring when it is built: granting an effect capability to a language-model actor is rejected on the spot. source(opens in a new tab)
- One rule engine serves code, agents, security, workflows and org charts, with one finding shape and one gate. Performance budgets and data findings join the same gate. source(opens in a new tab)
- Thousands of test lines state the output they promise. A harness runs each file and compares, and is itself tested on deliberately wrong promises. source(opens in a new tab)
The distinctive thing here is unification, not any single tool: one CI gate (stzRuleReport) collects findings in one shape from ~11 domains -- code rules, agent-graph invariants, security reachability, org charts, service contracts, workflow SLAs, even diagram notations -- something neither semgrep (code-only) nor OPA (policy-only) attempts. The honest gaps are extensibility (no way to author a custom rule pattern), a two-grammar tree-sitter, and shallow reflection.
What a crafter does with it, and what stands out
- One CI gate, one finding shape, across ~11 domains -- a genuine category-of-one
- Code rules born from the library's own hard-won bugs, so it lints itself
- A three-language code graph (Haro, Python, JS) that self-checks via CheckRules()
- A signable, sha256-sealed rule constitution -- governance of the rules
What is owed
- Declarative rule and policy authoring (semgrep-style patterns, Rego-style expressions)
- Broaden tree-sitter and put Haro on it
- Richer reflection; resolved call edges and dataflow; full dominator analysis for effects-guarded
- Production-harden the semantic resolver; a policy expression language
The Softanza way, run
What Softanza does differently in this area, shown by code taken from its narrations and guards, and run for this page.
The rule reads call edges, so a real call is flagged while a method merely named substr is not.
aF = StzCheckCode("class Foo" + nl + "def Bar()" + nl + " x = substr(s, 2)" + nl)
nF = len(aF)
for i = 1 to nF
? aF[i][:rule] + " @line " + aF[i][:line] + " [" + aF[i][:severity] + "]"
next
? "findings: " + len(StzCheckCode("class Foo" + nl + "def substr(x)" + nl + " return x" + nl))engine-first @line 3 [warning] findings: 0
run on 2026-10-01 21:18 inside the library at commit 0e72e2e2c; taken from base/doc/narrations/stz-rules-as-graph-rules-narration.md(opens in a new tab)
Granting the power to act to a language-model actor is refused at construction, not merely reported afterwards.
oAG = new stzAgentGraph("mailer")
oAG.AddLLMActor("writer")
try
oAG.Grant("writer", "effectful")
catch
? cCatchError
doneREFUSED: granting 'effectful' to llm actor 'writer' -- an LLM proposes, only a pi-gate commits (no-llm-effectful, enforced at CONSTRUCTION, not merely audited).
run on 2026-10-01 21:18 inside the library at commit 0e72e2e2c; taken from base/doc/narrations/stz-rules-as-graph-rules-narration.md(opens in a new tab)
A sandboxed actor that holds no effect itself is still caught, because the graph finds a path to an effect through a tool.
oSG = new stzSecurityGraph("resto")
oSG.AddActor("llm", "sandboxed")
oSG.AddTool("shell")
oSG.Uses("llm", "shell")
oSG.Grants("shell", "effectful")
? "llm holds effectful directly? no. reaches it by a path? " + oSG.ReachesEffectful("llm")llm holds effectful directly? no. reaches it by a path? 1
run on 2026-10-01 21:18 inside the library at commit 0e72e2e2c; taken from base/doc/narrations/stz-rules-as-graph-rules-narration.md(opens in a new tab)
The lanes, one by one
Lanes and their notes are quoted as they were read at the source, on Read from the source on 2026-09-16, from a read-only main worktree.