instar 1.3.673 → 1.3.674

package/dist/core/inboundLossRouting.d.ts

@@ -0,0 +1,30 @@
+/**
+ * F3 (Inbound Delivery Is Sacred) — pure routing plan for inbound-queue loss
+ * notices. A lost inbound user message must reach the user who sent it (each
+ * loss item's `sessionKey` IS the topic id they messaged from) OR, if it has no
+ * resolvable destination, be surfaced LOUDLY — never silently expired. This pure
+ * function decides the routing; server.ts does the actual notify()/loud-surface.
+ * Constitution: "The User Experience Is the Product" → sub-standard #3 Inbound
+ * Delivery Is Sacred. Spec: docs/specs/inbound-delivery-sacred.md.
+ */
+export interface InboundLossRoutePlan {
+    /** Per-ORIGINATING-topic notice — each affected topic + how many of its
+     *  messages were lost (delivered IN that topic, the proven path). */
+    perTopic: Array<{
+        topicId: number;
+        count: number;
+    }>;
+    /** Count of lost items whose sessionKey is not a resolvable numeric topic.
+     *  These fall back to the attention topic; if that is unset too, they MUST be
+     *  surfaced loudly (the one seam where a loss could otherwise go silent). */
+    unresolved: number;
+}
+/**
+ * Group inbound loss items by their originating topic. Pure: same input → same
+ * output. A sessionKey that is a positive finite number is a topic id; anything
+ * else (empty, non-numeric, legacy single-file key) is counted as `unresolved`.
+ */
+export declare function planInboundLossNotices(items: ReadonlyArray<{
+    sessionKey: string;
+}>): InboundLossRoutePlan;
+//# sourceMappingURL=inboundLossRouting.d.ts.map

package/dist/core/inboundLossRouting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inboundLossRouting.d.ts","sourceRoot":"","sources":["../../src/core/inboundLossRouting.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,oBAAoB;IACnC;yEACqE;IACrE,QAAQ,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD;;iFAE6E;IAC7E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAC3C,oBAAoB,CAkBtB"}

package/dist/core/inboundLossRouting.js

@@ -0,0 +1,35 @@
+/**
+ * F3 (Inbound Delivery Is Sacred) — pure routing plan for inbound-queue loss
+ * notices. A lost inbound user message must reach the user who sent it (each
+ * loss item's `sessionKey` IS the topic id they messaged from) OR, if it has no
+ * resolvable destination, be surfaced LOUDLY — never silently expired. This pure
+ * function decides the routing; server.ts does the actual notify()/loud-surface.
+ * Constitution: "The User Experience Is the Product" → sub-standard #3 Inbound
+ * Delivery Is Sacred. Spec: docs/specs/inbound-delivery-sacred.md.
+ */
+/**
+ * Group inbound loss items by their originating topic. Pure: same input → same
+ * output. A sessionKey that is a positive finite number is a topic id; anything
+ * else (empty, non-numeric, legacy single-file key) is counted as `unresolved`.
+ */
+export function planInboundLossNotices(items) {
+    const byTopic = new Map();
+    let unresolved = 0;
+    for (const it of items) {
+        const tid = Number(it.sessionKey);
+        if (Number.isFinite(tid) && tid > 0) {
+            byTopic.set(tid, (byTopic.get(tid) ?? 0) + 1);
+        }
+        else {
+            unresolved++;
+        }
+    }
+    return {
+        // Deterministic order (ascending topic id) for stable notices + tests.
+        perTopic: [...byTopic.entries()]
+            .sort((a, b) => a[0] - b[0])
+            .map(([topicId, count]) => ({ topicId, count })),
+        unresolved,
+    };
+}
+//# sourceMappingURL=inboundLossRouting.js.map

package/dist/core/inboundLossRouting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inboundLossRouting.js","sourceRoot":"","sources":["../../src/core/inboundLossRouting.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAA4C;IAE5C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC;QAClC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,UAAU,EAAE,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO;QACL,uEAAuE;QACvE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;aAC7B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;aAC3B,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,UAAU;KACX,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.673",
+  "version": "1.3.674",
   "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-26T09:25:54.721Z",
-  "instarVersion": "1.3.673",
+  "generatedAt": "2026-06-26T09:54:44.118Z",
+  "instarVersion": "1.3.674",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.674.md

@@ -0,0 +1,43 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The durable inbound holding-queue's loss notices ("I didn't get to your messages")
+were delivered to a single internal attention-topic and **silently dropped when that
+topic was unset** — so a held inbound user message could expire AND the user never be
+told (postmortem Failure 3, the "why aren't you responding?" failure). This routes each
+loss notice to the **originating topic** the user actually messaged from (every loss
+item carries its `sessionKey` = topic id), and surfaces LOUDLY (`console.error`) the one
+residual case where a loss has no resolvable topic and no attention topic is configured.
+A lost inbound message is now never silently expired.
+
+New pure router `planInboundLossNotices` (`src/core/inboundLossRouting.ts`, unit-tested)
++ a `notifyInboundLoss` helper in server.ts, applied to all 5 inbound-queue loss sites.
+Constitution: *The User Experience Is the Product* → sub-standard #3.
+
+## What to Tell Your User
+
+Nothing changes day-to-day — the inbound holding-queue ships **dark** (off by default),
+so this code only runs when it is deliberately enabled. The guarantee it adds: when the
+queue IS in use and can't deliver one of your messages, you hear about it **in your own
+conversation**, not in a side channel you might never see. A message you send either
+gets through or you're told it didn't — never silence.
+
+## Summary of New Capabilities
+
+- Inbound-queue loss notices now route to the originating topic (per-user, in their
+  conversation) instead of a single attention topic.
+- A loss with no resolvable topic and no attention topic configured is surfaced loudly
+  (error log) instead of silently dropped.
+- No new config, route, or surface; no behavior change while the inbound queue is dark.
+
+## Evidence
+
+- 6 unit tests for the pure router (`tests/unit/inboundLossRouting.test.ts`) — originating-topic
+  routing, unresolved counting, zero/negative/non-numeric → unresolved, deterministic order.
+- Full `npm run lint` (tsc + ~20 lint scripts) exits 0; clean tsc.
+- Side-effects review: `upgrades/side-effects/inbound-delivery-sacred.md`.
+- Spec: `docs/specs/inbound-delivery-sacred.md`.

package/upgrades/side-effects/inbound-delivery-sacred.md

@@ -0,0 +1,62 @@
+# Side-Effects Review — Inbound Delivery Is Sacred (Postmortem F3)
+
+**Version / slug:** `inbound-delivery-sacred`
+**Date:** `2026-06-26`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `not-required — Phase 5 triggers on a block/allow DECISION on inbound messaging; this makes no block/allow decision (it is loss-notice delivery ROUTING, no authority added), runs only while the queue is dark, and is backed by a pure unit-tested router. Rigor is the 6-case unit suite + this review.`
+
+## Summary
+
+Routes inbound-queue loss notices to the ORIGINATING topic (each loss item's
+`sessionKey` is the topic id) instead of the single `agent-attention-topic` that
+`notify()` silently drops when unset. A loss with no resolvable topic and no
+attention topic surfaces LOUDLY (`console.error`) instead of vanishing. New pure
+function `planInboundLossNotices` (`src/core/inboundLossRouting.ts`) + a thin
+`notifyInboundLoss` helper in server.ts, applied to all 5 inbound-queue loss sites.
+
+## The 8 questions
+
+1. **Over-block** — N/A. This is not a gate; it adds no block/reject. It only
+   changes WHERE a loss notice is delivered. It cannot reject a legitimate message.
+2. **Under-block** — N/A (no blocking). The failure mode it closes is *under-notice*
+   (a silent drop), which is exactly what it fixes.
+3. **Level-of-abstraction fit** — Correct layer. The loss is detected in
+   `QueueDrainLoop` (already complete); the DELIVERY of the notice is a server-bootstrap
+   concern (where `notify` + the attention-topic state live). The grouping logic is
+   extracted to a pure, testable core (`inboundLossRouting.ts`); server.ts only does
+   the side-effecting notify/console.error. Right split.
+4. **Signal vs authority** — Pure signal-delivery. No blocking authority added. The
+   pure router holds no authority; the helper only emits notices. Complies with
+   `docs/signal-vs-authority.md`.
+5. **Interactions** — Reuses the existing `notify()` funnel (batcher, attention
+   topic, Slack mirror) — does not bypass it, only passes a `topicId` so it lands in
+   the originating topic. The `stuck-recovery` notice already routed per-topic and is
+   UNCHANGED. No double-fire: each loss item is counted once, per topic.
+6. **External surfaces** — Changes the destination + wording of a user-facing loss
+   notice (now per-topic, drops the redundant "topics:" list). It depends on the loss
+   item's `sessionKey` being the topic id (verified — that is how the queue keys
+   custody). No new external dependency.
+7. **Multi-machine posture** — Machine-local BY DESIGN. Each machine reports the loss
+   of the messages IT held; the notice goes to the originating topic on that machine's
+   Telegram path. No replication needed (a loss is a local custody event). The
+   attention-topic fallback + loud `console.error` are also machine-local.
+8. **Rollback cost** — Trivial. The change is inert while the inbound queue is dark
+   (default). Revert is a code-only back-out (no migration, no state). The queue's
+   loss-DETECTION is unchanged; only the notice routing differs.
+
+## What it does NOT do
+
+- Does not change the queue's loss-detection, retry, or expiry logic (all already
+  complete). It only hardens the notice *channel*.
+- Does not touch the fail-OPEN direct-inject fallback (already comprehensive).
+- Does not run while the queue is dark (default) — zero behavior change on the fleet.
+
+## Rollback
+
+Revert the commit. No persisted state, no migration. Inert while `inboundQueueConfig`
+ships `enabled:false`.
+
+## Second-pass reviewer verdict
+
+Not required — see the header rationale (no block/allow decision; delivery-routing only;
+dark; pure-function-backed). The decision boundary is covered by the 6-case unit suite.