Skip to content

fix(kb): refuse a chain change that would strand stored entries - #195

Open
ophiocus wants to merge 1 commit into
theam:mainfrom
ophiocus:fix/kb-refuse-stranding-chain-change
Open

fix(kb): refuse a chain change that would strand stored entries#195
ophiocus wants to merge 1 commit into
theam:mainfrom
ophiocus:fix/kb-refuse-stranding-chain-change

Conversation

@ophiocus

Copy link
Copy Markdown

What changes

PUT /v1/projects/:projectId/kb/space now refuses a config whose chain would leave
an entry already stored in the space undeclared. The refusal is a 409 chain_change_strands_entries naming the chain and every stranded entry by artifact
id; the stored config stays untouched. Doc-only saves and any config that still
declares every stored type go through exactly as before.

  • packages/harnessentriesStrandedByChain(entries, chain): the entries a chain
    leaves undeclared, by artifact id. Pure, exported, three tests of its own.
  • services/api — the PUT handler runs it inside the update transaction against the
    entries stored for the space, before touching patch.config. One end-to-end test
    through app.inject: write an H under the research default, try
    {"chain":"product"} → 409 with the entry named and the config unchanged; then a
    charter-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 sits
beside #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
(chainFromConfig defaults to it), so agents legitimately write H/E/F/L under it.
Rewrite that config to {"chain":"product"} and every one of those entries is
undeclared from then on:

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

  • Legacy spaces are untouched. Nothing here changes how an existing config
    resolves; a space stored with {} still runs the research chain. A space that is
    already 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.
  • The check runs inside the update transaction at read-committed isolation. An
    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.
  • The default chain for new spaces is not changed here. The docs describe only the
    product chain, and the platform's own intake route writes S — yet an empty config
    resolves 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 every
    new 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

pnpm exec biome check --write <changed files>        # no fixes applied
pnpm --filter @facility/harness test                 # 7 passed (3 new)
pnpm --filter @facility/harness exec tsc --noEmit    # clean
pnpm --filter @facility/api exec tsc --noEmit        # clean
pnpm test:critical                                   # exit 0, no skips:
                                                     #   db 18/18 · cli 98/98 ·
                                                     #   api 471/471 (42 files) · gateway 52/52

Against main @ ae68401, Node 22.23.2 / pnpm 11.20.0, Postgres via
docker-compose.dev.yml (facility_test / facility_gw).

Addresses #36.

`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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant