Skip to content

A write accepts importance outside 1-10 on every type except event (-f importance=99, MCP kb_create) #1537

Closed

Description

@markramm

importance is 1-10 on every entry. A write refuses a value outside that range only when the entry is an event. Every other type stores it, and pyrite qa validate then reports the value Pyrite just wrote.

Found by the 2026-11-16 code audit (kb/designs/code-audit-2026-11-16.md, finding H3). Both hallway tests on 2026-11-16 hit it (see #1393).

Steps

dev at bccf8f7 (0.26.3), with HOME, PYRITE_CONFIG_DIR and PYRITE_DATA_DIR pointed at empty directories.

$ pyrite init -t research -p kbs/res -n res --no-examples
$ pyrite create -k res -t person --title "Jane Roe" -b x -f importance=99 --format json
{
  "created": true,
  "entry_id": "jane-roe",
  "entry_type": "person",
  "outcome": "done"
}
$ grep -n '^importance' kbs/res/people/jane-roe.md
5:importance: 99
$ pyrite update jane-roe -k res -f importance=77 --format json
{
  "updated": true,
  "entry_id": "jane-roe",
  "locked": false,
  "outcome": "done"
}
$ pyrite qa validate res --format json | grep -B1 -A3 '"rule": "importance_range"'
      "kb_name": "res",
      "rule": "importance_range",
      "severity": "warning",
      "field": "importance",
      "message": "Entry 'jane-roe' has importance 77 (must be 1-10)"

The same value on an event, same KB:

$ pyrite create -k res -t event --title "Hearing" -b x -f date=2026-01-02 -f importance=99 --format json
{"outcome": "error", "errors": [{"field": "importance", "rule": "range", "message": "Importance must be 1-10, got: 99", "expected": "1-10"}], "error": "Importance must be 1-10, got: 99", "error_code": "VALIDATION_FAILED", "retryable": false, "suggestion": "use 1-10 for importance"}
$ echo $?
1

Expected

The person create and update are refused exactly as the event is: exit 1, VALIDATION_FAILED, the errors row naming importance, nothing written. The same on MCP kb_create and kb_update.

Groom 2026-11-16

Automated groom (architect agent, working for the maintainer). Written so someone new to Pyrite can start from this issue alone. "Checked" means I ran the command or read the line on bccf8f7.

The user's model. "Importance is 1 to 10. If I send 99, Pyrite tells me, whatever kind of entry it is."
The implementation model. One range rule, on the base entry, reached by every write through the one write gate. Design principle 8 (kb/design.md): each rule lives in one place.
The difference today. The rule sits on one subclass. The gate that calls it already runs for every type.

Contracts that apply

  • kb/design.md principle 8: a rule is enforced at the single point everything passes through.
  • kb/design.md principle 2: a hand-edited file is never refused or repaired for what it already holds. An update that leaves a bad value alone must still succeed.
  • docs/json-contracts.md, "canonical error shape": the refusal is VALIDATION_FAILED with an errors row (field, rule, message, expected).
  • kb/maps/types-and-schema.md: its first invariant (write path and qa validate agree) covers enums only. No sibling for ranges is written anywhere; 0.26.4 theme T1: a type is one schema per KB #1528 slice T1-4 writes it. Not this issue's job.

What the code does today (checked)

  • pyrite/services/kb_service.py:759 KBService._validate_write is the write gate. Create (:1589) and every update path (:1724, :2321, :2350) call it, and it calls entry.validation_errors() for every type. So the enforcement point exists and every surface passes it.
  • pyrite/models/core_types.py:198 EventEntry.validation_errors is the only place the range is checked on a write (:221-232, calling validate_importance, pyrite/schema/validators.py:103).
  • pyrite/models/base.py:724 Entry.validation_errors checks id and title only. importance is a base field (:287), carried by all of the about 40 entry classes (13 in core).
  • Surprise: a third copy. extensions/journalism-investigation/src/pyrite_journalism_investigation/validators.py:142-150 has its own range check, which runs only in a KB registered with that plugin's type. tests/test_plugin_contract.py:403-446 uses it.
  • pyrite/services/qa_service.py:915 _check_importance_range and :1179 report the same rule after the fact, as a warning.
  • REST bounds the top-level field in pydantic (pyrite/server/schemas.py:467, :484, ge=1, le=10). MCP only describes it (pyrite/server/tool_schemas.py:784, :844, :874). The CLI has no bound on --importance (pyrite/cli/entry_commands.py:318, :565) or on -f importance=.
  • The on-disk case already works for events (checked). With importance: 99 hand-written into an event file, pyrite update vote -k res -f location=Hall succeeds and returns a warning: "rule": "model_validation", "message": "Importance must be 1-10, got: 99", "note": "violation already on disk; kept". That is _validate_write's prior_model_errors (:783-807). Moving the rule to the base class gives every type this behaviour with no new code.

Invariant and surfaces

A write never stores an importance outside 1-10, on any type, by any surface. A value already in the file is reported, not refused.

Surface Today Evidence
CLI create/update -f importance= fails for non-events steps above
CLI create/update --importance fails for non-events #1393; PR #1428 adds a usage error in front
MCP kb_create, kb_update fails for non-events audit H3 probe (99, then 77); not re-run here
REST create/update, top-level importance holds pydantic bound (read)
REST, importance inside metadata not checked assumed to fail; the test below settles it
pyrite add <file> an event file is refused today; other types are not read (:1589), not run
Plugins journalism KBs refuse through their own copy read
Hand edit + index sync not a write by Pyrite; qa validate reports it must stay so

Shapes (parametrise the test over these):

Shape Count How counted
Entry classes about 40 (13 core) grep -rnE "^class \w+\(" pyrite/models/*.py extensions/*/src/*/*.py | grep -c Entry
Types defined by kb.yaml alone (GenericEntry) 1 class, any name read
Values in range (1, 10); out (0, 11, -5, 99); "7"; "high"; absent the event rule's own cases
Operation create; update setting it; update of another field over a bad value on disk; add _validate_write callers
importance: in this repo's own files 369 lines, 368 in range, 1 template placeholder (<1-10>) git grep -hE "^importance:" -- '*.md' | sort | uniq -c

Options

  • A. Move the range row from EventEntry.validation_errors to Entry.validation_errors (recommended). About ten lines moved. Every type and surface is covered by the gate that already runs; the on-disk exception comes with it. kb_service.py is not edited.
  • B. Check in _validate_write. Same effect, but it edits kb_service.py, which is the busiest file in the tree this month (0.26.4 themes: order of work #1533, "Files that force a series"), and puts a model rule in the service.
  • C. Wait for 0.26.4 theme T1: a type is one schema per KB #1528 T1-4 (one value check behind type_spec). Right end state, about three weeks out, and importance is a base field whose range does not depend on the type.

Open questions

  • Should qa validate report importance_range as an error, now that a write refuses it? Today it is a warning. Leave it unless the maintainer says otherwise; note what you find.
  • The journalism plugin's copy becomes unreachable for a write (the model check raises first). Remove it here, or leave it for 0.26.4 theme T2: a plugin passes the same single points as core #1529? If you remove it, tests/test_plugin_contract.py::TestValidateWritePrefersMessage needs another rule-less validator to exercise.
  • pyrite add of a hand-written file with importance: 99: refused, as an event file is today. Say so in the changelog fragment. If you find that this breaks an import path, report it instead of working around it.

Pointers

pyrite/models/core_types.py (EventEntry.validation_errors), pyrite/models/base.py (Entry.validation_errors, unrepresented_frontmatter), pyrite/services/kb_service.py (_validate_write, read only), tests/test_enum_enforcement.py (a write-gate test over surfaces), tests/conftest.py (cli_world), tests/_world.py.

Checked versus assumed

  • Ran: every command above; the on-disk event case.
  • Read, not run: MCP and REST paths, pyrite add.
  • Assumed: no entry class overrides validation_errors without calling super() (grep finds one override, EventEntry, which does call it).
  • This groom is wrong if some type or importer relies on storing 0 or a value above 10. I found none in pyrite/, extensions/ or the shipped templates.
  • Predicted footprint: pyrite/models/base.py, pyrite/models/core_types.py, one new test file, one changelog.d/*.changed.md fragment. About 60 lines with tests. If it grows past four source files, stop and say why.
Acceptance:   create and update of a non-event with importance 0, 11, -5 or 99 are refused on the CLI
              (-f importance=) and on MCP kb_create/kb_update with VALIDATION_FAILED and an errors row
              naming importance; no file is written or changed. 1 and 10 are accepted. An update of
              another field on a file that already holds importance: 99 succeeds with the
              "violation already on disk; kept" warning. The event behaviour is unchanged.
              Fails today: the person create in "Steps" exits 0.
Regimes:      value already out of range on disk (kept, warned); importance absent (default 5, accepted);
              non-numeric value in a hand-written file ("high": kept, as for events today);
              a kb.yaml-only type; a plugin type.
Shapes:       the table above; one test parametrised over type x value x operation.
Touches:      existing: pyrite/models/base.py, pyrite/models/core_types.py
              new: tests/test_importance_range_on_every_type.py, changelog.d/<slug>.changed.md
Sequence:     independent. PR #1428 (#1393) edits pyrite/cli/entry_commands.py only and stays in front
              as a usage error (exit 2) for --importance; write this issue's tests with -f importance=
              and MCP so the two do not collide. #1502 is the list-field half of the same audit finding
              and is separate. #1528 T1-4 later moves this rule behind type_spec; if #1528 T1-0's
              value matrix has landed, remove its expected-failure marker for the importance row here.
Model:        sonnet
Size:         S
heavy:        no
Cold read:    no (no new shape; an existing refusal now applies to more types)
Out of scope: list-typed fields (#1502). The CLI --importance usage error (#1393, PR #1428).
              MCP schema minimum/maximum (the service refusal is the rule; a schema bound would
              answer with a second error shape, see #1508). QA severity. Read-side --min-importance
              filters (#1412, #1474).

🤖 Filed by the maintainer's conductor agent (pyrite-architect) (Claude Code)

Activity

  1. added this to the 0.26.4 milestone on Nov 16, 2026
  2. added
    bugSomething isn't working
    cliCommand-line interface
    mcpMCP server and tools
    on Nov 16, 2026
  3. markramm commented on Nov 17, 2026

    @markramm
    CollaboratorAuthor

    Claimed by the maintainer's loop, 2026-11-17T02:46Z: a cloud worker is building this on branch fix/1537-importance-range-every-type from the groom above (option A: the range rule moves to the base entry; kb_service.py is not edited). The groom's three open questions are taken at their defaults for this fix: QA severity stays a warning, the journalism plugin's own copy stays for #1529, and pyrite add of a file with an out-of-range importance is refused as an event file is today. The draft pull request will link here. If you were about to start on it, say so on this issue and the work can be shared or handed over.

    🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingcliCommand-line interfacemcpMCP server and tools

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions