instar 1.3.357 → 1.3.358

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.357",
+  "version": "1.3.358",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-06T08:26:56.471Z",
-  "instarVersion": "1.3.357",
+  "generatedAt": "2026-06-06T09:11:03.969Z",
+  "instarVersion": "1.3.358",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {
@@ -418,7 +418,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -426,7 +426,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -434,7 +434,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -442,7 +442,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -450,7 +450,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -458,7 +458,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -466,7 +466,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -474,7 +474,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -482,7 +482,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -490,7 +490,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -498,7 +498,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -506,7 +506,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -514,7 +514,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -522,7 +522,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -530,7 +530,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -538,7 +538,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -546,7 +546,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -554,7 +554,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -562,7 +562,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -570,7 +570,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -578,7 +578,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -586,7 +586,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -594,7 +594,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -602,7 +602,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -610,7 +610,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -618,7 +618,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -626,7 +626,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -634,7 +634,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -642,7 +642,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -650,7 +650,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -658,7 +658,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -666,7 +666,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -674,7 +674,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -682,7 +682,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -690,7 +690,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -698,7 +698,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -706,7 +706,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -714,7 +714,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -722,7 +722,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -730,7 +730,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -738,7 +738,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -746,7 +746,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -754,7 +754,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -770,7 +770,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "1256daa92d8ec5e17f975580bb076fa2c451cbd7db03b36ae3c4a929837adac4",
+      "contentHash": "5455fb08f0a997120fadd63be41f30d19fb619beaa19970b889b1f1fa90446b7",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/1.3.358.md

@@ -0,0 +1,44 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The agent now runs an OBSERVE-ONLY coherence check on its OWN outbound messages
+(Know Your Principal standard, security-build increment 3 — the READ side). When
+a finalized message credits an operator-ROLE decision (approval / mandate /
+credential / lock / acting-for) to a principal who is NOT the topic's VERIFIED
+operator, a structured finding is appended to `state/principal-coherence.jsonl`.
+This is the first runtime consumer of `PrincipalGuard` (shipped pure in #902):
+the verified operator comes from the authenticated-sender binding
+(#904/#906/#909), never from a name in content.
+
+## What to Tell Your User
+
+Nothing user-facing changes. Foundation observability (experimental) for the
+"Caroline" identity-bleed security fix: the agent can now NOTICE — in its own
+output, where no inbound gate watches — when it credits a decision to someone who
+isn't its verified operator. It is SIGNAL-ONLY: it NEVER blocks, delays, or
+rewrites a message; it only writes a log line. It ships off by default (dark) so
+the detector's false-positive rate can be measured on real outbound before any
+warn or block surface is ever considered.
+
+## Summary of New Capabilities
+
+- `monitoring.principalCoherence.enabled` config flag (default false / absent).
+- Observe-only outbound check on the `checkOutboundMessage` delivery seam,
+  modeled on the existing `observeSelfViolation` (fire-and-forget, fail-open,
+  dark by default).
+- Audit trail at `state/principal-coherence.jsonl` (one JSON line per finding:
+  topicId, operatorUid, operatorBound, principal, attributionKind, verdict,
+  snippet, reason). The `verdict` is recorded for analysis, NEVER enforced.
+
+## Evidence
+
+14 tests across all three tiers, all green: Tier-1 unit
+(`principal-coherence-operator-seam`, 5 — the store→guard contract, both sides),
+Tier-2 integration (`principal-coherence-signal`, 5 — over the wire, gating both
+sides), Tier-3 e2e (`principal-coherence-lifecycle`, 4 — production boot,
+feature-is-alive, signal-only proof that a block-verdict finding still returns
+200 not 422). Clean `tsc --noEmit`; docs-coverage `--check` passes (no new route).

package/upgrades/side-effects/principal-coherence-observe.md

@@ -0,0 +1,82 @@
+# Side-effects review — Principal-Coherence Signal, observe-only (Know Your Principal, increment 3)
+
+## What this change does
+The READ side of the operator binding — the first runtime consumer of
+`PrincipalGuard.evaluatePrincipalCoherence` (shipped pure + unwired in #902).
+On the outbound delivery seam (`checkOutboundMessage` in routes.ts), every
+finalized agent message is checked against the topic's VERIFIED operator. When
+the message credits an operator-ROLE decision (approval / mandate / credential /
+lock / acting-for) to a principal who is NOT the bound operator — the "Caroline"
+identity-bleed failure, caught in the agent's OWN output — a structured line is
+appended to `state/principal-coherence.jsonl`.
+
+- `src/core/types.ts`: one new optional config block,
+  `monitoring.principalCoherence?: { enabled: boolean }`. Documented, off by
+  default by absence.
+- `src/server/routes.ts`: one new observe function `observePrincipalCoherence`,
+  modeled byte-for-byte on the existing `observeSelfViolation`, plus one
+  fire-and-forget `void observePrincipalCoherence(...)` call placed next to the
+  existing `void observeSelfViolation(...)` at the top of `checkOutboundMessage`
+  (before the gate-availability early-return, so it runs regardless of whether a
+  tone gate is configured).
+
+## The load-bearing security property
+The operator the check resolves against comes ONLY from
+`TopicOperatorStore.asVerifiedOperator(topicId)` — the authenticated-sender
+binding (#904/#906/#2d), never a name read from content. A name in the agent's
+prose can therefore never become the "known good" principal; it can only ever be
+the thing being CHECKED. This is the whole point of the standard: an unverified
+identity is a guess, not a fact.
+
+## SIGNAL-ONLY contract (identical to observeSelfViolation)
+- **Returns void; fire-and-forget.** It has NO path to block, delay, rewrite, or
+  influence the outbound message or the tone-gate verdict. The verdict field in
+  the audit line (block for mandate/credential, warn otherwise) is RECORDED for
+  later analysis and NEVER enforced — proven by an e2e assertion that a
+  credential misattribution still returns 200, not 422.
+- **Fail-open.** Every operation is guarded; the outer body is try/catch and each
+  fs op is independently guarded. Any throw is swallowed and the message sends.
+- **Dark by default.** Inert unless `monitoring.principalCoherence.enabled === true`
+  AND `ctx.topicOperatorStore` is non-null AND the topic id is numeric. Absent
+  config (every existing + new agent today) = fully inert, zero cost.
+- **Observe-first rationale.** The PrincipalGuard regex can false-positive on
+  prose that merely names a capitalized person. Observe mode exists precisely to
+  measure that FP rate on real outbound BEFORE any warn/block surface is built.
+
+## Blast radius
+- **Additive.** No route added, no class added, no dependency added. One config
+  key, one function, one fire-and-forget call.
+- **Hot path, but cold by default.** The call sits on the outbound delivery path,
+  but when the flag is off it returns on the first `if` before touching the store
+  or importing PrincipalGuard (dynamic import, so the cold path never even loads
+  the module).
+- **Audit write.** On a finding it appends to `state/principal-coherence.jsonl`,
+  mkdir-ing `state/` defensively first (the TopicOperatorStore only creates that
+  dir on its first write, which may not have happened yet). Append-only; bounded
+  per message by the number of distinct attributions found.
+
+## Migration parity
+None required. This is server-side route behavior + a config TYPE only. The
+config flag follows the exact convention of its sibling observe flag
+`monitoring.correctionLearning` — read with `=== true`, so absent → off. Behavior
+is therefore IDENTICAL for new and existing agents with no migrateConfig write
+(adding one would only cosmetically materialize a false flag). The
+`correctionLearning` flag has no migrateConfig/generateDefaultConfig entry for
+the same reason; this mirrors it.
+
+## Tests (all three tiers)
+- Tier 1 (unit): `tests/unit/principal-coherence-operator-seam.test.ts` (5) —
+  locks the store→guard contract the wiring depends on, both sides of the
+  boundary (bound operator resolves → no finding; outsider → finding; unbound →
+  finding; credential/mandate → block verdict; benign prose → nothing).
+- Tier 2 (integration): `tests/integration/principal-coherence-signal.test.ts`
+  (5) — over the wire: flag on + bound operator + misattribution logs; bound
+  operator attribution logs nothing; unbound logs operatorBound:false; flag off
+  logs nothing; a block-verdict finding never 422s.
+- Tier 3 (e2e): `tests/e2e/principal-coherence-lifecycle.test.ts` (4) — production
+  AgentServer boot; feature-is-alive write lands; signal-only (credential → 200,
+  not 422); bound-operator no-op; flag-off dark.
+
+## Rollback
+Revert the one observe function + its one call site + the config type, and delete
+the three test files. The jsonl on disk is inert. No data migration to unwind.