instar 1.3.351 → 1.3.353

package/upgrades/side-effects/topic-operator-binding-inc2b.md

@@ -0,0 +1,72 @@
+# Side-effects review — Topic Operator binding (Know Your Principal #898, increment 2b)
+
+## What this change does
+Wires the already-merged `TopicOperatorStore` (#904) into the live `AgentServer`
+composition and exposes it over HTTP, plus the session-start injection block.
+
+- `AgentServer.ts`: a new `topicOperatorStore` field constructed under the
+  `stateDir` guard inside its own try/catch (mirrors the `approvalLedger`
+  precedent), then passed into `routeCtx`.
+- `routes.ts`: a `topicOperatorStore` field on `RouteContext` and four routes —
+  `GET /topic-operator`, `GET /topic-operator/:topicId`,
+  `GET /topic-operator/session-context?topicId=N`, `POST /topic-operator`.
+- `CapabilityIndex.ts`: a `topicOperator` capability entry (prefix
+  `/topic-operator`) so the routes are discoverable.
+
+## Blast radius
+- **Additive only.** No existing route, field, or store is modified. The store
+  is constructed when `stateDir` is available and is otherwise `null`; every
+  route degrades to `503` (feature-not-available) when it is `null`, never a
+  null-deref crash. The E2E test asserts the routes answer `200` on the real
+  production boot path (the store is genuinely composed in, not null).
+- **No auth change.** All four routes sit behind the existing Bearer
+  middleware, identical to `/topic-bindings` and `/approvals`.
+- **Fail-safe by construction.** An init failure is caught and reported via
+  `console.warn`; it can never block server boot. A corrupt store file is
+  treated as empty (a missing operator means the cross-principal guard treats
+  everything as unverifiable — deny-safe, not allow-safe).
+
+## The load-bearing security property (unchanged from #904)
+The operator is established ONLY from the authenticated sender `uid`. The POST
+route refuses a blank uid with `400`; a `displayName` (a content name) is never
+authoritative — it is only lowercased for prose-matching. There is no code path
+by which a name read from content becomes the operator. This is the structural
+fix for the "Caroline" identity-bleed failure mode, and the integration + E2E
+tests both assert the blank-uid refusal over the wire.
+
+## Migration parity
+No migration is required. These are server-side routes and an in-process store
+field — they reach existing agents automatically on the next server update (the
+Migration Parity Standard governs agent-installed FILES: settings hooks, config
+defaults, CLAUDE.md template, hook scripts, skills — none of which this touches).
+The store auto-creates `state/topic-operators.json` on first write; no config
+key is added, so there is nothing for `migrateConfig` to backfill.
+
+The session-start HOOK wiring (so the `<topic-operator>` block is actually
+fetched and injected at boot) is deliberately NOT in this increment — that is a
+hook-template change requiring `migrateHooks`, and is scoped to increment 2c so
+this PR stays a focused, reviewable composition+routes change. Until 2c lands the
+block is reachable at the route but nothing injects it yet; that is intentional.
+
+## Framework generality
+This is framework-agnostic. `platform` is a generic string (`telegram` |
+`whatsapp` | `slack` | …), so the binding works for any messaging adapter, not
+just Telegram. The `session-context` route returns a plain text block that any
+framework's session-start hook can fetch and inject — it is not coupled to
+Claude Code, Codex, or Gemini. The store has no platform-specific logic; it
+delegates identity establishment to `PrincipalGuard.establishOperator`, which is
+itself pure and framework-neutral.
+
+## Tests
+- Tier 1 (unit): `tests/unit/topic-operator-store.test.ts` (10) — shipped in #904.
+- Tier 2 (integration): `tests/integration/topic-operator-routes.test.ts` (10) —
+  full HTTP pipeline over a real file-backed store, incl. the blank-uid refusal
+  and the store-not-wired 503 degradation.
+- Tier 3 (E2E): `tests/e2e/topic-operator-lifecycle.test.ts` (6) — feature-alive
+  on the real `AgentServer` boot path (200 not 503), full bind→read→inject
+  lifecycle, durable-write proof, and the over-the-wire blank-uid refusal.
+
+## Rollback
+Revert the three source edits + delete the two test files. The store on disk
+(`state/topic-operators.json`) is inert without the routes and can be left or
+removed with no consequence.

package/upgrades/side-effects/topic-operator-store.md

@@ -0,0 +1,37 @@
+# Side-effects review — TopicOperatorStore (Know Your Principal, increment 2)
+
+## What this change is
+A new `src/users/TopicOperatorStore.ts` — a JSON-backed (`state/topic-operators.json`)
+store for the verified per-topic operator, plus its unit test. Decoupled from
+the ScopeVerifier topic→project binding by design (a topic can have an operator
+without a project binding; TopicProjectBinding requires projectName/projectDir).
+
+## Blast radius
+- **Runtime impact: none.** Nothing constructs or imports TopicOperatorStore at
+  boot or in any route/job/sentinel yet — adding it cannot change live behavior.
+  The routes + session-start injection that consume it are later increments.
+- Imports only `PrincipalGuard.establishOperator` (pure, already shipped in #902).
+- New state file `state/topic-operators.json` is created lazily on first write;
+  read fails safe to empty on missing/corrupt (a missing operator → the guard
+  treats everything as unverifiable, which is the safe direction).
+
+## Security review
+- Operator establishment is uid-only by construction (delegates to
+  establishOperator) — no path accepts a name from content as the operator
+  (the Caroline failure mode is impossible).
+- No network, no secrets, no new auth; one local JSON file.
+
+## Framework generality
+Pure logic + one local JSON file — no session-launch/inject/message-delivery
+surface; framework-agnostic.
+
+## Test coverage
+10 unit tests (`tests/unit/topic-operator-store.test.ts`) covering both sides of
+every boundary: valid-uid establish + read-back, blank-uid refusal, content-name-
+never-becomes-operator, unbound→null, persistence across instances, replace,
+asVerifiedOperator (feeds the guard), and sessionContextBlock (bound/unbound/uid-
+fallback). tsc clean; docs-coverage class floor restored (TopicOperatorStore
+documented in the Know Your Principal concept doc).
+
+## Rollback
+Delete the module + test + the doc mention; zero runtime consequence (no consumers).

package/upgrades/topic-operator-binding-inc2b.eli16.md

@@ -0,0 +1,47 @@
+# ELI16 — Who's the boss of this chat?
+
+## The problem in one sentence
+An AI agent needs to know, for sure, *which real person* it's working for in a
+given conversation — and it should never get tricked into thinking some other
+name it read somewhere is the boss.
+
+## The story behind it
+Not long ago, an agent running on a shared computer slowly started treating a
+*different real person* — call her Caroline — as the person giving it orders. It
+even wrote her name into its work as if her approvals counted. Nobody caught it,
+because the mix-up happened entirely inside the agent's own writing. There was no
+"front door" guard checking that, because the bad name never came in through a
+message — it leaked in from the machine's settings and the agent's own notes.
+
+We already built two pieces to stop this: a detector brain (`PrincipalGuard`)
+that spots when the agent credits a decision to the wrong person, and a small
+filing cabinet (`TopicOperatorStore`) that remembers, per conversation, exactly
+who the verified boss is. The rule the filing cabinet enforces is strict: the
+boss is decided ONLY by the verified ID of whoever actually sent the message —
+never by a name typed in some document.
+
+## What this change adds
+This step plugs that filing cabinet into the running server so the rest of the
+system can actually use it. It adds four simple web endpoints:
+
+- "Who's the boss of this chat?" — read one conversation's verified operator.
+- "Show me all the bosses" — list every conversation's verified operator.
+- "Set the boss" — record the boss, but ONLY from a verified sender ID. If you
+  try to set it with a blank ID (hoping a typed-in name will stick), it says no.
+- "Give me the boot-up note" — hand back a short block the agent can read at the
+  start of a session so it knows, from message one, who it's really serving.
+
+## Why it's safe
+It only *adds* things. Nothing old changes. If the server can't build the filing
+cabinet for some reason, the endpoints politely say "not available" instead of
+crashing. And the one rule that matters most — a name you merely *read* can never
+become the boss, only a verified sender can — is checked right at the web layer,
+and we have tests that prove it by trying to sneak the name "Caroline" in through
+a blank ID and watching it get rejected.
+
+## What's deliberately left for next time
+The actual "read the boot-up note at session start" wiring (so the agent
+automatically sees who its boss is every time it wakes up) is a separate, slightly
+riskier change to the start-up script, so it gets its own follow-up step. For now
+the note is available to ask for; nothing reads it automatically yet. That's on
+purpose — it keeps this change small and easy to review.