instar 1.3.16 → 1.3.18

package/dist/feedback-factory/receiver/defense.d.ts

@@ -0,0 +1,82 @@
+/**
+ * defense.ts — framework-agnostic port of the feedback receiver's intake defenses.
+ *
+ * Ports the six defense-in-depth layers of `the-portal/pages/api/instar/feedback.ts`
+ * (rate-limit, agent fingerprint, honeypot, HMAC signature, input validation,
+ * dedup-key/type) out of the Next.js handler into pure/injectable functions, so the
+ * canonical front (whatever framework hosts it) reuses the exact same logic. The
+ * HTTP wiring + the app/framework placement is deliberately NOT here (it is the
+ * architecture decision in the spec's blocked list); this is the reusable core.
+ *
+ * Reference is TypeScript, so equivalence is by faithful transcription + exhaustive
+ * both-sides-of-boundary unit tests (not a cross-runtime parity harness — those
+ * apply to the Python processor ports). `now` is injected everywhere the reference
+ * used `Date.now()`, so tests are deterministic.
+ *
+ * Convergence finding folded in: `normalizeWebhookSecret` trims the secret at load
+ * so a trailing newline can't silently break the HMAC (the reference relied on a
+ * "use printf not echo" warning; this makes it structural).
+ */
+export declare const VALID_TYPES: readonly ["bug", "feature", "improvement", "question", "hallucination", "other"];
+export type FeedbackType = typeof VALID_TYPES[number];
+export declare const SEMVER_RE: RegExp;
+export declare const FEEDBACK_ID_RE: RegExp;
+export declare const AGENT_NAME_RE: RegExp;
+export declare const NODE_VERSION_RE: RegExp;
+export declare const RATE_LIMITS: {
+    perHour: number;
+    perDay: number;
+    windowHourMs: number;
+    windowDayMs: number;
+};
+/** Trim the webhook secret so a trailing newline can't silently break the HMAC (convergence finding). */
+export declare function normalizeWebhookSecret(secret: string | undefined): string | undefined;
+export declare function isValidType(type: unknown): type is FeedbackType;
+/** Port of extractSourceIp: first x-forwarded-for hop, else remoteAddress, else 'unknown'. */
+export declare function extractSourceIp(headers: Record<string, string | string[] | undefined>, remoteAddress?: string): string;
+/** Port of validateAgentFingerprint: UA must contain "instar/"; version header, if present, must be semver. */
+export declare function validateAgentFingerprint(userAgent: string | undefined, headerVersion?: string): {
+    valid: boolean;
+    reason?: string;
+};
+/** Port of checkHoneypot: real agents never send `website`/`email`; presence ⇒ bot. */
+export declare function checkHoneypot(body: Record<string, unknown>): boolean;
+/**
+ * Port of verifySignature. HMAC-SHA256 over `${timestamp}.${JSON.stringify(body)}`,
+ * timing-safe compare, with a +5min / −1min replay window. `now` injected (ms).
+ */
+export declare function verifySignature(args: {
+    signature?: string;
+    timestamp?: string;
+    body: unknown;
+    secret: string | undefined;
+    now: number;
+}): boolean;
+/** Port of the input-validation block (:242–269): title ≥3, description ≥10, valid type, semver instarVersion. */
+export declare function validateFeedbackInput(body: Record<string, unknown>): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Port of the in-memory sliding-window rate limiter (checkRateLimit + prune) as an
+ * injectable class. `now()` is injectable for deterministic tests; defaults to Date.now.
+ */
+export declare class RateLimiter {
+    private readonly limits;
+    private readonly now;
+    private store;
+    private lastPrune;
+    private readonly pruneIntervalMs;
+    constructor(limits?: {
+        perHour: number;
+        perDay: number;
+        windowHourMs: number;
+        windowDayMs: number;
+    }, now?: () => number);
+    private prune;
+    check(ip: string): {
+        allowed: boolean;
+        retryAfterSec?: number;
+    };
+}
+//# sourceMappingURL=defense.d.ts.map

package/dist/feedback-factory/receiver/defense.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defense.d.ts","sourceRoot":"","sources":["../../../src/feedback-factory/receiver/defense.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,eAAO,MAAM,WAAW,kFAAmF,CAAC;AAC5G,MAAM,MAAM,YAAY,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;AAEtD,eAAO,MAAM,SAAS,QAA8B,CAAC;AACrD,eAAO,MAAM,cAAc,QAAyB,CAAC;AACrD,eAAO,MAAM,aAAa,QAAiD,CAAC;AAC5E,eAAO,MAAM,eAAe,QAAsB,CAAC;AAEnD,eAAO,MAAM,WAAW;;;;;CAKvB,CAAC;AAEF,yGAAyG;AACzG,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAErF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,YAAY,CAE/D;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAItH;AAED,+GAA+G;AAC/G,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CASnI;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAEpE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,OAAO,CAkBV;AAED,kHAAkH;AAClH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAcvG;AAED;;;GAGG;AACH,qBAAa,WAAW;IAMpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IANtB,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;gBAG/B,MAAM;;;;;KAAc,EACpB,GAAG,GAAE,MAAM,MAAyB;IAGvD,OAAO,CAAC,KAAK;IAWb,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE;CAsBhE"}

package/dist/feedback-factory/receiver/defense.js

@@ -0,0 +1,147 @@
+/**
+ * defense.ts — framework-agnostic port of the feedback receiver's intake defenses.
+ *
+ * Ports the six defense-in-depth layers of `the-portal/pages/api/instar/feedback.ts`
+ * (rate-limit, agent fingerprint, honeypot, HMAC signature, input validation,
+ * dedup-key/type) out of the Next.js handler into pure/injectable functions, so the
+ * canonical front (whatever framework hosts it) reuses the exact same logic. The
+ * HTTP wiring + the app/framework placement is deliberately NOT here (it is the
+ * architecture decision in the spec's blocked list); this is the reusable core.
+ *
+ * Reference is TypeScript, so equivalence is by faithful transcription + exhaustive
+ * both-sides-of-boundary unit tests (not a cross-runtime parity harness — those
+ * apply to the Python processor ports). `now` is injected everywhere the reference
+ * used `Date.now()`, so tests are deterministic.
+ *
+ * Convergence finding folded in: `normalizeWebhookSecret` trims the secret at load
+ * so a trailing newline can't silently break the HMAC (the reference relied on a
+ * "use printf not echo" warning; this makes it structural).
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export const VALID_TYPES = ['bug', 'feature', 'improvement', 'question', 'hallucination', 'other'];
+export const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+export const FEEDBACK_ID_RE = /^fb-[a-z0-9-]{6,36}$/;
+export const AGENT_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9 _-]{0,98}[a-zA-Z0-9]$/;
+export const NODE_VERSION_RE = /^v?\d+\.\d+\.\d+$/;
+export const RATE_LIMITS = {
+    perHour: 10,
+    perDay: 50,
+    windowHourMs: 60 * 60 * 1000,
+    windowDayMs: 24 * 60 * 60 * 1000,
+};
+/** Trim the webhook secret so a trailing newline can't silently break the HMAC (convergence finding). */
+export function normalizeWebhookSecret(secret) {
+    return secret == null ? secret : secret.trim();
+}
+export function isValidType(type) {
+    return typeof type === 'string' && VALID_TYPES.includes(type);
+}
+/** Port of extractSourceIp: first x-forwarded-for hop, else remoteAddress, else 'unknown'. */
+export function extractSourceIp(headers, remoteAddress) {
+    const xff = headers['x-forwarded-for'];
+    const xffStr = Array.isArray(xff) ? xff[0] : xff;
+    return xffStr?.split(',')[0]?.trim() || remoteAddress || 'unknown';
+}
+/** Port of validateAgentFingerprint: UA must contain "instar/"; version header, if present, must be semver. */
+export function validateAgentFingerprint(userAgent, headerVersion) {
+    const ua = userAgent || '';
+    if (!ua.toLowerCase().includes('instar/')) {
+        return { valid: false, reason: 'missing-ua' };
+    }
+    if (headerVersion && !SEMVER_RE.test(headerVersion)) {
+        return { valid: false, reason: 'invalid-version-header' };
+    }
+    return { valid: true };
+}
+/** Port of checkHoneypot: real agents never send `website`/`email`; presence ⇒ bot. */
+export function checkHoneypot(body) {
+    return Boolean(body.website || body.email);
+}
+/**
+ * Port of verifySignature. HMAC-SHA256 over `${timestamp}.${JSON.stringify(body)}`,
+ * timing-safe compare, with a +5min / −1min replay window. `now` injected (ms).
+ */
+export function verifySignature(args) {
+    const { signature, timestamp, body, secret, now } = args;
+    if (!signature || !timestamp || !secret)
+        return false;
+    const age = now - parseInt(timestamp, 10);
+    if (isNaN(age) || age > 300_000 || age < -60_000)
+        return false;
+    const payload = `${timestamp}.${JSON.stringify(body)}`;
+    const expected = createHmac('sha256', secret).update(payload).digest('hex');
+    try {
+        const sigBuf = Buffer.from(signature, 'hex');
+        const expBuf = Buffer.from(expected, 'hex');
+        if (sigBuf.length !== expBuf.length)
+            return false;
+        return timingSafeEqual(new Uint8Array(sigBuf), new Uint8Array(expBuf));
+    }
+    catch {
+        return false;
+    }
+}
+/** Port of the input-validation block (:242–269): title ≥3, description ≥10, valid type, semver instarVersion. */
+export function validateFeedbackInput(body) {
+    if (!body.type || !isValidType(body.type)) {
+        return { valid: false, error: 'Invalid request format' };
+    }
+    if (!body.title || typeof body.title !== 'string' || body.title.trim().length < 3) {
+        return { valid: false, error: 'Invalid request format' };
+    }
+    if (!body.description || typeof body.description !== 'string' || body.description.trim().length < 10) {
+        return { valid: false, error: 'Invalid request format' };
+    }
+    if (body.instarVersion && !SEMVER_RE.test(body.instarVersion)) {
+        return { valid: false, error: 'Invalid request format' };
+    }
+    return { valid: true };
+}
+/**
+ * Port of the in-memory sliding-window rate limiter (checkRateLimit + prune) as an
+ * injectable class. `now()` is injectable for deterministic tests; defaults to Date.now.
+ */
+export class RateLimiter {
+    limits;
+    now;
+    store = new Map();
+    lastPrune = 0;
+    pruneIntervalMs = 10 * 60 * 1000;
+    constructor(limits = RATE_LIMITS, now = () => Date.now()) {
+        this.limits = limits;
+        this.now = now;
+    }
+    prune() {
+        const now = this.now();
+        if (now - this.lastPrune < this.pruneIntervalMs)
+            return;
+        this.lastPrune = now;
+        const cutoff = now - this.limits.windowDayMs;
+        this.store.forEach((entry, key) => {
+            entry.timestamps = entry.timestamps.filter(t => t > cutoff);
+            if (entry.timestamps.length === 0)
+                this.store.delete(key);
+        });
+    }
+    check(ip) {
+        this.prune();
+        const now = this.now();
+        const entry = this.store.get(ip) || { timestamps: [] };
+        const hourAgo = now - this.limits.windowHourMs;
+        const dayAgo = now - this.limits.windowDayMs;
+        const hourCount = entry.timestamps.filter(t => t > hourAgo).length;
+        const dayCount = entry.timestamps.filter(t => t > dayAgo).length;
+        if (hourCount >= this.limits.perHour) {
+            const oldest = entry.timestamps.filter(t => t > hourAgo).sort()[0];
+            return { allowed: false, retryAfterSec: Math.ceil((oldest + this.limits.windowHourMs - now) / 1000) };
+        }
+        if (dayCount >= this.limits.perDay) {
+            const oldest = entry.timestamps.filter(t => t > dayAgo).sort()[0];
+            return { allowed: false, retryAfterSec: Math.ceil((oldest + this.limits.windowDayMs - now) / 1000) };
+        }
+        entry.timestamps.push(now);
+        this.store.set(ip, entry);
+        return { allowed: true };
+    }
+}
+//# sourceMappingURL=defense.js.map

package/dist/feedback-factory/receiver/defense.js.map

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

package/dist/scheduler/MentorStageBForensics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MentorStageBForensics.d.ts","sourceRoot":"","sources":["../../src/scheduler/MentorStageBForensics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,uCAAuC,CAAC;AAU/C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAiB9E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAgCvF;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAS/F"}
+{"version":3,"file":"MentorStageBForensics.d.ts","sourceRoot":"","sources":["../../src/scheduler/MentorStageBForensics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,uCAAuC,CAAC;AA6B/C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA0B9E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAgCvF;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAS/F"}

package/dist/scheduler/MentorStageBForensics.js

@@ -14,10 +14,28 @@
 import { ISSUE_BUCKETS, ISSUE_SEVERITIES, } from '../monitoring/FrameworkIssueLedger.js';
 const MAX_FINDINGS_PER_RUN = 10; // bound a single tick's output
 const MAX_TITLE = 200;
-/** A normalized slug for a conservative dedupKey when the model omits one. */
+/** A normalized slug for a dedupKey from a model-supplied stable id (keeps it as-is, kebabed). */
 function slug(s) {
     return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'untitled';
 }
+/**
+ * Derive a conservative dedupKey from a title when the model omits one. Strips
+ * VOLATILE tokens that would split one issue across runs — standalone numbers,
+ * timeout/percent/version literals, and hex-ish ids — keeping only the stable
+ * symptom words. (§13.3: titles are operator-dependent; this is the last-resort
+ * fallback — the prompt asks the model for a stable id directly.)
+ */
+function deriveStableSlug(title) {
+    const stable = title
+        .toLowerCase()
+        .replace(/\bv?\d+(?:\.\d+)+\b/g, ' ') // version strings (v1.3.14, 1.2.3)
+        .replace(/\b\d+\s*(?:ms|s|m|h|%|k|kb|mb|tokens?|turns?)\b/g, ' ') // 8s, 42%, 15k, 1 turn
+        .replace(/\b[0-9a-f]{6,}\b/g, ' ') // hex ids / shas
+        .replace(/\b\d+\b/g, ' ') // any remaining standalone numbers
+        .replace(/\s+/g, ' ')
+        .trim();
+    return slug(stable || title);
+}
 /**
  * Build the Stage-B forensic prompt. The model is asked to classify ONLY what
  * the signals actually evidence into the three buckets, and to output a strict
@@ -36,6 +54,15 @@ export function buildForensicPrompt(framework, signals) {
         ``,
         `Output ONLY a JSON array (no markdown, no prose). Each element:`,
         `  {"bucket": "...", "title": "<short>", "severity": "low|medium|high", "dedupKey": "<stable-id>"}`,
+        ``,
+        `CRITICAL — the dedupKey must be STABLE across runs. It is a short lowercase-kebab identifier`,
+        `for the ROOT SYMPTOM, NOT a rephrasing of your title. Use the SAME id you would use if you saw`,
+        `this exact issue again next time. Base it on the symptom class + the component, e.g.`,
+        `"feedback-webhook-429", "inputguard-review-timeout", "codex-single-turn-exit". Do NOT put`,
+        `version numbers, timestamps, session ids, counts, or wording variations in the dedupKey —`,
+        `those drift and would split one issue into many. Two reports of the same root problem MUST`,
+        `produce the same dedupKey.`,
+        ``,
         `If the signals evidence no concrete issue, output []. Never invent issues.`,
         ``,
         `--- Signals ---`,
@@ -84,7 +111,7 @@ export function parseForensicFindings(raw, framework) {
             : 'medium';
         const dedupKey = typeof o.dedupKey === 'string' && o.dedupKey.trim()
             ? `${framework}::${slug(o.dedupKey)}`
-            : `${framework}::${slug(title)}`;
+            : `${framework}::${deriveStableSlug(title)}`;
         out.push({ bucket: bucket, title, severity, dedupKey, signature: title });
     }
     return out;

package/dist/scheduler/MentorStageBForensics.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.16",
+  "version": "1.3.18",
   "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-05-27T06:41:15.968Z",
-  "instarVersion": "1.3.16",
+  "generatedAt": "2026-05-27T07:09:40.342Z",
+  "instarVersion": "1.3.18",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.17.md

@@ -0,0 +1,34 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Framework-Onboarding Mentor System — forensic dedup stability.** A live validation run surfaced
+that the same root issue could be logged 2–3 times across ticks under different IDs, because when the
+model omitted a stable identifier the system derived one from the (drifting) wording — the exact
+title-dependence the design doc warns against. Fixed two ways: the forensic prompt now demands a
+stable, symptom-based identifier (no version numbers, counts, ids, or wording variants), and the
+fallback derivation strips volatile tokens before building a key. Live re-run confirmed cross-tick
+merging now works (16 → 12 issues over the same 3 iterations). Still dormant.
+
+## What to Tell Your User
+
+- The mentor's notebook now keeps one entry per real problem even when the wording wobbles between
+  inspections — no more slow drizzle of near-duplicate entries.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Stable forensic dedup | Automatic — the same root issue collapses to one ledger entry across ticks |
+
+## Evidence
+
+Found by running the real loop through multiple iterations against real data (the iterate-and-harden
+loop working as designed). Fix proven by: 3 new unit tests asserting the model-supplied stable key is
+preferred, that two phrasings of one issue differing only in volatile tokens (`8s` vs `8000ms`)
+collapse to the **same** dedupKey, and that version/percent/hex tokens are stripped from the derived
+fallback; plus a live re-run on Echo's real server.log + Codey's real rollouts showing cross-tick
+merge dropped duplicates from 16 → 12 over the same 3 iterations. 13 unit tests total; affected
+push-config suite green vs canonical main.

package/upgrades/1.3.18.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Sixth increment of the **Feedback Factory Migration** (Dawn → Echo; spec `docs/specs/feedback-factory-migration.md`, approved). Ports the **receiver intake defenses** — the six security layers of the feedback front door — out of the reference Next.js handler (`the-portal/pages/api/instar/feedback.ts`) into framework-agnostic TypeScript at `src/feedback-factory/receiver/defense.ts`.
+
+The layers: a per-IP sliding-window rate limiter (10/hour, 50/day), the agent fingerprint check (User-Agent must say `instar/`, version header must be semver), the honeypot (real agents never send `website`/`email`), HMAC signature verification with a 5-minute replay window, input validation (title/description length, valid type, semver), and the type/dedup helpers. Pure/injectable functions plus one self-contained `RateLimiter` class. **Not wired into any route yet** — the HTTP/app placement is a separate decision; this is the reusable core.
+
+A convergence finding is folded in: the webhook secret is trimmed at load, so a trailing newline can't silently break the signature check (replacing a "be careful how you set it" warning with structure).
+
+## What to Tell Your User
+
+- The security guards on the feedback front door — rate limiting, bot traps, signature checks, input validation — are now ported into our own codebase, ready to attach to the new front door when we stand it up.
+- One sharp-edge removed for good: a stray newline in the signing secret used to be able to silently break verification; now it's trimmed automatically.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Receiver intake defenses (TS port) | Internal module `src/feedback-factory/receiver/defense.ts` — not yet wired |
+
+## Evidence
+
+- The reference is TypeScript, so equivalence is by faithful transcription plus exhaustive both-sides-of-boundary tests (16 unit tests): rate limit at 10 vs 11 and after a window slide and per-IP; fingerprint with/without `instar/` and valid/invalid version; honeypot present/absent; HMAC valid/wrong/missing and both replay-window edges (+5min/−1min); validation at title 2 vs 3 and description 9 vs 10. The clock is injected everywhere, so the time-based windows are tested deterministically.
+- The HMAC payload formula, replay thresholds, and validation bounds are copied verbatim from the reference the field agents already sign against.

package/upgrades/side-effects/feedback-factory-receiver-defense.md

@@ -0,0 +1,33 @@
+# Side-Effects Review — feedback receiver intake defenses (Phase 1, increment 6)
+
+**Slug:** `feedback-factory-receiver-defense`
+**Date:** `2026-05-27`
+**Author:** Echo (autonomous)
+**Spec:** `docs/specs/feedback-factory-migration.md` (converged v2, approved by Justin 2026-05-26)
+**Scope:** The six intake defense layers of the receiver, ported as pure/injectable functions. NOT the Next.js/Vercel HTTP wiring (the app-placement architecture decision — spec's blocked list).
+
+## Summary of the change
+
+Ports the defense-in-depth logic of `the-portal/pages/api/instar/feedback.ts` out of the Next.js handler into `src/feedback-factory/receiver/defense.ts` as framework-agnostic functions: `RateLimiter` (in-memory sliding window, 10/hr + 50/day, injectable clock), `validateAgentFingerprint` (UA must contain `instar/`; version-header semver), `checkHoneypot` (website/email ⇒ bot), `verifySignature` (HMAC-SHA256 over `${timestamp}.${JSON.stringify(body)}`, timing-safe, +5min/−1min replay window, injectable `now`), `validateFeedbackInput` (title ≥3, description ≥10, valid type, semver version), plus the regex constants + `isValidType` + `extractSourceIp`. **Not wired into any route yet** — no behavioral change.
+
+Convergence finding folded in: `normalizeWebhookSecret` trims the secret at load so a trailing newline can't silently break the HMAC (replaces the reference's "use printf not echo" warning with structure).
+
+## Equivalence verification
+
+The reference is TypeScript (not Python), so equivalence is by **faithful transcription + exhaustive both-sides-of-boundary unit tests**, not a cross-runtime parity harness (those apply only to the Python processor ports). `now` is injected everywhere the reference used `Date.now()`, so the rate-limit window + replay window are tested deterministically (10 allowed → 11th blocked; window slide; per-IP isolation; replay-window edges at +5min/−1min; HMAC valid/wrong/missing). The HMAC formula, replay thresholds, and validation bounds are copied verbatim from the reference.
+
+## Seven-dimension review
+
+1. **Over/under-reach** — Pure/injectable functions + one stateful class (`RateLimiter`) that owns its own Map (no module-level global, unlike the reference — a deliberate improvement for testability + multi-instance safety). Not wired into any route.
+2. **Level-of-abstraction fit** — `src/feedback-factory/receiver/` — the receiver layer, separate from the processor. The HTTP/framework wiring is intentionally excluded (blocked architecture decision); this is the reusable core that any host calls.
+3. **Signal vs Authority** — N/A; these are validators/guards returning verdicts. The HTTP handler (later) decides the response code.
+4. **Interactions** — None. New isolated module; nothing imports it yet.
+5. **Rollback cost** — Trivial: delete the module + tests.
+6. **Migration parity** — N/A. New internal library code; no agent-installed file touched.
+7. **Failure modes** — (a) HMAC payload-construction divergence from what agents sign → the formula is transcribed verbatim (`${timestamp}.${JSON.stringify(body)}`); the sender side already uses this. (b) Trailing-newline secret → structurally trimmed (`normalizeWebhookSecret`) + tested. (c) Rate-limit clock non-determinism → injectable `now`, tested via window-slide. (d) Replay-window off-by-one → both edges (+5min/−1min) tested.
+
+## Tests
+
+- Tier-1 unit (CI): `tests/unit/feedback-factory/defense.test.ts` — 16 tests across all six layers + secret normalization + boundaries.
+- No cross-runtime parity harness (reference is TS; equivalence by transcription + boundary tests — noted above).
+- No integration/E2E this increment: the HTTP wiring/app placement is the blocked architecture decision; these functions attach to a route when that's decided. Reasoned, documented.

package/upgrades/side-effects/mentor-forensic-dedup-stability.md

@@ -0,0 +1,49 @@
+# Side-Effects Review — Forensic dedupKey stability (§19.4 follow-on)
+
+**Spec:** `docs/specs/FRAMEWORK-ONBOARDING-MENTOR-SPEC.md` (converged 5 iters, approved by Justin)
+**Change:** Hardens Stage-B forensic dedupKey stability so the same root issue produces the same
+key across ticks (§13.3: "title is too operator-dependent"). Found by **live validation**: running
+the real forensics through 3 iterations on real data logged the same issue 2–3× under different
+keys, because the LLM-omitted-key fallback derived from the (drifting) title. Fix: (1) the prompt
+now demands a stable, symptom-based lowercase-kebab `dedupKey` with explicit "no versions / numbers /
+ids / wording variants" guidance; (2) the fallback derivation strips volatile tokens
+(numbers, version/percent/unit literals, hex ids) before slugging.
+**Files:** `src/scheduler/MentorStageBForensics.ts`, `tests/unit/MentorStageBForensics.test.ts`,
+`upgrades/NEXT.md`.
+
+## Principle check (Phase 1)
+
+Decision point? No. This sharpens an identifier (dedup quality) on a signal-only path. No gating.
+
+## The seven questions
+
+1. **Over-block.** Over-aggressive token stripping could in theory merge two genuinely-distinct
+   issues whose titles differ only in numbers. Mitigated: the strip only applies to the *fallback*
+   (when the LLM omits a key); the LLM-supplied symptom key is preferred. And §13.3's design makes
+   false merges the conservative-acceptable direction only on `dedupKey` while `signature` (the full
+   title) preserves the distinction for probable-dup review.
+2. **Under-block.** LLM forensics are inherently variable run-to-run, so cross-tick merging is
+   improved (live-measured 16→12 issues over the same 3 iterations) but not perfect; the residual
+   is handled by the `signature`-based probable-dup review (§13.3), unchanged.
+3. **Level-of-abstraction fit.** Pure-module change (prompt + key derivation); no I/O. Correct layer.
+4. **Signal vs authority.** Unchanged — signal-only.
+5. **Interactions.** Only changes the `dedupKey` a finding carries; the ledger's existing
+   conservative auto-merge on `(framework, dedupKey)` does the rest (no ledger change).
+6. **External surfaces.** None — internal forensic logic.
+7. **Rollback cost.** Trivial — revert the prompt + derivation change.
+
+## Phase 5 — second-pass
+
+Not required — a dedup-quality refinement on a pure, tested module; no decision/spawn/session surface.
+
+## Validation
+
+Live re-run on Echo's real server.log + Codey's real rollouts: before, 3 iterations produced 16
+issues (near-zero cross-tick merge); after, the same 3 iterations produced 12 (iterations 2–3 each
+merged ~half their findings into existing issues) — the cross-tick merge now demonstrably works.
+
+## Testing
+
+13 unit tests (+3): prefers the model-supplied stable key; fallback strips volatile tokens so
+phrasing/number variants of one issue collapse to the same key; version/percent/hex tokens stripped.
+Affected push-config suite green vs canonical main.