Skip to content

Give the runbook the new-table case, and separate the two rebuilds - #8

Merged
kengio merged 2 commits into
mainfrom
docs/runbook-new-table-rebuild
Aug 31, 2026
Merged

Give the runbook the new-table case, and separate the two rebuilds#8
kengio merged 2 commits into
mainfrom
docs/runbook-new-table-rebuild

Conversation

@kengio

@kengio kengio commented Aug 31, 2026

Copy link
Copy Markdown
Owner

Follow-up to #7, which added rebuild to the master workflow and documented the skip in modes.md. The reference docs now describe the behaviour; the runbook — where an operator actually goes when something looks wrong — still did not.

The case that was missing

An estate using a table glob meets this before any other: a table created since the last generate is not granted, and every run since has reported success. Nothing in the runbook explained that.

New 3i covers:

  • why the skip holds — config_hash fingerprints config rows and cannot see the catalog
  • that it is intended: a table arriving in storage is not by itself a decision to share it
  • rebuild=True re-resolves every pattern, so it takes in every table added since the last real generate, not only the one you had in mind — read the plan, not the config diff
  • holding one back with exclude_tables, and that a zero-match exclude is an error (rule A2), so the table must already exist
  • the stale converse: a deleted table stays in the mapping, and apply keeps submitting a role naming a path that is gone
  • the unrelated conditions (member pattern, drifted objectIds, target mismatch, member-table errors, framework-version change) that force a full re-resolution and therefore widen scope as a side effect — a run made for one of those reasons can grant new tables with no config edit behind it

The sharper problem: one word, two opposite meanings

rebuild appeared in the runbook in exactly one place — 3e, setup(rebuild=True), which DROPS a control table and loses its data.

So an operator whose new table is missing, searching the runbook for rebuild, found the destructive one and no sign that a harmless one exists. 3e now states that the two share a parameter name and nothing else, and points at 3i.

Safety language

Both sections say plainly that not granting a table is not denying it — readability still depends on workspace and item permissions and the access path, so a missing grant must not be read as containment. This matches the framing modes.md and architecture.md already use.

Verification

  • check_public_release.py tree . — PASS, 0 findings
  • check_external_links.py — 40/40 reachable
  • docs-only: no runtime change, no version bump, no tag. CHANGELOG under [Unreleased].

kengio added 2 commits August 31, 2026 21:05
An estate using a table glob meets one operational case before any other: a
table created since the last generate is not granted, and every run since has
reported success. The runbook had no entry for it. 3i covers why the skip
holds, what `rebuild=True` re-resolves and drops, holding one back with
`exclude_tables`, the stale converse when a table is deleted, and the unrelated
conditions that force a re-resolution and widen scope as a side effect.

The sharper problem is the word itself. `rebuild` appeared in the runbook in
exactly one place — 3e, `setup(rebuild=True)`, which DROPS a control table and
loses its data. So an operator whose new table is missing, searching the runbook
for `rebuild`, found the destructive one and no sign that a harmless one exists.
3e now says the two share a name and nothing else, and points next door.

Both sections say plainly that not granting a table is not denying it: readability
still depends on workspace and item permissions, and a missing grant must not be
read as containment.
Follow-up review of the same claim across the repo turned up two more.

The cookbook's generate note told readers that re-running an unchanged config
is a no-op — true, and the half nobody is surprised by. The half that surprises
them is that a changed CATALOG is also a no-op, which is exactly the case the
new runbook section exists for. It now says both and points there.

`config-examples.md`'s CLS whitelist takeaway said the difference "only shows up
on a later generation" — the same ambiguity 7a lost two sections earlier in the
previous commit, left behind in 7b because the sweep matched on wildcards rather
than on the shape of the claim.
@kengio
kengio merged commit 34219bc into main Aug 31, 2026
6 checks passed
@kengio
kengio deleted the docs/runbook-new-table-rebuild branch August 31, 2026 14:24
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