instar 1.3.352 → 1.3.354

package/upgrades/side-effects/apprenticeship-keystone-dormancy.md

@@ -0,0 +1,62 @@
+# Side-effects review — keystoneBalance dormancy dimension
+
+**Change:** add an orthogonal `dormant` flag (+ `lastKeystoneAgeMs`,
+`dormancyThresholdMs`) to the observe-only `keystoneBalance` block, plus a
+`?keystoneDormancyMs` route knob, template awareness, and a migration.
+
+**Signal vs authority (Phase 1):** This change involves **no decision point**. It
+adds read-only computed fields to an existing observe-only signal. It never gates,
+blocks, filters, or constrains any agent behavior. It is a pure signal-producer —
+the consumer (a human, or a future cadence job) decides what to do with `dormant`.
+`docs/signal-vs-authority.md` compliance: trivially satisfied (no authority held).
+
+1. **Over-block:** N/A — nothing is blocked. The only "false positive" risk is
+   reporting `dormant: true` for a layer that is intentionally idle. That is the
+   correct report (the layer IS dormant); acting on it remains a human/cadence
+   judgment. A future-dated keystone clamps age to 0, so clock skew cannot
+   manufacture false dormancy.
+
+2. **Under-block:** N/A — nothing is blocked. The signal still cannot see a layer
+   that was *never* registered as an instance (the separate fragmentation finding,
+   filed to the framework ledger as `apprenticeship-cycle-instance-no-referential-integrity`,
+   tracked for a follow-up decision). Dormancy is scoped to a single instance's
+   keystone axis by design.
+
+3. **Level-of-abstraction fit:** Correct layer. Dormancy is computed inside
+   `ApprenticeshipCycleStore.computeKeystoneBalance` alongside `starved`, from the
+   same already-tallied timestamps + the store's injectable `now()`. No new store,
+   no cross-store wiring, no new dependency. It belongs exactly where `starved`
+   already lives.
+
+4. **Signal vs authority compliance:** Compliant. Pure signal; zero blocking
+   authority. Both knobs (`?oversightStarvationThreshold`, `?keystoneDormancyMs`)
+   are observe-only tuning, not gates.
+
+5. **Interactions:** `dormant` is orthogonal to `starved` (both can be true; unit
+   test pins this). It does not shadow or get shadowed by `starved`, `driftWarning`,
+   or the §4a direct-shortcut exclusion. The migration interacts with the prior
+   layer-balance migration: the full-line insert fires only when `keystoneBalance`
+   is absent (now appends the dormant-aware shape); the new in-place upgrade fires
+   only when the pre-dormancy shape is present. The two are mutually exclusive and
+   each idempotent (tested).
+
+6. **External surfaces:** The `role-coverage` JSON response gains three fields and
+   the route accepts one new query param — purely additive, no removed/renamed
+   fields. The CLAUDE.md template + migration change what installed agents read
+   (one awareness line). No timing/runtime dependence beyond the store's `now()`,
+   which is injectable and tested with a fixed clock.
+
+7. **Rollback cost:** Trivial. Observe-only and additive — reverting the commit
+   removes the fields with no data migration, no agent-state repair, no hot-fix
+   urgency (nothing depends on `dormant` to function). The CLAUDE.md awareness line
+   is cosmetic and harmless if left.
+
+**Tier:** 1 (observe-only computed fields on an existing endpoint; all three test
+tiers green plus migration-parity tests). Below the risk-floor signal (2, raised
+by the PostUpdateMigrator touch) — acknowledged: the migrator change is the
+established idempotent doc-awareness pattern from #893, not a data migration.
+
+**No deferrals:** the feature ships complete — code, three test tiers, template
+awareness, and migration parity (new + already-migrated agents) all in this commit.
+The separate cycle-instance fragmentation finding is a distinct issue (filed to the
+ledger), not a deferred part of this change.

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/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.