docs: record the IsActive no-write rule in AGENTS.md

2026-07-29 16:04:08 -05:00
parent 05ec465f74
commit 8a4ab2402d
1 changed files with 20 additions and 0 deletions
@@ -47,6 +47,26 @@ say nothing about the item being fetched, so they must not be recorded as per-it
 - Long-running commands return exit 3 when a pass ends incomplete (rate-limit pause, breaker trip, or
  skipped items), so a caller can distinguish that from a clean run
 ### `IsActive` Is Not Ours To Write
 `Blogs.IsActive`, `Posts.IsActive` and `Notes.IsActive` are removal flags set by other tools
 (Rolodex). `0` means removed; anything else, including `NULL`, means live. Full detail in
 `URLNotesGrabberCORE/TL.db.md`.
 - **Never write any `IsActive` column.** Not in an `INSERT` column list, not in an `UPDATE`,
  and never via `INSERT OR REPLACE` on these tables — that resets the column default and
  un-removes the row. Re-crawling a removed row must refresh its content and leave the flag
  where it was
 - **Filter at selection, not at write.** Every query that *selects* posts, notes or blogs
  excludes removed rows. Update statements stay keyed on a row the caller already selected;
  filtering them would spend API quota and then fail to persist the result
 - `Posts.IsActive` and `Notes.IsActive` are **optional** — they are absent from databases
  that predate them, and naming a missing column is a hard SQLite error. Compose the filter
  with `AndIsActive`/`WhereIsActive` in `DataAccess.cs`, which return
  `COALESCE(IsActive, 1) = 1` only when `HasIsActiveColumn` finds the column. `Blogs.IsActive`
  is not optional and is filtered directly
 - Do not add these columns from this app, and do not add them to the missing-column list in
  `verify-db-schema.sql`
 ### Testing
 - No existing test suite; use xUnit if adding tests
 - Test critical logic: `ApiKeyPool` init, color parsing, config persistence