Medulla Development
The medulla repository is a Cargo workspace: 48 member crates under
crates/ plus the root facade package medulla-engine (src/), root version
2.27.0. Its failure mode is not bugs — it is sprawl: a second predicate that
answers a question already answered, a hand-copied list of another crate's tables,
a shared helper extracted across a boundary it should not cross.
Read this file before writing EG code. Every claim below was verified against the tree; anything unverified is marked. Verify again — the tree moves.
Spec-driven flow
Run this before any code. Full table and gates: the Spec-driven development section of AGENTS.md and the spec standard.
- Read
.specify/memory/constitution.md; create it from.specify/templates/constitution-template.mdif absent (speckit-constitution). - Specify the feature:
speckit-specifygathers the inputs and writesspecs/<stable-id>/spec.mdandrequirements.md. - Clarify: resolve every
[NEEDS CLARIFICATION: ...]marker (speckit-clarify). - Plan:
plan.mdfrom.specify/templates/plan-template.md, including Build contract, Production caller chain and Cross-repo seams (speckit-plan). - Tasks:
tasks.mdlines- [ ] T001 [P] [US1] <ROW-ID> ...(speckit-tasks). - Analyze: fix the gaps and fill
checklists/requirements.md(speckit-analyze). - Implement and land with the delivery contract in this skill (
speckit-implement); release through pipelinesreleases/*.ymlbundles.
Never write code for a row that is not SPECIFIED. Feature directories use the stable spec ID, never a numbered prefix. The state is computed from rows, Spec: trailers and test bindings; never write status.json or a Status: line.
Rapid delivery: the 5-minute contract
Specs are already designed. The work is implementation, delivered in very small, continuously landed slices.
Time and size
- One agent delivers one PR in 5 minutes or less. No agent or sub-agent runs longer than 5 minutes; an orchestrator dispatches the next slice to a fresh agent.
- CI turns around in 5 minutes or less. PR CI runs the fast subset: lint, type check, the spec check, and only the tests and crates the diff touches. Pushes to main run the full suite.
- Never spawn sub-agents from a delivery agent.
Investigation budget
- At most 2 minutes and about 10 tool calls of reading before the first edit, and at most about 25 tool calls per PR.
- If the change is not clear by then, ship the
.1slice (typed model plus refusal test) or skip the row with a one-line note. Do not write deferral essays. - Trust the orchestrator's evidence and ID list; do not re-verify it.
Sizing (deterministic)
- Split a requirement when its size score is above 6, it names more than 2 code roots, or it is cross-repo. Children are
<ID>.<n>, producer first. - Net-new work is sliced, never skipped:
.1typed model plus validation and refusal tests,.2the one entry point that uses it,.3+ each further behavior. - Cross-repo moves split into one child per repo: the destination copies the behavior first, then the source switches importers and deletes.
Before every push
- Work in a real
git worktree addfromorigin/main. Never edit a shared checkout, nevergit stash, nevergit add -A, never force-push. - Run the repo's own pre-commit on the changed files:
uvx --from pre-commit==4.6.0 pre-commit run --files $(git diff --name-only origin/main...HEAD). Fix every failure. Nonoqa,type: ignore, skip, xfail or whitelist entries to pass a gate. - Run the targeted tests only, never a full suite.
Landing
- Every PR lands within minutes of going green; no PR sits idle. Mechanical conflicts (generated files, Markdown) are resolved automatically by the merge-train tool. Real conflicts are additive in most cases and are resolved, not deferred.
- Many open PRs land together as a merge train (one integration branch, one CI run), built with the orchestrator's merge-train tool.
- Full CI on main catches what the fast subset missed; regressions are fixed forward immediately.
- Landing in this repo: delivery agents open the PR and do not run per-PR build-host builds or merge. The orchestrator lands EG in batches about every 20 minutes, validated by one warm integration build (
cargo check --workspace --all-featuresplus contract regeneration) on the least-loaded build host.
Report: at most 8 lines: PR URL, requirement IDs, test result, and any ID:<main sha> proof for rows already on main.
0. Mandatory guardrails — read these before §1
Twelve rules. Every one was broken in this program, usually by someone who had just written it down — so each names the failure that produced it and, more importantly, what actually enforces it here today. A rule you have to remember at the moment of writing is not a guardrail; a rule with a gate behind it is. Where nothing enforces one, that is stated plainly rather than implied away. Numbers are cross-referenced to the section that owns them, never restated.
| # | The rule, instantiated for EG | Enforced today by |
|---|---|---|
| G1 | State the universe with every number. MUST. An arch-lint count means nothing without which target dirs were in scope; a test count means nothing without the feature set (G3). |
Nothing — discipline. Self-check: every number you report is followed by the exact command that produced it. |
| G2 | A gate's declaration is not its behaviour. Run it. MUST. arch-lint.toml declares preset = "minimal" — which arch-lint list-rules shows is AL001 only — and then disables AL001, so a config-faithful run would enforce nothing. 0.5.0 ignores the preset and runs 7 rules. §3 has the measured verdict. |
Nothing — discipline. Self-check: arch-lint list-rules, then cite the gate's OUTPUT with its invocation quoted. Never cite arch-lint.toml. |
| G3 | "Green" is meaningless without its feature set. MUST. 133 features; 97 in the default closure; 36 outside it. Procedure + command below. |
Nothing — no hook checks feature closure. Self-check command below. |
| G4 | A fix that passes only its author's own new test has demonstrated nothing. MUST. §7.1 and §7.5 are both this. Procedure below. | Partly: the pytest hook (pre-push/manual) gates the Python integration suite differentially via scripts/check_integration_baseline.py. Nothing scopes the Rust suite for you — do it by hand, below. |
| G5 | Re-derive the consequential closure on every composition. MUST. A frozen path set describes the base it was cut against, not the base it lands on: MutationBatch v1 was accepted at 18 paths and composed to 53 (commit 1d83cf4b). A candidate's recorded path count is a LOWER BOUND, never a scope. |
Partly: persisted-mutation-contract sources its inventory from scripts/method_policy_inventory.py instead of a frozen list, so the method surface re-enumerates itself rather than being frozen (⚠ that hook is RED today for an unrelated reason — §3). Everything else: discipline. |
| G6 | Verify a claim before acting on it — including from a skill, a brief, or a report. MUST. The migration contract said identity.graph_name(), which does not exist (§5). §7.7 lists four recorded items that were stale as written. |
Nothing — discipline. Cite file:line you personally opened. |
| G7 | Never delete on island evidence alone. MUST NOT. A module island is a compile fact; a symbol island is a lead. Static analysis here cannot see trait objects, macro-generated calls, #[cfg] paths, FFI, or string-keyed registries — and 36 features are outside the default build, so a symbol can look unused purely because you never compiled its feature (G3 again). |
Nothing — dead_code is per-feature-set only. Trace it by hand before deleting. |
| G8 | No baseline files. Ever. MUST NOT. Verified 2026-09-03: no --update-baseline mechanism exists anywhere in scripts/ — the sole mention is check_tracked_privacy.py:1045 recording that its own was DELETED. Two committed known-bad lists do exist and are the permitted shape, not ratchets: tests/integration_failure_baseline.txt (79 lines) and tests/protocol_unbound_baseline.txt (173 lines). |
scripts/check_integration_baseline.py — it refuses a malformed line, requires # owner=@handle review-by=YYYY-MM-DD per entry, fails when anything NEW joins and when anything on the list starts passing. A ledger that rots loudly. Add no third list, and never add a self-updating flag. |
| G9 | A gate whose universe is empty must FAIL, not pass. MUST. Vacuous truth is not coverage. | Enforced by example — copy this shape. scripts/check_mint_lease_call_sites.py exits non-zero on ZERO matches: "either the scan paths drifted or the feature was deleted … don't let it go quietly blind." Verified passing today: 1 production call site (src/server/dispatch.rs:4974), 1 test-only. Any new gate you write must refuse an empty universe the same way. |
| G10 | A count's composition matters as much as its size. MUST. "Fix the exclude, remove 1,144 arch-lint findings" was true and useless — 0 of those 1,144 were blocking errors. arch-lint.toml's exclude lists **/target/** and not target-isolated/**; verified. §3 owns the breakdown. |
Nothing — discipline. Break every delta down by rule and severity before calling it progress. |
| G11 | Isolation and staging. MUST NOT. Never edit the canonical checkout; never use the harness's worktree-isolation tool (it sets core.bare=true on the shared common dir); never git stash (refs/stash is repo-wide across 50+ worktrees); never git add -A/.; never export CARGO_TARGET_DIR; never update-ref to advance a branch — merge --ff-only, then verify by TREE (git cat-file -e HEAD:<path>), not by ref. ⚠ pre-commit run --all-files belongs on this list too and §8 currently tells you to run it: it git stashes every UNSTAGED change around the run, and a file-rewriting hook touching the same path can silently DROP those edits on restore. EG ships no safe wrapper. Use §8's own replacement — a throwaway detached worktree with a lane-private PRE_COMMIT_HOME and TMPDIR. (agent-utilities' scripts/safe_precommit_all_files.py derives its repo root from git rev-parse in the cwd and so is repo-agnostic in principle; that is unverified against EG — do not treat it as a shipped affordance here.) §8 "Git, in a shared multi-worktree repo" owns the rest of the list with each prohibition's replacement — read it, this row is only the index. |
lane-guard refuses a commit authored in the canonical checkout and a commit made with CARGO_TARGET_DIR exported off-lane. git stash, git add -A, the harness worktree tool and update-ref are NOT enforced — discipline. |
| G12 | Fail closed, and never substitute a sentinel for absence. MUST. A native scope has no graph name: comparing Option against Some(x) is correct; an empty-string sentinel is a security defect. Worked instances below. |
Partly: universal-read-rls-architecture and mint-lease-call-sites cover parts of the served-read seam. The scope→authz_action mapping is not gated — see the two live shapes below. |
G3 in practice — the feature matrix, and why --lib green is not green
Run this. It needs no build and it is the command that revealed the problem:
python3 - <<'PY'
import re, tomllib
f = tomllib.load(open('Cargo.toml','rb'))['features']
closure, stack = set(), list(f['default'])
while stack:
x = stack.pop()
if x.startswith('dep:') or '/' in x or x in closure: continue
closure.add(x); stack.extend(f.get(x, []))
src = open('src/lib.rs').read().splitlines()
outside = [(m.group(1), g) for i, line in enumerate(src)
if (m := re.match(r'\s*(?:pub )?mod (\w+);', line))
and (g := re.findall(r'feature = "([\w-]+)"', src[i-1] if i else ''))
and not any(x in closure for x in g)]
print("features:", len(f)-1, "| in default closure:", len(closure),
"| outside:", len(f)-1-len(closure))
print("src/ modules the DEFAULT build does not compile:", outside)
PY
Output on 1d83cf4b: features: 133 | in default closure: 97 | outside: 36, and
src/ modules the DEFAULT build does not compile: [('raft', ['raft'])] —
src/lib.rs:154 gates pub mod raft; on the raft feature, and raft is
reachable only through cluster, which is outside default.
Why this is not academic. src/raft/ is 32 .rs files (find src/raft -name '*.rs' | wc -l). Commit 1d83cf4b edited
src/raft/store.rs — replacing two graph-name comparisons with the fail-closed
match … scope().graph_name() { Some(g) => …, None => false } shape, i.e. code
written specifically to satisfy G12 — and its own verification line reads
"cargo test -p medulla-engine --lib at --test-threads=4 reports 1270 passed, 0
failed, 3 ignored." --lib at default features never compiled a line of it.
Separately, src/raft/cross_shard_txn.rs:845 calls the 3-argument
eg_mutation_store::read_record (crates/medulla-mutation-store/src/store/persist.rs:348);
that call site is also compiled by no default build, so nothing in the repo's
routine gate suite has ever type-checked it.
So: name the build in every acceptance claim. 1,270 passed is a statement
about -p medulla-engine --lib under default, and about nothing else. If your
diff touches a path behind a non-default feature, you owe a second run:
cargo check -p medulla-engine --features raft # or the feature that gates your path
cargo test -p medulla-engine --lib --features <set> -j 8 -- --test-threads=4
G4 in practice — the scoped PRE-EXISTING run, before the full one
Twice in one session a plausible fix compiled and passed the fixture written for
it, and was wrong: the three-class predicate split (caught only by a
pre-existing test, §7.1) and the SqlCatalog/Broker reclassification
(15 → 27 failures, §5). A scoped run that only covers new tests is not
evidence. Do this, in order, before the full run:
- Name the touched crates — the package name equals the directory name for
all 48 crates (verified), so this mapping is exact:
git diff --name-only main...HEAD -- '*.rs' \ | sed -E 's#^crates/([^/]+)/.*#\1#; s#^(src|benches|tests)/.*#medulla-engine#' \ | sort -u - Name the pre-existing test modules that already exercise what you changed —
by symbol, not by file, because the tests that catch this class live in
another crate or in an inline
#[cfg(test)] mod(the 15 → 27 regression was caught bywired_catalog_tests, an inline module atsrc/server/wire/mod.rs:5470, and bysqlite_wire— neither is in the changed files):git grep -n 'mod .*_tests\b' -- src/ crates/ | grep -i '<the thing you changed>' git grep -l '<the symbol you changed>' -- src/ crates/ tests/ - Subtract your own new tests so what remains is genuinely pre-existing:
git diff --name-only --diff-filter=A main...HEAD - Run the remainder BY NAME first, then the crate, then everything:
cargo test -p medulla-engine --lib wired_catalog_tests -j 8 -- --test-threads=4 cargo test -p <touched crate> --lib -j 8 -- --test-threads=4--test-threads=4is not optional — the suite deadlocks at the 24-thread default (§8). - Say which pre-existing test would have caught the bug had it been running. If none would have, you have not written the test yet.
G12 in practice — two live shapes on the current tree
Both verified 2026-09-03; neither is gated, so neither will stop you.
- An empty rendering set is not "no restrictions."
src/server/policy_export/mod.rs:356returnsRenderings::default(), sotrino/opensearch/lakekeepercome back empty for a one-marking bundle, pinned empty by its own test at:718-720. That is deliberate —DEC-CA-04splits generator from applier and CA-26 owns population — so the renderer is not itself the defect. The defect shape is any applier that reads an empty list as "nothing to enforce". If you write that consumer, fail closed on empty. policy:exportis cleared by a read scope.Method::PolicyExportcarriesauthz_action = "policy:export"withmutates = false(crates/medulla-capabilities/src/domains/security.rs:15).coarse_kg_admin_only(src/server/auth.rs:632) matches only anadmin:/security:prefix or an:admin/:controlsuffix, sopolicy:exportfalls past that filter (src/server/auth.rs:185) tohas("kg:read") || has("kg:write")(:193) — a plainkg:readbearer can export the policy bundle.src/server/policy_export/mod.rs:100says the non-admin tier was chosen deliberately; whether a read scope should clear it is a decision someone still has to make, not self-evidently a bug. G6 applies to this very bullet: open those four sites before acting on it. §1 carries the full request→decision chain, the chokepoint, and the two other measured findings; this bullet is only the G12-shaped instance of one of them.
1. The authorization model — who may call what
Four of the five findings a security review produced against this tree are
authorization defects, and not one is a coding error: each reads correctly line
by line and is wrong at the level of the model. So this section comes before
the architecture. Read it before you add a Method, a MethodPolicy row, a
carrier, or a second scope check. Every file:line was opened on 2.27.0 for
this section; re-open them (G6).
The request → decision chain
| # | Stage | Where | Establishes |
|---|---|---|---|
| 1 | Claims arrive as an untrusted wire DTO | RequestContextClaims, crates/medulla-types/src/acl.rs:17 — principal, tenant, audience, agent_id, roles, scopes, policy_version, delegation, node, priority |
Nothing. Its own doc: "Callers must not treat a deserialized value as trusted until the server has verified the envelope MAC, deployment audience/tenant/policy version, request binding, and delegation chain." |
| 2 | Envelope verification | verify_request_with_security_dir (src/server/auth.rs:1773) → verify_envelope_v2_with (:1681) |
eg2. prefix → HMAC over the request → clock-skew window → validate_context_claims (:1110) → bind_verified_identity (:1550) → non-empty idempotency key → durable replay-nonce consumption (:1709). Order matters: the nonce is spent last, so a claims-invalid request costs no ledger write. |
| 3 | Claims → identity binding | validate_context_claims (:1110) |
Required claims non-empty; no duplicate role/scope/delegation entries; req.agent_id matches; the delegation chain must run principal → agent_id (empty iff principal == agent_id); audience/tenant/policy-version equal the deployment's; a present node claim exact-matches this node. |
| 4 | IdP binding | bind_verified_identity (:1550 under oidc; :1658 without it) |
Every claimed role must appear in the verified token's roles, and every claimed scope must appear in its scopes or roles — "request context asserts unverified scope '{scope}'". require_oidc() (:1482) defaults to true, so a build with no configured issuer fails closed rather than accepting HMAC-only identity. A caller cannot self-assert kg:read; the IdP grants it. |
| 5 | The trusted wrapper | VerifiedRequestContext (:60), built only by from_verified_claims (:68) |
Private fields, so "downstream code cannot construct a trusted context from caller-supplied JSON." Two indexes are derived once here (:69-74): scope_index (scopes verbatim) and scope_wildcard_domains (each scope's ":*" suffix stripped). |
| 6 | The decision | VerifiedRequestContext::allows_method(action, mutates), src/server/auth.rs:177 |
The one function answering "may this principal call this method." Name it exactly; there is no second one. |
action and mutates are never chosen at the call site — they come from the
capability ledger: eg_capabilities::policy(&req.method) yields
MethodPolicy { authz_action, mutates, durability_domain, audited, emits_cdc, … }
(crates/medulla-capabilities/src/lib.rs; rows in src/domains/*.rs).
allows_method then decides in five ordered steps: (1) allows_action(action)
(:148) — the exact scope, a domain wildcard (graph:*), or global *
→ allow; (2) kg:admin → allow, unconditionally; (3)
coarse_kg_admin_only(action) (:632) — a string test,
starts_with("admin:") || starts_with("security:") || ends_with(":admin") || ends_with(":control")
→ deny; (4) mutates → requires kg:write; (5) otherwise →
kg:read || kg:write. Step 5 is the fall-through that produces finding 1.
The scope vocabulary that actually exists
Verified, because the shape is not what its name suggests. Scopes a caller
holds are kg:read / kg:write / kg:admin (the coarse aggregates, which
appear only in allows_method, allows_analytics_worker and the carrier
minters), *, <domain>:*, and any exact action string. Actions a method
declares are the 103 distinct authz_action strings the ledger carries
over its 412 rows — node:read, compute:finance, udf:exec,
admin:cluster, … none of them kg:-prefixed. The two vocabularies are
disjoint; do not assume an action is spelled kg:read. Two dedicated
authorities no coarse grant implies: analytics:worker (:159) and
security:bootstrap (:163, which also demands principal == agent_id, an
empty delegation chain, and exactly one scope). replicated_mutation
(:89, raft) mints scopes: ["*"] for the Raft apply task — the one
legitimate * holder, reachable only from the state machine after the leader
already dispatched through the full external gate.
The chokepoint, and what runs beside it
check_scope_and_admin_authority (src/server/dispatch.rs:5349) is the
chokepoint. It has exactly one caller — dispatch_preamble_checks (:5586) —
and every request reaching dispatch_inner (:5647) passes through it,
including one arriving with an already-verified context, because
dispatch_with_context(state, req, Some(ctx)) (:2966) still runs the preamble.
(git grep -n check_scope_and_admin_authority returns the definition and one
call.) In order it applies: (1) check_resource_and_capacity_scope;
(2) check_cross_tenant_scope — "The tenant in a resource body is a
correlation, not an authority claim", so only a privileged aggregate reader or
kg:admin crosses tenants; (3) allows_method(action, mutates) (:5377);
(4) when is_admin_authz_action(action) (src/server/access.rs:1126 —
action == "security:admin" || action.starts_with("admin:")), additionally
require_admin_capability (access.rs:1137) → IsolationLayer::has_admin_capability
(crates/medulla-core/src/isolation.rs:1894): an agent registered in rbac.redb
with AgentRole::System or an explicit RBAC Admin grant. No provisioned policy
at all is a deny, not a default-open (access.rs:1152).
⚠ Those are two different definitions of "admin" and they disagree.
coarse_kg_admin_only matches 22 action strings; is_admin_authz_action
matches 5. The 17 in the gap — 50 of the 412 methods — need the
kg:admin claim but no durable admin grant. security:audit is the clean
example: it starts with security: so a kg:write bearer is refused, but it is
not equal to security:admin, so rbac.redb is never consulted.
src/server/policy_export/mod.rs:100-105 is the in-tree record of this
asymmetry, written by the lane that hit it.
A second axis runs after the method gate: per-graph ACL and row-level
security. Clearing allows_method says the method is permitted; it says
nothing about which rows. That is check_graph_access (access.rs:852) →
IsolationLayer::check_access (isolation.rs:1508, default-deny — an actor
with no provisioned identity returns false before any graph-type rule runs),
plus GraphReadAuthority::from_verified (access.rs:188) and
IsolationLayer::filter_view (isolation.rs:1732). Never treat a scope check
as an isolation check — §7.3's RLS-view-cache finding is what happens when the
two are conflated.
Call sites outside the chokepoint
allows_method has four production call sites that are not
check_scope_and_admin_authority (git grep -n allows_method -- src/ crates/,
excluding tests and comments). src/server/wire/mod.rs:1245 (SQL-carrier
handshake) and src/server/bolt_wire/mod.rs:239 / :409 are additional
earlier gates — those requests still reach dispatch_inner, so they are not
bypasses. src/server/graphql_sub.rs:204 is a genuine parallel path: it
verifies, calls allows_method(policy.authz_action, false), then goes straight
to authorized_snapshot → check_graph_access + GraphReadAuthority::from_verified
and serves from the graph notifier. It never reaches require_admin_capability
or the cross-tenant check — benign today only because GraphQl's action is not
admin-tier, which is a property of one ledger row, not of this code.
Rule: a fifth
allows_methodcall site is a fifth place that must independently get the surrounding checks right. Add one only with a written reason, and say which of the four preamble stages it is choosing to skip.
Three measured findings
1 — a bare read scope reaches 221 of 412 methods. Re-derived for this skill
by parsing crates/medulla-capabilities/src/domains/*.rs and reimplementing
coarse_kg_admin_only's four string tests (script in the reference below):
412 rows · 234 non-mutating · 221 reachable by a caller holding only
kg:read · 45 distinct actions. Recheck these historical counts against the
current tree with scripts/method_policy_inventory.py and the independent
method in references/authorization-reference.md.
The mechanism is step 5: any non-mutating
action whose name does not match one of four string shapes is granted to any
read-tier caller. 110 of the 221 are compute:* — finance, graph-algo,
datascience, semantic, parse, vision. mutates is a durability property
being used as an authorization property; those are different axes, the same
category error as §5's scope/domain conflation. The narrow fix (one more string
in coarse_kg_admin_only) leaves 220 methods unchanged while looking closed;
the general fix is a declared coarse posture on the MethodPolicy row with
no Default impl, so a new method fails to compile until it states its answer.
2 — RunUdf executes caller-supplied code, unaudited, in a default build.
crates/medulla-capabilities/src/domains/compute.rs:113 declares it
mutates: false, authz_action: "udf:exec", audited: false — so it clears
kg:read and leaves no audit-chain record — and its ledger row carries no
#[cfg], unlike Quantum, Asr, TtsSynthesize and PolicyExport.
⚠ Correction to how this is usually stated: the Method variant is
feature-gated (crates/medulla-types/src/protocol.rs:2866, #[cfg(feature = "wasm-udf")];
dispatch arm src/server/dispatch.rs:11949) — but wasm-udf is inside full,
which is inside default (verified with the G3 closure script), so it is
compiled and routed in a default build anyway. The conclusion holds; the
reason "there is no cfg gate" does not. The sandbox is real (crates/medulla-wasm:
wasmtime, fuel + memory limits, no host capabilities) — the finding is about who
may invoke it, and that nothing records that they did.
3 — whether a read scope should clear policy:export is an OPEN DESIGN
QUESTION, not a bug. Method::PolicyExport declares "policy:export",
mutates = false (crates/medulla-capabilities/src/domains/security.rs:15), so it
falls through to kg:read || kg:write. src/server/policy_export/mod.rs:100-105
records that the non-admin tier was chosen deliberately: naming it
"security:admin" — the obvious first choice, matching
GetIdentity/RegisterIdentity — would have routed it through
is_admin_authz_action and therefore through rbac.redb (M7) instead of the
effective request-time role set, "silently reproducing the exact mistake
DEC-CA-04 A2 corrected." src/server/access.rs:2293 carries the same
rationale. So the admin-tier decision is settled and documented; what nobody
has decided is whether the read tier should clear it. Do not "fix" this.
Raise it as a decision, name DEC-CA-04 A2, and let the owner rule. It is also
outside the default build (policy_export ∉ the default closure), so any
change needs a declared feature set to be tested at all (G3).
Enumerations — all 103 action prefixes with method counts, the 45 actions a
read scope clears, the two admin definitions and the 17 strings between them,
the six cfg-gated reachable rows with their default-closure status, and the
script that re-derives 412 / 234 / 221 / 45 / 22 / 5 / 50 — are in
references/authorization-reference.md.
2. Where code goes — the layer model
48 member crates under crates/ plus the root facade medulla-engine
(src/). Source of truth: Cargo.toml [workspace] members, the crates'
Cargo.toml dependencies, and their public interfaces. The current layer model is:
0 contract leaves (medulla-types — the DAG's bottom and the only crate
everything can see — medulla-durable, medulla-quantum-core, medulla-resource,
medulla-sqlite-format, medulla-wasm, medulla-viz-core) → 1 shared seams
(medulla-modality, medulla-mutation-store, medulla-capabilities) → 2 modality/index
leaves (13 crates) → 3 core (medulla-core) → 4 storage/transaction
(medulla-tsdb, medulla-jobs, medulla-statechart, medulla-kvcache, plus
src/server/persistence/) → replication (src/raft/) → 5
query/reasoning (medulla-compute, medulla-query, medulla-epistemic, medulla-plan,
medulla-rdf, medulla-shacl, medulla-shex, medulla-graphql) → 6 server/protocol adapter
(src/ — there is deliberately no medulla-server crate) → 7 binary
composition ([[bin]] targets behind required-features). Plus four
default-off specialty sub-DAGs (quantum ×6, viz ×5, providers ×2, medulla-pyengine).
Two subtrees the layer table used to omit: src/server/persistence/ (13
files, 21,637 lines) is Layer-4 storage living inside the Layer-6 facade —
the GraphStore trait plus its one redb_backend implementation, not wire
code; src/raft/ (32 files, 29,761 lines, declared at src/lib.rs:154) is a
top-level src/ module beside the server adapter, a consensus tier between
storage and dispatch, and it is outside the default build so no routine
gate type-checks it (G3). Together they hold 293 of the 687 arch-lint
blockers (42.6%) — so that burn-down is a storage/consensus workstream.
A crate may only
usecrates to its left. No storage or query crate imports server dispatch.
Enforced by Cargo, not by a lint — crates/* cannot depend on the root
medulla-engine package because the root depends on them, and no
crates/*/Cargo.toml declares it. ⚠ That covers [dependencies] only;
[dev-dependencies] cycles exist and build fine. ⚠ The numbering is a
target: three shipped crates already violate it, so use the table to answer
"which direction should this edge point?", never "is this edge legal?"
The per-crate "what this crate OWNS" tables for all 48 crates, the specialty
stacks, the three violating crates, the dev-dep cycle, the two stale AGENTS.md
claims, and the full placement argument with the arch-lint distribution by path
are in
references/architecture-reference.md.
Open it before creating a crate or moving a module.
Finding a symbol's CONSUMERS before you change it
The direction rule tells you where a new thing belongs. It says nothing about
who already holds the thing you are about to change — and with 36 of 133
features outside the default closure (G3), the consumer set you can see
is smaller than the one that exists. Four commands; run all four, they answer
different questions:
# 1. Every crate that DECLARES the dependency — feature-independent, from the manifests.
git grep -n '^<crate> = ' -- 'crates/*/Cargo.toml' Cargo.toml
# 2. The reverse dependency tree cargo will actually BUILD, under one feature set.
cargo tree -i <crate> -e normal --offline # default features
cargo tree -i <crate> -e normal --offline --all-features # the widest set
# 3. Every source reference to the SYMBOL, including tests and benches (a trait impl,
# a macro body or a string-keyed registry never appears in 1 or 2).
git grep -n '<Symbol>' -- src/ crates/ tests/ benches/ examples/
# 4. Its declaration site, to learn how far it can travel at all.
git grep -n 'pub\( *(crate)\)\? \(fn\|struct\|enum\|const\|trait\) <Symbol>' -- src/ crates/
Why all four. Measured on medulla-modality, 2026-09-04: 23 manifests declare
it as a direct dependency, but cargo tree -i medulla-modality -e normal --offline
returns 11 nodes — the rest are optional or behind a non-default feature.
cargo tree alone under default features hides more than half the consumers;
the manifests alone tell you nothing about which of them compile the path you
are touching; and neither sees a trait object, a macro-generated call, or a
string-keyed registry — which is exactly why G7 forbids deleting on island
evidence alone. Visibility is the fourth question: a pub(crate) item's blast
radius is one crate and cargo check -p <crate> is a complete consumer test; a
pub item in medulla-types can be reached by all 48, and only --all-features
sees them all.
3. What is actually enforced, and what is red today
.pre-commit-config.yaml declares 60 hooks. For the architecture-enforcing
subset — and the contract- and hygiene-enforcing ones beside it — every hook id,
its script, exactly what it refuses, the scope traps in the two non-Rust hooks,
and the per-hook measured PASS/FAIL state with each failure's real message, see
references/gates-reference.md. Read the row
there before citing what a gate enforces (G2). Headlines before you plan work:
- Nothing checks crate-graph direction.
arch-lint0.5.0 has 8 rules and none is a dependency rule; Cargo does that job (§2). rust-arch-lintis RED with a measured denominator:arch-lint checkreports 4,642 findings, 687 blocking over 1,077 files (re-run 2026-09-04, identical to the recorded census). All 687 are AL002no-sync-io, and 293 (42.6%) sit insrc/raft/+src/server/persistence/. About a quarter of the warnings are vendored build artifacts scanned through a broken exclude — fix the exclude before scoping the work (G10).- Four other gates are red (re-run 2026-09-04):
persisted-mutation-contract,current-only-architectureandexact-fault-restart-harness-architectureall fail on a path or literal their contract merely MOVED past — see §4, which is about exactly that.p2-modality-architectureis the one naming a real defect ("KnowledgeStream retains a claims-only or conditionally fenced served path"); do not relax it. - Heavy hooks (
cargo-clippy,cargo-clippy-all-features,cargo-deny-advisories,wheel-smoke,pytest,constrained-parallelism) are unmeasured here. Do not infer their state.
Rule that produced several of these: composing candidates into a repository whose gate suite is already red hides the regressions the composition itself causes. Keep a named per-hook baseline and re-run it after each composition; an aggregate pass/fail count cannot tell you what you just broke.
4. Authoring a gate — how not to ship coverage you do not have
The most repeated failure in this program is not a gate that fails; it is a gate
that reports coverage it does not have. One passed on an empty universe; one
measured two of the five properties it claimed; one crashed and still looked
green. A gate is a claim about the world, and an unfalsified claim is worth
nothing. Four rules. The evidence for each — the full worked instances, with the
file:line you can open — is in
references/gates-reference.md →
"Evidence behind the gate-authoring rules".
4.1 Prove it FAILS on a known-bad input before you trust a pass
A gate you have only ever seen pass has demonstrated nothing (G4; §7.5 is the same rule for fixes). Construct the violation the gate exists to catch, run it, watch it exit non-zero, then remove the violation. If you cannot construct the bad input, you do not yet know what the gate enforces.
A gate whose universe is empty must FAIL (G9). Copy this shape —
scripts/check_mint_lease_call_sites.py:88-95 refuses its own empty universe
with "found ZERO calls … either the scan paths drifted or the feature was
deleted … don't let it go quietly blind." ⚠ It is nearly alone: measured
2026-09-04 across the 27 scripts/check_*.py gates, 24 have no emptiness test
at all and only this one turns a test into a refusal (command in the
reference; it is a heuristic, so audit the gate you copy from).
4.2 State the universe and the denominator, in the gate's own output
G1 applies to gates, not only to reports. A gate must print what it
scanned, not only what it found: "0 violations in 0 files" and "0 violations
in 1,077 files" are different verdicts and most output cannot tell them apart.
Two live instances, both in the reference: a universe that silently grew
(arch-lint.toml excludes **/target/**, but the committed target dir is
target-isolated, so 1,144 of 4,642 findings are vendored codegen), and one
that silently emptied (a real git commit exports GIT_DIR/GIT_INDEX_FILE
into every hook and git -C <root> ls-files does not override them; a
liveness gate reported orphan_modules: 4 → 196 with zero source changes).
Two independent fixes for that second one already exist here —
scripts/_git_subprocess_env.py and scanner_contract.run_git/sanitized_env —
while two gates still call git ls-files with no env=. Adopt one of the two;
write neither a third nor a bare call. Test a suspect gate both ways: plain,
then with GIT_DIR and GIT_INDEX_FILE set to the worktree's real gitdir and
index. Different answers mean the universe is ambient, not declared.
4.3 Never key a gate on a byte offset, a line number, or a symbol name
All three have broken here. A gate keyed on the text of the code cannot distinguish a contract that was lost from one that moved — and refactoring moves things, which is the whole point of the work these gates supervise. The false positive is the expensive direction: it reds the tree, sends someone to fix correct code, and trains everyone to override the gate.
scripts/check_exact_fault_restart_harness.py fails today with 18 missing
literals, every one of which is present in the tree — a file became a module
directory, a function moved into a submodule, and a parameter type was
tightened from a raw WriteTransaction to the validated MutationWrite. Its
sibling persisted-mutation-contract fails the mirror-image way (it expects a
module directory whe
…(truncated)