fix(kb): refuse a chain change that would strand stored entries - #195
Open
ophiocus wants to merge 1 commit into
Open
fix(kb): refuse a chain change that would strand stored entries#195ophiocus wants to merge 1 commit into
ophiocus wants to merge 1 commit into
Conversation
`PUT /v1/projects/:projectId/kb/space` stored whatever `config` it was given
(`kb-tasks.ts:163`) while `validate()` judges every entry by the chain that
config resolves to *now* (`validate.ts:48,113-118`). A space stored with an
empty config runs the research chain (`chainFromConfig` defaults to it), so
agents legitimately write H/E/F/L under it; rewriting the config to
`{"chain":"product"}` then leaves every one of those entries undeclared:
- the PATCH route validates on every autosave, so the page can never be saved
again (`unknown_artifact_type` in the editor — theam#36);
- `validateProjectKb()` validates the whole space, and the orchestrator treats
its failure as a terminal gate, so one stranded entry fails the KB
checkpoint of every later run in the project.
The same thing strands S/D/T/V/R in the other direction.
Refuse the change instead of storing a config that re-litigates history. The
harness gains `entriesStrandedByChain(entries, chain)` — the entries a chain
leaves undeclared, by artifact id — and the PUT handler runs it inside the
update transaction against the entries stored for the space. A non-empty
result is a 409 `chain_change_strands_entries` naming the chain and the
entries; the stored config is untouched. Doc-only saves and a config that
still declares every stored type go through as before, and nothing changes
for entry creation, which already validates against the stored chain.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3 tasks
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.
What changes
PUT /v1/projects/:projectId/kb/spacenow refuses aconfigwhose chain would leavean entry already stored in the space undeclared. The refusal is a
409 chain_change_strands_entriesnaming the chain and every stranded entry by artifactid; the stored config stays untouched. Doc-only saves and any config that still
declares every stored type go through exactly as before.
packages/harness—entriesStrandedByChain(entries, chain): the entries a chainleaves undeclared, by artifact id. Pure, exported, three tests of its own.
services/api— the PUT handler runs it inside the update transaction against theentries stored for the space, before touching
patch.config. One end-to-end testthrough
app.inject: write anHunder the research default, try{"chain":"product"}→ 409 with the entry named and the config unchanged; then acharter-only save and an explicit
{"chain":"research"}both 200.apps/docs— one paragraph in Knowledge & the Project Owner stating the rule.No change to
chain.ts, to entry creation, or to how a chain is resolved — so this sitsbeside #179 without overlap.
Why
validate()judges every entry by the chain the space's config resolves to now(
validate.ts:48,113-118), and the PUT stored whatever config it was given(
kb-tasks.ts:163). A space stored with an empty config runs the research chain(
chainFromConfigdefaults to it), so agents legitimately write H/E/F/L under it.Rewrite that config to
{"chain":"product"}and every one of those entries isundeclared from then on:
unknown_artifact_typein the editor, which is KB: editing agent-written pages 400s when their type is not in the space chain config (unknown_artifact_type) #36 as reported;validateProjectKb()validates the whole space, and the orchestrator treats itsfailure as a terminal gate (
sandbox/orchestrator.ts:321-327), so one stranded entryfails the KB checkpoint of every later run in the project.
The same thing strands S/D/T/V/R in the other direction. Nothing was written wrongly in
either case; the config change re-litigated history. The fix is to refuse the change
while it would do that — which is the approach @imran-ishaq described on #179 when he
asked for this as a sibling PR, and it is the one I'd have argued for after trying the
alternative. I had a soft-allow in my pocket (let stored entries of an undeclared type
stay editable) and set it aside: it keeps pages saveable, but it treats the symptom,
and every later validation still has to know about the exception. Refusing at the
cause needs no exceptions anywhere else.
Boundaries
resolves; a space stored with
{}still runs the research chain. A space that isalready stranded today stays that way — recovering it (supersede or remove the
stranded entries, or set a chain that declares them) is a separate, deliberate act,
and the 409 tells the operator exactly which entries are involved.
entry created concurrently, between this check and the commit, is validated by its
own route against the config stored at its read — the same last-writer window
entry creation already has. Narrowing it further would need a space-level lock, which
felt out of proportion for an operator action.
product chain, and the platform's own intake route writes
S— yet an empty configresolves to research. That default is where KB: editing agent-written pages 400s when their type is not in the space chain config (unknown_artifact_type) #36 starts, and @imran-ishaq proposed
defaulting product spaces to
chain: "product". It is a behaviour change for everynew project, so I have kept it out of this PR on purpose and would open it separately
if you want it — persisted at creation time, never at resolution time, so existing
spaces are not re-chained retroactively (which would strand them, the exact class
this PR closes).
Verification
Against
main@ae68401, Node 22.23.2 / pnpm 11.20.0, Postgres viadocker-compose.dev.yml(facility_test/facility_gw).Addresses #36.