Repository navigation
position and watch: the atomic units - #21
Merged
Merged
Conversation
Backlog task 013. Position holds the operator's decisions; a Watch is one
pre-registered claim serving one of them. Neither file is in this repo --
they name real decisions, deadlines and exposures, and this repo is public.
The loaders take configurable paths (POSITION_PATH / WATCHES_PATH) defaulting
to ~/.config/insightweaver/, .gitignore refuses a real position.yaml, and what
ships here is the schema plus config/{position,watches}.example.yaml.
Three shape decisions, recorded rather than discovered:
Watch is a new table, not an evolution of Decision + Factor. Task 012 dropped
decision_factors and decisions at 0 rows, so there was nothing left to evolve.
Decision lives in Position, not the database: it is an operator commitment in
a hand-edited file under git, not a row the system writes. One model of the
idea, not two.
so_what is a key plus prose. `decision` is a key into the Position's decisions
and `because` says what changes. The key makes invariant 2 machine-checkable;
an invariant enforced only by prose is what left 25 unfalsifiable predictions
in the deleted ledger.
triggers is structured and must stay so: a list of clauses over terms,
entities and source allowlists -- a disjunction of conjunctions Tier 1 can
compile to word-boundary regexes with no model involved. predictions.
trigger_condition was free text; 33 rows were written against it and graded
zero times, because nothing downstream can evaluate a sentence. A clause that
is a sentence is rejected by name.
Rejection is a claim about the table, so it is tested against the table: every
invalid watch asserts the row count is unchanged, and the assertion runs
whether or not the loader raised. Empty, whitespace-only and absent so_what,
an unknown decision, belief outside [0,1], a past expiry and staleness under
one day all refuse and store nothing; a file with one bad watch stores none of
its watches. Four CHECK constraints enforce the same invariants against raw
SQL, so a row inserted by hand fails the way a bad file does.
There is no `watch add` and there will not be one. It satisfies no acceptance
criterion and is the seam through which auto-generated watches arrive
(invariant 6). `watch sync` mirrors the files and takes no arguments; a test
asserts on the registered subcommands and their parameter lists.
staleness_alert_days accepts a cadence string via src/utils/cadence.py rather
than a second interval parser.
A Position over two pages warns loudly and still loads -- a three-page
Position of real deadlines beats a one-page Position of vague interests, so
length can only ever be a flag. Missing stakes and passed deadlines warn the
same way. Everything structurally checkable rejects.
554 tests pass, 103 of them new. Every enforcement above was verified by
mutation: removing it makes a named test fail.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M9gY2miAUXijbFm25YnFcq
watches.py had grown to 583 lines, past the 200-300 the repository asks for. The split is along a real seam rather than a line count: _validate.py takes a raw YAML value and either appends a sentence to `problems` or returns a clean one, and touches neither the file system nor the database; watches.py owns the loaded object, the file, and the sync. validate_watch returns constructor keywords rather than a Watch. That keeps the dependency one-way -- watches -> _validate -> position -- where returning the type would have required _validate to import the module that imports it. It also puts construction in the loader, which is the thing that admits a watch; validation only decides whether it is admissible. Pure move. 554 tests still pass, and the mutation checks still bite: removing any one enforcement (so_what defaulting, an unknown decision tolerated, the belief range, the past-expiry check, the staleness floor, prose triggers, or the all-or-nothing raise) still fails a named test. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M9gY2miAUXijbFm25YnFcq
The reviewer's one actionable finding: the caveat that sync_watches deletes rows for removed watches, and that task 017 will hang belief history off those rows, was disclosed only in the IC's report. That is the same failure as the cadence gap in task 011 -- a limitation that lives in a conversation is one nobody reads. It is now in sync_watches' own docstring and in backlog/017's landmines, which is where the implementer who would destroy calibration history will actually be looking.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements
backlog/013. The first task that builds after the deletion. 554 tests (451 → 554),make checkexit 0.Both invariants hold at two independent layers
Invariant 2 — every Watch carries a
so_whatnaming a decision. Verified independently at the loader and at the schema:Invariant 6 — the system never authors its own watches.
watchofferslistandsync, nothing else.syncreads the checked-in file. There is no create path, and a test fails if one is added.triggersis compilable, not proseThis was the task's central design risk: the previous attempt at this idea accumulated prose where it needed structure, and 33 predictions were graded zero times as a result.
A list of clauses over exactly
terms,entities,sources— AND within a clause, OR across. Disjunctive normal form, stored as JSON.It compiles because every axis is already a mechanic that survived task 012: terms and entities are word-boundary regexes from
src/matching/entity_matcher.py(with its shouted-acronym case rules), sources is set membership over the producing adapter. Task 015 asks for "a deterministic predicate over entities, terms and source allowlists" — those are the three fields.Prose is refused by name, citing the precedent:
Nothing invalid is ever stored
29 parametrised rejections — empty / whitespace-only / absent / bare-prose
so_what, unknown decision, belief out of range or prose, past or absent expiry, staleness 0 or negative, seven bad trigger shapes.The structural detail that makes this real: the row-count assertion runs whether or not the loader raised. A loader that silently accepts fails on the count, not on a missing exception — testing for the absence of a row rather than the presence of an error.
The author ran mutation testing across ten guards, removing each in turn and counting failures. The reviewer corroborated seven of ten against the test code statically.
Decisions recorded, not assumed
Watch is a new table; Decision lives in Position under git, not the database. The old
decisions/decision_factorstables were dropped at 0 rows by task 012, so there was nothing to evolve — and why they stayed empty (prose all the way down) is exactly whybeliefis a float andtriggersis structured.so_whatis a key plus prose —{decision: <key into Position>, because: <sentence>}, both required. The key makes invariant 2 machine-checkable and "which watches serve this decision" a query; the prose makes the answer readable.Position stays out of this repo.
.gitignorerefusesposition.yamlandwatches.yamlat both the root andconfig/; only the*.example.yamlfiles are tracked.One reviewer finding, fixed
The caveat that
sync_watchesdeletes rows for removed watches — and that task 017 will hang belief history off those rows, at which point a delete destroys calibration data — was disclosed only in the IC's report. Same failure as the cadence gap in task 011: a limitation that lives in a conversation is one nobody reads. It is now insync_watches' docstring and inbacklog/017's landmines, where the implementer who would destroy that history will actually be looking.Known limits
_validate.py(385) andposition.py(318) exceed the 200–300 guide. Split once along a real seam; further splitting would fragment the design rationale in the docstrings.