Written by: agent · Confirmed by: — Version: v1 Last reviewed: 2026-10-15 (agent review; user confirmation at application) Module document for the
kernel/component.ARCHITECTURE.md§ 2 names it; the user confirmed that entry on 2026-09-24 (merged in 34d7be63). Cap: ≤ 600 lines. This is the kernel's specification, originally written before kernel implementation (DESIGN-023 § 6 row A). The design it specifies isperry/design/DESIGN-023-a-kernel-and-a-skill.md. Overflow → split per-§ toarchitecture/sections/§<N>-<topic>.md, the root document's convention underkernel/. § 5 is split out.
The kernel holds a project's structured state and applies the structural rules that a process template declares. It is stdlib-only Python behind one CLI, and every command takes JSON and returns JSON. The skill (markdown) calls the kernel. The kernel never calls the skill.
The kernel knows eight concepts (§ 2) and no method. Every item type, state, field,
transition and guard comes from the template, which is data that the skill ships. The names
in this document's examples (widget, gauge, queued, bench, inspector) are
invented and mean nothing to the kernel. DESIGN-023 Goal 1 applies to this document as it
does to the code.
It deliberately does not read, parse, lint or render markdown (Goal 2). It does not run
a command or spawn a process (decision 8), judge what a document means (decision 3), or
recommend a next step (decision 5). It does not serve several users, run a server, sync
machines or draw a UI (§ 3 Non-Goals). Status: implemented and integrated through DESIGN-023 F/G/H. Work, goals,
decide and root snapshots use native items/events; legacy writers are retired. The first template is shipped under templates/process/.
| Concept | Fields |
|---|---|
| Template | format (the kernel's template-format version, 1), name, version (a positive integer that only rises), types{}, relations{}. One version is applied at a time, and applying one is an event (§ 5.2) |
| Item | id (minted from its type's prefix), type, state, fields{} (every declared field, null when unset), seq (the seq of the last event that touched it), created_at, updated_at |
| Field | declared per type: kind is one of text int number date enum actor ref list metric, plus that kind's options (§ 5.3). Its value lives on the item |
| Transition | declared per type: name, from (one or more states), to (one state), guards[] |
| Guard | kind (required · actor · relations_closed · limit), the kind's keys, and an optional when (§ 5.4). Guards run on create and on transitions |
| Relation | kind, from, to. The built-in kinds are blocks (from blocks to) and parent (to is the parent of from). The template can declare others |
| Event | seq, at, actor, command, items[], transition, changes[] (each with a key and its before and after values), note, warnings[]. Events are append-only and are the store's history (ADR-022) |
| Attachment | item, ref (a path or URL, kept verbatim), hash (optional, sha256:<hex>). The kernel never opens the target |
startable, blocked_by, a metric's met and fraction, and an item's rollup are
derived when read and never stored (§ 5.5, § 5.6).
kernel/ holds the generic package, tests and this target. bin/perry is the
sole thin native wrapper. H changes its path from bin/perry-kernel; it does
not change kernel production code, concepts, guards or the native contract.
8 concepts (the eight above) and at most 12 command groups. Ten groups are in use:
init, template, item, rel, attach, query, events, export, import and
describe. There are also exactly 4 guard kinds and 9 field kinds. A fifth guard kind
or a tenth field kind is a concept change (DESIGN-023 § 3, § 7).
How a test checks it. describe reports concepts, budget
({"concepts": 8, "command_groups": 12}), every command, and the template format's
field_kinds and guard_kinds. The kernel suite asserts that concepts is exactly the
list above, that commands[].name has at most 12 distinct first words, that there are 4
guard kinds and 9 field kinds, and that budget equals the test's own literals, 8 and 12.
The test does not read this file, because the kernel suite must pass with every *.md
removed (Goal 2). Raising a number means editing both the test literal and this section,
and DESIGN-023 § 7 makes that a revision of the design, not a new row.
flowchart TD
Skill["skill — SKILL.md, lanes, templates/process/*.json<br/>markdown and data"] -->|"argv + JSON in"| CLI["kernel executable<br/>thin wrapper"]
CLI -->|imports| Pkg["perry_kernel<br/>stdlib only"]
Pkg -->|"sqlite3, WAL"| Store[("store<br/><git-common-dir>/perry/<slug>.db")]
Pkg -->|"export writes and compares · import loads"| Export[("<state root>/export/<br/>items.jsonl · events.jsonl")]
Pkg -.->|"reads .git and commondir<br/>for the path rule"| Git[(".git metadata")]
CLI -->|"JSON out"| Skill
Skill-side helpers and tests call the native CLI through subprocesses. They
never import kernel internals to read a live store. All test/rehearsal calls
name temporary --store and explicit --root with PERRY_KERNEL_TESTING=1.
The one-shot legacy work importer retires at H; historical receipts remain.
External viewers, CLIs and automation clients call the same native CLI and adapt its responses in their own code. No particular consumer is required to install or use the kernel; the kernel imports no consumer code. Historical consumer validation in DESIGN-023 decision 11 does not add a runtime dependency.
Allowed directions: skill → kernel → store, where each caller named above stands in the skill's place. There are no others.
Forbidden:
- Importing anything outside the stdlib and
perry_kernel,bin/,viewer/andrelease/included. Reading markdown, in any mode (the suite runs with no*.md). - Running a command. The kernel makes no
subprocess,os.system,os.exec*oros.spawn*call. It finds the git common dir by reading.gitandcommondir(§ 5.7). The skill runs a measurement's command and writes the value (decision 8). - Naming a skill path or a template-declared name. Goal 1's test greps the kernel
source for every type, state and field name in the shipped template as a string literal
(
"name"or'name'), case-sensitively. A collision is fixed by renaming on the kernel's side. - Any other path. The kernel reads only its store, its
--inputfile, the.gitmetadata and the export. It writes only the store and<state root>/export/. Onlyimportloads the export;exportreads its own files only to tellunchangedapart.
flowchart TD
Argv["argv"] -->|"-h or --help anywhere"| Help["usage generated from the declaration · exit 0"]
Argv --> Parse["parse against the command's declaration"]
Parse -->|"undeclared flag or positional, or a flag this command does not honour"| Usage["usage · exit 2"]
Parse --> Input["read --input: exactly one JSON object"]
Input -->|"an undeclared key at any declared level"| Key["unknown_key · exit 2"]
Input --> Resolve["resolve the root, then the store (§ 5.7)"]
Resolve --> Txn["open the store and check its format<br/>BEGIN IMMEDIATE for a write, a snapshot for a read"]
Txn --> Validate["load the applied template · validate kinds, refs, relations<br/>check expect{} (compare-and-set)"]
Validate --> Guards["run every guard that applies (§ 5.4)"]
Guards -->|"a refuse-mode guard fails"| Refuse["guard_refused · roll back · exit 1"]
Guards --> Mint["mint ids in the transaction · write rows · append one event"]
Mint -->|"--dry-run"| Roll["roll back · effect: dry_run"]
Mint -->|"nothing differs"| Same["no event · effect: unchanged"]
Mint --> Commit["COMMIT · effect: written · events: [seq]"]
One command is one transaction. A refusal after BEGIN rolls back the whole transaction,
including the relations and attachments written by the same item create, so an edge made
at create cannot half-land (DESIGN-015 § 5.3). An unexpected exception is caught at the
top, rolled back and reported as internal. No traceback reaches the caller (NN-K6).
Split out whole on 2026-09-26 (TASK-488), under the overflow convention in the header, to
architecture/sections/§5-contracts.md. It holds
5.1 the envelope, exit codes and error codes · 5.2 the process template, format 1 ·
5.3 field kinds · 5.4 guards · 5.5 metrics and the roll-up · 5.6 commands · 5.7 the store ·
5.8 export and import · 5.9 the argument for each new claimed path. Every § 5.x in this
document, and every kernel/ARCHITECTURE.md § 5.x elsewhere, means that file's subsection.
Every rule below is proposed (NN-6), and none of them binds until the user confirms it. NN-K3 to NN-K8 restate DESIGN-016's argument-contract lessons as rules of this CLI.
- Severity: hard · Status: proposed
- Rule: kernel source names no skill path, and no type, state or field that the shipped template declares (Goal 1).
- Check: the grep test in § 3, and the kernel suite run with every
*.mdremoved.
- Severity: hard · Status: proposed
- Rule: no process is spawned, whether for a metric or for the git path rule. No markdown file is opened.
- Check: a source scan for the process calls listed in § 3, and the markdown-free run.
- Severity: hard · Status: proposed
- Rule:
-hor--help, in any argument position, prints the generated usage and exits 0, before the root or store is resolved,--inputis read, or any lock is taken. - Rationale: DESIGN-016 goal 2. A
bin/render once ran when it was asked for help.
- Severity: hard · Status: proposed
- Rule: every command, read-only ones included, refuses with exit 2 an undeclared flag
or positional, a flag it does not honour (
--dry-runon a read,--inputondescribe), and an undeclared input key at any level. An undeclared template key istemplate_invalid, and an undeclared export key isexport_invalid. Nothing is accepted and then ignored. - Rationale: DESIGN-016 § 1.4 and goal 12.
--wrteprinted a render, wrote nothing, and exited 0.
- Severity: hard · Status: proposed
- Rule:
--rootbeatsPERRY_PROJECT, which beats the walk up.--storebeatsPERRY_STORE, which beats the derived path (§ 5.7). - Rationale: DESIGN-016 goal 1. A write landed in a project the caller never named.
- Severity: hard · Status: proposed
- Rule: every outcome, an internal fault included, reaches the caller as one JSON envelope on stdout and an exit code. A refusal adds one stderr line. An advisory that a program must act on is an envelope field, never only a stderr line.
- Rationale: DESIGN-016 § 1.5 and goal 10. A refusal once escaped as a traceback.
- Severity: hard · Status: proposed
- Rule:
queryandeventsreturn at most 50 rows unlesslimitsays otherwise, and always reporttotalandtruncated(DESIGN-016 goal 6).
- Severity: hard · Status: proposed
- Rule:
effectsayswritten,unchangedordry_run. A write that changes nothing appends no event and says so, and every write returns its seqs andstore_seq. - Rationale: DESIGN-016 § 1.5. A render exited 0 having restored none of 151 rows.
- Severity: hard · Status: proposed
- Rule: kernel tests name a temporary store, and § 5.7's live-store check fails the
suite otherwise. This is root NN-5's reason, moved inside
.git/.
- Severity: hard · Status: proposed
- Rule: an id is minted inside the write transaction, and no command lowers a ceiling or reuses an id. Two checkouts once minted the same id (DESIGN-023 § 1), and Goal 5's concurrent-worktree test holds this rule.
-
OQ-K1 — Which metric values fold together? Resolved: the user chose (a) on 2026-09-24, and § 5.5 now defines
rollup. DESIGN-022 fixes the fold (§ 5.5). It does not say which values fold together once the measured things are items of their own (DESIGN-023 § 5.4). The options:- (a) The
parentchildren. An item'srollupfolds every metric field of the items whoseparentit is. It needs no template key and fits § 5.4's separate types; an item with no metric-bearing children getsnull. - (b) A marked relation. One declared relation kind per template carries
"fold": true. The rule stays fixed; the relation it follows is data. - (c) Several metrics on one item, as a
listofmetric. This contradicts § 5.4, and list elements have no ids to update one at a time. - (d) No fold in the kernel. The skill folds
queryoutput, against decision 8 ("fixes how several … roll up") and root § 3 (a lane does not compute a number).
Two further questions follow from the answer and stay open: a second-level count, like DESIGN-022 § 5.2's per-grouping counts that exclude items by a field, and whether
count_bymay count byrollup.met. - (a) The
-
OQ-K2 — The age of a measurement. DESIGN-022's
duestate needs the time at whichcurrentlast changed. Either (a) the skill reads it fromevents(keys: ["field:<name>"]) and applies its own threshold, which works today, or (b) the metric output gains a derivedcurrent_at, a key decision 8 does not name. -
OQ-K3 — Where the count of unexported events lives. DESIGN-023 § 5.3 has
describereport it, and § 5.1 makesdescribebyte-identical across projects; both cannot hold. This document keeps § 5.1 and puts the count onevents(unexported), a departure from § 5.3 that needs a DESIGN-023## Changesentry. -
OQ-K4 — Detection versus another session's write. Resolved: the user answered on 2026-09-24 — an event of the run's own session fails the suite, another session's is reported — and
kernel/tests/livestore.pyimplements it. The store is shared. If another worktree wrote during a test run, detection saw a leak and the run went red. Prevention is exact. The question was whether detection should report the new events or fail the suite. -
OQ-K5 — Readings where DESIGN-023 is silent. Each can be reversed.
limit.peris a list, so decision 9's "a named field" can mean more than one. A metric is set oncecurrentis non-null. A flag is anenumof[false, true]. The slug isroot/<path>, percent-encoded. The state root is recorded atinit, so the kernel never reads.perry/config.jsonl(DESIGN-023 § 8).startablemeans theinitialstate with an emptyblocked_by. Anagentactor must carrysession.--jsonis accepted everywhere and changes nothing, because output is always JSON; refusing it would be NN-K4's stricter reading. An empty variable is read per variable (§ 5.7; the user, 2026-09-25): an emptyPERRY_STOREis refused withusage, an emptyPERRY_PROJECTcounts as unset, and an emptyPERRY_KERNEL_TESTINGcounts as set, which the user accepted on 2026-09-26 because a safety switch that is present should fail safe. -
OQ-K6 — The executable's name. Closed: the user named it
bin/perry-kernelon 2026-09-24 (§ 2).
- 2026-10-09 · v1 · TASK-489 round 6. § 5.8 step 2:
importrefuses an event that mixes atemplatechange with item changes (commands._event_shape); no command writes one. The claim that order inside an event never decides a check now rests on that rule and the round-5 type rule together. No command, error code or key is added;surfacestays 1.0. - 2026-10-09 · v1 · TASK-489 round 5. In
architecture/sections/§5-contracts.md, § 5.8 step 2 says what the replay check covers and what it does not, and that a change before its item'stypechange in one event is checked against the type that event sets (commands.replay_check). No command, error code or key is added;surfacestays 1.0. - 2026-10-07 · v1 · TASK-489 round 4. § 3's allowed-directions line says each caller named above it stands in the skill's place, so "There are no others" agrees with the callers it lists. The direction itself, caller → kernel → store and nothing back, is unchanged.
- 2026-10-07 · v1 · TASK-489 round 3. § 3's diagram and text name
bin/perry-kernel-migrate, row D's one-shot importer, as a caller of the CLI besides the skill until row H, and say that the test suites andbin/perry's forward also run it; the allowed-directions line is unchanged. Inarchitecture/sections/§5-contracts.md: § 5.8 step 2 says the replay holds anattach:ref to the check a liveattach addorattach removeruns (commands.check_attachment), and § 5.7's prevention layer says the importer setsPERRY_KERNEL_TESTINGtoo, as a safety switch. No command, error code or key is added, andsurfacestays 1.0. - 2026-09-29 · v1 · TASK-489, the import items carried from TASK-487. In
architecture/sections/§5-contracts.md: § 5.8 step 2 saysimportholds each replayed change to the template in force when its event was written (a template change must rise and strand nothing, and a type is set once), and refuses a relation change that flips nothing for every kind (F1); § 5.1 says a damagedexport_tokenisstore_corrupt(F6) and thatexport_invalidcovers a replayed change; § 5.7 says an open sets its busy deadline before it probes (F4). No command, error code or key is added, andsurfacestays 1.0. - 2026-09-29 · v1 · TASK-488 round 2, DESIGN-023 decision 13. § 3 says Goal 1's grep
matches a template name as a string literal, not as a whole word.
describe's per-command description key is renamedpurpose(surfacestays 1.0, unreleased); § 5.6 names it. - 2026-09-26 · v1 · TASK-488, the user's decisions of 2026-09-25 and 2026-09-26. § 5 moves
whole to
architecture/sections/§5-contracts.mdunder the overflow convention the header now names; § 5 here is a pointer. Then, in that file: § 5.1 describesid_exhausted(part of the unreleasedsurface1.0), theusageandinput_invalidclasses TASK-487 round 3 added, thestore_corruptcases, and the empty-variable readings; § 5.6 listsid_exhaustedamongitem create's errors; § 5.7 states the empty-variable rules and addsexport_tokentometa; § 5.9 states the token exception. § 7 OQ-K5 records the empty-variable readings. The TASK-487 line below said round 4 made § 5.9 state the token rule; it did not, and the line now says what round 4 did there. - 2026-09-24/25 · v1 · TASK-487: § 2 lists
rollupamong the derived fields, line 6 records the confirmed § 2 entry, and the executable isbin/perry-kernel(OQ-K6 closed). Round 2: § 1 says the kernel is built, and § 7 marks OQ-K4 resolved. Round 3: § 3, § 5.8 and § 5.9 sayexportalso reads the export, to decideunchanged; § 5.7 says detection fails only on the run's own session. Round 4: § 3's diagram says export compares and import loads; § 5.1 and § 5.8 say export removes only a temporary file named with the store's recorded token, and § 5.9 says export reads its own two files only to decideunchanged; § 7 OQ-K4 reads as answered. - 2026-09-24 · v1 · The user answered OQ-K1 with option (a): § 5.5 defines
rollupover theparentchildren, and § 7 marks the question resolved. - 2026-09-24 · v1 · Written for DESIGN-023 § 6 row A, before any kernel code exists. It
covers the concepts, template format 1, every command with its input, output and error
codes, the metric formula and fold, the store, export and import, the claims' arguments,
and the CLI rules, proposed as NN-K1 to NN-K10. It includes eight CLI rules that the
coordinator added with the user's approval the same day: write seqs and
store_seq,expectwithstale_write,sessionon the actor, required inputs in the versioneddescribe, stdout as the whole answer, the thin wrapper, and refusal of both undeclared positionals and flags a command does not honour.
The user approved the bounded revision on 2026-10-20 under DESIGN-023 §7;
perry/evidence/2026-10/TASK-492-prefix-floor/approval.json preserves the actual
reply. Existing template apply can raise declared floors through optional
ceilings, using existing ceiling events. No concept, command group or guard
was added. See §5 contracts. Source availability never authorizes another live
migration; its actual writes still require project-specific authority.