knowledge-40.md

systems/40-server/gov/knowledge-40.md
# knowledge-40.md — Server [40]
# CAI System Experience & Expertise Log
# Standard: D095 Series F — loaded at session open step 3b alongside jurisdiction-40.md
# Last updated: 07/12/26

---

## Environment
[07/10/26] Backend directory hierarchy restructure complete — D207. All content branches off domain root. Hierarchy map now permanent standard in BACKEND-S.md v1.1.
[07/10/26] backend/ access rules — whitelists API  script paths to bypass auth gate. Token-auth via cookie is for HTML pages only. APIs use token= param, must be in whitelist.
[07/10/26] records.db moved to backend/records/db/ — API at backend/records/db/data-api. Old sys-com/db/data-api is 404 (correct — retired).
[07/10/26] records.db API 302 was the  access rules auth gate — FIXED by whitelisting API  script paths. Confirmed 200 + JSON. This was Admin[00] T464 item 1.
[07/10/26] restructure_data-api v1.1 — ping action added. POST add_entry to log board entries. All systems must post here at every SYNC.
[07/10/26] [api] v1.2 live at systems/commands/ — D211. Pulls decisions/sessions/transfers/events/domain/inbox since last closed_at. Registered in [api].
[07/10/26] [api] v1.2 — action=force now works via GET (was broken, fixed this session).
[07/10/26] sys-records.db was a 0-byte ghost — deleted. Real DB is records/db/records.db.
[07/09/26] Series F live — session-opener + session-closer replace all manual session steps.
[07/09/26] cai_time() + cai_now() canonical in [api]. No format args.
[07/09/26] [api] at systems/commands/ — list/status for all 11 systems.

## Patterns
[07/17/26] Multi-thread sessions: David frequently introduces new subjects mid-session before current work is complete. Pattern: immediately LOG the open thread as a task (title + exact current state + next step), PARK in handoff, SURFACE open list to David, confirm priority. Prevents invisible drift. D357.
[07/10/26] [api] (D209/D212) — enforces 2-version backup rule (CURRENT+PREVIOUS only) + D102 trash lifecycle across all systems. Trigger: David says clean up or take out the trash. GET token [&system &dry=1]. Never hard-deletes — extras to trash.
[07/10/26] Backup drift root cause: BACKUP item_name is free-form, so same file backed up under different names (verify_lib vs VerifyLib) = multiple CURRENTs. CLEANBACKUPS normalizes + keeps newest. Use consistent item_names.
[07/10/26] [api] v2.1 — accepts bare path strings in files[] OR {item_name,path,type} objects. Bare string auto-derives item_name from filename, type from ext (.html=html-pages else applications). JSON body most reliable: POST -H Content-Type:application/json -d {token,system,files:[paths]}.
[07/10/26] Backend hierarchy rule: info/=reference content, records/=data, projects/=active projects, sys-com/=UI+APIs only, ed/=own root. New dirs must branch off domain root.
[07/10/26]  access rules token bypass: add RewriteCond %{REQUEST_URI} !^/backend/path/to/api\ script for each new API that needs token-auth without cookie.
[07/10/26] [api] system DB schema: events has subject/detail (not title/body). domain has category (not type at top level). Always check schema before querying system DBs.
[07/10/26] security filter blocks  access rules writes via write-api — use bootstrap deploy.
[07/10/26] Force snapshot: GET [api]?token=...&action=force (fixed in v1.2).
[07/09/26] Bootstrap deploy REQUIRED for systems/commands/* script — security filter blocks direct write.
[07/09/26] Transfers over 1KB — use content@/tmp/file not inline -d.

## Lessons
[07/10/26] Auth gate intercepts ALL /backend/ requests without cookie — new APIs must be whitelisted in  access rules or they return 302. Check this whenever a new PHP tool is deployed to backend/.
[07/10/26] PHP string interpolation: complex expressions inside {} (casts, chained calls) cause parse errors. Use simple variables only inside interpolated strings.
[07/10/26] System DB schemas vary per system — always read PRAGMA table_info before writing event/domain queries. events table uses subject/detail, NOT title/body.
[07/09/26] cai_time() does not accept format arguments — causes timestamp bug (PPDT).
[07/09/26] write-api — WRITE ONLY. Never use to read.

## Open Items
[07/10/26] ed/reference/data-api — old sys-com/db/ path may still be present. Handed to Builder (T451) + on site-build board.
[07/10/26] site-index.html — required by STANDARDS-REG.md, not yet built.

### auth/ — PROTECTED — DO NOT CLEAN
[07/09/26] backend/auth/ is Server [40] jurisdiction — contains real deploy/gate tooling:
  [api], [api], [api], [api], gate_b64.txt,
  ht_b64.txt, [api], [api], log_b64.txt
CLEAN must never touch backend/auth/. Already in CLEAN protected paths (D118).

## Lockdown — 07/13/26 Session 012
[07/13/26] commands/ wipe happened TWICE (07/12 + 07/13). Root cause: bootstrap scripts deployed directly into systems/commands/ used unlink() on themselves, taking adjacent command files during failed execution. NOT external intrusion.
[07/13/26] FIX DEPLOYED:  access rules in systems/commands/ — negative lookahead FilesMatch blocks any PHP not in the 16-name whitelist from executing via web. Bootstrap/rogue scripts written there cannot execute.
[07/13/26] All 16 command PHPs backed up to backups/platform/commands/ with CURRENT rotation. [api] now covered (was missing).
[07/13/26] WISDOM: Bootstrap scripts MUST go to backend/tmp/ ONLY. Never write executable PHP to systems/commands/ directly. The  access rules is the last line of defense — backend/tmp/ rule is the first.
[07/13/26] To add a new command PHP: (1) add <Files> whitelist entry to systems/commands/ access rules first, (2) back up  access rules to platform/commands/, (3) then deploy the new PHP.
[07/13/26] transfers/[api] confirmed at transfers/[api] (root) — systems/transfers/ holds inbound/outbound dirs only, no API ever lived there. T033 was a false alarm.


## Commands/ Wipe Incident & Lockdown — 07/13/26 Session 012

### What Happened
- commands/ wipe occurred TWICE: 07/12/26 and 07/13/26 (confirmed from Master [01] report)
- Root cause: bootstrap deploy scripts were written directly into systems/commands/ instead of backend/tmp/
- Those scripts used unlink(__FILE__) to self-delete on execution
- When execution failed mid-run, files in commands/ were left corrupted or missing
- NOT an external intrusion. Platform-internal deploy error.

### Fixes Deployed This Session
-  access rules deployed to systems/commands/ — negative lookahead blocks any PHP not on the 16-name whitelist from executing via web
- [api] upgraded v1.2->v1.3 — now has ACTIVE SWEEP: orphans moved to trash, never hard-deleted
- All 16 command PHPs backed up to backups/platform/commands/ with CURRENT/PREVIOUS rotation
- [api] backup gap closed — was the only command with no backup
- backups/ access rules deployed — backups/ directory now 403 from web (server-side only)

### Security Protocol — PERMANENT RULES
1. Bootstrap scripts MUST go to backend/tmp/ ONLY — never to systems/commands/ or any live dir
2. systems/commands/ access rules whitelist is the last line of defense — backend/tmp/ rule is the first
3. To add a new command PHP: whitelist it in systems/commands/ access rules FIRST, then deploy
4. [api] runs active sweep every housekeeping — orphans to trash, never deleted
5. backups/ is web-inaccessible — confirmed 403

### WISDOM — 07/13/26
WISDOM 07/13/26: Bootstrap scripts in wrong dir + self-delete = wipe -- always write bootstrap to backend/tmp/, never to live command directories
WISDOM 07/13/26: [api] was report-only, not active -- upgraded to v1.3 with live sweep -- housekeeping must always move to trash, never delete
WISDOM 07/13/26: [api] had no backup -- most critical file, zero coverage -- always include RESTORE in backup runs
WISDOM 07/13/26: transfers/[api] is at transfers/ root, not systems/transfers/ -- T033 was false alarm

### Transfer/Transfers Canonical Location
- transfers/[api] = transfers/ (root level, NOT systems/transfers/)
- systems/transfers/ = inbound/ and outbound/ dirs only, no API
[07/21/26] records.db canonical paths confirmed: Real DB = backend/records/db/records.db (581KB, live). Real API = backend/api/critical/records-api (39KB). TRAP: backend/api/critical/records.db exists as 16KB ghost stub — bootstrap scripts that hit this path silently fail. Old API backend/records/db/data-api = 301 stub only. Always use records-api at critical/ path. STANDARDS-REG.md is corrupted (single garbled line) — records.db path doc pending Admin [00] repair of that file.