Skip to content

fix(tags): prune every persisted tag id through one vocabulary reader - #28779

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/tag-prune-one-reader-26160
Nov 3, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/tag-prune-one-reader-26160

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: every place that prunes saved tag ids against the tag list applies the same rule, so a hand-edited tag file cannot break the sidebar columns and the stale-store rule lives in one place.

Three sites prune persisted tag ids against the tag vocabulary loaded from tags.json, and each built its own vocabulary set:

  • the slot metadata restore, _read_tags in src/kiro_crew/dashboard/slot_persistence/metadata_codec.py:651-653 (every restore, recent and resume read);
  • the folder / channel inheritance filter, validate_folder_tag_ids in src/kiro_crew/dashboard/chat_tags_store.py:41 (slot create, folder create/PATCH, channel filing and the channel restore read);
  • the sidebar-column boot prune in load_tags, src/kiro_crew/dashboard/state_parts/sidebar_stores.py:867-872.

They differed on shape guards, and each restated the UNKNOWN / KNOWN-EMPTY rule on its own, so the stale-store rule could not be decided in one place (#26160, a follow-up named by #5933).

Why it matters

The column prune had no string guard. A hand-edited tag_boards.json with a non-string id in a column's tag_ids raised unhashable type: 'list' inside load_tags, which set _tag_boards_load_failed, so every column write (create, rename, reorder, delete) was refused for the life of the process. The folder reader kept an empty-string id under an UNKNOWN vocabulary while the slot reader dropped it.

Not a goal

  • Changing what a stale-but-readable store does. See "Design choice" below.
  • api_chat_slot_tags (chat_tags.py:173) and the column API's _clean_column (chat_tags.py:352). They validate REQUEST input against the vocabulary, strictly, and prune no persisted value. They stay their own filters; the validate_folder_tag_ids docstring now says so instead of calling them a pending follow-up.

What changed (motivation → approach → change)

  • New leaf module src/kiro_crew/dashboard/tag_vocabulary_read.py:
    • known_tag_ids(state) returns None when the vocabulary is UNKNOWN (_tags_authoritative False), else a frozenset of the string ids (empty = KNOWN-EMPTY).
    • prune_tag_ids(raw, known) applies the shape guards in every state (list only; non-empty string ids only, checked before the membership test; order-preserving; de-duplicated) and intersects with known only when it is not None.
    • No dashboard imports, so state_parts/ and slot_persistence/ use it without an import cycle. The three callers import it inside the function that prunes, so no owner of the chat_tags, chat_persistence or state facades binds a new module-level name (those facades serve every name their owners bind, and their contract tests pin that surface).
  • validate_folder_tag_ids, _read_tags and the column boot prune now each call prune_tag_ids(raw, known_tag_ids(state)).
  • Behaviour deltas, all on malformed or duplicate input only: a column with a non-string id loads (the bad id is dropped) instead of failing the columns store; slot restore de-duplicates ids; the folder reader drops an empty-string id under an UNKNOWN vocabulary, as the slot reader already did; the column prune applies the same shape guards under an UNKNOWN vocabulary (it still prunes no listed-or-unlisted string id there).
  • Module map: one line for the new module in docs/system-specs/modules/learn-cron-dashboard.md.

Design choice

A stale-but-readable store (a restored backup, a half-synced data home) parses as KNOWN, and nothing in a parsed list tells it apart from a current one. This PR keeps pruning against a KNOWN store and decides that rule in one function, known_tag_ids.

The other design was to stop pruning at boot against a KNOWN store (or to add a staleness stamp to tags.json). It lost because: every vocabulary mutation in this tree is commit-first, so the process never writes a stale store itself; the boot prune is the only pass that removes an id left dangling by a crash between a tag delete's commit and its sweep; and telling "deleted" from "never listed" needs a durable per-id record. #5933's design notes (docs/system-specs/modules/history.md on its branch, "Why the boot prune is kept even though a stale store would strip") reach the same conclusion. If a staleness signal is added later, it changes known_tag_ids alone and every prune site follows.

Intended? / Repro

Intended? No. The validate_folder_tag_ids docstring on main (src/kiro_crew/dashboard/chat_tags_store.py:47-53) says the inline prunes elsewhere should be consolidated onto it and that this was "deliberately left to a follow-up"; #5933 names #26160 as that follow-up. Nothing in docs or history argues for keeping separate readers.

Repro on main 15bcfebef2 (the base this branch was cut from; the code is unchanged on the current base) (standalone script with a scratch data home, not a test run):

  • tags.json = [{"id": "keep", "name": "Keep", "status": false}]
  • tag_boards.json = [{"id": "c1", "name": "Col", "tag_ids": ["keep", ["hand-edited"]], "mode": "any"}]
  • DashboardState(...).load_tags()

Saw: Failed to load sidebar columns ... TypeError: unhashable type: 'list', _tag_boards_load_failed = True, the column left as ["keep", ["hand-edited"]], while validate_folder_tag_ids on the same ids answered ["keep"]. Under an UNKNOWN vocabulary validate_folder_tag_ids(["keep", ""]) answered ["keep", ""], where the slot reader drops "". With this branch the same script prints _tag_boards_load_failed = False, column ["keep"], and ["keep"] for the UNKNOWN case.

Backwards compatibility

No persisted format change. Well-formed string ids are pruned exactly as before in each vocabulary state; only malformed, empty or duplicate entries are treated differently (listed above).

Reader: callers of validate_folder_tag_ids (channel_slots.py, chat_api/slot_create.py, chat_folders_records.py, session_directive_apply_slot.py) -- an empty-string id is now dropped under an UNKNOWN vocabulary; no tag can have an empty id (load_tags refuses such rows), so nothing they apply changes.
Reader: slot restore (metadata_codec.apply, every restore/recent/resume read) -- a duplicate id on the metadata line is now kept once; a slot's tags are a set in every UI and API that reads them.
Reader: sidebar columns (load_tags) -- a non-string id in a column's tag_ids is dropped instead of failing the columns load; the column API already refuses such ids on write.

Tests

test/test_tag_vocabulary_one_reader.py (new):

  • test_every_prune_site_answers_what_the_one_reader_answers, parametrized over a stale-but-readable store (lists old; newer was applied since), an unreadable store (UNKNOWN) and [] (KNOWN-EMPTY). One persisted value ["old", "newer", "old", "", ["list-id"], 7] goes through the column boot prune, validate_folder_tag_ids and a real slot restore (codec.apply), and each must equal prune_tag_ids(raw, known_tag_ids(state)). It also asserts the non-string id does not fail the columns load.
  • test_known_tag_ids_states and test_prune_shape_guards_hold_in_every_state pin the reader itself.
  • test_no_prune_site_reads_the_vocabulary_authority_flag_itself: a source scan that refuses a new read of _tags_authoritative outside the reader (writes are allowed; chat_tags_policy.py, which refuses an agent removal and never prunes, is the one other reader).

Local gates only, per host rule: black, isort, flake8 and mypy clean on the changed files. CI runs the tests.

Manual verification

The repro script above, before and after.

Related Issues

Fixes #26160. Follow-up from #5933 (not touched here).

Sibling sweep

Swept: git grep -n "_tags_authoritative\|validate_folder_tag_ids\|for t in .*_tags}" -- src/
Sibling: src/kiro_crew/dashboard/slot_persistence/metadata_codec.py -- changed here (slot restore prune)
Sibling: src/kiro_crew/dashboard/state_parts/sidebar_stores.py -- changed here (column boot prune)
Sibling: src/kiro_crew/dashboard/chat_tags_store.py -- changed here (folder/channel filter delegates)
Sibling: src/kiro_crew/dashboard/channel_slots.py, chat_api/slot_create.py, chat_folders_records.py, session_directive_apply_slot.py -- not affected -- they already call validate_folder_tag_ids
Sibling: src/kiro_crew/dashboard/chat_tags.py:173, :352 -- not affected -- request-input validators, not persisted-tag prunes
Sibling: src/kiro_crew/dashboard/chat_tags_policy.py:275 -- not affected -- refuses an unresolvable agent removal; prunes nothing

Pattern harvest

Not generalizable: the rule is specific to the tag vocabulary, and the new source-scan test already keeps any future prune site from reading the vocabulary authority flag on its own.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners November 3, 2026 01:52
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 3, 2026
@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision fc5296e29024194beaefd6e1c92ab4c7580bd334 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of fc5296e29024194beaefd6e1c92ab4c7580bd334 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Each item fixes a defect the PR reproduces, or removes a duplicate prune rule from the three sites that each carried their own copy.

Notes

  • Item 6 — rides along: "slot restore de-duplicates ids" is a behaviour change on its own, and its only support is "aligned with the folder reader", which is the symmetry form of inherited. Subtraction: none needed. Keeping it lets all three sites share prune_tag_ids, and that sharing is the Goal.

What this change ships

Inventory (7 items) — 6 justified

Intent: Make every prune of saved tag ids against tags.json follow one rule, so a hand-edited column file can no longer lock column edits. FIX.

  1. A sidebar column with a non-string tag id now loads with that id dropped, instead of refusing every column write until restart — justified
  2. Under an unreadable vocabulary, the folder and channel inheritance filter now drops an empty-string id, as the slot restore already did — justified
  3. The column boot prune applies the same shape guards under an unreadable vocabulary — justified
  4. New leaf module tag_vocabulary_read.py (known_tag_ids, prune_tag_ids) with 3 consumers; validate_folder_tag_ids now delegates to it — justified
  5. A new source-scan test refuses any new read of _tags_authoritative outside the reader — justified
  6. Slot restore now de-duplicates tag ids — rides along, symmetry with the folder reader
  7. One module-map line in learn-cron-dashboard.md — justified

[FIRST-PRINCIPLES-REVIEWED] fc5296e

Description read

[DESCRIPTION-READ] 4bd5ac3bf68765b08bb858dcd53f784b2fe674805b439ae36e68d614e70dd3c0

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of fc5296e29024194beaefd6e1c92ab4c7580bd334 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the three prune sites move onto one leaf reader, and behaviour changes only for malformed, empty or duplicate ids.

Notes

  • ## Backwards compatibility lists no Reader: lines. The PR does take something away: an empty-string folder id is now dropped under an UNKNOWN vocabulary, and slot restore now de-duplicates. List the callers of validate_folder_tag_ids (channel_slots.py, chat_api/slot_create.py) as readers, or state Removes nothing with the reason.

[DESIGN-REVIEWED] fc5296e

Description read

[DESCRIPTION-READ] 89e45ce81ae2b55de3c33ed0f9360bdcfe877608658d4cdef78c68180b0789fc

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed fc5296e29024194beaefd6e1c92ab4c7580bd334 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] fc5296e

Verdict parsed from the review's SHA-scoped output markers for commit fc5296e29024194beaefd6e1c92ab4c7580bd334.

False positive or not applicable? A repository writer can comment:
/ai-review override fable fc5296e29024194beaefd6e1c92ab4c7580bd334 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of fc5296e29024194beaefd6e1c92ab4c7580bd334 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fc5296e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt fc5296e29024194beaefd6e1c92ab4c7580bd334 false-positive: <reason, 20 to 500 characters>

@CrysisDeu
CrysisDeu force-pushed the fix/tag-prune-one-reader-26160 branch from 8277a93 to 31b9237 Compare November 3, 2026 02:16
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 3, 2026
The slot metadata restore, the folder/channel inheritance filter and the
sidebar-column boot prune each built their own vocabulary set. They
disagreed on shape (a non-string column id raised 'unhashable type' and
failed the whole tag_boards.json load, refusing every column write for
the process) and each restated the UNKNOWN / KNOWN-EMPTY rule.

Add dashboard/tag_vocabulary_read.py (known_tag_ids + prune_tag_ids) and
route all three sites through it, so the stale-store rule is decided in
one place. A test seeds stale-but-readable, unknown and known-empty
stores and asserts every site answers what the one reader answers.

Fixes #26160
@CrysisDeu
CrysisDeu force-pushed the fix/tag-prune-one-reader-26160 branch from 31b9237 to fc5296e Compare November 3, 2026 02:44
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision labels Nov 3, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 3, 2026 04:06

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (6 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: every persisted tag-id prune now reads the tag vocabulary through one reader, with a test per vocabulary state. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/system-specs/modules/learn-cron-dashboard.md.

@KiroCrewCaptain
KiroCrewCaptain merged commit e04f120 into main Nov 3, 2026
108 of 116 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/tag-prune-one-reader-26160 branch November 3, 2026 04:07
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 3, 2026
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.

Consolidate the tag-prune readers on one vocabulary read

2 participants