instar 1.3.17 → 1.3.19

package/dist/core/wireRegistrySync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wireRegistrySync.js","sourceRoot":"","sources":["../../src/core/wireRegistrySync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkBH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,WAAmC,EACnC,IAAuB;IAEvB,MAAM,MAAM,GAAG,CAAC,IAAa,EAAE,EAAW,EAAE,EAAE,CAC5C,IAAI,CAAC,iBAAiB,CAAC,cAAc,MAAM,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,cAAc,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAE1F,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;IAE5C,OAAO;QACL,WAAW,EAAE,CAAC,YAAY,EAAE,kBAAkB,CAAC;QAC/C,MAAM;YACJ,WAAW,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;YACtC,WAAW,CAAC,GAAG,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/feedback-factory/dispatch/dispatch.d.ts

@@ -0,0 +1,47 @@
+/**
+ * dispatch.ts — framework-agnostic port of the dispatch (guidance-out) logic.
+ *
+ * Ports the pure logic of `the-portal/pages/api/instar/dispatches/index.ts` out of
+ * the Next.js handler: the dispatch type/priority vocab, the semver comparison used
+ * for version-compat filtering (an agent only receives a dispatch whose
+ * [minVersion, maxVersion] window includes the agent's version), the list query
+ * filter (since/type/version), and the create-dedup title normalization. The HTTP
+ * wiring + storage are excluded (the app-placement decision); this is the reusable
+ * core. Reference is TypeScript, so equivalence is by faithful transcription +
+ * exhaustive both-sides-of-boundary tests (not a cross-runtime parity harness).
+ */
+export declare const DISPATCH_TYPES: readonly ["strategy", "behavioral", "lesson", "configuration", "security", "action"];
+export type DispatchType = typeof DISPATCH_TYPES[number];
+export declare const DISPATCH_PRIORITIES: readonly ["low", "normal", "high", "critical"];
+export type DispatchPriority = typeof DISPATCH_PRIORITIES[number];
+export declare const SEMVER_RE: RegExp;
+export declare function isValidDispatchType(type: unknown): type is DispatchType;
+export declare function isValidDispatchPriority(p: unknown): p is DispatchPriority;
+/** Port of parseVersion: leading major.minor.patch → [n,n,n]; [0,0,0] if unparseable. */
+export declare function parseVersion(v: string): [number, number, number];
+/** Port of isVersionGte: version >= min (major.minor.patch, equal counts as gte). */
+export declare function isVersionGte(version: string, min: string): boolean;
+/** Port of isVersionLte: version <= max (equal counts as lte). */
+export declare function isVersionLte(version: string, max: string): boolean;
+export interface DispatchRecord {
+    dispatchId: string;
+    type: string;
+    title: string;
+    content?: string;
+    priority?: string;
+    minVersion?: string | null;
+    maxVersion?: string | null;
+    active?: boolean;
+    createdAt?: string;
+    [k: string]: unknown;
+}
+/**
+ * Port of handleList's version-compat filter: a dispatch is included only if the
+ * agent's version is within its [minVersion, maxVersion] window. Mirrors the
+ * reference — applied only when the agent sent a valid-semver version; otherwise
+ * all candidates pass (the caller gates on SEMVER_RE before calling).
+ */
+export declare function filterDispatchesForVersion(dispatches: DispatchRecord[], version: string): DispatchRecord[];
+/** Port of the create-path title normalization used for dedup: trim + cap at 500 chars. */
+export declare function normalizeDispatchTitle(title: string): string;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/feedback-factory/dispatch/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/feedback-factory/dispatch/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,cAAc,sFAAuF,CAAC;AACnH,MAAM,MAAM,YAAY,GAAG,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;AACzD,eAAO,MAAM,mBAAmB,gDAAiD,CAAC;AAClF,MAAM,MAAM,gBAAgB,GAAG,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAElE,eAAO,MAAM,SAAS,QAA8B,CAAC;AAErD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,YAAY,CAEvE;AACD,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,gBAAgB,CAEzE;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAIhE;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQlE;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQlE;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAM1G;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/feedback-factory/dispatch/dispatch.js

@@ -0,0 +1,72 @@
+/**
+ * dispatch.ts — framework-agnostic port of the dispatch (guidance-out) logic.
+ *
+ * Ports the pure logic of `the-portal/pages/api/instar/dispatches/index.ts` out of
+ * the Next.js handler: the dispatch type/priority vocab, the semver comparison used
+ * for version-compat filtering (an agent only receives a dispatch whose
+ * [minVersion, maxVersion] window includes the agent's version), the list query
+ * filter (since/type/version), and the create-dedup title normalization. The HTTP
+ * wiring + storage are excluded (the app-placement decision); this is the reusable
+ * core. Reference is TypeScript, so equivalence is by faithful transcription +
+ * exhaustive both-sides-of-boundary tests (not a cross-runtime parity harness).
+ */
+export const DISPATCH_TYPES = ['strategy', 'behavioral', 'lesson', 'configuration', 'security', 'action'];
+export const DISPATCH_PRIORITIES = ['low', 'normal', 'high', 'critical'];
+export const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+export function isValidDispatchType(type) {
+    return typeof type === 'string' && DISPATCH_TYPES.includes(type);
+}
+export function isValidDispatchPriority(p) {
+    return typeof p === 'string' && DISPATCH_PRIORITIES.includes(p);
+}
+/** Port of parseVersion: leading major.minor.patch → [n,n,n]; [0,0,0] if unparseable. */
+export function parseVersion(v) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+    if (!match)
+        return [0, 0, 0];
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** Port of isVersionGte: version >= min (major.minor.patch, equal counts as gte). */
+export function isVersionGte(version, min) {
+    const v = parseVersion(version);
+    const m = parseVersion(min);
+    for (let i = 0; i < 3; i++) {
+        if (v[i] > m[i])
+            return true;
+        if (v[i] < m[i])
+            return false;
+    }
+    return true; // equal
+}
+/** Port of isVersionLte: version <= max (equal counts as lte). */
+export function isVersionLte(version, max) {
+    const v = parseVersion(version);
+    const m = parseVersion(max);
+    for (let i = 0; i < 3; i++) {
+        if (v[i] < m[i])
+            return true;
+        if (v[i] > m[i])
+            return false;
+    }
+    return true; // equal
+}
+/**
+ * Port of handleList's version-compat filter: a dispatch is included only if the
+ * agent's version is within its [minVersion, maxVersion] window. Mirrors the
+ * reference — applied only when the agent sent a valid-semver version; otherwise
+ * all candidates pass (the caller gates on SEMVER_RE before calling).
+ */
+export function filterDispatchesForVersion(dispatches, version) {
+    return dispatches.filter((d) => {
+        if (d.minVersion && !isVersionGte(version, d.minVersion))
+            return false;
+        if (d.maxVersion && !isVersionLte(version, d.maxVersion))
+            return false;
+        return true;
+    });
+}
+/** Port of the create-path title normalization used for dedup: trim + cap at 500 chars. */
+export function normalizeDispatchTitle(title) {
+    return title.trim().slice(0, 500);
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/feedback-factory/dispatch/dispatch.js.map

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

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/messaging/FencedOutbox.d.ts

@@ -0,0 +1,42 @@
+/**
+ * FencedOutbox — fencing-token-gated outbound reply path (spec §8 G3a).
+ *
+ * "No duplicate replies" is enforced here STRUCTURALLY, not by assuming a single
+ * consumer. A reply is sent only while this machine holds the lease at the epoch
+ * the reply was stamped under; a fenced (stale-epoch) machine's in-flight reply
+ * is SUPPRESSED at the send path. The reply is committed to the message ledger
+ * with a deterministic idempotency key (hash(dedupeKey + replyIndex)) so any
+ * machine re-running the same event reproduces it identically — and the ledger
+ * recognizes an already-committed reply and refuses to re-send.
+ *
+ * On a channel with native outbound dedup the idempotency key makes a re-send a
+ * no-op; on a channel without it (Telegram), the dual-medium reply_committed
+ * marker (propagated by the sync layer) is what prevents a failover re-send.
+ */
+import { MessageProcessingLedger } from './MessageProcessingLedger.js';
+export interface FencedOutboxDeps {
+    ledger: MessageProcessingLedger;
+    /** The current effective fencing epoch. */
+    currentEpoch: () => number;
+    /** Whether this machine structurally holds the lease right now. */
+    holdsLease: () => boolean;
+    logger?: (msg: string) => void;
+}
+export interface SendOutcome {
+    sent: boolean;
+    suppressed: boolean;
+    reason: 'sent' | 'already-replied' | 'fenced-no-lease' | 'fenced-stale-epoch' | 'send-failed';
+    idempotencyKey: string;
+}
+export declare class FencedOutbox {
+    private readonly d;
+    constructor(deps: FencedOutboxDeps);
+    private log;
+    /**
+     * Send a reply for `dedupeKey`, stamped under `stampedEpoch` (the epoch the
+     * turn began processing under). Returns the outcome. The actual platform send
+     * is `sendFn`; it is invoked ONLY after the fencing checks pass.
+     */
+    send(dedupeKey: string, replyIndex: number, stampedEpoch: number, sendFn: () => Promise<void>): Promise<SendOutcome>;
+}
+//# sourceMappingURL=FencedOutbox.d.ts.map

package/dist/messaging/FencedOutbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FencedOutbox.d.ts","sourceRoot":"","sources":["../../src/messaging/FencedOutbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,uBAAuB,EAA8B,MAAM,8BAA8B,CAAC;AAEnG,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,uBAAuB,CAAC;IAChC,2CAA2C;IAC3C,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,mEAAmE;IACnE,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,oBAAoB,GAAG,aAAa,CAAC;IAC9F,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAmB;gBAEzB,IAAI,EAAE,gBAAgB;IAIlC,OAAO,CAAC,GAAG;IAIX;;;;OAIG;IACG,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC1B,OAAO,CAAC,WAAW,CAAC;CAgCxB"}

package/dist/messaging/FencedOutbox.js

@@ -0,0 +1,60 @@
+/**
+ * FencedOutbox — fencing-token-gated outbound reply path (spec §8 G3a).
+ *
+ * "No duplicate replies" is enforced here STRUCTURALLY, not by assuming a single
+ * consumer. A reply is sent only while this machine holds the lease at the epoch
+ * the reply was stamped under; a fenced (stale-epoch) machine's in-flight reply
+ * is SUPPRESSED at the send path. The reply is committed to the message ledger
+ * with a deterministic idempotency key (hash(dedupeKey + replyIndex)) so any
+ * machine re-running the same event reproduces it identically — and the ledger
+ * recognizes an already-committed reply and refuses to re-send.
+ *
+ * On a channel with native outbound dedup the idempotency key makes a re-send a
+ * no-op; on a channel without it (Telegram), the dual-medium reply_committed
+ * marker (propagated by the sync layer) is what prevents a failover re-send.
+ */
+import { computeReplyIdempotencyKey } from './MessageProcessingLedger.js';
+export class FencedOutbox {
+    d;
+    constructor(deps) {
+        this.d = deps;
+    }
+    log(m) {
+        this.d.logger?.(`[outbox] ${m}`);
+    }
+    /**
+     * Send a reply for `dedupeKey`, stamped under `stampedEpoch` (the epoch the
+     * turn began processing under). Returns the outcome. The actual platform send
+     * is `sendFn`; it is invoked ONLY after the fencing checks pass.
+     */
+    async send(dedupeKey, replyIndex, stampedEpoch, sendFn) {
+        const idempotencyKey = computeReplyIdempotencyKey(dedupeKey, replyIndex);
+        // Idempotency: if a reply was already committed (locally or via a remote
+        // dual-medium marker), do not send again.
+        if (this.d.ledger.isActedOn(dedupeKey)) {
+            this.log(`already replied to ${dedupeKey} — suppressing`);
+            return { sent: false, suppressed: true, reason: 'already-replied', idempotencyKey };
+        }
+        // Fencing: only the current lease holder, at the stamped epoch, may send.
+        if (!this.d.holdsLease()) {
+            this.log(`fenced (no lease) — suppressing reply to ${dedupeKey}`);
+            return { sent: false, suppressed: true, reason: 'fenced-no-lease', idempotencyKey };
+        }
+        const epoch = this.d.currentEpoch();
+        if (epoch !== stampedEpoch) {
+            this.log(`fenced (stale epoch ${stampedEpoch} != current ${epoch}) — suppressing reply to ${dedupeKey}`);
+            return { sent: false, suppressed: true, reason: 'fenced-stale-epoch', idempotencyKey };
+        }
+        try {
+            await sendFn();
+        }
+        catch (err) {
+            this.log(`send failed for ${dedupeKey}: ${err instanceof Error ? err.message : String(err)}`);
+            return { sent: false, suppressed: false, reason: 'send-failed', idempotencyKey };
+        }
+        // Commit the reply marker (durable, synchronous) BEFORE advancing the cursor.
+        this.d.ledger.commitReply(dedupeKey, idempotencyKey, stampedEpoch);
+        return { sent: true, suppressed: false, reason: 'sent', idempotencyKey };
+    }
+}
+//# sourceMappingURL=FencedOutbox.js.map

package/dist/messaging/FencedOutbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FencedOutbox.js","sourceRoot":"","sources":["../../src/messaging/FencedOutbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAA2B,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAkBnG,MAAM,OAAO,YAAY;IACN,CAAC,CAAmB;IAErC,YAAY,IAAsB;QAChC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;IAChB,CAAC;IAEO,GAAG,CAAC,CAAS;QACnB,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,CACR,SAAiB,EACjB,UAAkB,EAClB,YAAoB,EACpB,MAA2B;QAE3B,MAAM,cAAc,GAAG,0BAA0B,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QAEzE,yEAAyE;QACzE,0CAA0C;QAC1C,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,sBAAsB,SAAS,gBAAgB,CAAC,CAAC;YAC1D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;QACtF,CAAC;QAED,0EAA0E;QAC1E,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC;YACzB,IAAI,CAAC,GAAG,CAAC,4CAA4C,SAAS,EAAE,CAAC,CAAC;YAClE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;QACtF,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC;QACpC,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,uBAAuB,YAAY,eAAe,KAAK,4BAA4B,SAAS,EAAE,CAAC,CAAC;YACzG,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,oBAAoB,EAAE,cAAc,EAAE,CAAC;QACzF,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,EAAE,CAAC;QACjB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,mBAAmB,SAAS,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9F,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC;QACnF,CAAC;QAED,8EAA8E;QAC9E,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;QACnE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAC3E,CAAC;CACF"}

package/dist/messaging/MessageProcessingLedger.d.ts

@@ -0,0 +1,105 @@
+/**
+ * MessageProcessingLedger — the no-loss / no-duplicate-reply guarantee (spec §8 G3a).
+ *
+ * A durable, SQLite-backed record of each inbound message's lifecycle:
+ *   received → processing → reply_committed → cursor_advanced
+ * keyed by the adapter's `dedupeKey(rawEvent)` (Telegram update_id, Slack
+ * event_id/client_msg_id). Rules:
+ *
+ *  - An event whose dedupeKey is already reply_committed/cursor_advanced is
+ *    NEVER acted on again — a redelivery (Telegram retry, Slack reconnect, or a
+ *    transfer-window overlap during a handoff) is recognized and dropped. This
+ *    is what makes "no duplicate replies" structural, not merely "only one
+ *    consumer".
+ *  - The ingress cursor advances ONLY on durable completion (cursor_advanced),
+ *    so a crash before completion replays the event (at-least-once) and the
+ *    ledger makes the replay a no-op-or-resume (exactly-once effect).
+ *  - Each transition is flushed to local SQLite synchronously on commit (WAL +
+ *    NORMAL), so a same-machine crash-restart never double-acts.
+ *  - A stuck `processing` entry past maxProcessingMs (old holder fenced
+ *    mid-turn) is re-runnable by the current holder from its stored input.
+ *
+ * Substrate is SQLite (the proven PendingRelayStore/CommitmentTracker path) —
+ * NOT a new ad-hoc JSON file and NOT a git-synced blob. Schema self-initializes
+ * on first access (no PostUpdateMigrator step needed). Per-agent-id isolation.
+ */
+export type LedgerState = 'received' | 'processing' | 'reply_committed' | 'cursor_advanced';
+export interface LedgerEntry {
+    dedupeKey: string;
+    platform: string;
+    topic: string | null;
+    state: LedgerState;
+    receivedAt: string;
+    processingStartedAt: string | null;
+    replyCommittedAt: string | null;
+    cursorAdvancedAt: string | null;
+    replyIdempotencyKey: string | null;
+    replyEpoch: number | null;
+    inputSnapshot: string | null;
+    attempts: number;
+}
+export declare function resolveMessageLedgerPath(stateDir: string, agentId: string): string;
+/**
+ * Deterministic outbound idempotency key — any machine re-running the same
+ * inbound event reproduces it identically (spec §8 G3a). Used so a failover
+ * re-send is recognized as the same reply.
+ */
+export declare function computeReplyIdempotencyKey(dedupeKey: string, replyIndex: number): string;
+export declare class MessageProcessingLedger {
+    private readonly db;
+    readonly path: string;
+    private constructor();
+    static open(agentId: string, stateDir: string): MessageProcessingLedger;
+    /** Open an in-memory ledger (tests). */
+    static openMemory(): MessageProcessingLedger;
+    /**
+     * Record an inbound event. Idempotent on dedupeKey (INSERT OR IGNORE).
+     * Returns whether this is the first time we've seen it + the current state.
+     * A caller seeing firstSeen:false with an acted-on state must DROP the event.
+     */
+    record(dedupeKey: string, opts: {
+        platform: string;
+        topic?: string | null;
+        input?: string;
+    }): {
+        firstSeen: boolean;
+        state: LedgerState;
+    };
+    /** Has this event already been acted on (reply committed or cursor advanced)? */
+    isActedOn(dedupeKey: string): boolean;
+    /**
+     * Claim an event for processing under the given fencing epoch. Returns false
+     * if it has already been acted on (drop). A stuck 'processing' entry can be
+     * re-claimed (the old holder was fenced); attempts is incremented.
+     */
+    beginProcessing(dedupeKey: string, epoch: number): boolean;
+    /**
+     * Commit that a reply was sent. Records the deterministic idempotency key and
+     * the fencing epoch it was committed under. Idempotent — committing twice is
+     * a no-op (the marker already exists).
+     */
+    commitReply(dedupeKey: string, replyIdempotencyKey: string, epoch: number): void;
+    /** Advance the ingress cursor — only call after durable reply commit. */
+    advanceCursor(dedupeKey: string): void;
+    /**
+     * Apply a reply_committed marker propagated from another machine (dual-medium
+     * marker, spec §8 G3a): if we have the entry and it's not yet acted on, mark
+     * it committed so a failover does not re-send. Creates the entry if unknown
+     * (the other machine saw it first).
+     */
+    applyRemoteReplyMarker(dedupeKey: string, opts: {
+        platform: string;
+        replyIdempotencyKey: string;
+        epoch: number;
+        topic?: string | null;
+    }): void;
+    /**
+     * Entries stuck in 'processing' past maxProcessingMs — eligible for re-run by
+     * the current lease holder from their stored input (spec §8 G3a). The old
+     * holder's abandoned output is discarded (the new holder re-executes).
+     */
+    reclaimStuck(maxProcessingMs: number, nowMs?: number): LedgerEntry[];
+    get(dedupeKey: string): LedgerEntry | null;
+    close(): void;
+}
+//# sourceMappingURL=MessageProcessingLedger.d.ts.map

package/dist/messaging/MessageProcessingLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageProcessingLedger.d.ts","sourceRoot":"","sources":["../../src/messaging/MessageProcessingLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAE5F,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,WAAW,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAoBD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAExF;AAED,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAuB;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB;IAYvE,wCAAwC;IACxC,MAAM,CAAC,UAAU,IAAI,uBAAuB;IAO5C;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG;QAC5F,SAAS,EAAE,OAAO,CAAC;QACnB,KAAK,EAAE,WAAW,CAAC;KACpB;IAYD,iFAAiF;IACjF,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAKrC;;;;OAIG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAc1D;;;;OAIG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAUhF,yEAAyE;IACzE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAStC;;;;;OAKG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAe9I;;;;OAIG;IACH,YAAY,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,WAAW,EAAE;IAahF,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAK1C,KAAK,IAAI,IAAI;CAGd"}