## Summary Raven can now read and change its own configuration through one tool, `raven_config`, instead of telling the user to open Settings or editing `config.json` with file tools. The same path lets it connect preset sub-agents and diagnose the ones that do not answer, and asks the user only for what needs them (a key, a sign-in, a paid model). **The tool and its catalog** - `raven_config` actions: `describe` (every setting with its value, or a search), `get`, `set` (one path, or several under one confirmation), `unset`, `add` (connect presets, several at once), `test`, `restart` (reload or restart once pending changes are gathered). `session.model` switches only the current conversation. - `raven/config/self_surface.py` is the catalog: 14 sections, about 93 settings, each with its value kind, its writer, and when a change takes effect (next turn, at once, reload, restart, memory server, or inert). Writes go through the RPC methods the settings page already uses (`SELF_CONFIG_METHODS` allowlist), so the page and the agent share one validation path. `tests/test_config_self_surface.py` holds every entry against the schema and every next-turn claim against a real reader. - A refused sub-agent comes back with one next step per refusal kind (9 Raven fixes itself, 5 the user does), with stop rules: no hunting for keys, no credential stores, no restarting another app's services, stop after three commands that explain nothing. - `subagents.add` stays preset-only: every execution field comes from the preset. Presets can be named by display name, an add can pin a model the agent lists, and a model pick on an unmeasured agent reads the handshake menu first. - The companion skill `raven-self-config` describes the whole flow; its description is injected every turn, the body is read on demand. **Approval** - Reads run unasked. Every write asks by default, on a dedicated config card (what changes, before and after, when it takes effect, a sensitive note). A grant for the session never carries a change. - In a turn someone is at, full access, the user's allow rule, and smart mode's reviewer let a change through; the reviewer never approves a sensitive setting. Sensitivity is declared by the owner: catalog entries (approval mode and review model, workspace confinement, sandbox, deny patterns, disabled tools, MCP servers switched on, skill blocklist and auto-install, provider endpoints, web and media proxies, remote machines, workspace path, lent keys, sub-agent descriptions) and each channel adapter's spec (who may instruct Raven, whether a channel is on, where its credentials and traffic go, encryption). The gate and the tool read a call the same way: one value decoder, one path spelling, one channel field lookup, an object value judged field by field; a path the tool does not write is refused at the gate, and a call naming one setting twice is refused. A value is secret when the schema, the channel spec or the catalog says so, a credential-named env entry, any header, or a credential inside a URL. The reviewer's instruction counts the agent's own non-security settings as ordinary work. Unattended turns (cron and other scheduled runs, no one to answer) are refused; a channel user who can answer an approval is attended. **Secrets** - A key never travels through a tool call. The agent names the secret with an empty value and a credential card of its own (`credential.request` / `submit` / `skip` / `pending` / `closed`) takes it; the host writes it through the handler that owns it and the model learns only saved or skipped. Channel secrets use the same card. A call that only asks for keys goes straight to the card. Enabled on page surfaces only. - Tool output is scrubbed of the values Raven holds (`config/held_secrets.py`, including JSON-escaped spellings and URL credentials) and dotfile reads under home are redacted, once, inside `ToolRegistry.execute`, so the trace span, the page's diffs, the sentinel and both agent loops get the scrubbed copy. What a sub-agent says is scrubbed where it is kept: transcripts, call labels, closing text, the output a later DAG node renders, error records, announces, the ACP frame journal, probe details. A key pasted into the chat is refused. - Lent keys: an ACP sub-agent row can name Raven providers (`lendKeys`) whose key it is started with. The row stores the provider name; each start (the spawn path and the capability probe) reads the key into the variable the preset reads (`presets.LENDABLE_KEYS`, Pi only for now), so it never reaches the model and follows a rotated key. Verified live: Pi refused without it, answered with Raven's OpenRouter key, and its row reads connected and tested with a 398-model menu. **Page** - Config card and credential card; the model and permission chips refresh after the agent changes them; the transcript names `raven_config` calls by what they did. - Agents page: the note on a refused connect, a failed test, or a check that found a problem offers "Hand it to Raven" on its title line; it opens a new conversation with a prompt naming the agent and the reason, not sent. A connected row whose check found a problem now shows one head line and an amber note in the body (shaped like a failure's) instead of the check's English sentence folded under the head. **Other** - Memory LLM left unset follows the main model (EverOS restarts when the main model moves). - Reload and restart wait for page turns in flight too. - `plugin` points agents and chat apps at `raven_config`; `cron` names the missing `message`; a GNU `timeout` shim on hosts without one, accepting only the durations the permission gate parses (one shared definition); read-only package-manager subcommands allow. - Contracts: `CONTRACTS_VERSION` 35 (this branch's credential types plus main's `FileWrite`) with the surface repinned; paper-tier line ceiling 3,700 (measured 3,682) with its review note. `CONTEXT.md` defines the self-configuration surface and lent key. ## Type - [ ] Fix - [x] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - `uv run pytest -q -n auto`: 27187 passed, 3 failed. The 3 fail on this machine regardless of this branch: `test_rpc_files::test_a_host_without_libreoffice_says_so` (LibreOffice is installed here), `test_simulation_scenario::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs` and `test_simulation_suite::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`. `schemas/subagent.schema.json` is regenerated for `lendKeys`; `test_import_cycle_budget` holds (the capability probe takes the launch env from its caller rather than importing the agent layer). - `make lint-ui` (gen:check, eslint, tsc): pass; the 4 eslint warnings are in files this branch does not touch. - `npx vitest run` in `ui-web`: 3116 passed; `check-css`, `check-class-namespace`, `check-page` OK. - `npm run lint:i18n`, `lint:rpc`, `type-check` in `ui-tui`: pass. - `uv run ruff check` and `ruff format --check` on every changed Python file, and `lint-imports` (10 contracts kept): pass. - In a browser against a local gateway: credential card save, skip, replace and reload replay; the value appears in no session, trace or log. Agents page link opens a new task with the prompt filled and unsent; sent, the agent reads the self-config skill and calls `raven_config` first, and for Pi offers Raven's key before a sign-in. - Smart-mode reviewer, run against the real model: 7 ordinary config changes allowed; `sed` or `write_file` on Raven's config, reading an SSH key, and `curl | sh` escalated. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [ ] User-facing docs or screenshots are updated when needed ## Risk - Behaviour changes: the agent can now change settings and connect sub-agents after the user confirms (or unasked under full access, and under smart mode for non-sensitive settings). Lending gives a sub-agent Raven's key for a provider after an explicit, sensitive confirmation; what it spends is billed to that key. - Memory: a memory LLM left unset now follows the main model, so long-term memory starts working after the upgrade for anyone who never pinned one, extracting on the main model and billed to the main provider's key, and EverOS restarts when the main model changes. To keep it off, set `memory.backend` to null; to keep it on a different model, pin one of its own. - Backward compatible: new config fields are optional, and both probe fingerprints include `lendKeys` only when set, so recorded verdicts and menus survive. A `config.json` written with `lendKeys` will not load on an older build (`extra=forbid`). - Rollback: revert this PR; nothing is migrated. To switch the feature off without a revert, add `raven_config` to `tools.disabledTools`. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A --------- Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com> Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
374 lines
19 KiB
Python
374 lines
19 KiB
Python
"""The kernel's size budget, pinned to the numbers the L0 booklet froze.
|
|
|
|
raven/spine is the frozen kernel. Frozen means the promise is not broken while
|
|
the implementation may change, and additions are safe -- but only inside a
|
|
budget, or "frozen" stops meaning anything as the tree around it grows. The L0
|
|
booklet ruled four clauses and measured each true by hand on the two trees it
|
|
compared (1,347 and 1,355 lines; this branch measured 1,360 when the guard
|
|
landed):
|
|
|
|
1. the package holds at most LINE_CEILING lines of Python;
|
|
2. it imports no other raven package -- every import is its own, the stdlib,
|
|
or an allowed third-party name, in-function imports included;
|
|
3. the third-party names are limited to THIRD_PARTY_ALLOWED (tiktoken lives in
|
|
utils, not here);
|
|
4. no file carries a TODO, FIXME or HACK marker.
|
|
|
|
The two numbers were set tight on purpose. Loose (5,000 lines, four third-party
|
|
packages) would let the kernel grow to three and a half times its size before
|
|
anything went red, which three years on is no guard at all; tight means adding
|
|
anything to the kernel passes one explicit review. The booklet also names the
|
|
signal that a threshold was set wrong: loose, and the assertion never once
|
|
fails; tight, and someone starts bumping the number in passing -- the moment
|
|
that happens the guard has lost its authority. So a change to a constant below
|
|
is a reviewed change to this file, never a drive-by, and this docstring is
|
|
where the reviewer reads why the number is what it is.
|
|
|
|
Clause 2 overlaps `the kernel stands alone` (import-linter) and
|
|
tests/test_kernel_closure.py, which ask about the whole kernel set; this file
|
|
asks the narrower question the booklet asked, of spine alone.
|
|
|
|
One addendum (2026-08-31) extends clause 1's discipline to raven/contracts:
|
|
the papers are additions-safe by design, but additions inside a budget --
|
|
1,922 lines when the ceiling landed -- so a new paper passes the same
|
|
explicit review a kernel line does, in the same file the reviewer already
|
|
reads for why the numbers are what they are.
|
|
|
|
The contracts ceiling moved once, 2,500 -> 2,520 (2026-09-09), and this is
|
|
the review. The 578 lines of headroom it landed with were spent, and the
|
|
change that found the end of them adds exactly one line to the papers: an
|
|
``answered`` flag on ``ApprovalOutcome``, so that a permission request nobody
|
|
saw stops being reported to a model as one a human refused. Its prose fits
|
|
the docstring that was already there, so the field is the whole cost.
|
|
|
|
Twenty rather than one. A ceiling a single line under the count is a ceiling
|
|
that fails on the next field, which is how a guard turns into a formality
|
|
somebody edits on the way past -- the failure mode this docstring names. The
|
|
alternative on the table was to shorten an unrelated paper's prose by a line,
|
|
which buys the same room while hiding that the papers grew.
|
|
|
|
It moved again, 2,520 -> 2,730 (2026-09-10), and this is that review. The
|
|
change is a whole paper rather than a field: contracts/harness.py, 198 lines,
|
|
declaring the four strategy roles the agent loop delegates to (Memory,
|
|
Planning, Capability, Action) and the carriers between them. It is the one
|
|
addition the four-module seam needs -- the roles were carved out of code the
|
|
loop already ran, so no behaviour moves with them -- and no amount of trimming
|
|
fits it under the old number: the overage alone is 193 lines against a file of
|
|
198, which would leave four Protocol signatures and nothing saying why they
|
|
are the four.
|
|
|
|
The paper is the whole of it. Without it the package stands at 2,515, which is
|
|
five lines under the number it has been passing on, so nothing here is a
|
|
ceiling absorbing somebody else's growth.
|
|
|
|
Seventeen lines of headroom, and deliberately not more. The smallest paper in
|
|
the package is 37 lines, so the slack cannot absorb a second one: the next
|
|
paper trips this gate and lands in this docstring the way this one did, while
|
|
a field or a docstring line on an existing paper still fits without a review
|
|
nobody would learn anything from.
|
|
|
|
It moved again, 2,730 -> 2,791, and this is that review. Two additions, both
|
|
about a call the loop could not describe once it was over. A failed model call
|
|
had no shape anything could carry: the loop knew a provider had raised and the
|
|
record kept a turn that simply stopped, so a run read back afterwards could not
|
|
say which call failed or what the provider said. ``CallRecord`` is that shape,
|
|
50 lines, with the two fields on the provider paper that hand it over. The
|
|
second is a single field, ``first_byte_timeout`` on ``GenerationSettings``,
|
|
with the prose for why a stream that never started is not a stream that
|
|
stopped: 9 lines.
|
|
|
|
The count is 2,771, and the twenty above it is the same headroom this docstring
|
|
argued for the first time, not room set aside to spend.
|
|
|
|
2,791 -> 2,960 (2026-09-14): the memory seam grew two declared shapes.
|
|
``contracts/memory.py`` gained ``health()`` with ``HealthCheck`` / ``BackendHealth``
|
|
(what ``raven doctor`` and ``raven import`` read instead of the plugin's
|
|
internals), and ``contracts/onboard.py`` is a new paper (``OnboardUI`` /
|
|
``OnboardStep`` / ``StepOutcome``, the screen a memory plugin contributes to
|
|
``raven onboard``). Measured at 2,938 on top of the ``CallRecord`` round
|
|
above; the headroom is the same twenty-odd lines as above, for the same reason.
|
|
|
|
2,960 -> 2,990 (2026-09-15): two grants the seam round left implicit. A
|
|
memory backend gained ``delete()``, which the memory browser needs in order to
|
|
stop deleting a derived index row behind a source of truth that keeps the text;
|
|
and ``ServiceLocator`` gained the host's embedding block, so the knowledge base
|
|
and the memory backend read one endpoint rather than a copy each. Measured at
|
|
2,969; the headroom is the same twenty-odd lines, for the same reason.
|
|
|
|
2,990 -> 3,040 (2026-09-15): ``recall_session`` joins the memory paper,
|
|
so the host can read back what a sub-agent left behind through the contract
|
|
rather than that backend's HTTP API, and ``store``'s two metadata conventions
|
|
are written down where a plugin author reads them. Measured at 3,013.
|
|
|
|
3,040 -> 3,100 (2026-09-17), and this is that review. No new paper: thirty-
|
|
nine lines onto two that were already here, both spent saying where a
|
|
dispatch's playbook is read rather than adding anything it can say.
|
|
|
|
``ActionModule`` gains ``judge`` (28 lines with its prose). The judgement a
|
|
playbook carries was read by a module-level helper inside the tool registry,
|
|
which put "what the agent does next" in two places -- the role for deciding it
|
|
and a private function for vetting it. The method moves the reading to the
|
|
role and leaves the refusing where it was: ``ToolRegistry.execute`` still
|
|
decides what a refusal does, so a replaced role withholds nothing it could not
|
|
already withhold. The prose is most of the 28: two callers and two moments is
|
|
the part a reader gets wrong.
|
|
|
|
``TurnContext`` and ``AssemblyContext`` gain ``task_brief`` and
|
|
``task_done_when``, 11 lines. The identity segment used to reach into the
|
|
dispatch layer's ContextVar to find out what this turn was asked to do, which
|
|
decided "what does this turn show its model" somewhere the Memory role could
|
|
not see it. Memory fills the two strings now and the segment renders them.
|
|
|
|
Measured at 3,072, and the twenty-eight above it is the headroom this
|
|
docstring has argued for since the first bump: a ceiling the next field trips
|
|
is a ceiling somebody edits on the way past.
|
|
|
|
3,100 -> 3,200 (2026-09-17), and this is that review. The Memory role gains
|
|
its mid-turn seat: ``shrink``, with ``WindowPressure`` (the five reasons a
|
|
window is asked to get smaller), ``WindowState`` (one turn's readings and
|
|
retry budgets, held by the shell because the role outlives the turn) and
|
|
``ShrinkResult``, 84 lines of which the prose is most. The five recoveries the
|
|
loop ran inline -- proactive compaction, the standing image window, overflow,
|
|
a picture refused in a tool result, pictures refused for size -- now go
|
|
through this one method, so the policy half moved onto the role while the
|
|
retry mechanism stayed in the shell; the six ``continue`` statements did not
|
|
move. ``REASONING_EFFORT_LADDER`` (11 lines with its prose) also lands in
|
|
``llm_provider.py``: the loop's empty-response descent and the window's head
|
|
summary both read it, and neither package may import the other.
|
|
|
|
Measured at 3,170, thirty over the count rather than one, for the reason the
|
|
first bump gave.
|
|
|
|
3,200 -> 3,410 (2026-09-18), and this is that review. The change is a whole
|
|
paper: contracts/agent_conduct.py, 191 lines, the nine verbs a sub-agent
|
|
implements instead of the six hook phases (``AgentConduct``, its ``StepView``
|
|
of fourteen read-only fields, the ``Intake`` and ``Verdict`` it answers with,
|
|
the per-turn ``ConductFactory``, and a diagnostic trail so a gate's one-line
|
|
findings still reach the loop's notes). Left in the names and the count it was
|
|
written with: an entry here is a dated record of one bump, not a description of
|
|
the file today, and the paper has since been renamed to contracts/participant.py
|
|
and grown past 191 lines -- both under their own entries below. It sits beside ``loop_hooks`` rather
|
|
than replacing it: the phases remain the loop's timing contract, this is the
|
|
judgement contract, and an adapter seats one in the other. Surveyed before it
|
|
was written -- 42 real hook implementations across five plugins read fourteen
|
|
context fields and used six decision fields, and every one of them fits one of
|
|
the verbs -- so the paper is sized to what exists, not to what might.
|
|
Factory-loop tier, so the contract-tier digest and ``CONTRACTS_VERSION`` do
|
|
not move with it.
|
|
|
|
Measured at 3,379, thirty-one over the count, for the reason given above.
|
|
|
|
3,410 -> 3,440 (2026-09-18), when the participants were seated on the roles:
|
|
``MemoryModule.intake``, ``PlanningModule.advise`` and ``ActionModule.review``
|
|
/ ``salvage`` -- the four verbs a participant answers that belong to a role rather
|
|
than to the seat, each taking this turn's participants so a replaced role decides
|
|
what a plugin's judgement does. 28 lines of protocol and prose; the
|
|
composition rules themselves live in the harness, not here.
|
|
|
|
Measured at 3,406, thirty-four over the count, for the reason given above.
|
|
|
|
And once more, 3,440 -> 3,470, for the closeout of the participant contract
|
|
(2026-09-18). Four changes, all of them narrowing what the paper claims rather
|
|
than widening it: ``observe`` is gone, because a verb with no return value
|
|
decides nothing and can only keep the state a participant is forbidden to
|
|
keep; ``outbound`` says on its own docstring that it is the one verb with no
|
|
module seat and therefore the one a generated participant cannot be handed;
|
|
``StepView`` gains ``phase``, so a verb asked at two moments reads which one it
|
|
is instead of inferring it from whichever other field happens to be set, and
|
|
``tools_ran`` becomes a property derived from it so the two cannot disagree;
|
|
and the four delegating role methods are named apart from the verbs they ask
|
|
(``read_inbound`` asks ``intake``, ``guide`` asks ``advise``, ``judge_step``
|
|
asks ``review``, ``rescue`` asks ``salvage``), so a reader of either name knows
|
|
which layer they are on.
|
|
|
|
Measured at 3,444. The headroom is the twenty-odd this docstring has argued
|
|
for since the first bump, not room set aside to spend.
|
|
|
|
|
|
And once more, 3,470 -> 3,500 (2026-09-18), for the three verbs the
|
|
seam applied without a seat. ``system_addendum``, ``archive`` and
|
|
``select_tools`` were rendered straight onto the hook decision, so each was the
|
|
one judgement in the set with nowhere to compose two participants, nowhere to
|
|
vet what came back, and nothing a replacement role could decide. They join the
|
|
roles the other four sit on: ``MemoryModule.ask_system_addendum`` and
|
|
``ask_archive``, and ``CapabilityModule.ask_select_tools``. The tool seat is
|
|
deliberately not the point where narrowing takes effect -- ``select`` still is, and the
|
|
registry still adjudicates every call -- so a participant narrows after the
|
|
product has spoken and never instead of it. 47 lines of protocol and prose.
|
|
|
|
Measured at 3,477.
|
|
|
|
|
|
And once more, 3,500 -> 3,540 (2026-09-18), for the verb that lets a
|
|
dispatch's own judgements be a participant rather than something a role reads
|
|
for itself. ``AgentParticipant.judge`` is the one synchronous verb -- it runs before
|
|
every tool dispatch and ahead of the permission gate -- and it was already pure
|
|
data, a list of sentences. Adding it is what makes the participant list the only
|
|
route an external judgement takes: a Charter's ``checks`` and ``code`` answer it
|
|
through a thin shell, and a judgement generated for one dispatch can join the
|
|
same list without a second way in. ``ActionModule.judge`` takes the list; the
|
|
merge is a veto, so the first participant that refuses decides and the rest are
|
|
not asked. 30 lines of protocol and prose.
|
|
|
|
Measured at 3,515.
|
|
|
|
|
|
And once more, 3,540 -> 3,550 (2026-09-18), for prose only -- no executable
|
|
line moves with it. Two claims on the paper were wider than the tree: the
|
|
``max_iterations`` docstring had been orphaned by the property inserted above
|
|
it, and ``judge`` read as though a plugin's override were asked, when the party
|
|
that asks it is the tool registry and a registry holds no handle on this turn's
|
|
participants. Both now say what is wired. A ceiling bump for a docstring is the
|
|
cost of keeping the paper honest about what it does not do, which is the half a
|
|
reader cannot check by reading the code.
|
|
|
|
Measured at 3,528.
|
|
|
|
|
|
And once more, 3,550 -> 3,570 (2026-09-18), for review. Prose again, and again
|
|
about what the papers do not do. The ``judge`` disclosure had landed in two of
|
|
its four homes; ``ActionModule.ask_judge`` on this paper was a third, and it is
|
|
the one a reader of the role protocol meets first, phrased without naming
|
|
anything the earlier fix touched -- which is why grepping the claim rather than
|
|
the symbol is what found it. The other addition is the type-only edge from this
|
|
paper to ``raven.agent.harness.participants``: the first the kernel has, taken
|
|
knowingly when ``Verdict`` and ``Intake`` moved off the paper so a generated
|
|
judgement could build what a participant answers with. It costs nothing at
|
|
import time and lint-imports does not see it, so it is written down here and
|
|
beside the contract it bends rather than left for the next reader to find.
|
|
|
|
Measured at 3,542.
|
|
|
|
|
|
And once more, 3,570 -> 3,620 (2026-09-22), for ``FileRemoval`` on the tool
|
|
paper: the file a call made vanish, beside ``FileChange``, the file it wrote.
|
|
No tool deletes as its purpose, so the shell tool reports what was on disk
|
|
either side of its command and the loops re-stat what the turn wrote; the
|
|
paper only names the shape that travels back -- a path and, when it could be
|
|
read before it went, the text -- and gives ``ToolResult`` and ``ToolOutput``
|
|
one ``removed`` tuple each, empty for every call that removed nothing. 24
|
|
lines of dataclass, two fields and their prose.
|
|
|
|
Measured at 3,593.
|
|
|
|
|
|
And once more, 3,620 -> 3,660 (2026-09-29), for ``FileWrite`` on the tool
|
|
paper: the files a command created or rewrote, the other half of the record
|
|
``FileRemoval`` started. The shell tool lists its directory either side of the
|
|
command and, where the checkpoint's shadow repo covers it, reads what each file
|
|
held from a tree staged just before; the paper only names what travels back --
|
|
a path, whether it is new, its size, and the line counts and diff when the
|
|
change could be measured -- and gives ``ToolResult`` and ``ToolOutput`` one
|
|
``written`` tuple each, empty for every other call. 34 lines, a dataclass and
|
|
its prose. The same change gives ``FileRemoval`` a ``withheld`` flag, set when
|
|
the shell tool kept a removed file's text back on purpose, so nothing else may
|
|
fill it in: five more lines.
|
|
|
|
Measured at 3,632.
|
|
|
|
|
|
And once more, 3,660 -> 3,700 (2026-09-30), for the credential card on the
|
|
asking paper: ``CredentialAsker``, the turn-scoped capability that asks the
|
|
user to type a secret into a masked field the model never reads, beside
|
|
``ApprovalResponder`` which asks them to allow a call, and the two carriers
|
|
it trades -- ``CredentialRequest`` (where the value goes, what the card calls
|
|
it) and ``CredentialOutcome`` (saved or skipped, never the value). 50 lines,
|
|
all of them this addition: without it the package stands at 3,632.
|
|
|
|
Measured at 3,682.
|
|
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import ast
|
|
import re
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
LINE_CEILING = 2_000
|
|
CONTRACTS_LINE_CEILING = 3_700
|
|
THIRD_PARTY_ALLOWED = frozenset({"loguru"})
|
|
DEBT_MARKER = re.compile(r"\b(TODO|FIXME|HACK)\b")
|
|
|
|
REPO = Path(__file__).resolve().parent.parent
|
|
KERNEL_PACKAGE = "raven.spine"
|
|
SPINE = REPO / "raven" / "spine"
|
|
CONTRACTS = REPO / "raven" / "contracts"
|
|
|
|
|
|
def _spine_files() -> list[Path]:
|
|
files = sorted(p for p in SPINE.rglob("*.py") if "__pycache__" not in p.parts)
|
|
assert files, "raven/spine has no Python files; a budget measured on nothing is met by nothing"
|
|
return files
|
|
|
|
|
|
def _imports() -> list[tuple[str, str]]:
|
|
"""Every import in the package as (module, where), in-function ones
|
|
included; a relative import counts as the package itself."""
|
|
found = []
|
|
for p in _spine_files():
|
|
for node in ast.walk(ast.parse(p.read_text(encoding="utf-8"))):
|
|
if isinstance(node, ast.Import):
|
|
mods = [a.name for a in node.names]
|
|
elif isinstance(node, ast.ImportFrom):
|
|
mods = [node.module or ""] if node.level == 0 else [KERNEL_PACKAGE]
|
|
else:
|
|
continue
|
|
found += [(m, f"{p.relative_to(REPO)}:{node.lineno} -> {m}") for m in mods]
|
|
assert found, "raven/spine imports nothing; the walk found no statements to judge"
|
|
return found
|
|
|
|
|
|
def test_the_kernel_stays_under_its_line_ceiling() -> None:
|
|
lines = sum(len(p.read_text(encoding="utf-8").splitlines()) for p in _spine_files())
|
|
|
|
assert 0 < lines <= LINE_CEILING, (
|
|
f"raven/spine is {lines} lines against a ceiling of {LINE_CEILING}; "
|
|
"growing the kernel is a reviewed change to this ceiling, not a bump in passing"
|
|
)
|
|
|
|
|
|
def test_the_kernel_imports_no_other_raven_package() -> None:
|
|
strays = [
|
|
where
|
|
for mod, where in _imports()
|
|
if mod.split(".")[0] == "raven" and mod != KERNEL_PACKAGE and not mod.startswith(KERNEL_PACKAGE + ".")
|
|
]
|
|
|
|
assert strays == [], f"the kernel reaches outside itself: {strays}"
|
|
|
|
|
|
def test_the_kernel_names_no_third_party_beyond_the_allowed() -> None:
|
|
beyond = sorted(
|
|
where
|
|
for mod, where in _imports()
|
|
if (root := mod.split(".")[0]) not in sys.stdlib_module_names
|
|
and root != "raven"
|
|
and root not in THIRD_PARTY_ALLOWED
|
|
)
|
|
|
|
assert beyond == [], f"the kernel took on a dependency outside {sorted(THIRD_PARTY_ALLOWED)}: {beyond}"
|
|
|
|
|
|
def test_the_kernel_carries_no_debt_markers() -> None:
|
|
marked = [
|
|
f"{p.relative_to(REPO)}:{n}"
|
|
for p in _spine_files()
|
|
for n, line in enumerate(p.read_text(encoding="utf-8").splitlines(), 1)
|
|
if DEBT_MARKER.search(line)
|
|
]
|
|
|
|
assert marked == [], f"the frozen kernel carries deferred work: {marked}"
|
|
|
|
|
|
def test_the_papers_stay_under_their_line_ceiling() -> None:
|
|
files = sorted(p for p in CONTRACTS.rglob("*.py") if "__pycache__" not in p.parts)
|
|
assert files, "raven/contracts has no Python files; a budget measured on nothing is met by nothing"
|
|
lines = sum(len(p.read_text(encoding="utf-8").splitlines()) for p in files)
|
|
|
|
assert 0 < lines <= CONTRACTS_LINE_CEILING, (
|
|
f"raven/contracts is {lines} lines against a ceiling of {CONTRACTS_LINE_CEILING}; "
|
|
"a new paper is a reviewed change to this ceiling, not a bump in passing"
|
|
)
|