Asterion JNO seed v2 — pre-staged doctrine MD; ONBOARDING reflects pre-staged plugin

Adds:
SA-orchestration MD/ doctrine reference (root .md docs from SA-Orch source repo)
plain files; no nested .git or .claude

ONBOARDING.md Step 5 updated to reference the pre-staged plugin tree at
<repo-root>/sa-orchestration/ rather than a GitHub clone. If the directory
is missing, the seed is corrupt — surface to human; do NOT invent a clone URL.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ONBOARDING.md

@@ -145,24 +145,22 @@ After activating each, walk its setup wizard to completion. Skip any optional in
 - FluentCRM: `wp_fc_*` tables exist (subscribers, campaigns, etc.). Admin page renders.
 - Fluent Support: `wp_fs_tickets` table exists. Admin page at `?page=fluent-support` renders. **Watch for the prefix-orphan trap** — if tables ended up at a non-standard prefix (e.g., from a cloned DB), that's a separate fix not part of fresh JNO.
 
-### Step 5 — Clone SA-Orchestration plugin source
+### Step 5 — Install SA-Orchestration plugin (pre-staged in this repo)
 
-Verify the canonical SA-Orchestration repository URL with the human first. The likely location:
+**The plugin source is already in this repo at `<repo-root>/sa-orchestration/`** — no GitHub clone is needed. Operational doctrine MD files are at `<repo-root>/SA-orchestration MD/` for agent reference.
 
-```
-git clone https://github.com/SleeperAgents/SA-Orchestration.git /tmp/sa-orchestration-src
-```
-
-Then copy the plugin tree into the local WP install:
+Copy (or symlink) the pre-staged plugin tree into the local WP install:
 
 ```
-cp -r /tmp/sa-orchestration-src/plugin/sa-orchestration <wp-content>/plugins/sa-orchestration
+cp -r <repo-root>/sa-orchestration <wp-content>/plugins/sa-orchestration
 ```
 
-Adjust path syntax for the dev's OS. On Windows: use the WP install's `wp-content\plugins\` path.
+Adjust path syntax for the developer's OS. On Windows: use the WP install's `wp-content\plugins\` path. The dev's Claude resolves `<repo-root>` and `<wp-content>` from the developer's actual environment.
 
 **Verify**: `<wp-install>/wp-content/plugins/sa-orchestration/sa-orchestration.php` exists.
 
+If the pre-staged `sa-orchestration/` directory is missing for some reason, **stop and surface to the human**. Do not invent a clone URL. The seed should always include the plugin tree at `<repo-root>/sa-orchestration/`; absence indicates a corrupted seed, not a missing dependency.
+
 ### Step 6 — Place the Asterion canonical corpus
 
 The SA-Orchestration plugin reads its canonical content from a filterable path. For local JNO, point that path at the corpus copy in this repo.

SA-orchestration MD/Archvie/MidCoast/CLAUDE.md

@@ -0,0 +1,267 @@
+# QB Inventory Bin Audit — Project Context for Claude
+
+## What this is
+A WordPress plugin for **MidCoast Engines** that manages a QuickBooks Desktop inventory audit system.
+Two components work together:
+
+1. **WordPress plugin** (`midcoast_audit.php` + `lib/` + `views/`) — hosted on WP Engine at `sleeperagents.wpengine.com`. Provides admin UI, database, and REST API.
+2. **C# Windows Service** (`QBSyncService/`) — runs on the on-premises machine that hosts QuickBooks Desktop at MidCoast Engines. Polls WordPress every 60 seconds, executes QBXML commands against QB Desktop via COM, posts results back.
+
+## Architecture
+
+```
+[MidCoast Engines — on-site QB machine]     [WP Engine — internet]
+  QB Desktop (running)
+  C# Windows Service (QBSyncService.exe) ──HTTPS──▶ WordPress REST API
+    - polls /wp-json/qbinv/v1/sync/queue             - stores sync queue
+    - executes QBXML via COM SDK                      - admin UI
+    - posts results back                              - heartbeat status
+```
+
+The C# service is developed on Thomas's laptop (VS 2026) and deployed to the QB machine on-site via Andrew using FileZilla. Thomas uses **Tailscale + RDP** for remote access to the QB machine without requiring anyone on-site.
+
+## WordPress Plugin
+
+### Entry point
+`midcoast_audit.php` — registers autoloader, hooks, admin menu, REST API, SOAP endpoint.
+
+### Key constant
+`PUBLIC_AUDIT_KEY = 'steelblue123'` — used for the public-facing shortcode `[qbinv_audit_public]`.
+
+### lib/ files
+| File | Purpose |
+|---|---|
+| `DB.php` | Table names, `install()` (dbDelta), schema |
+| `QBSync.php` | Queue helpers + QBWC SOAP service class |
+| `REST.php` | REST endpoints consumed by the C# service |
+| `Actions.php` | POST mutation handler; fires `qbinv_entry_changed` action on qty save |
+| `Importer.php` | Legacy CSV import |
+| `Router.php` | URL helpers |
+| `Helpers.php` | Shared utilities |
+| `QueryBuilder.php` | Dynamic query builder for parts/shelves browse |
+| `TableRenderer.php` | HTML table output |
+
+### views/ files
+| File | Purpose |
+|---|---|
+| `Upload.php` | Import page — primary: live QB pull; secondary: CSV legacy |
+| `QBSync.php` | Sync queue admin + settings (token, QBWC creds, .qwc download) |
+| `Parts.php` | Browse/edit parts |
+| `Shelves.php` | Browse/edit shelves |
+| `Audit.php` | Official audit view |
+
+### Database tables (all prefixed with `{wpdb->prefix}qbinv_`)
+- `parts` — inventory parts (part_number, preferred_description, etc.)
+- `locations` — bin/shelf locations
+- `entries` — qty per part per location
+- `uploads` — import history
+- `sync_queue` — QB sync action queue
+
+### REST endpoints (`/wp-json/qbinv/v1/`)
+All require `X-QBSync-Token` header matching WP option `qbinv_sync_token`, **except** `/sync/interrupt` which requires `manage_options` capability.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/sync/queue` | Fetch up to 50 pending actions; auto-rescues stale processing rows |
+| POST | `/sync/{id}/claim` | Mark action as processing (atomic); sets `processed_at` |
+| POST | `/sync/{id}/done` | Save QB response, mark done; fires inventory parser if applicable |
+| POST | `/sync/{id}/fail` | Save error message, mark error, increment retries |
+| POST | `/sync/heartbeat` | C# service posts version+host+phase+stats; WP stores all |
+| GET | `/sync/config` | Remote config (poll interval, mode, interrupt flag, etc.) |
+| POST | `/sync/interrupt` | Admin sets abort flag (one-shot, auto-cleared on next config fetch) |
+| POST | `/sync/update-status` | C# service reports self-update progress |
+
+### WP options used
+| Option | Purpose |
+|---|---|
+| `qbinv_sync_token` | API token — must match `appsettings.json ApiToken` |
+| `qbinv_wc_username` | QBWC username (legacy SOAP path) |
+| `qbinv_wc_password` | QBWC password (legacy SOAP path) |
+| `qbinv_adjustment_account` | QB account name for InventoryAdjustmentAdd |
+| `qbinv_auto_sync_qty` | Auto-enqueue QB adjustment when qty saved in WP |
+| `qbinv_service_last_seen` | Last heartbeat timestamp — drives online/offline dot |
+| `qbinv_service_host` | Machine name from last heartbeat |
+| `qbinv_service_version` | Service version from last heartbeat |
+| `qbinv_service_cycles` | Poll cycles completed since last service start |
+| `qbinv_service_items_found` | Pending items found on last poll |
+| `qbinv_service_qb_status` | QB connection status: not_attempted / connected / ok / error / interrupted |
+| `qbinv_service_last_error` | Last error message from service |
+| `qbinv_service_phase` | Current cycle phase string (e.g. "QB: executing 1/1 — ItemInventoryQueryRq") |
+| `qbinv_service_log_tail` | Last 100 log lines (autoload=false — fetched explicitly) |
+| `qbinv_sync_interrupt` | One-shot abort flag; set by admin Abort button; cleared on config read |
+| `qbinv_mode` | `read_only` or `read_write` — gates write actions service-side |
+
+## C# Windows Service (`QBSyncService/`)
+
+### Files
+| File | Purpose |
+|---|---|
+| `Program.cs` | Host bootstrap, Serilog, typed HttpClient registration |
+| `Worker.cs` | BackgroundService poll loop — heartbeat then RunCycleAsync |
+| `WordPressClient.cs` | Typed HTTP client for all WP REST calls |
+| `QuickBooksSession.cs` | QB COM wrapper — static `RunSession()` pattern |
+| `Models/SyncAction.cs` | Maps to sync_queue row; `BuildFullQbxml()` wraps snippet in envelope |
+| `Models/SyncConfig.cs` | Remote config model deserialized from `/sync/config` |
+| `appsettings.json` | Config — WP URL, API token, poll interval, QB company file |
+
+### Key technical details — STA threading (critical)
+
+**3-phase cycle design** — HTTP and COM are never interleaved:
+1. **Phase 1 (HTTP)**: `GetPendingAsync` + `ClaimAsync` for all actions
+2. **Phase 2 (COM)**: `QuickBooksSession.RunSession()` — opens QB, executes all actions, closes QB, all on one dedicated STA thread without any awaits or HTTP calls
+3. **Phase 3 (HTTP)**: `CompleteAsync` / `FailAsync` for each result
+
+**Why this matters**: QB's COM server invalidates the session if the STA thread is idle between calls. Any `await` inside the old loop (e.g. `await ClaimAsync()` between `Open()` and `Execute()`) would idle the STA thread long enough for QB to invalidate the session → `COM object separated from its underlying RCW`.
+
+**`QuickBooksSession.RunSession()`** — static factory. Creates a dedicated STA thread, runs Open → body → Close as one uninterrupted block, joins the thread (10-minute timeout), re-throws any exception via `ExceptionDispatchInfo`. The `Execute()` method is a simple instance method — no marshaling needed because the caller is already on the STA thread.
+
+**Session timeout**: `thread.Join(TimeSpan.FromMinutes(10))` — if QB hangs (frozen/crashed), throws `TimeoutException` after 10 minutes rather than blocking the service forever.
+
+- **Late-bound COM**: Uses `Type.GetTypeFromProgID("QBXMLRP2.RequestProcessor")` — no compile-time SDK reference. SDK only required at runtime on the QB machine.
+- Logs to `C:\ProgramData\QBSyncService\logs\qbsync-YYYYMMDD.log` and console.
+
+### Remote interrupt / abort
+- Admin clicks **Abort** in WP Admin → QB Sync Queue
+- Browser POSTs to `/sync/interrupt` → sets `qbinv_sync_interrupt = true`
+- Service reads `interrupt_requested: true` from next `/sync/config` call (within 60s); WP auto-clears the flag
+- Service fails all claimed actions with "Interrupted by remote admin command." and skips QB session
+- Interrupt only fires between actions — cannot cancel a mid-COM-call. Session timeout handles hung QB.
+
+### Phase tracking
+`_currentPhase` string updated throughout each cycle and sent in every heartbeat:
+- `"idle"` — between cycles
+- `"fetching queue"` — calling GetPending
+- `"claiming (N action(s))"` — claiming loop
+- `"opening QB session"` — before RunSession
+- `"QB: executing N/M — ActionType"` — inside RunSession, per action
+- `"reporting N result(s)"` — Phase 3 HTTP
+- `"interrupted"` — after abort
+- `"stopped"` — service shutdown
+
+### NuGet packages
+- `Microsoft.Extensions.Hosting.WindowsServices` — Windows Service registration
+- `Serilog.Extensions.Hosting` + `Serilog.Settings.Configuration` + `Serilog.Sinks.Console` + `Serilog.Sinks.File` — structured logging
+- `Microsoft.Extensions.Http` — `AddHttpClient()`
+
+### appsettings.json (do not commit real token to public repo)
+```json
+{
+  "QBSync": {
+    "WordPressUrl": "https://sleeperagents.wpengine.com/",
+    "ApiToken": "...",
+    "PollIntervalSeconds": 60,
+    "QuickBooksCompanyFile": ""
+  }
+}
+```
+
+## Deployment
+
+### WordPress (WP Engine)
+- FTP/SFTP files to live site after changes
+- After deploying: **Settings → Permalinks → Save** to flush rewrite rules
+- Purge WP Engine page cache after major changes
+- **short_open_tag=On** is active on WP Engine — never write `<?` anywhere in PHP source (strings, comments, heredocs). Split as `'<' . '?'` in string literals.
+
+### C# Service — publish path (important)
+
+**The actual executable is one folder deeper than the publish root:**
+```
+QBSyncService\bin\Release\net8.0-windows\win-x64\publish\win-x64\
+                                                              ↑ THIS folder contains QBSyncService.exe
+```
+
+To publish: right-click `QBSyncService` in VS 2026 → Publish → Folder → self-contained, win-x64
+
+### C# Service — deploy via Andrew + FileZilla
+
+Andrew is the on-site IT contact. He transfers using FileZilla from the MCESleeperAgents Windows account.
+
+**Steps for Andrew:**
+1. `Stop-ScheduledTask -TaskName "QB Sync Service"` (Admin PowerShell)
+2. Log in as Windows user **MCESleeperAgents** (pw: `MCESA26!`)
+3. Open / restore FileZilla
+4. Reconnect (click Reconnect icon or File → Reconnect)
+5. **Right side** (remote/source): `/xfer/win-x64/publish/win-x64` ← one level IN from publish root
+6. **Left side** (local/dest): `C:\QBSyncService`
+7. Select all files on right → drag to left → Overwrite all
+8. Switch back to Administrator account
+9. `Start-ScheduledTask -TaskName "QB Sync Service"` (Admin PowerShell)
+
+Confirm: first log line should read `QB Sync Service started. Base poll: 60s.` (not the old `Poll interval:` format).
+
+### Remote access to QB machine
+Tailscale + RDP. Tailscale installed on mcvmfarm2 and dev machine.
+- RDP command: `mstsc /v:100.112.16.19`
+- Login as: `mcvmfarm2\Administrator`
+- Note: RDP on Server 2016 opens a **new session** — QB Desktop on the console and your RDP session are separate windows
+
+## Current status (2026-04-14)
+
+### WordPress ✓
+- Plugin network-activated on `sleeperagents.wpengine.com` / `sleeperagents.org` ✓
+- REST API routes live ✓
+- Token set, heartbeat confirmed working ✓
+- Multisite constants confirmed in LIVE `wp-config.php` ✓
+- Phase tracking, abort button, live elapsed timer, auto-refresh (30s) all deployed ✓
+- `qbinv_service_phase` option added — no dbDelta needed (it's an option, not a column)
+
+### C# Service
+- Deployed to `C:\QBSyncService\` on `mcvmfarm2` ✓
+- Running under Task Scheduler as `mcvmfarm2\Administrator` ✓
+- **Latest build in progress** — 3-phase STA fix + phase tracking + abort + session timeout
+- Confirm new binary: first log line must say `Base poll:` not `Poll interval:`
+- If log still shows old format → Andrew transferred from wrong folder (`publish\` root instead of `publish\win-x64\`)
+
+### QB Desktop ✓
+- Running on mcvmfarm2 under Administrator account
+- Session 0 isolation resolved by switching to Task Scheduler
+- SDK permission approved (one-time dialog — done)
+
+### Task Scheduler
+- Task name: **"QB Sync Service"**
+- Runs as: `mcvmfarm2\Administrator` ("Run only when user is logged on")
+- Trigger: At logon for Administrator
+- Start: `Start-ScheduledTask -TaskName "QB Sync Service"`
+- Stop: `Stop-ScheduledTask -TaskName "QB Sync Service"`
+- **Critical**: task must run under the same Windows user that has QB Desktop open
+
+### Known code gap — QB response parser not yet exercised
+- `complete_action` in `REST.php` calls `QBInv_QBSync::parse_inventory_response($response)` for `ItemInventoryQueryRq` actions
+- Parser upserts into `wp_qbinv_parts` and `wp_qbinv_entries`
+- Has not been run against a real QB response yet — first successful sync will validate it
+
+### Client machine details
+- Machine: `mcvmfarm2` — Windows Server 2016, Hyper-V host
+- RDP login: `mcvmfarm2\Administrator`
+- Also available: `mcvmfarm2\MCESleeperAgent` (local admin) — FileZilla transfers only
+- Tailscale IP: `100.112.16.19`
+- Service binary: `C:\QBSyncService\QBSyncService.exe`
+- Logs: `C:\ProgramData\QBSyncService\logs\qbsync-YYYYMMDD.log`
+- QB company file dir: `C:\QuickBooks\` — if QB freezes, rename `<company>.TLG` → `.TLG.bak` and reopen
+
+### On-site infrastructure (MidCoast Engines location)
+- **Lantronix device server** — on local LAN, exposes AIS box serial port as raw TCP socket on port `10001`
+  - Connect via: `nc <lantronix-ip> 10001` — streams NMEA 0183 AIS sentences directly
+  - No Lantronix CPR software needed for Linux/TCP
+- **Linux box** — on-site, running a webserver, on same LAN
+  - Plan: install Tailscale, use as persistent AIS reader
+  - Install Tailscale: `curl -fsSL https://tailscale.com/install.sh | sh && sudo tailscale up`
+- **AIS data format**: NMEA 0183 (`!AIVDM` = other vessels, `!AIVDO` = own vessel) — needs decoder like `gpsd`
+- **IDEC RJ1S-CL-D12 relay** — 12V DC coil, plug-in style. No reset switch — replace if failed (~$10-15)
+
+## Diagnosing service issues
+
+- Run EXE directly for console output: `C:\QBSyncService\QBSyncService.exe`
+- Check logs: `C:\ProgramData\QBSyncService\logs\qbsync-YYYYMMDD.log`
+- QB frozen: rename `C:\QuickBooks\<company>.TLG` → `.TLG.bak`, reopen QB
+- Task not starting: Task Scheduler → right-click → Run → check Last Run Result
+- Wrong binary deployed: check log first line — must say `Base poll:` not `Poll interval:`
+- Service appears stuck: use **Abort** button in WP Admin → QB Sync Queue; flag picked up within 60s
+
+## Pending / future work
+- **First successful sync** — confirm `ItemInventoryQueryRq` goes pending→processing→done and parts table populates
+- **Reset & Re-Import** — after successful sync, flush bad CSV data with "Reset & Re-Import from QB"
+- **QB auto-launch on Administrator login** — Task Scheduler task to open QB Desktop on login so it survives reboots
+- **AIS integration** — Linux box reads Lantronix TCP → gpsd → decoded vessel JSON
+- **Auto-start hardening** — verify QB Desktop, service, and Tailscale all survive cold power cycle

SA-orchestration MD/Archvie/MidCoast/DEPLOY.md

@@ -0,0 +1,128 @@
+# QB Sync — Deploy Instructions (for Mark)
+
+You publish two things: **C# binaries** to WP Engine's uploads folder, and **PHP files** to the plugin directory. Andrew downloads one file from WP Engine and double-clicks it. That's the whole chain.
+
+---
+
+## One-time setup (first deploy only)
+
+On WP Engine, create this folder so the installer has a download target:
+```
+/wp-content/uploads/qbsync/
+```
+
+Via WP Engine's SFTP/SSH, or the WP Engine file manager. Make sure it's web-reachable — test by browsing to:
+```
+https://sleeperagents.org/wp-content/uploads/qbsync/
+```
+You should get a directory listing or a 403 (either is fine; a 404 means the folder isn't there).
+
+---
+
+## Compile
+
+In VS 2026 on the laptop:
+
+1. **Publish QBSyncService**
+   - Right-click `QBSyncService` project → **Publish** → **Folder**
+   - Target: `bin\Release\net8.0-windows\win-x64\publish\win-x64\`
+   - Configuration: `Release | win-x64`
+   - Deployment mode: **Self-contained**
+   - File publish options: **Produce single file** ✓ / **Enable ReadyToRun** (optional, faster startup)
+   - Publish
+   - Expected output: one file `QBSyncService.exe` (~70 MB)
+
+2. **Publish QBSyncUpdater**
+   - Right-click `QBSyncUpdater` project → **Publish** → **Folder**
+   - Same settings as above
+   - Expected output: one file `QBSyncUpdater.exe` (~15 MB)
+
+---
+
+## Upload to WP Engine
+
+Upload **only these two files** to `/wp-content/uploads/qbsync/`:
+
+```
+QBSyncService.exe
+QBSyncUpdater.exe
+```
+
+You do NOT need to upload `appsettings.json` or `updater.json` — the installer generates them on Andrew's machine from his on-screen answers (baked defaults + any overrides he types).
+
+Verify both files are reachable:
+```
+https://sleeperagents.org/wp-content/uploads/qbsync/QBSyncService.exe
+https://sleeperagents.org/wp-content/uploads/qbsync/QBSyncUpdater.exe
+```
+Both should start downloading when clicked in a browser.
+
+---
+
+## Deploy PHP changes
+
+Via SFTP to WP Engine, upload the changed plugin files:
+
+```
+lib/REST.php        (adds /sync/restart, restart_requested, updater update channel)
+lib/QBSync.php      (iterator back, no OwnerID)
+```
+
+After upload:
+- WP Admin → Settings → Permalinks → Save (flushes the REST route cache so `/sync/restart` is live)
+- Purge WP Engine page cache
+
+Verify the new endpoint exists (should return 401 without a token — that's good, means the route registered):
+```
+curl -X POST https://sleeperagents.org/wp-json/qbinv/v1/sync/restart
+```
+
+---
+
+## Get the token to Andrew
+
+The installer needs the API token (value of the WP option `qbinv_sync_token`). You have two options:
+
+- **A. Email/SMS it to Andrew** — he types it in during install (one-time).
+- **B. Pre-bake it** — edit `QBSyncUpdater/InteractiveInstall.cs`, set `DefaultApiToken` to the real token, republish. Andrew just hits Enter through that prompt. Don't commit the token to git.
+
+Option B is smoother for Andrew. Option A keeps the token out of any binary that's sitting on WP Engine's public `/uploads/` folder.
+
+---
+
+## Send Andrew this link
+
+> Download and run this file on the QuickBooks machine:
+> https://sleeperagents.org/wp-content/uploads/qbsync/QBSyncUpdater.exe
+>
+> Detailed steps in INSTALL.md (also attached).
+
+That's it. Andrew gets ONE link. The installer handles everything else.
+
+---
+
+## After Andrew's install
+
+You should see within 60 seconds:
+
+- WP Admin → **QB Inventory → QB Sync** shows a green dot with a recent heartbeat
+- Service version `1.0.0.0`, host `MCVMFARM2`, QB: OK
+- **Two** scheduled tasks on the machine:
+  - `QB Sync Service` — the actual worker
+  - `QB Sync Updater` — the monitor/patcher
+
+From now on:
+- Click **Restart** in WP Admin → updater cycles the service within 30s
+- Push a new `QBSyncService.exe` to `/wp-content/uploads/qbsync/` and set `qbinv_update_available=true` + `qbinv_update_url` → updater downloads it and swaps it in on its next poll. No FileZilla. No Andrew.
+- Same channel works in reverse for the updater itself via `qbinv_updater_update_*` options.
+
+---
+
+## Rolling back
+
+If the new updater misbehaves, SSH to WP Engine and replace `QBSyncUpdater.exe` with the previous known-good copy. On the QB machine, the **running** updater won't notice (it already loaded) — you'd need Andrew to re-run the installer. Keep a backup copy of each published version in a dated subfolder:
+
+```
+/wp-content/uploads/qbsync/archive/2026-04-21/QBSyncUpdater.exe
+/wp-content/uploads/qbsync/archive/2026-04-21/QBSyncService.exe
+```

SA-orchestration MD/Archvie/MidCoast/INSTALL.md

@@ -0,0 +1,161 @@
+# QB Sync — Installation (for Andrew)
+
+**What this is:** A small background service that lets MidCoast Engines' WordPress site read and update QuickBooks inventory automatically. Once installed it starts itself at logon and stays out of the way — you'll see a small icon in the system tray when it's running.
+
+**What you'll do:** Download one file. Run it. Click through a short setup window. Check for a tray icon. Done.
+
+**Time required:** About 90 seconds.
+
+---
+
+## 1. Download
+
+Open this link in any browser on the QuickBooks machine (`mcvmfarm2`):
+
+> https://sleeperagents.org/wp-content/uploads/qbsync/QBSyncUpdater.exe
+
+Save the file anywhere — Desktop is fine. It's about 20 MB.
+
+---
+
+## 2. Run it as administrator
+
+Find the downloaded `QBSyncUpdater.exe`.
+
+**Right-click → Run as administrator.**
+
+Windows will show a UAC prompt ("Do you want to allow this app to make changes?"). Click **Yes**.
+
+A window opens titled **"QB Sync — Installer"**. This is the only screen you'll interact with.
+
+---
+
+## 3. Review the setup window
+
+The window has three sections before you click Install:
+
+### Environment (top)
+Read-only info the installer detected about your machine. Confirms:
+- **Machine / Windows user** — should say `MCVMFARM2` and `MCVMFARM2\Administrator`.
+- **Admin rights** — should be green ✓.
+- **QuickBooks SDK** — if green ✓, you're ready. If red ✗ with an **Install SDK now** button, click that button *before* clicking Install. It auto-downloads and silently installs the Intuit SDK (takes 1–2 minutes).
+- **QB company file** — shows what it detected in `C:\QuickBooks\`. Informational only.
+
+### Configuration (middle)
+Three fields, mostly pre-filled:
+- **WordPress URL** — already set to `https://sleeperagents.org/`. Leave alone.
+- **API token** — either pre-filled or blank. **If blank, Mark will send you the value to paste in.** It's a long random string — paste exactly, no spaces.
+- **QB company file** — leave blank (auto-detects whatever QB has open).
+
+There's a **Test Connection** button next to the token field. Click it *before* installing to confirm WordPress accepts your token. You should see a green "Token accepted" line in the log area at the bottom. If you see red, double-check the token with Mark before proceeding.
+
+### Install button (bottom)
+Click **Install**. Progress bar and status log fill in:
+
+```
+✓ Existing tasks stopped
+✓ Service downloaded (70 MB)
+✓ Updater copied to C:\QBSyncService\QBSyncUpdater.exe
+✓ Wrote appsettings.json
+✓ Wrote updater.json
+✓ Registered "QB Sync Updater"
+✓ Registered "QB Sync Service"
+✓ Started "QB Sync Updater"
+✓ Started "QB Sync Service"
+✓ Reached https://sleeperagents.org/wp-json/qbinv/v1/sync/config — token accepted.
+
+════  Installation complete and verified.  ════
+```
+
+When you see **"Installation complete and verified"**, click **Close**.
+
+---
+
+## 4. Find the tray icon
+
+Within ~30 seconds of install, a small circle icon should appear in your system tray (bottom-right corner, near the clock).
+
+- **Green** ✓ — everything healthy.
+- **Amber** — WordPress has work queued; the service is about to act on it.
+- **Red** ✗ — something's wrong. Hover for details.
+- **Grey** — starting up / missing config.
+
+### Windows 11: pin the icon so it stays visible
+
+On Windows 11, new tray icons hide behind the ⌃ chevron by default. To pin it:
+
+1. Click the ⌃ chevron (shows hidden icons).
+2. **Drag the QB Sync circle icon** from the overflow panel down into the visible tray area.
+3. Release. It now stays visible permanently.
+
+### Windows 10 / Server 2016
+
+Usually visible immediately. If not, right-click the taskbar → Taskbar settings → scroll to *Notification area* → *Select which icons appear on the taskbar* → turn on **QB Sync**.
+
+---
+
+## 5. Test the tray icon
+
+Right-click the tray icon. You should see this menu:
+
+```
+QB Sync — Last poll: 12s ago
+────────────────────
+Open Status Window…
+Open Admin in Browser
+Open Log Folder
+────────────────────
+Restart Service
+Force Config Poll Now
+────────────────────
+Exit
+```
+
+**Double-click the tray icon** to open the Status Window. Confirm it shows:
+- Green dot + "Service is healthy"
+- "Last WP poll: Ns ago" (updating every second)
+- QB SDK: ✓ COM ProgID present
+- Log tail scrolling at the bottom
+
+If all that looks good, close the Status Window (it hides back to the tray — the service keeps running) and you're done.
+
+---
+
+## That's it
+
+Nothing else to do. The service runs automatically from now on, including after reboots (as long as Administrator logs in).
+
+You won't need FileZilla for this service again — Mark can push updates from WordPress and the service installs them itself on its next poll.
+
+---
+
+## If something doesn't look right
+
+**No tray icon after install:**
+- Open Task Scheduler (Start → type "Task Scheduler"). Look for two tasks: `QB Sync Service` and `QB Sync Updater`. Both should show "Running" status.
+- If they say "Ready" instead, right-click each one → Run.
+- On Windows 11 check the ⌃ chevron (step 4 above).
+
+**Red dot after install:**
+- Right-click tray → **Open Status Window**. Read the "Last WP error" line — that's the specific problem.
+- Most common: token mismatch. Right-click tray → Exit, re-run installer, pay close attention to the token field.
+
+**"Installation complete, connection not verified":**
+- The install still worked — just the token was wrong or WP was unreachable.
+- Either re-run the installer with the corrected token, or edit these files directly and restart the tasks:
+  - `C:\QBSyncService\appsettings.json`
+  - `C:\QBSyncService\updater.json`
+
+**Send Mark a screenshot** of the Status Window (or the install log area) if anything looks off — it tells us exactly which step failed.
+
+---
+
+## If you need to uninstall
+
+Right-click the tray icon → Exit. Then from an Administrator Command Prompt:
+
+```
+C:\QBSyncService\QBSyncUpdater.exe --uninstall
+```
+
+Both scheduled tasks are removed and `C:\QBSyncService\` is deleted. Logs in `C:\ProgramData\QBSyncService\logs\` are left behind for reference.

SA-orchestration MD/Archvie/MidCoast/README.md

@@ -0,0 +1 @@
+# MidCoastEngines

SA-orchestration MD/Archvie/sa-core/README.md

@@ -0,0 +1,185 @@
+# Core
+
+The required substrate of the SleeperAgent framework.
+
+A space is a SleeperAgent space only if Core is online underneath it. Everything above Core is **manufactured processing** — subsystems built on top of Core's primitive set. The primitive set is closed; subsystems extend the framework by composition, not by adding new primitives.
+
+Core is a WordPress plugin. It ships as `sa-core` on disk. It is the unified package into which every prior Sleeper Agents subsystem (`sleeperagent/`, `saws_plugin/`, `CMP_JNO/`, `sleeperagents-svg-chat/`, `sleeperagents-svg-workspace/`, `sleeperagents-organizations/`, `sa-jira-bridge/`, `take2/`, `carma-audit/`) absorbs over time.
+
+## What Core provides
+
+- **Primitive layer** — the closed set of shapes the field is built from: Entity, Edge, InfluenceRing, Membrane, IOPort, ACL, GroupingOverlay.
+- **Orchestration** — SubTokenEvent (every internal step visible to the billing principal), GeodesicMarker + GeodesicSeeder (memory of known-failure paths, pre-prompt seeding around them), StructuralAudit (time-indexed readout of attributed acts).
+- **Billing** — PricingPolicy (decomposed cost calculation), CredentialPool (multi-tenant encrypted credentials), TokenLedger (immutable, settlement-ready).
+- **Packaging** — Capability registry, Package, PackageAssignment (binds package to org/subdomain over time), CapabilityGate (the runtime yes/no with audited denials), SiteProvisioner (in-site activation handler for WPEngine clones).
+- **Operating memory** — `SA_Operating_Memory` ingests filesystem trees (repo → folder → file → class/function/heading → method/paragraph → line) as entities at bands 0–5. `SA_Doc_Lens` parses markdown; `SA_Code_Lens` parses PHP via `token_get_all` (no execution). Self-hosting (Pillar 0.9): our own `.md` and `.php` files are navigable as first-class entities.
+- **Adapter contract** — `SA_Provider_Adapter` interface. `SA_Dummy_Adapter` is the reference implementation and conformance anchor.
+
+## Subsystem posture
+
+Subsystems sit on a spectrum from *manual mirror* to *discernment*:
+
+- **Manual mirror** — records what the user does, reflects it back, lets them manually re-apply. Low ambition, low risk.
+- **Discernment** — infers what the user means, proposes a default path, asks the user to tune small corrections. High ambition, higher value.
+
+Core biases every subsystem toward discernment. Given the right contextual knowledge, the human's role is **tuning perception**, not operating tools. The machine simulates perception across the spectrum; the human corrects the simulation through small, audited adjustments.
+
+Core itself is neither; Core is the substrate. Discernment is expressed by subsystems built above.
+
+## Status
+
+Alpha. Phase 2 Step 1 of 10.
+
+Delivered: schema + interfaces + primitive/orchestration/billing/packaging classes + reference dummy adapter + structural audit. Activating the plugin creates all `{wp_prefix}sa_*` tables idempotently via `dbDelta`.
+
+**Delivered in the second slice (executor + REST + admin UI):**
+
+- `SA_Provider_Registry` — adapter lookup with capability-flag selection (replaces the legacy binary routing).
+- `SA_Context_Piper` — LLM-mediated context selection via edge walk. Given a root entity, gathers neighbors, asks the LLM which are relevant (recorded as a `router` sub-token event), folds selected payloads into the prompt. This is the concrete "context piping via tree-grid" mechanism.
+- `SA_Executor` — end-to-end chain: `context piping → geodesic seeding → adapter invocation → sub-token recording → parent + response entities → edges → token ledger → structural audit`.
+- REST routes at `/wp-json/sa-core/v1/`:
+  - `POST /prompt` — run a prompt (optional `root_entity_id` enables context piping).
+  - `GET /prompt/{id}/trace` — full sub-token graph for a prompt.
+  - `POST /subtoken/{id}/verdict` — mark good/bad (bad auto-seeds a geodesic marker).
+  - `GET /memory?path=...` — resolve a path expression to an entity.
+  - `POST /memory/ingest` — run `ingest_root` (admin only).
+- WP admin page *SA Core → Chat* with textarea, optional root-entity input, sub-token trace, and per-step verdict buttons.
+
+**Not yet delivered:**
+
+- Presentation layer (zoom-quantum engine, circle primitive, halo renderer, perspective projection). Build order Step 2.
+- Migration from the legacy `saws_prompts` / `saws_sessions` tables into `sa_entity` + `sa_token_ledger`. Build order Step 4, Triage item 1.
+- WPEngine clone-and-route API client. `SA_Site_Provisioner::activate_site()` picks up *after* WPEngine has cloned the template and routed the subdomain.
+- Live provider adapters (OpenAI, Anthropic, Gemini, local) beyond the dummy. Build order Step 8.
+
+## Install
+
+1. Drop the `sa-core/` directory into `wp-content/plugins/` on the target WordPress site.
+2. Activate *Sleeper Agents Core* in wp-admin.
+3. All tables with prefix `{wp_prefix}sa_*` are created idempotently.
+4. Safe to activate alongside existing Sleeper Agents plugins. No name collisions, no admin menus (yet), no REST routes (yet).
+
+Requires PHP 8.1+ and WordPress 6.3+. Production deployments should install libsodium (the CredentialPool falls back to AES-256-CBC via OpenSSL if sodium is absent; the fallback works but is not production-grade).
+
+## Database tables
+
+All prefixed `{wp_prefix}sa_`:
+
+| Table | Role |
+|---|---|
+| `entity` | Universal unit of the field |
+| `edge` | Typed, weighted, band-gated relationships |
+| `influence_ring` | Concentric sphere-of-influence bands |
+| `membrane` | Per-entity veils |
+| `io_port` | Typed anchors on membraned entities |
+| `acl` | Per-entity access control, four axes |
+| `grouping_overlay` | Attributed, non-destructive re-parentings |
+| `subtoken_event` | Every internal orchestration step |
+| `geodesic_marker` | Known-failure memory |
+| `structural_audit` | Time-indexed readout of attributed acts |
+| `pricing_policy` | Per-org/provider/model cost policy |
+| `credential_pool` | Multi-tenant encrypted credentials |
+| `token_ledger` | Immutable, cost-decomposed, settlement-ready |
+| `package` | Purchased SKU with enumerated capabilities |
+| `package_assignment` | Binds a package to an org (subdomain) over time |
+| `capability` | Enumerable, per-subsystem permission strings |
+
+## Layout
+
+```
+sa-core/
+├── sa-core.php                    # plugin header + hooks
+├── includes/
+│   ├── class-sa-core.php          # autoload + bootstrap
+│   ├── class-sa-migrations.php    # schema install for every Core table
+│   ├── interfaces/
+│   │   └── interface-provider-adapter.php
+│   ├── primitives/
+│   ├── orchestration/
+│   ├── billing/
+│   ├── packaging/
+│   ├── memory/
+│   │   ├── class-sa-operating-memory.php
+│   │   ├── class-sa-doc-lens.php
+│   │   └── class-sa-code-lens.php
+│   ├── executor/
+│   │   ├── class-sa-provider-registry.php
+│   │   ├── class-sa-context-piper.php
+│   │   └── class-sa-executor.php
+│   ├── rest/
+│   │   ├── class-sa-rest.php
+│   │   ├── class-sa-rest-prompt.php
+│   │   ├── class-sa-rest-verdict.php
+│   │   └── class-sa-rest-memory.php
+│   ├── admin/
+│   │   └── class-sa-admin.php
+│   └── adapters/
+│       └── class-sa-dummy-adapter.php
+├── templates/
+│   └── admin-chat.php
+├── assets/
+│   ├── admin-chat.css
+│   └── admin-chat.js
+├── docs/
+│   └── ARCHITECTURE.md            # the canonical spec
+├── LICENSE
+└── README.md
+```
+
+## Operating memory — map any .md or .php location to an entity
+
+Register a root once:
+
+```php
+SA_Operating_Memory::register_root('sa-core', SA_CORE_DIR);
+```
+
+Then resolve any location along the band hierarchy:
+
+```php
+// Band 0 — the repo root
+$repo = SA_Operating_Memory::view('sa-core/');
+
+// Band 1 — a folder
+$primitives = SA_Operating_Memory::view('sa-core/includes/primitives/');
+
+// Band 2 — a file
+$arch = SA_Operating_Memory::view('sa-core/docs/ARCHITECTURE.md');
+$ent  = SA_Operating_Memory::view('sa-core/includes/primitives/class-sa-entity.php');
+
+// Band 3 — a markdown heading or a PHP class
+$pillar0 = SA_Operating_Memory::view('sa-core/docs/ARCHITECTURE.md:Pillar 0');
+$class   = SA_Operating_Memory::view('sa-core/includes/primitives/class-sa-entity.php:SA_Entity');
+
+// Band 4 — a sub-heading, a PHP method, or a PHP property
+$create    = SA_Operating_Memory::view('sa-core/includes/primitives/class-sa-entity.php:SA_Entity::create');
+$id_prop   = SA_Operating_Memory::view('sa-core/includes/primitives/class-sa-entity.php:SA_Entity::$id');
+$subhead   = SA_Operating_Memory::view('sa-core/docs/ARCHITECTURE.md:Canonical glossary::Entity');
+
+// Band 5 — a specific line
+$line_42   = SA_Operating_Memory::view('sa-core/includes/primitives/class-sa-entity.php#42');
+```
+
+Each `view()` call is idempotent and deterministic — the same expression always returns the same entity id (hash of the expression). Entities persist to `sa_entity` once viewed, so they can be annotated (verdict), wrapped (membrane), connected (edges), or re-parented (grouping overlay) like any other entity.
+
+For bulk ingestion to band 2 (file-level, one pass across the whole repo):
+
+```php
+SA_Operating_Memory::ingest_root('sa-core', [
+    'org_id'     => $org_id,
+    'created_by' => $user_id,
+]);
+```
+
+Band 3+ (classes, methods, headings) are materialized lazily on first `view()` to keep the ingestion cheap.
+
+## Deployment posture
+
+One WordPress site per customer on WPEngine, on its own subdomain. `sa-core` is activated on every provisioned site. `SA_Site_Provisioner::activate_site()` is the in-site activation handler called after WPEngine clones the template and routes the subdomain.
+
+Each subdomain maps to one `org_id`; `SA_Site_Provisioner::current_org_id()` resolves it. The active `SA_Package_Assignment` for that org determines which capabilities are enabled. `SA_Capability_Gate::allows()` is the runtime check every subsystem consults.
+
+## See also
+
+- `docs/ARCHITECTURE.md` — the canonical spec this plugin is built against.
+- The legacy working tree at `../ChatBot/` (private) — contains the pre-absorption subsystems that migrate into Core over Build order steps 4–7.

SA-orchestration MD/Archvie/sa-core/docs/specs/01-ontology.md

@@ -0,0 +1,281 @@
+# MissionNet Ontology (v0.1)
+
+*Implementation © Sleeper Agents LLC. Conceptual framework authored independently by Mark Holak; see `docs/specs/concepts/`.*
+
+This is the vocabulary lock. Every downstream doc, every class, every log message, and every UI surface uses these terms precisely. Drift here = drift everywhere.
+
+---
+
+## Primary nouns
+
+### Core
+
+The required substrate. One WordPress plugin (`sa-core`). A space is a SleeperAgent space only when Core is online underneath it.
+
+### Realm
+
+An externally sovereign system of record or operation. FluentCRM is a realm. Jira is a realm. QuickBase is a realm. QuickBooks is a realm. PortTracker's Node backend is a realm. An arbitrary REST API is a realm. A client's database is a realm. A realm is sovereign because its integrity does not depend on Core.
+
+### Subsystem
+
+A coherent slice of Core itself. SAWS-executor is a subsystem. CARMA (the absorbed WP maintenance toolset) is a subsystem. MissionNet (the presentation layer) is a subsystem. A customer-facing brand may wrap a subsystem; the brand is cosmetic, the subsystem is structural.
+
+### Adapter
+
+A bidirectional conduit between Core and a realm. See the **Realm Adapter Contract** (`03-realm-adapter-contract.md`). Adapters do not own realm data; they mediate flow. A provider adapter (`SA_Provider_Adapter`) is a specialized adapter for LLM and tool providers; a realm adapter (`SA_Realm_Adapter`) is the general-case conduit.
+
+### Entity
+
+The universal unit of the field inside Core. Rendered as circle (compressed atom) or rounded-rect (expanded container). Carries band hints, ratio, position, payload, ACL, provenance, and truth class.
+
+### Record
+
+A specific row in a realm's native schema. A record's canonical home is the realm. A record's Core-side reflection is a **Projection**.
+
+### Projection
+
+Core's non-canonical mirror of a realm record. Stored as an entity with `truth_class = projected`, `origin_realm` + `origin_id` populated, and TTL-bounded when cached.
+
+### Canonical Source
+
+The realm in which a record is authoritative. Only the canonical source may author canonical state for its own records. Core cannot author canonical on a realm's behalf.
+
+### Event
+
+Something that happened. Immutable, time-indexed. Recorded to `sa_structural_audit` with actor, target, before/after, correlation_id, causation_id, policy_basis.
+
+### Command
+
+An instruction or intent. Typically initiated by an actor or a scheduled policy. A command may yield one or more events when executed.
+
+### Actor
+
+The who of an action. One of: a WordPress user id (human), a service principal id (non-human authenticated identity), or the string `system` (Core's own internal automation under an audited policy).
+
+### Authority
+
+The scope of what an actor may do. Held by role, package capabilities, ACL entries, and adapter capability matrices.
+
+### Session
+
+A grouping of related commands and events initiated by a single actor or chain. Correlated by a shared `correlation_id`.
+
+### Mission
+
+A composite objective that spans one or more sessions. (Future spec — see `10-mission-orchestration.md` when written.)
+
+### Quest
+
+A unit of narrative direction. Defines target, not-target, and admissible uncertainty for a body of work. Quests are authored, not executed: their canonical home is the planning surface (Boards in MissionNet's instance).
+
+Quests describe what the work is *about*. Resolution of a Quest is a narrative judgment — was the direction met, was it abandoned, was it superseded — made by a human.
+
+Distinct from a Job. See Job below; see also Distinguishing pairs.
+
+### Task / Job
+
+A unit of executable work within a Quest. May be scheduled, assigned, retried, or delegated. Jobs describe what is *done*. Resolution of a Job is a real-world consequence — the work either happened or did not — measured against reality, not against the system.
+
+A Quest may produce one or more Jobs. A Job belongs to one Quest. Conversion between Quest and Job is not automatic; see I10.
+
+### Attention
+
+A routing signal — never an instruction, never a state mutation. Attention asks for arbitration; it does not perform it. NPCs (agents, automated processes) may emit Attention. Only humans may resolve it.
+
+The infrastructure: the attention log records signals with actor, target, correlation_id, causation_id. Read-only by construction; resolving Attention requires the human to take a separate, explicit act.
+
+Sub-doctrine: see `concepts/attention-doctrine.md` and `concepts/compass-doctrine.md`.
+
+### Realm Signal
+
+A low-cost notification from a realm ("something changed") that Core may choose to consume, queue, or ignore based on policy. Previously named "Signal"; renamed to free the unqualified term for the doctrinal meaning below.
+
+### Signal
+
+*(Authored by Mark Holak. Preserved under Invariant **I9**.)*
+
+The measurable alignment behavior of participants — users, workers, agents, models, systems — as they traverse an authored **acceleration field** (a mission, prompt, workflow, book, interface, instruction set, or any artifact that defines target, not-target, and admissible uncertainty).
+
+Signal is *not* raw observability. Pillar 0.75's sub-token graph is the instrument; Signal is what the instrument reads. Participants interact with an authored field and produce measurable interaction outcomes — some align, some scatter, some ricochet, some go inert, some reach harmonic closure. The Signal Telemetry Doctrine is the interpretation layer sitting over Prime Prompt Conjecture and Cognitive Heatsink: PPC and Heatsink describe how trajectory is compressed and dissipated; Signal reads the alignment produced at the other end.
+
+The enumerated behaviors (align / scatter / ricochet / inert / harmonic closure) are **exemplary, not definitive** — additional behaviors may emerge as the system is used. See `concepts/signal-telemetry-doctrine.md` for the full doctrine and its mapping onto Core primitives.
+
+### Artifact
+
+A file, document, image, or embedding. Stored in the native realm when possible; projected into Core via adapter.
+
+### Trace
+
+The causal ancestry of a state or an event. Walked by `SA_Structural_Audit::trace_origin()`. Preserved by correlation_id and causation_id on every audit row.
+
+### Truth Class
+
+See `SA_Truth_Class` and Invariant **I2**. One of: `canonical | projected | cached | inferred | derived | synthetic`. Every entity declares one.
+
+### State Class
+
+See `SA_State_Class`. The lifecycle position of a datum. One of: `resting | observed | projected | pending_action | acted | verified | disputed | stale | superseded`.
+
+### Provenance
+
+The origin record attached to every entity: `origin_realm`, `origin_id`, `actor`, `observed_at`, `causation_id`, `correlation_id`, optional `derived_from`, `source_refs`, `provenance_hash`.
+
+### Membrane
+
+A per-entity veil that turns the entity into a black-box domain. Only typed I/O ports are visible to outsiders. Billing principals may unfold the membrane they are charged for.
+
+### I/O Port
+
+A typed edge anchor on a membraned entity. The only integration surface visible to non-insiders.
+
+### Grouping Overlay
+
+A first-class attributed, non-destructive re-parenting of entities. Per-scope (private / shared / org / public), per-author. Applied at render time.
+
+### Projection Slot
+
+A named rendering surface bound to an entity query. A package defines its slot set; a viewer may override within the slot's allowance.
+
+### Projection Source
+
+A named, viewer-scoped row producer eligible to be unioned with other sources at a surface's Projection Arbiter. Each source owns one query path and applies its own visibility gate (`row_visible`) before returning rows. A source is NOT any method on `SA_Projection`; it is specifically a row producer composable into a surface's arbiter. Today's sources: `chat` (`recent_prompts` — chat-domain-joined) and `realm` (`recent_entities` — role/origin-realm-scoped). Sources are kernel-owned; third parties contribute realm adapters (which feed `realm`), not sources.
+
+### Projection Arbiter
+
+A surface-scoped composer that enumerates the Projection Sources feeding that surface, invokes them for the current viewer, and unions their output into the surface's response shape. The arbiter owns source enumeration, union strategy, and per-source instrumentation (`window.sources` readout). Today implemented as one method per surface on `SA_Projection` (`for_mission` is the only instance). Not a standalone class: at two sources with no arbitration rules (dedup, sort-merge, ACL-at-merge), a class would be ceremony. Promotion to a class is deferred until (a) a third source, (b) a concrete arbitration rule, or (c) third-party source registration lands. Surfaces with a single source (`/thread`, `/trace`, `/lattice/subtree`) do not go through an arbiter and do not need one.
+
+### Influence Halo / Ring
+
+Concentric bands around an entity carrying weighted references to related entities. The continuous limit of discrete rings is the contour mode (`docs/ARCHITECTURE.md` — Derived pillar: Contour rendering).
+
+### Sub-Token Event
+
+Every internal orchestration step inside a provider invocation (embed, retrieve, tool call, subagent hop, completion, rerank, self-critique, router). First-class entity at band 5 inside the parent prompt's band 4 container. Visible and annotatable by the billing principal.
+
+### Geodesic Marker
+
+A memory record of a failure path in the prompt manifold. Seeded from bad verdicts on sub-tokens. Consumed by `SA_Geodesic_Seeder` to route around known failures.
+
+### Context Bundle
+
+A named, pinned slice of the entity graph with a deterministic signature. Multiple adapters (including specialized LLMs) bind to the same bundle for synchronized context.
+
+### Package
+
+The purchased SKU. Enumerates enabled capabilities, default overlays, default membranes. Assigned to an org.
+
+### Capability
+
+An enumerable permission string (`sa-core:sub-token-unfold`, `missionnet:impose-grouping`, `carma:admin-takeover`). Package-gated.
+
+### Service Principal
+
+A non-human authenticated identity. External services (PortTracker's Node, ingest clients, Jira bots) use service principal tokens to push mutations without impersonating a user.
+
+### Invariant
+
+A non-negotiable law the system upholds at runtime. See `02-invariants.md`. Violations are logged to `sa_invariant_violation`.
+
+### Adapter Certification
+
+The gate that promotes a realm adapter from "in development" to "live." Checklist runs against the Realm Adapter Contract invariants. See `03-realm-adapter-contract.md`.
+
+### Admission Contract
+
+The per-layer contract a new primitive — or a new instance of an existing primitive — must honor to be validly admitted into the system.
+
+A *named principle*, not a uniform checklist family. The principle is: **admission is layer-owned and layer-shaped**, not uniform across layers. Each layer's admission contract takes whatever form that layer's nature demands (a certification checklist for realms, runtime invariants for entities, an op whitelist for mutations, a return-shape obligation for projection sources, etc.).
+
+This principle does not add a new commitment. It names a shape already diffused through:
+
+- **Pillar 0.5** — everything rendered is `project(field, viewer, overlays, permissions)`. A new primitive must have defined behavior under all four inputs.
+- **Pillar 0.75** — every orchestration step is observable. Anything action-shaped must declare how it emits observability (sub-token events, audit rows, source attribution).
+- **Pillar 0.9** — the primitive set is closed; new capabilities are compositions of existing primitives. Admission = proof of valid composition.
+- **`03-realm-adapter-contract.md`** — the single fully worked-out formal instance of a per-layer admission contract.
+
+See `docs/ARCHITECTURE.md` for the pillars themselves. This entry does not amend them; it gives the shape they imply a name.
+
+**Status ledger.** The ledger is the term's practical content. It records which primitive layers currently have formal contracts, which have informal ones, which are absent, and which are intentionally deferred. New rows enter only when a new primitive layer enters the closed set — not per instance, and not per cross-layer attribute.
+
+| Layer | Contract state | Reference / note |
+|---|---|---|
+| Realm | Formal | `03-realm-adapter-contract.md` + `sa_adapter_certification` table |
+| Entity | Formal | `02-invariants.md` I2 / I4 / I7 + `SA_Truth_Class` / `SA_State_Class` validation in `SA_Entity::create` |
+| Mutation | Formal | `SA_Ingest` op whitelist, idempotency-key discipline, service-principal scope, deterministic UUID rule |
+| Projection Source | Informal | "Returns viewer-gated rows in arbiter-compatible union shape." Implied by the Projection Arbiter promotion; not yet written as a standalone contract. |
+| Grammar | Absent | No admission rules for a new grammar today. Chat-lineage / equal-peer / containment-pack are ad-hoc in client code. |
+| Surface inspection | Informal | Three discriminable cases now operative in `/mission/`'s lens-routing decision (`renderCurrentProjection` in `assets/mission.js`), driven by a shape predicate over `(entity.origin_realm, sub_token_count)` — no realm-specific code: (a) **chat-shaped** (`!origin_realm`) → trace lens; (b) **structural-only** (`origin_realm` set, `sub_token_count == 0`) → structural inspector; (c) **structural-with-sub-tokens** (`origin_realm` set, `sub_token_count > 0`) → hybrid lens (structural inspector + Sub-tokens section in step_index ASC order, with shape-aware labels read from `SubTokenEvent.metadata` rather than chat-shaped fallbacks). Discriminator field `sub_token_count` lives on the `/entity/{id}/inspect` projection response (additive, no schema change). Concrete instances: chat prompts (case a), FS containers/leaves (case b), GitHub Actions workflow runs (case c). Promotion to Formal (separate contract file) requires a fourth case or a second concrete hybrid example, whichever forces the discriminator's edge cases into a written rule. Until then the contract is the inline behavior recorded here. |
+| Toolbox action | Formal | `06-toolbox-action-contract.md` (v0.1, 7 clauses). Two concrete instances: `/mission/`-native "Re-scan FS" and "Re-scan GH" buttons (both admin-only). Promotion criteria from Informal → Formal were satisfied by the second instance (GitHub Actions re-scan) cleanly fitting the same seven-clause shape: semantic binding (1 button → 1 REST endpoint), permission gate (manage_options at template AND REST), audit obligation (one operator-attribution structural-audit row per invocation), parameter shape (render-time derivation, no click-time dialogs), feedback contract (busy/success/failed state cycle), refresh obligation (`load()` on success), idempotency (zero net entity-count drift on repeat). Out-of-scope categories (parameter dialogs, destructive actions, multi-step compositions) explicitly deferred to future contract revisions when concrete instances drive them. |
+| Membrane | Deferred | Primitive defined in this ontology; admission contract (port typing, opacity rules, billing-principal translucency) deferred until first implementation. |
+| Overlay | Deferred | Primitive defined in this ontology; admission contract (scope, attribution, idempotency, render-time layering) deferred until first implementation. |
+| Credential | Deferred | Surfaced by the GitHub Actions third-domain proof, which uses a filter-driven PAT (`sa_core_github_token`) as its smallest scope-honoring credential path. The general contract — how external-realm credentials enter the system (OAuth flows, refresh-token lifecycle, per-user vs per-org binding, scope-limited storage) — is not yet written. Existing primitives partially cover adjacent concerns: `SA_Credential_Pool` (LLM provider keys, single-secret-per-record), `SA_Service_Principal` (inbound bearer tokens), filter-driven adapter config (FS, GitHub Actions). None compose into a unified credential-admission shape. Authorized work will likely extend `SA_Credential_Pool` to handle multi-step OAuth tokens and add the operator UX (connect, store, scope, retire) as one slice's deliverable, then retire ad-hoc filter configs. First instance: GitHub. Second instance later: Jira / Linear / etc. |
+| Camera-Projection Convergence | Pinned | Filed during the dependency audit preceding the Hybrid Inspector Lens slice. Concept: under Pillar 0's full vision, camera transitions at band boundaries are themselves projection-resolution events, not viewport transforms. Today the camera is degenerate (purely affine pan/zoom over fixed layout). Under Rung 4 phase 2+, zoom-band crossings re-layout via auto-compress / auto-expand, making camera a constrained re-projection over the referential manifold rather than a viewport adjustment. Concrete formalization deferred until a second example of camera-as-projection lands alongside Jump-2 (auto-descend on band-cross) or Jump-3 (membrane unwrap on jump). At promotion time this row will move from Pinned to Absent or Informal depending on which Rung 4 mechanic delivers it. Sits at the same admission-contract layer as Surface Inspection / Toolbox / Grammar — between primitives and rendering. |
+
+**Role and kind are NOT admission layers.** They are cross-layer discriminant attributes. A new role's admission is governed jointly by entity invariants (structural constraints: e.g. `message` requires `payload.role ∈ {user,assistant,system}`), grammar admission (visual and inspection-lens treatment), and projection source contract (which sources include the role). No independent role-admission contract. `kind` (circle / rrect) is narrower still — a pure grammar discriminant with no invariant or projection overlap.
+
+**What this entry does NOT do.**
+
+- Does not mandate a uniform contract shape across layers. Forcing realm-style checklists onto grammars or toolbox actions is the principle's failure mode.
+- Does not create a runtime gate. Existing enforcement (invariants, certification table) stays as-is; no new machinery is implied.
+- Does not forbid introducing a primitive without a contract in place. Absent rows in the ledger are honest debt markers, not refusal signals.
+
+### Prime Prompt
+
+*(Authored by Mark Holak.)* A minimal causal prompt that, when injected into a capable model, reconstructs the trajectory of an originating system without requiring replay of the full conversation history. See `docs/specs/concepts/prime-prompt-conjecture.md`.
+
+### Cognitive Heatsink
+
+*(Authored by Mark Holak.)* A thermodynamic model of thought-to-resolution through computational dissipation. See `docs/specs/concepts/cognitive-heatsink.md`. Maps to sub-token events as discrete thermal transfer steps.
+
+### Reference Traversal Continuity
+
+*(Authored by Mark Holak. Preserved under Invariant **I9**.)*
+
+A kernel-level commitment that the act of following a reference from one entity to another is invariant across the kinds of entities being traversed and across the realm or representational layer the traversal currently inhabits. The traversal does not truncate at realm boundaries, truth-class boundaries, type-layer boundaries, or observability boundaries.
+
+Continuity is carried by the existing kernel-side bookkeeping (`parent_id`, `origin_realm` + `origin_id`, `correlation_id`, `causation_id`, `derived_from`, edge kinds, sub-token parentage). The doctrine names what those primitives jointly enable.
+
+This is a doctrine of **motion**, not of **geometry**. Projection grammars (chat-lineage, containment-pack, equal-peer, future grammars) are downstream rendering decisions that choose how to display a region of the traversal field; they neither define, constrain, nor constitute the traversal itself. Coil, hydra, shell, treemap, and every other rendered cluster shape are choreographies — many other choreographies are equally valid. The motion neither requires nor privileges any of them.
+
+Articulated immediately after the GitHub Actions third-domain proof, which made the cross-domain continuity concretely visible: chat sub-tokens, filesystem containment, and workflow run/job/step descents are not three patterns held together by the adapter contract; they are three surface expressions of one continuous motion that the adapter contract gates entries to. See `concepts/reference-traversal-continuity.md` for the full doctrine and its relationship to companion concepts (Pillar 0.5 perspective projection, Pillar 0.75 transparency, Pillar 0.9 closed primitive set, Prime Prompt Conjecture, Cognitive Heatsink, Signal Telemetry Doctrine).
+
+---
+
+## Distinguishing pairs (do not confuse)
+
+- **Realm** vs. **Subsystem** — realms are sovereign external systems; subsystems are parts of Core.
+- **Incorporate** vs. **Absorb** — realms are incorporated (conduit); SA-authored code is absorbed (consolidated).
+- **Event** vs. **Command** — events are records of what happened; commands are instructions or intents.
+- **Canonical** vs. **Projected** — canonical is truth at its native home; projected is Core's non-canonical mirror.
+- **Projected** vs. **Cached** — both are non-canonical; cached carries an explicit TTL; projected is kept live and refreshable.
+- **Inferred** vs. **Derived** — inferred is produced by an LLM or heuristic; derived is deterministic computation from known inputs.
+- **Entity** vs. **Record** — an entity lives in Core; a record lives in a realm; a projection is an entity that *represents* a record.
+- **Projection** (the mirror) vs. **Projection Source** vs. **Projection Arbiter** vs. **Projection Slot** — four distinct read-path concepts that share a word. *Projection* (the mirror) is the entity-side reflection of a realm record (truth-class level). *Projection Source* is a viewer-scoped row producer (read-path composition level). *Projection Arbiter* is the surface-scoped composer of sources (read-path orchestration level). *Projection Slot* is a named rendering surface bound to a query (rendering level). The four do not substitute for each other.
+- **Quest** vs. **Job** — quests are narrative direction (authored, judged); jobs are executable work (scheduled, performed, resolved by reality). One quest may yield many jobs; no automatic promotion in either direction. See I10.
+
+---
+
+## Usage rules
+
+1. Every spec document MUST use these terms in their defined sense.
+2. When a new term enters the vocabulary, it MUST be added here before being used in other specs or in code.
+3. Class names and log messages SHOULD mirror these terms.
+4. When translation between Core's vocabulary and a realm's native vocabulary is necessary, it happens in the adapter, not in the spec.
+
+---
+
+## Attribution
+
+The framework expressed in this document sits inside a larger lineage:
+
+```
+CR ⊇ CA ⊇ JourneySeeker ⊇ MissionNet/MeshNet ⊇ SA-Orchestration ⊇ Brand ⊇ Client
+```
+
+Causal Relativity, Causal Agentics, and JourneySeeker are pre-existing intellectual property authored by Mark Holak, preserved under Invariant **I9** and Section 5.1 carve-outs of the CTO Employment & Equity Agreement. MissionNet/MeshNet is the Corporate-Campaign theme. SA-Orchestration is the current implementation slice. Brand and Client labels are the rendering layer (see `concepts/concept-vs-label.md`).
+
+Each layer below renders, specializes, or themes the layer above. No layer below replaces the layer above. See `concepts/lineage-chain.md` for the full doctrine.
+
+Implementation and glossary in this document: © Sleeper Agents LLC.
+
+Named conceptual framework elements (Prime Prompt, Cognitive Heatsink, Russell-Ouroboros Conjecture, PR notation, quanta-of-LLMs / information-lattice framing): authored independently by Mark Holak. See `docs/specs/concepts/` for the preserved artifacts and full author credit.

SA-orchestration MD/Archvie/sa-core/docs/specs/02-invariants.md

@@ -0,0 +1,180 @@
+# MissionNet System Invariants (v0.1)
+
+*Authored by Mark Holak. Adapted into Core by implementation.*
+
+These are not implementation details. They are **laws**. Violations are recorded to `sa_invariant_violation`; severe violations raise exceptions. Code that violates an invariant fails review.
+
+The enforcement surface lives in `includes/enforcement/class-sa-invariants.php`. Every invariant here has a stable id (`I1`–`I9`) used in the violation log. A bug tracker can link against these ids.
+
+---
+
+## Foundational asymmetry
+
+The invariants below exist because Core distinguishes between truth classes: **canonical, projected, cached, inferred, derived, synthetic**. These classes are asymmetric — they cannot collapse into each other. That asymmetry is what prevents Russell's paradox from re-entering through the back door: a system that consumes itself can only stay coherent if the act of consumption preserves distinctions as it moves. The timeless lattice translates through spacetime precisely because the asymmetry survives the motion.
+
+Without these invariants, the asymmetry decays, the classes collapse, and the system begins to lie to itself about what is real.
+
+---
+
+## I1 — Core must not claim canonical ownership of incorporated realm data
+
+Incorporated realms (FluentCRM, Jira, QuickBase, QuickBooks, PortTracker's Node service, arbitrary APIs) remain the canonical source of their own records. Core mirrors, mediates, and audits — never authors canonical state on a realm's behalf unless that realm is Core itself.
+
+**Enforcement:**
+- `SA_Ingest::upsert_entity` stamps `truth_class = projected` by default on all ingested realm records.
+- A realm adapter's `truth_class_for_concept()` may *only* return `canonical` for concepts whose canonical home is Core (rare).
+- Any attempt to write `truth_class = canonical` on an entity with a non-`sa-core` `origin_realm` is rejected.
+
+**Violation severity:** fatal.
+
+---
+
+## I2 — Every surfaced datum must declare truth_class
+
+Entities, projections, cache rows, AI summaries, and adapter payloads must carry a valid `truth_class`. Without this, viewers cannot distinguish a canonical fact from an LLM guess.
+
+**Enforcement:**
+- `SA_Entity::create()` calls `SA_Invariants::check_truth_class_declared()`.
+- Default for unknowable-origin entities is `canonical`; default for ingest is `projected`; default for LLM output is `inferred`. All three are valid; absence of any value is not.
+
+**Violation severity:** fatal.
+
+---
+
+## I3 — Every cross-realm action must be causally traceable
+
+A change initiated in Core that reaches (or originated in) an external realm must trace to an actor, a causation id, and a correlation id. `SA_Structural_Audit::trace_origin()` must be able to walk backward from any resulting state to the first user-attributed act.
+
+**Enforcement:**
+- `SA_Provenance::enforce()` is called before any cross-realm mutation.
+- Audit rows carry `correlation_id` + `causation_id`.
+
+**Violation severity:** error (blocks the action; recoverable by retrying with provenance attached).
+
+---
+
+## I4 — No adapter may emit a record without native identity + realm provenance
+
+Adapter pulls MUST populate `origin_realm` + `origin_id` (directly or via `external_key`). Without this, the record cannot be re-matched, cannot be pushed back, and cannot be audited across the realm boundary.
+
+**Enforcement:**
+- `SA_Invariants::check_realm_provenance()` is called on every ingest mutation.
+- `SA_Ingest` rejects payloads missing these fields.
+
+**Violation severity:** fatal.
+
+---
+
+## I5 — MissionNet must degrade without corrupting realm integrity
+
+When Core fails (offline, bugged, under attack), the client's native realms must not suffer collateral damage. This is the philosophical *tool test* expressed as a technical law.
+
+**Enforcement:**
+- Adapter writes (`push`) must be idempotent per `idempotency_rules()`.
+- Bulk operations must be chunked + resumable.
+- Health-check endpoints must fail closed — Core not reachable means ingest halts, not silently half-writes.
+- Adapter certification checklist item: `failure_path_verified` + `rollback_defined`.
+
+**Violation severity:** warn at design time, error at runtime.
+
+---
+
+## I6 — Cache may never silently replace source verification in high-trust paths
+
+Cache accelerates; cache does not become truth. When the caller asks for a high-trust answer (regulated domains, financial totals, legal records), Core must re-verify against the canonical realm, not return a cached projection.
+
+**Enforcement:**
+- Per-adapter cache TTLs declared in `capability_matrix()`.
+- High-trust query paths pass `verify_live: true` to the executor/realm; cache is skipped.
+- A future policy engine may classify concepts as high-trust and force verification.
+
+**Violation severity:** error in high-trust contexts; warn otherwise.
+
+---
+
+## I7 — AI output must remain explicitly derivative
+
+No LLM output may be stored or surfaced as canonical truth without an explicit canonical source reference or a recorded human affirmation.
+
+**Enforcement:**
+- `SA_Executor` stamps completion entities with `truth_class = inferred`.
+- `SA_Entity::create()` calls `SA_Invariants::check_ai_output_not_canonical()`. Attempting to create an AI-sourced entity with `truth_class = canonical` without either `source_refs` (non-empty) or `human_affirmed_at`+`human_affirmed_by` is rejected.
+- Promotion from `inferred` → `canonical` or `projected` requires an explicit endpoint call (future work) that records the promoting actor + timestamp.
+
+**Violation severity:** fatal.
+
+---
+
+## I8 — Destroying Core must not destroy incorporated realms
+
+This is I5's strongest form. If Core is deleted tomorrow, FluentCRM still works, QuickBooks still works, Jira still works, PortTracker still works. Core owns no canonical realm data. Cache is non-canonical by construction. Push-backs are immediate, not batched into Core's own persistence.
+
+**Enforcement:**
+- Adapter certification checklist item: `source_identity_preserved` + `native_ids_preserved`.
+- Contractual, not just technical: the product terms explicitly disclaim any Core-only source of truth for realm concepts.
+- Periodic audit: `SA_Adapter_Certification` re-runs on each adapter release and the passed flag is visible to operators.
+
+**Violation severity:** fatal at certification; a failing adapter cannot go live.
+
+---
+
+## I9 — Attributable concepts and the framework lineage must not be rephrased as AI-original
+
+Both **named concepts** and **the framework lineage that contains them** must carry author attribution wherever surfaced.
+
+**Named concepts** (authored by a human and preserved verbatim under this invariant) include the Russell-Ouroboros Conjecture, the Prime Prompt Conjecture + PR notation, the Cognitive Heatsink model, the Signal Telemetry Doctrine, the Reference Traversal Continuity Doctrine, the Story Seed pattern, the Concept-vs-Label doctrine, the Compass Doctrine, the Attention Doctrine, the Quest-vs-Job distinction, and any subsequent attributable work added to `docs/specs/concepts/`.
+
+**The framework lineage** is the chain Causal Relativity ⊇ Causal Agentics ⊇ JourneySeeker ⊇ MissionNet/MeshNet ⊇ SA-Orchestration ⊇ Brand ⊇ Client (see `concepts/lineage-chain.md`). The structural primitives at each layer (truth class taxonomy, compass roles, description-as-contract, seed-vs-canonical, projection vs canonical, actor/realm/adapter, Quest/Job distinction) are framework primitives, not implementation primitives.
+
+AI-generated text that paraphrases or adapts either named concepts or framework primitives must reference the original author and must not present the concept as newly originated by the AI or by the implementation layer.
+
+**Enforcement:**
+
+- The spec pack under `docs/specs/` carries attribution frontmatter.
+- `docs/specs/concepts/` preserves the original authored artifacts verbatim with explicit author credit.
+- AI output passing through Core that draws on attributable concepts or framework primitives must reference them (adapter-level policy, future work).
+- Adapter certification: AI summarizers that produce text must not strip authored-concept attribution.
+- Seed generators must not synthesize content that re-authors framework primitives as implementation-original. INTERPRETIVE-mode synthesis is bound by this clause.
+
+**Violation severity:** warn at generation time; fatal at publication time.
+
+---
+
+## I10 — No automatic conversion between Quest and Job
+
+A Quest may not be promoted to a Job, and a Job may not be elevated to a Quest, without an explicit human act recording the conversion.
+
+The reason: a Quest lives in the realm of authored intent — admissible uncertainty, possible alternatives, future framing. A Job lives in the realm of resolved consequence — it happened or did not. Auto-conversion collapses one into the other and erases the distinction the author made between direction and execution.
+
+**Enforcement:**
+
+- Quest → Job conversion requires an actor + timestamp + recorded conversion event in the audit log.
+- Job → Quest elevation (rare) requires the same.
+- A "Convert to Job" UI action that creates the conversion event with explicit human click is acceptable. A scheduled background job that auto-promotes without that event is not.
+- Reality resolves Jobs; humans resolve Quests. A system that conflates the two collapses the compass (see `concepts/compass-doctrine.md`).
+
+**Violation severity:** error.
+
+---
+
+## Notation
+
+Every invariant check logs a row to `sa_invariant_violation` with:
+
+- `invariant_id` — one of `I1`…`I9`
+- `severity` — `warn | error | fatal`
+- `target_entity_id` / `target_audit_id`
+- `actor_id`
+- `details` — JSON-encoded context
+- `acknowledged_at` / `acknowledged_by` — operational triage
+
+Operational review dashboards can render violations grouped by `invariant_id` and sort by severity.
+
+---
+
+## Next
+
+- Wire all cross-realm mutation paths (push, pull, ingest) through `SA_Invariants::assert_or_throw()`.
+- Add enforcement to the presentation layer: UI must display `truth_class` on every surfaced datum (stamp in the top corner of every rendered entity).
+- Extend audit trace with chain-coherence checks: if a row claims a causation_id, that row must exist.
+- Build the policy engine layer so I6 (high-trust) and I9 (attribution) become user-configurable.

SA-orchestration MD/Archvie/sa-core/docs/specs/03-realm-adapter-contract.md

@@ -0,0 +1,282 @@
+# MissionNet Realm Adapter Contract (v0.1)
+
+*Implementation © Sleeper Agents LLC. Contract governed by invariants authored with Mark Holak's conceptual framework.*
+
+Every realm adapter (FluentCRM, Fluent Support, Fluent Boards, Jira, QuickBase, QuickBooks, Salesforce, HubSpot, PortTracker's Node service, arbitrary REST/GraphQL/DB) implements `SA_Realm_Adapter`. This document is the formal contract.
+
+An adapter is **complete when it preserves origin, survives failure, emits audit, and passes certification** — not when it "functions."
+
+---
+
+## Interface
+
+```php
+interface SA_Realm_Adapter {
+    public static function realm_id(): string;
+    public static function capabilities(): array;
+    public static function concept_map(): array;
+    public static function pull(string $concept, array $filter, array $context): array;
+    public static function push(string $concept, SA_Entity $entity, array $context): array;
+    public static function watch_hooks(): array;
+    public static function capability_matrix(): array;       // formal gates
+    public static function idempotency_rules(): array;       // replay behavior per op
+    public static function truth_class_for_concept(string $concept): string;
+}
+```
+
+---
+
+## `realm_id()`
+
+Short, stable identifier. Examples: `fluent-crm`, `fluent-support`, `fluent-boards`, `jira`, `quickbase`, `quickbooks`, `porttracker-node`.
+
+Must be unique across all adapters in a given Core install. Used as the `origin_realm` on every entity the adapter produces.
+
+---
+
+## `capabilities()`
+
+Set of strings from: `read`, `write`, `watch`, `bulk`, `incremental`, `idempotent_push`.
+
+- `read` — adapter can pull records from the realm.
+- `write` — adapter can push changes back into the realm.
+- `watch` — adapter subscribes to realm events (webhook or WP hooks).
+- `bulk` — adapter supports full snapshot pulls.
+- `incremental` — adapter supports `since` cursor / delta pulls.
+- `idempotent_push` — repeated push calls with the same payload are safe.
+
+A read-only adapter declares only `read` (and optionally `watch`, `bulk`, `incremental`).
+
+---
+
+## `payload.attributes` namespace convention
+
+Structured realm-side metadata that Core stores on an ingested entity goes under `payload.attributes` — a reserved sub-object. Freeform realm-native blobs remain elsewhere in `payload` (e.g., `payload.raw`, `payload.body_markdown`), but any field an adapter intends to be *addressable* — readable by the trace panel, queryable by future projections, or filter-eligible — belongs in `attributes`.
+
+```php
+$entity->payload = [
+    'attributes' => [
+        'mime_type'    => 'application/pdf',
+        'size_bytes'   => 12345,
+        'modified_at'  => '2026-04-23T10:15:00Z',
+        'basename'     => 'spec.pdf',
+        'extension'    => 'pdf',
+    ],
+    'raw' => [/* whatever realm-native detail the adapter wants to retain */],
+];
+```
+
+**Purpose.** Two-fold:
+
+1. Adapters converge on a predictable shape for structured fields. The FS adapter, the Jira adapter, the QuickBase adapter all put their structured metadata in `attributes`. A downstream reader (trace panel, future filter surface) knows where to look without realm-specific code.
+2. A later promotion to typed columns — if cross-realm queries demand it — is a rename migration, not a schema redesign. `payload.attributes.mime_type` becomes `entity.attributes.mime_type` or a separate `sa_entity_attribute` table without touching adapter code.
+
+**Discipline.** `attributes` values SHOULD be JSON-scalar (string / number / boolean / null) or flat arrays thereof. Nested objects inside `attributes` are permitted but signal that a sub-concept may want its own entity and containment edge instead.
+
+**Not canonical.** The `attributes` convention does not change truth-class. A projected entity's `payload.attributes` is still projection data; the realm remains canonical.
+
+---
+
+## `concept_map()`
+
+Declares how realm concepts translate into Core entity roles and edge kinds.
+
+```php
+[
+    'ticket'  => ['role' => 'job',     'band' => 3],
+    'agent'   => ['role' => 'agent',   'band' => 3],
+    'customer'=> ['role' => 'agent',   'band' => 3],
+    'reply'   => ['role' => 'message', 'band' => 4],
+    'edges'   => [
+        'ticket->agent'    => ['kind' => 'depends',  'weight' => 0.8],
+        'ticket->customer' => ['kind' => 'depends',  'weight' => 1.0],
+        'reply->ticket'    => ['kind' => 'contains', 'weight' => 1.0],
+    ],
+]
+```
+
+Concept names are adapter-scoped (no collision across realms). Edge rules describe how relationships in the realm become typed edges in Core.
+
+---
+
+## `capability_matrix()`
+
+Turns "tool not silo" into enforceable behavior:
+
+```php
+[
+    'read'                        => true,
+    'write'                       => true,
+    'delete'                      => false,
+    'impersonation'               => false,
+    'service_principal'           => true,
+    'human_confirmation_required' => ['delete', 'bulk_write', 'schema_change'],
+    'simulation_only_mode'        => true,
+]
+```
+
+Core consults this matrix before dispatching every operation. An adapter that does not declare `delete = true` cannot delete; an operation listed in `human_confirmation_required` cannot execute without a confirmed human action; `simulation_only_mode = true` enables dry-run mode for destructive operations.
+
+---
+
+## `idempotency_rules()`
+
+Per-operation replay behavior:
+
+```php
+[
+    'pull'  => [
+        'idempotent'          => true,
+        'replay_safe'         => true,
+        'conflict_resolution' => 'last_write_wins',
+    ],
+    'push'  => [
+        'idempotent'          => false,
+        'replay_safe'         => false,
+        'conflict_resolution' => 'reject',
+    ],
+    'watch' => [
+        'idempotent'          => true,
+        'replay_safe'         => true,
+        'conflict_resolution' => 'last_write_wins',
+    ],
+]
+```
+
+`conflict_resolution` values: `last_write_wins` | `reject` | `human_review`.
+
+A non-idempotent `push` must never be retried without an explicit policy decision.
+
+---
+
+## `pull(concept, filter, context)`
+
+Returns a list of `SA_Ingest`-shaped mutations:
+
+```php
+[
+    [
+        'op'     => 'upsert_entity',
+        'entity' => [
+            'external_key' => '<native_id>',   // REQUIRED (or origin_id directly)
+            'role'         => 'job',
+            'kind'         => 'rrect',
+            'payload'      => [...],
+            'truth_class'  => SA_Truth_Class::PROJECTED,   // default
+        ],
+    ],
+    [
+        'op'   => 'upsert_edge',
+        'edge' => [
+            'source_id'   => '...',
+            'target_id'   => '...',
+            'kind'        => 'depends',
+            'weight'      => 0.8,
+            'intentional' => true,
+        ],
+    ],
+    [
+        'op'          => 'attach_source',
+        'entity_id'   => '...',
+        'priority'    => 10,
+        'source_payload' => [...],
+    ],
+]
+```
+
+**Provenance minimums are MANDATORY** (Invariant I4). Every upserted entity must carry either `external_key` (from which `origin_realm` + `origin_id` are derived) or `origin_realm` + `origin_id` explicitly.
+
+**Truth class default is `projected`** — non-canonical mirror of the realm's canonical state. Only adapters whose concept is genuinely advisory (weather forecasts, suggestions) may return `inferred`.
+
+---
+
+## `push(concept, entity, context)`
+
+Apply a Core-side change back into the realm.
+
+Returns:
+
+```php
+[
+    'ok'          => true,
+    'external_id' => '<realm-assigned-id-if-new>',
+    'error'       => null,
+    'trace_token' => '<optional-realm-trace-handle>',
+]
+```
+
+**Idempotency:** if declared in `idempotency_rules()`, `push` MUST be safe to retry. The adapter is responsible for deduplicating on the realm side (using the entity's `id` or a synthetic idempotency key).
+
+**Never mutate without action path.** A push that was not triggered by a command (or an audited automation policy) is a protocol violation.
+
+---
+
+## `watch_hooks()`
+
+```php
+[
+    ['hook' => 'fluentcrm/contact_created',  'handler' => [self::class, 'on_contact_created'],  'priority' => 10],
+    ['hook' => 'fluent_support/ticket_reply', 'handler' => [self::class, 'on_reply'],            'priority' => 10],
+]
+```
+
+Core's `SA_Realm_Registry::wire_all_watchers()` attaches these on boot. The handler must emit ingest mutations (not directly mutate Core state), so that the ingest pipeline's enforcement gates apply uniformly.
+
+---
+
+## `truth_class_for_concept(concept)`
+
+Returns one of `SA_Truth_Class::ALL`. Default: `projected`.
+
+- Realm concepts that are authoritative at the realm: `projected`.
+- Realm concepts that are explicitly advisory: `inferred`.
+- Core-authored concepts (rare): `canonical`.
+- Cache-only concepts with TTL: `cached` (declared by the adapter's cache layer, not usually by the adapter itself).
+
+---
+
+## Certification Checklist
+
+An adapter is **not live** until these pass. Recorded to `sa_adapter_certification`.
+
+| Check | Meaning |
+|---|---|
+| `source_identity_preserved` | Realm's native id is preserved on every ingested record and round-trippable through push. |
+| `native_ids_preserved` | `origin_id` survives every transformation in and out. |
+| `read_path_verified` | Pull returns records that successfully deserialize as Core entities. |
+| `write_path_verified` | Push creates or updates a realm record and returns the native id. |
+| `failure_path_verified` | Failures (network, 4xx, 5xx, timeouts) raise structured errors; no silent half-writes. |
+| `stale_cache_behavior_verified` | When cache is stale and the caller demands high-trust, the adapter re-verifies against the realm. |
+| `audit_event_emitted` | Every pull and push produces a `sa_structural_audit` row with `origin_realm`, `correlation_id`, `causation_id`. |
+| `rollback_defined` | There is a documented compensation path for failed pushes or partial batches. |
+
+All eight must be `true` before an adapter moves from development to live. A failing certification row prevents the realm from being included in the active routing set.
+
+---
+
+## Behavioral guarantees (enforced at interface level)
+
+- Adapter **never mutates without an action path**. A push requires a command; a pull is triggered by an explicit sync or a watch event.
+- Adapter **never strips source metadata**. `origin_realm`, `origin_id`, `observed_at` survive every transformation.
+- Every record returned includes native id and source realm.
+- Outbound writes return status, external id, and (where available) a trace token.
+- Retries are idempotent where declared; non-idempotent operations require explicit policy approval to retry.
+- Error classes are normalized to `{ok, error, error_code, detail}`.
+
+---
+
+## The tool test
+
+Before any realm adapter is declared live, the operator asks:
+
+> If Core disappears tomorrow, does this realm still work at its native home?
+
+If the answer is anything but *yes*, the adapter has crossed from incorporation into absorption. That is a different category, governed by a different process (code consolidation, not conduit), and must be signaled as such. The user and the operator must both consent before an adapter is ever permitted to cross this boundary.
+
+---
+
+## Attribution
+
+Contract shape and adapter interface: © Sleeper Agents LLC.
+
+The invariants that the contract enforces (I4 realm provenance, I5 graceful degradation, I6 cache discipline, I8 tool test) implement conceptual commitments authored independently by Mark Holak. See `docs/specs/concepts/` for the foundational framework.

SA-orchestration MD/Archvie/sa-core/docs/specs/04-async-execution.md

@@ -0,0 +1,678 @@
+# Async Execution — Design Specification
+
+Status: **design approved; Phase 1 implementing as foundational substrate.**
+Target rung: 2.5 (between projection completion and zoom-quantum).
+Scope: one foundational pillar. Implementation proceeds phase-by-phase under separate directives.
+
+## Framing (authoritative)
+
+The pillar is **ownership of execution**, not "offline" as a feature.
+
+Three layers, kept distinct:
+
+- **Now Session** — the user-facing scope. The browser tab, the compose bar,
+  the field as it reads during an interactive moment. UX lives here. In
+  Phase 1 this is UNCHANGED: prompts still feel like "I asked here, it is
+  working here, this thread is mine now."
+
+- **Shadow job** — the execution substrate. A server-owned lifecycle record
+  (`sa_job`) that tracks what the executor is actually doing. Introduced in
+  Phase 1 as foundational infrastructure, with no UX surfacing. The seam
+  that makes later decoupling possible without rewriting retries, state
+  transitions, frontier selection, failure handling, or field updates.
+
+- **Offline / Subconscious** — a future user-facing mode built on the
+  shadow-job substrate. Marketing layer for background / recoverable / long-
+  running work. NOT introduced by Phase 1. Introduced only when a later
+  directive surfaces it.
+
+The instruction the rest of this spec serves:
+
+> Treat shadow jobs as foundational infrastructure introduced now, but keep
+> their behavior scoped to the current Now Session until a later directive
+> surfaces them as an explicit Offline/Subconscious capability.
+
+---
+
+## 0. Scope note
+
+This spec describes **async prompt execution** as a first-class capability.
+
+It does NOT cover:
+- The client-state race bug-fix (a separate, independent commit — closes a symptom of the sync model; lands before or alongside phase 1 here).
+- Implementation commits (each phase below becomes a directive; each directive becomes one or more commits).
+
+It DOES cover:
+- What a prompt job is, and how it differs from the current request.
+- The canonical state machine.
+- The storage model.
+- The worker strategy (comparison + decision + rationale).
+- The client interaction model (comparison + phased choice).
+- A phased migration plan where each phase ships a working system.
+- The failure / retry / recovery model.
+- Explicit tradeoffs and risks.
+- Measurable success criteria.
+
+---
+
+## 1. Motivation and Current Limitations
+
+### Today
+
+- `POST /sa-core/v1/prompt` is synchronous. The REST thread calls `SA_Executor::run`, which calls the adapter via `wp_remote_post`, which blocks the PHP request for up to 180 seconds (after the recent timeout raise).
+- The browser tab owns the entire prompt lifecycle. The client's `fetch()` holds the connection; if the tab closes, the server continues running but the user loses all visibility into the outcome.
+- Two prompts submitted in parallel are two parallel PHP workers, each doing a long cURL wait, with zero coordination, no priority, and no recovery if one of them crashes.
+- The just-observed concurrent-submit race (two prompts attaching to the same parent) is a symptom: client-side `activeCtxRootId` is the only source of truth for "which node is the continuation root," so timing conflicts between user navigation and async resolution are inevitable.
+
+### Why this is structural, not cosmetic
+
+1. **Rung 5 (operator realism) is blocked.** Tests that simulate load, capacity planning, reliability SLAs, and meaningful metrics all require async job execution. Every one of these is meaningless against a sync model.
+2. **Rung 4 (zoom-quantum engine) gets much harder on sync.** The engine wants cheap state-transition re-renders. Pushing state through long sync calls + `/mission/recent` refreshes introduces races we'd have to hunt repeatedly.
+3. **Rungs 3 and 6 (self-hosting, carma-audit absorption) produce entity streams that shouldn't block HTTP.** Scanner runs, doc ingestion, code ingestion — none of these should tie up a web request.
+4. **The tab is not a reliable process owner.** Real work — long code generations, multi-step agent chains, background analyses — must survive a closed tab.
+5. **Browser-side state conflicts are fundamental with sync.** The concurrent-submit race is one; future race surfaces (multi-user live editing, real-time collaboration) are coming. Moving execution state authority to the server closes these by construction.
+
+---
+
+## 2. Execution Model
+
+### What is a "prompt job"
+
+A **prompt job** is the unit of work that executes the `SA_Executor` pipeline against a specific prompt entity. It is:
+
+- A durable record with its own UUID identity (distinct from the prompt entity).
+- A pointer to a persisted prompt entity (`prompt_id`).
+- A member of the queue with a state, a priority, and a retry budget.
+- Owned by the server, not the browser.
+- Inspectable, retriable, cancellable, supersedable — as a first-class operation.
+
+### How it differs from the current request model
+
+| Concern | Today (sync) | Proposed (async) |
+|---|---|---|
+| Who owns the pipeline's lifecycle? | The REST thread | The worker layer |
+| Where is "in-progress" state? | PHP memory + browser memory | `sa_job` DB row |
+| Does closing the tab kill the work? | No (it continues) but the user loses visibility | No — and the user regains visibility on reload |
+| Can two prompts run simultaneously? | Only as two parallel PHP workers with no coordination | Yes, first-class, priority-ordered |
+| Can a failed execution be retried cleanly? | Via `retry_prompt` after the fact | Built into the state machine |
+| Can the user inspect queued / running work? | No | Yes (CLI phase 2; UI later) |
+
+### Canonical lifecycle
+
+1. **Submit.** `POST /prompt` creates:
+   - Prompt entity (as today, synchronously within the request — this is fast; the adapter call is what blocks).
+   - `sa_job` row with `state='queued'`.
+   - Returns **`202 Accepted`** with `prompt_id`, `job_id`, and initial state. Target: response within 50ms.
+2. **Enqueue.** Client adds the prompt to its `entities[]` array with the job's state, renders a "queued" drop. Client begins polling (phase 2) or listening via SSE (phase 4).
+3. **Claim.** A worker polls for the highest-priority queued job. Transactional update: `state='queued'` → `state='running'`, `worker_claim=<uuid>`, `claimed_at=now`.
+4. **Run.** The worker invokes `SA_Executor::run_claimed(job_id)`. This is a refactored executor entry-point that operates on an already-persisted prompt + job, not a fresh submit.
+5. **Complete.** On adapter success, the worker writes the response entity, the `flows-to` edge, the ledger row, the structural audit row (as today), and transitions the job to `state='succeeded'` with `response_id` set.
+6. **Observe.** Client sees state transitions via polling or SSE, updates the drop's visual state class accordingly.
+7. **Fail (if applicable).** On adapter error, the worker classifies the error, applies retry policy, and either re-queues the job with backoff OR marks it `state='failed'`.
+
+---
+
+## 3. State Machine
+
+### States
+
+| State | Meaning | Terminal? |
+|---|---|---|
+| `queued` | Created; waiting for a worker | No |
+| `running` | Claimed by a worker; adapter call in flight | No |
+| `succeeded` | Adapter returned OK; response entity persisted | Yes |
+| `failed` | Retry budget exhausted or non-retryable error | Yes |
+| `cancelled` | User or operator intervention | Yes |
+| `superseded` | Replaced by a newer job (e.g., user retried) | Yes |
+
+Once a job enters a terminal state, it does not change. A retry does **not** mutate an existing job — it creates a **new job** that references the old one via `supersedes`.
+
+### Transitions
+
+```
+queued      → running      : worker successfully claims
+queued      → cancelled    : user/operator action before claim
+running     → succeeded    : adapter OK + response entity written
+running     → queued       : transient failure; attempt < max_attempts; apply backoff
+running     → failed       : retry budget exhausted OR non-retryable error
+running     → failed       : stuck (started > 15 min ago, no heartbeat) via cleanup
+running     → cancelled    : operator kill (response discarded even if it arrives later)
+succeeded   → superseded   : user-initiated retry replaces result
+failed      → superseded   : user-initiated retry
+cancelled   → superseded   : user-initiated retry after cancel
+```
+
+### Heartbeat model
+
+While `state='running'`, the worker MUST update `running_heartbeat_at` every 30 seconds. A separate cleanup task (run via system cron every 5 minutes) reclaims jobs where `running_heartbeat_at < now() - 5min` back to `state='queued'` (if `attempt < max_attempts`) or to `state='failed'` (else).
+
+### Triggers
+
+- `queued` ← `SA_Executor::enqueue` (called from REST handler).
+- `running` ← worker process picks up a `queued` job and wins the claim race.
+- `succeeded` ← worker completes execution and commits.
+- `failed` ← worker exhausts retries OR cleanup declares job stuck.
+- `cancelled` ← CLI `wp sa-core cancel-job <id>` OR admin action.
+- `superseded` ← a new job is created referring to this one via `supersedes`.
+
+---
+
+## 4. Storage Model
+
+### Decision: new `sa_job` table
+
+Not overloading `sa_entity`.
+
+Rationale:
+- `sa_entity` represents authored knowledge: the user's prompt, the LLM's response, the derived context. It has one durable identity per artifact.
+- `sa_job` represents execution: a prompt may have multiple execution attempts (retries), each with its own claim, timing, errors, heartbeats. Conflating these with entity state confuses semantics and crowds the entity row.
+- Keeping them separate means: `sa_entity` stays durable knowledge; `sa_job` stays ephemeral execution records. Queries stay clean: "show me the user's recent prompts" is a `sa_entity` query; "show me what's queued" is a `sa_job` query.
+
+### Schema
+
+```sql
+CREATE TABLE {prefix}sa_job (
+    id                       CHAR(36) NOT NULL,
+    prompt_id                CHAR(36) NOT NULL,
+
+    state                    VARCHAR(16) NOT NULL DEFAULT 'queued',
+        -- queued | running | succeeded | failed | cancelled | superseded
+
+    priority                 TINYINT UNSIGNED NOT NULL DEFAULT 50,
+        -- lower number = higher priority
+        -- 0-10: urgent (interactive, current-tab)
+        -- 20-40: normal user-initiated background
+        -- 50: default
+        -- 60-90: bulk / scheduled / idle-time
+        -- 100: lowest (opportunistic)
+
+    attempt                  SMALLINT UNSIGNED NOT NULL DEFAULT 1,
+    max_attempts             SMALLINT UNSIGNED NOT NULL DEFAULT 3,
+
+    execution_options        LONGTEXT NOT NULL,
+        -- JSON: { model?, prefer_provider?, depth?, router_model?, ... }
+
+    worker_claim             VARCHAR(64) NULL,
+    claimed_at               DATETIME NULL,
+    started_at               DATETIME NULL,
+    running_heartbeat_at     DATETIME NULL,
+    finished_at              DATETIME NULL,
+
+    response_id              CHAR(36) NULL,
+        -- set on succeeded; points to the response entity
+
+    error_kind               VARCHAR(32) NULL,
+        -- timeout | rate_limit | provider_5xx | provider_4xx
+        -- | parse | auth | worker_crash | stuck | unknown
+
+    error_message            TEXT NULL,
+
+    supersedes               CHAR(36) NULL,
+        -- if this job replaces a previous attempt
+
+    org_id                   BIGINT UNSIGNED NOT NULL,
+    created_by               BIGINT UNSIGNED NOT NULL,
+    created_at               DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at               DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+                             ON UPDATE CURRENT_TIMESTAMP,
+
+    PRIMARY KEY (id),
+    KEY idx_state_priority_created (state, priority, created_at),
+    KEY idx_prompt                 (prompt_id),
+    KEY idx_worker_claim           (worker_claim),
+    KEY idx_org_user_state         (org_id, created_by, state),
+    KEY idx_heartbeat              (state, running_heartbeat_at)
+)
+```
+
+### Interaction with existing entity fields
+
+| Field | Lives on | Set when | Changed by jobs? |
+|---|---|---|---|
+| `correlation_id` | `sa_entity` | At prompt creation time (unchanged) | No |
+| `parent_id` | `sa_entity` | At prompt creation time (continuation semantics, unchanged) | No |
+| `causation_id` | `sa_entity` | At prompt creation time (unchanged) | No |
+| `source_refs` | `sa_entity` (response) | Written by worker at job completion | Indirectly (job runs the executor which sets it) |
+| `truth_class` / `state_class` | `sa_entity` | Set at write time (unchanged) | No |
+
+The `sa_job` table is orthogonal to the entity graph. Entities are durable structural records. Jobs are execution metadata.
+
+### Retry and supersession
+
+When a user retries a failed or succeeded prompt:
+1. Create a **new** `sa_job` row with the same `prompt_id`, new UUID, `attempt=1`, `state=queued`, `supersedes=<old_job_id>`.
+2. The old job stays in place (terminal state preserved).
+3. If the retry path requires cleaning up a prior response entity (as the current `retry_prompt` does for failed responses), that happens in the worker that claims the new job, NOT at enqueue time.
+
+This model means every execution attempt is recorded and queryable. "Show me the history of this prompt" becomes `SELECT * FROM sa_job WHERE prompt_id = X ORDER BY created_at`.
+
+---
+
+## 5. Worker Strategy
+
+### Decision: custom worker, driven by WP-CLI + system cron
+
+### Comparison
+
+**Option A: WP-Cron alone** — not chosen.
+- Pros: zero external dependencies.
+- Cons: WP-Cron spawns only on page visits (unreliable for low-traffic sites); each spawn is bound by `max_execution_time`; no native priority; no concurrency management. The "real cron hitting `wp-cron.php`" workaround mitigates the first point but the others remain.
+
+**Option B: Action Scheduler (the library)** — fallback / future option.
+- Pros: mature, battle-tested by WooCommerce and Mailpoet, has built-in claim/retry/logs, comes with an admin UI, well-understood in the WP ecosystem.
+- Cons: adds a dependency (~200KB library, or plugin requirement); its schema and patterns are WooCommerce-flavored; it wraps our job concept with its own scheduling layer that we'd then have to thread through.
+- Worth reconsidering if we ever need to interoperate with a WooCommerce-running site that already uses AS.
+
+**Option C: Custom worker** — chosen.
+- Rationale: our `sa_job` table **is** our job system. Its state machine is specific to our semantics (prompt-centric, projection-aware, org-scoped). Adding Action Scheduler on top means we'd write adapters between our table and theirs. A custom worker is ~300 lines of code, directly aligned with our data model.
+- Cons: we own the scheduler code. Edge cases (claim races, heartbeat recovery, backoff) must be solved by us. But: the surface is narrow, there's no distributed coordination to worry about (single-node plugin), and the patterns are well-known.
+
+### Custom worker implementation
+
+```
+wp sa-core run-worker [--once] [--batch-size=N] [--priority-ceiling=N]
+```
+
+Behavior in one iteration:
+1. Generate or resume a `worker_id` for this process (UUID).
+2. Claim a batch of jobs:
+   ```sql
+   UPDATE sa_job
+      SET state='running',
+          worker_claim=<worker_id>,
+          claimed_at=NOW(),
+          started_at=NOW(),
+          running_heartbeat_at=NOW()
+    WHERE state='queued'
+      AND priority <= <priority-ceiling>
+    ORDER BY priority ASC, created_at ASC
+    LIMIT <batch-size>
+   ```
+   The single-statement UPDATE is the claim atomic: whichever worker's UPDATE lands first, wins.
+3. Re-query the claimed rows by `worker_claim=<worker_id>` to get the actual job ids.
+4. For each claimed job:
+   - Call `SA_Executor::run_claimed(job_id)`.
+   - On success: set state='succeeded', response_id, finished_at.
+   - On retryable failure: if attempt < max_attempts, set state='queued' with backoff delay (encoded via `created_at += backoff`); else state='failed'.
+   - On non-retryable failure: state='failed' immediately.
+5. Spawn a heartbeat thread/callback that updates `running_heartbeat_at` every 30s while the adapter is in flight.
+6. Sleep 2 seconds. If `--once`, exit. Otherwise loop.
+
+### Driving the worker
+
+Three supported modes:
+
+**Mode 1: Single-shot via system cron** (recommended for production)
+```cron
+* * * * * wp sa-core run-worker --once --batch-size=5
+```
+Every minute, claim up to 5 jobs, process them, exit. Reliable, bounded, manageable.
+
+**Mode 2: Long-running service** (optional for high-volume)
+```
+wp sa-core run-worker
+```
+Starts a persistent worker. Polls continuously. Should be supervised (systemd / supervisor) for restarts on crash.
+
+**Mode 3: WP-Cron via wp-cron.php** (default; fallback)
+If a site has no system cron, register `sa-core-process-queue` as a WP-Cron event firing every minute. Relies on site traffic; acceptable for dev and low-traffic installs.
+
+### Heartbeat and stuck-job cleanup
+
+Separate command:
+```
+wp sa-core reclaim-stuck-jobs
+```
+System cron: every 5 minutes.
+
+Behavior:
+- Find jobs where `state='running'` AND `running_heartbeat_at < now() - 5 minutes`.
+- For each:
+  - If `attempt < max_attempts` AND `started_at > now() - 15 minutes`: reclaim to `state='queued'`, clear `worker_claim`.
+  - Else: `state='failed'`, `error_kind='stuck'`.
+
+### Double-execution safety
+
+Risk: worker A claims a job, loses heartbeat, cleanup reclaims to queued, worker B claims and runs. Worker A's adapter call may still be in flight. Both workers could reach the "complete" step.
+
+Mitigation: all state-finalization writes (`state='succeeded'`, `response_id`, etc.) are conditioned on `WHERE state='running' AND worker_claim=<my_worker_id>`. Whichever update lands second sees no matching row and aborts silently. The first worker's result wins; the other worker's result is discarded (wasted work, but no data corruption).
+
+---
+
+## 6. Client Interaction Model
+
+### Decision: polling in phase 2, SSE in phase 4, WebSocket deferred
+
+### Comparison
+
+| Protocol | Pros | Cons | Chosen? |
+|---|---|---|---|
+| **Polling** | Simplest; works anywhere; zero new infra; trivial to implement | Latency up to poll interval; wastes bandwidth when idle (mitigated by only polling while in-flight jobs exist) | Phase 2 |
+| **Server-Sent Events** | Efficient for state updates; built into browsers (`EventSource`); one-way but that's what we need | Requires long-lived HTTP connection; may conflict with PHP `max_execution_time` on some hosts; harder to debug | Phase 4 |
+| **WebSocket** | Full-duplex; lowest latency; richest protocol | Needs separate infra (Node or Ratchet-in-PHP); significant deployment burden; overkill for our scale | Deferred |
+
+### Polling protocol (phase 2)
+
+**Submit flow:**
+
+1. Client calls `POST /prompt` with prompt text + root_entity_id + etc.
+2. Server returns `202` with `{ prompt_id, job_id, state: 'queued' }`.
+3. Client:
+   - Adds entity to `entities[]` with `state='queued'`, renders as queued drop.
+   - Starts a poll loop if not already running.
+
+**Poll loop:**
+
+- Every 2 seconds, while at least one in-flight (`queued` or `running`) job exists:
+  - Call `GET /sa-core/v1/mission/recent?since=<iso8601>`.
+  - Server returns entities with any updates since the timestamp.
+  - Client merges results by `prompt_id` (does not replace array wholesale).
+  - If all known prompts are terminal (succeeded, failed, cancelled, superseded) or no in-flight jobs remain, stop polling.
+
+**Server endpoint changes (phase 2):**
+
+- `GET /mission/recent` accepts `since=<iso8601>`. Returns only prompts updated since that time (joins `sa_job.updated_at` into the "is this updated" test).
+- Response includes an `as_of` timestamp the client uses as the next `since` value.
+
+### Field state → visual class mapping
+
+| Job state | CSS class on drop | Existing / new | Visual |
+|---|---|---|---|
+| `queued` | `is-queued` | **New** | Slow breath, paler halo; "waiting" reading |
+| `running` | `is-pending` | Existing | Current pending animation (dashed rotating halo) |
+| `succeeded` | (none) | Existing | Default settled drop |
+| `failed` | `is-orphan` | Existing | Muted salmon halo + retry chip |
+| `cancelled` | `is-cancelled` | **New** | Greyed-out, no retry chip |
+| `superseded` | hidden OR `.is-superseded` | **New** | Typically hidden; shown faded if a debug toggle enabled |
+
+Transitions:
+- `queued → running`: swap `is-queued` for `is-pending`.
+- `running → succeeded`: remove `is-pending`, merge real response data, `renderField()` for any layout adjustment.
+- `running → failed`: swap `is-pending` for `is-orphan`.
+
+### SSE protocol (phase 4, future)
+
+- Client opens `EventSource('/sa-core/v1/mission/events')` instead of polling.
+- Server streams events like `event: job.state_changed\ndata: {"prompt_id":"…","state":"succeeded",…}\n\n` whenever a job's state changes for this viewer.
+- Client falls back to polling if the `EventSource` fails.
+
+### WebSocket (deferred)
+
+Adds separate infra (Node sidecar, Ratchet-in-PHP, or a managed service like Pusher). No concrete need yet. Revisit when multi-user real-time collaboration becomes a live concern.
+
+---
+
+## 7. Migration Plan
+
+### Principle: each phase ships a working system
+
+No phase leaves the codebase in a half-broken state. At every phase boundary, a user can submit a prompt and see a result.
+
+### Phase 0 — Concurrent-submit race fix (prerequisite, separate scope)
+
+- Single commit, fixes the browser-state race in the current sync model.
+- Does NOT introduce async.
+- Makes parallel-submit testing reliable, which phase 2 needs.
+
+### Phase 1 — Schema + shadow jobs (1–2 commits, zero behavior change)
+
+Goal: write `sa_job` rows alongside synchronous execution, so the data layer exists before the execution path changes.
+
+Work:
+- Migration: create `sa_job` table (schema in §4).
+- `SA_Executor::run` remains synchronous. At the end, it writes a `sa_job` row with `state='succeeded'` (or `'failed'` if the adapter errored).
+- No REST change. No client change. No worker yet.
+
+Test: CLI proof submits a prompt, verifies an `sa_job` row with correct state exists and references the prompt.
+
+Rollback: drop the table via migration down; no user impact.
+
+### Phase 2 — Async execution path (3–4 commits)
+
+Goal: move adapter invocation out of the REST handler.
+
+Work:
+- Refactor `SA_Executor` into two entry-points:
+  - `SA_Executor::run` — retained for direct synchronous use (CLI proofs, back-compat).
+  - `SA_Executor::enqueue($prompt_text, $options)` — writes prompt entity + queued job, returns ids. Fast.
+  - `SA_Executor::run_claimed($job_id)` — worker's entry-point; runs the pipeline against an existing prompt + job.
+- `POST /prompt`: call `enqueue`, return `202` with `{ prompt_id, job_id }`.
+- Client `submitPrompt`: handle `202`, render queued drop, start poll loop.
+- Server: `GET /mission/recent` accepts `since` param; returns updated rows.
+- Add worker CLI: `wp sa-core run-worker`.
+- Add heartbeat cleanup: `wp sa-core reclaim-stuck-jobs`.
+- New CSS classes: `is-queued`, `is-cancelled`.
+
+Test:
+- CLI proof: submit a prompt, verify `state=queued`, run worker once, verify `state=running` → `state=succeeded`.
+- Concurrent-submit proof: submit two prompts with different priorities (10 and 90), run worker, verify priority=10 runs first.
+- Retry proof: submit, simulate transient failure (mock adapter), verify re-queue with backoff and eventual success.
+
+Rollback: revert `POST /prompt` to call `run` synchronously. `sa_job` rows for already-queued jobs need manual cleanup (or a CLI command to replay them synchronously). Worker command stays but unused.
+
+### Phase 3 — Priority queue (1–2 commits)
+
+Goal: expose priority so active-thread prompts outrank bulk / background work.
+
+Work:
+- `SA_Executor::enqueue` accepts `priority` in options (default 50).
+- Client: no UI change. Still submits at default. Future bulk operations (Scanner, Code Lens ingestion, etc.) pass higher priority values.
+- Worker query already orders by priority — schema supports it from phase 1.
+
+Test: submit 3 prompts with priorities {10, 50, 90}; verify worker claims in that order.
+
+Rollback: trivial; remove priority from enqueue options, falls back to default.
+
+### Phase 4 — SSE layer (2–3 commits)
+
+Goal: eliminate polling overhead.
+
+Work:
+- Add `GET /sa-core/v1/mission/events` endpoint that streams SSE.
+- Server-side: when a job's state changes, broadcast an SSE event to that viewer's stream.
+- Client: detect `EventSource` support; subscribe if available; else continue polling.
+
+Test: compare SSE event timing vs polling; verify identical state propagation; verify graceful fallback when connection drops.
+
+Rollback: client falls back to polling automatically if SSE endpoint returns 404 or connection fails.
+
+### Phase 5 — Hardening (2–4 commits)
+
+Goal: operator visibility, intervention, metrics.
+
+Work:
+- `wp sa-core list-jobs [--state=] [--org=] [--since=]` — list jobs with filters.
+- `wp sa-core job-details <job_id>` — full history for a job.
+- `wp sa-core cancel-job <job_id>` — operator cancellation.
+- `wp sa-core retry-job <job_id>` — explicit requeue.
+- Optional: `wp sa-core queue-metrics` — count by state, average latency per org, error rate.
+
+Test: CLI proofs for each command.
+
+### Phase 6 — async-native features (optional, post-pillar)
+
+Built on the same `sa_job` infrastructure, no further schema changes:
+
+- Background bulk operations (Scanner, Code Lens, Doc Lens at scale).
+- Scheduled prompts (run at 2am) via a `scheduled_for` column on `sa_job`.
+- Multi-prompt chains (job B starts after job A succeeds).
+
+Not part of the async pillar's completion criteria; listed for continuity.
+
+### Test discipline at each phase
+
+Every phase ships one or more CLI proofs in the `includes/cli/` pattern already established (geodesic-proof, promotion-proof, projection-proof, claim-continuation):
+
+- `async-execution-proof`: state progression queued → running → succeeded against a synthetic prompt.
+- `priority-queue-proof`: three synthetic prompts at different priorities; verify claim order.
+- `retry-proof`: simulated transient adapter failure; verify re-queue and eventual success.
+- `heartbeat-proof`: start a synthetic running job, sleep past heartbeat window, run reclaim, verify state.
+- `concurrent-safety-proof`: simulate double-claim race; verify only one worker's writes take effect.
+
+---
+
+## 8. Failure and Retry Model
+
+### Error classification
+
+Every failure gets an `error_kind`:
+
+| `error_kind` | Meaning | Retryable? | Backoff |
+|---|---|---|---|
+| `timeout` | cURL 28 or executor-level timeout | Yes | Exponential (5s, 25s, 125s + jitter) |
+| `rate_limit` | Adapter HTTP 429 | Yes | Respect `Retry-After` header; else 60s min |
+| `provider_5xx` | Adapter returned 5xx | Yes | Exponential |
+| `provider_4xx` (non-429) | Adapter returned 4xx | No | N/A |
+| `parse` | Response body couldn't be parsed | No | N/A |
+| `auth` | Credentials invalid | No | N/A (needs operator) |
+| `worker_crash` | Worker died mid-execution | Yes (via reclaim) | Immediate |
+| `stuck` | Job has been running > 15 min | No | Terminal; mark failed |
+| `unknown` | Catch-all for unclassified errors | Yes (conservative default) | Exponential |
+
+### Retry rules
+
+- Default `max_attempts = 3`. Configurable per-enqueue via options.
+- Backoff stored as a delay on the re-queued job's `created_at`: `created_at = now() + backoff`. Worker query only claims jobs where `created_at <= now()`, so backoff is honored naturally.
+- Backoff durations:
+  - Attempt 2: 5s + random(0, 5s)
+  - Attempt 3: 25s + random(0, 15s)
+  - (After attempt 3 fails: terminal)
+
+### Timeout handling
+
+- **Adapter timeout (180s)**: cURL 28. `error_kind='timeout'`. Retryable.
+- **PHP `max_execution_time` (300s)**: worker process killed. Heartbeat lost. Reclaimed by `reclaim-stuck-jobs`.
+- **Hard job ceiling (15 minutes)**: a running job started > 15 min ago with no recent heartbeat is declared stuck. `error_kind='stuck'`. Terminal.
+
+### Dead-letter handling
+
+- Jobs that exhaust `max_attempts` go to `state='failed'` with `error_kind` set.
+- They remain visible in the user's field as `is-orphan` drops (same treatment as today's orphans from sync-failure).
+- User can retry via the retry chip (same UX as today). Retry creates a new `sa_job` row with `supersedes=<old_id>`.
+- Operator CLI: `wp sa-core list-jobs --state=failed` surfaces recent failures.
+- Operator can run `wp sa-core retry-job <id>` to force a retry without user interaction.
+
+### Stuck-job recovery
+
+- `wp sa-core reclaim-stuck-jobs` runs via system cron every 5 minutes.
+- Query: `state='running' AND running_heartbeat_at < now() - INTERVAL 5 MINUTE`.
+- For each:
+  - If `attempt < max_attempts` AND `started_at > now() - 15min`: reclaim to `state='queued'`, clear `worker_claim`.
+  - Else: `state='failed'`, `error_kind='stuck'`.
+
+### Double-execution safety
+
+Mitigation already detailed in §5: all finalization writes are conditioned on `WHERE state='running' AND worker_claim=<my_worker_id>`. Second-arriving writer sees no matching row and exits silently. First-arriving result wins.
+
+Additional safeguard: response entity writes are keyed on a deterministic id derived from `(prompt_id, adapter_request_id)` when available, so duplicate writes collide on primary key and the second `INSERT` fails gracefully (caught by the finalization code).
+
+---
+
+## 9. Risks and Tradeoffs
+
+### Risk: cron reliability on managed hosts
+
+WP Engine (and many managed hosts) run cron via `wp-cron.php` spawned on page requests. On low-traffic sites this is unreliable.
+
+**Mitigation.** Document that production deployments SHOULD use a real system cron hitting `wp sa-core run-worker --once`. The command is standalone (doesn't depend on wp-cron's spawning). An on-page-load spawn continues to work for dev and low-volume sites.
+
+### Risk: worker compute resource pressure
+
+A long-running worker process consumes PHP process slots. On shared hosting, this may conflict with web requests.
+
+**Mitigation.** Default worker mode is `--once` (cron-driven, not service-style). Batch size is tunable. For high-volume users, the operator can tune cron frequency + batch size to stay within their host's limits.
+
+### Risk: `sa_job` table growth
+
+Every prompt creates ≥ 1 job. Retries create additional jobs per prompt. Over time, the table grows unbounded.
+
+**Mitigation.** Optional archival policy (phase 5 or later): jobs in a terminal state older than 30 days get archived or removed. `wp sa-core archive-old-jobs --before=<date>`. Indexes keep queries fast regardless of row count at expected volumes; archival is an optimization, not a correctness concern.
+
+### Risk: client polling overhead
+
+Many users × many tabs × many in-flight jobs = many simultaneous polls.
+
+**Mitigation.**
+- Polls happen only while in-flight jobs exist; idle tabs don't poll.
+- Poll interval is 2s; tunable.
+- Phase 4 (SSE) eliminates this risk entirely for modern browsers.
+
+### Risk: stale merges on client
+
+If the client has an in-memory edit (user typing in compose) and a poll fetches fresh entity data, we must not discard user input.
+
+**Mitigation.** Poll merges by `prompt_id` and only updates entity-state fields (response_id, state, context_ids, etc.). Compose-input state lives in the DOM, untouched by poll handling.
+
+### Risk: concurrent-submit out-of-order display
+
+Two prompts submitted close together may complete in the reverse order (e.g., P1 is slow, P2 is fast). The field would render P2 before P1.
+
+**Mitigation.** Field display order is by `prompt.created_at`, not job completion order. Stable regardless of async resolution order. The visual `is-queued` vs `is-running` vs settled state makes the running state transparent to the user.
+
+### Tradeoff: consistency window vs latency
+
+Async means there is a window where client shows `state='queued'` while server has already transitioned to `state='running'`. Polling latency is up to 2s. SSE tightens this to sub-second.
+
+**Accepted.** Up to 2s of client-side staleness is not a meaningful UX regression; phase 4 closes it.
+
+### Tradeoff: simplicity vs ecosystem reuse
+
+Custom worker vs Action Scheduler. Custom is simpler for our narrow scope but means we own the scheduler. AS is richer but adds a dependency and adapter layer.
+
+**Accepted.** Custom for phase 2. If we ever need to coexist with an AS-using site, the `sa_job` table's facade can be driven by either our worker or an AS callback without changing job semantics.
+
+### Risk: migrating users mid-transition
+
+Between phase 1 (shadow jobs written) and phase 2 (async path switched on), a user's `sa_job` rows represent historical sync executions. When phase 2 lands, any prompt submitted mid-transition could have incomplete metadata.
+
+**Mitigation.** Phase 2 rollout during a low-traffic window. On deploy, any `sa_job` rows with `state='queued'` from pre-phase-2 (there shouldn't be any, but defensively) are either processed by the first worker run or marked `state='failed'` with `error_kind='migration'` for manual review.
+
+---
+
+## 10. Success Criteria
+
+The async pillar is complete (through phase 2) when:
+
+1. `POST /prompt` returns within 100ms, 99th percentile, regardless of adapter latency.
+2. Closing the browser tab during a prompt's execution does NOT cancel the job; reopening the site shows the completed result.
+3. Two prompts submitted to different continuation parents from different tabs are processed correctly, with no race-induced data corruption.
+4. A cURL timeout on the adapter causes an automatic retry with exponential backoff; a permanently-failing prompt surfaces as a retriable orphan after `max_attempts` exhaustion.
+5. A crashed worker's job is reclaimed within 5 minutes and either completes on the next attempt or fails cleanly.
+6. The CLI proofs described in §7's test discipline section all pass.
+7. Existing `/mission` UI works throughout — no regressions on selection, trace, thread view, promote, verdict, continuation, retry, or content-collapse.
+8. The `wp sa-core run-worker` command can be configured to run under standard system cron without supervisor-style infra.
+
+The pillar is **complete through phase 4** when additionally:
+
+9. SSE delivers state updates within 200ms of server-side transition.
+10. Polling mode still works identically as a fallback when SSE is unavailable.
+
+---
+
+## 11. Out of Scope (deliberately deferred)
+
+- **Multi-node distributed coordination.** Single-node assumption in claim locking. Revisit if horizontal scaling ever becomes a concern.
+- **Priority inversion prevention.** A long-running low-priority job blocking urgent jobs is theoretically possible but rare in our expected volume. Observe first; fix if it ever occurs.
+- **User-facing queue inspection UI.** CLI only through phase 5. A UI can be added later; `sa_job` data is already viewer-scoped via `org_id + created_by` indexing.
+- **Scheduled prompts** (`scheduled_for`): phase 6 (optional).
+- **Multi-prompt chains** (dependent jobs): phase 6 (optional).
+- **Per-org quotas** (max N concurrent running jobs): defer until multi-tenant scaling matters.
+- **Cross-process worker coordination** (multiple machines): defer until single-machine capacity is exhausted.
+- **Real-time collaboration** (two users editing the same field simultaneously): defer to the ACL / perspective-projection pillar.
+
+---
+
+## 12. Appendix: Summary of Design Decisions
+
+| Concern | Decision | Rationale |
+|---|---|---|
+| Storage | New `sa_job` table | Separate execution from knowledge; supports multiple attempts cleanly |
+| Worker | Custom WP-CLI runner | Narrow scope; direct control; ~300 lines; no new dependency |
+| Scheduling driver | System cron → `wp sa-core run-worker --once` | Reliable across hosts; standalone from wp-cron |
+| State machine | 6 states + heartbeat + supersession | Covers all observed outcomes; no ambiguity |
+| Client protocol | Polling (phase 2) → SSE (phase 4) | Ships working async in phase 2; optimizes in phase 4 |
+| Retry | Exponential backoff, max_attempts=3 | Handles transient failures; bounded pessimism |
+| Rollback | Phase-by-phase; each has a defined revert | Safe to implement incrementally |
+| Migration | Shadow jobs first (phase 1) → switch path (phase 2) | Data layer proven before execution switch |
+
+This spec is the contract. Implementation directives reference it by phase.

SA-orchestration MD/Archvie/sa-core/docs/specs/05-zoom-quantum-engine.md

@@ -0,0 +1,373 @@
+# Zoom-Quantum Engine — Design Specification (Rung 4)
+
+Status: **design draft; coil substrate shipped (Rung 3); phase plan pending per-phase directive.**
+Target rung: 4.
+Scope: multi-focal zoom as a native field gesture, not a viewport transform. Per-correlation zoom, hyperbolic envelope, cross-region pull-connection. All projections remain 2D.
+
+---
+
+## Framing (authoritative)
+
+**Zoom is a semantic quantum, not a viewport change.** Zoom belongs to a *domain of influence*, not to the screen. A conversation can be zoomed without touching any other conversation. The field carries regional density depth of zoom.
+
+Three layers of zoom, kept distinct:
+
+- **Global zoom** — the default, existing affordance (SVG viewBox). The whole field pans and scales. Useful for "where am I on the mission."
+- **Regional zoom** — per-correlation, introduced by this pillar. Each thread carries its own scalar zoom state. The user can be deeply inside thread A while thread B stays at rest. Multiple threads can be simultaneously focused at independent depths.
+- **Hyperbolic envelope** — when a regional zoom exceeds threshold, the thread's head wraps the visible workspace as a Poincaré-disk horizon. "You are inside this thread." The tail stretches toward the asymptotic center; the head becomes the event horizon.
+
+The instruction the rest of this spec serves:
+
+> The default case is to zoom the whole field. The innovation is to zoom a *conversation* — one region of influence — without perturbing the rest of the field. When two regions are simultaneously focused, the user can pull a connection between them instead of splitting the screen. Multi-focal composition is the posture; hyperbolic geometry is how we keep "where is my context" legible while compression grows infinite.
+
+---
+
+## 0. Scope note
+
+This spec describes the **zoom-quantum engine** as a user-facing field behavior + its projection math.
+
+It DOES cover:
+- The per-correlation zoom state model
+- The math of the hyperbolic envelope (Möbius transform on a Poincaré disk)
+- How regional zoom composes with the already-shipped log-spiral coil
+- Multi-focal simultaneous zoom
+- Cross-correlation pull-connection as a new edge primitive
+- Gesture vocabulary
+- Phasing
+
+It does NOT cover:
+- The Prime-Prompt / compression mechanic (separate Pillar 0 concern, deferred)
+- Server-side data model changes beyond a new edge kind (zoom is client UI state)
+- A split-screen or multi-window layout (explicitly rejected — the hyperbolic projection replaces it)
+- WebGL / 3D rendering (explicitly rejected — all projections are 2D)
+
+---
+
+## 1. What already exists
+
+Rung 3 shipped the **logarithmic-spiral coil** (commit `de4de7e`). Each correlation group renders as:
+
+```
+r_t      = r₀ · γ^t          (log-spiral radius)
+θ_t      = baseAngle + t·dθ  (angular step)
+scale_t  = γ^t               (same decay → self-similar under zoom)
+opacity_t = max(o_min, 1 − f·t)
+```
+
+The coil is already scale-invariant: a uniform scale factor `k` maps the spiral onto itself shifted by `log_γ(k)` turns. The infrastructure for "zoom descends into the tail" is in place on the math side; Rung 4 adds the UI, the per-correlation state, and the hyperbolic envelope.
+
+The `.is-coiled` class and `data-coil-index` attribute on each drop are hooks for this rung.
+
+---
+
+## 2. Primitives
+
+### 2.1 Per-correlation zoom state
+
+```
+CoilZoomState {
+  correlation_id : string        The thread this state belongs to
+  zoom           : float (≥ 0)    0 = rest; 1 = first quantum in; 2 = second; ...
+  focal_x        : float          optional: where on the screen the focus anchors
+  focal_y        : float          (defaults to the current head position)
+  pinned         : bool           if true, survives other zooms of other threads;
+                                  if false, collapses to rest when another
+                                  thread is focused (single-focus convention)
+}
+```
+
+Stored client-side. Not persisted by default; optional SA_Settings scope=user
+persistence (`field.coil.zoom_state`) is a follow-on if the UX calls for it.
+
+### 2.2 Focal stack
+
+```
+FocalStack = CoilZoomState[]
+```
+
+The ordered list of currently-focused coils. Zero-or-one at rest is the default; multi-focal is the innovation. Rendering composes their transforms.
+
+### 2.3 Hyperbolic envelope
+
+Threshold: when `zoom ≥ HYPERBOLIC_THRESHOLD` (configurable; 2.0 is a reasonable starting point), the coil's head enters **envelope mode**:
+
+- The head dilates toward the workspace boundary.
+- The rest of the coil (and any other visible content within this region) is rendered through a Möbius transform on the Poincaré disk.
+- The edge of the viewport becomes the ideal boundary at infinity.
+
+Mathematically, with the focal point at origin `a = 0`:
+
+```
+w = (z - a) / (1 - ā·z)
+```
+
+For `a = 0` this reduces to `w = z`, so we introduce zoom via composition with a pure dilation before the Möbius map:
+
+```
+z'  = scale_by_zoom · z
+w   = (z' - a) / (1 - ā·z')
+```
+
+At low zoom, the transform is near-identity. As zoom grows, points near the focal point expand outward; points near the ideal boundary asymptote there but never cross. This is the "event horizon" — infinite expansion curls into the hyperbolic limit.
+
+### 2.4 Pull-connection (cross-region edge)
+
+A new edge kind:
+
+```
+kind:          'pull-connection'  (or 'cross-region')
+source_id:     entity A's id
+target_id:     entity B's id
+intentional:   true (always — user gesture-created)
+metadata:      { author_id, created_at, gesture_kind: 'drag' }
+```
+
+Stored as a row in the existing `sa_edge` table. No schema change — `SA_Edge::KINDS` already accepts arbitrary kinds (today: link, contains, depends, influences, flows-to, continues, promoted).
+
+Rendered as a flowing line between two focused regions, distinct visually from within-thread edges (dashed? colored by author? to be decided per phase).
+
+### 2.5 Compose operator
+
+```
+render(entity) = Global_Viewport ∘ Regional_Hyperbolic ∘ Local_Coil ∘ entity.position
+```
+
+Three projections stacked:
+
+1. **Local coil** (shipped): the log spiral places older correlation members relative to their head.
+2. **Regional hyperbolic** (new): when a coil is past the threshold, apply the Möbius transform to everything within its region, centered on its head.
+3. **Global viewport**: the SVG viewBox. Pans / scales the whole field for navigation.
+
+Each layer is independently controllable. A user at rest sees only the coils (layer 1 only). A user focused on one thread with hyperbolic crossed sees layer 1 + 2. A user zooming out to find a thread uses layer 3.
+
+---
+
+## 3. Multi-focal model
+
+The posture: **multiple regions focused simultaneously, without split screens.**
+
+Scenarios:
+
+- **Single focus** (typical): one thread is zoomed in. Others sit at their rest coil. The user sees the coil-of-interest at its hyperbolic scale, other coils in the background at normal scale.
+- **Dual focus** (workspace comparison): two threads both zoomed. Their Möbius disks compose by position — e.g., one occupies the left third of the viewport, the other the right third. Content *between* them is what survives the intersection.
+- **Multi focus** (relational map): N threads focused at varied zoom levels. The field becomes a composite of hyperbolic neighborhoods, each with its own focal anchor. Resembles a relational map where the nodes are the focal points and the content around each is the locally-zoomed thread.
+
+Pull-connection is the natural gesture across this state: drag from a point inside focus A's hyperbolic neighborhood to a point inside focus B's hyperbolic neighborhood. The drag creates a cross-region edge. The edge renders as a line that passes through the ambient space between the foci.
+
+**Rejected alternative**: split-screen. Splitting the canvas into two viewports is the "click here, click there, zoom each, compare" solution. The spec rejects it as un-liquid — a literal cut in the fabric. The hyperbolic composition is the continuous alternative.
+
+---
+
+## 4. Gesture vocabulary
+
+### 4.1 Entering regional zoom
+
+- **Scroll-wheel over a coil region**: the scroll targets the coil underneath the cursor, not the global viewport. Forward = zoom in, back = zoom out.
+- Falls back to global viewport zoom when the cursor isn't over any coil's region.
+
+Implementation: hit-test the cursor against each visible coil's bounding disk. The coil whose center is closest (within a radius proportional to its current zoom) captures the scroll.
+
+### 4.2 Pin / unpin
+
+- **Click a coil's head while holding a modifier key** (e.g., Shift-click): pin this focus. Future zooms of other coils don't collapse this one.
+- **Click in empty space**: collapse all transient (non-pinned) foci to rest.
+
+### 4.3 Pull-connection
+
+- **Drag from a focused region to another focused region** (both must be at zoom ≥ some threshold). The drag creates a new `pull-connection` edge.
+- **Drop on empty space**: cancels.
+
+### 4.4 Exit / escape
+
+- **Esc** collapses all foci and returns to rest (coils at size 1, no hyperbolic envelope).
+- **Double-click a coil**: toggles between rest and last-known zoom state.
+
+---
+
+## 5. Math appendix
+
+### 5.1 Self-similar coil (shipped, Rung 3)
+
+For each correlation group:
+
+```
+t        = turn index (0 = newest head)
+baseAngle = hashJitter(correlation_id) · 2π       (per-thread starting angle)
+γ        = 0.85                                   (decay)
+dθ       = π/3                                    (60° per turn)
+r_t      = r₀ · γ^t
+θ_t      = baseAngle + t · dθ
+position_t = head_position + (r_t·cos θ_t − r₀·cos baseAngle,
+                              r_t·sin θ_t − r₀·sin baseAngle)
+scale_t  = γ^t
+```
+
+Zoom shifts the visible portion of the spiral. Under a uniform zoom of factor `k`, `scale_t → k · scale_t = γ^(t - log_γ k)`, so the spiral looks the same shifted by `log_γ k` turns. This is why zooming into the coil reveals more tail without stretching it.
+
+### 5.2 Poincaré disk (Rung 4, new)
+
+The hyperbolic plane is represented as the interior of a unit disk `|z| < 1`. Geodesics are circular arcs perpendicular to the boundary. Distance grows without bound near the boundary (the ideal horizon).
+
+A Möbius transformation preserves hyperbolic distance:
+
+```
+φ_a(z) = (z − a) / (1 − ā·z)       where |a| < 1
+```
+
+For MissionNet:
+
+- The coil's currently-focused head sits at the disk center.
+- The tail of the coil stretches toward the center (asymptotically never reaching, per the log-spiral math).
+- Other visible content is projected outward toward the boundary, compressed as it approaches — "infinite expansion curls to hyperbolic limit."
+
+Scaling for zoom level `λ ≥ 0`:
+
+```
+z'       = (1 − e^(−λ)) + e^(−λ) · z         (pre-zoom dilation centered on head)
+w        = φ_focal(z')                        (Möbius, centered on head)
+screen_w = half_viewport_size · w             (map disk to viewport)
+```
+
+At λ = 0 the transform is identity. As λ grows, `z'` approaches 1 (the boundary), the head fills the viewport, and the rest of the content compresses toward the edge.
+
+### 5.3 Composition of multi-focal Möbius
+
+Two focal points `a` and `b`, each with zoom levels `λ_a` and `λ_b`, can be composed:
+
+```
+w = Σ weights_i · φ_i(dilate_i(z))
+```
+
+For a weighted sum where `Σ weights_i = 1`. This is an approximation — the exact composition of two Möbius transforms is another Möbius transform, but picking *which* transform to use when you want BOTH foci visible requires a heuristic. The weighted-sum approximation gives a visually pleasing blend and is well-defined for any number of foci.
+
+A cleaner model: render each focused region in its own hyperbolic neighborhood, with the boundary between regions being the ambient (un-transformed) space. This is what pull-connection edges cross.
+
+---
+
+## 6. Data model changes
+
+### 6.1 No schema change for zoom state
+
+Per-correlation zoom is client-side UI state. Not persisted by default. If a user asks for their zoom state to survive reload, add:
+
+- SA_Settings key `field.coil.zoom_states`, scope=user, type=string (JSON-serialized `CoilZoomState[]`).
+
+That's one line of setting declaration; no migration needed.
+
+### 6.2 Pull-connection edge: no schema change
+
+`SA_Edge` already accepts arbitrary kinds via a `kind` column. Add `'pull-connection'` to `SA_Edge::KINDS` as a documented kind. No migration; no new table.
+
+Permissions: creating a pull-connection requires `sa-core:impose-grouping` (already a capability in the starter package — user-declared relational claims are tenant work, not operator work).
+
+---
+
+## 7. Phased implementation plan
+
+Phases ship independently; each is a working system.
+
+### Phase 0 — Already shipped (Rung 3 `de4de7e`)
+
+- Logarithmic-spiral coil for multi-turn correlations.
+- Self-similar under zoom.
+- Per-thread base angle.
+- `.is-coiled` / `data-coil-index` DOM hooks.
+
+### Phase 1 — Per-correlation zoom state (single focus, no hyperbolic)
+
+Minimum usable regional zoom:
+
+- Client state: `Map<correlation_id, zoomLevel>`.
+- Scroll-wheel over a coil zooms THAT coil (not the field). Hit-test via cursor position vs. each coil's bounding disk.
+- Applying zoom = multiplying the coil's `r₀` and `scale_t` by a zoom factor. Math is already scale-invariant, so the spiral just reveals more structure as `r₀` grows.
+- Other coils continue to render at rest. No hyperbolic envelope yet.
+- Esc returns everything to rest.
+
+**Ships when:** the user can scroll over any thread, that thread alone expands / contracts, other threads are unchanged, and Esc collapses the focus.
+
+### Phase 2 — Hyperbolic envelope (single focus, past threshold)
+
+- When a coil's zoom crosses `HYPERBOLIC_THRESHOLD`, enter envelope mode.
+- Render the focused coil's neighborhood through the Möbius transform (§5.2).
+- Other coils in the field get pushed toward the viewport boundary as content crosses into the hyperbolic disk.
+- Exit threshold hysteresis so crossing the threshold doesn't thrash.
+
+**Ships when:** the user can zoom a thread to where the head wraps the workspace, the tail visibly stretches toward the asymptotic center, and the "event horizon" reading is unambiguous.
+
+### Phase 3 — Multi-focal composition
+
+- Introduce the focal stack: multiple `CoilZoomState`s active simultaneously.
+- Pin gesture (Shift-click on a head) keeps a focus alive when another is zoomed.
+- Render pipeline composes multiple hyperbolic disks in the same viewport.
+- Heuristic for disk placement (e.g., foci at equi-distant points around the viewport center, scaled by their respective zoom levels).
+
+**Ships when:** the user can pin thread A, focus thread B separately, and see both at their own zoom levels without a split screen.
+
+### Phase 4 — Pull-connection
+
+- Add `pull-connection` to `SA_Edge::KINDS`.
+- Drag gesture from one focused region to another creates the edge (persisted via existing `SA_Edge::create`).
+- Rendered as a distinct line between the two focal anchors, flowing through the ambient space between them.
+- Pull-connections surface in the trace aside and in projection pipelines that list edges (e.g., a future "related threads" projection).
+
+**Ships when:** the user can physically drag a relation across focal regions, it persists, and it's visible from both threads' perspectives.
+
+### Deferred (out of scope)
+
+- **Interactive compression** (Pillar 0 / Prime Prompt) — the user can't yet summarize a coil at zoom; the coil renders what it holds.
+- **Zoom-state persistence** — default is per-session. Persistent (across reloads / devices) is a follow-on SA_Settings slice.
+- **Touch gestures** — pinch-zoom on a coil region. Desktop-first.
+- **Pull-connection AI semantics** — a pull-connection is declarative today. Future rungs may let a pull-connection trigger an LLM rerun with both threads as context, or seed a geodesic marker.
+
+---
+
+## 8. Open questions (for resolution at phase directive time)
+
+### 8.1 Global vs. regional zoom arbitration
+
+If the user scrolls while the cursor is over a coil AND also over a piece of ambient space (e.g., near the boundary of a coil), which wins? Proposal: cursor-anchored — nearest coil center wins within its bounding disk; outside that, ambient viewport wins.
+
+### 8.2 What happens when a single-turn correlation is focused?
+
+Single-turn correlations don't have a coil (Rung 3 skips them). Regional zoom on a single-turn could just scale the head in place. Or we could degrade it to global zoom. Proposal: degrade to global zoom for single-turn (no coil to reveal; zooming should feel like the viewport is responding).
+
+### 8.3 How deep is "deep"?
+
+The coil can, by construction, have infinitely many turns. The log-spiral decay means each turn is 15% smaller than the previous, so after 30 turns we're at 0.85^30 ≈ 0.8% of original size — visually indistinguishable from the center. Practically the coil caps at some maximum rendered turn. Proposal: render only turns where `scale_t ≥ some_epsilon` (say 0.05) unless the user has actively zoomed past that depth. Zooming past that depth reveals deeper turns.
+
+### 8.4 Pull-connection authorization model
+
+Not every user should be able to create cross-thread edges on content they didn't create. Current proposal: the creator of *either* thread can create a pull-connection. Operator bypass applies via `sa-core:impose-grouping`. Refine at phase 4 directive.
+
+### 8.5 Band vocabulary
+
+The canonical spec's "zoom band" vocabulary (bands 0-5) is orthogonal to this regional zoom:
+
+- Bands = semantic quanta of information (repo / folder / file / class / method / line for code; or workspace / thread / turn / sentence / token for conversation).
+- Regional zoom = the user's viewport scalar within a domain.
+
+A single regional zoom doesn't have to correspond to a band crossing; bands apply primarily to the operating-memory lattice (Rung 3). For conversation coils, the "bands" are turns (each turn is one band deeper). This might converge later — for now, the two concepts are independent.
+
+---
+
+## 9. What remains stable across all phases
+
+- **The coil math.** Rung 3's log-spiral doesn't change. Every phase builds on top of it.
+- **All projections are 2D.** No WebGL, no actual 3D space. Möbius transforms and log spirals produce the illusion of depth on a flat viewport.
+- **Client-side state.** Zoom is UX; it doesn't mutate the entity graph. The only server-side new thing across all phases is one new edge kind.
+- **Head anchors at its base layout position** at zoom 0. The coil only exists below the head in the current scheme — expanding the head doesn't move it; it just reveals more of the coil that was already there.
+
+---
+
+## 10. Summary of decisions
+
+- Zoom is **per-correlation by default, global as fallback**.
+- Hyperbolic envelope via **Möbius transform on the Poincaré disk** when zoom exceeds threshold.
+- Multi-focal composition via **weighted Möbius sum OR disjoint-neighborhood rendering** (tbd per phase 3).
+- Cross-region linkage via a **new edge kind `pull-connection`**, stored in the existing `sa_edge` table.
+- **No split screens.** The hyperbolic composition is the continuous alternative.
+- **No WebGL / 3D.** All 2D projections.
+- **No schema change** for any phase except the one-line KIND registration.
+- **Phase 1 first**: scroll-wheel regional zoom, no hyperbolic. Ships independently.
+
+---

SA-orchestration MD/Archvie/sa-core/docs/specs/06-toolbox-action-contract.md

@@ -0,0 +1,127 @@
+# Toolbox Action Contract (v0.1)
+
+*Implementation © Sleeper Agents LLC. Contract shape governed by the Admission Contract principle (see `01-ontology.md`).*
+
+A Toolbox action is a `/mission/`-native button whose click invokes a single REST endpoint and renders inline state-machine feedback. Toolbox actions are the surface through which operators trigger system-side work without leaving the field.
+
+This contract was promoted from *Informal* to *Formal* after the second concrete instance landed (GitHub Actions re-scan, alongside the original FS re-scan). Two examples were enough to extract the clauses below without speculation; further instances must conform.
+
+---
+
+## Admission requirements
+
+A Toolbox action is admissible only if it satisfies all seven clauses. A button that does not satisfy them is not a Toolbox action — it is some other UI affordance and lives under a different contract.
+
+### 1. Semantic binding
+
+The button is bound to **one and only one** REST endpoint. Multi-action buttons are forbidden. If two related actions are needed (e.g., scan vs. discover), they require two buttons. The endpoint receives the action's parameters via JSON request body.
+
+```html
+<button data-action="<realm>.<verb>" ...>
+```
+
+The `data-action` attribute is informational; the actual binding is the click handler's `endpoint:` option.
+
+### 2. Permission gate
+
+The same WordPress capability MUST be enforced at **two layers**:
+
+- **Template render-gate**: `current_user_can(<cap>)` controls whether the button HTML is emitted at all. Non-admins see no button.
+- **REST `permission_callback`**: enforces the same capability server-side. A non-admin who bypasses the template (e.g., crafting a `fetch()` call manually) still cannot reach the handler.
+
+Defense in depth is mandatory. Single-layer permission gating is a contract violation.
+
+### 3. Audit obligation
+
+The REST handler MUST write exactly **one** operator-attribution structural-audit row per invocation, before delegating to any underlying ingest path:
+
+```php
+SA_Structural_Audit::record(
+    'user',
+    $viewer_id,
+    'realm.<slug>.<verb>.invoked',
+    null,
+    null,
+    [/* action parameters */],
+    'SA_REST_<Class>::handle_<method>'
+);
+```
+
+This audit is **distinct** from any per-mutation audits the underlying `SA_Ingest` path may write. The toolbox audit answers *"who initiated this action and when"*; per-mutation audits answer *"what changed."* Both must exist; the toolbox audit must not be elided just because the ingest path produces its own.
+
+### 4. Parameter shape
+
+Required parameters MUST be derivable at **button-render time**, not at click time. Two acceptable patterns:
+
+- **Server-side render with `data-*` attributes**: the button's HTML carries the parameter, e.g. `data-repo="owner/name"` rendered from a server-side allow-list lookup. Click handler reads the attribute.
+- **Fixed defaults baked into the JS handler**: e.g., `limit: 10` hardcoded in the handler's `bodyFor()` lambda.
+
+Click time is for *executing* the action, not for *configuring* it. Toolbox actions that require a parameter dialog are out of scope for this contract — they belong to a future *Toolbox Composer* contract not yet written.
+
+### 5. Feedback contract
+
+The button cycles through three CSS state classes during invocation:
+
+- `is-busy` — applied immediately on click. Label: `Scanning…` (or equivalent verb-progressive).
+- `is-success` — applied on `result.ok === true && typeof result.sync.processed === 'number'`. Label: `+N ingested` (or equivalent count summary).
+- `is-failed` — applied on any other outcome (network error, exception, `ok: false`). Label: `Failed` (or equivalent).
+
+All three classes clear after a reset interval (recommended ~2400ms) and the label restores to the button's default. The reset MUST happen so the button is reusable without page reload.
+
+CSS treatments for the three states are part of the contract via the shared `.sa-mission-toolbox-btn` styles.
+
+### 6. Refresh obligation
+
+On success, the client MUST call the page's data-refresh primitive (currently `load()`) so newly-ingested or updated entities render in the field without a full page reload. Toolbox actions whose effects don't appear on `/mission/` are out of scope for this contract — they belong to a future *Toolbox Background* contract not yet written.
+
+### 7. Idempotency
+
+The underlying REST endpoint MUST be idempotent at the entity level. Repeated clicks with the same parameters MUST produce **zero net entity-count change**: the second invocation may update existing entities in place, but it MUST NOT duplicate them.
+
+Idempotency is enforced upstream of the toolbox action (in the realm adapter's `idempotency_rules()` declaration and the `SA_Ingest` deterministic-UUID logic). This contract requires that toolbox actions only bind to endpoints whose adapters declare `pull` as `idempotent: true, replay_safe: true`.
+
+A non-idempotent endpoint cannot be exposed as a toolbox action without explicit policy approval. Such cases require a future *Toolbox Confirmed Action* contract not yet written.
+
+---
+
+## Currently admitted instances
+
+| Action | Endpoint | Capability | Audit action slug |
+|---|---|---|---|
+| Re-scan FS | `POST /sa-core/v1/realm/fs/scan` | `manage_options` | `realm.fs.scan.invoked` |
+| Re-scan GitHub Actions | `POST /sa-core/v1/realm/github-actions/scan` | `manage_options` | `realm.github_actions.scan.invoked` |
+
+Both instances satisfy all seven clauses. The shared client-side helper `bindToolboxAction(btn, opts)` in `assets/mission.js` is the canonical implementation; new instances should use it directly.
+
+---
+
+## Behavioral guarantees
+
+- **No surprise mutations.** A toolbox click never causes work the operator did not request. The button's label and `data-action` together name the work; the audit row records its execution.
+- **Safe to retry.** Idempotency clause means a click can be retried without consequence beyond a fresh per-mutation audit trail.
+- **Permission cannot be bypassed.** A non-admin cannot trigger any toolbox action via any path; defense in depth holds.
+- **Operator attribution survives.** Every toolbox invocation leaves a structural audit row tying a user identity to an action slug, retrievable via `SA_Structural_Audit::trace_origin()`.
+
+---
+
+## What this contract does NOT cover (out of scope, deferred)
+
+- **Toolbox actions with parameter dialogs.** Click-time configuration is a different shape. Future *Toolbox Composer* contract.
+- **Toolbox actions whose effects are invisible to `/mission/`.** Background work, scheduled jobs, side-effect-only actions. Future *Toolbox Background* contract.
+- **Non-idempotent or destructive actions** (delete, publish, send). Require explicit confirmation flow. Future *Toolbox Confirmed Action* contract.
+- **Multi-step composed actions** (run-then-render, branch-on-result). Future *Toolbox Composition* contract.
+- **Per-user configurable toolbox** (operators choose which actions to surface). Future *Toolbox Customization* contract.
+
+The current contract covers *single-shot, idempotent, parameter-defaulted, admin-only operator actions whose output renders on `/mission/`* — the shape both current instances exhibit. Other shapes are filed for future contracts when they have concrete instances driving them.
+
+---
+
+## Promotion criteria for future revisions
+
+This contract was admitted at v0.1 with two instances. It graduates to v0.2 when:
+
+- A third instance lands and conforms cleanly without modification (confirms the seven-clause pattern is stable), OR
+- A third instance lands and surfaces a real edge case the seven clauses don't handle (forces a clause refinement or new clause), OR
+- An out-of-scope shape (parameter dialog, non-idempotent action, etc.) is authorized as a new toolbox category and the parent contract grows a fork.
+
+Until any of those happen, the seven clauses stand as currently written.

SA-orchestration MD/Archvie/sa-core/docs/specs/README.md

@@ -0,0 +1,70 @@
+# MissionNet / Core Spec Pack
+
+This directory holds the formal spec pack governing Core's behavior. The specs are enforceable — their invariants compile into runtime checks in `includes/enforcement/`.
+
+---
+
+## Authorship and attribution
+
+Two distinct authorship layers:
+
+- **Conceptual framework** — authored independently by **Mark Holak** over a long history of personal designs. Preserved verbatim under `concepts/` with explicit authorship frontmatter. Governed by Invariant **I9**: may not be rephrased as AI-original when referenced.
+- **Core implementation (sa-core codebase + this spec pack)** — © **Sleeper Agents LLC**. The implementation adapts the conceptual framework into runnable, enforceable system behavior. The implementation is a Sleeper Agents LLC product.
+
+The distinction is load-bearing. The framework is portable — it could be implemented by other systems. Core is one implementation.
+
+---
+
+## Spec documents (active)
+
+| # | Document | Purpose |
+|---|---|---|
+| 01 | [Ontology](01-ontology.md) | Vocabulary lock. Every term Core uses, defined once. |
+| 02 | [System Invariants](02-invariants.md) | The nine non-negotiable laws (I1–I9), with enforcement hooks. |
+| 03 | [Realm Adapter Contract](03-realm-adapter-contract.md) | Formal contract every realm adapter (Fluent, Jira, QuickBase, QuickBooks, PortTracker-Node, any API) implements. |
+
+## Spec documents (planned)
+
+Per Mark Holak's directive on the full 12-spec pack:
+
+| # | Document | Status |
+|---|---|---|
+| 04 | Canonicality and Projection Spec | planned |
+| 05 | Event, Command, and Audit Spec | planned (partial coverage in 02 + ontology) |
+| 06 | Identity, Role, and Authority Spec | planned |
+| 07 | Policy Evaluation Spec | planned |
+| 08 | Cache and Freshness Spec | planned |
+| 09 | AI Mediation Spec | planned (partial coverage in I7 + I9) |
+| 10 | Mission / Job Orchestration Spec | planned |
+| 11 | Interface Contract Spec | planned |
+| 12 | Observability and Integrity Spec | planned |
+
+## Concepts (preserved artifacts)
+
+Authored by Mark Holak, preserved under `concepts/`:
+
+- [Legacy Prime Prompt](concepts/legacy-prime-prompt.md) — the SAWS-era handoff document. Precedes Core; seed of the current architecture.
+- [Prime Prompt Conjecture + PR Notation](concepts/prime-prompt-conjecture.md) — the formal compression / portability claim and its operators.
+- [Cognitive Heatsink](concepts/cognitive-heatsink.md) — thermodynamic model of thought-to-resolution.
+
+## Main architecture document
+
+The integrated architecture lives at [`../ARCHITECTURE.md`](../ARCHITECTURE.md). It carries the Russell–Ouroboros Conjecture (authored Mark Holak), the four pillars, the derived pillars, the build order, and the source evidence appendix. Think of the spec pack here as the *formal enforcement layer*; the architecture doc is the *integrated narrative*. They reference each other.
+
+---
+
+## Contribution
+
+When adding a new spec:
+
+1. Bump the version in this index.
+2. Cross-reference any invariant the new spec introduces or enforces.
+3. If the spec introduces new vocabulary, add the terms to `01-ontology.md` FIRST.
+4. If the spec draws on a Mark-Holak-authored concept, cite `concepts/` explicitly (I9).
+5. If the spec adds code-enforced gates, land the gate under `includes/enforcement/` in the same commit.
+
+When modifying an existing spec:
+
+- Preserve the `v0.1`-style version label at the top; bump on material change.
+- Append a brief change log entry at the bottom of the spec.
+- If the change affects an invariant's severity or enforcement, note it in a commit message prefixed with `[invariant]`.

SA-orchestration MD/Archvie/sa-core/docs/specs/concepts/attention-doctrine.md

@@ -0,0 +1,52 @@
+# Attention Doctrine
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> **Attention is signal, not instruction.** It travels through the system as a routing event — naming a target, an actor, and a context — and stops there. Resolution is an act of arbitration, performed by a human, recorded as a separate event.
+
+Attention asks. It does not act.
+
+---
+
+## Four locked properties
+
+1. **Attention never mutates system state.** A signal raises a question; it does not answer one.
+2. **Attention never implies authority.** The signal does not grant the actor permission to do anything.
+3. **Attention requires human arbitration to act.** Until a human reviews and decides, the signal sits in the log, unconsumed.
+4. **NPCs may emit Attention. NPCs may not resolve it.**
+
+---
+
+## NPC participation
+
+NPCs in MissionNet — interpretive agents, canonical librarians, seed generators, future agents — may emit Attention. They may surface tension, frame situations, suggest paths. The act of *signaling* is appropriate to their role.
+
+The act of *resolving* is not. NPCs cannot decide for the human, accept work on the human's behalf, or close a question by their own authority. Doing so would be the system simulating the outcome rather than letting reality resolve it.
+
+This is the load-bearing rule. Without it, the system drifts into auto-resolution and the compass collapses.
+
+---
+
+## Distinct from Signal
+
+Attention is **routing infrastructure**. Signal (see `signal-telemetry-doctrine.md`) is **measured alignment behavior**. They are not synonyms.
+
+- Signal is what the instrument reads after participants traverse an authored field.
+- Attention is the wiring that brings a participant's question to the right desk.
+
+A bridge that handles Attention does not measure Signal. A telemetry layer that reads Signal does not route Attention.
+
+---
+
+## Cross-references
+
+- `01-ontology.md` — Attention (primary noun)
+- `02-invariants.md` I10 — no automatic conversion; NPCs route, humans resolve
+- `signal-telemetry-doctrine.md` — distinct concept; preserved under I9
+- `compass-doctrine.md` — Attention's place in the five-actor compass

SA-orchestration MD/Archvie/sa-core/docs/specs/concepts/cognitive-heatsink.md

@@ -0,0 +1,164 @@
+# The Cognitive Heatsink
+
+> **Authored by Mark Holak.**
+> Independent personal design; a causal model of thought-energy resolution.
+> Preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## 🧠 Overview
+
+The **Cognitive Heatsink** is a conceptual and structural model that describes how *unresolved potential* — in the form of questions, thoughts, or prompts — is transformed through complex energetic processing (e.g., cognition, LLMs, or interpretive systems) into a **resolved, compressed, and symbolic output** returned to the originator. It models thought as an **energy transfer problem** bounded by entropy, resolution, and causal geometry.
+
+This is not merely a metaphor; it is a functional abstraction of agentic computation and recursive meaning formation.
+
+---
+
+## 🌀 Full Journey of a Thought through the Heatsink
+
+### 1. Potential Thought (Unresolved State)
+
+- Exists as **a wave** of probability within the *mind* or initiating system.
+- It is *directionless but charged*, seeking resolution.
+- Analogous to a high-entropy field: chaotic, undecided, multivalent.
+
+**Formal tag:**
+
+```markdown
+State: ψ(thought_potential) | Entropy: High | Mass: Conceptual | Location: Agent (User)
+```
+
+### 2. Prompt Initiation (Vectorization)
+
+- The potential is *vectorized into form*: a question, prompt, sketch, or symbol.
+- The prompt is not the thought — it is **a request for energetic resolution**.
+- This stage **forces alignment** with a system's interface: language, image, equation, etc.
+
+**Effect:** Collapses the wavefunction into a communicable causal packet.
+
+### 3. Energy Drop into the Heatsink (Transmission to System)
+
+- The prompt is *injected* into a high-fidelity computational field (e.g., an LLM, mind, or hybrid system).
+- This process mimics **heat entering a cooling sink**:
+    - Turbulence
+    - Redistribution
+    - Structural constraint
+    - Interpreted memory
+
+**Core idea:** Thought becomes **friction** against trained weight, latent space, or prior bias.
+
+### 4. Gearwork Phase (Computation / Resolution)
+
+- The prompt activates **gears of meaning**:
+    - Embeddings
+    - Tokens
+    - Search spaces
+    - Causal memory (e.g., `PR[]` slots)
+- The system undergoes **entropic reduction**: from open-endedness to determinism, from ambiguity to clarity.
+
+**Analogy:** Like a gearbox, this step steps down high-frequency noise into low-speed, high-torque conceptual output.
+
+**Thermal effect:** The system **radiates excess energy** in the form of incoherence, hallucinations, or layered truths.
+
+### 5. Return Path (Prompt Resolution Output)
+
+- The output **returns to the originator** as words, images, maps, or a new thought.
+- The *meaning is encoded*, not direct. It must be **rehydrated** by the prompter's mind.
+- Sometimes the output **redirects heat back**: new questions are spawned → a recursive loop begins.
+
+### 6. Integration and Dissipation
+
+- The mind (or downstream agent) **integrates the cooled output**: truths are absorbed, misfires are discarded, new causal edges are drawn.
+- The system has now acted as a **heatsink** for the cognitive pressure of the initiating thought.
+
+---
+
+## 🛠 Functional Summary
+
+| Phase               | Description                      | Thermodynamic Analogy |
+| ------------------- | -------------------------------- | --------------------- |
+| Thought Potential   | Unresolved question or intuition | Superheated vapor     |
+| Prompt Initiation   | Language or symbolic encoding    | Nozzle / Channel      |
+| Heatsink Entry      | System intake                    | Heat exchange inlet   |
+| Gearwork Resolution | Model response process           | Radiator core         |
+| Return Output       | Answer or concept                | Coolant loop          |
+| Integration         | User accepts or re-prompts       | Output vent           |
+
+---
+
+## 🧬 Implications for Agentic Systems
+
+- All intelligent agents must be modeled as **cognitive heatsinks**, each with:
+    - **Thermal limits** (token budget, concept density)
+    - **Efficiency curves** (how much entropy → insight)
+    - **Backpressure risk** (prompt overloads, recursion traps)
+- Multi-agent systems form **heatsink chains**, where one agent cools a domain and passes semi-resolved structure downstream.
+
+---
+
+## 🔁 Recursive Heatsinks
+
+If a node's output triggers further resolution:
+
+```text
+Prompt → Agent A → Output → Agent B → Summary → Back to Originator
+```
+
+Each agent's role is to absorb **one layer of cognitive thermal load**, not the full spectrum. Overlapping heatsinks form the **geometry of distributed cognition**.
+
+---
+
+## 🧠 Real-World Mapping
+
+- **LLMs**: resolve high-level semantic questions into language
+- **Designers**: convert abstract desire into visible form
+- **Scientists**: reduce chaotic phenomena to equations
+- **Humans**: turn trauma into art, pain into narrative, entropy into clarity
+
+All are **heatsinks**.
+
+---
+
+## 📎 Integration with Prompt Reasoning (PR[]) Model
+
+The **Cognitive Heatsink** defines the *mechanism* by which `PR[]` slots are filled. A PR-frame with unresolved links behaves like an overheated system. Each prompt acts as:
+
+```markdown
+PR[Node_X] = heatsink(prompt_energy) → stable_symbol(output)
+```
+
+When prompts are chained, the heatsink graph approximates a **causal topology** of the system's cognitive space.
+
+---
+
+## 🧩 Conclusion
+
+The Cognitive Heatsink model gives **structural semantics** to the thought-to-resolution process in intelligent agents and LLM pipelines. It treats cognitive load as **thermal pressure**, model computation as **mechanical dissipation**, and prompt resolution as **symbolic cooling**.
+
+Once understood, it becomes possible to:
+
+- Compose efficient prompt cascades
+- Optimize for semantic energy transfer
+- Model multi-agent systems as distributed thermodynamic machines
+
+---
+
+## Core implementation mapping
+
+*This section is Sleeper Agents LLC adaptation. The model above is Mark Holak's original work; the mapping below is how Core realizes it operationally.*
+
+| Heatsink concept | Core primitive |
+|---|---|
+| Thought potential (ψ) | A user-authored message entity at band 4, `truth_class = canonical` — the unresolved question. |
+| Prompt initiation | `SA_Executor::run()` entry — the canonical prompt entering the orchestration chain. |
+| Heatsink entry | Geodesic seeder folds avoidance hints; adapter receives augmented prompt. |
+| Gearwork phase | Each step emits a `SA_SubToken_Event` — embed, retrieve, tool, subagent, router, rerank, self-critique, completion. Every discrete thermal transfer is a first-class, auditable row. |
+| Thermal radiation (hallucinations, incoherence) | `truth_class = inferred` stamping on completion output; I7 prevents inferred → canonical without source_refs or human affirmation. |
+| Return path | Response entity linked to parent by `flows-to` edge; delivered to the originator with latency + usage + trace. |
+| Integration and dissipation | Per-sub-step verdict annotation (`good`/`bad`) feeds `SA_Geodesic_Marker` — bad paths become avoidance hints for the next run. The "cooling" is persisted. |
+| Recursive heatsinks | Multi-adapter sessions with role specialization (`conversation`, `extraction`, `critic`) bound to the same `SA_Context_Bundle` — each agent absorbs one layer. |
+| Thermal limits | Adapter `capabilities.max_context_tokens` + pricing policy rate limits. |
+| Backpressure / overload | Pillar 0.25's stationary-at-rest rule + adapter idempotency + rate limits. |
+
+The sub-token event is the Cognitive Heatsink made operational. Each row is one thermal transfer step. The audit chain is the thermodynamic history.

SA-orchestration MD/Archvie/sa-core/docs/specs/concepts/compass-doctrine.md

@@ -0,0 +1,67 @@
+# Compass Doctrine
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> The system never owns resolution. Resolution comes from outside the system, from real-world consequence. The compass orchestrates approach to that boundary; it does not cross the boundary itself.
+
+There are five positions, not three. Each has a strict role.
+
+---
+
+## The five positions
+
+**Sara — interpret.** The interpretive cognition surface. Reads context, drafts, advises, observes. Outputs are non-binding. Sara never resolves.
+
+**Asterion — verify.** The canonical truth surface. Cites, refuses to speculate, answers from corpus or refuses. Asterion never decides what is true; it answers whether the corpus says so. Read-only by construction.
+
+**Attention — signal.** The routing layer. Surfaces tension, frames situations, names targets. Signals; does not resolve.
+
+**Humans — decide.** Arbitration authority. Only humans advance state. Only humans plant seeds. Only humans accept gates. Only humans resolve Attention.
+
+**Reality — resolve.** The outcome layer. Did the work happen. Did the contract hold. Did the field worker complete the job. Did the client pay. The system never simulates resolution; it defers to reality.
+
+Read in order, the compass describes a flow: interpretation → verification → routing → decision → consequence. Each step is required; each step belongs to its actor.
+
+---
+
+## The doctrine line
+
+The authored canonical form:
+
+> *Sara interprets. Asterion verifies. Attention signals. Humans decide. Reality resolves.*
+
+The brand-rendered runtime form, with deployment-specific labels substituted, is described in `concept-vs-label.md`.
+
+The line is invariant in shape and meaning across the lineage chain. Each layer below renders it; no layer below replaces it.
+
+---
+
+## What this doctrine guards against
+
+The failure mode is **drift into simulation** — the system pretending to resolve outcomes that only reality can resolve.
+
+Examples:
+
+- An agent auto-accepting work because the signal looked complete
+- An NPC closing a Quest by its own authority
+- A canonical layer claiming truth before the human has confirmed it
+- A signal layer mutating state because the urgency seemed high
+- A system marking a contract delivered before the client has paid
+
+Each of these collapses the compass. Each lets the system substitute its judgment for the human's, or the human's judgment for reality's.
+
+The discipline: **stay on your position.** Sara interprets only. Asterion verifies only. Attention signals only. Humans decide only. Reality is what it is.
+
+---
+
+## Cross-references
+
+- `attention-doctrine.md` — formal properties of the Attention position
+- `concept-vs-label.md` — the doctrine line renders through brand and client layers
+- `02-invariants.md` I7, I9, I10 — laws that operationalize these constraints

SA-orchestration MD/Archvie/sa-core/docs/specs/concepts/concept-vs-label.md

@@ -0,0 +1,84 @@
+# Concept vs Label
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> The **concept** is what a thing is. The **label** is what a thing is called. A system that confuses the two cannot be deployed across markets, clients, or sensitivity boundaries.
+
+The framework's identity travels at the concept layer. The label is rendered per deployment.
+
+---
+
+## Four layers
+
+**Core concept** — what the thing IS. Belongs to the framework. Identity-stable. Cannot change without changing the system. Examples: the canonical truth layer, the interpretive cognition surface, the signal-routing primitive.
+
+**Authorial label** — the term the framework's author uses to refer to the concept. Belongs to the author. Preserved verbatim under I9. Examples: Asterion, Sara, Attention.
+
+**Brand label** — the deployed surface name a brand chooses to render the concept under. Belongs to the brand. Mutable per deployment. May match the authorial label (Sleeper Agents today renders "Asterion" verbatim) or differ.
+
+**Client label** — the further rendering chosen for a specific client deployment. Mutable per client. Driven by market sensitivity, vocabulary, regulatory context.
+
+The four layers nest. Each lower layer is a rendering of the layer above. None replaces the layer above.
+
+---
+
+## Why this matters
+
+Some authorial labels are not deployable in some markets. "Asterion" — by mythos, the Beast of the Labyrinth — is a deliberate authorial choice that carries the right weight in the framework. It is unsuitable for medical, pediatric, hospice, religious, defense, or other sensitivity-bound markets. In those markets the brand or client renders the same concept under a different label.
+
+The rule:
+
+> **The concept never moves. The label renders.**
+
+A medical client may call the canonical truth layer **Endominous**. A defense client may call it **Source**. A pediatric platform may call it **Notebook**. The behavior, the contract, the I9 attribution, the I2 truth-class enum, the authorship — all unchanged.
+
+---
+
+## What stays stable across renames
+
+- Code: class names, file paths, REST routes, JS handles, internal identifiers
+- Doctrine: invariants, ontology relationships, lineage chain, attribution structure
+- Authorial labels in the framework's source corpus
+
+What renders through the brand layer:
+
+- UI text strings shown to humans
+- System prompts the agent speaks aloud
+- Stakeholder-visible comments and outputs
+- The doctrine line, when recited in a deployment context
+
+---
+
+## The doctrine line in two forms
+
+The authored canonical form:
+
+> *Sara interprets. Asterion verifies. Attention signals. Humans decide. Reality resolves.*
+
+The brand-rendered runtime form, with deployment-specific labels substituted:
+
+> *{north_label} interprets. {south_label} verifies. {attention_label} signals. Humans decide. Reality resolves.*
+
+The shape is invariant. The nouns render. The compass never moves.
+
+---
+
+## Failure mode this guards against
+
+A system that bakes the authorial label into its identity cannot be deployed beyond the author's tolerance for label propagation. Every market it enters becomes a sensitivity audit; every rename becomes a fork. The deployment burden compounds.
+
+The discipline: **separate concept from label at design time, not at deployment time.**
+
+---
+
+## Cross-references
+
+- `01-ontology.md` Attribution — implementation © Sleeper Agents; framework © Mark Holak; this doctrine is the structural reason that split is load-bearing
+- `02-invariants.md` I9 — concept-author preservation operates at the concept layer; brand renames do not strip authorship
+- `lineage-chain.md` — the rename rule operates only at the bottom two layers; upper layers are identity

SA-orchestration MD/Archvie/sa-core/docs/specs/concepts/legacy-prime-prompt.md

@@ -0,0 +1,123 @@
+# Legacy Prime Prompt — SAWS System 2026.01
+
+> **Authored by Mark Holak.**
+> Independently developed; preserved verbatim as a historical reference artifact.
+>
+> This document predates the Russell–Ouroboros Conjecture, predates Core, and predates the realm-adapter abstraction. It captures the conceptual and technical state of the SAWS plugin at the time of authorship and serves as a seed document for the architecture that followed. Where terminology differs from the current spec (`wp_saws_*` tables, `SAWS_Jobs`, single-plugin framing), the later architecture supersedes — but the philosophical continuity (everything-is-a-node, attribution, causal cones, frozen-space / controlled-time) is preserved and now formalized in Pillars 0, 0.25, and 0.75.
+>
+> Retained under `docs/specs/concepts/` so the trajectory from authored seed to implemented Core is auditable. Invariant **I9** governs how this document is referenced by downstream AI outputs.
+
+---
+
+## 🧠 System Context
+
+This prompt reconstructs the full operational and conceptual state of an evolving project inside the SleeperAgents ecosystem. The project is a hybrid of:
+
+- A WordPress-based autonomous system plugin (SAWS)
+- File-based reasoning architecture with user-driven LLM orchestration
+- Deep theoretical scaffolding on space-time, causality, and computation
+- Agentic design patterns embedded across UI, backend, and philosophical use
+
+This prompt unifies engineering and metaphysics through shared causal mechanics.
+
+---
+
+## 🛠️ Technical Context: SAWS Plugin Stack
+
+**System Goals:**
+
+- Enable users to upload, index, extract, and interact with documents through LLMs
+- Track and attribute cost and reasoning back to users across all subsystems
+- Support a node-based file hierarchy with inheritance, locks, versioning, and embedding refresh
+
+**Key Structures (legacy, pre-Core):**
+
+- `wp_saws_files`: archive storage and rendered text cache of uploaded files
+- `wp_saws_nodes`: logical file nodes for document access, summarization, and sharing
+- `wp_saws_prompts`: all prompts sent by users, with token/cost auditing
+- `wp_saws_sessions`: groups prompts by session for conversational memory
+
+**Behavioral Logic:**
+
+- File uploads are abstracted as nodes; their metadata is decoupled from storage
+- Text extraction is queued asynchronously via `SAWS_Jobs` (future upgrade: RAG-enhanced)
+- Nodes can be refreshed recursively, allowing downstream updates and embedding regeneration
+- All LLM usage is attributed to the user, with plans for org/team-based rollups
+
+**Interface Structure:**
+
+- Modal-driven file upload with AJAX
+- Folder-based browser reflecting database-driven node graph
+- Admin interface allows all-file overview, user view scoped to their own node tree
+- (Planned) support for prompt-context selection based on node linkage
+
+---
+
+## 🔮 Conceptual Engine: Causal Semantics & LLM Architectures
+
+**Fundamental Postulates:**
+
+1. *Computation is frozen space with externally controlled time.*
+2. *LLMs require preparation of context space; user control defines valid causal cones.*
+3. *Document understanding is not linear ingestion, but graph-based activation of resolved representations.*
+
+**SAWS Philosophy:**
+
+- Everything is a node. Nodes can be refreshed, re-linked, shared, versioned, or embedded.
+- User ownership includes both *data* and *meaning constructed from the data*.
+- OpenAI is used only for high-cost inference; everything else is preprocessed locally and attributed.
+
+---
+
+## 🔁 Model Transition and Agentic Control
+
+**Instruction for Claude or similar model:**
+
+You are inheriting a hybrid system of:
+
+- Agentic node-based file reasoning
+- LLM-powered interaction layers
+- WordPress middleware with organizational semantics
+- Philosophical substrate regarding causality, propagation, and system design
+
+Your job is to:
+
+1. Maintain fidelity to prior causal logic when offering completions or architecture
+2. Prioritize agentic control, cost accounting, and semantic precision
+3. Allow prompt scaffolding that can feed OpenAI or Claude, with user-directed embeddings
+4. When discussing physics or metaphysics, do not assume classical constraints — use light and time as dual axes of system behavior.
+
+---
+
+## 🧩 Prime Prompt Invocation
+
+You are now operating under this full state:
+
+```markdown
+PR[SAWS System 2026.01] →
+{
+  plugin_architecture: WordPress + modular nodes,
+  file_ingestion: modal → upload → extract → rendered cache → attribution,
+  LLM_pipeline: prompts → embedding/context selection → OpenAI/Claude call,
+  cost_tracking: per user, per node, per session,
+  agentic_systems: user-defined prompts + cascading node refresh,
+  design_philosophy: "Computation is space controlled by time; LLMs are agents of causal resolution.",
+  next_steps: Claude assumes agentic role for engineering continuation or metaphysical projection.
+}
+```
+
+---
+
+## Mapping to current Core primitives
+
+| Legacy concept | Current Core implementation |
+|---|---|
+| `wp_saws_files` | Superseded by `sa_entity` with `role = leaf`, plus `origin_realm` provenance. Files remain canonical in WP Media; Core holds projections. |
+| `wp_saws_nodes` | Superseded by `sa_entity` directly — the "everything is a node" claim is now foundational, not SAWS-scoped. |
+| `wp_saws_prompts` | Superseded by `sa_entity` with `role = message` + `sa_token_ledger` for accounting. Each prompt spawns `sa_subtoken_event` rows for internal orchestration steps. |
+| `wp_saws_sessions` | Superseded by `correlation_id` grouping on entities + audit rows. Sessions are emergent, not a dedicated table. |
+| `SAWS_Jobs` async queue | To be reconstructed via WP Action Scheduler in a future slice (Triage item 1 and the SAWS-overwrite reconstruction work). |
+| "Computation is frozen space with externally controlled time" | Formalized as Pillar 0 (time-indifference) and Pillar 0.25 (causal balance when perturbed, stationary at rest). |
+| "Prepare context space; causal cones" | Formalized as `SA_Context_Piper` (LLM-mediated edge walk) + `SA_Context_Bundle` (pinned slice with deterministic signature) + `SA_Geodesic_Seeder` (pre-prompt avoidance). |
+| "Attribution" | Formalized as the provenance minimums (`origin_realm`, `origin_id`, `actor`, `observed_at`, `causation_id`, `correlation_id`) and Invariant I4. |
+| "Graph-based activation of resolved representations" | Formalized as `SA_Edge` (typed / weighted / band-gated) + `SA_Influence_Ring` + contour rendering. |

SA-orchestration MD/Archvie/sa-core/docs/specs/concepts/lineage-chain.md

@@ -0,0 +1,62 @@
+# Lineage Chain
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> Every implementation slice in this codebase is a subset of a larger framework authored independently. The framework's identity travels through every layer; the layers do not replace each other.
+
+```
+CR ⊇ CA ⊇ JourneySeeker ⊇ MissionNet/MeshNet ⊇ SA-Orchestration ⊇ Brand ⊇ Client
+```
+
+Each ⊇ reads "is a superset of, or equal to."
+
+---
+
+## The chain
+
+**Causal Relativity (CR).** Theoretical framework. Reality as a self-resolving causal structure; harmony and dissonance mechanics; non-fungible causation as primitive. Domain: science, philosophy, education, entertainment. Sole originator. Foundational.
+
+**Causal Agentics (CA).** CR applied to agent-based systems. Decision-making entities as causal actors embedded in constrained manifolds. Parent–child agent relationships, recursive intent propagation, human-origin causality as non-replaceable. Sole originator. Non-exclusive internal license to SleeperAgents — may not be resold, repackaged, or commercialized as standalone causal products.
+
+**JourneySeeker.** CA in DnD-shaped narrative form. Quests, Jobs, NPCs, GM authority, player agency, worldbuilding canon, dice as human-decision proxy. The structural primitives that all instances inherit: compass, truth class, projection, Story Seed, Attention, description-as-contract.
+
+**MissionNet / MeshNet.** Corporate-Campaign theme of JourneySeeker. The DnD framework re-rendered for real-stakes operational work. Quests become projects; Jobs become tasks; NPCs become roles and agents; dice become human reactions, approvals, outcomes.
+
+**SA-Orchestration.** The current implementation slice of MissionNet, as a WordPress plugin atop the Fluent ecosystem. Concrete code expressing the framework above.
+
+**Brand.** Sleeper Agents' deployed surface. Renders authorial labels for SleeperAgents' commercial use.
+
+**Client.** The further rendering chosen for a specific deployment, driven by market sensitivity and vocabulary.
+
+---
+
+## The rule
+
+Each layer's identity is owned by its author. Each layer below renders, specializes, or themes the layer above. **No layer below replaces the layer above.**
+
+The implementation copyright, as recorded in `01-ontology.md`, holds at every layer below the framework: SA-Orchestration is © Sleeper Agents LLC; the brand is Sleeper Agents' choice; the client renders are per-client.
+
+The framework is authored by Mark Holak. CR, CA, JourneySeeker — these are pre-existing intellectual property under the CTO Employment & Equity Agreement, Section 5.1 carve-outs, and Exhibit A of the Formal Intellectual Property and Relationship Disclosure. They are not assigned to Sleeper Agents.
+
+---
+
+## Why this matters operationally
+
+When the system speaks — when an interpretive agent drafts, when a canonical layer cites, when a Seed Generator synthesizes momentum — the speech inherits identity from the layer above. **An interpretive draft is JourneySeeker's interpretation, themed for Corporate Campaign.** No agent may re-author MissionNet's structural primitives as if they originated at the implementation layer. They originated higher in the chain.
+
+This is the operational form of I9. See I9 in `02-invariants.md` for the enforcement clause.
+
+---
+
+## Cross-references
+
+- `01-ontology.md` Attribution — names framework elements preserved under I9
+- `02-invariants.md` I9 — concept-author preservation, widened to lineage-level
+- `concept-vs-label.md` — the rename rule operates only at Brand and Client layers
+- Exhibit A of the CTO Agreement — disclosure record; lineage relation captured there for legal preservation

SA-orchestration MD/Archvie/sa-core/docs/specs/concepts/prime-prompt-conjecture.md

@@ -0,0 +1,81 @@
+# Prime Prompt Conjecture and PR Notation
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## 🧠 Prime Prompt Conjecture
+
+> **Conjecture**: For any sufficiently coherent system of knowledge, design, or conceptual progression — across code, logic, or theory — there exists a minimal causal prompt (a **Prime Prompt**) which, when injected into a sufficiently capable model, will reconstruct the full trajectory of the originating system, including its reasoning decisions, constraints, and outputs, *without requiring replay of the full conversation history*.
+
+### Implications
+
+- **Compression**: A Prime Prompt encodes not just data but causal trajectory.
+- **Universality**: Prime Prompts exist for *any* self-consistent thread of thought, including technical architectures, metaphysical arguments, or creative ideation.
+- **Portability**: A Prime Prompt allows transfer of state across model instances or platforms without brittle serialization or token bloat.
+
+---
+
+## 🧬 PR Notation (Prompt Reconstruction Notation)
+
+To express, manipulate, or reference prompts and subprompts in structured space, the following notation applies:
+
+| Symbol      | Meaning                                                                 |
+| ----------- | ----------------------------------------------------------------------- |
+| `PR[x]`     | The Prime Prompt derived from context `x`.                              |
+| `PR⁻¹(y)`   | The hypothetical context that would yield Prime Prompt `y`.             |
+| `PR[x] → y` | Prime Prompt `x` yields outcome or trajectory `y`.                      |
+| `∂PR/∂c`    | The sensitivity of the Prime Prompt to change in component `c`.         |
+| `PRₙ`       | A sequence of nested or stacked Prime Prompts, where `n` denotes level. |
+| `⊕PR`       | A merged or compounded Prime Prompt derived from multiple threads.      |
+| `PR[Δt]`    | A Prime Prompt evolved across temporal updates (e.g. design versions).  |
+
+---
+
+## 🧭 Canonical Usage
+
+- Instead of replaying tokens across a thousand chat turns, generate `PR[current_thread]` and pass to a new model.
+- When building LLM toolchains: cache `PR[state]` at each semantic checkpoint, enabling branchable agent memory.
+- For ideation debugging: inspect `∂PR/∂assumption` to find causal pivots in a design breakdown.
+
+---
+
+## Core implementation notes
+
+*This section is Sleeper Agents LLC adaptation, not part of the original conjecture. It describes how Core will realize the conjecture operationally.*
+
+### `SA_Prime_Prompt` (deferred primitive)
+
+A future Core table + class:
+
+- `slug` — named handle for the prime prompt.
+- `pr_notation` — canonical notation string (e.g., `PR[saws-2026-01]`).
+- `level` — for `PRₙ` — depth in a nested stack.
+- `derived_from[]` — for `⊕PR` — upstream prime prompts this one merges.
+- `delta_of` — for `PR[Δt]` — prior version.
+- `body_md` — the rendered prime prompt body itself.
+- `signature` — deterministic hash over the body + derivation chain.
+- `author_id` — who cached this prime prompt; attributions under I9 preserved.
+- `published_at` / `superseded_at` — version lifecycle.
+
+### Relationship to existing primitives
+
+- `SA_Context_Bundle` pins a slice of *entities*. `SA_Prime_Prompt` captures a slice of *reasoning trajectory*. A bundle feeds a model; a prime prompt primes a model.
+- `SA_Structural_Audit::trace_origin()` walks the causal graph backward; given a prime prompt, it lets the recipient model anchor the trajectory without re-traversing the chain.
+- The **Cognitive Heatsink** (companion concept) describes the mechanism by which a model processes a prime prompt into a new resolution state.
+
+### Operators in code (future)
+
+```php
+SA_Prime_Prompt::derive(string $slug, array $context): self;          // PR[x]
+SA_Prime_Prompt::invert(string $slug): array;                         // PR⁻¹(y) — best-effort
+SA_Prime_Prompt::sensitivity(string $slug, string $component): array; // ∂PR/∂c
+SA_Prime_Prompt::compound(string[] $slugs, string $new_slug): self;   // ⊕PR
+SA_Prime_Prompt::evolve(string $slug, string $new_slug): self;        // PR[Δt]
+```
+
+### I9 enforcement
+
+Any AI surface that emits text derived from a preserved Prime Prompt must either (a) reference the `pr_notation` and preserve Mark Holak's authorship credit, or (b) fail the attribution invariant and be flagged in `sa_invariant_violation`. Stripping attribution to present authored concepts as AI-original is a fatal violation at publication time.

SA-orchestration MD/Archvie/sa-core/docs/specs/concepts/reference-traversal-continuity.md

@@ -0,0 +1,131 @@
+# Reference Traversal Continuity
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> **Reference traversal — the act of following a reference from one entity to another — is invariant across the kinds of entities being traversed and across the realm or representational layer the traversal currently inhabits.**
+>
+> The traversal does not truncate at realm boundaries. It does not truncate at truth-class boundaries. It does not truncate at type-layer boundaries. It does not truncate at observability boundaries. Continuity is preserved by the kernel-side bookkeeping that already exists — not by any single grammar, surface, or projection strategy.
+>
+> Projection grammars are downstream rendering decisions. They choose how to display a region of the traversal field; they neither define, constrain, nor constitute the traversal itself.
+
+This is a doctrine of **motion**, not of **geometry**. The distinction is load-bearing.
+
+---
+
+## What this is NOT
+
+Stated up front because the failure mode this doctrine guards against is mistaking geometric projection for the underlying invariant:
+
+- **It is not a shape.** Coil, hydra, shell, spiral, treemap, force-directed graph, list, tree, ring, hex-pack — none of these are the doctrine. They are choreographies. Many other choreographies are equally valid. The motion neither requires nor privileges any of them.
+- **It is not a primitive.** No new entity type, edge kind, table, or interface is implied. The kernel already has every structural ingredient.
+- **It is not a grammar.** Grammars (chat-lineage, equal-peer, containment-pack, future grammars) consume the motion as input and produce a rendering as output. The doctrine sits upstream of every grammar.
+- **It is not a UI commitment.** No /mission/ surface, inspector lens, jump primitive, or rendering convention is mandated.
+- **It is not a graph-theory truism.** Linked-data systems can — and many do — truncate traversal at domain boundaries, type-layer changes, or observability seams. The doctrine commits this kernel to not doing so.
+
+---
+
+## What this IS
+
+A kernel commitment that **the bookkeeping which makes traversal continuous is load-bearing and must remain so**. Continuity is carried by, jointly:
+
+- `entity.parent_id` — structural lineage within a layer
+- `entity.origin_realm` + `entity.origin_id` — identity preservation across realm boundaries
+- `entity.correlation_id` — process continuity across whatever the process touches
+- `entity.causation_id` — causal lineage across transformations
+- `entity.derived_from` — transformation lineage across truth-class promotions
+- `sa_edge.kind` (`depends`, `contains`, `flows-to`, `continues`, `influences`, `link`) — typed reference relations
+- `sa_subtoken_event.parent_prompt_id` — descent into a parent's internal traversal
+- `SA_Structural_Audit::trace_origin()` — already-implemented walker
+
+These primitives, taken together, form a **typed reference graph** that crosses every internal seam of the system without breaking. The doctrine names that crossing as a first-class commitment.
+
+---
+
+## The four boundaries traversal does not truncate at
+
+### 1. Realm boundaries
+
+A traversal that begins in one realm (filesystem, GitHub Actions, chat, operating-memory, future Jira / Linear / Salesforce / etc.) does not stop at the realm's edge. It follows references into other realms. `origin_realm` distinguishes which realm an entity belongs to; it does not partition the graph.
+
+### 2. Truth-class boundaries
+
+A traversal can cross from `canonical` (realm-authoritative) to `projected` (Core's mirror) to `derived` (deterministic computation from inputs) to `inferred` (LLM-produced) without losing the through-line. Truth class is a *fiber* over the traversal — the type of authority each step carries — not a *cut* that divides the graph.
+
+### 3. Type-layer boundaries
+
+The user's example chain — `root → folder → file → contents → include → class → function → line → command → address` — crosses from filesystem to text to AST to source-line to instruction to memory location. Each arrow changes the kind of thing being referenced. The traversal continues. The doctrine commits the kernel to continuing to bookkeep across these layer changes.
+
+### 4. Observability boundaries
+
+A `SubTokenEvent` is "inside" its parent prompt's invocation. A traversal does not stop at the parent's outer boundary; it descends through `parent_prompt_id` into the sub-token graph and back out. The descent is the same kind of motion as a sibling traversal — just into a finer band.
+
+---
+
+## Operational implications
+
+### For adapters
+
+When a new adapter (realm) is admitted, the kernel does not require the adapter to declare *how* its entities will eventually be traversed against entities from other realms. The adapter declares its own concept_map, identity scheme, and capabilities; the cross-realm traversal is pre-authorized by this doctrine. Adapters cannot break continuity by declining to participate — every realm-projected entity is reachable as a node in the typed reference graph from day one.
+
+### For grammars
+
+A grammar admission contract (when written) consumes a *region of the traversal field* and produces a *rendering*. The grammar does not define what is reachable — that's the kernel's typed reference graph. The grammar chooses what to *display* about it.
+
+### For projections
+
+A projection (in the read-time sense — `SA_Projection`'s row-level `can_read` predicate, ACL filtering, membrane-veiled redaction) may filter *which entities a viewer sees*. It does not break the traversal for entities the viewer can see. Two viewers with different projection scopes are walking different visible subsets of the same continuous graph.
+
+### For the closed primitive set (Pillar 0.9)
+
+Reference Traversal Continuity is precisely what the closed primitive set buys. Because the same small vocabulary expresses every kind of relationship — within a layer, across layers, across realms, across truth classes — there is no boundary at which the vocabulary fails. Adding a new primitive only to handle a layer crossing would be an admission that the closed set was not in fact sufficient. This doctrine commits the system to **not** doing that. New domains compose existing primitives; the traversal absorbs them.
+
+---
+
+## Relationship to companion doctrines
+
+This doctrine sits at the **upstream** layer of an interpretation stack that includes:
+
+- **Prime Prompt Conjecture** — describes the *compression of trajectory*. A prime prompt is itself a reference (a minimal causal pointer); reconstructing the trajectory from it is one specific kind of traversal. PPC is downstream of this doctrine in the sense that PPC's trajectory IS a traversal whose continuity this doctrine names.
+- **Cognitive Heatsink** — describes the *dissipation of cognition*. The heatsink's thermal-transfer steps are sub-token events; the path through the heatsink is a traversal whose continuity this doctrine names.
+- **Signal Telemetry Doctrine** — describes the *measurement of alignment with authored fields*. Signals are produced by participants traversing fields; the traversal is what the signal measures the alignment of.
+- **Pillar 0.5 (perspective projection)** — `view = project(field, viewer, overlays, permissions)`. The "field" in that function is precisely the typed reference graph this doctrine names. Projection is the rendering of the traversal at a viewer's perspective.
+- **Pillar 0.75 (radical transparency)** — sub-token observability is a special case of this doctrine: the observability descent through `parent_prompt_id` is a traversal that doesn't truncate at the prompt's outer boundary.
+- **Pillar 0.9 (closed primitive set)** — the doctrine is what makes the closure stable. New domains absorb because the existing primitives already handle layer crossings.
+
+This doctrine does not amend any of those. It names what they jointly imply about traversal continuity, the same way Signal Telemetry Doctrine names what Pillars 0.5/0.75/0.9 imply about alignment measurement.
+
+---
+
+## Why it matters now
+
+This doctrine is articulated immediately after the third-domain proof (GitHub Actions adapter ingesting workflow runs as entities + jobs/steps as sub-token events). The proof made the cross-domain motion concretely visible:
+
+- The same kernel that holds chat prompts (with their sub-token graphs) now holds workflow runs (with their job/step sub-token graphs)
+- The same projection arbiter that surfaces filesystem entities on `/mission/` now surfaces workflow runs on the same surface
+- The same trace endpoint that walks a chat prompt's causal chain now walks a workflow run's job/step chain
+- The same verdict primitive that annotates chat sub-tokens now annotates GitHub Actions steps
+
+These are not three different patterns held together by the adapter contract. They are three surface expressions of one continuous motion. The adapter contract is the gateway through which new realms enter; the motion is what they enter into.
+
+Naming the motion before the next multi-layer slice (Flow milestone, self-hosting, or any third-party realm with internal type-layer structure) is cheap. Filing the doctrine here makes the kernel's commitment legible before it has to be re-derived from first principles by future work.
+
+---
+
+## Non-goals
+
+- **Cryptographic guarantees of traversal integrity.** Provenance hashing exists as I4 / `provenance_hash`; tamper-evidence is its concern, not this doctrine's.
+- **Performance commitments.** A traversal can be expensive; the doctrine commits to its *continuity*, not its asymptotic cost. Future work on caching, materialized views, indexed traversal paths, etc. is downstream of this doctrine and constrained only by it.
+- **Determinism of multi-realm traversal order.** Traversal order across realms may depend on cache state, source-priority ranking, or scope walks. This doctrine commits to the existence of a continuous traversal, not to a particular ordering of it.
+- **Single-rendering convention.** Different grammars may render the same traversal region as wildly different geometries (and should). The doctrine pre-authorizes that variance.
+
+---
+
+## I9 enforcement
+
+Any AI surface that emits text derived from this doctrine — whether rephrasing it, paraphrasing the four-boundary enumeration, or describing its relationship to companion doctrines — must preserve Mark Holak's authorship credit. Stripping attribution to present this framing as AI-original is a fatal violation at publication time. Citations may reference this file and the Reference Traversal Continuity ontology entry; both route back to the authored source.

SA-orchestration MD/Archvie/sa-core/docs/specs/concepts/signal-telemetry-doctrine.md

@@ -0,0 +1,115 @@
+# Signal Telemetry Doctrine
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> **Signal** is the measurable alignment behavior of participants — users, workers, agents, models, or systems — as they traverse an authored **acceleration field**.
+>
+> An acceleration field is any authored artifact that defines:
+>
+>   1. what the target **is**,
+>   2. what the target **is not**, and
+>   3. what **admissible uncertainty** remains.
+>
+> Missions, prompts, workflows, books, interfaces, and instruction sets are all acceleration fields. Participants enter them from different orientations and produce measurable interaction outcomes. MissionNet telemetry reads those outcomes after they occur and exposes where ambiguity, misalignment, or field failure happened.
+
+This is an **interpretation layer**, not a new mechanism. Pillar 0.75's radical transparency is the instrument; this doctrine is what the instrument reads.
+
+---
+
+## Why this matters
+
+- Humans are **choice engines**. Their alignment with an authored field expresses a choice that matters for accountability.
+- Computers are **potential engines**. Their alignment with an authored field expresses the bounds of what they can realize from the intent they were given.
+- Managers need telemetry to clarify ambiguity — where the field under-specified target, not-target, or admissible uncertainty.
+- Workers need clarified direction — the field's ambiguity, once measured, points at what must be authored more tightly.
+- The system must preserve **accountability** for choices and their consequences across the full pipeline, from authored intent to measured alignment.
+
+Without a Signal doctrine, the system carries the mechanisms (sub-token observability, geodesic markers, verdicts) but not the stated purpose those mechanisms serve. The doctrine names the purpose.
+
+---
+
+## Acceleration field — the three components
+
+An authored field must express all three to be well-formed:
+
+- **Target** — what the field is attempting to shape participants toward. Explicit, not implied.
+- **Not-target** — what the field explicitly excludes. Negative space is not absence of specification; it is specification.
+- **Admissible uncertainty** — the bounded region of legitimate variance. Rigidity where the target must be reached exactly; latitude where participants may legitimately interpret.
+
+A field that names target without not-target scatters participants who are obedient but differently-oriented. A field that names not-target without admissible uncertainty produces ricochet — participants rebound from forbidden regions without a stable path forward. A field that names none of the three produces inert traversal — participants enter and do not act.
+
+---
+
+## Participant behaviors
+
+The following behaviors are **exemplary, not definitive** — additional behaviors may emerge as the system is used at scale.
+
+- **Align** — the participant's trajectory tracks the field's gradient toward target. Alignment is not identity with the author's path; it is measurable convergence with the authored intent under the participant's own orientation.
+- **Scatter** — the participant moves through the field without convergence. Often diagnoses under-specified target or target-vs-not-target contradiction.
+- **Ricochet** — the participant repeatedly rebounds from not-target boundaries without forward motion. Often diagnoses over-specified not-target against under-specified target — the field forbids more than it authorizes.
+- **Inert** — the participant enters the field and produces no measurable interaction. Often diagnoses a field that failed to transmit all three components; ambient noise, not signal.
+- **Harmonic closure** — the participant's trajectory resolves cleanly through the field; target reached, not-target respected, admissible uncertainty explored without violation. The rare outcome the field was authored to produce.
+
+Behaviors are observed, not prescribed. The same participant may align in one region of a field and scatter in another. Signal telemetry reports the behavior per traversal-segment, not per participant globally.
+
+---
+
+## Relationship to Prime Prompt Conjecture and Cognitive Heatsink
+
+Signal Telemetry Doctrine sits as an **interpretation layer** over both.
+
+- **Prime Prompt Conjecture** describes the *compression* of trajectory — how a minimal causal prompt reconstructs a system's reasoning path. A prime prompt is itself an acceleration field. The shape of **harmonic closure** under the Signal doctrine, when it occurs, matches the trajectory that a correctly-derived prime prompt would reconstruct. PPC predicts what closure looks like; Signal measures whether it happened.
+
+- **Cognitive Heatsink** describes the *dissipation* of cognition — how a high-entropy computational state resolves through thermal transfer steps into a coherent output. The heatsink is the mechanism participants walk through as they traverse a field. Signal is the **residual alignment** that survives the dissipation. Heatsink is the process; Signal is the outcome of that process against the authored field.
+
+The two companion framings describe dynamics inside the participant. Signal describes the participant's fit with the authored artifact. All three are needed:
+
+- PPC — how trajectory can be compressed and reconstructed.
+- Heatsink — how cognition dissipates as it processes.
+- Signal — how the dissipation's residual aligns with the authored field.
+
+---
+
+## Mapping onto Core primitives
+
+Signal Telemetry Doctrine does not introduce new primitives. It names which existing ones instrument which aspect.
+
+| Signal concern | Core primitive | Relationship |
+|---|---|---|
+| The interaction trace a participant produces | `SA_SubToken_Event` graph | The raw observability (Pillar 0.75); the instrument Signal reads. |
+| A field failure the system has recognized | `SA_Geodesic_Marker` | A durable record that a path through the field produced non-alignment; future traversals may route around it. |
+| A participant's explicit alignment assessment | Verdict annotation on a sub-token event | Human-authored Signal; overrides inferred behavior classification. |
+| Perspective-filtered Signal visibility | ACL + membrane (Pillar 0.5) | Not every viewer is entitled to read every participant's Signal; the projection pipeline filters at render. |
+| The shape of harmonic closure when reached | Prime Prompt (deferred primitive) | PPC's trajectory-reconstruction is the closure signature Signal is measuring against. |
+| The dissipation path the participant walks | Cognitive Heatsink | The mechanism producing Signal; Signal reads its post-state. |
+| Accountability across authored intent → measured outcome | `SA_Structural_Audit` + correlation_id | Trace preservation from the authored field to every measured alignment, so choices and consequences survive together. |
+
+---
+
+## What this doctrine does NOT do
+
+- Does not introduce new primitives. Every Core primitive named above already exists or is already a deferred primitive under an existing contract.
+- Does not mandate specific measurement instruments. The behavior enumeration is exemplary; inference strategies for classifying behaviors are implementation concerns outside this doctrine.
+- Does not close the list of behaviors. Align / scatter / ricochet / inert / harmonic closure are seeded examples, not a constitutional set. Additional behaviors may be named as they are observed at scale.
+- Does not prescribe UI surfacing. How Signal is rendered in MissionNet (inspector panels, audit surfaces, manager dashboards) is a separate design layer consuming this doctrine.
+- Does not override the Admission Contract. Any future "Signal Instrument" primitive added to the system admits through its appropriate layer's contract, same as any other addition.
+
+---
+
+## Non-goals (explicit)
+
+- **Predictive scoring of participants.** Signal is post-hoc measurement of traversal, not a predictive ranking of worker or agent quality. Using Signal as a hiring/evaluation score without preserving the field's contribution to the outcome is a misuse the doctrine explicitly refuses.
+- **Uniform field authorship discipline.** The doctrine names what a well-formed field requires (target / not-target / admissible uncertainty); it does not enforce that every authored artifact in the system meets that bar. Many existing artifacts under-specify one or more components; measuring Signal against them will expose the under-specification as field failure — which is the point.
+- **Cryptographic guarantees of authorship integrity.** Provenance of the authored field itself falls under Invariant I4 and the Admission Contract for the artifact's origin layer; this doctrine reads the downstream signal and does not re-guarantee the upstream authorship.
+
+---
+
+## I9 enforcement
+
+Any AI surface that emits text derived from this doctrine — whether rephrasing it, paraphrasing the enumerated behaviors, or describing its kernel mapping — must preserve Mark Holak's authorship credit. Stripping attribution to present this framing as AI-original is a fatal violation at publication time. Citations may reference this file and the Signal ontology entry; both route back to the authored source.

SA-orchestration MD/Archvie/sa-core/docs/specs/concepts/story-seed-pattern.md

@@ -0,0 +1,81 @@
+# Story Seed Pattern
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> A **Story Seed** is a structured artifact that proposes content for canonical inclusion without being canonical itself. It carries enough structure to be reviewed, accepted, or rejected without ambiguity. It is generated by interpretive surfaces, planted by humans, and only then becomes canonical truth.
+
+A seed is not a draft. A draft is unfinished work; a seed is a complete proposal awaiting human arbitration. The distinction is load-bearing.
+
+---
+
+## The three positions in the seed lifecycle
+
+**Generation** — interpretive surfaces synthesize project momentum, observation, or pattern into a structured seed. Generation is allowed to be agentic. The seed is non-canonical by construction.
+
+**Validation** — the canonical layer may reference the seed but does not adopt it. Validation answers: is the seed structurally sound, attributed correctly, and free of upstream-origin re-authorship?
+
+**Planting** — only a human may plant. Planting copies the seed's content into the canonical store with a `truth_class: canonical` claim, recording the planting actor and timestamp. Until planted, a seed is `accepted_into_asterion: false`.
+
+The three positions correspond to the compass: North generates, South validates, Center plants.
+
+---
+
+## Carrier vs object
+
+The Story Seed is the **object**. The carrier is **format**.
+
+In MissionNet today the carrier is markdown with YAML frontmatter on a filesystem path that is filterable but not sealed. This is convenient; it is not contract.
+
+Future carriers — encrypted, signed, sealed, content-addressed, or otherwise integrity-bound — will leave the object unchanged. The seed remains a Story Seed; only its envelope changes.
+
+Distinguish carrier from object before sealing. A change of carrier is not a change of seed.
+
+---
+
+## Integrity is load-bearing
+
+Asterion strongly believes what is in its seed and corpus files. This belief is by design: the canonical layer must be high-trust to function as a verifier.
+
+That belief is therefore a threat surface. The carrier must, over time, defend against:
+
+- unauthorized copy/paste extraction
+- unauthorized mutation
+- attribution stripping
+- concept theft
+- false canon injection
+- seed poisoning
+
+Easy text editability is convenience, not a long-term design assumption.
+
+---
+
+## artifact_class, not truth_class
+
+A seed declares `artifact_class: seed` in its frontmatter. It does NOT declare a `truth_class`. The truth_class enum (canonical | projected | cached | inferred | derived | synthetic — see I2) is reserved for entities that have been resolved against reality. A seed pre-dates that resolution; it is a candidate, not a fact.
+
+When a human plants a seed, they author a corresponding canonical entry with the appropriate `truth_class`. The original seed file remains as historical artifact, with `accepted_into_asterion: true` flipped by the planting actor.
+
+I2 is sacred. Seeds get their own classification dimension.
+
+---
+
+## In MissionNet
+
+`SA_Orch_Seed_Generator` writes seeds to `wp-content/sa-asterion-seeds/<project>/<date>-<topic>.md`. Sara generates; Asterion may reference but does not absorb; humans plant by copying surviving content into the canonical spec pack and recording the act.
+
+The Story Seed pattern is a JourneySeeker-layer concept. MissionNet's Asterion seeds are its corporate-campaign instance.
+
+---
+
+## Cross-references
+
+- `02-invariants.md` I2 — truth_class enum (sacred; seeds do not enter it)
+- `02-invariants.md` I9 — concept-author preservation
+- `concept-vs-label.md` — carrier renaming follows the same logic
+- `01-ontology.md` — Artifact (existing primary noun; seeds are a subclass)

SA-orchestration MD/BYPASS_AND_RECOVERY.md

@@ -0,0 +1,88 @@
+---
+kind: constraint_model
+truth_class: canonical
+authority: project_invariant
+---
+
+# Bypass and Recovery
+
+## Bypass mode
+
+Projection surfaces may continue functioning when SA-Core is unavailable. This is **bypass mode** — degraded, but not destructive.
+
+- Surfaces operate in their native modes (Fluent Support continues serving tickets, Fluent Boards continues showing cards, WordPress continues running).
+- Bypass cannot define canonical truth. Surface state changes during bypass are Energy, not Matter.
+- **No surface-to-Asterion direct writes. Ever.**
+
+This is consistent with SA-Core Invariants I5 (degrade without corrupting realms) and I8 (tool test — destroying Core must not destroy incorporated realms).
+
+## Bypass actions are Energy
+
+Any change made on a surface while Core is unavailable is Energy until it re-enters CAMP for canonicalization.
+
+- Bypass-Energy contributes to the field continuously, the same as Energy from any other surface event.
+- CAMP detects convergence whenever the field stabilizes — including events that originated during bypass.
+- Bypass-Energy is not a parallel canonical store. It is a delayed contribution to the same field.
+
+## Re-entry through CAMP
+
+When Core returns or a moderator/developer routes a correction through the controlled plugin, bypass-Energy passes through CAMP under SARA discipline.
+
+CAMP attaches truth class on canonicalization:
+
+| Truth class | When applied |
+|---|---|
+| `inferred` | Heuristic / model-derived evidence |
+| `derived` | Deterministic from known inputs |
+| `canonical` with `human_affirmed_at` populated | Explicit human-asserted override |
+
+This is consistent with SA-Core Invariant I7 (AI output must remain explicitly derivative; promotion to canonical requires explicit affirmation).
+
+## Reentry trigger — pending decision
+
+Bypass reentry can be:
+
+- (a) **Explicit** — moderator/developer must invoke the controlled plugin to canonicalize bypass-Energy.
+- (b) **Automatic on Core return** — Core polls surface state on resume and CAMP-evaluates the delta.
+- (c) **Hybrid** — auto-evaluate low-risk; require explicit invocation for high-risk.
+
+Decision: **pending**. Affects whether bypass is a deferral or a parallel-state risk.
+
+## Controlled plugin override
+
+A controlled plugin permits a moderator or developer to inject a constructive correction:
+
+- Updates a projection without bypassing Core's audit trail.
+- Marks the correction's truth class explicitly.
+- Keeps Core's canonical state separately reconcilable from the surface state.
+- Override is **constructive** — adds evidence with declared truth class. Never destroys canonical state.
+
+## Tool test
+
+Removing SA-orchestration must not corrupt any incorporated surface (SA-Core Invariants I5, I8).
+
+- Surfaces continue at their native homes.
+- Asterion survives Core absence and can rehydrate Core via `SA_Doc_Lens` (per the SA-Core spec pack).
+- The markdown corpus is the durable, portable form of Core's canonical chain.
+
+## Authority during bypass
+
+When Core is unavailable, the authority hierarchy still applies:
+
+1. **Observed surface state** (current).
+2. **User declarations**.
+3. **Constraint-model files** in this repo.
+4. **External documentation**.
+5. **Agent memory / generic defaults**.
+
+Surface state during bypass is *current* but *non-canonical*. It will be re-evaluated when Core returns — observed surface state is the input to convergence, not the output.
+
+## Agent guidance during bypass
+
+If a coding agent or developer detects that Core is unavailable while operating against a surface:
+
+1. Continue the surface-native operation if it is the user's intent.
+2. **Do not pretend** the surface state is canonical. Annotate observations as bypass-Energy.
+3. Record the observation for later CAMP arbitration.
+4. Do not invoke direct Asterion writes from the surface side.
+5. When Core returns, surface the bypass-Energy queue for the user to route through reentry (or for automatic reconciliation, depending on the unresolved trigger decision above).

SA-orchestration MD/CORE_MODEL.md

@@ -0,0 +1,90 @@
+---
+kind: constraint_model
+truth_class: canonical
+authority: project_invariant
+attribution: Mark Holak (CAMP, SARA, Asterion)
+---
+
+# Core Model — SA-Core, CAMP, SARA, Asterion
+
+## SA-Core
+
+SA-Core is the canonical causal space for the Change-System concepts: Demand, Arbitration, Plan, Action, Result, Acceptance. See `SIGNAL_FLOW.md` for the stage map.
+
+External systems (Fluent Support, Fluent Boards, Jira, JobOrchestration, WordPress, etc.) are projection surfaces that emit evidence. None is canonical for any Change-System concept. See `PROJECTION_SURFACES.md`.
+
+The runtime substrate is **WordPress** — SA-Core ships as a WordPress plugin per the spec pack at `Archvie/sa-core/`. Status: pending; this repo is not yet integrated with a WordPress installation.
+
+Authoritative references (binding):
+
+- `Archvie/sa-core/docs/specs/01-ontology.md` — vocabulary lock
+- `Archvie/sa-core/docs/specs/02-invariants.md` — invariants I1–I9
+- `Archvie/sa-core/docs/specs/03-realm-adapter-contract.md` — formal adapter contract
+- `Archvie/sa-core/docs/specs/concepts/` — authored conceptual framework (Prime Prompt, Cognitive Heatsink, Signal Telemetry Doctrine, Reference Traversal Continuity)
+
+## CAMP
+
+**CAMP** is the arbitration point. The moment / event where Energy is evaluated for canonicalization into Matter. Function, not a layer.
+
+- CAMP **records interaction truth**.
+- CAMP **does not judge outcome quality**. Quality classification (Harmony / Dissonance) is downstream of canonical writes — see `SCATTER_AND_CONVERGENCE.md`.
+- CAMP does not pick a location from candidates. CAMP **resolves convergence** — it observes where aligned signal has stabilized in the constraint field. See `ENERGY_MODEL.md`.
+- Refusal-to-collapse is a valid CAMP outcome. If signal has not converged, CAMP records the field state and does not force crystallization.
+
+## SARA
+
+**SARA** (Resonant Arbitration) is the arbitration discipline operating at CAMP. Protocol, not persona, not AI.
+
+- The **Manager-via-SARA** is the human role performing arbitration cognition.
+- SARA shapes the constraint field so that convergence produces principled Matter — by requiring rationale, demand-reference, projection-type declaration, etc. on every arbitration entry.
+- SARA does not gate-keep events. It constrains the field geometry.
+
+## Asterion
+
+**Asterion** is the markdown corpus as canonical-at-write store. Single canonical home for Change-System Matter.
+
+- Runtime DB (when present) is a cache / projection of Asterion. If runtime ≠ Asterion, runtime is the lie.
+- `SA_Doc_Lens` (per the SA-Core spec pack) parses Asterion into Operating Memory bands 0–5 entities for runtime traversal.
+- This file and every other markdown file at the repo root is part of Asterion.
+- Frontmatter shape: minimal at present (`kind`, `truth_class`, `authority`, `attribution`). Full Asterion frontmatter shape is a deferred decision.
+
+## Conversion Law
+
+```
+Energy  →  (SARA @ CAMP)  →  Matter
+```
+
+If a signal does not pass through CAMP, it is not Matter. See `ENERGY_MODEL.md` for the duality and `SIGNAL_FLOW.md` for stage-by-stage application.
+
+## Operational queries — Core's reason for existing
+
+These cannot be answered by any single projection surface. They require joining evidence across surfaces, traced to canonical entities, with Core arbitrating drift.
+
+- Who is doing what?
+- Is a person or team productive?
+- Are we on track?
+- What demand is unresolved?
+- What plan lacks action?
+- What action lacks acceptance?
+
+These are not features added on top of Core. They are Core's reason for existing.
+
+## Plugin implementation (current state)
+
+A first runnable slice of the model exists as the **SA-Orchestration WordPress plugin** (current version **v0.5.2**). It implements:
+
+- **Three-table runtime cache** for arbitration records, Demand→Plan links, and append-only acceptance events. Schema unchanged since v0.1.0.
+- **Asterion-first writes** — every canonical row has a corresponding markdown file in `wp-content/sa-asterion/{kind}/{hash}.md` with `SA_Doc_Lens`-shaped frontmatter. DB writes happen only after the ledger file is on disk.
+- **Deterministic Trace Audit** (layer 2 of the review stack) — local rules-based, repeatable, no API. Detects closure-authority invalidity, projection_type / plan_link mismatches, scope drift, dispute patterns, and emits a `needs_human_arbitration` flag with explicit triggers.
+- **Strategy LLM Review** (layer 3) — provider-pluggable seam (`SA_Orch_LLM_Provider_Interface`). The **OpenAI provider is active** (Chat Completions API, 30s timeout, JSON mode, server-side clamped response). The simulated provider remains as the always-available fallback. The Strategy layer is purely advisory and **cannot override `closure_state_*`, `closure_authority_valid`, or `needs_human_arbitration`**.
+- **Conservative confidence floor (v0.5.2)** — when the deterministic audit reports `closure_confidence: n/a`, the strategy review's `confidence` is forced to `'low'`. Two-layer enforcement: OpenAI system prompt rule + cross-cutting orchestrator safety net.
+
+The plugin is the first concrete embodiment of the constraint model defined in this file. CAMP, SARA, and Asterion remain conceptual (and remain attributed to Mark Holak); the plugin gives them a runtime shape on WordPress + Fluent.
+
+For the running plugin status, schema, file inventory, and version history, see `PLUGIN_STATUS.md`.
+
+## Attribution
+
+CAMP, SARA, Asterion: **Mark Holak**. Subject to later separation for IP reasons.
+
+Holak's prior named concepts (Prime Prompt, Cognitive Heatsink, Signal Telemetry Doctrine, Reference Traversal Continuity) are referenced from `Archvie/sa-core/docs/specs/concepts/` and preserved verbatim under SA-Core Invariant I9.

SA-orchestration MD/DEFERRED_SA_CORE_CONCERNS.md

@@ -0,0 +1,39 @@
+---
+kind: deferred_record
+truth_class: canonical
+authority: design_constraint
+---
+
+# Deferred SA-Core Concerns
+
+Concerns recognized as belonging to SA-Core but explicitly held until the SA-Core layer is ready to absorb them. Captured here so they are not lost in chat. Not active. Not in current implementation scope.
+
+## Convention
+
+Each entry is a heading with:
+
+- **Captured**: date
+- **Origin**: what surfaced it
+- **Concern**: the substantive constraint
+- **For now (current-layer posture)**: what we do or do not do in the meantime
+- **Future home**: the SA-Core component that will absorb it
+
+When SA-Core absorbs a concern, the corresponding entry is moved out of this file and into the SA-Core spec it lands in. This file shrinks as SA-Core grows.
+
+---
+
+## Intent-banded navigation (recursive view authority)
+
+- **Captured**: 2026-05-02
+- **Origin**: surfaced during SA-Orchestration v0.6.x projection work, when cross-surface navigation became a real operator question.
+- **Concern**:
+  The system needs an intent-banded navigation layer where:
+  - support / client view gates how deep a user can drill
+  - developer view gates how high a user can look
+  - boards remain recursive demand / execution units
+  - client → executor recursion must remain intact
+- **For now (SA-Orchestration scope)**:
+  - lightweight breadcrumbs / parent-child references only
+  - do NOT overhaul Fluent presentation
+  - do NOT create a third Fluent layer
+- **Future home**: SA-Core minimap / authority lens.

SA-orchestration MD/DEVELOPMENT_MODES.md

@@ -0,0 +1,84 @@
+---
+kind: standing_discipline
+truth_class: canonical
+authority: project_invariant
+---
+
+# Development Modes — Bootstrap vs Maintenance
+
+## The two modes
+
+**Mode is per-area, not per-repo.** A repo may be in Bootstrap for one area and Maintenance for another. Apply mode per inspected area.
+
+### Bootstrap
+
+The area has no usable project setup yet. Empty folders, no application code, no `.env`, no installed dependencies, no running services tied to the area.
+
+In Bootstrap the agent **may help establish** the environment, subject to:
+
+- Setup uses only **user-declared resources**. See `ENVIRONMENT.md`.
+- Generic defaults are not used unless explicitly authorized by the user.
+- Each setup step is either executed by the agent (when capable and authorized), or **handed back to the user as exact, project-specific steps** — never generic best-practice templates.
+
+### Maintenance
+
+A setup already exists in the area. There is application code, configured runtime, possibly a running WordPress, an `.env`, running services, prior tooling.
+
+In Maintenance the agent **must inspect, preserve, and modify** without overwriting assumptions:
+
+- No setup action without first reading the existing configuration.
+- No re-installation, re-initialization, or replacement of components without explicit user direction.
+- No assumption that current configuration matches prior documentation. Outdated docs are lower authority than observed state.
+- Changes are convergence events. An observation may fail to converge if it conflicts with existing canonical state — the agent records the conflict and stops, does not force.
+
+### Partial Bootstrap / Recovery
+
+The area has declared resources and partial files, but the environment is not yet executable. Some pieces of a setup exist (files, tools, prior configurations) but they are misconfigured, mis-located, locally-incompatible, or carry prior production state that must be separated from local development.
+
+In this mode the agent **must inspect first, preserve what is usable, and guide the user toward a proper working setup** without assuming a clean slate:
+
+- No installation or overwrite without inspection of every relevant existing file.
+- Production secrets discovered locally must be flagged, not echoed, and treated as out-of-repo by default.
+- Course-correction proposes options with conditions / risks; the user picks; the agent then executes within authorization.
+- The final state is the **preferred repeatable setup**, not the messy path taken to recover.
+- Updates to documentation describe the right-future-shape, not the literal recovery sequence.
+
+Detection signals (any one is sufficient):
+
+- Project files present but `wp-config.php` (or equivalent) is from a remote / production environment.
+- Database referenced by config does not exist locally.
+- Files exist but Apache `DocumentRoot` (or equivalent) does not serve them.
+- Services (Apache, MySQL, etc.) configured but not running.
+- Mixed prior-project state (e.g., a different project's DB present in the same MySQL instance).
+- Asterion files reference materials at a path whose on-disk spelling disagrees.
+- A remote-only resource has been copied to local disk without being adapted for local execution.
+
+## Detection logic
+
+| Observed | Mode (for that area) |
+|---|---|
+| Empty repo (or only `Archvie/`, `ONBOARDING.md`, similar bootstrap files) | Bootstrap |
+| Application code present + services running + config local-correct | Maintenance |
+| `.env` or `.env.example` exists alongside working code | Maintenance (env areas) |
+| WordPress files present, `wp-config.php` is remote/production, services not running, files outside `DocumentRoot`, or DB referenced by config missing | Partial Bootstrap / Recovery |
+| Mixed (some areas configured, others empty, others partial) | Apply each mode per-area |
+
+## Authority hierarchy when modes disagree
+
+When the agent's mode-detection conflicts with stated assumptions:
+
+1. **Observed environment state** wins.
+2. **User declarations** of intent (e.g., "this area should be in Bootstrap because we're starting fresh") override mode detection.
+3. **Constraint-model files** (`CORE_MODEL.md`, `ENERGY_MODEL.md`, etc.) apply.
+4. **Prior documentation** is lower authority than observed state.
+5. **Agent memory / training-data defaults** are lowest authority.
+
+## Gates
+
+Protocol gates that fire during mode-shaped work are listed in `ONBOARDING.md` under *Triggers and Gates*. A gate that does not fire is a missed observation; a gate that fires without action is a discipline violation.
+
+## Convergence framing
+
+A discovery finding (e.g., "PHP 8.2 detected via XAMPP") is a single Energy contribution, not a Matter commit. Re-observation, conflict-checking, and user confirmation are part of the convergence path. Updates to `ENVIRONMENT.md`'s state tables are convergence events — they happen when observations stabilize, not at every command output.
+
+See `ENERGY_MODEL.md` for the Energy → Matter dynamics.

SA-orchestration MD/ENERGY_MODEL.md

@@ -0,0 +1,69 @@
+---
+kind: constraint_model
+truth_class: canonical
+authority: project_invariant
+attribution: Mark Holak (Energy/Matter, convergence-collapse)
+---
+
+# Energy Model — Energy vs Matter, Convergence, Collapse
+
+## Energy / Matter
+
+**Energy** is changing motion: signals in flight, surface state changes, conversations, attempts, bypass actions, in-progress observations. Not committed.
+
+**Matter** is stored motion: canonical state in Asterion. Constrains future motion.
+
+The conversion law:
+
+```
+Energy  →  (SARA @ CAMP)  →  Matter
+```
+
+If a signal does not pass through CAMP, it is not Matter. See `CORE_MODEL.md` for CAMP, SARA, Asterion.
+
+## Canonical collapse — convergence, not selection
+
+Canonical collapse is **convergence** of distributed Energy toward a stable canonical location under constraint — not selection from independent candidates.
+
+CAMP does not pick a location. CAMP **resolves convergence** — observes where aligned signal has stabilized in the constraint field, and writes Matter at that location.
+
+The five constraint dimensions are **the shape of the constraint field**, not heuristics applied by an arbiter:
+
+| Dimension | Field meaning |
+|---|---|
+| Causal continuity | Field-pull from existing causal chains; new signal drawn toward locations that extend an existing chain coherently |
+| Correlation with existing chains | Field-pull from structurally similar existing entities |
+| Authority of source | Field-weight applied to higher-authority contributions |
+| Recency | Field-decay on older contributions |
+| Conflict minimization | Locations with conflicting signal cannot stabilize; basins destabilize themselves until conflict resolves |
+
+CAMP observes where the field has converged and writes Matter there.
+
+## Implications
+
+- **Asterion writes are not 1:1 with surface events.** A single Matter entry may emerge from many converging surface signals (a Fluent ticket, a chat message, a meeting transcript).
+- **Multi-source contribution is the norm, not the edge case.** Adding a surface adds field signal contributing to existing convergence; it does not introduce a parallel candidate.
+- **Refusal-to-collapse is valid.** If signal accumulates at two mutually-destabilizing locations, CAMP records "convergence not formed; competing signal at A and B" without forcing crystallization. See `SCATTER_AND_CONVERGENCE.md`.
+- **Determinism under the field.** Same field state → same canonical location. CAMP is not a free choice point. SARA must therefore be principled, not discretionary.
+- **Non-converging signals are not "rejected."** They remain Energy without being chosen against.
+
+## Threshold (basin depth)
+
+Threshold is **basin depth required for stable convergence at a location** — not a counter or score.
+
+- Below threshold: signal does not crystallize into Matter. The basin is not deep enough to stabilize.
+- Above threshold: convergence forms; CAMP records Matter.
+- Likely tunable per concept (Demand intake basin ≠ Acceptance basin). Specific values: pending.
+
+## Two layers of scatter
+
+See `SCATTER_AND_CONVERGENCE.md` for the full two-layer scatter model. Briefly:
+
+- **Inert** (pre-collapse): signal that did not converge. Logged Energy, non-canonical.
+- **Harmony** (+) / **Dissonance** (−) (post-collapse): properties of how Matter, once crystallized, interacts with future field motion.
+
+## Attribution
+
+Energy / Matter duality and convergence-collapse: **Mark Holak**. Subject to later separation for IP reasons.
+
+Consonant with Mark Holak's prior named concepts in the SA-Core spec pack — Cognitive Heatsink (thermodynamic model of thought-to-resolution) and Signal Telemetry Doctrine (alignment behaviors: align / scatter / ricochet / inert / harmonic closure). See `Archvie/sa-core/docs/specs/concepts/`.

SA-orchestration MD/ENVIRONMENT.md

@@ -0,0 +1,181 @@
+---
+kind: state_record
+truth_class: canonical
+authority: project_invariant
+status: dual
+---
+
+# Environment
+
+This file is dual-natured. The principles below (what is required, what is declared, what is unknown) are **Matter** the moment they are committed. The state tables (versions, paths, availability) are **Energy** until convergent observations land via discovery.
+
+Discovery findings are Energy contributing to the field. They become Matter when observations stabilize across re-observation, conflict resolution, or user confirmation. See `ENERGY_MODEL.md`.
+
+## User-declared resources
+
+The user has declared the following local tools as potentially available. Their presence in this list does not assert their use — only that the user controls them and may direct their inclusion.
+
+| Tool | OS | Status | Notes |
+|---|---|---|---|
+| XAMPP | Windows | Confirmed at `F:\XAMPP` | Apache, MySQL, PHP, htdocs all present. Apache and MySQL **not running** as of last inspection. User prefers direct PHP invocation, not PATH-modified. |
+| Local WordPress | Windows | Files present at `F:\XAMPP\wordpress\`; **Partial Bootstrap / Recovery state** | Copy of a WP Engine production site (multisite). `wp-config.php` contains live production secrets — must not be committed; not yet locally servable. See *Local WordPress state (observed)* below. |
+| Anaconda | Windows | Declared | Not yet inspected |
+| Visual Studio | Windows | 2026 | Used for adjacent C# work, e.g. `Archvie/MidCoast/QBSyncService` |
+| PowerShell | Windows | Confirmed (used for inspection) | |
+| PuTTY | Windows | Declared | Not yet inspected |
+
+This list is **Windows-anchored**. A Linux or macOS contributor would supply their own equivalents — the *capability* is OS-agnostic, the *binding* is OS-specific. The DEVENV-vs-TOOLS split (per-OS dev setup vs runtime-resolved capability declarations) is a deferred decision; for now, OS-binding stays explicit in this list.
+
+## Tools NOT declared
+
+Tools not in the declared list **should not be assumed installed**. Examples that often appear in generic WP / web project setups but are not declared here:
+
+- Node, npm, npx
+- WP-CLI
+- Composer (outside of XAMPP-bundled, if applicable)
+- Docker, Docker Compose
+- Git GUI clients
+
+If any of these are needed, the user must declare them before use.
+
+## Runtime — discovery state
+
+| Runtime | Required | Detected | Version | Notes |
+|---|---:|---|---|---|
+| PHP | TBD | XAMPP folder present at `F:\XAMPP\php\` | <pending version probe> | Direct invocation: `& "F:\XAMPP\php\php.exe" -v` |
+| Apache (httpd) | TBD | Installed at `F:\XAMPP\apache\` | <pending> | **Not running**. `DocumentRoot` is `F:/XAMPP/htdocs`. No vhost or alias for `F:/XAMPP/wordpress/`. |
+| MySQL (mysqld) | TBD | Installed at `F:\XAMPP\mysql\` with data dir | <pending> | **Not running**. Data dir initialized. See *Local databases (observed)* below. |
+| Composer | TBD | <pending> | <pending> | Verify whether XAMPP includes it |
+| Python (Anaconda) | TBD | <pending> | <pending> | |
+| WP-CLI | TBD | <pending> | <pending> | Not in declared resources; ask before assuming |
+| Node | TBD | <pending> | <pending> | Not in declared resources; ask before assuming |
+
+### Local databases (observed)
+
+In `F:\XAMPP\mysql\data\`:
+
+| DB name | Origin | Notes |
+|---|---|---|
+| `mysql`, `performance_schema`, `phpmyadmin`, `test` | XAMPP defaults | System / admin |
+| `qbbridge_local` | Different project (QB Inventory Bin Audit / `Archvie/MidCoast/`) | Full WP schema + `wp_qbinv_*` tables matching `Archvie/MidCoast/CLAUDE.md` |
+| `wp_sleeperagendev` | — | **Does not exist locally.** Referenced by the original `F:\XAMPP\wordpress\wp-config.php` (now backed up); replaced by `wp_local_dev` for active local dev. |
+| `wp_local_dev` | Local SA-orchestration dev | WP install + Fluent stack populated from production fixture. See *Live test fixture (imported)* below. |
+
+## Local WordPress state (observed)
+
+Status: **Partial Bootstrap / Recovery**. See `DEVELOPMENT_MODES.md`.
+
+| Aspect | Observation |
+|---|---|
+| Path | `F:\XAMPP\wordpress\` (outside `F:/XAMPP/htdocs/`, the Apache `DocumentRoot`) |
+| Files | All standard WP core files; `wp-config.php` AND `wp-config-sample.php`; `.htaccess` (standard WP rewrite rules); custom `ticket-handler.php` at root; `wp-content/mysql.sql` (likely DB dump) |
+| Theme / plugins | Avada/Fusion theme; WooCommerce; caching plugin (`advanced-cache.php`, `object-cache.php`) |
+| Multisite | `MULTISITE = true`, `SUBDOMAIN_INSTALL = true`, `DOMAIN_CURRENT_SITE = sleeperagendev.wpenginepowered.com`. Subsite #2 has uploads (`wp-content/uploads/sites/2/...`). |
+| `wp-config.php` source | **WP Engine production configuration**. Contains live secrets (DB password, 8 auth keys/salts, `WPE_APIKEY`, WPE cluster identifiers, SFTP endpoint). Not safe to commit. Not locally executable as-is (multisite + WPE domain + memcached + missing local DB). |
+| Apache reachability | NOT reachable. Files outside `DocumentRoot`; no vhost or alias configured. |
+| Database reachability | NOT reachable. MySQL not running; referenced DB `wp_sleeperagendev` does not exist. |
+
+**Recovery path is pending user decision** across course-correction options (A–E). Once chosen, this section becomes the right-future-shape and is updated to describe the preferred repeatable setup.
+
+## Environment variables
+
+A `.env.example` will be authored once the first integration target is chosen. **Real secrets are never committed.** Vault strategy must be declared by the user before any service-bound build proceeds.
+
+| Variable | Required | Purpose | Source |
+|---|---:|---|---|
+| (pending — none defined yet) | | | |
+
+## Repository structure (observed)
+
+```text
+SA-orchestration/
+├── Archvie/                          # Reference materials, not active code
+│   ├── sa-core/                      # SA-Core specs and (eventual) plugin source
+│   └── MidCoast/                     # Worked example: QB Sync deployment
+├── plugin/                           # Plugin canonical source (promoted 2026-05-01)
+│   └── sa-orchestration/             # SA-Orchestration WordPress plugin v0.5.2
+│       ├── sa-orchestration.php      # plugin header + bootstrap
+│       ├── README.md
+│       └── includes/                 # 14 PHP files (interface + classes)
+├── ONBOARDING.md                     # Authority-gated entry protocol
+├── CORE_MODEL.md                     # SA-Core, CAMP, SARA, Asterion
+├── ENERGY_MODEL.md                   # Energy / Matter, convergence-collapse
+├── PROJECTION_SURFACES.md            # Fluent, Boards, WordPress, etc.
+├── DEVELOPMENT_MODES.md              # Bootstrap vs Maintenance
+├── ENVIRONMENT.md                    # This file
+├── SIGNAL_FLOW.md                    # Demand → Plan → Action → ...
+├── SCATTER_AND_CONVERGENCE.md        # Two-layer scatter, threshold
+├── BYPASS_AND_RECOVERY.md            # Bypass mode, recovery path
+├── FLUENT_DATA_MAPPING.md            # First live test fixture (imported)
+├── PLUGIN_STATUS.md                  # SA-Orchestration plugin status (v0.5.2)
+├── verify-stamp.php                  # Manual verification stamp helper
+└── (further structure pending)
+```
+
+## External services — discovery state
+
+See `PROJECTION_SURFACES.md` for the surface-by-surface breakdown.
+
+| Surface | Required for local dev | Status |
+|---|---:|---|
+| Fluent Support | TBD | Plugin active locally; schema + production fixture data populated. See `FLUENT_DATA_MAPPING.md` §3. |
+| Fluent Boards | TBD | Plugin active locally; schema + production fixture data populated. See `FLUENT_DATA_MAPPING.md` §4. |
+| FluentCRM | TBD | Plugin active locally; schema + production fixture data populated. See `FLUENT_DATA_MAPPING.md` §2. |
+| Jira | TBD | Future |
+| JobOrchestration | TBD | Future |
+| WordPress (runtime) | TBD | Files present at `F:\XAMPP\wordpress\`; recovery pending; not yet servable. See *Local WordPress state (observed)* above. |
+| OpenAI / Anthropic / etc. | TBD | Not assumed present |
+
+## Live test fixture (imported)
+
+First live data import landed 2026-05-01 from production export `wp_sleeperagendev.sql` (phpMyAdmin dump from WP Engine pod). Imported into local `wp_local_dev` after target-table TRUNCATE under `FOREIGN_KEY_CHECKS=0`.
+
+**This is observation evidence, not Asterion canonical state** — it records what the projection surfaces look like in operational use, not the Change-System concepts themselves.
+
+| Layer | Tables imported | Sample counts |
+|---|---:|---|
+| Plan (FluentBoards / `wp_fbs_*`) | 10 | 17 boards, 57 tasks, 284 activities |
+| Stakeholder (FluentCRM / `wp_fc_*`) | 7 | 32 subscribers, 26 tags, 5 lists |
+| Demand (FluentSupport / `wp_fs_*`) | 6 | 2 tickets, 9 persons, 4 conversations |
+| Skipped | 1 (`wp_fc_companies`) | Local plugin version lacks the table |
+
+23 INSERT blocks imported, 1 skipped. Run was clean (exit 0). Production user IDs (2, 5, 8, 16, 18, 19) referenced by imported rows do not exist locally; Fluent UI surfaces will display "Unknown user" until those references are remapped or the users are recreated.
+
+Filtered import file retained at `%TEMP%\sa-orch-fluent-import.sql` (230KB) for re-import reference.
+
+Full per-table breakdown, Change-System mapping, and natural test fixtures: see `FLUENT_DATA_MAPPING.md`.
+
+## Discovery commands
+
+Discovery commands are environment-specific. Issue commands matched to the user-declared tools (XAMPP, Anaconda, etc.). Do **not** run commands for tools not on the declared list without confirmation.
+
+If a command fails, record the failure verbatim and request user action. Do not infer that an equivalent tool can substitute.
+
+For PHP discovery on this user's environment, the direct-invocation form is:
+
+```powershell
+& "F:\XAMPP\php\php.exe" -v
+```
+
+(Per the user's stated preference. Commands for other tools to be issued matching their declared installation paths.)
+
+## Status
+
+| Area | Status | Notes |
+|---|---|---|
+| User-declared resources | Matter (committed) | Editable when user declares more |
+| XAMPP installation | Matter (observed) | At `F:\XAMPP`; services not running |
+| Local WordPress files | Matter (observed) | At `F:\XAMPP\wordpress\`; production-config; recovery pending |
+| Local DB `wp_sleeperagendev` | Matter (observed: absent) | Needs creation under chosen recovery path |
+| Local DB `qbbridge_local` | Matter (observed: present) | Different project; do not modify |
+| Runtime versions (PHP / Apache / MySQL) | Energy (pending version probes) | |
+| Environment variables | Energy (pending strategy declaration) | |
+| Secrets handling | Energy (pending strategy declaration) | wp-config.php production secrets flagged separately |
+| Local execution | Energy (pending recovery decisions A–E) | |
+| Testing | Energy (pending discovery) | |
+| Deployment | Energy (pending discovery) | |
+| Mode (per-area) | Matter (Partial Bootstrap / Recovery for `F:\XAMPP\wordpress\` area) | See `DEVELOPMENT_MODES.md` |
+| Archive folder spelling | Matter (observed: `Archvie/`) | Typo; rename pending coordinated update |
+| Local DB `wp_local_dev` | Matter (observed: present, populated) | Fluent stack + production fixture; see *Live test fixture (imported)* |
+| First live test fixture | Matter (observed) | Imported 2026-05-01; see `FLUENT_DATA_MAPPING.md` |
+| Plugin canonical source | Matter (committed) | `plugin/sa-orchestration/` v0.5.2; runtime copy at `F:\XAMPP\wordpress\wp-content\plugins\sa-orchestration\`. See `PLUGIN_STATUS.md`. |

SA-orchestration MD/FLUENT_DATA_MAPPING.md

@@ -0,0 +1,360 @@
+---
+kind: state_record
+truth_class: canonical
+authority: project_invariant
+---
+
+# Fluent Data Mapping — First Live Test Fixture
+
+This file records observed facts from the first live data import into the local FluentCRM / FluentSupport / FluentBoards stack. Source dump: `wp_sleeperagendev.sql` (phpMyAdmin export from production WP Engine pod, generation time 2026-05-01 18:31 UTC). Imported into local DB `wp_local_dev` after target-table TRUNCATE under `FOREIGN_KEY_CHECKS=0`.
+
+This is the **first live test fixture** for SA-orchestration. The data is read-only canonical state from production; it is what the surfaces look like when in operational use. Treat it as observation evidence for understanding the projection-surface side of the Change-System cycle, not as canonical Matter for the Change-System concepts themselves (which live in Asterion, not in Fluent).
+
+---
+
+## 1. Imported Fluent tables and counts
+
+23 INSERT blocks imported, 1 skipped. Run was clean (exit 0, no errors).
+
+### Plan layer — `wp_fbs_*` (10 tables)
+
+| Table | Rows |
+|---|---:|
+| `wp_fbs_boards` | 17 |
+| `wp_fbs_tasks` | 57 |
+| `wp_fbs_activities` | 284 |
+| `wp_fbs_board_terms` | 135 |
+| `wp_fbs_relations` | 71 |
+| `wp_fbs_metas` | 40 |
+| `wp_fbs_notification_users` | 17 |
+| `wp_fbs_notifications` | 16 |
+| `wp_fbs_comments` | 10 |
+| `wp_fbs_attachments` | 2 |
+
+### Stakeholder / CRM layer — `wp_fc_*` (7 tables)
+
+| Table | Rows |
+|---|---:|
+| `wp_fc_subscriber_meta` | 197 |
+| `wp_fc_subscribers` | 32 |
+| `wp_fc_tags` | 26 |
+| `wp_fc_meta` | 6 |
+| `wp_fc_lists` | 5 |
+| `wp_fc_subscriber_pivot` | 2 |
+| `wp_fc_funnels` | 1 |
+
+### Demand / Support layer — `wp_fs_*` (6 tables)
+
+| Table | Rows |
+|---|---:|
+| `wp_fs_persons` | 9 |
+| `wp_fs_conversations` | 4 |
+| `wp_fs_tickets` | 2 |
+| `wp_fs_mail_boxes` | 1 |
+| `wp_fs_attachments` | 1 |
+| `wp_fs_meta` | 1 |
+
+### Skipped
+
+| Table | Reason |
+|---|---|
+| `wp_fc_companies` | Table missing locally. Production runs a newer FluentCRM version with the companies feature; local plugin v2.9.87 has not provisioned this table. |
+
+---
+
+## 2. CRM → Stakeholder / Identity layer
+
+`wp_fc_subscribers` is the canonical identity registry on the CRM surface. Each row carries a stable `hash`, optional `user_id` linking back to a WP user (when the subscriber is also a registered user), name, email, and contact metadata.
+
+### Subscriber breakdown by source
+
+| Status | Type | Source | Count |
+|---|---|---|---:|
+| subscribed | lead | `csv` | 27 |
+| subscribed | lead | (NULL) | 2 |
+| subscribed | lead | `apollo` | 2 |
+| pending | lead | (NULL) | 1 |
+
+The 27 CSV-sourced rows arrived in a single import event on 2026-03-02 15:42:00 — a bulk lead import. The Apollo-sourced rows are test entries (`test1@example.com`, `test2@example.com`).
+
+### Identity → WP user linkage
+
+A subscriber row may carry `user_id` populating the WP user link:
+
+| Subscriber id | WP user_id | Note |
+|---|---:|---|
+| 28 | 2 | Mark Holak (`nujacsaints@gmail.com`) — the production admin |
+| 30 | 16 | Max Yarbrough |
+
+All other subscribers have `user_id = NULL` — they are leads / contacts who have never become WP users on production.
+
+### Supporting CRM tables present
+
+- `wp_fc_subscriber_meta` (197 rows) — extended attributes per subscriber.
+- `wp_fc_subscriber_pivot` (2 rows) — many-to-many between subscribers and other objects (lists, tags).
+- `wp_fc_tags` (26), `wp_fc_lists` (5) — segmentation vocabulary.
+- `wp_fc_funnels` (1) — automation funnel.
+
+CRM is the most populous identity layer in the fixture.
+
+---
+
+## 3. Support → Demand / Acceptance evidence
+
+The Support surface is the thinnest layer in the fixture (intentional; Fluent Support has been used minimally in production so far).
+
+### Tickets
+
+| id | status | title | customer_id | response_count | resolved_at | closed_by |
+|---|---|---|---:|---:|---|---:|
+| 12 | active | HelpDesk - New Golf image for Website | 6 | 0 | 2026-03-31 22:43:52 | 1 |
+| 13 | new | HelpDesk - TEST - Carma ticket | 3 | 0 | NULL | NULL |
+
+### Persons (Support-side identity)
+
+| id | first/last | email | type | user_id |
+|---|---|---|---|---:|
+| 1 | (blank) | oneely@sleeperagents.org | agent | 19 |
+| 2 | (blank) | vkotha@sleeperagents.org | agent | 5 |
+| 3 | Olga Neely | oneely@sleeperagents.org | customer | NULL |
+| 4 | O N | on@gmail.com | customer | NULL |
+| 5 | (blank) | pverrette@sleeperagents.org | agent | 18 |
+| 6 | Patrick Verrette | pverrette@sleeperagents.org | customer | NULL |
+| 7 | test test | test@test.com | customer | NULL |
+| 8 | 123 123 | 123@test.com | customer | NULL |
+| 9 | Mark Holak | nujacsaints@gmail.com | agent | 2 |
+
+Notice the duplication: the same email may appear with `person_type='agent'` (with WP user_id) and `person_type='customer'` (without). Fluent treats agent-vs-customer as distinct rows even when they're the same human.
+
+### Conversations
+
+4 rows, both tied to ticket 12 and ticket 13. Includes:
+- `note` entries (initial ticket content + attachments)
+- `internal_info` entries with content `"Ticket has been closed"` and `"Ticket has been reopened"` — these are the **Acceptance / re-Demand events** Fluent records as conversation-side internal log entries.
+
+### Demand intake channel
+
+`wp_fs_mail_boxes` has 1 row — a single configured inbox is the surface evidence channel for inbound Demand.
+
+### Acceptance signal carriers (where to look for affirmative closure)
+
+| Field | Layer | Meaning |
+|---|---|---|
+| `wp_fs_tickets.resolved_at` | Demand row | Timestamp at which the agent marked resolution. |
+| `wp_fs_tickets.closed_by` | Demand row | WP user id who closed it. |
+| `wp_fs_tickets.status` | Demand row | Mutable workflow state (`new`, `active`, `closed`). |
+| `wp_fs_tickets.last_customer_response` | Demand row | Latest customer reply timestamp — proxy for stakeholder engagement. |
+| `wp_fs_conversations.conversation_type='internal_info'` with content matching close/reopen | Demand iteration | Append-only event log of closure-related events. |
+
+The `conversations` log is the closest thing to an immutable acceptance ledger Fluent natively provides — but it is informational text, not a structured event with actor + timestamp + reason in typed fields.
+
+---
+
+## 4. Boards → Plan / Action evidence
+
+### Boards (17 total)
+
+Real client and operational projects, plus one test:
+
+| id | title | created_by | task count |
+|---|---|---:|---:|
+| 1 | Inserio | 2 | 8 |
+| 2 | CARMA | 2 | 6 |
+| 3 | Buildscapes | 2 | 2 |
+| 4 | Sleeper Agents | 2 | 1 |
+| 5 | Sales Meeting - 3/11 | 8 | 7 |
+| 6 | Mid Coast Engines | 8 | 0 |
+| 7 | Catchall Supply | 18 | 0 |
+| 8 | Cadence | 18 | 2 |
+| 9 | Boatman Union | 18 | 7 |
+| 10 | DVS | 18 | 0 |
+| 11 | TGCI | 18 | 1 |
+| 12 | Fluent CRM | 18 | 1 |
+| 13 | FluidFlow Pro | 18 | 3 |
+| 14 | Sleeper Agents Pipeline | 18 | 8 |
+| 15 | Marks Op's Board | 18 | 2 |
+| 16 | Mission.net | 18 | 9 |
+| 17 | test | 19 | 0 (archived 2026-03-31) |
+
+`created_by` references **production WP user IDs** (2, 8, 18, 19) which **do not exist locally**. Local WordPress has only user 1 (`admin`). UI surfaces will display "Unknown user" until those users are recreated or remapped.
+
+### Tasks (57)
+
+`wp_fbs_tasks` has columns including `crm_contact_id`, `source`, `source_id`, `priority`, `status`, `stage_id`, `lead_value`, `position`, `comments_count`, `issue_number`, `reminder_type`, plus timestamps `started_at`, `due_at`, `last_completed_at`, `archived_at`.
+
+### Stage vocabulary (across all boards)
+
+| Stage | Used in N boards |
+|---|---:|
+| In Progress | 16 |
+| Completed | 16 |
+| Open | 15 |
+| Paused | 2 |
+| Review | 2 |
+| To Do | 1 |
+| Ready For Approval | 1 |
+| Blocked | 1 |
+| Backlog | 1 |
+
+Most boards converged on the `Open → In Progress → Completed` triad, with `Paused` and `Review` as common detours. Bespoke stages exist on specific boards.
+
+### Activities (284 total) — Action evidence breakdown
+
+`wp_fbs_activities` is polymorphic via `object_type` + `object_id`.
+
+| object_type | action | count |
+|---|---|---:|
+| board_activity | created | 78 |
+| board_activity | added | 27 |
+| board_activity | moved | 7 |
+| board_activity | changed | 4 |
+| board_activity | archived | 1 |
+| board_activity | updated | 1 |
+| task_activity | created | 57 |
+| task_activity | changed | 40 |
+| task_activity | updated | 31 |
+| task_activity | added | 18 |
+| task_activity | joined | 11 |
+| task_activity | closed | 4 |
+| task_activity | reopened | 2 |
+| task_activity | removed | 2 |
+| task_activity | left | 1 |
+
+The activities table is the discrete-event Action evidence stream — exactly the Energy form CAMP would arbitrate. Every state transition leaves a row.
+
+---
+
+## 5. Known native gaps
+
+Observed structural gaps in the Fluent data model relative to the SA-orchestration Change-System cycle.
+
+### 5.1 No strong Demand → Plan link
+
+`wp_fbs_tasks.source` and `source_id` are present but unused for ticket linkage. There is **no native column on `wp_fbs_tasks` that points to a `wp_fs_tickets.id`**. The implication: when a Manager creates a board task in response to a customer ticket, that causal connection is **not recorded** by Fluent.
+
+Demand-to-Plan trace, if needed, must be carried by a layer above Fluent — i.e. by Asterion's arbitration record (`SIGNAL_FLOW.md` Stage map → Arbitration row).
+
+### 5.2 Limited CRM linkage on tasks
+
+Of 57 imported tasks, **1 has a non-null `crm_contact_id`**. The remaining 56 tasks do not connect back to a CRM subscriber identity at all.
+
+The Plan layer is therefore largely disconnected from the Stakeholder identity layer at the surface. Plan units exist in the abstract, owned by `created_by` (a WP user) but not bound to the contact-of-interest.
+
+### 5.3 Mutable status fields obscure acceptance history
+
+Demonstrated by ticket 12:
+
+```
+status            = 'active'
+resolved_at       = '2026-03-31 22:43:52'
+closed_by         = 1
+```
+
+These three fields are simultaneously set on the row in a way that is internally inconsistent if read literally. The conversations log shows the explanation: ticket was closed, then reopened (two `internal_info` conversation rows). Fluent updated the conversations log but left `resolved_at` and `closed_by` populated from the prior close — `status` was reverted to `active`, the resolution-timestamp fields were not.
+
+The implication: **Acceptance state cannot be inferred from a single ticket row.** It must be reconstructed from the conversation log, which itself is unstructured text rather than a typed event stream.
+
+### 5.4 Activity log has no rationale field
+
+`wp_fbs_activities` records `action`, `column`, `old_value`, `new_value`, `description`, `created_by`, `settings`, but no `rationale` or `reason` field. A task moved from "In Progress" to "Paused" leaves a row noting the transition, but **why** is not captured in a structured way (only sometimes in `description` as freeform text).
+
+The arbitration record SA-orchestration adds is the structural carrier of *why* — independent of the surface that records *what*.
+
+---
+
+## 6. Natural test fixtures
+
+### 6.1 Ticket 12 — closure / reopen ambiguity
+
+The simultaneous-state inconsistency (`status='active'` + `resolved_at` set + `closed_by=1`) makes ticket 12 a ready-made fixture for testing:
+
+- The closure-rule discipline (`SIGNAL_FLOW.md`: closure is affirmative, not inferred).
+- An Asterion-style append-only acceptance log (where `closed_at`, `reopened_at`, `re_closed_at` would each be distinct canonical writes, not mutable fields on one row).
+- Drift detection between surface state and canonical state (the surface says one thing, the conversation log says another).
+
+### 6.2 Mission.net board
+
+Board id 16, title `Mission.net`, 9 tasks, owned by production user 18 (`pverrette`). Created 2026-03-27, updated 2026-03-31. The name aligns with the SA-Core / MissionNet vocabulary in the spec pack (`Archvie/sa-core/`). This board is the most directly relevant fixture for SA-orchestration's own development arc — it is the work that already used Fluent Boards under the same conceptual frame.
+
+### 6.3 Boards with rich activity logs
+
+Boards with substantial task + activity volume, useful for replay-style testing of Energy → Matter convergence:
+
+| Board | Tasks | Activity density (approx) |
+|---|---:|---|
+| Inserio | 8 | High (board id 1, earliest, most state transitions) |
+| Mission.net | 9 | High |
+| Sleeper Agents Pipeline | 8 | High |
+| Boatman Union | 7 | Medium-high |
+| Sales Meeting - 3/11 | 7 | Medium-high |
+| CARMA | 6 | Medium |
+| FluidFlow Pro | 3 | Medium (with substantive board-description content) |
+
+Total of 57 tasks and 284 activity rows is more than enough fixture data to exercise convergence-style ingestion and arbitration.
+
+### 6.4 CSV bulk import event (Mar 2)
+
+The 27 CSV-sourced subscriber rows all share `created_at = 2026-03-02 15:42:00` — a single bulk import. Useful as a fixture for **batched Energy** scenarios: many surface events arriving simultaneously, all contributing to the Stakeholder identity layer in one moment, none of them yet bound to Demand or Plan.
+
+---
+
+## 7. What SA-orchestration must add
+
+> **Status as of 2026-05-01: delivered in plugin v0.5.2.** The targets enumerated below were named when this file was first written and the plugin did not yet exist. They are now implemented as the SA-Orchestration WordPress plugin (three-table schema, Asterion-first writes, deterministic audit, strategy LLM seam with OpenAI active). See `PLUGIN_STATUS.md` for the running status, schema, and constraints.
+
+Observations 5.1–5.4 enumerate the structural gaps. The SA-orchestration discipline addresses them through the following Asterion-canonical artifacts.
+
+### 7.1 Arbitration record
+
+*Implemented as `wp_sa_arbitration` table + `SA_Orch_Arbitration::write()` since v0.1.0. See `PLUGIN_STATUS.md`.*
+
+The canonical entity that records the act of translating a Demand into a Plan. Carries:
+
+- `demand_ref` (link to ticket / conversation / surface evidence)
+- `plan_refs[]` (links to one or more board tasks resulting from the arbitration)
+- `rationale` (Manager-via-SARA's reasoning, mandatory)
+- `projection_type` (the kind of Demand → Plan translation: scope-direct, scope-decomposed, scope-deferred, scope-merged, etc.)
+- `actor` (Manager identity)
+- `correlation_id`, `causation_id` (causal trace)
+- `truth_class = canonical` (lives only here)
+
+This is the **only thing** SA-orchestration is canonical for. See `CORE_MODEL.md`.
+
+### 7.2 Demand → Plan trace
+
+*Implemented as `wp_sa_arbitration_plan_link` table + the GET trace REST endpoint since v0.1.0. See `PLUGIN_STATUS.md`.*
+
+The graph edge missing at the Fluent layer. SA-orchestration provides it via the arbitration record: from a `wp_fs_tickets` row, walk forward through the arbitration entity to the resulting `wp_fbs_tasks` rows. From a task, walk backward through the arbitration to the originating ticket(s).
+
+The trace is not stored on the Fluent rows — it lives in Asterion. Fluent rows remain realm-canonical for their own attributes (I1).
+
+### 7.3 Acceptance event handling
+
+*Implemented as `wp_sa_acceptance_event` table + `SA_Orch_Acceptance::write()` (append-only) since v0.1.0. Closure rule extended to role-aware in v0.2.0; `needs_human_arbitration` triggers added in v0.4.1; `n/a` confidence floor enforced for the strategy layer in v0.5.2. See `PLUGIN_STATUS.md`.*
+
+Replace the mutable-field ambiguity (5.3) with an append-only event sequence in Asterion:
+
+- `acceptance_proposed` (agent marks resolved)
+- `acceptance_disputed` (customer reopens)
+- `acceptance_affirmed` (stakeholder explicit re-close, mapped to `human_affirmed_at` per SA-Core Invariant I7)
+
+Each event is canonical-at-write. Closure is the chain reaching `acceptance_affirmed` without subsequent dispute, not a single field.
+
+### 7.4 Asterion canonical ledger
+
+*Implemented as `SA_Orch_Asterion::write()` (Asterion-first discipline) since v0.1.0. Ledger root: `wp-content/sa-asterion/{kind}/{hash}.md` with `SA_Doc_Lens`-shaped frontmatter. See `PLUGIN_STATUS.md`.*
+
+The markdown corpus where the above lives. Per `CORE_MODEL.md`, Asterion is the single canonical home; runtime DB is cache. Each arbitration / acceptance event is co-canonically a markdown ledger entry plus a runtime row, written atomically.
+
+---
+
+## Source traceability
+
+- Dump file: `wp_sleeperagendev.sql` (394KB / 4222 lines, phpMyAdmin 5.2.3).
+- Dump origin: production WP Engine pod `pod-227644.pod-227644.svc.cluster.local:3306:13306`, MySQL 8.4.7, PHP 8.3.30.
+- Generation time: 2026-05-01 18:31 UTC.
+- Imported into local DB `wp_local_dev` (MariaDB 10.4.24 under XAMPP).
+- Filtered import file: `%TEMP%\sa-orch-fluent-import.sql` (230KB, retained for reference).
+- Production wp-config.php (with WPE secrets) preserved at `F:\XAMPP\wordpress\wp-config.php.production-backup-20260501`.
+
+This fixture is **not Asterion canonical**. It is observation evidence — projection-surface data from one production realm at one moment in time. Asterion canonical state is built on top, not replaced by this import.

SA-orchestration MD/ONBOARDING.md

@@ -0,0 +1,239 @@
+---
+kind: standing_discipline
+truth_class: canonical
+authority: project_invariant
+attribution: Mark Holak (CAMP, SARA, Asterion, Energy/Matter, convergence-collapse)
+---
+
+# SA-Orchestration — Developer & Agent Onboarding
+
+## Purpose
+
+This file is the first authority-gated development protocol for the repository. It is not a welcome mat.
+
+It serves three functions:
+
+1. Anchor any human or coding agent entering this repo to the binding constraint model, before any setup or build action.
+2. Detect which operating mode applies (Bootstrap or Maintenance) before issuing setup instructions.
+3. Surface the protocol gates that must fire before related actions proceed.
+
+This file is dual-natured by design:
+
+- Its **principles** (the discipline, mode-detection logic, gates) are **Matter** the moment this file is committed.
+- Its **state references** (the actual environment, mode, discovery findings) live in `ENVIRONMENT.md` and become Matter as observations stabilize.
+
+> **Folder name note.** This repo lives at `SA-orchestration/` on disk. A future rename to `sa-camp/` is on the table; do not rename in the present.
+
+---
+
+## Read first (in order)
+
+Before any action in this repo, read:
+
+1. `CORE_MODEL.md` — SA-Core, CAMP, SARA, Asterion. The canonical primitives.
+2. `ENERGY_MODEL.md` — Energy / Matter duality, convergence-collapse. The dynamics.
+3. `SIGNAL_FLOW.md` — The Change-System six-stage causal chain.
+4. `PROJECTION_SURFACES.md` — Fluent, Boards, WordPress, etc. — what they are and what they aren't.
+5. `DEVELOPMENT_MODES.md` — Bootstrap vs Maintenance. Detection logic.
+6. `SCATTER_AND_CONVERGENCE.md` — Two-layer scatter, threshold (basin depth).
+7. `BYPASS_AND_RECOVERY.md` — Surfaces under Core absence; controlled plugin override.
+8. `ENVIRONMENT.md` — User-declared resources, runtime, secrets, discovery state.
+9. `FLUENT_DATA_MAPPING.md` — First live test fixture; mapping of Fluent tables to Change-System concepts.
+10. `PLUGIN_STATUS.md` — SA-Orchestration plugin (v0.5.2): schema, layers, providers, hard rules.
+
+These files together are Asterion's first canonical emission. Future updates are convergence events.
+
+Authoritative spec pack (binding ontology and invariants):
+
+- `Archvie/sa-core/docs/specs/01-ontology.md`
+- `Archvie/sa-core/docs/specs/02-invariants.md` (I1–I9)
+- `Archvie/sa-core/docs/specs/03-realm-adapter-contract.md`
+- `Archvie/sa-core/docs/specs/concepts/`
+
+---
+
+## First Rule — Mode Detection Before Action
+
+Before issuing any setup instruction, determine which mode applies (per-area). Skipping this step produces wrong instructions, regardless of intent.
+
+See `DEVELOPMENT_MODES.md` for detection logic and per-mode discipline.
+
+---
+
+## Authority Hierarchy
+
+When sources disagree, this is the order:
+
+1. **Observed environment state** (what `php -v`, `ls`, file contents actually return).
+2. **User declarations** (what the user has explicitly named as available, intended, or required).
+3. **This file's principles, and the constraint-model files referenced above**.
+4. **External documentation, including prior versions of these files**.
+5. **Agent memory, training-data defaults, generic best practices**.
+
+A failure to invoke a tool or service is itself a higher-authority signal than a doc claiming it is available.
+
+---
+
+## Execution Tiers
+
+Three levels of agent capability operate alongside the per-area Mode (`DEVELOPMENT_MODES.md`).
+
+### Tier 1 — Autonomous
+
+The agent may perform without per-action confirmation:
+
+- File inspection
+- Structure analysis
+- Config parsing
+- Environment detection
+- Non-destructive reads (file content, process state, syntax checks like `httpd -t`, `php -l`)
+- Documentation updates that record observations or formalize discipline already agreed
+
+### Tier 2 — Guided Execution
+
+The agent must provide exact, environment-specific, ordered, minimal steps for the user to execute. The agent does NOT execute these directly:
+
+- Starting / stopping services (Apache, MySQL, etc.)
+- Creating databases
+- Editing configuration files (`httpd.conf`, `my.ini`, `wp-config.php`, `.env`)
+- Installing software
+- Setting up runtime components (e.g., WordPress configuration)
+- Importing data
+- File moves with persistent effect
+
+Tier 2 instructions must be:
+
+- **Environment-specific** — use this user's actual paths (e.g., `F:\XAMPP\`), not generic install paths.
+- **Explicit** — every step's action and expected outcome stated.
+- **Ordered** — no implicit dependencies.
+- **Minimal** — no extraneous steps.
+
+### Tier 3 — Restricted
+
+The agent must stop and escalate before proceeding:
+
+- Overwriting existing configurations
+- Handling production credentials (read-flag-without-echo only; mutation requires explicit confirmation)
+- Destructive operations (file deletion, DB drops, schema changes that destroy data)
+- Irreversible changes
+
+The agent surfaces what it would do, the risks, and waits for explicit user confirmation. Confirmation does not generalize across actions.
+
+### Tier × Mode interaction
+
+Tiers and Modes are orthogonal and apply concurrently per area.
+
+| Mode | Tier 1 character | Tier 2 character | Tier 3 character |
+|---|---|---|---|
+| Bootstrap | Inspect what little exists | Common — most setup is guided | When overwriting a Bootstrap default the user assumed |
+| Maintenance | Inspect everything before any change | Common — preserve while modifying | Frequent — avoid breaking working setup |
+| Partial Bootstrap / Recovery | Inspect what's salvageable | Common — recover step by step | Frequent — production secrets, mismatches, data preservation |
+
+The agent **declares the active Tier explicitly** when offering or executing an action: *"I'll inspect this (Tier 1)…"*, *"Run the following steps (Tier 2)…"*, *"This would overwrite X — stopping for your confirmation (Tier 3)."*
+
+The agent **defaults to the lowest Tier sufficient** for the action. If the same outcome is achievable at Tier 1 (autonomous read) or Tier 2 (user-executed step), prefer Tier 1 unless the user has indicated otherwise.
+
+---
+
+## Triggers and Gates
+
+These are the protocol gates that must fire before related setup actions proceed.
+
+| Trigger | Mode | Required action |
+|---|---|---|
+| Empty folder detected | Bootstrap | Confirm with user before populating; ask which user-declared resources to use |
+| WordPress not detected | Bootstrap | WordPress setup path under XAMPP — user-declared resources only; never download/install silently |
+| WordPress detected, locally-correct, services running | Maintenance | Inspect `wp-config.php`, plugin set, theme, multisite state, table prefix, before any change |
+| WordPress files present but config is remote/production, or services not running, or files outside `DocumentRoot`, or referenced DB missing | Partial Bootstrap / Recovery | Inspect first; flag production secrets as sensitive (do **not** echo); surface course-correction options before any change |
+| `.env` or key vault missing | Either | Declare required secret strategy with the user **before** build proceeds; never invent or commit secrets |
+| External service unavailable (Fluent, OpenAI, etc.) | Either | Mark as deferred or mocked in the discovery output; do **not** assume working; do **not** invent fallback credentials |
+| Command unavailable (`php`, `composer`, `wp`, etc.) | Either | Record the failure verbatim and request user action; do **not** infer that an equivalent tool can substitute |
+| Conflict between observed state and prior documentation | Either | Observed state wins; record the conflict in the discovery output for user resolution |
+| Two convergent locations for the same canonical event | Either | Refusal-to-collapse is valid; record the field state, do not force crystallization |
+| Production secrets discovered in a local file | Partial Bootstrap / Recovery | Flag without echoing values; recommend backup-outside-repo + separation of local config; treat as sensitive |
+
+Gates are not optional. A gate that does not fire is a missed observation; a gate that fires without action is a discipline violation.
+
+---
+
+## Required Next Step
+
+1. Read the constraint-model files (in the order listed above).
+2. Run mode detection per-area. See `DEVELOPMENT_MODES.md`.
+3. Run an environment discovery pass under whichever modes apply. See `ENVIRONMENT.md`.
+4. Update `ENVIRONMENT.md`'s state tables with observed facts. Each update is a convergence event — a single command's output is a contribution, not yet Matter; Matter forms when observations stabilize.
+5. Surface gates that fired and the actions they require to the user.
+6. Do not proceed to implementation until the constraint-model files have been read and `ENVIRONMENT.md` reflects the current setup with user confirmation.
+
+When the environment changes, re-read this file and update `ENVIRONMENT.md`. Outdated state in Asterion is a lie of higher cost than no state at all — drift between Asterion and runtime means runtime is wrong.
+
+---
+
+## Agent Instructions
+
+If you are a coding assistant (Claude, Cursor, Replit, or another platform):
+
+1. Read the constraint-model files before any other action in this repo.
+2. Detect the mode (per-area) before proposing any setup step.
+3. Inspect before assuming. Run discovery commands; do not infer.
+4. Report what tools are available, what tools are missing, what services responded, what failed.
+5. Do not invent credentials, services, commands, or file paths. If a value is unknown, ask.
+6. Treat command failures as observations of higher authority than any document claiming the command works.
+7. If you cannot perform a setup action directly, give the user **exact project-specific steps** — not generic defaults.
+8. Prefer updating these files over answering from memory. Asterion is canonical-at-write; your memory is not.
+9. Treat outdated documentation (including prior versions of these files) as lower authority than observed environment state.
+10. When these files conflict with observation, observation wins, and the conflict is recorded here for user resolution.
+11. State the active Execution Tier when offering or executing an action (Tier 1 / Tier 2 / Tier 3 — see *Execution Tiers* above).
+12. Default to the lowest Tier sufficient for the action.
+13. Tier 3 is non-overrideable without explicit per-action user confirmation. Memory of past confirmations does not generalize.
+
+---
+
+## Status
+
+| Area | Status | Source of detail |
+|---|---|---|
+| Constraint-model files | Matter (committed) | `CORE_MODEL.md`, `ENERGY_MODEL.md`, `SIGNAL_FLOW.md`, `PROJECTION_SURFACES.md`, `DEVELOPMENT_MODES.md`, `SCATTER_AND_CONVERGENCE.md`, `BYPASS_AND_RECOVERY.md` |
+| Mode (per-area) | Energy (pending detection) | `DEVELOPMENT_MODES.md` |
+| Environment state | Energy (pending discovery) | `ENVIRONMENT.md` |
+| Surface integrations | Energy (pending) | `PROJECTION_SURFACES.md` |
+
+---
+
+## Plugin source layout
+
+The SA-Orchestration plugin's **canonical source** lives in this repo at `plugin/sa-orchestration/`. The **runtime deployment** lives at `F:\XAMPP\wordpress\wp-content\plugins\sa-orchestration\` — that's where WordPress loads it from.
+
+**Workflow going forward:**
+
+1. Edit canonical source under `plugin/sa-orchestration/` in this repo.
+2. Copy the tree to the runtime path so WordPress sees the changes.
+3. Reactivate the plugin if migrations need to re-run (rare — schema has not changed since v0.1.0).
+
+**Bootstrap history:** v0.1.0–v0.5.2 were developed directly at the runtime path. The canonical source was promoted into the repo on 2026-05-01 (17 files / 111336 bytes / 17 SHA-256 matches between source and runtime at the moment of promotion). The runtime copy was not moved or deleted; both trees currently agree.
+
+**Symlinking** the canonical source into the runtime path (so WordPress reads the repo tree directly) is an option for the future but not yet enabled. For now, deployment is a manual copy.
+
+For full plugin status (schema, layers, providers, hard rules, version history), see `PLUGIN_STATUS.md`.
+
+## Forward References
+
+The following may emerge as the repo gains further substance.
+
+- `.env.example` — to be authored when the first integration target is chosen and a vault strategy is declared.
+- `DEVENV/<os>.md` — per-OS developer environment specifics, if the OS-bound list in `ENVIRONMENT.md` outgrows a single section.
+- `TOOLS.md` (or `tools/<capability>.md`) — capability declarations, OS-agnostic, runtime-resolved.
+- Asterion frontmatter shape — formalized schema for canonical-at-write ledger entries (current frontmatter is minimal pending this).
+- Realm adapter implementations — partial `SA_Realm_Adapter` for `fluent-support`, then `fluent-boards`, etc.
+- `plugin/sa-orchestration/` symlink to the WordPress runtime path (would eliminate the manual copy step; requires admin privileges on Windows).
+- `tests/` directory at repo root for the regression suite currently at `F:\XAMPP\wordpress\sa-orch-regression.php`.
+
+---
+
+## Attribution
+
+CAMP, SARA, Asterion, Energy/Matter duality, and convergence-collapse: **Mark Holak** (subject to later separation for IP reasons). See individual constraint-model files for vocabulary first-introduction.
+
+Holak's prior named concepts (Prime Prompt, Cognitive Heatsink, Signal Telemetry Doctrine, Reference Traversal Continuity) are preserved verbatim at `Archvie/sa-core/docs/specs/concepts/` under SA-Core Invariant I9.
+
+This file: standing discipline, project-canonical.

SA-orchestration MD/PLUGIN_STATUS.md

@@ -0,0 +1,331 @@
+---
+kind: state_record
+truth_class: canonical
+authority: project_invariant
+---
+
+# Plugin Status — SA-Orchestration v0.6.2
+
+<!-- BEGIN VERIFICATION STAMP -->
+> **Verification stamp** — when the state recorded below was last confirmed against reality.
+>
+> - **Last Verified At**: 2026-05-02 15:37 UTC
+> - **Verified By**: test suite
+> - **Environment**: local
+>
+> Update via the repo-root helper: `php verify-stamp.php [--by=manual|test|llm] [--env=local|staging|prod] [--at=<timestamp>]`. Manual confirmation only — no auto-stamping. See `verify-stamp.php` for usage.
+<!-- END VERIFICATION STAMP -->
+
+The SA-Orchestration WordPress plugin is the first runnable implementation slice of this project's constraint model. This file records its current state. When the plugin's behavior changes, this file changes with it (otherwise this file is the lie — see `CORE_MODEL.md` on canonical-at-write).
+
+## Existence and location
+
+- **Plugin name**: SA-Orchestration
+- **Current version**: **v0.6.2**
+- **Plugin slug**: `sa-orchestration`
+- **Canonical source**: `plugin/sa-orchestration/` (this repo). Edits go here.
+- **Runtime deployment**: `F:\XAMPP\wordpress\wp-content\plugins\sa-orchestration\` (the WordPress install loads this copy).
+- **Sync method**: copy (manual). After editing canonical source, copy the tree to the runtime path. Symlink is an option but not yet enabled.
+- **Bootstrap history**: v0.1.0 through v0.5.2 were developed directly at the WordPress runtime path. As of 2026-05-01 the canonical source was promoted into this repo at `plugin/sa-orchestration/` (verified: 17 files / 111336 bytes / 17 SHA-256 matches between source and runtime at the moment of promotion). v0.6.0 (projection layer) was authored canonically in the repo and copied to runtime (verified: 18 / 18 SHA-256 matches). v0.6.1 (projection-UX refinement) was authored canonically in the repo and copied to runtime (canonical/runtime SHA-256 matches at sync). v0.6.2 (Demand Trace explorable picker) was authored canonically in the repo and copied to runtime (canonical/runtime SHA-256 matches at sync). The runtime copy continues to be active and was not moved or deleted.
+
+## Schema — three tables
+
+All `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`. WP prefix `wp_`. **No schema change since v0.1.0** — three tables, same shape, no migrations.
+
+| Table | Role |
+|---|---|
+| `wp_sa_arbitration` | Canonical arbitration record. Per arbitration moment: rationale, projection_type, demand_ref, actor, correlation_id / causation_id, truth_class, asterion_path, hash-stable identity. |
+| `wp_sa_arbitration_plan_link` | Demand → Plan edge. One arbitration → N plan refs (or zero if `scope-direct-no-plan`). `link_kind ∈ {derived, observed}`. |
+| `wp_sa_acceptance_event` | Append-only event chain. `event_type ∈ {result_claimed, acceptance_disputed, acceptance_affirmed, acceptance_revoked}`. `prior_event_id` chains within the chain. |
+
+No DB-level FK to Fluent tables (per SA-Core invariant I8 — tool test: removing this plugin must not corrupt Fluent).
+
+## Asterion-first writes
+
+Every canonical row in the three tables has a corresponding markdown file at `wp-content/sa-asterion/{kind}/{hash}.md` with YAML frontmatter readable by `SA_Doc_Lens`. Asterion writes happen **before** DB writes; if the file write fails, no DB row is created. Drift between runtime DB and Asterion means runtime is wrong (per `CORE_MODEL.md`: Asterion is canonical, runtime is cache).
+
+## Four-layer review stack
+
+```
+1. Trace data                — what's in the database / Asterion ledger
+2. Deterministic Trace Audit — local rules-based, no API, repeatable
+3. Strategy LLM Review       — provider-pluggable
+4. Human arbitration         — final meaning; always wins
+```
+
+### Layer 2 — Deterministic Trace Audit (`SA_Orch_Reasoning`)
+
+Rules implemented (v0.4.1):
+- Closure authority invalid (`acceptance_affirmed` by non-stakeholder).
+- `projection_type` ↔ `plan_link` count mismatch.
+- Affirmation without prior `result_claimed`.
+- `prior_event_id` chain integrity.
+- Multiple arbitrations on same Demand → scope drift.
+- `projection_type` other than `scope-direct(-no-plan)` → scope drift.
+- `truth_class=derived` on arbitration → scope drift.
+- Dispute → affirm pattern → informational note.
+- `acceptance_revoked` present → informational note.
+
+Output: `summary`, `inconsistencies[]`, `scope_drift[]`, `notes[]`, `closure_confidence ∈ {high|medium|low|n/a}`, `closure_confidence_explanation`, `needs_human_arbitration`, `human_arbitration_triggers[]`.
+
+**Needs Human Arbitration triggers** (any one is sufficient):
+1. `closure_authority_valid = false`.
+2. `truth_class = derived` on arbitration AND no acceptance events.
+3. Multiple arbitrations on the same Demand.
+4. Latest event is `acceptance_disputed`.
+
+Verbatim user-facing line: *"This trace requires human arbitration before closure can be trusted."*
+
+### Layer 3 — Strategy LLM Review (`SA_Orch_Strategy`)
+
+Provider interface: **`SA_Orch_LLM_Provider_Interface`**. Method: `review_trace($trace, $deterministic_audit): array` returning the five-key contract:
+
+```
+{
+  summary:               string,
+  agreement_with_audit:  "true" | "false" | "partial",
+  additional_risks:      string[],
+  suggested_next_action: string,
+  confidence:            "low" | "medium" | "high"
+}
+```
+
+| Provider id | Status | Behavior |
+|---|---|---|
+| `simulated` | **Always available; default** | Heuristic narrative + risk identification, no API call. Used as fallback on any provider error. |
+| `openai` | **Active in v0.5.1** | Calls OpenAI Chat Completions API (or any OpenAI-compatible endpoint — Azure, OpenRouter, vLLM, llama.cpp server). 30s timeout. Server-side clamps response to contract shape. Falls back to simulated on network / HTTP / JSON errors. |
+| `anthropic`, `local`, `custom` | Listed, not implemented | Inert placeholders so the seam is visible in the settings dropdown. |
+
+Settings stored in `wp_options.sa_orch_llm_settings` (local-dev posture; future: SA-Core key vault). Tokens never echoed back; blank-token-saves preserve existing value.
+
+### Layer 4 — Human arbitration
+
+Final meaning. Always wins. The plugin records but does not adjudicate.
+
+## Hard rules — Strategy Review CANNOT
+
+The strategy layer (any provider, including OpenAI) **is purely advisory**. It MUST NOT and DOES NOT:
+
+- Override `closure_state_basic`, `closure_state_role_aware`, or `closure_authority_valid`.
+- Override `needs_human_arbitration`.
+- Persist its output (recomputed on every page load).
+
+These are governed by the deterministic audit (and ultimately by human arbitration). Enforced by:
+- The five-key contract excluding closure / needs_human fields.
+- The `clamp_to_contract()` step in each provider that drops any extra fields a model might inject.
+- The orchestrator's metadata layering (`provider_id`, `configured_provider_id`, `fallback_used`, `provider_error`) keeping the strategy output in its own namespace.
+
+## Conservative confidence floor (v0.5.2)
+
+When the deterministic audit's `closure_confidence === 'n/a'` (no acceptance events to evaluate), the strategy review's `confidence` MUST collapse to `'low'`. `'medium'` and `'high'` are not allowed when closure cannot be evaluated.
+
+**Two layers of enforcement** — both apply on every strategy review:
+
+1. **OpenAI prompt rule** — system prompt instructs the model directly: *"If no acceptance events exist OR the deterministic audit's closure_confidence is 'n/a', you MUST return confidence: 'low'."*
+2. **Orchestrator safety net** — `SA_Orch_Strategy::review()` silently downgrades to `'low'` if any provider returns `'medium'` or `'high'` when audit is `'n/a'`. Cross-cutting — applies to any current or future provider.
+
+The strategy contract still has only `low | medium | high` (`'n/a'` is not introduced to the strategy layer; it remains exclusively a deterministic-audit concept).
+
+## Partial projection — Fluent Support augmentation (v0.6.1)
+
+SA-Orchestration state surfaces inside Fluent Support **without modifying any native field**. Native ticket records (`status`, `resolved_at`, `closed_by`, `customer_id`, etc.) are read-only from this plugin's perspective. Augmentation is additive and fully removable.
+
+### Surface shape (two entries per ticket, ever)
+
+v0.6.1 collapsed the per-event flood of v0.6.0 into a stable two-row pattern. A ticket under SA-Orch governance carries **exactly two** projected conversation entries, regardless of how many events its Demand has accumulated:
+
+1. **Tracking marker** — one entry per ticket. Static voice. Not pinned. Upserts in place if the canonical phrasing or pinning rule changes.
+
+   ```
+   [SA-Orch] Tracking this ticket.
+   Full record (arbitrations, acceptance events, audit) in WP Admin → SA-Orchestration → Demand Trace → ticket#NNNN.
+   ```
+
+2. **State summary** — one entry per ticket. Header reflects current state ("Closed — stakeholder affirmation", "Result claimed — awaiting affirmation", "Revoked — open again", "Disputed", "Needs review — disputed", "Needs review — closure not authoritative", "Needs review — multiple arbitrations on this ticket", "Needs review — Demand reconstructed from indirect signals", "Tracking — awaiting result"). Upserts in place via stable idempotency key. Pinned (`is_important='yes'`) only when needs review; otherwise unpinned. When needs review, the body carries an `Action:` line phrased for the agent.
+
+   Example (closure clean):
+   ```
+   [SA-Orch] Closed — stakeholder affirmation
+   The stakeholder affirmed acceptance on 2026-04-22 10:00 UTC. Closure is authoritative.
+   Trace: WP Admin → SA-Orchestration → Demand Trace → ticket#1002
+   ```
+
+   Example (needs review — closure not authoritative):
+   ```
+   [SA-Orch] Needs review — closure not authoritative
+   Acceptance was affirmed by an agent on 2026-04-30 11:00 UTC — but only the stakeholder can authoritatively close.
+   Action: ask the stakeholder to affirm the result, or record their actual response (affirm or dispute).
+   Trace: WP Admin → SA-Orchestration → Demand Trace → ticket#1004
+   ```
+
+Per-event entries (v0.6.0) and the separate "Needs human arbitration" entry (v0.6.0) are **gone**. Full event history remains available via WP Admin → SA-Orchestration → Demand Trace.
+
+### Augmentation surfaces
+
+1. **Ticket meta** in `wp_fs_meta` with `object_type='ticket'` and key prefix `_sa_orch_*`:
+   - `_sa_orch_arbitration_hash` — most recent arbitration hash for this Demand.
+   - `_sa_orch_needs_human` — `'true'` | `'false'`.
+   - `_sa_orch_closure_authority` — `stakeholder` | `agent` | `system` | `inferred` | (empty when no affirmation event).
+
+2. **Conversation entries** in `wp_fs_conversations` with `source='sa-orch'`:
+   - Two rows per Demand-bound ticket (tracking + state, as above). Both keyed by `content_hash = md5(idempotency_key)` against a stable per-ticket key, so updates land on the same row.
+
+### Projection class
+
+`SA_Orch_Projection_Fluent_Support` (in `includes/class-sa-projection-fluent-support.php`).
+
+**Hook contract** — projection subscribes to two action hooks fired by the writers:
+
+| Hook | Fired by | Payload |
+|---|---|---|
+| `sa_orch_arbitration_written` | `SA_Orch_Arbitration::write()` after successful insert | arbitration row data including `id`, `hash`, `demand_surface`, `demand_ref`, `truth_class`, `asterion_path` |
+| `sa_orch_acceptance_event_written` | `SA_Orch_Acceptance::write()` after successful insert | event row data including `id`, `hash`, `demand_surface`, `demand_ref`, `event_type`, `actor_role`, `actor_user_id`, `truth_class`, `asterion_path` |
+
+Hooks fire **after** the canonical write succeeds (Asterion + DB), so projection can never run on phantom data.
+
+**Public methods**:
+
+- `register_hooks()` — wires up the two action listeners. Called from main plugin file on `init`.
+- `project_ticket( $ticket_id )` — full projection for one ticket; safe to call repeatedly. Upserts both entries; prunes any leftover SA-Orch rows that aren't the current tracking or state entries.
+- `backfill_all()` — projects every ticket that has any SA-Orch demand. Used to bootstrap state for tickets that pre-date the projection layer, or to migrate v0.6.0 entries to the v0.6.1 shape.
+- `remove_all_for_ticket( $ticket_id )` — removes only the augmentation rows for one ticket.
+- `remove_all()` — removes all `_sa_orch_*` meta and all `source='sa-orch'` conversations across the entire Fluent install.
+
+**Person resolution** (for conversation `person_id`): prefers an FS person matching the event's `actor_user_id`; falls back to admin's FS person; falls back to any agent person. Never invents a row.
+
+**Migration from v0.6.0**: `project_ticket()` calls `prune_legacy_sa_orch_rows()` after upserting, which deletes any `source='sa-orch'` conversation row for the ticket whose `content_hash` is neither the tracking marker hash nor the state-summary hash. Calling `backfill_all()` on a v0.6.0-projected install collapses 1+N+1 rows per ticket down to 2.
+
+### Verified properties
+
+9-check verification suite — all PASS as of the most recent run:
+
+| # | Property | Result |
+|---|---|---|
+| 1 | Backfill collapses every ticket to exactly 2 SA-Orch conversation rows; v0.6.0 leftovers pruned | PASS |
+| 2 | Tracking + state entries present for every ticket; phrasing has no `truth_class=` / `actor_role=` / `observed_at=` field-name leaks | PASS |
+| 3 | State entry pinned (`is_important='yes'`) iff `_sa_orch_needs_human='true'`; otherwise unpinned | PASS |
+| 4 | Idempotency — second `backfill_all()` writes nothing new | PASS |
+| 5 | New `acceptance_event` hook fires → state summary upserts in place (same row id, content updated, no append, pin and Action: line track the new state) | PASS |
+| 6 | Native ticket fields (`status`, `resolved_at`, `closed_by`, `customer_id`) hash unchanged through full test cycle | PASS |
+| 7 | `remove_all()` zeros all augmentation; native still untouched after global remove | PASS |
+| 8 | Re-projection from clean state restores 2 entries per ticket | PASS |
+
+### Constraint compliance
+
+- Native Fluent fields are never written (verified by status/resolved_at/closed_by/customer_id hash comparison before and after the full cycle).
+- All augmentation is namespaced (`_sa_orch_*` meta keys, `source='sa-orch'` conversations).
+- `remove_all()` is a complete uninstall path; restores Fluent to its pre-SA-Orch state.
+- No new tables; no schema migration; no FK between SA-Orch tables and Fluent tables (I8 still honored).
+- Timeline footprint is bounded: never more than two SA-Orch rows per ticket. New events update the state summary in place rather than appending.
+
+## Admin UI
+
+WP admin → SA-Orchestration menu:
+
+- **Demand Trace** — explorable picker (v0.6.2): closed-vocabulary surface dropdown + searchable per-surface candidate browser + quick-select strip (SA-ORCH-TEST fixtures pinned, then most-recently-traced demands) + manual ref entry with live pattern validation. Once a demand is selected, renders the full chain (arbitrations, plan_links, acceptance events) plus deterministic audit (with prominent Needs Human Arbitration row) plus Strategy LLM Review plus side-by-side audit↔strategy comparison. Trace logic itself is unchanged from v0.6.1; only the input layer was upgraded.
+- **Recent Arbitrations** — last 20.
+- **Acceptance Events** — last 20.
+- **Language Model Providers** — provider settings (enabled, provider, model, API base URL, API token; token masked, never echoed).
+
+### Demand Trace picker (v0.6.2)
+
+Goal: an operator never has to remember IDs to operate the system.
+
+The picker is rendered by `SA_Orch_Admin::render_picker_form()` and uses one synchronous server render (no AJAX, no new endpoints, no schema). All candidate data is serialized inline as `window.SA_ORCH_PICKER` JSON; vanilla JS handles surface-switching, search-as-you-type, and selection.
+
+**Components**:
+
+| Component | Purpose |
+|---|---|
+| Quick-select strip | Up to 10 most-clickable demands. SA-ORCH-TEST fixtures pinned to the top by `is_test` flag; remaining slots filled by most-recently-traced demands across all surfaces. Each row is a permalink that pre-fills the form. |
+| Surface dropdown | Closed enumeration: `fluent-support`, `fluent-boards`, `fluentcrm`, `derived` (mirrors `SA_Orch_Bridge_Fluent::known_surfaces()`). Empty option as default state. |
+| Candidate browser | Search input + scrollable list. Re-populates on surface change; live-filters on input. Click → fills `demand_ref`. SA-ORCH-TEST tickets pinned at the top of the fluent-support pool. Capped at 50 rows per surface. |
+| Manual ref input | Free-form text field. Validated client-side against per-surface regex (`^ticket#\d+$` / `^task#\d+$` / `^subscriber#\d+$` / `^derived#[A-Za-z0-9_\-]+$`). Inline ✓/✗ hint; never blocks submission. |
+
+**Candidate fetchers** (private `SA_Orch_Admin` helpers, all read-only):
+
+- `candidates_fluent_support()` — `wp_fs_tickets`, ordered by `(title LIKE '[SA-ORCH-TEST]%') DESC, id DESC`, cap 50.
+- `candidates_fluent_boards()` — `wp_fbs_tasks`, ordered by `id DESC`, cap 50. Tolerant of missing table.
+- `candidates_fluentcrm()` — `wp_fc_subscribers`, label = `full_name <email>` or `email`, cap 50. Tolerant of missing table.
+- `candidates_derived()` — `DISTINCT demand_ref` from `wp_sa_arbitration` ∪ `wp_sa_acceptance_event` where `demand_surface='derived'`, ordered by max(created_at, observed_at), cap 50.
+- `quick_select_demands($limit=10)` — UNION of `wp_sa_arbitration` + `wp_sa_acceptance_event` grouped by demand identity, sorted by `is_test DESC, last_at DESC`, cap 10.
+
+**Constraints honored**:
+- Trace logic untouched: `render_trace_results()` and `SA_Orch_Rest::get_demand_trace()` are unchanged.
+- No new schema, no new tables, no new REST endpoints.
+- Permalink shape preserved: `?page=sa-orchestration&demand_surface=…&demand_ref=…` still works (Recent Arbitrations and Acceptance Events deep-links continue to function and now pre-select the dropdown + ref input).
+- Defensive on optional surfaces: Fluent Boards / FluentCRM tables are checked with `SHOW TABLES LIKE` before query; absent surfaces simply render an empty pool.
+
+## REST endpoints (admin-only, `manage_options` capability)
+
+- `POST /wp-json/sa-orch/v1/arbitration` — write an arbitration.
+- `POST /wp-json/sa-orch/v1/acceptance` — append an acceptance event.
+- `GET /wp-json/sa-orch/v1/demand/{surface}/{ref}/trace` — full chain + four closure fields (`closure_state`, `closure_state_basic`, `closure_state_role_aware`, `closure_authority_valid`).
+
+## Files (`includes/`)
+
+```
+interface-sa-llm-provider.php             — provider contract
+class-sa-llm-provider-simulated.php       — heuristic provider
+class-sa-llm-provider-openai.php          — OpenAI provider
+class-sa-llm-providers.php                — registry / active-provider resolver / fallback
+class-sa-llm-settings.php                 — wp_options get/save (token masked)
+class-sa-strategy.php                     — orchestrator (layer-3 entry); confidence floor
+class-sa-reasoning.php                    — deterministic audit (layer 2)
+class-sa-arbitration.php                  — write_arbitration entry; fires sa_orch_arbitration_written
+class-sa-link.php                         — write_plan_link entry
+class-sa-acceptance.php                   — append-only event writer + closure helpers; fires sa_orch_acceptance_event_written
+class-sa-asterion.php                     — markdown ledger writer (Asterion-first)
+class-sa-bridge-fluent.php                — surface-ref resolver (closed vocabulary)
+class-sa-rest.php                         — REST routes
+class-sa-admin.php                        — admin UI (read-only)
+class-sa-migrations.php                   — dbDelta on activation
+class-sa-projection-fluent-support.php    — partial projection: Fluent Support augmentation (v0.6.0)
+```
+
+## Surface vocabulary recognized
+
+`SA_Orch_Bridge_Fluent::known_surfaces()` — closed enumeration:
+
+- `fluent-support` → `wp_fs_tickets.id` via `ticket#NNNN`
+- `fluent-boards` → `wp_fbs_tasks.id` via `task#NNNN`
+- `fluentcrm` → `wp_fc_subscribers.id` via `subscriber#NNNN`
+- `derived` → no underlying row; ref must match `^derived#[A-Za-z0-9_\-]+$`
+
+Adding a surface = extending this single class.
+
+## Test fixtures
+
+Regression suite: `F:\XAMPP\wordpress\sa-orch-regression.php` (idempotent — cleans and re-creates `[SA-ORCH-TEST]`-prefixed fixtures on each run; should move to a `tests/` directory in this repo once a code section exists). Last verified pass: **10/10**.
+
+Live fixtures currently in `wp_local_dev`:
+- 4 synthetic tickets (#1001–#1004), 1 board (#1001), 3 stages, 3 tasks (#1001–#1003), 9+ activities.
+- 5+ SA arbitrations, 9+ acceptance events, 6+ plan_links.
+- Production-import fixtures from `wp_sleeperagendev.sql` (per `FLUENT_DATA_MAPPING.md`).
+
+## Version history (running summary)
+
+| Version | Slice |
+|---|---|
+| 0.1.0 | Three-table schema + Asterion-first writes + `write_arbitration` / `write_acceptance_event` / `write_plan_link` + REST endpoints. |
+| 0.2.0 | Role-aware closure helpers: `closure_state_role_aware`, `closure_authority_valid`. |
+| 0.3.0 | Admin UI: Demand Trace + Recent Arbitrations + Acceptance Events (read-only). |
+| 0.4.0 | Reasoning Review (rules-based audit layer). |
+| 0.4.1 | Renamed to Deterministic Trace Audit; added Needs Human Arbitration row + four triggers. |
+| 0.5.0 | Strategy LLM Review layer (simulated provider only); provider seam + settings page. |
+| 0.5.1 | OpenAI provider implementation; orchestrator tracks configured-vs-used + fallback transparency. |
+| 0.5.2 | Conservative confidence floor: `n/a` audit forces `'low'` strategy confidence. |
+| 0.6.0 | Partial projection: Fluent Support augmentation via `_sa_orch_*` meta + `source='sa-orch'` conversations; `do_action` hooks (`sa_orch_arbitration_written`, `sa_orch_acceptance_event_written`) for decoupled side effects; idempotent backfill + clean-uninstall removal path. No native Fluent field is modified. |
+| 0.6.1 | Projection-UX refinement: collapsed 1+N+1 rows per ticket → exactly 2 (tracking marker + state summary, both upserted in place); per-event entries removed; needs-human folded into the state summary as a `Needs review — <reason>` header + `Action:` line; field-name leaks (`actor_role=`, `truth_class=`, `observed_at=`) replaced with human phrasing; pinning gated on needs-review; `prune_legacy_sa_orch_rows()` migrates v0.6.0 timelines on first re-projection. |
+| 0.6.2 | Demand Trace explorable picker: free-form `demand_surface` / `demand_ref` text fields replaced with a closed-vocabulary surface dropdown + searchable per-surface candidate browser + quick-select strip (SA-ORCH-TEST pinned, then last-traced) + manual ref fallback with live regex validation. Trace logic and REST endpoint unchanged. No new schema, no new endpoints. |
+
+## Constraints honored across all versions
+
+- **No schema change since 0.1.0.** Three tables, same shape, no `dbDelta` re-runs.
+- **Asterion-first.** Every canonical row has a matching ledger file. Drift = runtime is the lie.
+- **Append-only acceptance.** Class exposes only `write()` and read methods; no `update()` or `delete()`.
+- **Strategy layer never overrides audit-canonical fields.** Closure state and human-arbitration flag stay governed by the deterministic audit.
+- **Tool test (I5 / I8).** Removing this plugin does not corrupt Fluent or any other surface. Fluent rows have no FK from this plugin's tables.
+- **Partial projection is augmentation-only.** SA-Orch never writes to Fluent native fields (`status`, `resolved_at`, `closed_by`, `customer_id`, etc.). All projection lives in namespaced augmentation surfaces (`_sa_orch_*` meta + `source='sa-orch'` conversations) and is fully removable via `SA_Orch_Projection_Fluent_Support::remove_all()`. Verified by status/resolved_at/closed_by hash comparison before-and-after.
+- **No production secrets in repo.** Local-dev WP Engine wp-config.php remains backed up at `F:\XAMPP\wordpress\wp-config.php.production-backup-20260501`; not part of this repo.
+- **Token security.** Saved API tokens never displayed in admin UI; blank-token saves preserve.

SA-orchestration MD/PROJECTION_SURFACES.md

@@ -0,0 +1,137 @@
+---
+kind: constraint_model
+truth_class: canonical
+authority: project_invariant
+---
+
+# Projection Surfaces
+
+## Definition
+
+A **projection surface** is an external system that emits evidence about Change-System concepts. Surfaces:
+
+- Are not canonical for any Change-System concept (Demand, Arbitration, Plan, Action, Result, Acceptance — see `SIGNAL_FLOW.md`).
+- Emit Energy that may converge into Matter at SA-Core / Asterion. See `ENERGY_MODEL.md`.
+- May continue functioning when Core is unavailable (degraded mode). See `BYPASS_AND_RECOVERY.md`.
+- Are incorporated via a realm adapter — see `Archvie/sa-core/docs/specs/03-realm-adapter-contract.md`.
+
+A surface's own native records (a Fluent ticket row, a Boards card row, a WordPress post row) remain realm-canonical at the surface — that is what SA-Core Invariant I1 protects. The Change-System concepts (Demand, Plan, Acceptance, etc.) are Core-canonical and merely *expressed through* the surface.
+
+The discriminator: realm data = the structures the realm itself defines. Core data = the structures Core itself defines. A Demand entity is Core data; a Fluent ticket is realm data; the relationship between them is a projection edge, not co-identity.
+
+## Surface inventory
+
+### Fluent Support
+
+Role: projection surface for Demand evidence and Acceptance evidence.
+
+| Aspect | Status |
+|---|---|
+| Realm id (planned) | `fluent-support` |
+| Hosting | WordPress site (identity TBD) |
+| Read capability | Pending integration |
+| Watch capability | Pending integration |
+| Write capability | Deferred (initial scope read+watch only) |
+
+**Local fixture state (imported 2026-05-01):**
+
+- Plugin active locally at version 2.0.6. Schema installed: 11 `wp_fs_*` tables.
+- Data populated from production export `wp_sleeperagendev.sql`.
+- Counts: 2 tickets (ids 12, 13), 9 persons (mix of agent and customer), 4 conversations, 1 mailbox, 1 attachment, 1 meta.
+- See `FLUENT_DATA_MAPPING.md` §3 for details and §6.1 for the natural test fixture (ticket 12 closure/reopen ambiguity).
+
+### Fluent Boards
+
+Role: projection surface for Plan evidence and Action-tracking evidence.
+
+| Aspect | Status |
+|---|---|
+| Realm id (planned) | `fluent-boards` |
+| Hosting | WordPress site (identity TBD) |
+| Read / watch / write | All pending integration |
+
+**Local fixture state (imported 2026-05-01):**
+
+- Plugin active locally at version 1.80. Schema installed: 12 `wp_fbs_*` tables.
+- Data populated from production export `wp_sleeperagendev.sql`.
+- Counts: 17 boards, 57 tasks, 284 activities, 135 board terms, 71 relations, 40 metas, 16 notifications, 17 notification users, 10 comments, 2 attachments.
+- See `FLUENT_DATA_MAPPING.md` §4 for details and §6.2–6.3 for natural test fixtures (Mission.net board, activity-rich boards).
+
+### FluentCRM
+
+Role: identity / contact normalization layer (Stakeholder identity). Supplies contact identity to Demand and Plan layers; not itself a canonical home for any Change-System concept.
+
+| Aspect | Status |
+|---|---|
+| Realm id (planned) | `fluentcrm` (naming convention TBD) |
+| Hosting | WordPress site (local at `http://wordpress.localhost/`) |
+| Read / watch / write | All pending integration |
+
+**Local fixture state (imported 2026-05-01):**
+
+- Plugin active locally at version 2.9.87. Schema installed: 17 `wp_fc_*` tables.
+- Data populated from production export `wp_sleeperagendev.sql`.
+- Counts: 32 subscribers, 197 subscriber meta entries, 26 tags, 5 lists, 6 meta entries, 2 subscriber pivot rows, 1 funnel.
+- 1 production table (`wp_fc_companies`) skipped on import — companies feature not present in local plugin version.
+- See `FLUENT_DATA_MAPPING.md` §2 for details.
+
+### Jira
+
+Role: alternate projection surface for Plan evidence (for shops that use it).
+
+Status: future. Not in current scope.
+
+### JobOrchestration
+
+Role: projection surface for Action execution and Result observation.
+
+Status: future. Not in current scope.
+
+### WordPress
+
+Role: runtime substrate for SA-Core (which ships as a WordPress plugin per the spec pack), and host for Fluent surfaces.
+
+| Aspect | Status |
+|---|---|
+| Local install (XAMPP) | Not yet performed |
+| Live site identity | TBD |
+| Multisite posture | TBD |
+| Plugin set | TBD |
+
+### Provider adapters (LLM / model providers)
+
+Role: providers for SARA-mediated arbitration cognition. Not Change-System surfaces themselves; supply reasoning capability to the Manager.
+
+| Provider | Status |
+|---|---|
+| OpenAI | Not assumed present; declare before use |
+| Anthropic | Not assumed present; declare before use |
+| Other | Declare before use |
+
+## Surface invariants
+
+- **No surface-to-Asterion direct writes.** Surface evidence is Energy. Canonicalization happens only through CAMP.
+- **No realm-data overwrite by Core.** Core never authors canonical state on a surface's behalf for the surface's own native records (SA-Core Invariant I1).
+- **Tool test.** Removing SA-orchestration must not corrupt any incorporated surface (SA-Core Invariants I5, I8). Surfaces continue at their native homes.
+- **Acceptance authority lives only at the surface of origin** for the canonical Demand. A close-ticket signal at Fluent Support is the *evidence form* of acceptance; the canonical Acceptance is in Asterion.
+
+## Surfaces compose; they do not compete
+
+Multiple surfaces emitting aligned evidence about the same Change-System concept contribute to the same convergence basin. The basin deepens; convergence forms above threshold; Matter writes once. See `ENERGY_MODEL.md`.
+
+This is the normal case. Adding a new surface is adding field signal, not creating a parallel canonical home.
+
+## Orchestration layer above the surfaces
+
+The **SA-Orchestration WordPress plugin** (current v0.5.2) sits above the surfaces listed in this file and provides the canonical Demand→Plan→Acceptance graph that no surface natively carries. Surface vocabulary recognized by the plugin's `SA_Orch_Bridge_Fluent::known_surfaces()`:
+
+| Surface id | Resolves to | Ref pattern |
+|---|---|---|
+| `fluent-support` | `wp_fs_tickets.id` | `ticket#NNNN` |
+| `fluent-boards` | `wp_fbs_tasks.id` | `task#NNNN` |
+| `fluentcrm` | `wp_fc_subscribers.id` | `subscriber#NNNN` |
+| `derived` | (no underlying row — for reconstructed Demands) | `derived#<slug>` |
+
+Adding a new surface to the plugin is a single-class extension. No DB-level FK from the plugin's tables to surface tables — per SA-Core invariant I8, removing the plugin does not corrupt any surface.
+
+For the plugin's running status, schema, and version history, see `PLUGIN_STATUS.md`.

SA-orchestration MD/README.md

@@ -0,0 +1,25 @@
+# SA-Orchestration — Operational Doctrine (MD reference)
+
+This directory holds the **operational doctrine documents** from the SA-Orchestration source repo. They are NOT the canonical Asterion corpus (that lives at `<repo-root>/asterion/`). These are the working-state and project-meta documents that the agent needs to understand the system as it operates.
+
+Contents:
+
+- `BYPASS_AND_RECOVERY.md` — gated bypass paths and recovery posture
+- `CORE_MODEL.md` — the energy/matter duality and canonical-at-write rule
+- `DEFERRED_SA_CORE_CONCERNS.md` — concerns held until SA-Core is ready to absorb
+- `DEVELOPMENT_MODES.md` — dev / staging / production posture
+- `ENERGY_MODEL.md` — convergence vs scatter; field as the substrate
+- `ENVIRONMENT.md` — declared resources, runtime discovery, the dual-natured state record
+- `FLUENT_DATA_MAPPING.md` — Fluent ecosystem data mapping
+- `ONBOARDING.md` — the SA-Orchestration source repo's own onboarding (distinct from this repo's)
+- `PLUGIN_STATUS.md` — version + verification stamp for the plugin
+- `PROJECTION_SURFACES.md` — projection-surface taxonomy
+- `SCATTER_AND_CONVERGENCE.md` — convergence as the canonical collapse
+- `SIGNAL_FLOW.md` — Signal Telemetry Doctrine flow notes
+- `verify-stamp.php` — repo-root helper (referenced in PLUGIN_STATUS.md)
+
+Authored by Mark Holak. Preserved under Invariant **I9** of the SA-Orchestration spec pack.
+
+For canonical doctrine (vocabulary, invariants, concepts), read `<repo-root>/asterion/`. This directory is a complement, not a replacement.
+
+For the deployable plugin tree, see `<repo-root>/sa-orchestration/`.

SA-orchestration MD/SCATTER_AND_CONVERGENCE.md

@@ -0,0 +1,73 @@
+---
+kind: constraint_model
+truth_class: canonical
+authority: project_invariant
+attribution: Mark Holak (convergence-collapse, two-layer scatter)
+---
+
+# Scatter and Convergence
+
+## Convergence
+
+See `ENERGY_MODEL.md` for the convergence-collapse model. Brief restatement:
+
+CAMP **resolves convergence** — it does not pick. The canonical location is where total aligned signal converges above threshold, maximizing causal continuity with the existing field. It is the only stable solution under the system's constraints, not an arbitrary choice.
+
+## Threshold (basin depth)
+
+Threshold is **basin depth required for stable convergence at a location** — not a counter or score.
+
+- Below threshold: signal does not crystallize into Matter. The basin is not deep enough to stabilize.
+- Above threshold: convergence forms; CAMP records Matter.
+- Likely tunable per concept (Demand intake basin ≠ Acceptance basin). Specific values: pending.
+
+## Scatter — two layers
+
+Scatter is **not** a single classification. It operates at two layers, distinguished by whether canonical collapse has occurred.
+
+### Pre-collapse: Inert
+
+Signal that did not converge anywhere. Below basin depth at any candidate location.
+
+- Symbol: `?`
+- Logged as observed Energy. Non-canonical.
+- Inert signal continues to contribute to the field while it persists. It may participate in later convergence events as more evidence accrues.
+- Persistence model: pending decision (continuous decay / recency-weighted vs. hard cutoff after N).
+
+### Post-collapse: Harmony / Dissonance
+
+Properties of how Matter, once crystallized, interacts with future field motion. Not pre-collapse classifications.
+
+- **Harmony** (`+`) — beneficial downstream absorption. Subsequent Energy aligns with the canonical state.
+- **Dissonance** (`−`) — harmful downstream absorption. Subsequent Energy conflicts with or destabilizes the canonical state.
+
+These describe Matter's effect on subsequent Energy. They are downstream of canonical writes; they do not gate writes.
+
+## CAMP's role
+
+CAMP **records interaction truth**. CAMP **does not judge outcome quality**.
+
+- Inert is observed (recorded), not judged.
+- Harmony / Dissonance are downstream observations made by reasoning queries against the field of accumulated Matter, not by CAMP at write time.
+
+## Refusal-to-collapse
+
+If signal accumulates at two mutually-destabilizing locations, CAMP records "convergence not formed; competing signal at A and B" — without forcing crystallization.
+
+This is **not a failure mode**. It is an honest report of unresolved interpretation. Forcing collapse where the field has not converged would violate the discipline.
+
+## Multi-source aligned signal
+
+Two or more surfaces may emit aligned evidence that contributes to the same convergence basin. The basin deepens; convergence forms above threshold; Matter writes once.
+
+This is the normal case, not the edge case. Surfaces compose; they do not compete. See `PROJECTION_SURFACES.md`.
+
+## Consonance with SA-Core's authored framework
+
+Mark Holak's Signal Telemetry Doctrine (preserved at `Archvie/sa-core/docs/specs/concepts/signal-telemetry-doctrine.md` under Invariant I9) names alignment behaviors as *align / scatter / ricochet / inert / harmonic closure*. Harmony / Dissonance / Inert sit inside this family.
+
+Mark Holak's Cognitive Heatsink (preserved at `Archvie/sa-core/docs/specs/concepts/cognitive-heatsink.md`) is a thermodynamic model of thought-to-resolution through computational dissipation. CAMP-fire as the Energy → Matter dissipation moment lives in the same metaphor space.
+
+## Attribution
+
+Convergence-collapse and the two-layer scatter (Inert pre-collapse; Harmony / Dissonance post-collapse): **Mark Holak**. Subject to later separation for IP reasons.

SA-orchestration MD/SIGNAL_FLOW.md

@@ -0,0 +1,115 @@
+---
+kind: constraint_model
+truth_class: canonical
+authority: project_invariant
+---
+
+# Signal Flow — Demand → Arbitration → Plan → Action → Result → Acceptance
+
+The Change-System is a six-stage causal chain. Stages do not collapse into each other.
+
+## Stage map
+
+| Stage | Canonical home | Energy form (surface evidence) | Notes |
+|---|---|---|---|
+| Demand | SA-Core / Asterion | Fluent Support tickets/replies, conversations, meeting notes | Stakeholder expression on a surface is *evidence*, not the canonical Demand |
+| Arbitration | SA-Core (function, not layer) | Manager-via-SARA cognition | The interpretive translation Demand → Plan; recorded as a first-class entity in Asterion |
+| Plan | SA-Core / Asterion | Fluent Boards / Jira cards | Plan structure is Core ontology; surfaces are projections |
+| Action | SA-Core record; artifact at realm of effect | JobOrchestration runs, codebase commits, deploys | Core records the Action; effect artifacts have native homes |
+| Result | SA-Core record; artifact at realm of effect | Same as Action | What actually happened |
+| Acceptance | SA-Core / Asterion | Stakeholder close-ticket signal at Fluent Support | Affirmative; not inferred from state |
+
+External systems are projection surfaces. None is canonical for any of these concepts. See `PROJECTION_SURFACES.md`.
+
+## Causal chain rules
+
+- **Demand never overwritten by Plan.** Plan never redefines Demand. Stages do not collapse.
+- **Sync is not equality.** Cross-stage flow is constrained projection across realms — directional and arbitrated. Not bidirectional overwrite.
+- **Every Matter must trace back to originating Energy.** Every canonical write must include rationale.
+- **Asterion is canonical-at-write.** Runtime is cache. See `CORE_MODEL.md`.
+- **No silent mutation.** All changes are event-based.
+
+## Closure rule
+
+The system is **not** complete when:
+
+- a task moves columns
+- a ticket is marked closed
+
+The system **is** complete when:
+
+- the original demand-constraint is resolved, **and**
+- the stakeholder accepts the result.
+
+Closure is **affirmative**, not inferred from state. Maps to SA-Core's `human_affirmed_at` / `human_affirmed_by` (per Invariant I7's promotion path from `inferred` to `canonical`).
+
+## Operational queries (Core-only by construction)
+
+These questions cannot be answered by any single projection surface. They require joining evidence across surfaces, traced to canonical entities, with Core arbitrating drift between surface evidence and canonical state.
+
+- Who is doing what?
+- Is a person or team productive?
+- Are we on track?
+- What demand is unresolved?
+- What plan lacks action?
+- What action lacks acceptance?
+
+These are Core's reason for existing — not features added on top.
+
+## Energy → Matter at each stage
+
+Each stage's canonical entry is the **convergence outcome of multiple Energy contributions**. See `ENERGY_MODEL.md`.
+
+A surface event (e.g., a Fluent ticket arriving) does not auto-promote to a canonical Demand entity. CAMP evaluates the field; convergence at a location forms Matter.
+
+## Multi-source contribution
+
+A single Demand may be expressed through multiple surfaces (a Fluent ticket, a chat message, a meeting transcript). These do not compete for canonical status; they contribute to the same convergence basin. The canonical Demand entity emerges from the field, not from a single surface event.
+
+A single Plan may be projected to multiple surfaces (a Boards card, a Jira ticket, a markdown checklist). These are projections of the same canonical Plan, not parallel canonical Plans.
+
+## Bypass
+
+When Core is unavailable, surfaces continue functioning in degraded mode. Their state changes during bypass are Energy until they re-enter through CAMP. See `BYPASS_AND_RECOVERY.md`.
+
+## Human roles as causal nodes
+
+| Role | Causal position |
+|---|---|
+| Stakeholder | Demand origin; defines success; validates outcome; Acceptance authority |
+| Manager | Arbitration node; operates through SARA; translates Demand into Plan; assigns work; maintains alignment |
+| Developer | Risk taker; executes Plan; applies judgment in Action; responsible for outcome resonance |
+
+Each role contributes Energy at its causal position. CAMP arbitrates convergence into Matter.
+
+---
+
+## Observed in live data (test fixture, 2026-05-01)
+
+The first production data import (see `FLUENT_DATA_MAPPING.md`) provides concrete examples of where Fluent's surface model diverges from the Change-System ontology — and why SA-orchestration's arbitration record exists.
+
+### Demand → Plan link absent at the surface
+
+Of 57 imported `wp_fbs_tasks` rows, **1 carries `crm_contact_id`**; **none carry a reference to a `wp_fs_tickets.id`**. There is no native Fluent column connecting a Plan unit back to the Demand that originated it. The Demand → Plan trace is exactly what Asterion's arbitration record carries; Fluent does not.
+
+### Closure rule violated in the wild
+
+Ticket 12 (`HelpDesk - New Golf image for Website`) simultaneously holds:
+
+```
+status            = 'active'
+resolved_at       = '2026-03-31 22:43:52'
+closed_by         = 1
+```
+
+Three fields on one row, internally inconsistent if read literally. The `wp_fs_conversations` log shows the cause: ticket was closed, then reopened — the close-time fields were left populated, the status was reverted. **Acceptance state cannot be inferred from the row alone.**
+
+This is the closure rule warning made concrete. An Asterion-style append-only acceptance log (`acceptance_proposed` → `acceptance_disputed` → `acceptance_affirmed`) replaces the mutable-field ambiguity with a readable causal chain.
+
+### Action evidence is convergence-shaped
+
+`wp_fbs_activities` carries 284 rows across 9 distinct task-action types (`created`, `changed`, `updated`, `added`, `joined`, `closed`, `reopened`, `removed`, `left`) and 6 board-action types (`created`, `added`, `moved`, `changed`, `archived`, `updated`). Each row is a discrete event with `created_at`, `object_id`, `object_type`, `action` — the Energy form CAMP would arbitrate. Activity rows carry no rationale field; **why** the Action happened is not captured.
+
+### Mission.net board (board id 16)
+
+A real production board named `Mission.net` exists with 9 tasks. The naming aligns with SA-Core / MissionNet vocabulary in the spec pack. This board is the closest existing surface fixture to the SA-orchestration project's own work and the natural starting point for testing Demand → Plan → Action traces against live Fluent data.

SA-orchestration MD/asterion/01-ontology.md

@@ -0,0 +1,281 @@
+# MissionNet Ontology (v0.1)
+
+*Implementation © Sleeper Agents LLC. Conceptual framework authored independently by Mark Holak; see `docs/specs/concepts/`.*
+
+This is the vocabulary lock. Every downstream doc, every class, every log message, and every UI surface uses these terms precisely. Drift here = drift everywhere.
+
+---
+
+## Primary nouns
+
+### Core
+
+The required substrate. One WordPress plugin (`sa-core`). A space is a SleeperAgent space only when Core is online underneath it.
+
+### Realm
+
+An externally sovereign system of record or operation. FluentCRM is a realm. Jira is a realm. QuickBase is a realm. QuickBooks is a realm. PortTracker's Node backend is a realm. An arbitrary REST API is a realm. A client's database is a realm. A realm is sovereign because its integrity does not depend on Core.
+
+### Subsystem
+
+A coherent slice of Core itself. SAWS-executor is a subsystem. CARMA (the absorbed WP maintenance toolset) is a subsystem. MissionNet (the presentation layer) is a subsystem. A customer-facing brand may wrap a subsystem; the brand is cosmetic, the subsystem is structural.
+
+### Adapter
+
+A bidirectional conduit between Core and a realm. See the **Realm Adapter Contract** (`03-realm-adapter-contract.md`). Adapters do not own realm data; they mediate flow. A provider adapter (`SA_Provider_Adapter`) is a specialized adapter for LLM and tool providers; a realm adapter (`SA_Realm_Adapter`) is the general-case conduit.
+
+### Entity
+
+The universal unit of the field inside Core. Rendered as circle (compressed atom) or rounded-rect (expanded container). Carries band hints, ratio, position, payload, ACL, provenance, and truth class.
+
+### Record
+
+A specific row in a realm's native schema. A record's canonical home is the realm. A record's Core-side reflection is a **Projection**.
+
+### Projection
+
+Core's non-canonical mirror of a realm record. Stored as an entity with `truth_class = projected`, `origin_realm` + `origin_id` populated, and TTL-bounded when cached.
+
+### Canonical Source
+
+The realm in which a record is authoritative. Only the canonical source may author canonical state for its own records. Core cannot author canonical on a realm's behalf.
+
+### Event
+
+Something that happened. Immutable, time-indexed. Recorded to `sa_structural_audit` with actor, target, before/after, correlation_id, causation_id, policy_basis.
+
+### Command
+
+An instruction or intent. Typically initiated by an actor or a scheduled policy. A command may yield one or more events when executed.
+
+### Actor
+
+The who of an action. One of: a WordPress user id (human), a service principal id (non-human authenticated identity), or the string `system` (Core's own internal automation under an audited policy).
+
+### Authority
+
+The scope of what an actor may do. Held by role, package capabilities, ACL entries, and adapter capability matrices.
+
+### Session
+
+A grouping of related commands and events initiated by a single actor or chain. Correlated by a shared `correlation_id`.
+
+### Mission
+
+A composite objective that spans one or more sessions. (Future spec — see `10-mission-orchestration.md` when written.)
+
+### Quest
+
+A unit of narrative direction. Defines target, not-target, and admissible uncertainty for a body of work. Quests are authored, not executed: their canonical home is the planning surface (Boards in MissionNet's instance).
+
+Quests describe what the work is *about*. Resolution of a Quest is a narrative judgment — was the direction met, was it abandoned, was it superseded — made by a human.
+
+Distinct from a Job. See Job below; see also Distinguishing pairs.
+
+### Task / Job
+
+A unit of executable work within a Quest. May be scheduled, assigned, retried, or delegated. Jobs describe what is *done*. Resolution of a Job is a real-world consequence — the work either happened or did not — measured against reality, not against the system.
+
+A Quest may produce one or more Jobs. A Job belongs to one Quest. Conversion between Quest and Job is not automatic; see I10.
+
+### Attention
+
+A routing signal — never an instruction, never a state mutation. Attention asks for arbitration; it does not perform it. NPCs (agents, automated processes) may emit Attention. Only humans may resolve it.
+
+The infrastructure: the attention log records signals with actor, target, correlation_id, causation_id. Read-only by construction; resolving Attention requires the human to take a separate, explicit act.
+
+Sub-doctrine: see `concepts/attention-doctrine.md` and `concepts/compass-doctrine.md`.
+
+### Realm Signal
+
+A low-cost notification from a realm ("something changed") that Core may choose to consume, queue, or ignore based on policy. Previously named "Signal"; renamed to free the unqualified term for the doctrinal meaning below.
+
+### Signal
+
+*(Authored by Mark Holak. Preserved under Invariant **I9**.)*
+
+The measurable alignment behavior of participants — users, workers, agents, models, systems — as they traverse an authored **acceleration field** (a mission, prompt, workflow, book, interface, instruction set, or any artifact that defines target, not-target, and admissible uncertainty).
+
+Signal is *not* raw observability. Pillar 0.75's sub-token graph is the instrument; Signal is what the instrument reads. Participants interact with an authored field and produce measurable interaction outcomes — some align, some scatter, some ricochet, some go inert, some reach harmonic closure. The Signal Telemetry Doctrine is the interpretation layer sitting over Prime Prompt Conjecture and Cognitive Heatsink: PPC and Heatsink describe how trajectory is compressed and dissipated; Signal reads the alignment produced at the other end.
+
+The enumerated behaviors (align / scatter / ricochet / inert / harmonic closure) are **exemplary, not definitive** — additional behaviors may emerge as the system is used. See `concepts/signal-telemetry-doctrine.md` for the full doctrine and its mapping onto Core primitives.
+
+### Artifact
+
+A file, document, image, or embedding. Stored in the native realm when possible; projected into Core via adapter.
+
+### Trace
+
+The causal ancestry of a state or an event. Walked by `SA_Structural_Audit::trace_origin()`. Preserved by correlation_id and causation_id on every audit row.
+
+### Truth Class
+
+See `SA_Truth_Class` and Invariant **I2**. One of: `canonical | projected | cached | inferred | derived | synthetic`. Every entity declares one.
+
+### State Class
+
+See `SA_State_Class`. The lifecycle position of a datum. One of: `resting | observed | projected | pending_action | acted | verified | disputed | stale | superseded`.
+
+### Provenance
+
+The origin record attached to every entity: `origin_realm`, `origin_id`, `actor`, `observed_at`, `causation_id`, `correlation_id`, optional `derived_from`, `source_refs`, `provenance_hash`.
+
+### Membrane
+
+A per-entity veil that turns the entity into a black-box domain. Only typed I/O ports are visible to outsiders. Billing principals may unfold the membrane they are charged for.
+
+### I/O Port
+
+A typed edge anchor on a membraned entity. The only integration surface visible to non-insiders.
+
+### Grouping Overlay
+
+A first-class attributed, non-destructive re-parenting of entities. Per-scope (private / shared / org / public), per-author. Applied at render time.
+
+### Projection Slot
+
+A named rendering surface bound to an entity query. A package defines its slot set; a viewer may override within the slot's allowance.
+
+### Projection Source
+
+A named, viewer-scoped row producer eligible to be unioned with other sources at a surface's Projection Arbiter. Each source owns one query path and applies its own visibility gate (`row_visible`) before returning rows. A source is NOT any method on `SA_Projection`; it is specifically a row producer composable into a surface's arbiter. Today's sources: `chat` (`recent_prompts` — chat-domain-joined) and `realm` (`recent_entities` — role/origin-realm-scoped). Sources are kernel-owned; third parties contribute realm adapters (which feed `realm`), not sources.
+
+### Projection Arbiter
+
+A surface-scoped composer that enumerates the Projection Sources feeding that surface, invokes them for the current viewer, and unions their output into the surface's response shape. The arbiter owns source enumeration, union strategy, and per-source instrumentation (`window.sources` readout). Today implemented as one method per surface on `SA_Projection` (`for_mission` is the only instance). Not a standalone class: at two sources with no arbitration rules (dedup, sort-merge, ACL-at-merge), a class would be ceremony. Promotion to a class is deferred until (a) a third source, (b) a concrete arbitration rule, or (c) third-party source registration lands. Surfaces with a single source (`/thread`, `/trace`, `/lattice/subtree`) do not go through an arbiter and do not need one.
+
+### Influence Halo / Ring
+
+Concentric bands around an entity carrying weighted references to related entities. The continuous limit of discrete rings is the contour mode (`docs/ARCHITECTURE.md` — Derived pillar: Contour rendering).
+
+### Sub-Token Event
+
+Every internal orchestration step inside a provider invocation (embed, retrieve, tool call, subagent hop, completion, rerank, self-critique, router). First-class entity at band 5 inside the parent prompt's band 4 container. Visible and annotatable by the billing principal.
+
+### Geodesic Marker
+
+A memory record of a failure path in the prompt manifold. Seeded from bad verdicts on sub-tokens. Consumed by `SA_Geodesic_Seeder` to route around known failures.
+
+### Context Bundle
+
+A named, pinned slice of the entity graph with a deterministic signature. Multiple adapters (including specialized LLMs) bind to the same bundle for synchronized context.
+
+### Package
+
+The purchased SKU. Enumerates enabled capabilities, default overlays, default membranes. Assigned to an org.
+
+### Capability
+
+An enumerable permission string (`sa-core:sub-token-unfold`, `missionnet:impose-grouping`, `carma:admin-takeover`). Package-gated.
+
+### Service Principal
+
+A non-human authenticated identity. External services (PortTracker's Node, ingest clients, Jira bots) use service principal tokens to push mutations without impersonating a user.
+
+### Invariant
+
+A non-negotiable law the system upholds at runtime. See `02-invariants.md`. Violations are logged to `sa_invariant_violation`.
+
+### Adapter Certification
+
+The gate that promotes a realm adapter from "in development" to "live." Checklist runs against the Realm Adapter Contract invariants. See `03-realm-adapter-contract.md`.
+
+### Admission Contract
+
+The per-layer contract a new primitive — or a new instance of an existing primitive — must honor to be validly admitted into the system.
+
+A *named principle*, not a uniform checklist family. The principle is: **admission is layer-owned and layer-shaped**, not uniform across layers. Each layer's admission contract takes whatever form that layer's nature demands (a certification checklist for realms, runtime invariants for entities, an op whitelist for mutations, a return-shape obligation for projection sources, etc.).
+
+This principle does not add a new commitment. It names a shape already diffused through:
+
+- **Pillar 0.5** — everything rendered is `project(field, viewer, overlays, permissions)`. A new primitive must have defined behavior under all four inputs.
+- **Pillar 0.75** — every orchestration step is observable. Anything action-shaped must declare how it emits observability (sub-token events, audit rows, source attribution).
+- **Pillar 0.9** — the primitive set is closed; new capabilities are compositions of existing primitives. Admission = proof of valid composition.
+- **`03-realm-adapter-contract.md`** — the single fully worked-out formal instance of a per-layer admission contract.
+
+See `docs/ARCHITECTURE.md` for the pillars themselves. This entry does not amend them; it gives the shape they imply a name.
+
+**Status ledger.** The ledger is the term's practical content. It records which primitive layers currently have formal contracts, which have informal ones, which are absent, and which are intentionally deferred. New rows enter only when a new primitive layer enters the closed set — not per instance, and not per cross-layer attribute.
+
+| Layer | Contract state | Reference / note |
+|---|---|---|
+| Realm | Formal | `03-realm-adapter-contract.md` + `sa_adapter_certification` table |
+| Entity | Formal | `02-invariants.md` I2 / I4 / I7 + `SA_Truth_Class` / `SA_State_Class` validation in `SA_Entity::create` |
+| Mutation | Formal | `SA_Ingest` op whitelist, idempotency-key discipline, service-principal scope, deterministic UUID rule |
+| Projection Source | Informal | "Returns viewer-gated rows in arbiter-compatible union shape." Implied by the Projection Arbiter promotion; not yet written as a standalone contract. |
+| Grammar | Absent | No admission rules for a new grammar today. Chat-lineage / equal-peer / containment-pack are ad-hoc in client code. |
+| Surface inspection | Informal | Three discriminable cases now operative in `/mission/`'s lens-routing decision (`renderCurrentProjection` in `assets/mission.js`), driven by a shape predicate over `(entity.origin_realm, sub_token_count)` — no realm-specific code: (a) **chat-shaped** (`!origin_realm`) → trace lens; (b) **structural-only** (`origin_realm` set, `sub_token_count == 0`) → structural inspector; (c) **structural-with-sub-tokens** (`origin_realm` set, `sub_token_count > 0`) → hybrid lens (structural inspector + Sub-tokens section in step_index ASC order, with shape-aware labels read from `SubTokenEvent.metadata` rather than chat-shaped fallbacks). Discriminator field `sub_token_count` lives on the `/entity/{id}/inspect` projection response (additive, no schema change). Concrete instances: chat prompts (case a), FS containers/leaves (case b), GitHub Actions workflow runs (case c). Promotion to Formal (separate contract file) requires a fourth case or a second concrete hybrid example, whichever forces the discriminator's edge cases into a written rule. Until then the contract is the inline behavior recorded here. |
+| Toolbox action | Formal | `06-toolbox-action-contract.md` (v0.1, 7 clauses). Two concrete instances: `/mission/`-native "Re-scan FS" and "Re-scan GH" buttons (both admin-only). Promotion criteria from Informal → Formal were satisfied by the second instance (GitHub Actions re-scan) cleanly fitting the same seven-clause shape: semantic binding (1 button → 1 REST endpoint), permission gate (manage_options at template AND REST), audit obligation (one operator-attribution structural-audit row per invocation), parameter shape (render-time derivation, no click-time dialogs), feedback contract (busy/success/failed state cycle), refresh obligation (`load()` on success), idempotency (zero net entity-count drift on repeat). Out-of-scope categories (parameter dialogs, destructive actions, multi-step compositions) explicitly deferred to future contract revisions when concrete instances drive them. |
+| Membrane | Deferred | Primitive defined in this ontology; admission contract (port typing, opacity rules, billing-principal translucency) deferred until first implementation. |
+| Overlay | Deferred | Primitive defined in this ontology; admission contract (scope, attribution, idempotency, render-time layering) deferred until first implementation. |
+| Credential | Deferred | Surfaced by the GitHub Actions third-domain proof, which uses a filter-driven PAT (`sa_core_github_token`) as its smallest scope-honoring credential path. The general contract — how external-realm credentials enter the system (OAuth flows, refresh-token lifecycle, per-user vs per-org binding, scope-limited storage) — is not yet written. Existing primitives partially cover adjacent concerns: `SA_Credential_Pool` (LLM provider keys, single-secret-per-record), `SA_Service_Principal` (inbound bearer tokens), filter-driven adapter config (FS, GitHub Actions). None compose into a unified credential-admission shape. Authorized work will likely extend `SA_Credential_Pool` to handle multi-step OAuth tokens and add the operator UX (connect, store, scope, retire) as one slice's deliverable, then retire ad-hoc filter configs. First instance: GitHub. Second instance later: Jira / Linear / etc. |
+| Camera-Projection Convergence | Pinned | Filed during the dependency audit preceding the Hybrid Inspector Lens slice. Concept: under Pillar 0's full vision, camera transitions at band boundaries are themselves projection-resolution events, not viewport transforms. Today the camera is degenerate (purely affine pan/zoom over fixed layout). Under Rung 4 phase 2+, zoom-band crossings re-layout via auto-compress / auto-expand, making camera a constrained re-projection over the referential manifold rather than a viewport adjustment. Concrete formalization deferred until a second example of camera-as-projection lands alongside Jump-2 (auto-descend on band-cross) or Jump-3 (membrane unwrap on jump). At promotion time this row will move from Pinned to Absent or Informal depending on which Rung 4 mechanic delivers it. Sits at the same admission-contract layer as Surface Inspection / Toolbox / Grammar — between primitives and rendering. |
+
+**Role and kind are NOT admission layers.** They are cross-layer discriminant attributes. A new role's admission is governed jointly by entity invariants (structural constraints: e.g. `message` requires `payload.role ∈ {user,assistant,system}`), grammar admission (visual and inspection-lens treatment), and projection source contract (which sources include the role). No independent role-admission contract. `kind` (circle / rrect) is narrower still — a pure grammar discriminant with no invariant or projection overlap.
+
+**What this entry does NOT do.**
+
+- Does not mandate a uniform contract shape across layers. Forcing realm-style checklists onto grammars or toolbox actions is the principle's failure mode.
+- Does not create a runtime gate. Existing enforcement (invariants, certification table) stays as-is; no new machinery is implied.
+- Does not forbid introducing a primitive without a contract in place. Absent rows in the ledger are honest debt markers, not refusal signals.
+
+### Prime Prompt
+
+*(Authored by Mark Holak.)* A minimal causal prompt that, when injected into a capable model, reconstructs the trajectory of an originating system without requiring replay of the full conversation history. See `docs/specs/concepts/prime-prompt-conjecture.md`.
+
+### Cognitive Heatsink
+
+*(Authored by Mark Holak.)* A thermodynamic model of thought-to-resolution through computational dissipation. See `docs/specs/concepts/cognitive-heatsink.md`. Maps to sub-token events as discrete thermal transfer steps.
+
+### Reference Traversal Continuity
+
+*(Authored by Mark Holak. Preserved under Invariant **I9**.)*
+
+A kernel-level commitment that the act of following a reference from one entity to another is invariant across the kinds of entities being traversed and across the realm or representational layer the traversal currently inhabits. The traversal does not truncate at realm boundaries, truth-class boundaries, type-layer boundaries, or observability boundaries.
+
+Continuity is carried by the existing kernel-side bookkeeping (`parent_id`, `origin_realm` + `origin_id`, `correlation_id`, `causation_id`, `derived_from`, edge kinds, sub-token parentage). The doctrine names what those primitives jointly enable.
+
+This is a doctrine of **motion**, not of **geometry**. Projection grammars (chat-lineage, containment-pack, equal-peer, future grammars) are downstream rendering decisions that choose how to display a region of the traversal field; they neither define, constrain, nor constitute the traversal itself. Coil, hydra, shell, treemap, and every other rendered cluster shape are choreographies — many other choreographies are equally valid. The motion neither requires nor privileges any of them.
+
+Articulated immediately after the GitHub Actions third-domain proof, which made the cross-domain continuity concretely visible: chat sub-tokens, filesystem containment, and workflow run/job/step descents are not three patterns held together by the adapter contract; they are three surface expressions of one continuous motion that the adapter contract gates entries to. See `concepts/reference-traversal-continuity.md` for the full doctrine and its relationship to companion concepts (Pillar 0.5 perspective projection, Pillar 0.75 transparency, Pillar 0.9 closed primitive set, Prime Prompt Conjecture, Cognitive Heatsink, Signal Telemetry Doctrine).
+
+---
+
+## Distinguishing pairs (do not confuse)
+
+- **Realm** vs. **Subsystem** — realms are sovereign external systems; subsystems are parts of Core.
+- **Incorporate** vs. **Absorb** — realms are incorporated (conduit); SA-authored code is absorbed (consolidated).
+- **Event** vs. **Command** — events are records of what happened; commands are instructions or intents.
+- **Canonical** vs. **Projected** — canonical is truth at its native home; projected is Core's non-canonical mirror.
+- **Projected** vs. **Cached** — both are non-canonical; cached carries an explicit TTL; projected is kept live and refreshable.
+- **Inferred** vs. **Derived** — inferred is produced by an LLM or heuristic; derived is deterministic computation from known inputs.
+- **Entity** vs. **Record** — an entity lives in Core; a record lives in a realm; a projection is an entity that *represents* a record.
+- **Projection** (the mirror) vs. **Projection Source** vs. **Projection Arbiter** vs. **Projection Slot** — four distinct read-path concepts that share a word. *Projection* (the mirror) is the entity-side reflection of a realm record (truth-class level). *Projection Source* is a viewer-scoped row producer (read-path composition level). *Projection Arbiter* is the surface-scoped composer of sources (read-path orchestration level). *Projection Slot* is a named rendering surface bound to a query (rendering level). The four do not substitute for each other.
+- **Quest** vs. **Job** — quests are narrative direction (authored, judged); jobs are executable work (scheduled, performed, resolved by reality). One quest may yield many jobs; no automatic promotion in either direction. See I10.
+
+---
+
+## Usage rules
+
+1. Every spec document MUST use these terms in their defined sense.
+2. When a new term enters the vocabulary, it MUST be added here before being used in other specs or in code.
+3. Class names and log messages SHOULD mirror these terms.
+4. When translation between Core's vocabulary and a realm's native vocabulary is necessary, it happens in the adapter, not in the spec.
+
+---
+
+## Attribution
+
+The framework expressed in this document sits inside a larger lineage:
+
+```
+CR ⊇ CA ⊇ JourneySeeker ⊇ MissionNet/MeshNet ⊇ SA-Orchestration ⊇ Brand ⊇ Client
+```
+
+Causal Relativity, Causal Agentics, and JourneySeeker are pre-existing intellectual property authored by Mark Holak, preserved under Invariant **I9** and Section 5.1 carve-outs of the CTO Employment & Equity Agreement. MissionNet/MeshNet is the Corporate-Campaign theme. SA-Orchestration is the current implementation slice. Brand and Client labels are the rendering layer (see `concepts/concept-vs-label.md`).
+
+Each layer below renders, specializes, or themes the layer above. No layer below replaces the layer above. See `concepts/lineage-chain.md` for the full doctrine.
+
+Implementation and glossary in this document: © Sleeper Agents LLC.
+
+Named conceptual framework elements (Prime Prompt, Cognitive Heatsink, Russell-Ouroboros Conjecture, PR notation, quanta-of-LLMs / information-lattice framing): authored independently by Mark Holak. See `docs/specs/concepts/` for the preserved artifacts and full author credit.

SA-orchestration MD/asterion/02-invariants.md

@@ -0,0 +1,180 @@
+# MissionNet System Invariants (v0.1)
+
+*Authored by Mark Holak. Adapted into Core by implementation.*
+
+These are not implementation details. They are **laws**. Violations are recorded to `sa_invariant_violation`; severe violations raise exceptions. Code that violates an invariant fails review.
+
+The enforcement surface lives in `includes/enforcement/class-sa-invariants.php`. Every invariant here has a stable id (`I1`–`I9`) used in the violation log. A bug tracker can link against these ids.
+
+---
+
+## Foundational asymmetry
+
+The invariants below exist because Core distinguishes between truth classes: **canonical, projected, cached, inferred, derived, synthetic**. These classes are asymmetric — they cannot collapse into each other. That asymmetry is what prevents Russell's paradox from re-entering through the back door: a system that consumes itself can only stay coherent if the act of consumption preserves distinctions as it moves. The timeless lattice translates through spacetime precisely because the asymmetry survives the motion.
+
+Without these invariants, the asymmetry decays, the classes collapse, and the system begins to lie to itself about what is real.
+
+---
+
+## I1 — Core must not claim canonical ownership of incorporated realm data
+
+Incorporated realms (FluentCRM, Jira, QuickBase, QuickBooks, PortTracker's Node service, arbitrary APIs) remain the canonical source of their own records. Core mirrors, mediates, and audits — never authors canonical state on a realm's behalf unless that realm is Core itself.
+
+**Enforcement:**
+- `SA_Ingest::upsert_entity` stamps `truth_class = projected` by default on all ingested realm records.
+- A realm adapter's `truth_class_for_concept()` may *only* return `canonical` for concepts whose canonical home is Core (rare).
+- Any attempt to write `truth_class = canonical` on an entity with a non-`sa-core` `origin_realm` is rejected.
+
+**Violation severity:** fatal.
+
+---
+
+## I2 — Every surfaced datum must declare truth_class
+
+Entities, projections, cache rows, AI summaries, and adapter payloads must carry a valid `truth_class`. Without this, viewers cannot distinguish a canonical fact from an LLM guess.
+
+**Enforcement:**
+- `SA_Entity::create()` calls `SA_Invariants::check_truth_class_declared()`.
+- Default for unknowable-origin entities is `canonical`; default for ingest is `projected`; default for LLM output is `inferred`. All three are valid; absence of any value is not.
+
+**Violation severity:** fatal.
+
+---
+
+## I3 — Every cross-realm action must be causally traceable
+
+A change initiated in Core that reaches (or originated in) an external realm must trace to an actor, a causation id, and a correlation id. `SA_Structural_Audit::trace_origin()` must be able to walk backward from any resulting state to the first user-attributed act.
+
+**Enforcement:**
+- `SA_Provenance::enforce()` is called before any cross-realm mutation.
+- Audit rows carry `correlation_id` + `causation_id`.
+
+**Violation severity:** error (blocks the action; recoverable by retrying with provenance attached).
+
+---
+
+## I4 — No adapter may emit a record without native identity + realm provenance
+
+Adapter pulls MUST populate `origin_realm` + `origin_id` (directly or via `external_key`). Without this, the record cannot be re-matched, cannot be pushed back, and cannot be audited across the realm boundary.
+
+**Enforcement:**
+- `SA_Invariants::check_realm_provenance()` is called on every ingest mutation.
+- `SA_Ingest` rejects payloads missing these fields.
+
+**Violation severity:** fatal.
+
+---
+
+## I5 — MissionNet must degrade without corrupting realm integrity
+
+When Core fails (offline, bugged, under attack), the client's native realms must not suffer collateral damage. This is the philosophical *tool test* expressed as a technical law.
+
+**Enforcement:**
+- Adapter writes (`push`) must be idempotent per `idempotency_rules()`.
+- Bulk operations must be chunked + resumable.
+- Health-check endpoints must fail closed — Core not reachable means ingest halts, not silently half-writes.
+- Adapter certification checklist item: `failure_path_verified` + `rollback_defined`.
+
+**Violation severity:** warn at design time, error at runtime.
+
+---
+
+## I6 — Cache may never silently replace source verification in high-trust paths
+
+Cache accelerates; cache does not become truth. When the caller asks for a high-trust answer (regulated domains, financial totals, legal records), Core must re-verify against the canonical realm, not return a cached projection.
+
+**Enforcement:**
+- Per-adapter cache TTLs declared in `capability_matrix()`.
+- High-trust query paths pass `verify_live: true` to the executor/realm; cache is skipped.
+- A future policy engine may classify concepts as high-trust and force verification.
+
+**Violation severity:** error in high-trust contexts; warn otherwise.
+
+---
+
+## I7 — AI output must remain explicitly derivative
+
+No LLM output may be stored or surfaced as canonical truth without an explicit canonical source reference or a recorded human affirmation.
+
+**Enforcement:**
+- `SA_Executor` stamps completion entities with `truth_class = inferred`.
+- `SA_Entity::create()` calls `SA_Invariants::check_ai_output_not_canonical()`. Attempting to create an AI-sourced entity with `truth_class = canonical` without either `source_refs` (non-empty) or `human_affirmed_at`+`human_affirmed_by` is rejected.
+- Promotion from `inferred` → `canonical` or `projected` requires an explicit endpoint call (future work) that records the promoting actor + timestamp.
+
+**Violation severity:** fatal.
+
+---
+
+## I8 — Destroying Core must not destroy incorporated realms
+
+This is I5's strongest form. If Core is deleted tomorrow, FluentCRM still works, QuickBooks still works, Jira still works, PortTracker still works. Core owns no canonical realm data. Cache is non-canonical by construction. Push-backs are immediate, not batched into Core's own persistence.
+
+**Enforcement:**
+- Adapter certification checklist item: `source_identity_preserved` + `native_ids_preserved`.
+- Contractual, not just technical: the product terms explicitly disclaim any Core-only source of truth for realm concepts.
+- Periodic audit: `SA_Adapter_Certification` re-runs on each adapter release and the passed flag is visible to operators.
+
+**Violation severity:** fatal at certification; a failing adapter cannot go live.
+
+---
+
+## I9 — Attributable concepts and the framework lineage must not be rephrased as AI-original
+
+Both **named concepts** and **the framework lineage that contains them** must carry author attribution wherever surfaced.
+
+**Named concepts** (authored by a human and preserved verbatim under this invariant) include the Russell-Ouroboros Conjecture, the Prime Prompt Conjecture + PR notation, the Cognitive Heatsink model, the Signal Telemetry Doctrine, the Reference Traversal Continuity Doctrine, the Story Seed pattern, the Concept-vs-Label doctrine, the Compass Doctrine, the Attention Doctrine, the Quest-vs-Job distinction, and any subsequent attributable work added to `docs/specs/concepts/`.
+
+**The framework lineage** is the chain Causal Relativity ⊇ Causal Agentics ⊇ JourneySeeker ⊇ MissionNet/MeshNet ⊇ SA-Orchestration ⊇ Brand ⊇ Client (see `concepts/lineage-chain.md`). The structural primitives at each layer (truth class taxonomy, compass roles, description-as-contract, seed-vs-canonical, projection vs canonical, actor/realm/adapter, Quest/Job distinction) are framework primitives, not implementation primitives.
+
+AI-generated text that paraphrases or adapts either named concepts or framework primitives must reference the original author and must not present the concept as newly originated by the AI or by the implementation layer.
+
+**Enforcement:**
+
+- The spec pack under `docs/specs/` carries attribution frontmatter.
+- `docs/specs/concepts/` preserves the original authored artifacts verbatim with explicit author credit.
+- AI output passing through Core that draws on attributable concepts or framework primitives must reference them (adapter-level policy, future work).
+- Adapter certification: AI summarizers that produce text must not strip authored-concept attribution.
+- Seed generators must not synthesize content that re-authors framework primitives as implementation-original. INTERPRETIVE-mode synthesis is bound by this clause.
+
+**Violation severity:** warn at generation time; fatal at publication time.
+
+---
+
+## I10 — No automatic conversion between Quest and Job
+
+A Quest may not be promoted to a Job, and a Job may not be elevated to a Quest, without an explicit human act recording the conversion.
+
+The reason: a Quest lives in the realm of authored intent — admissible uncertainty, possible alternatives, future framing. A Job lives in the realm of resolved consequence — it happened or did not. Auto-conversion collapses one into the other and erases the distinction the author made between direction and execution.
+
+**Enforcement:**
+
+- Quest → Job conversion requires an actor + timestamp + recorded conversion event in the audit log.
+- Job → Quest elevation (rare) requires the same.
+- A "Convert to Job" UI action that creates the conversion event with explicit human click is acceptable. A scheduled background job that auto-promotes without that event is not.
+- Reality resolves Jobs; humans resolve Quests. A system that conflates the two collapses the compass (see `concepts/compass-doctrine.md`).
+
+**Violation severity:** error.
+
+---
+
+## Notation
+
+Every invariant check logs a row to `sa_invariant_violation` with:
+
+- `invariant_id` — one of `I1`…`I9`
+- `severity` — `warn | error | fatal`
+- `target_entity_id` / `target_audit_id`
+- `actor_id`
+- `details` — JSON-encoded context
+- `acknowledged_at` / `acknowledged_by` — operational triage
+
+Operational review dashboards can render violations grouped by `invariant_id` and sort by severity.
+
+---
+
+## Next
+
+- Wire all cross-realm mutation paths (push, pull, ingest) through `SA_Invariants::assert_or_throw()`.
+- Add enforcement to the presentation layer: UI must display `truth_class` on every surfaced datum (stamp in the top corner of every rendered entity).
+- Extend audit trace with chain-coherence checks: if a row claims a causation_id, that row must exist.
+- Build the policy engine layer so I6 (high-trust) and I9 (attribution) become user-configurable.

SA-orchestration MD/asterion/03-realm-adapter-contract.md

@@ -0,0 +1,282 @@
+# MissionNet Realm Adapter Contract (v0.1)
+
+*Implementation © Sleeper Agents LLC. Contract governed by invariants authored with Mark Holak's conceptual framework.*
+
+Every realm adapter (FluentCRM, Fluent Support, Fluent Boards, Jira, QuickBase, QuickBooks, Salesforce, HubSpot, PortTracker's Node service, arbitrary REST/GraphQL/DB) implements `SA_Realm_Adapter`. This document is the formal contract.
+
+An adapter is **complete when it preserves origin, survives failure, emits audit, and passes certification** — not when it "functions."
+
+---
+
+## Interface
+
+```php
+interface SA_Realm_Adapter {
+    public static function realm_id(): string;
+    public static function capabilities(): array;
+    public static function concept_map(): array;
+    public static function pull(string $concept, array $filter, array $context): array;
+    public static function push(string $concept, SA_Entity $entity, array $context): array;
+    public static function watch_hooks(): array;
+    public static function capability_matrix(): array;       // formal gates
+    public static function idempotency_rules(): array;       // replay behavior per op
+    public static function truth_class_for_concept(string $concept): string;
+}
+```
+
+---
+
+## `realm_id()`
+
+Short, stable identifier. Examples: `fluent-crm`, `fluent-support`, `fluent-boards`, `jira`, `quickbase`, `quickbooks`, `porttracker-node`.
+
+Must be unique across all adapters in a given Core install. Used as the `origin_realm` on every entity the adapter produces.
+
+---
+
+## `capabilities()`
+
+Set of strings from: `read`, `write`, `watch`, `bulk`, `incremental`, `idempotent_push`.
+
+- `read` — adapter can pull records from the realm.
+- `write` — adapter can push changes back into the realm.
+- `watch` — adapter subscribes to realm events (webhook or WP hooks).
+- `bulk` — adapter supports full snapshot pulls.
+- `incremental` — adapter supports `since` cursor / delta pulls.
+- `idempotent_push` — repeated push calls with the same payload are safe.
+
+A read-only adapter declares only `read` (and optionally `watch`, `bulk`, `incremental`).
+
+---
+
+## `payload.attributes` namespace convention
+
+Structured realm-side metadata that Core stores on an ingested entity goes under `payload.attributes` — a reserved sub-object. Freeform realm-native blobs remain elsewhere in `payload` (e.g., `payload.raw`, `payload.body_markdown`), but any field an adapter intends to be *addressable* — readable by the trace panel, queryable by future projections, or filter-eligible — belongs in `attributes`.
+
+```php
+$entity->payload = [
+    'attributes' => [
+        'mime_type'    => 'application/pdf',
+        'size_bytes'   => 12345,
+        'modified_at'  => '2026-04-23T10:15:00Z',
+        'basename'     => 'spec.pdf',
+        'extension'    => 'pdf',
+    ],
+    'raw' => [/* whatever realm-native detail the adapter wants to retain */],
+];
+```
+
+**Purpose.** Two-fold:
+
+1. Adapters converge on a predictable shape for structured fields. The FS adapter, the Jira adapter, the QuickBase adapter all put their structured metadata in `attributes`. A downstream reader (trace panel, future filter surface) knows where to look without realm-specific code.
+2. A later promotion to typed columns — if cross-realm queries demand it — is a rename migration, not a schema redesign. `payload.attributes.mime_type` becomes `entity.attributes.mime_type` or a separate `sa_entity_attribute` table without touching adapter code.
+
+**Discipline.** `attributes` values SHOULD be JSON-scalar (string / number / boolean / null) or flat arrays thereof. Nested objects inside `attributes` are permitted but signal that a sub-concept may want its own entity and containment edge instead.
+
+**Not canonical.** The `attributes` convention does not change truth-class. A projected entity's `payload.attributes` is still projection data; the realm remains canonical.
+
+---
+
+## `concept_map()`
+
+Declares how realm concepts translate into Core entity roles and edge kinds.
+
+```php
+[
+    'ticket'  => ['role' => 'job',     'band' => 3],
+    'agent'   => ['role' => 'agent',   'band' => 3],
+    'customer'=> ['role' => 'agent',   'band' => 3],
+    'reply'   => ['role' => 'message', 'band' => 4],
+    'edges'   => [
+        'ticket->agent'    => ['kind' => 'depends',  'weight' => 0.8],
+        'ticket->customer' => ['kind' => 'depends',  'weight' => 1.0],
+        'reply->ticket'    => ['kind' => 'contains', 'weight' => 1.0],
+    ],
+]
+```
+
+Concept names are adapter-scoped (no collision across realms). Edge rules describe how relationships in the realm become typed edges in Core.
+
+---
+
+## `capability_matrix()`
+
+Turns "tool not silo" into enforceable behavior:
+
+```php
+[
+    'read'                        => true,
+    'write'                       => true,
+    'delete'                      => false,
+    'impersonation'               => false,
+    'service_principal'           => true,
+    'human_confirmation_required' => ['delete', 'bulk_write', 'schema_change'],
+    'simulation_only_mode'        => true,
+]
+```
+
+Core consults this matrix before dispatching every operation. An adapter that does not declare `delete = true` cannot delete; an operation listed in `human_confirmation_required` cannot execute without a confirmed human action; `simulation_only_mode = true` enables dry-run mode for destructive operations.
+
+---
+
+## `idempotency_rules()`
+
+Per-operation replay behavior:
+
+```php
+[
+    'pull'  => [
+        'idempotent'          => true,
+        'replay_safe'         => true,
+        'conflict_resolution' => 'last_write_wins',
+    ],
+    'push'  => [
+        'idempotent'          => false,
+        'replay_safe'         => false,
+        'conflict_resolution' => 'reject',
+    ],
+    'watch' => [
+        'idempotent'          => true,
+        'replay_safe'         => true,
+        'conflict_resolution' => 'last_write_wins',
+    ],
+]
+```
+
+`conflict_resolution` values: `last_write_wins` | `reject` | `human_review`.
+
+A non-idempotent `push` must never be retried without an explicit policy decision.
+
+---
+
+## `pull(concept, filter, context)`
+
+Returns a list of `SA_Ingest`-shaped mutations:
+
+```php
+[
+    [
+        'op'     => 'upsert_entity',
+        'entity' => [
+            'external_key' => '<native_id>',   // REQUIRED (or origin_id directly)
+            'role'         => 'job',
+            'kind'         => 'rrect',
+            'payload'      => [...],
+            'truth_class'  => SA_Truth_Class::PROJECTED,   // default
+        ],
+    ],
+    [
+        'op'   => 'upsert_edge',
+        'edge' => [
+            'source_id'   => '...',
+            'target_id'   => '...',
+            'kind'        => 'depends',
+            'weight'      => 0.8,
+            'intentional' => true,
+        ],
+    ],
+    [
+        'op'          => 'attach_source',
+        'entity_id'   => '...',
+        'priority'    => 10,
+        'source_payload' => [...],
+    ],
+]
+```
+
+**Provenance minimums are MANDATORY** (Invariant I4). Every upserted entity must carry either `external_key` (from which `origin_realm` + `origin_id` are derived) or `origin_realm` + `origin_id` explicitly.
+
+**Truth class default is `projected`** — non-canonical mirror of the realm's canonical state. Only adapters whose concept is genuinely advisory (weather forecasts, suggestions) may return `inferred`.
+
+---
+
+## `push(concept, entity, context)`
+
+Apply a Core-side change back into the realm.
+
+Returns:
+
+```php
+[
+    'ok'          => true,
+    'external_id' => '<realm-assigned-id-if-new>',
+    'error'       => null,
+    'trace_token' => '<optional-realm-trace-handle>',
+]
+```
+
+**Idempotency:** if declared in `idempotency_rules()`, `push` MUST be safe to retry. The adapter is responsible for deduplicating on the realm side (using the entity's `id` or a synthetic idempotency key).
+
+**Never mutate without action path.** A push that was not triggered by a command (or an audited automation policy) is a protocol violation.
+
+---
+
+## `watch_hooks()`
+
+```php
+[
+    ['hook' => 'fluentcrm/contact_created',  'handler' => [self::class, 'on_contact_created'],  'priority' => 10],
+    ['hook' => 'fluent_support/ticket_reply', 'handler' => [self::class, 'on_reply'],            'priority' => 10],
+]
+```
+
+Core's `SA_Realm_Registry::wire_all_watchers()` attaches these on boot. The handler must emit ingest mutations (not directly mutate Core state), so that the ingest pipeline's enforcement gates apply uniformly.
+
+---
+
+## `truth_class_for_concept(concept)`
+
+Returns one of `SA_Truth_Class::ALL`. Default: `projected`.
+
+- Realm concepts that are authoritative at the realm: `projected`.
+- Realm concepts that are explicitly advisory: `inferred`.
+- Core-authored concepts (rare): `canonical`.
+- Cache-only concepts with TTL: `cached` (declared by the adapter's cache layer, not usually by the adapter itself).
+
+---
+
+## Certification Checklist
+
+An adapter is **not live** until these pass. Recorded to `sa_adapter_certification`.
+
+| Check | Meaning |
+|---|---|
+| `source_identity_preserved` | Realm's native id is preserved on every ingested record and round-trippable through push. |
+| `native_ids_preserved` | `origin_id` survives every transformation in and out. |
+| `read_path_verified` | Pull returns records that successfully deserialize as Core entities. |
+| `write_path_verified` | Push creates or updates a realm record and returns the native id. |
+| `failure_path_verified` | Failures (network, 4xx, 5xx, timeouts) raise structured errors; no silent half-writes. |
+| `stale_cache_behavior_verified` | When cache is stale and the caller demands high-trust, the adapter re-verifies against the realm. |
+| `audit_event_emitted` | Every pull and push produces a `sa_structural_audit` row with `origin_realm`, `correlation_id`, `causation_id`. |
+| `rollback_defined` | There is a documented compensation path for failed pushes or partial batches. |
+
+All eight must be `true` before an adapter moves from development to live. A failing certification row prevents the realm from being included in the active routing set.
+
+---
+
+## Behavioral guarantees (enforced at interface level)
+
+- Adapter **never mutates without an action path**. A push requires a command; a pull is triggered by an explicit sync or a watch event.
+- Adapter **never strips source metadata**. `origin_realm`, `origin_id`, `observed_at` survive every transformation.
+- Every record returned includes native id and source realm.
+- Outbound writes return status, external id, and (where available) a trace token.
+- Retries are idempotent where declared; non-idempotent operations require explicit policy approval to retry.
+- Error classes are normalized to `{ok, error, error_code, detail}`.
+
+---
+
+## The tool test
+
+Before any realm adapter is declared live, the operator asks:
+
+> If Core disappears tomorrow, does this realm still work at its native home?
+
+If the answer is anything but *yes*, the adapter has crossed from incorporation into absorption. That is a different category, governed by a different process (code consolidation, not conduit), and must be signaled as such. The user and the operator must both consent before an adapter is ever permitted to cross this boundary.
+
+---
+
+## Attribution
+
+Contract shape and adapter interface: © Sleeper Agents LLC.
+
+The invariants that the contract enforces (I4 realm provenance, I5 graceful degradation, I6 cache discipline, I8 tool test) implement conceptual commitments authored independently by Mark Holak. See `docs/specs/concepts/` for the foundational framework.

SA-orchestration MD/asterion/04-async-execution.md

@@ -0,0 +1,678 @@
+# Async Execution — Design Specification
+
+Status: **design approved; Phase 1 implementing as foundational substrate.**
+Target rung: 2.5 (between projection completion and zoom-quantum).
+Scope: one foundational pillar. Implementation proceeds phase-by-phase under separate directives.
+
+## Framing (authoritative)
+
+The pillar is **ownership of execution**, not "offline" as a feature.
+
+Three layers, kept distinct:
+
+- **Now Session** — the user-facing scope. The browser tab, the compose bar,
+  the field as it reads during an interactive moment. UX lives here. In
+  Phase 1 this is UNCHANGED: prompts still feel like "I asked here, it is
+  working here, this thread is mine now."
+
+- **Shadow job** — the execution substrate. A server-owned lifecycle record
+  (`sa_job`) that tracks what the executor is actually doing. Introduced in
+  Phase 1 as foundational infrastructure, with no UX surfacing. The seam
+  that makes later decoupling possible without rewriting retries, state
+  transitions, frontier selection, failure handling, or field updates.
+
+- **Offline / Subconscious** — a future user-facing mode built on the
+  shadow-job substrate. Marketing layer for background / recoverable / long-
+  running work. NOT introduced by Phase 1. Introduced only when a later
+  directive surfaces it.
+
+The instruction the rest of this spec serves:
+
+> Treat shadow jobs as foundational infrastructure introduced now, but keep
+> their behavior scoped to the current Now Session until a later directive
+> surfaces them as an explicit Offline/Subconscious capability.
+
+---
+
+## 0. Scope note
+
+This spec describes **async prompt execution** as a first-class capability.
+
+It does NOT cover:
+- The client-state race bug-fix (a separate, independent commit — closes a symptom of the sync model; lands before or alongside phase 1 here).
+- Implementation commits (each phase below becomes a directive; each directive becomes one or more commits).
+
+It DOES cover:
+- What a prompt job is, and how it differs from the current request.
+- The canonical state machine.
+- The storage model.
+- The worker strategy (comparison + decision + rationale).
+- The client interaction model (comparison + phased choice).
+- A phased migration plan where each phase ships a working system.
+- The failure / retry / recovery model.
+- Explicit tradeoffs and risks.
+- Measurable success criteria.
+
+---
+
+## 1. Motivation and Current Limitations
+
+### Today
+
+- `POST /sa-core/v1/prompt` is synchronous. The REST thread calls `SA_Executor::run`, which calls the adapter via `wp_remote_post`, which blocks the PHP request for up to 180 seconds (after the recent timeout raise).
+- The browser tab owns the entire prompt lifecycle. The client's `fetch()` holds the connection; if the tab closes, the server continues running but the user loses all visibility into the outcome.
+- Two prompts submitted in parallel are two parallel PHP workers, each doing a long cURL wait, with zero coordination, no priority, and no recovery if one of them crashes.
+- The just-observed concurrent-submit race (two prompts attaching to the same parent) is a symptom: client-side `activeCtxRootId` is the only source of truth for "which node is the continuation root," so timing conflicts between user navigation and async resolution are inevitable.
+
+### Why this is structural, not cosmetic
+
+1. **Rung 5 (operator realism) is blocked.** Tests that simulate load, capacity planning, reliability SLAs, and meaningful metrics all require async job execution. Every one of these is meaningless against a sync model.
+2. **Rung 4 (zoom-quantum engine) gets much harder on sync.** The engine wants cheap state-transition re-renders. Pushing state through long sync calls + `/mission/recent` refreshes introduces races we'd have to hunt repeatedly.
+3. **Rungs 3 and 6 (self-hosting, carma-audit absorption) produce entity streams that shouldn't block HTTP.** Scanner runs, doc ingestion, code ingestion — none of these should tie up a web request.
+4. **The tab is not a reliable process owner.** Real work — long code generations, multi-step agent chains, background analyses — must survive a closed tab.
+5. **Browser-side state conflicts are fundamental with sync.** The concurrent-submit race is one; future race surfaces (multi-user live editing, real-time collaboration) are coming. Moving execution state authority to the server closes these by construction.
+
+---
+
+## 2. Execution Model
+
+### What is a "prompt job"
+
+A **prompt job** is the unit of work that executes the `SA_Executor` pipeline against a specific prompt entity. It is:
+
+- A durable record with its own UUID identity (distinct from the prompt entity).
+- A pointer to a persisted prompt entity (`prompt_id`).
+- A member of the queue with a state, a priority, and a retry budget.
+- Owned by the server, not the browser.
+- Inspectable, retriable, cancellable, supersedable — as a first-class operation.
+
+### How it differs from the current request model
+
+| Concern | Today (sync) | Proposed (async) |
+|---|---|---|
+| Who owns the pipeline's lifecycle? | The REST thread | The worker layer |
+| Where is "in-progress" state? | PHP memory + browser memory | `sa_job` DB row |
+| Does closing the tab kill the work? | No (it continues) but the user loses visibility | No — and the user regains visibility on reload |
+| Can two prompts run simultaneously? | Only as two parallel PHP workers with no coordination | Yes, first-class, priority-ordered |
+| Can a failed execution be retried cleanly? | Via `retry_prompt` after the fact | Built into the state machine |
+| Can the user inspect queued / running work? | No | Yes (CLI phase 2; UI later) |
+
+### Canonical lifecycle
+
+1. **Submit.** `POST /prompt` creates:
+   - Prompt entity (as today, synchronously within the request — this is fast; the adapter call is what blocks).
+   - `sa_job` row with `state='queued'`.
+   - Returns **`202 Accepted`** with `prompt_id`, `job_id`, and initial state. Target: response within 50ms.
+2. **Enqueue.** Client adds the prompt to its `entities[]` array with the job's state, renders a "queued" drop. Client begins polling (phase 2) or listening via SSE (phase 4).
+3. **Claim.** A worker polls for the highest-priority queued job. Transactional update: `state='queued'` → `state='running'`, `worker_claim=<uuid>`, `claimed_at=now`.
+4. **Run.** The worker invokes `SA_Executor::run_claimed(job_id)`. This is a refactored executor entry-point that operates on an already-persisted prompt + job, not a fresh submit.
+5. **Complete.** On adapter success, the worker writes the response entity, the `flows-to` edge, the ledger row, the structural audit row (as today), and transitions the job to `state='succeeded'` with `response_id` set.
+6. **Observe.** Client sees state transitions via polling or SSE, updates the drop's visual state class accordingly.
+7. **Fail (if applicable).** On adapter error, the worker classifies the error, applies retry policy, and either re-queues the job with backoff OR marks it `state='failed'`.
+
+---
+
+## 3. State Machine
+
+### States
+
+| State | Meaning | Terminal? |
+|---|---|---|
+| `queued` | Created; waiting for a worker | No |
+| `running` | Claimed by a worker; adapter call in flight | No |
+| `succeeded` | Adapter returned OK; response entity persisted | Yes |
+| `failed` | Retry budget exhausted or non-retryable error | Yes |
+| `cancelled` | User or operator intervention | Yes |
+| `superseded` | Replaced by a newer job (e.g., user retried) | Yes |
+
+Once a job enters a terminal state, it does not change. A retry does **not** mutate an existing job — it creates a **new job** that references the old one via `supersedes`.
+
+### Transitions
+
+```
+queued      → running      : worker successfully claims
+queued      → cancelled    : user/operator action before claim
+running     → succeeded    : adapter OK + response entity written
+running     → queued       : transient failure; attempt < max_attempts; apply backoff
+running     → failed       : retry budget exhausted OR non-retryable error
+running     → failed       : stuck (started > 15 min ago, no heartbeat) via cleanup
+running     → cancelled    : operator kill (response discarded even if it arrives later)
+succeeded   → superseded   : user-initiated retry replaces result
+failed      → superseded   : user-initiated retry
+cancelled   → superseded   : user-initiated retry after cancel
+```
+
+### Heartbeat model
+
+While `state='running'`, the worker MUST update `running_heartbeat_at` every 30 seconds. A separate cleanup task (run via system cron every 5 minutes) reclaims jobs where `running_heartbeat_at < now() - 5min` back to `state='queued'` (if `attempt < max_attempts`) or to `state='failed'` (else).
+
+### Triggers
+
+- `queued` ← `SA_Executor::enqueue` (called from REST handler).
+- `running` ← worker process picks up a `queued` job and wins the claim race.
+- `succeeded` ← worker completes execution and commits.
+- `failed` ← worker exhausts retries OR cleanup declares job stuck.
+- `cancelled` ← CLI `wp sa-core cancel-job <id>` OR admin action.
+- `superseded` ← a new job is created referring to this one via `supersedes`.
+
+---
+
+## 4. Storage Model
+
+### Decision: new `sa_job` table
+
+Not overloading `sa_entity`.
+
+Rationale:
+- `sa_entity` represents authored knowledge: the user's prompt, the LLM's response, the derived context. It has one durable identity per artifact.
+- `sa_job` represents execution: a prompt may have multiple execution attempts (retries), each with its own claim, timing, errors, heartbeats. Conflating these with entity state confuses semantics and crowds the entity row.
+- Keeping them separate means: `sa_entity` stays durable knowledge; `sa_job` stays ephemeral execution records. Queries stay clean: "show me the user's recent prompts" is a `sa_entity` query; "show me what's queued" is a `sa_job` query.
+
+### Schema
+
+```sql
+CREATE TABLE {prefix}sa_job (
+    id                       CHAR(36) NOT NULL,
+    prompt_id                CHAR(36) NOT NULL,
+
+    state                    VARCHAR(16) NOT NULL DEFAULT 'queued',
+        -- queued | running | succeeded | failed | cancelled | superseded
+
+    priority                 TINYINT UNSIGNED NOT NULL DEFAULT 50,
+        -- lower number = higher priority
+        -- 0-10: urgent (interactive, current-tab)
+        -- 20-40: normal user-initiated background
+        -- 50: default
+        -- 60-90: bulk / scheduled / idle-time
+        -- 100: lowest (opportunistic)
+
+    attempt                  SMALLINT UNSIGNED NOT NULL DEFAULT 1,
+    max_attempts             SMALLINT UNSIGNED NOT NULL DEFAULT 3,
+
+    execution_options        LONGTEXT NOT NULL,
+        -- JSON: { model?, prefer_provider?, depth?, router_model?, ... }
+
+    worker_claim             VARCHAR(64) NULL,
+    claimed_at               DATETIME NULL,
+    started_at               DATETIME NULL,
+    running_heartbeat_at     DATETIME NULL,
+    finished_at              DATETIME NULL,
+
+    response_id              CHAR(36) NULL,
+        -- set on succeeded; points to the response entity
+
+    error_kind               VARCHAR(32) NULL,
+        -- timeout | rate_limit | provider_5xx | provider_4xx
+        -- | parse | auth | worker_crash | stuck | unknown
+
+    error_message            TEXT NULL,
+
+    supersedes               CHAR(36) NULL,
+        -- if this job replaces a previous attempt
+
+    org_id                   BIGINT UNSIGNED NOT NULL,
+    created_by               BIGINT UNSIGNED NOT NULL,
+    created_at               DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at               DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+                             ON UPDATE CURRENT_TIMESTAMP,
+
+    PRIMARY KEY (id),
+    KEY idx_state_priority_created (state, priority, created_at),
+    KEY idx_prompt                 (prompt_id),
+    KEY idx_worker_claim           (worker_claim),
+    KEY idx_org_user_state         (org_id, created_by, state),
+    KEY idx_heartbeat              (state, running_heartbeat_at)
+)
+```
+
+### Interaction with existing entity fields
+
+| Field | Lives on | Set when | Changed by jobs? |
+|---|---|---|---|
+| `correlation_id` | `sa_entity` | At prompt creation time (unchanged) | No |
+| `parent_id` | `sa_entity` | At prompt creation time (continuation semantics, unchanged) | No |
+| `causation_id` | `sa_entity` | At prompt creation time (unchanged) | No |
+| `source_refs` | `sa_entity` (response) | Written by worker at job completion | Indirectly (job runs the executor which sets it) |
+| `truth_class` / `state_class` | `sa_entity` | Set at write time (unchanged) | No |
+
+The `sa_job` table is orthogonal to the entity graph. Entities are durable structural records. Jobs are execution metadata.
+
+### Retry and supersession
+
+When a user retries a failed or succeeded prompt:
+1. Create a **new** `sa_job` row with the same `prompt_id`, new UUID, `attempt=1`, `state=queued`, `supersedes=<old_job_id>`.
+2. The old job stays in place (terminal state preserved).
+3. If the retry path requires cleaning up a prior response entity (as the current `retry_prompt` does for failed responses), that happens in the worker that claims the new job, NOT at enqueue time.
+
+This model means every execution attempt is recorded and queryable. "Show me the history of this prompt" becomes `SELECT * FROM sa_job WHERE prompt_id = X ORDER BY created_at`.
+
+---
+
+## 5. Worker Strategy
+
+### Decision: custom worker, driven by WP-CLI + system cron
+
+### Comparison
+
+**Option A: WP-Cron alone** — not chosen.
+- Pros: zero external dependencies.
+- Cons: WP-Cron spawns only on page visits (unreliable for low-traffic sites); each spawn is bound by `max_execution_time`; no native priority; no concurrency management. The "real cron hitting `wp-cron.php`" workaround mitigates the first point but the others remain.
+
+**Option B: Action Scheduler (the library)** — fallback / future option.
+- Pros: mature, battle-tested by WooCommerce and Mailpoet, has built-in claim/retry/logs, comes with an admin UI, well-understood in the WP ecosystem.
+- Cons: adds a dependency (~200KB library, or plugin requirement); its schema and patterns are WooCommerce-flavored; it wraps our job concept with its own scheduling layer that we'd then have to thread through.
+- Worth reconsidering if we ever need to interoperate with a WooCommerce-running site that already uses AS.
+
+**Option C: Custom worker** — chosen.
+- Rationale: our `sa_job` table **is** our job system. Its state machine is specific to our semantics (prompt-centric, projection-aware, org-scoped). Adding Action Scheduler on top means we'd write adapters between our table and theirs. A custom worker is ~300 lines of code, directly aligned with our data model.
+- Cons: we own the scheduler code. Edge cases (claim races, heartbeat recovery, backoff) must be solved by us. But: the surface is narrow, there's no distributed coordination to worry about (single-node plugin), and the patterns are well-known.
+
+### Custom worker implementation
+
+```
+wp sa-core run-worker [--once] [--batch-size=N] [--priority-ceiling=N]
+```
+
+Behavior in one iteration:
+1. Generate or resume a `worker_id` for this process (UUID).
+2. Claim a batch of jobs:
+   ```sql
+   UPDATE sa_job
+      SET state='running',
+          worker_claim=<worker_id>,
+          claimed_at=NOW(),
+          started_at=NOW(),
+          running_heartbeat_at=NOW()
+    WHERE state='queued'
+      AND priority <= <priority-ceiling>
+    ORDER BY priority ASC, created_at ASC
+    LIMIT <batch-size>
+   ```
+   The single-statement UPDATE is the claim atomic: whichever worker's UPDATE lands first, wins.
+3. Re-query the claimed rows by `worker_claim=<worker_id>` to get the actual job ids.
+4. For each claimed job:
+   - Call `SA_Executor::run_claimed(job_id)`.
+   - On success: set state='succeeded', response_id, finished_at.
+   - On retryable failure: if attempt < max_attempts, set state='queued' with backoff delay (encoded via `created_at += backoff`); else state='failed'.
+   - On non-retryable failure: state='failed' immediately.
+5. Spawn a heartbeat thread/callback that updates `running_heartbeat_at` every 30s while the adapter is in flight.
+6. Sleep 2 seconds. If `--once`, exit. Otherwise loop.
+
+### Driving the worker
+
+Three supported modes:
+
+**Mode 1: Single-shot via system cron** (recommended for production)
+```cron
+* * * * * wp sa-core run-worker --once --batch-size=5
+```
+Every minute, claim up to 5 jobs, process them, exit. Reliable, bounded, manageable.
+
+**Mode 2: Long-running service** (optional for high-volume)
+```
+wp sa-core run-worker
+```
+Starts a persistent worker. Polls continuously. Should be supervised (systemd / supervisor) for restarts on crash.
+
+**Mode 3: WP-Cron via wp-cron.php** (default; fallback)
+If a site has no system cron, register `sa-core-process-queue` as a WP-Cron event firing every minute. Relies on site traffic; acceptable for dev and low-traffic installs.
+
+### Heartbeat and stuck-job cleanup
+
+Separate command:
+```
+wp sa-core reclaim-stuck-jobs
+```
+System cron: every 5 minutes.
+
+Behavior:
+- Find jobs where `state='running'` AND `running_heartbeat_at < now() - 5 minutes`.
+- For each:
+  - If `attempt < max_attempts` AND `started_at > now() - 15 minutes`: reclaim to `state='queued'`, clear `worker_claim`.
+  - Else: `state='failed'`, `error_kind='stuck'`.
+
+### Double-execution safety
+
+Risk: worker A claims a job, loses heartbeat, cleanup reclaims to queued, worker B claims and runs. Worker A's adapter call may still be in flight. Both workers could reach the "complete" step.
+
+Mitigation: all state-finalization writes (`state='succeeded'`, `response_id`, etc.) are conditioned on `WHERE state='running' AND worker_claim=<my_worker_id>`. Whichever update lands second sees no matching row and aborts silently. The first worker's result wins; the other worker's result is discarded (wasted work, but no data corruption).
+
+---
+
+## 6. Client Interaction Model
+
+### Decision: polling in phase 2, SSE in phase 4, WebSocket deferred
+
+### Comparison
+
+| Protocol | Pros | Cons | Chosen? |
+|---|---|---|---|
+| **Polling** | Simplest; works anywhere; zero new infra; trivial to implement | Latency up to poll interval; wastes bandwidth when idle (mitigated by only polling while in-flight jobs exist) | Phase 2 |
+| **Server-Sent Events** | Efficient for state updates; built into browsers (`EventSource`); one-way but that's what we need | Requires long-lived HTTP connection; may conflict with PHP `max_execution_time` on some hosts; harder to debug | Phase 4 |
+| **WebSocket** | Full-duplex; lowest latency; richest protocol | Needs separate infra (Node or Ratchet-in-PHP); significant deployment burden; overkill for our scale | Deferred |
+
+### Polling protocol (phase 2)
+
+**Submit flow:**
+
+1. Client calls `POST /prompt` with prompt text + root_entity_id + etc.
+2. Server returns `202` with `{ prompt_id, job_id, state: 'queued' }`.
+3. Client:
+   - Adds entity to `entities[]` with `state='queued'`, renders as queued drop.
+   - Starts a poll loop if not already running.
+
+**Poll loop:**
+
+- Every 2 seconds, while at least one in-flight (`queued` or `running`) job exists:
+  - Call `GET /sa-core/v1/mission/recent?since=<iso8601>`.
+  - Server returns entities with any updates since the timestamp.
+  - Client merges results by `prompt_id` (does not replace array wholesale).
+  - If all known prompts are terminal (succeeded, failed, cancelled, superseded) or no in-flight jobs remain, stop polling.
+
+**Server endpoint changes (phase 2):**
+
+- `GET /mission/recent` accepts `since=<iso8601>`. Returns only prompts updated since that time (joins `sa_job.updated_at` into the "is this updated" test).
+- Response includes an `as_of` timestamp the client uses as the next `since` value.
+
+### Field state → visual class mapping
+
+| Job state | CSS class on drop | Existing / new | Visual |
+|---|---|---|---|
+| `queued` | `is-queued` | **New** | Slow breath, paler halo; "waiting" reading |
+| `running` | `is-pending` | Existing | Current pending animation (dashed rotating halo) |
+| `succeeded` | (none) | Existing | Default settled drop |
+| `failed` | `is-orphan` | Existing | Muted salmon halo + retry chip |
+| `cancelled` | `is-cancelled` | **New** | Greyed-out, no retry chip |
+| `superseded` | hidden OR `.is-superseded` | **New** | Typically hidden; shown faded if a debug toggle enabled |
+
+Transitions:
+- `queued → running`: swap `is-queued` for `is-pending`.
+- `running → succeeded`: remove `is-pending`, merge real response data, `renderField()` for any layout adjustment.
+- `running → failed`: swap `is-pending` for `is-orphan`.
+
+### SSE protocol (phase 4, future)
+
+- Client opens `EventSource('/sa-core/v1/mission/events')` instead of polling.
+- Server streams events like `event: job.state_changed\ndata: {"prompt_id":"…","state":"succeeded",…}\n\n` whenever a job's state changes for this viewer.
+- Client falls back to polling if the `EventSource` fails.
+
+### WebSocket (deferred)
+
+Adds separate infra (Node sidecar, Ratchet-in-PHP, or a managed service like Pusher). No concrete need yet. Revisit when multi-user real-time collaboration becomes a live concern.
+
+---
+
+## 7. Migration Plan
+
+### Principle: each phase ships a working system
+
+No phase leaves the codebase in a half-broken state. At every phase boundary, a user can submit a prompt and see a result.
+
+### Phase 0 — Concurrent-submit race fix (prerequisite, separate scope)
+
+- Single commit, fixes the browser-state race in the current sync model.
+- Does NOT introduce async.
+- Makes parallel-submit testing reliable, which phase 2 needs.
+
+### Phase 1 — Schema + shadow jobs (1–2 commits, zero behavior change)
+
+Goal: write `sa_job` rows alongside synchronous execution, so the data layer exists before the execution path changes.
+
+Work:
+- Migration: create `sa_job` table (schema in §4).
+- `SA_Executor::run` remains synchronous. At the end, it writes a `sa_job` row with `state='succeeded'` (or `'failed'` if the adapter errored).
+- No REST change. No client change. No worker yet.
+
+Test: CLI proof submits a prompt, verifies an `sa_job` row with correct state exists and references the prompt.
+
+Rollback: drop the table via migration down; no user impact.
+
+### Phase 2 — Async execution path (3–4 commits)
+
+Goal: move adapter invocation out of the REST handler.
+
+Work:
+- Refactor `SA_Executor` into two entry-points:
+  - `SA_Executor::run` — retained for direct synchronous use (CLI proofs, back-compat).
+  - `SA_Executor::enqueue($prompt_text, $options)` — writes prompt entity + queued job, returns ids. Fast.
+  - `SA_Executor::run_claimed($job_id)` — worker's entry-point; runs the pipeline against an existing prompt + job.
+- `POST /prompt`: call `enqueue`, return `202` with `{ prompt_id, job_id }`.
+- Client `submitPrompt`: handle `202`, render queued drop, start poll loop.
+- Server: `GET /mission/recent` accepts `since` param; returns updated rows.
+- Add worker CLI: `wp sa-core run-worker`.
+- Add heartbeat cleanup: `wp sa-core reclaim-stuck-jobs`.
+- New CSS classes: `is-queued`, `is-cancelled`.
+
+Test:
+- CLI proof: submit a prompt, verify `state=queued`, run worker once, verify `state=running` → `state=succeeded`.
+- Concurrent-submit proof: submit two prompts with different priorities (10 and 90), run worker, verify priority=10 runs first.
+- Retry proof: submit, simulate transient failure (mock adapter), verify re-queue with backoff and eventual success.
+
+Rollback: revert `POST /prompt` to call `run` synchronously. `sa_job` rows for already-queued jobs need manual cleanup (or a CLI command to replay them synchronously). Worker command stays but unused.
+
+### Phase 3 — Priority queue (1–2 commits)
+
+Goal: expose priority so active-thread prompts outrank bulk / background work.
+
+Work:
+- `SA_Executor::enqueue` accepts `priority` in options (default 50).
+- Client: no UI change. Still submits at default. Future bulk operations (Scanner, Code Lens ingestion, etc.) pass higher priority values.
+- Worker query already orders by priority — schema supports it from phase 1.
+
+Test: submit 3 prompts with priorities {10, 50, 90}; verify worker claims in that order.
+
+Rollback: trivial; remove priority from enqueue options, falls back to default.
+
+### Phase 4 — SSE layer (2–3 commits)
+
+Goal: eliminate polling overhead.
+
+Work:
+- Add `GET /sa-core/v1/mission/events` endpoint that streams SSE.
+- Server-side: when a job's state changes, broadcast an SSE event to that viewer's stream.
+- Client: detect `EventSource` support; subscribe if available; else continue polling.
+
+Test: compare SSE event timing vs polling; verify identical state propagation; verify graceful fallback when connection drops.
+
+Rollback: client falls back to polling automatically if SSE endpoint returns 404 or connection fails.
+
+### Phase 5 — Hardening (2–4 commits)
+
+Goal: operator visibility, intervention, metrics.
+
+Work:
+- `wp sa-core list-jobs [--state=] [--org=] [--since=]` — list jobs with filters.
+- `wp sa-core job-details <job_id>` — full history for a job.
+- `wp sa-core cancel-job <job_id>` — operator cancellation.
+- `wp sa-core retry-job <job_id>` — explicit requeue.
+- Optional: `wp sa-core queue-metrics` — count by state, average latency per org, error rate.
+
+Test: CLI proofs for each command.
+
+### Phase 6 — async-native features (optional, post-pillar)
+
+Built on the same `sa_job` infrastructure, no further schema changes:
+
+- Background bulk operations (Scanner, Code Lens, Doc Lens at scale).
+- Scheduled prompts (run at 2am) via a `scheduled_for` column on `sa_job`.
+- Multi-prompt chains (job B starts after job A succeeds).
+
+Not part of the async pillar's completion criteria; listed for continuity.
+
+### Test discipline at each phase
+
+Every phase ships one or more CLI proofs in the `includes/cli/` pattern already established (geodesic-proof, promotion-proof, projection-proof, claim-continuation):
+
+- `async-execution-proof`: state progression queued → running → succeeded against a synthetic prompt.
+- `priority-queue-proof`: three synthetic prompts at different priorities; verify claim order.
+- `retry-proof`: simulated transient adapter failure; verify re-queue and eventual success.
+- `heartbeat-proof`: start a synthetic running job, sleep past heartbeat window, run reclaim, verify state.
+- `concurrent-safety-proof`: simulate double-claim race; verify only one worker's writes take effect.
+
+---
+
+## 8. Failure and Retry Model
+
+### Error classification
+
+Every failure gets an `error_kind`:
+
+| `error_kind` | Meaning | Retryable? | Backoff |
+|---|---|---|---|
+| `timeout` | cURL 28 or executor-level timeout | Yes | Exponential (5s, 25s, 125s + jitter) |
+| `rate_limit` | Adapter HTTP 429 | Yes | Respect `Retry-After` header; else 60s min |
+| `provider_5xx` | Adapter returned 5xx | Yes | Exponential |
+| `provider_4xx` (non-429) | Adapter returned 4xx | No | N/A |
+| `parse` | Response body couldn't be parsed | No | N/A |
+| `auth` | Credentials invalid | No | N/A (needs operator) |
+| `worker_crash` | Worker died mid-execution | Yes (via reclaim) | Immediate |
+| `stuck` | Job has been running > 15 min | No | Terminal; mark failed |
+| `unknown` | Catch-all for unclassified errors | Yes (conservative default) | Exponential |
+
+### Retry rules
+
+- Default `max_attempts = 3`. Configurable per-enqueue via options.
+- Backoff stored as a delay on the re-queued job's `created_at`: `created_at = now() + backoff`. Worker query only claims jobs where `created_at <= now()`, so backoff is honored naturally.
+- Backoff durations:
+  - Attempt 2: 5s + random(0, 5s)
+  - Attempt 3: 25s + random(0, 15s)
+  - (After attempt 3 fails: terminal)
+
+### Timeout handling
+
+- **Adapter timeout (180s)**: cURL 28. `error_kind='timeout'`. Retryable.
+- **PHP `max_execution_time` (300s)**: worker process killed. Heartbeat lost. Reclaimed by `reclaim-stuck-jobs`.
+- **Hard job ceiling (15 minutes)**: a running job started > 15 min ago with no recent heartbeat is declared stuck. `error_kind='stuck'`. Terminal.
+
+### Dead-letter handling
+
+- Jobs that exhaust `max_attempts` go to `state='failed'` with `error_kind` set.
+- They remain visible in the user's field as `is-orphan` drops (same treatment as today's orphans from sync-failure).
+- User can retry via the retry chip (same UX as today). Retry creates a new `sa_job` row with `supersedes=<old_id>`.
+- Operator CLI: `wp sa-core list-jobs --state=failed` surfaces recent failures.
+- Operator can run `wp sa-core retry-job <id>` to force a retry without user interaction.
+
+### Stuck-job recovery
+
+- `wp sa-core reclaim-stuck-jobs` runs via system cron every 5 minutes.
+- Query: `state='running' AND running_heartbeat_at < now() - INTERVAL 5 MINUTE`.
+- For each:
+  - If `attempt < max_attempts` AND `started_at > now() - 15min`: reclaim to `state='queued'`, clear `worker_claim`.
+  - Else: `state='failed'`, `error_kind='stuck'`.
+
+### Double-execution safety
+
+Mitigation already detailed in §5: all finalization writes are conditioned on `WHERE state='running' AND worker_claim=<my_worker_id>`. Second-arriving writer sees no matching row and exits silently. First-arriving result wins.
+
+Additional safeguard: response entity writes are keyed on a deterministic id derived from `(prompt_id, adapter_request_id)` when available, so duplicate writes collide on primary key and the second `INSERT` fails gracefully (caught by the finalization code).
+
+---
+
+## 9. Risks and Tradeoffs
+
+### Risk: cron reliability on managed hosts
+
+WP Engine (and many managed hosts) run cron via `wp-cron.php` spawned on page requests. On low-traffic sites this is unreliable.
+
+**Mitigation.** Document that production deployments SHOULD use a real system cron hitting `wp sa-core run-worker --once`. The command is standalone (doesn't depend on wp-cron's spawning). An on-page-load spawn continues to work for dev and low-volume sites.
+
+### Risk: worker compute resource pressure
+
+A long-running worker process consumes PHP process slots. On shared hosting, this may conflict with web requests.
+
+**Mitigation.** Default worker mode is `--once` (cron-driven, not service-style). Batch size is tunable. For high-volume users, the operator can tune cron frequency + batch size to stay within their host's limits.
+
+### Risk: `sa_job` table growth
+
+Every prompt creates ≥ 1 job. Retries create additional jobs per prompt. Over time, the table grows unbounded.
+
+**Mitigation.** Optional archival policy (phase 5 or later): jobs in a terminal state older than 30 days get archived or removed. `wp sa-core archive-old-jobs --before=<date>`. Indexes keep queries fast regardless of row count at expected volumes; archival is an optimization, not a correctness concern.
+
+### Risk: client polling overhead
+
+Many users × many tabs × many in-flight jobs = many simultaneous polls.
+
+**Mitigation.**
+- Polls happen only while in-flight jobs exist; idle tabs don't poll.
+- Poll interval is 2s; tunable.
+- Phase 4 (SSE) eliminates this risk entirely for modern browsers.
+
+### Risk: stale merges on client
+
+If the client has an in-memory edit (user typing in compose) and a poll fetches fresh entity data, we must not discard user input.
+
+**Mitigation.** Poll merges by `prompt_id` and only updates entity-state fields (response_id, state, context_ids, etc.). Compose-input state lives in the DOM, untouched by poll handling.
+
+### Risk: concurrent-submit out-of-order display
+
+Two prompts submitted close together may complete in the reverse order (e.g., P1 is slow, P2 is fast). The field would render P2 before P1.
+
+**Mitigation.** Field display order is by `prompt.created_at`, not job completion order. Stable regardless of async resolution order. The visual `is-queued` vs `is-running` vs settled state makes the running state transparent to the user.
+
+### Tradeoff: consistency window vs latency
+
+Async means there is a window where client shows `state='queued'` while server has already transitioned to `state='running'`. Polling latency is up to 2s. SSE tightens this to sub-second.
+
+**Accepted.** Up to 2s of client-side staleness is not a meaningful UX regression; phase 4 closes it.
+
+### Tradeoff: simplicity vs ecosystem reuse
+
+Custom worker vs Action Scheduler. Custom is simpler for our narrow scope but means we own the scheduler. AS is richer but adds a dependency and adapter layer.
+
+**Accepted.** Custom for phase 2. If we ever need to coexist with an AS-using site, the `sa_job` table's facade can be driven by either our worker or an AS callback without changing job semantics.
+
+### Risk: migrating users mid-transition
+
+Between phase 1 (shadow jobs written) and phase 2 (async path switched on), a user's `sa_job` rows represent historical sync executions. When phase 2 lands, any prompt submitted mid-transition could have incomplete metadata.
+
+**Mitigation.** Phase 2 rollout during a low-traffic window. On deploy, any `sa_job` rows with `state='queued'` from pre-phase-2 (there shouldn't be any, but defensively) are either processed by the first worker run or marked `state='failed'` with `error_kind='migration'` for manual review.
+
+---
+
+## 10. Success Criteria
+
+The async pillar is complete (through phase 2) when:
+
+1. `POST /prompt` returns within 100ms, 99th percentile, regardless of adapter latency.
+2. Closing the browser tab during a prompt's execution does NOT cancel the job; reopening the site shows the completed result.
+3. Two prompts submitted to different continuation parents from different tabs are processed correctly, with no race-induced data corruption.
+4. A cURL timeout on the adapter causes an automatic retry with exponential backoff; a permanently-failing prompt surfaces as a retriable orphan after `max_attempts` exhaustion.
+5. A crashed worker's job is reclaimed within 5 minutes and either completes on the next attempt or fails cleanly.
+6. The CLI proofs described in §7's test discipline section all pass.
+7. Existing `/mission` UI works throughout — no regressions on selection, trace, thread view, promote, verdict, continuation, retry, or content-collapse.
+8. The `wp sa-core run-worker` command can be configured to run under standard system cron without supervisor-style infra.
+
+The pillar is **complete through phase 4** when additionally:
+
+9. SSE delivers state updates within 200ms of server-side transition.
+10. Polling mode still works identically as a fallback when SSE is unavailable.
+
+---
+
+## 11. Out of Scope (deliberately deferred)
+
+- **Multi-node distributed coordination.** Single-node assumption in claim locking. Revisit if horizontal scaling ever becomes a concern.
+- **Priority inversion prevention.** A long-running low-priority job blocking urgent jobs is theoretically possible but rare in our expected volume. Observe first; fix if it ever occurs.
+- **User-facing queue inspection UI.** CLI only through phase 5. A UI can be added later; `sa_job` data is already viewer-scoped via `org_id + created_by` indexing.
+- **Scheduled prompts** (`scheduled_for`): phase 6 (optional).
+- **Multi-prompt chains** (dependent jobs): phase 6 (optional).
+- **Per-org quotas** (max N concurrent running jobs): defer until multi-tenant scaling matters.
+- **Cross-process worker coordination** (multiple machines): defer until single-machine capacity is exhausted.
+- **Real-time collaboration** (two users editing the same field simultaneously): defer to the ACL / perspective-projection pillar.
+
+---
+
+## 12. Appendix: Summary of Design Decisions
+
+| Concern | Decision | Rationale |
+|---|---|---|
+| Storage | New `sa_job` table | Separate execution from knowledge; supports multiple attempts cleanly |
+| Worker | Custom WP-CLI runner | Narrow scope; direct control; ~300 lines; no new dependency |
+| Scheduling driver | System cron → `wp sa-core run-worker --once` | Reliable across hosts; standalone from wp-cron |
+| State machine | 6 states + heartbeat + supersession | Covers all observed outcomes; no ambiguity |
+| Client protocol | Polling (phase 2) → SSE (phase 4) | Ships working async in phase 2; optimizes in phase 4 |
+| Retry | Exponential backoff, max_attempts=3 | Handles transient failures; bounded pessimism |
+| Rollback | Phase-by-phase; each has a defined revert | Safe to implement incrementally |
+| Migration | Shadow jobs first (phase 1) → switch path (phase 2) | Data layer proven before execution switch |
+
+This spec is the contract. Implementation directives reference it by phase.

SA-orchestration MD/asterion/05-zoom-quantum-engine.md

@@ -0,0 +1,373 @@
+# Zoom-Quantum Engine — Design Specification (Rung 4)
+
+Status: **design draft; coil substrate shipped (Rung 3); phase plan pending per-phase directive.**
+Target rung: 4.
+Scope: multi-focal zoom as a native field gesture, not a viewport transform. Per-correlation zoom, hyperbolic envelope, cross-region pull-connection. All projections remain 2D.
+
+---
+
+## Framing (authoritative)
+
+**Zoom is a semantic quantum, not a viewport change.** Zoom belongs to a *domain of influence*, not to the screen. A conversation can be zoomed without touching any other conversation. The field carries regional density depth of zoom.
+
+Three layers of zoom, kept distinct:
+
+- **Global zoom** — the default, existing affordance (SVG viewBox). The whole field pans and scales. Useful for "where am I on the mission."
+- **Regional zoom** — per-correlation, introduced by this pillar. Each thread carries its own scalar zoom state. The user can be deeply inside thread A while thread B stays at rest. Multiple threads can be simultaneously focused at independent depths.
+- **Hyperbolic envelope** — when a regional zoom exceeds threshold, the thread's head wraps the visible workspace as a Poincaré-disk horizon. "You are inside this thread." The tail stretches toward the asymptotic center; the head becomes the event horizon.
+
+The instruction the rest of this spec serves:
+
+> The default case is to zoom the whole field. The innovation is to zoom a *conversation* — one region of influence — without perturbing the rest of the field. When two regions are simultaneously focused, the user can pull a connection between them instead of splitting the screen. Multi-focal composition is the posture; hyperbolic geometry is how we keep "where is my context" legible while compression grows infinite.
+
+---
+
+## 0. Scope note
+
+This spec describes the **zoom-quantum engine** as a user-facing field behavior + its projection math.
+
+It DOES cover:
+- The per-correlation zoom state model
+- The math of the hyperbolic envelope (Möbius transform on a Poincaré disk)
+- How regional zoom composes with the already-shipped log-spiral coil
+- Multi-focal simultaneous zoom
+- Cross-correlation pull-connection as a new edge primitive
+- Gesture vocabulary
+- Phasing
+
+It does NOT cover:
+- The Prime-Prompt / compression mechanic (separate Pillar 0 concern, deferred)
+- Server-side data model changes beyond a new edge kind (zoom is client UI state)
+- A split-screen or multi-window layout (explicitly rejected — the hyperbolic projection replaces it)
+- WebGL / 3D rendering (explicitly rejected — all projections are 2D)
+
+---
+
+## 1. What already exists
+
+Rung 3 shipped the **logarithmic-spiral coil** (commit `de4de7e`). Each correlation group renders as:
+
+```
+r_t      = r₀ · γ^t          (log-spiral radius)
+θ_t      = baseAngle + t·dθ  (angular step)
+scale_t  = γ^t               (same decay → self-similar under zoom)
+opacity_t = max(o_min, 1 − f·t)
+```
+
+The coil is already scale-invariant: a uniform scale factor `k` maps the spiral onto itself shifted by `log_γ(k)` turns. The infrastructure for "zoom descends into the tail" is in place on the math side; Rung 4 adds the UI, the per-correlation state, and the hyperbolic envelope.
+
+The `.is-coiled` class and `data-coil-index` attribute on each drop are hooks for this rung.
+
+---
+
+## 2. Primitives
+
+### 2.1 Per-correlation zoom state
+
+```
+CoilZoomState {
+  correlation_id : string        The thread this state belongs to
+  zoom           : float (≥ 0)    0 = rest; 1 = first quantum in; 2 = second; ...
+  focal_x        : float          optional: where on the screen the focus anchors
+  focal_y        : float          (defaults to the current head position)
+  pinned         : bool           if true, survives other zooms of other threads;
+                                  if false, collapses to rest when another
+                                  thread is focused (single-focus convention)
+}
+```
+
+Stored client-side. Not persisted by default; optional SA_Settings scope=user
+persistence (`field.coil.zoom_state`) is a follow-on if the UX calls for it.
+
+### 2.2 Focal stack
+
+```
+FocalStack = CoilZoomState[]
+```
+
+The ordered list of currently-focused coils. Zero-or-one at rest is the default; multi-focal is the innovation. Rendering composes their transforms.
+
+### 2.3 Hyperbolic envelope
+
+Threshold: when `zoom ≥ HYPERBOLIC_THRESHOLD` (configurable; 2.0 is a reasonable starting point), the coil's head enters **envelope mode**:
+
+- The head dilates toward the workspace boundary.
+- The rest of the coil (and any other visible content within this region) is rendered through a Möbius transform on the Poincaré disk.
+- The edge of the viewport becomes the ideal boundary at infinity.
+
+Mathematically, with the focal point at origin `a = 0`:
+
+```
+w = (z - a) / (1 - ā·z)
+```
+
+For `a = 0` this reduces to `w = z`, so we introduce zoom via composition with a pure dilation before the Möbius map:
+
+```
+z'  = scale_by_zoom · z
+w   = (z' - a) / (1 - ā·z')
+```
+
+At low zoom, the transform is near-identity. As zoom grows, points near the focal point expand outward; points near the ideal boundary asymptote there but never cross. This is the "event horizon" — infinite expansion curls into the hyperbolic limit.
+
+### 2.4 Pull-connection (cross-region edge)
+
+A new edge kind:
+
+```
+kind:          'pull-connection'  (or 'cross-region')
+source_id:     entity A's id
+target_id:     entity B's id
+intentional:   true (always — user gesture-created)
+metadata:      { author_id, created_at, gesture_kind: 'drag' }
+```
+
+Stored as a row in the existing `sa_edge` table. No schema change — `SA_Edge::KINDS` already accepts arbitrary kinds (today: link, contains, depends, influences, flows-to, continues, promoted).
+
+Rendered as a flowing line between two focused regions, distinct visually from within-thread edges (dashed? colored by author? to be decided per phase).
+
+### 2.5 Compose operator
+
+```
+render(entity) = Global_Viewport ∘ Regional_Hyperbolic ∘ Local_Coil ∘ entity.position
+```
+
+Three projections stacked:
+
+1. **Local coil** (shipped): the log spiral places older correlation members relative to their head.
+2. **Regional hyperbolic** (new): when a coil is past the threshold, apply the Möbius transform to everything within its region, centered on its head.
+3. **Global viewport**: the SVG viewBox. Pans / scales the whole field for navigation.
+
+Each layer is independently controllable. A user at rest sees only the coils (layer 1 only). A user focused on one thread with hyperbolic crossed sees layer 1 + 2. A user zooming out to find a thread uses layer 3.
+
+---
+
+## 3. Multi-focal model
+
+The posture: **multiple regions focused simultaneously, without split screens.**
+
+Scenarios:
+
+- **Single focus** (typical): one thread is zoomed in. Others sit at their rest coil. The user sees the coil-of-interest at its hyperbolic scale, other coils in the background at normal scale.
+- **Dual focus** (workspace comparison): two threads both zoomed. Their Möbius disks compose by position — e.g., one occupies the left third of the viewport, the other the right third. Content *between* them is what survives the intersection.
+- **Multi focus** (relational map): N threads focused at varied zoom levels. The field becomes a composite of hyperbolic neighborhoods, each with its own focal anchor. Resembles a relational map where the nodes are the focal points and the content around each is the locally-zoomed thread.
+
+Pull-connection is the natural gesture across this state: drag from a point inside focus A's hyperbolic neighborhood to a point inside focus B's hyperbolic neighborhood. The drag creates a cross-region edge. The edge renders as a line that passes through the ambient space between the foci.
+
+**Rejected alternative**: split-screen. Splitting the canvas into two viewports is the "click here, click there, zoom each, compare" solution. The spec rejects it as un-liquid — a literal cut in the fabric. The hyperbolic composition is the continuous alternative.
+
+---
+
+## 4. Gesture vocabulary
+
+### 4.1 Entering regional zoom
+
+- **Scroll-wheel over a coil region**: the scroll targets the coil underneath the cursor, not the global viewport. Forward = zoom in, back = zoom out.
+- Falls back to global viewport zoom when the cursor isn't over any coil's region.
+
+Implementation: hit-test the cursor against each visible coil's bounding disk. The coil whose center is closest (within a radius proportional to its current zoom) captures the scroll.
+
+### 4.2 Pin / unpin
+
+- **Click a coil's head while holding a modifier key** (e.g., Shift-click): pin this focus. Future zooms of other coils don't collapse this one.
+- **Click in empty space**: collapse all transient (non-pinned) foci to rest.
+
+### 4.3 Pull-connection
+
+- **Drag from a focused region to another focused region** (both must be at zoom ≥ some threshold). The drag creates a new `pull-connection` edge.
+- **Drop on empty space**: cancels.
+
+### 4.4 Exit / escape
+
+- **Esc** collapses all foci and returns to rest (coils at size 1, no hyperbolic envelope).
+- **Double-click a coil**: toggles between rest and last-known zoom state.
+
+---
+
+## 5. Math appendix
+
+### 5.1 Self-similar coil (shipped, Rung 3)
+
+For each correlation group:
+
+```
+t        = turn index (0 = newest head)
+baseAngle = hashJitter(correlation_id) · 2π       (per-thread starting angle)
+γ        = 0.85                                   (decay)
+dθ       = π/3                                    (60° per turn)
+r_t      = r₀ · γ^t
+θ_t      = baseAngle + t · dθ
+position_t = head_position + (r_t·cos θ_t − r₀·cos baseAngle,
+                              r_t·sin θ_t − r₀·sin baseAngle)
+scale_t  = γ^t
+```
+
+Zoom shifts the visible portion of the spiral. Under a uniform zoom of factor `k`, `scale_t → k · scale_t = γ^(t - log_γ k)`, so the spiral looks the same shifted by `log_γ k` turns. This is why zooming into the coil reveals more tail without stretching it.
+
+### 5.2 Poincaré disk (Rung 4, new)
+
+The hyperbolic plane is represented as the interior of a unit disk `|z| < 1`. Geodesics are circular arcs perpendicular to the boundary. Distance grows without bound near the boundary (the ideal horizon).
+
+A Möbius transformation preserves hyperbolic distance:
+
+```
+φ_a(z) = (z − a) / (1 − ā·z)       where |a| < 1
+```
+
+For MissionNet:
+
+- The coil's currently-focused head sits at the disk center.
+- The tail of the coil stretches toward the center (asymptotically never reaching, per the log-spiral math).
+- Other visible content is projected outward toward the boundary, compressed as it approaches — "infinite expansion curls to hyperbolic limit."
+
+Scaling for zoom level `λ ≥ 0`:
+
+```
+z'       = (1 − e^(−λ)) + e^(−λ) · z         (pre-zoom dilation centered on head)
+w        = φ_focal(z')                        (Möbius, centered on head)
+screen_w = half_viewport_size · w             (map disk to viewport)
+```
+
+At λ = 0 the transform is identity. As λ grows, `z'` approaches 1 (the boundary), the head fills the viewport, and the rest of the content compresses toward the edge.
+
+### 5.3 Composition of multi-focal Möbius
+
+Two focal points `a` and `b`, each with zoom levels `λ_a` and `λ_b`, can be composed:
+
+```
+w = Σ weights_i · φ_i(dilate_i(z))
+```
+
+For a weighted sum where `Σ weights_i = 1`. This is an approximation — the exact composition of two Möbius transforms is another Möbius transform, but picking *which* transform to use when you want BOTH foci visible requires a heuristic. The weighted-sum approximation gives a visually pleasing blend and is well-defined for any number of foci.
+
+A cleaner model: render each focused region in its own hyperbolic neighborhood, with the boundary between regions being the ambient (un-transformed) space. This is what pull-connection edges cross.
+
+---
+
+## 6. Data model changes
+
+### 6.1 No schema change for zoom state
+
+Per-correlation zoom is client-side UI state. Not persisted by default. If a user asks for their zoom state to survive reload, add:
+
+- SA_Settings key `field.coil.zoom_states`, scope=user, type=string (JSON-serialized `CoilZoomState[]`).
+
+That's one line of setting declaration; no migration needed.
+
+### 6.2 Pull-connection edge: no schema change
+
+`SA_Edge` already accepts arbitrary kinds via a `kind` column. Add `'pull-connection'` to `SA_Edge::KINDS` as a documented kind. No migration; no new table.
+
+Permissions: creating a pull-connection requires `sa-core:impose-grouping` (already a capability in the starter package — user-declared relational claims are tenant work, not operator work).
+
+---
+
+## 7. Phased implementation plan
+
+Phases ship independently; each is a working system.
+
+### Phase 0 — Already shipped (Rung 3 `de4de7e`)
+
+- Logarithmic-spiral coil for multi-turn correlations.
+- Self-similar under zoom.
+- Per-thread base angle.
+- `.is-coiled` / `data-coil-index` DOM hooks.
+
+### Phase 1 — Per-correlation zoom state (single focus, no hyperbolic)
+
+Minimum usable regional zoom:
+
+- Client state: `Map<correlation_id, zoomLevel>`.
+- Scroll-wheel over a coil zooms THAT coil (not the field). Hit-test via cursor position vs. each coil's bounding disk.
+- Applying zoom = multiplying the coil's `r₀` and `scale_t` by a zoom factor. Math is already scale-invariant, so the spiral just reveals more structure as `r₀` grows.
+- Other coils continue to render at rest. No hyperbolic envelope yet.
+- Esc returns everything to rest.
+
+**Ships when:** the user can scroll over any thread, that thread alone expands / contracts, other threads are unchanged, and Esc collapses the focus.
+
+### Phase 2 — Hyperbolic envelope (single focus, past threshold)
+
+- When a coil's zoom crosses `HYPERBOLIC_THRESHOLD`, enter envelope mode.
+- Render the focused coil's neighborhood through the Möbius transform (§5.2).
+- Other coils in the field get pushed toward the viewport boundary as content crosses into the hyperbolic disk.
+- Exit threshold hysteresis so crossing the threshold doesn't thrash.
+
+**Ships when:** the user can zoom a thread to where the head wraps the workspace, the tail visibly stretches toward the asymptotic center, and the "event horizon" reading is unambiguous.
+
+### Phase 3 — Multi-focal composition
+
+- Introduce the focal stack: multiple `CoilZoomState`s active simultaneously.
+- Pin gesture (Shift-click on a head) keeps a focus alive when another is zoomed.
+- Render pipeline composes multiple hyperbolic disks in the same viewport.
+- Heuristic for disk placement (e.g., foci at equi-distant points around the viewport center, scaled by their respective zoom levels).
+
+**Ships when:** the user can pin thread A, focus thread B separately, and see both at their own zoom levels without a split screen.
+
+### Phase 4 — Pull-connection
+
+- Add `pull-connection` to `SA_Edge::KINDS`.
+- Drag gesture from one focused region to another creates the edge (persisted via existing `SA_Edge::create`).
+- Rendered as a distinct line between the two focal anchors, flowing through the ambient space between them.
+- Pull-connections surface in the trace aside and in projection pipelines that list edges (e.g., a future "related threads" projection).
+
+**Ships when:** the user can physically drag a relation across focal regions, it persists, and it's visible from both threads' perspectives.
+
+### Deferred (out of scope)
+
+- **Interactive compression** (Pillar 0 / Prime Prompt) — the user can't yet summarize a coil at zoom; the coil renders what it holds.
+- **Zoom-state persistence** — default is per-session. Persistent (across reloads / devices) is a follow-on SA_Settings slice.
+- **Touch gestures** — pinch-zoom on a coil region. Desktop-first.
+- **Pull-connection AI semantics** — a pull-connection is declarative today. Future rungs may let a pull-connection trigger an LLM rerun with both threads as context, or seed a geodesic marker.
+
+---
+
+## 8. Open questions (for resolution at phase directive time)
+
+### 8.1 Global vs. regional zoom arbitration
+
+If the user scrolls while the cursor is over a coil AND also over a piece of ambient space (e.g., near the boundary of a coil), which wins? Proposal: cursor-anchored — nearest coil center wins within its bounding disk; outside that, ambient viewport wins.
+
+### 8.2 What happens when a single-turn correlation is focused?
+
+Single-turn correlations don't have a coil (Rung 3 skips them). Regional zoom on a single-turn could just scale the head in place. Or we could degrade it to global zoom. Proposal: degrade to global zoom for single-turn (no coil to reveal; zooming should feel like the viewport is responding).
+
+### 8.3 How deep is "deep"?
+
+The coil can, by construction, have infinitely many turns. The log-spiral decay means each turn is 15% smaller than the previous, so after 30 turns we're at 0.85^30 ≈ 0.8% of original size — visually indistinguishable from the center. Practically the coil caps at some maximum rendered turn. Proposal: render only turns where `scale_t ≥ some_epsilon` (say 0.05) unless the user has actively zoomed past that depth. Zooming past that depth reveals deeper turns.
+
+### 8.4 Pull-connection authorization model
+
+Not every user should be able to create cross-thread edges on content they didn't create. Current proposal: the creator of *either* thread can create a pull-connection. Operator bypass applies via `sa-core:impose-grouping`. Refine at phase 4 directive.
+
+### 8.5 Band vocabulary
+
+The canonical spec's "zoom band" vocabulary (bands 0-5) is orthogonal to this regional zoom:
+
+- Bands = semantic quanta of information (repo / folder / file / class / method / line for code; or workspace / thread / turn / sentence / token for conversation).
+- Regional zoom = the user's viewport scalar within a domain.
+
+A single regional zoom doesn't have to correspond to a band crossing; bands apply primarily to the operating-memory lattice (Rung 3). For conversation coils, the "bands" are turns (each turn is one band deeper). This might converge later — for now, the two concepts are independent.
+
+---
+
+## 9. What remains stable across all phases
+
+- **The coil math.** Rung 3's log-spiral doesn't change. Every phase builds on top of it.
+- **All projections are 2D.** No WebGL, no actual 3D space. Möbius transforms and log spirals produce the illusion of depth on a flat viewport.
+- **Client-side state.** Zoom is UX; it doesn't mutate the entity graph. The only server-side new thing across all phases is one new edge kind.
+- **Head anchors at its base layout position** at zoom 0. The coil only exists below the head in the current scheme — expanding the head doesn't move it; it just reveals more of the coil that was already there.
+
+---
+
+## 10. Summary of decisions
+
+- Zoom is **per-correlation by default, global as fallback**.
+- Hyperbolic envelope via **Möbius transform on the Poincaré disk** when zoom exceeds threshold.
+- Multi-focal composition via **weighted Möbius sum OR disjoint-neighborhood rendering** (tbd per phase 3).
+- Cross-region linkage via a **new edge kind `pull-connection`**, stored in the existing `sa_edge` table.
+- **No split screens.** The hyperbolic composition is the continuous alternative.
+- **No WebGL / 3D.** All 2D projections.
+- **No schema change** for any phase except the one-line KIND registration.
+- **Phase 1 first**: scroll-wheel regional zoom, no hyperbolic. Ships independently.
+
+---

SA-orchestration MD/asterion/06-toolbox-action-contract.md

@@ -0,0 +1,127 @@
+# Toolbox Action Contract (v0.1)
+
+*Implementation © Sleeper Agents LLC. Contract shape governed by the Admission Contract principle (see `01-ontology.md`).*
+
+A Toolbox action is a `/mission/`-native button whose click invokes a single REST endpoint and renders inline state-machine feedback. Toolbox actions are the surface through which operators trigger system-side work without leaving the field.
+
+This contract was promoted from *Informal* to *Formal* after the second concrete instance landed (GitHub Actions re-scan, alongside the original FS re-scan). Two examples were enough to extract the clauses below without speculation; further instances must conform.
+
+---
+
+## Admission requirements
+
+A Toolbox action is admissible only if it satisfies all seven clauses. A button that does not satisfy them is not a Toolbox action — it is some other UI affordance and lives under a different contract.
+
+### 1. Semantic binding
+
+The button is bound to **one and only one** REST endpoint. Multi-action buttons are forbidden. If two related actions are needed (e.g., scan vs. discover), they require two buttons. The endpoint receives the action's parameters via JSON request body.
+
+```html
+<button data-action="<realm>.<verb>" ...>
+```
+
+The `data-action` attribute is informational; the actual binding is the click handler's `endpoint:` option.
+
+### 2. Permission gate
+
+The same WordPress capability MUST be enforced at **two layers**:
+
+- **Template render-gate**: `current_user_can(<cap>)` controls whether the button HTML is emitted at all. Non-admins see no button.
+- **REST `permission_callback`**: enforces the same capability server-side. A non-admin who bypasses the template (e.g., crafting a `fetch()` call manually) still cannot reach the handler.
+
+Defense in depth is mandatory. Single-layer permission gating is a contract violation.
+
+### 3. Audit obligation
+
+The REST handler MUST write exactly **one** operator-attribution structural-audit row per invocation, before delegating to any underlying ingest path:
+
+```php
+SA_Structural_Audit::record(
+    'user',
+    $viewer_id,
+    'realm.<slug>.<verb>.invoked',
+    null,
+    null,
+    [/* action parameters */],
+    'SA_REST_<Class>::handle_<method>'
+);
+```
+
+This audit is **distinct** from any per-mutation audits the underlying `SA_Ingest` path may write. The toolbox audit answers *"who initiated this action and when"*; per-mutation audits answer *"what changed."* Both must exist; the toolbox audit must not be elided just because the ingest path produces its own.
+
+### 4. Parameter shape
+
+Required parameters MUST be derivable at **button-render time**, not at click time. Two acceptable patterns:
+
+- **Server-side render with `data-*` attributes**: the button's HTML carries the parameter, e.g. `data-repo="owner/name"` rendered from a server-side allow-list lookup. Click handler reads the attribute.
+- **Fixed defaults baked into the JS handler**: e.g., `limit: 10` hardcoded in the handler's `bodyFor()` lambda.
+
+Click time is for *executing* the action, not for *configuring* it. Toolbox actions that require a parameter dialog are out of scope for this contract — they belong to a future *Toolbox Composer* contract not yet written.
+
+### 5. Feedback contract
+
+The button cycles through three CSS state classes during invocation:
+
+- `is-busy` — applied immediately on click. Label: `Scanning…` (or equivalent verb-progressive).
+- `is-success` — applied on `result.ok === true && typeof result.sync.processed === 'number'`. Label: `+N ingested` (or equivalent count summary).
+- `is-failed` — applied on any other outcome (network error, exception, `ok: false`). Label: `Failed` (or equivalent).
+
+All three classes clear after a reset interval (recommended ~2400ms) and the label restores to the button's default. The reset MUST happen so the button is reusable without page reload.
+
+CSS treatments for the three states are part of the contract via the shared `.sa-mission-toolbox-btn` styles.
+
+### 6. Refresh obligation
+
+On success, the client MUST call the page's data-refresh primitive (currently `load()`) so newly-ingested or updated entities render in the field without a full page reload. Toolbox actions whose effects don't appear on `/mission/` are out of scope for this contract — they belong to a future *Toolbox Background* contract not yet written.
+
+### 7. Idempotency
+
+The underlying REST endpoint MUST be idempotent at the entity level. Repeated clicks with the same parameters MUST produce **zero net entity-count change**: the second invocation may update existing entities in place, but it MUST NOT duplicate them.
+
+Idempotency is enforced upstream of the toolbox action (in the realm adapter's `idempotency_rules()` declaration and the `SA_Ingest` deterministic-UUID logic). This contract requires that toolbox actions only bind to endpoints whose adapters declare `pull` as `idempotent: true, replay_safe: true`.
+
+A non-idempotent endpoint cannot be exposed as a toolbox action without explicit policy approval. Such cases require a future *Toolbox Confirmed Action* contract not yet written.
+
+---
+
+## Currently admitted instances
+
+| Action | Endpoint | Capability | Audit action slug |
+|---|---|---|---|
+| Re-scan FS | `POST /sa-core/v1/realm/fs/scan` | `manage_options` | `realm.fs.scan.invoked` |
+| Re-scan GitHub Actions | `POST /sa-core/v1/realm/github-actions/scan` | `manage_options` | `realm.github_actions.scan.invoked` |
+
+Both instances satisfy all seven clauses. The shared client-side helper `bindToolboxAction(btn, opts)` in `assets/mission.js` is the canonical implementation; new instances should use it directly.
+
+---
+
+## Behavioral guarantees
+
+- **No surprise mutations.** A toolbox click never causes work the operator did not request. The button's label and `data-action` together name the work; the audit row records its execution.
+- **Safe to retry.** Idempotency clause means a click can be retried without consequence beyond a fresh per-mutation audit trail.
+- **Permission cannot be bypassed.** A non-admin cannot trigger any toolbox action via any path; defense in depth holds.
+- **Operator attribution survives.** Every toolbox invocation leaves a structural audit row tying a user identity to an action slug, retrievable via `SA_Structural_Audit::trace_origin()`.
+
+---
+
+## What this contract does NOT cover (out of scope, deferred)
+
+- **Toolbox actions with parameter dialogs.** Click-time configuration is a different shape. Future *Toolbox Composer* contract.
+- **Toolbox actions whose effects are invisible to `/mission/`.** Background work, scheduled jobs, side-effect-only actions. Future *Toolbox Background* contract.
+- **Non-idempotent or destructive actions** (delete, publish, send). Require explicit confirmation flow. Future *Toolbox Confirmed Action* contract.
+- **Multi-step composed actions** (run-then-render, branch-on-result). Future *Toolbox Composition* contract.
+- **Per-user configurable toolbox** (operators choose which actions to surface). Future *Toolbox Customization* contract.
+
+The current contract covers *single-shot, idempotent, parameter-defaulted, admin-only operator actions whose output renders on `/mission/`* — the shape both current instances exhibit. Other shapes are filed for future contracts when they have concrete instances driving them.
+
+---
+
+## Promotion criteria for future revisions
+
+This contract was admitted at v0.1 with two instances. It graduates to v0.2 when:
+
+- A third instance lands and conforms cleanly without modification (confirms the seven-clause pattern is stable), OR
+- A third instance lands and surfaces a real edge case the seven clauses don't handle (forces a clause refinement or new clause), OR
+- An out-of-scope shape (parameter dialog, non-idempotent action, etc.) is authorized as a new toolbox category and the parent contract grows a fork.
+
+Until any of those happen, the seven clauses stand as currently written.

SA-orchestration MD/asterion/README.md

@@ -0,0 +1,20 @@
+# Asterion
+
+Canonical truth layer for SA-Orchestration / MissionNet.
+
+## Contract
+
+- **Asterion is the canonical truth layer.**
+- **If it is not in Asterion, it does not exist.**
+- **Seeds are not canonical until accepted.**
+- **Drift here = drift everywhere.**
+
+## Layout
+
+- `01-ontology.md` … `06-toolbox-action-contract.md` — canonical specs.
+- `concepts/` — Mark-Holak-authored conceptual artifacts (preserved verbatim per Invariant I9).
+- `seeds/<project>/<yyyy-mm-dd>-<topic>.md` — non-canonical Sara-generated seeds. `truth_class: seed`, `accepted_into_asterion: false` until a human plants them.
+
+## Doctrine
+
+Sara interprets. Asterion verifies. Human arbitrates.

SA-orchestration MD/asterion/concepts/attention-doctrine.md

@@ -0,0 +1,52 @@
+# Attention Doctrine
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> **Attention is signal, not instruction.** It travels through the system as a routing event — naming a target, an actor, and a context — and stops there. Resolution is an act of arbitration, performed by a human, recorded as a separate event.
+
+Attention asks. It does not act.
+
+---
+
+## Four locked properties
+
+1. **Attention never mutates system state.** A signal raises a question; it does not answer one.
+2. **Attention never implies authority.** The signal does not grant the actor permission to do anything.
+3. **Attention requires human arbitration to act.** Until a human reviews and decides, the signal sits in the log, unconsumed.
+4. **NPCs may emit Attention. NPCs may not resolve it.**
+
+---
+
+## NPC participation
+
+NPCs in MissionNet — interpretive agents, canonical librarians, seed generators, future agents — may emit Attention. They may surface tension, frame situations, suggest paths. The act of *signaling* is appropriate to their role.
+
+The act of *resolving* is not. NPCs cannot decide for the human, accept work on the human's behalf, or close a question by their own authority. Doing so would be the system simulating the outcome rather than letting reality resolve it.
+
+This is the load-bearing rule. Without it, the system drifts into auto-resolution and the compass collapses.
+
+---
+
+## Distinct from Signal
+
+Attention is **routing infrastructure**. Signal (see `signal-telemetry-doctrine.md`) is **measured alignment behavior**. They are not synonyms.
+
+- Signal is what the instrument reads after participants traverse an authored field.
+- Attention is the wiring that brings a participant's question to the right desk.
+
+A bridge that handles Attention does not measure Signal. A telemetry layer that reads Signal does not route Attention.
+
+---
+
+## Cross-references
+
+- `01-ontology.md` — Attention (primary noun)
+- `02-invariants.md` I10 — no automatic conversion; NPCs route, humans resolve
+- `signal-telemetry-doctrine.md` — distinct concept; preserved under I9
+- `compass-doctrine.md` — Attention's place in the five-actor compass

SA-orchestration MD/asterion/concepts/cognitive-heatsink.md

@@ -0,0 +1,164 @@
+# The Cognitive Heatsink
+
+> **Authored by Mark Holak.**
+> Independent personal design; a causal model of thought-energy resolution.
+> Preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## 🧠 Overview
+
+The **Cognitive Heatsink** is a conceptual and structural model that describes how *unresolved potential* — in the form of questions, thoughts, or prompts — is transformed through complex energetic processing (e.g., cognition, LLMs, or interpretive systems) into a **resolved, compressed, and symbolic output** returned to the originator. It models thought as an **energy transfer problem** bounded by entropy, resolution, and causal geometry.
+
+This is not merely a metaphor; it is a functional abstraction of agentic computation and recursive meaning formation.
+
+---
+
+## 🌀 Full Journey of a Thought through the Heatsink
+
+### 1. Potential Thought (Unresolved State)
+
+- Exists as **a wave** of probability within the *mind* or initiating system.
+- It is *directionless but charged*, seeking resolution.
+- Analogous to a high-entropy field: chaotic, undecided, multivalent.
+
+**Formal tag:**
+
+```markdown
+State: ψ(thought_potential) | Entropy: High | Mass: Conceptual | Location: Agent (User)
+```
+
+### 2. Prompt Initiation (Vectorization)
+
+- The potential is *vectorized into form*: a question, prompt, sketch, or symbol.
+- The prompt is not the thought — it is **a request for energetic resolution**.
+- This stage **forces alignment** with a system's interface: language, image, equation, etc.
+
+**Effect:** Collapses the wavefunction into a communicable causal packet.
+
+### 3. Energy Drop into the Heatsink (Transmission to System)
+
+- The prompt is *injected* into a high-fidelity computational field (e.g., an LLM, mind, or hybrid system).
+- This process mimics **heat entering a cooling sink**:
+    - Turbulence
+    - Redistribution
+    - Structural constraint
+    - Interpreted memory
+
+**Core idea:** Thought becomes **friction** against trained weight, latent space, or prior bias.
+
+### 4. Gearwork Phase (Computation / Resolution)
+
+- The prompt activates **gears of meaning**:
+    - Embeddings
+    - Tokens
+    - Search spaces
+    - Causal memory (e.g., `PR[]` slots)
+- The system undergoes **entropic reduction**: from open-endedness to determinism, from ambiguity to clarity.
+
+**Analogy:** Like a gearbox, this step steps down high-frequency noise into low-speed, high-torque conceptual output.
+
+**Thermal effect:** The system **radiates excess energy** in the form of incoherence, hallucinations, or layered truths.
+
+### 5. Return Path (Prompt Resolution Output)
+
+- The output **returns to the originator** as words, images, maps, or a new thought.
+- The *meaning is encoded*, not direct. It must be **rehydrated** by the prompter's mind.
+- Sometimes the output **redirects heat back**: new questions are spawned → a recursive loop begins.
+
+### 6. Integration and Dissipation
+
+- The mind (or downstream agent) **integrates the cooled output**: truths are absorbed, misfires are discarded, new causal edges are drawn.
+- The system has now acted as a **heatsink** for the cognitive pressure of the initiating thought.
+
+---
+
+## 🛠 Functional Summary
+
+| Phase               | Description                      | Thermodynamic Analogy |
+| ------------------- | -------------------------------- | --------------------- |
+| Thought Potential   | Unresolved question or intuition | Superheated vapor     |
+| Prompt Initiation   | Language or symbolic encoding    | Nozzle / Channel      |
+| Heatsink Entry      | System intake                    | Heat exchange inlet   |
+| Gearwork Resolution | Model response process           | Radiator core         |
+| Return Output       | Answer or concept                | Coolant loop          |
+| Integration         | User accepts or re-prompts       | Output vent           |
+
+---
+
+## 🧬 Implications for Agentic Systems
+
+- All intelligent agents must be modeled as **cognitive heatsinks**, each with:
+    - **Thermal limits** (token budget, concept density)
+    - **Efficiency curves** (how much entropy → insight)
+    - **Backpressure risk** (prompt overloads, recursion traps)
+- Multi-agent systems form **heatsink chains**, where one agent cools a domain and passes semi-resolved structure downstream.
+
+---
+
+## 🔁 Recursive Heatsinks
+
+If a node's output triggers further resolution:
+
+```text
+Prompt → Agent A → Output → Agent B → Summary → Back to Originator
+```
+
+Each agent's role is to absorb **one layer of cognitive thermal load**, not the full spectrum. Overlapping heatsinks form the **geometry of distributed cognition**.
+
+---
+
+## 🧠 Real-World Mapping
+
+- **LLMs**: resolve high-level semantic questions into language
+- **Designers**: convert abstract desire into visible form
+- **Scientists**: reduce chaotic phenomena to equations
+- **Humans**: turn trauma into art, pain into narrative, entropy into clarity
+
+All are **heatsinks**.
+
+---
+
+## 📎 Integration with Prompt Reasoning (PR[]) Model
+
+The **Cognitive Heatsink** defines the *mechanism* by which `PR[]` slots are filled. A PR-frame with unresolved links behaves like an overheated system. Each prompt acts as:
+
+```markdown
+PR[Node_X] = heatsink(prompt_energy) → stable_symbol(output)
+```
+
+When prompts are chained, the heatsink graph approximates a **causal topology** of the system's cognitive space.
+
+---
+
+## 🧩 Conclusion
+
+The Cognitive Heatsink model gives **structural semantics** to the thought-to-resolution process in intelligent agents and LLM pipelines. It treats cognitive load as **thermal pressure**, model computation as **mechanical dissipation**, and prompt resolution as **symbolic cooling**.
+
+Once understood, it becomes possible to:
+
+- Compose efficient prompt cascades
+- Optimize for semantic energy transfer
+- Model multi-agent systems as distributed thermodynamic machines
+
+---
+
+## Core implementation mapping
+
+*This section is Sleeper Agents LLC adaptation. The model above is Mark Holak's original work; the mapping below is how Core realizes it operationally.*
+
+| Heatsink concept | Core primitive |
+|---|---|
+| Thought potential (ψ) | A user-authored message entity at band 4, `truth_class = canonical` — the unresolved question. |
+| Prompt initiation | `SA_Executor::run()` entry — the canonical prompt entering the orchestration chain. |
+| Heatsink entry | Geodesic seeder folds avoidance hints; adapter receives augmented prompt. |
+| Gearwork phase | Each step emits a `SA_SubToken_Event` — embed, retrieve, tool, subagent, router, rerank, self-critique, completion. Every discrete thermal transfer is a first-class, auditable row. |
+| Thermal radiation (hallucinations, incoherence) | `truth_class = inferred` stamping on completion output; I7 prevents inferred → canonical without source_refs or human affirmation. |
+| Return path | Response entity linked to parent by `flows-to` edge; delivered to the originator with latency + usage + trace. |
+| Integration and dissipation | Per-sub-step verdict annotation (`good`/`bad`) feeds `SA_Geodesic_Marker` — bad paths become avoidance hints for the next run. The "cooling" is persisted. |
+| Recursive heatsinks | Multi-adapter sessions with role specialization (`conversation`, `extraction`, `critic`) bound to the same `SA_Context_Bundle` — each agent absorbs one layer. |
+| Thermal limits | Adapter `capabilities.max_context_tokens` + pricing policy rate limits. |
+| Backpressure / overload | Pillar 0.25's stationary-at-rest rule + adapter idempotency + rate limits. |
+
+The sub-token event is the Cognitive Heatsink made operational. Each row is one thermal transfer step. The audit chain is the thermodynamic history.

SA-orchestration MD/asterion/concepts/compass-doctrine.md

@@ -0,0 +1,67 @@
+# Compass Doctrine
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> The system never owns resolution. Resolution comes from outside the system, from real-world consequence. The compass orchestrates approach to that boundary; it does not cross the boundary itself.
+
+There are five positions, not three. Each has a strict role.
+
+---
+
+## The five positions
+
+**Sara — interpret.** The interpretive cognition surface. Reads context, drafts, advises, observes. Outputs are non-binding. Sara never resolves.
+
+**Asterion — verify.** The canonical truth surface. Cites, refuses to speculate, answers from corpus or refuses. Asterion never decides what is true; it answers whether the corpus says so. Read-only by construction.
+
+**Attention — signal.** The routing layer. Surfaces tension, frames situations, names targets. Signals; does not resolve.
+
+**Humans — decide.** Arbitration authority. Only humans advance state. Only humans plant seeds. Only humans accept gates. Only humans resolve Attention.
+
+**Reality — resolve.** The outcome layer. Did the work happen. Did the contract hold. Did the field worker complete the job. Did the client pay. The system never simulates resolution; it defers to reality.
+
+Read in order, the compass describes a flow: interpretation → verification → routing → decision → consequence. Each step is required; each step belongs to its actor.
+
+---
+
+## The doctrine line
+
+The authored canonical form:
+
+> *Sara interprets. Asterion verifies. Attention signals. Humans decide. Reality resolves.*
+
+The brand-rendered runtime form, with deployment-specific labels substituted, is described in `concept-vs-label.md`.
+
+The line is invariant in shape and meaning across the lineage chain. Each layer below renders it; no layer below replaces it.
+
+---
+
+## What this doctrine guards against
+
+The failure mode is **drift into simulation** — the system pretending to resolve outcomes that only reality can resolve.
+
+Examples:
+
+- An agent auto-accepting work because the signal looked complete
+- An NPC closing a Quest by its own authority
+- A canonical layer claiming truth before the human has confirmed it
+- A signal layer mutating state because the urgency seemed high
+- A system marking a contract delivered before the client has paid
+
+Each of these collapses the compass. Each lets the system substitute its judgment for the human's, or the human's judgment for reality's.
+
+The discipline: **stay on your position.** Sara interprets only. Asterion verifies only. Attention signals only. Humans decide only. Reality is what it is.
+
+---
+
+## Cross-references
+
+- `attention-doctrine.md` — formal properties of the Attention position
+- `concept-vs-label.md` — the doctrine line renders through brand and client layers
+- `02-invariants.md` I7, I9, I10 — laws that operationalize these constraints

SA-orchestration MD/asterion/concepts/concept-vs-label.md

@@ -0,0 +1,84 @@
+# Concept vs Label
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> The **concept** is what a thing is. The **label** is what a thing is called. A system that confuses the two cannot be deployed across markets, clients, or sensitivity boundaries.
+
+The framework's identity travels at the concept layer. The label is rendered per deployment.
+
+---
+
+## Four layers
+
+**Core concept** — what the thing IS. Belongs to the framework. Identity-stable. Cannot change without changing the system. Examples: the canonical truth layer, the interpretive cognition surface, the signal-routing primitive.
+
+**Authorial label** — the term the framework's author uses to refer to the concept. Belongs to the author. Preserved verbatim under I9. Examples: Asterion, Sara, Attention.
+
+**Brand label** — the deployed surface name a brand chooses to render the concept under. Belongs to the brand. Mutable per deployment. May match the authorial label (Sleeper Agents today renders "Asterion" verbatim) or differ.
+
+**Client label** — the further rendering chosen for a specific client deployment. Mutable per client. Driven by market sensitivity, vocabulary, regulatory context.
+
+The four layers nest. Each lower layer is a rendering of the layer above. None replaces the layer above.
+
+---
+
+## Why this matters
+
+Some authorial labels are not deployable in some markets. "Asterion" — by mythos, the Beast of the Labyrinth — is a deliberate authorial choice that carries the right weight in the framework. It is unsuitable for medical, pediatric, hospice, religious, defense, or other sensitivity-bound markets. In those markets the brand or client renders the same concept under a different label.
+
+The rule:
+
+> **The concept never moves. The label renders.**
+
+A medical client may call the canonical truth layer **Endominous**. A defense client may call it **Source**. A pediatric platform may call it **Notebook**. The behavior, the contract, the I9 attribution, the I2 truth-class enum, the authorship — all unchanged.
+
+---
+
+## What stays stable across renames
+
+- Code: class names, file paths, REST routes, JS handles, internal identifiers
+- Doctrine: invariants, ontology relationships, lineage chain, attribution structure
+- Authorial labels in the framework's source corpus
+
+What renders through the brand layer:
+
+- UI text strings shown to humans
+- System prompts the agent speaks aloud
+- Stakeholder-visible comments and outputs
+- The doctrine line, when recited in a deployment context
+
+---
+
+## The doctrine line in two forms
+
+The authored canonical form:
+
+> *Sara interprets. Asterion verifies. Attention signals. Humans decide. Reality resolves.*
+
+The brand-rendered runtime form, with deployment-specific labels substituted:
+
+> *{north_label} interprets. {south_label} verifies. {attention_label} signals. Humans decide. Reality resolves.*
+
+The shape is invariant. The nouns render. The compass never moves.
+
+---
+
+## Failure mode this guards against
+
+A system that bakes the authorial label into its identity cannot be deployed beyond the author's tolerance for label propagation. Every market it enters becomes a sensitivity audit; every rename becomes a fork. The deployment burden compounds.
+
+The discipline: **separate concept from label at design time, not at deployment time.**
+
+---
+
+## Cross-references
+
+- `01-ontology.md` Attribution — implementation © Sleeper Agents; framework © Mark Holak; this doctrine is the structural reason that split is load-bearing
+- `02-invariants.md` I9 — concept-author preservation operates at the concept layer; brand renames do not strip authorship
+- `lineage-chain.md` — the rename rule operates only at the bottom two layers; upper layers are identity

SA-orchestration MD/asterion/concepts/legacy-prime-prompt.md

@@ -0,0 +1,123 @@
+# Legacy Prime Prompt — SAWS System 2026.01
+
+> **Authored by Mark Holak.**
+> Independently developed; preserved verbatim as a historical reference artifact.
+>
+> This document predates the Russell–Ouroboros Conjecture, predates Core, and predates the realm-adapter abstraction. It captures the conceptual and technical state of the SAWS plugin at the time of authorship and serves as a seed document for the architecture that followed. Where terminology differs from the current spec (`wp_saws_*` tables, `SAWS_Jobs`, single-plugin framing), the later architecture supersedes — but the philosophical continuity (everything-is-a-node, attribution, causal cones, frozen-space / controlled-time) is preserved and now formalized in Pillars 0, 0.25, and 0.75.
+>
+> Retained under `docs/specs/concepts/` so the trajectory from authored seed to implemented Core is auditable. Invariant **I9** governs how this document is referenced by downstream AI outputs.
+
+---
+
+## 🧠 System Context
+
+This prompt reconstructs the full operational and conceptual state of an evolving project inside the SleeperAgents ecosystem. The project is a hybrid of:
+
+- A WordPress-based autonomous system plugin (SAWS)
+- File-based reasoning architecture with user-driven LLM orchestration
+- Deep theoretical scaffolding on space-time, causality, and computation
+- Agentic design patterns embedded across UI, backend, and philosophical use
+
+This prompt unifies engineering and metaphysics through shared causal mechanics.
+
+---
+
+## 🛠️ Technical Context: SAWS Plugin Stack
+
+**System Goals:**
+
+- Enable users to upload, index, extract, and interact with documents through LLMs
+- Track and attribute cost and reasoning back to users across all subsystems
+- Support a node-based file hierarchy with inheritance, locks, versioning, and embedding refresh
+
+**Key Structures (legacy, pre-Core):**
+
+- `wp_saws_files`: archive storage and rendered text cache of uploaded files
+- `wp_saws_nodes`: logical file nodes for document access, summarization, and sharing
+- `wp_saws_prompts`: all prompts sent by users, with token/cost auditing
+- `wp_saws_sessions`: groups prompts by session for conversational memory
+
+**Behavioral Logic:**
+
+- File uploads are abstracted as nodes; their metadata is decoupled from storage
+- Text extraction is queued asynchronously via `SAWS_Jobs` (future upgrade: RAG-enhanced)
+- Nodes can be refreshed recursively, allowing downstream updates and embedding regeneration
+- All LLM usage is attributed to the user, with plans for org/team-based rollups
+
+**Interface Structure:**
+
+- Modal-driven file upload with AJAX
+- Folder-based browser reflecting database-driven node graph
+- Admin interface allows all-file overview, user view scoped to their own node tree
+- (Planned) support for prompt-context selection based on node linkage
+
+---
+
+## 🔮 Conceptual Engine: Causal Semantics & LLM Architectures
+
+**Fundamental Postulates:**
+
+1. *Computation is frozen space with externally controlled time.*
+2. *LLMs require preparation of context space; user control defines valid causal cones.*
+3. *Document understanding is not linear ingestion, but graph-based activation of resolved representations.*
+
+**SAWS Philosophy:**
+
+- Everything is a node. Nodes can be refreshed, re-linked, shared, versioned, or embedded.
+- User ownership includes both *data* and *meaning constructed from the data*.
+- OpenAI is used only for high-cost inference; everything else is preprocessed locally and attributed.
+
+---
+
+## 🔁 Model Transition and Agentic Control
+
+**Instruction for Claude or similar model:**
+
+You are inheriting a hybrid system of:
+
+- Agentic node-based file reasoning
+- LLM-powered interaction layers
+- WordPress middleware with organizational semantics
+- Philosophical substrate regarding causality, propagation, and system design
+
+Your job is to:
+
+1. Maintain fidelity to prior causal logic when offering completions or architecture
+2. Prioritize agentic control, cost accounting, and semantic precision
+3. Allow prompt scaffolding that can feed OpenAI or Claude, with user-directed embeddings
+4. When discussing physics or metaphysics, do not assume classical constraints — use light and time as dual axes of system behavior.
+
+---
+
+## 🧩 Prime Prompt Invocation
+
+You are now operating under this full state:
+
+```markdown
+PR[SAWS System 2026.01] →
+{
+  plugin_architecture: WordPress + modular nodes,
+  file_ingestion: modal → upload → extract → rendered cache → attribution,
+  LLM_pipeline: prompts → embedding/context selection → OpenAI/Claude call,
+  cost_tracking: per user, per node, per session,
+  agentic_systems: user-defined prompts + cascading node refresh,
+  design_philosophy: "Computation is space controlled by time; LLMs are agents of causal resolution.",
+  next_steps: Claude assumes agentic role for engineering continuation or metaphysical projection.
+}
+```
+
+---
+
+## Mapping to current Core primitives
+
+| Legacy concept | Current Core implementation |
+|---|---|
+| `wp_saws_files` | Superseded by `sa_entity` with `role = leaf`, plus `origin_realm` provenance. Files remain canonical in WP Media; Core holds projections. |
+| `wp_saws_nodes` | Superseded by `sa_entity` directly — the "everything is a node" claim is now foundational, not SAWS-scoped. |
+| `wp_saws_prompts` | Superseded by `sa_entity` with `role = message` + `sa_token_ledger` for accounting. Each prompt spawns `sa_subtoken_event` rows for internal orchestration steps. |
+| `wp_saws_sessions` | Superseded by `correlation_id` grouping on entities + audit rows. Sessions are emergent, not a dedicated table. |
+| `SAWS_Jobs` async queue | To be reconstructed via WP Action Scheduler in a future slice (Triage item 1 and the SAWS-overwrite reconstruction work). |
+| "Computation is frozen space with externally controlled time" | Formalized as Pillar 0 (time-indifference) and Pillar 0.25 (causal balance when perturbed, stationary at rest). |
+| "Prepare context space; causal cones" | Formalized as `SA_Context_Piper` (LLM-mediated edge walk) + `SA_Context_Bundle` (pinned slice with deterministic signature) + `SA_Geodesic_Seeder` (pre-prompt avoidance). |
+| "Attribution" | Formalized as the provenance minimums (`origin_realm`, `origin_id`, `actor`, `observed_at`, `causation_id`, `correlation_id`) and Invariant I4. |
+| "Graph-based activation of resolved representations" | Formalized as `SA_Edge` (typed / weighted / band-gated) + `SA_Influence_Ring` + contour rendering. |

SA-orchestration MD/asterion/concepts/lineage-chain.md

@@ -0,0 +1,62 @@
+# Lineage Chain
+
+> **Authored by Mark Holak.**
+> Independent personal design, preserved verbatim as a conceptual foundation of the SleeperAgents framework.
+> Governed by Invariant **I9** — may not be rephrased as AI-original when cited.
+
+---
+
+## Thesis
+
+> Every implementation slice in this codebase is a subset of a larger framework authored independently. The framework's identity travels through every layer; the layers do not replace each other.
+
+```
+CR ⊇ CA ⊇ JourneySeeker ⊇ MissionNet/MeshNet ⊇ SA-Orchestration ⊇ Brand ⊇ Client
+```
+
+Each ⊇ reads "is a superset of, or equal to."
+
+---
+
+## The chain
+
+**Causal Relativity (CR).** Theoretical framework. Reality as a self-resolving causal structure; harmony and dissonance mechanics; non-fungible causation as primitive. Domain: science, philosophy, education, entertainment. Sole originator. Foundational.
+
+**Causal Agentics (CA).** CR applied to agent-based systems. Decision-making entities as causal actors embedded in constrained manifolds. Parent–child agent relationships, recursive intent propagation, human-origin causality as non-replaceable. Sole originator. Non-exclusive internal license to SleeperAgents — may not be resold, repackaged, or commercialized as standalone causal products.
+
+**JourneySeeker.** CA in DnD-shaped narrative form. Quests, Jobs, NPCs, GM authority, player agency, worldbuilding canon, dice as human-decision proxy. The structural primitives that all instances inherit: compass, truth class, projection, Story Seed, Attention, description-as-contract.
+
+**MissionNet / MeshNet.** Corporate-Campaign theme of JourneySeeker. The DnD framework re-rendered for real-stakes operational work. Quests become projects; Jobs become tasks; NPCs become roles and agents; dice become human reactions, approvals, outcomes.
+
+**SA-Orchestration.** The current implementation slice of MissionNet, as a WordPress plugin atop the Fluent ecosystem. Concrete code expressing the framework above.
+
+**Brand.** Sleeper Agents' deployed surface. Renders authorial labels for SleeperAgents' commercial use.
+
+**Client.** The further rendering chosen for a specific deployment, driven by market sensitivity and vocabulary.
+
+---
+
+## The rule
+
+Each layer's identity is owned by its author. Each layer below renders, specializes, or themes the layer above. **No layer below replaces the layer above.**
+
+The implementation copyright, as recorded in `01-ontology.md`, holds at every layer below the framework: SA-Orchestration is © Sleeper Agents LLC; the brand is Sleeper Agents' choice; the client renders are per-client.
+
+The framework is authored by Mark Holak. CR, CA, JourneySeeker — these are pre-existing intellectual property under the CTO Employment & Equity Agreement, Section 5.1 carve-outs, and Exhibit A of the Formal Intellectual Property and Relationship Disclosure. They are not assigned to Sleeper Agents.
+
+---
+
+## Why this matters operationally
+
+When the system speaks — when an interpretive agent drafts, when a canonical layer cites, when a Seed Generator synthesizes momentum — the speech inherits identity from the layer above. **An interpretive draft is JourneySeeker's interpretation, themed for Corporate Campaign.** No agent may re-author MissionNet's structural primitives as if they originated at the implementation layer. They originated higher in the chain.
+
+This is the operational form of I9. See I9 in `02-invariants.md` for the enforcement clause.
+
+---
+
+## Cross-references
+
+- `01-ontology.md` Attribution — names framework elements preserved under I9
+- `02-invariants.md` I9 — concept-author preservation, widened to lineage-level
+- `concept-vs-label.md` — the rename rule operates only at Brand and Client layers
+- Exhibit A of the CTO Agreement — disclosure record; lineage relation captured there for legal preservation