instar 1.3.992 → 1.3.993

package/dist/core/RecurrenceActuator.d.ts

@@ -0,0 +1,79 @@
+/**
+ * RecurrenceActuator — turns a recurrence finding into tracked work, once.
+ *
+ * `RecurrenceReader` makes recurrence VISIBLE. Visibility is not the goal: the
+ * project's whole diagnosis is that instar notices constantly and closes almost
+ * nothing (filing-to-completion ≈ 30:1). A reader that produces a beautiful
+ * report which nobody acts on would be the 30:1 ratio with better typography.
+ *
+ * Operator directive, 2026-07-26 20:08Z: *"the synthesis itself must lead to
+ * ACTION and a fully closed loop"*, with as little user dependence as possible.
+ *
+ * So this proposes ONE thing, through a path that already exists: for a cluster
+ * that genuinely recurs and that nobody has ever turned into work, create a
+ * tracked action on the EXISTING evolution action queue. That closes the loop —
+ * noticed repeatedly → becomes real work → appears where work is tracked → gets
+ * done or explicitly cancelled.
+ *
+ * WHAT THIS IS NOT:
+ *  - Not a new notification channel. The single funniest way to fail at fixing
+ *    "we notice things and never close them" is to build a fourth place that
+ *    notices things. Nothing here notifies anybody.
+ *  - Not authority. Creating a tracked action QUEUES work for a human or agent to
+ *    judge. It does not close, prioritise, escalate, or act on anything.
+ *  - Not a bulk importer. See "the fix must not become its own pile" below.
+ */
+import type { RecurrenceReport } from './RecurrenceReader.js';
+/** A proposed piece of tracked work. The caller performs the actual write. */
+export interface ProposedAction {
+    title: string;
+    description: string;
+    priority: 'critical' | 'high' | 'medium' | 'low';
+    /**
+     * Stable key derived from the cluster, so a re-run UPDATES rather than
+     * duplicates. Without this the actuator would itself become a generator of
+     * repeated noticings — the precise disease it treats.
+     */
+    externalKey: string;
+    /** The cluster this came from, for the caller's audit trail. */
+    sourceKey: string;
+    observedCount: number;
+}
+export type ActuationRefusal = {
+    reason: 'actions-store-unreadable';
+    detail: string;
+} | {
+    reason: 'no-qualifying-clusters';
+    detail: string;
+};
+export interface ActuationPlan {
+    /** Empty when `refused` is set. */
+    propose: ProposedAction[];
+    /** Set when the actuator declined to act at all, with why. */
+    refused?: ActuationRefusal;
+    /** Clusters that qualified but were held back by the per-run cap. */
+    deferredByCap: number;
+    /** Always present, so a caller can report honestly even on a refusal. */
+    consideredClusters: number;
+}
+export interface ActuationOptions {
+    /**
+     * A thing seen twice is not yet a pattern worth spending a work item on.
+     * Default 10: high enough that a proposal is obviously justified by volume.
+     */
+    minCount?: number;
+    /**
+     * Hard cap per run. 69 qualifying clusters turned into 69 action items would
+     * be a new backlog wearing a different hat — the fix becoming its own pile.
+     * A small cap converges across sessions instead, densest-first.
+     */
+    maxPerRun?: number;
+}
+/**
+ * Decide what work to propose from a recurrence report.
+ *
+ * Pure: it returns a PLAN. The caller writes it, so the write path (and its
+ * gating) stays exactly where it already is.
+ */
+export declare function planActuation(report: RecurrenceReport, opts?: ActuationOptions): ActuationPlan;
+//# sourceMappingURL=RecurrenceActuator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RecurrenceActuator.d.ts","sourceRoot":"","sources":["../../src/core/RecurrenceActuator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAqB,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEjF,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACjD;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,MAAM,EAAE,0BAA0B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,MAAM,EAAE,wBAAwB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,gBAAgB,EACxB,IAAI,GAAE,gBAAqB,GAC1B,aAAa,CAyDf"}

package/dist/core/RecurrenceActuator.js

@@ -0,0 +1,116 @@
+/**
+ * RecurrenceActuator — turns a recurrence finding into tracked work, once.
+ *
+ * `RecurrenceReader` makes recurrence VISIBLE. Visibility is not the goal: the
+ * project's whole diagnosis is that instar notices constantly and closes almost
+ * nothing (filing-to-completion ≈ 30:1). A reader that produces a beautiful
+ * report which nobody acts on would be the 30:1 ratio with better typography.
+ *
+ * Operator directive, 2026-07-26 20:08Z: *"the synthesis itself must lead to
+ * ACTION and a fully closed loop"*, with as little user dependence as possible.
+ *
+ * So this proposes ONE thing, through a path that already exists: for a cluster
+ * that genuinely recurs and that nobody has ever turned into work, create a
+ * tracked action on the EXISTING evolution action queue. That closes the loop —
+ * noticed repeatedly → becomes real work → appears where work is tracked → gets
+ * done or explicitly cancelled.
+ *
+ * WHAT THIS IS NOT:
+ *  - Not a new notification channel. The single funniest way to fail at fixing
+ *    "we notice things and never close them" is to build a fourth place that
+ *    notices things. Nothing here notifies anybody.
+ *  - Not authority. Creating a tracked action QUEUES work for a human or agent to
+ *    judge. It does not close, prioritise, escalate, or act on anything.
+ *  - Not a bulk importer. See "the fix must not become its own pile" below.
+ */
+/**
+ * Decide what work to propose from a recurrence report.
+ *
+ * Pure: it returns a PLAN. The caller writes it, so the write path (and its
+ * gating) stays exactly where it already is.
+ */
+export function planActuation(report, opts = {}) {
+    const minCount = opts.minCount ?? 10;
+    const maxPerRun = opts.maxPerRun ?? 3;
+    // THE REFUSAL, and it is sharper than the reader's.
+    //
+    // The reader withholds a VERDICT on any partial read. The actuator must
+    // withhold the ACTION — but only one missing store actually invalidates the
+    // decision, and conflating them would be lazy symmetry:
+    //
+    //   attention/sentinel unreadable → the reader saw FEWER observations. Counts
+    //     are understated, so a cluster that qualifies still genuinely qualifies.
+    //     Acting is conservative and safe.
+    //
+    //   ACTIONS unreadable → `tracked` is UNKNOWABLE for every cluster, because
+    //     `tracked` means "a member came from the action queue". Every cluster
+    //     would look untracked. Acting would duplicate work that may already
+    //     exist — the actuator would manufacture the exact redundancy it exists to
+    //     remove, and do it under the banner of fixing it.
+    //
+    // So: actions-store unreadable ⇒ propose NOTHING, and say why.
+    const actionsUnreadable = report.coverage.unreadable.find((u) => u.store === 'actions');
+    if (actionsUnreadable) {
+        return {
+            propose: [],
+            refused: {
+                reason: 'actions-store-unreadable',
+                detail: `the action queue could not be read (${actionsUnreadable.reason}), so "has anyone already ` +
+                    'committed to this?" is unanswerable for every cluster. Proposing work now would duplicate ' +
+                    'whatever is already tracked. No actions proposed.',
+            },
+            deferredByCap: 0,
+            consideredClusters: report.clusters.length,
+        };
+    }
+    const qualifying = report.clusters.filter((c) => !c.tracked && c.count >= minCount);
+    if (qualifying.length === 0) {
+        return {
+            propose: [],
+            refused: {
+                reason: 'no-qualifying-clusters',
+                detail: `no untracked cluster reached the minCount=${minCount} threshold`,
+            },
+            deferredByCap: 0,
+            consideredClusters: report.clusters.length,
+        };
+    }
+    const selected = qualifying.slice(0, maxPerRun);
+    return {
+        propose: selected.map(toProposedAction),
+        deferredByCap: qualifying.length - selected.length,
+        consideredClusters: report.clusters.length,
+    };
+}
+/** Priority from volume alone — deterministic, no model, no judgment. */
+function priorityFor(count) {
+    if (count >= 100)
+        return 'high';
+    if (count >= 25)
+        return 'medium';
+    return 'low';
+}
+function toProposedAction(c) {
+    const span = c.firstSeen && c.lastSeen && c.firstSeen !== c.lastSeen
+        ? ` between ${c.firstSeen} and ${c.lastSeen}`
+        : '';
+    return {
+        title: `Recurring, untracked: ${c.exemplar.slice(0, 90)}`,
+        description: `Noticed ${c.count} times${span} across ${c.stores.join(', ')}` +
+            (c.sources.length ? ` (sources: ${c.sources.slice(0, 5).join(', ')})` : '') +
+            `, and never turned into tracked work.\n\n` +
+            'Surfaced by RecurrenceReader, which groups observations across the attention queue, the ' +
+            'action queue and the sentinel log. The individual noticings are each minor and each true; ' +
+            'the VOLUME is the finding.\n\n' +
+            'This action exists so the recurrence is either fixed or deliberately dismissed, rather than ' +
+            'noticed a further N times. Cancelling it IS a valid outcome — an explicit decision beats ' +
+            'silent accumulation.',
+        priority: priorityFor(c.count),
+        // Stable across runs: the same cluster always maps to the same key, so a
+        // second pass updates one row instead of adding another.
+        externalKey: `recurrence:${c.key}`,
+        sourceKey: c.key,
+        observedCount: c.count,
+    };
+}
+//# sourceMappingURL=RecurrenceActuator.js.map

package/dist/core/RecurrenceActuator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecurrenceActuator.js","sourceRoot":"","sources":["../../src/core/RecurrenceActuator.ts"],"names":[],"mappings":"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"}

package/dist/core/recurrenceLoop.d.ts

@@ -0,0 +1,66 @@
+/**
+ * recurrenceLoop — the caller that makes the loop actually close.
+ *
+ * `RecurrenceReader` sees. `RecurrenceActuator` decides. Neither touches a store,
+ * which is what keeps both pure and testable — but it also meant "the loop
+ * closes" was a DESIGNED property and not a demonstrated one. This is the piece
+ * that demonstrates it: it reads the three stores, plans, and writes the result
+ * through the caller-supplied action-creation function.
+ *
+ * It is deliberately the ONLY place in this feature that performs I/O, so every
+ * read failure has exactly one place to be reported from and cannot be swallowed
+ * somewhere in the middle.
+ *
+ * Operator directive 2026-07-26 20:08Z: synthesis must lead to ACTION, through
+ * paths that already exist, with the loop closed and minimal user dependence.
+ */
+import { type Observation, type RecurrenceReport } from './RecurrenceReader.js';
+import { type ActuationOptions, type ProposedAction } from './RecurrenceActuator.js';
+/** Reads one store. Returning a rejected promise is how it reports "unreadable". */
+export type StoreReader = () => Promise<Observation[]>;
+export interface LoopDeps {
+    readAttention: StoreReader;
+    readActions: StoreReader;
+    readSentinel: StoreReader;
+    /**
+     * Creates ONE tracked action. The caller supplies this so the write goes
+     * through whatever path it already uses, with whatever gating that path
+     * already has. This module never constructs an HTTP call itself.
+     */
+    createAction: (a: ProposedAction) => Promise<{
+        id: string;
+    }>;
+}
+export interface LoopResult {
+    report: RecurrenceReport;
+    /** Actions actually created, with the ids the store returned. */
+    created: {
+        id: string;
+        title: string;
+        observedCount: number;
+    }[];
+    /** Set when the actuator declined; `created` is then empty. */
+    refused?: {
+        reason: string;
+        detail: string;
+    };
+    /** Qualifying clusters held back by the per-run cap. */
+    deferredByCap: number;
+    /**
+     * Proposals whose WRITE failed. Distinct from `refused` (a decision not to
+     * act) — this is a decision to act that did not land, and conflating the two
+     * would hide real breakage behind a principled-looking refusal.
+     */
+    writeFailures: {
+        title: string;
+        error: string;
+    }[];
+}
+/**
+ * Run one pass: read → group → plan → create.
+ *
+ * Never throws for an unreadable store — that is data, reported in
+ * `report.coverage`, and it is what the actuator's refusal reads.
+ */
+export declare function runRecurrenceLoop(deps: LoopDeps, opts?: ActuationOptions): Promise<LoopResult>;
+//# sourceMappingURL=recurrenceLoop.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recurrenceLoop.d.ts","sourceRoot":"","sources":["../../src/core/recurrenceLoop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAiB,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEpG,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AAEvD,MAAM,WAAW,QAAQ;IACvB,aAAa,EAAE,WAAW,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,YAAY,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB,iEAAiE;IACjE,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAChE,+DAA+D;IAC/D,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,aAAa,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACnD;AAoBD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,QAAQ,EACd,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,UAAU,CAAC,CA0CrB"}

package/dist/core/recurrenceLoop.js

@@ -0,0 +1,76 @@
+/**
+ * recurrenceLoop — the caller that makes the loop actually close.
+ *
+ * `RecurrenceReader` sees. `RecurrenceActuator` decides. Neither touches a store,
+ * which is what keeps both pure and testable — but it also meant "the loop
+ * closes" was a DESIGNED property and not a demonstrated one. This is the piece
+ * that demonstrates it: it reads the three stores, plans, and writes the result
+ * through the caller-supplied action-creation function.
+ *
+ * It is deliberately the ONLY place in this feature that performs I/O, so every
+ * read failure has exactly one place to be reported from and cannot be swallowed
+ * somewhere in the middle.
+ *
+ * Operator directive 2026-07-26 20:08Z: synthesis must lead to ACTION, through
+ * paths that already exist, with the loop closed and minimal user dependence.
+ */
+import { buildRecurrenceReport, } from './RecurrenceReader.js';
+import { planActuation } from './RecurrenceActuator.js';
+/** Read a store, converting failure into a named coverage gap rather than a throw. */
+async function readOrRecord(store, read, into, coverage) {
+    try {
+        into.push(...(await read()));
+        coverage.read.push(store);
+    }
+    catch (err) {
+        coverage.unreadable.push({
+            store,
+            reason: err instanceof Error ? err.message.slice(0, 200) : String(err).slice(0, 200),
+        });
+    }
+}
+/**
+ * Run one pass: read → group → plan → create.
+ *
+ * Never throws for an unreadable store — that is data, reported in
+ * `report.coverage`, and it is what the actuator's refusal reads.
+ */
+export async function runRecurrenceLoop(deps, opts = {}) {
+    const observations = [];
+    const coverage = { read: [], unreadable: [], completeness: 'complete' };
+    await readOrRecord('attention', deps.readAttention, observations, coverage);
+    await readOrRecord('actions', deps.readActions, observations, coverage);
+    await readOrRecord('sentinel', deps.readSentinel, observations, coverage);
+    coverage.completeness = coverage.unreadable.length === 0 ? 'complete' : 'partial';
+    const report = buildRecurrenceReport(observations, coverage);
+    const plan = planActuation(report, opts);
+    if (plan.refused) {
+        return {
+            report,
+            created: [],
+            refused: plan.refused,
+            deferredByCap: plan.deferredByCap,
+            writeFailures: [],
+        };
+    }
+    const created = [];
+    const writeFailures = [];
+    for (const proposal of plan.propose) {
+        try {
+            const { id } = await deps.createAction(proposal);
+            created.push({ id, title: proposal.title, observedCount: proposal.observedCount });
+        }
+        catch (err) {
+            // A failed write is NOT a refusal. Recording it separately keeps a real
+            // outage from reading as a principled decision not to act — which would be
+            // this project's own failure mode (absence presenting as presence) at the
+            // very end of the loop it exists to close.
+            writeFailures.push({
+                title: proposal.title,
+                error: err instanceof Error ? err.message.slice(0, 200) : String(err).slice(0, 200),
+            });
+        }
+    }
+    return { report, created, deferredByCap: plan.deferredByCap, writeFailures };
+}
+//# sourceMappingURL=recurrenceLoop.js.map

package/dist/core/recurrenceLoop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurrenceLoop.js","sourceRoot":"","sources":["../../src/core/recurrenceLoop.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.992",
+  "version": "1.3.993",
   "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-07-27T03:37:34.934Z",
-  "instarVersion": "1.3.992",
+  "generatedAt": "2026-07-27T04:10:39.708Z",
+  "instarVersion": "1.3.993",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.993.md

@@ -0,0 +1,73 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The recurrence reader (shipped in the previous fragment) makes recurrence visible. Visibility was
+never the goal: a report nobody acts on is the same filing-to-completion ratio with better
+typography. Two modules close the remaining half.
+
+`src/core/RecurrenceActuator.ts` turns a recurrence finding into a proposal for ONE tracked action on
+the EXISTING evolution action queue — no new store, no new notification channel, no new authority.
+Creating a tracked action queues work for a human or agent to judge; it does not close, prioritise,
+escalate, or act on anything.
+
+`src/core/recurrenceLoop.ts` is the caller that actually closes the loop: it reads the three stores,
+plans, and writes through a caller-supplied action-creation function. It is deliberately the only
+place in the feature that performs I/O, so a read failure has exactly one place to be reported from
+and cannot be swallowed mid-pipeline.
+
+## What to Tell Your User
+
+Things you notice repeatedly can now become real work instead of being noticed again.
+
+The part shipped earlier counted how often the same underlying problem had been raised. This part
+takes the worst offenders and opens tracked items for them in the queue you already use — noticed
+repeatedly, never owned, becomes a job that gets done or explicitly dropped. Dropping it is a fine
+outcome, and the item says so: an explicit "no, we're fine with this" is worth far more than the same
+thing being raised another two hundred times.
+
+It is bounded on purpose. Out of 836 problems in a live dry run it would open three and hold back
+seventeen, working through the backlog over time rather than replacing one pile with another.
+
+The honest limit: nothing runs it on a schedule yet, so it closes the loop when something calls it,
+not on its own.
+
+## Summary of New Capabilities
+
+No new endpoint, command, or config key. Two internal modules: one that decides what recurring,
+untracked problem deserves a tracked action, and one that performs the read-plan-create pass through
+the action queue that already exists.
+
+## Evidence
+
+Full loop run against the three live stores with only the write intercepted: coverage complete, 836
+distinct problems, **would create 3, deferred 17 by the cap, zero write failures**. So "the loop
+closes" is demonstrated, not designed.
+
+Two refusals, deliberately **not** symmetric:
+
+- **Actions store unreadable ⇒ propose nothing.** `tracked` is unknowable for every cluster, so every
+  cluster looks unowned and the actuator would manufacture duplicates of work that already exists —
+  the exact redundancy it was built to remove, under the banner of fixing it.
+- **Attention or sentinel unreadable ⇒ proceed.** Those only understate counts, so a cluster still
+  clearing the threshold genuinely clears it. Treating all three identically would have looked
+  tidier and been wrong.
+
+A **failed write** is recorded separately from a **refusal**. One is an outage; the other is a
+decision not to act. Conflating them would let real breakage present as sound judgment. One failed
+write does not abandon the remaining ones.
+
+Bounds against the fix becoming its own pile: `minCount` (default 10), a hard per-run cap (default 3)
+so it converges across sessions densest-first rather than turning 69 clusters into 69 items, and a
+stable `externalKey` so a re-run updates instead of duplicating. Unit suite 30/30 across the feature;
+`tsc --noEmit` exit 0.
+
+## Known limits
+
+**Nothing schedules it.** The loop can close unattended; nothing yet calls it, so today it closes only
+when something invokes it. That is stated rather than implied. Priority is derived from volume alone
+— deterministic, no model, no judgment — so a rare-but-serious problem ranks below a frequent-but-
+trivial one. It inherits the reader's title-only keying, including its occasional over-merge.

package/upgrades/side-effects/recurrence-actuator.md

@@ -0,0 +1,130 @@
+# Side-Effects Review — RecurrenceActuator (Tier 2 item 4, plan-only)
+
+**Version / slug:** `recurrence-actuator`
+**Date:** `2026-07-27`
+**Author:** `Echo (instar-dev agent)`
+
+## Summary
+
+`RecurrenceReader` makes recurrence visible. Visibility was never the goal — the project's diagnosis
+is that instar notices constantly and closes almost nothing (≈30:1). A reader nobody acts on is that
+ratio with better typography.
+
+Operator directive 2026-07-26 20:08Z: *"the synthesis itself must lead to ACTION and a fully closed
+loop"*, minimal user dependence.
+
+`planActuation()` returns a PLAN: for clusters that genuinely recur AND are untracked, propose work on
+the EXISTING evolution action queue. Pure — the caller performs the write, so the write path and its
+gating stay exactly where they already are.
+
+**Live dry-run, 2026-07-27:** 836 clusters considered → **3 proposed, 17 deferred by cap**
+(278x idle-timeout, 238x escalation-suppressed, 177x credential rebalancer — all `high`).
+
+## Refusal evidence (constraint 2)
+
+```
+REFUSAL 1 — actions store unreadable  ⇒  propose NOTHING
+  refused.reason : actions-store-unreadable
+  detail         : "…so 'has anyone already committed to this?' is unanswerable for every
+                    cluster. Proposing work now would duplicate whatever is already tracked."
+  propose        : []          consideredClusters: 1   ← still honest about scope
+
+DELIBERATELY NOT SYMMETRIC — attention/sentinel unreadable ⇒ it DOES act
+  Those only UNDERSTATE counts, so a cluster still clearing the bar genuinely clears it.
+  Treating all partial reads alike would be lazy symmetry that blocks safe action.
+
+REFUSAL 2 — per-run cap: 10 qualifying clusters ⇒ propose 3, deferredByCap 7
+REFUSAL 3 — below threshold: seen 3x with minCount 10 ⇒ no-qualifying-clusters
+REFUSAL 4 — already tracked: a member from the action queue ⇒ propose nothing
+```
+
+Tests **10 passed (10)**; combined with the reader **21 passed (21)**; `tsc --noEmit` exit 0.
+
+## A test caught the documented over-merge risk, live
+
+My first cap test built clusters titled `problem 0`…`problem 9` and asserted 3 proposals. It got 1:
+the recurrence key normalizes digits to `N`, so all ten collapsed to one cluster. **The fixture was
+naive, not the code** — and it is a live demonstration of the over-merge trade the reader's
+side-effects review names as its weakest point. Fixed with word-titles and the reason recorded in
+the test.
+
+## Decision-point inventory
+
+| point | classification |
+|---|---|
+| actions-unreadable ⇒ refuse | `invariant` — the load-bearing rule |
+| untracked + minCount filter | `invariant` — deterministic thresholds |
+| per-run cap, densest-first | `invariant` |
+| priority from volume | `invariant` — fixed bands, no model |
+| `externalKey` from cluster key | `invariant` — stable, idempotent |
+
+No judgment points, no LLM.
+
+## 1. Over-block
+
+Refuses entirely when the actions store is unreadable — deliberately, since acting blind creates
+duplicates. Cost: on a broken actions store, nothing is proposed until it is fixed. Correct trade.
+
+The `minCount` default of 10 will skip genuine problems seen 4–9 times. Accepted: a work item per
+seen-twice observation is how the queue got to 371 open in the first place.
+
+## 2. Under-block
+
+**Nothing prevents the CALLER from ignoring the plan or writing it badly.** This module returns data;
+the write is the caller's. That is the right seam (the write path keeps its own gating) but it means
+"the loop closes" is only true once a caller is wired. No caller ships here — that is the next step
+and is not claimed.
+
+**Cancelled actions are not re-proposed-proof.** If a human cancels a proposed action, the cluster
+remains untracked, so a later run could propose it again. The `externalKey` makes it the same row
+rather than a new one, but a "dismissed, stop asking" state belongs to the action store, not here.
+Named as a real gap. <!-- tracked: ACT-1311 -->
+
+## 3. Level-of-abstraction fit
+
+Plan-only, pure over the report. It cannot flood, cannot notify, cannot write. The one thing it
+must never become — a fourth place that notices things — is structurally impossible: it has no
+output channel.
+
+## 4. Signal vs authority compliance
+
+It proposes; it holds no authority. Creating a tracked action QUEUES work for a human or agent to
+judge — it does not close, prioritise beyond a fixed volume rule, escalate, or act.
+
+## 5. Interactions
+
+Consumes `RecurrenceReport` only. No writes, no schema change, no existing caller. Depends on
+`RecurrenceReader` (same branch, PR #1662) — this is stacked on it.
+
+## 6. External surfaces
+
+**None.** No route, no config, no persisted state, no user-visible behaviour in this increment.
+
+## 7. Multi-machine posture
+
+**Posture: `machine-local`.** `machine-local-justification: physical-credential-locality` — it plans
+over one machine's stores, whose observation titles carry that machine's ids, topics and account
+emails. Cross-machine synthesis would mean replicating those records; the correct route is the
+existing pool-scope fan-out, serving each machine's data from that machine.
+
+## 8. Rollback cost
+
+**Zero.** One module, one test file, no callers. Delete removes the feature.
+
+## Phase 5 — Second-pass review
+
+No gate/sentinel/watchdog, no block/allow authority, no session lifecycle, no LLM. Author lenses:
+
+**Adversarial — "how would I make this useless?"** Let it propose blind when the actions store is
+down (duplicates existing work), or let it propose for everything at once (new backlog). Both are
+asserted refusals.
+
+**"Would it have caught the incident?"** The incident is 69 untracked recurrers. It selects exactly
+that class and would open the top three today.
+
+**"Symptom or cause?"** Cause for the never-gets-picked-up half. NOT for the recurrence itself —
+proposing work does not fix the 278x idle-timeout; it makes someone decide about it. Claiming
+otherwise would be filing-as-progress.
+
+**Weakest point:** no caller is wired, so "the loop closes" is a designed property, not yet a
+demonstrated one. The dry-run shows what it WOULD propose; nothing has been written.

package/upgrades/side-effects/recurrence-loop.md

@@ -0,0 +1,112 @@
+# Side-Effects Review — recurrenceLoop (the caller that closes the loop)
+
+**Version / slug:** `recurrence-loop` · **Date:** `2026-07-27` · **Author:** `Echo (instar-dev agent)`
+
+## Summary
+
+`RecurrenceReader` sees; `RecurrenceActuator` decides. Both are pure, which left **"the loop closes"
+a DESIGNED property, not a demonstrated one** — the weakest point named in the actuator's own review.
+This closes it: read three stores → group → plan → create, via a caller-supplied `createAction`.
+
+It is deliberately the ONLY I/O in the feature, so every read failure has exactly one reporting site
+and cannot be swallowed mid-pipeline.
+
+**Live run, writes intercepted, 2026-07-27:** coverage `complete` (attention, actions, sentinel);
+836 problems; **would create 3, deferred 17, 0 write failures, no refusal.**
+
+## Refusal evidence (constraint 2)
+
+```
+REFUSAL — action store unreadable ⇒ createAction NEVER CALLED
+  create spy      : not called          created: 0
+  refused.reason  : actions-store-unreadable      writeFailures: 0
+
+A FAILED WRITE IS NOT A REFUSAL  (the distinction this module exists to protect)
+  createAction throws '503 action store unavailable'
+    refused       : undefined      ← an outage must NOT present as judgement
+    writeFailures : [{ error: '503 …' }]
+    created       : 0
+
+  one failure among three ⇒ created 2, writeFailures 1 (others not abandoned)
+
+UNREADABLE STORE IS DATA, NOT AN EXCEPTION
+  sentinel throws ⇒ coverage.unreadable names it, completeness 'partial',
+    and it STILL creates 1 (sentinel only understates counts)
+  all three throw ⇒ verdict undefined, created 0, no crash
+```
+
+Tests **9 passed (9)**; whole feature **30 passed (30)**; `tsc --noEmit` exit 0.
+
+## Decision-point inventory
+
+| point | classification |
+|---|---|
+| read failure → coverage gap | `invariant` — try/catch → named entry, never a throw |
+| refusal vs write-failure separation | `invariant` — distinct fields, the load-bearing rule |
+| write loop continues past a failure | `invariant` |
+
+No judgment points, no LLM, no authority: `createAction` is supplied by the caller, so the write path
+keeps whatever gating it already has. This module never constructs an HTTP call.
+
+## 1. Over-block
+
+Refuses to write when the actions store is unreadable — inherited from the actuator and correct: it
+cannot tell what is already owned. Cost: a broken actions store stops proposals until fixed.
+
+## 2. Under-block
+
+**No scheduler/route calls it.** Running it is deliberate. So this demonstrates the loop CAN close,
+not that it closes *unattended*. Wiring a cadence is a separate increment with its own risk, and is
+not claimed here.
+
+**No dismissal memory.** A cancelled action leaves the cluster untracked, so a later run can propose
+it again (same `externalKey`, so one row, not many). A "dismissed, stop asking" state belongs to the
+action store. <!-- tracked: ACT-1311 -->
+
+**`createAction` failures are reported, not retried.** Deliberate: retry policy belongs to the write
+path, and a silent retry here would obscure the outage the separate field exists to surface.
+
+## 3. Level-of-abstraction fit
+
+All I/O in one place, everything else pure. The alternative — reads scattered through reader and
+actuator — is exactly how a failed read becomes an empty result that reads as "nothing found".
+
+## 4. Signal vs authority
+
+Holds none. It executes a plan produced by deterministic rules and writes through a function the
+caller owns.
+
+## 5. Interactions
+
+Consumes `RecurrenceReader` + `RecurrenceActuator` (same stack, PRs #1662 / actuator branch). Writes
+only via the injected function. No schema change.
+
+## 6. External surfaces
+
+**None.** No route, no config, no persisted state of its own.
+
+## 7. Multi-machine posture
+
+**Posture: `machine-local`.** `machine-local-justification: physical-credential-locality` — it reads
+one machine's stores, whose observation titles carry that machine's ids, topics and account emails,
+and writes to that machine's action queue. Cross-machine synthesis would mean replicating those
+records; the existing pool-scope fan-out is the correct route.
+
+## 8. Rollback cost
+
+**Zero.** One module, one test file, no callers.
+
+## Phase 5 — Second-pass review
+
+No gate/sentinel/watchdog, no block/allow authority, no LLM. Lenses:
+
+**Adversarial — "how would I make this useless?"** Report a write outage as a refusal, so breakage
+reads as judgement. Asserted against directly.
+
+**"Would it have caught the incident?"** It IS the incident's remedy: 69 untracked recurrers, top
+three actionable today.
+
+**"Symptom or cause?"** Cause for never-picked-up. Not for the recurrence itself — creating an item
+makes someone decide about the 278x idle-timeout; it does not fix it.
+
+**Weakest point:** nothing schedules it. "Closes unattended" remains unclaimed.