@claude-flow/cli 3.32.3 → 3.32.5

package/dist/src/funnel/promo.js

@@ -0,0 +1,144 @@
+/**
+ * Promo-row orchestrator — the single entry point the statusline hook calls
+ * (ADR-301). Applies, in order:
+ *
+ *   1. Control precedence (env / enterprise / user / project / remote) —
+ *      any disable → nothing renders, ever.
+ *   2. Environment gates — CI never sees funnel content.
+ *   3. Disclosure gate — an upgraded install shows the disclosure text
+ *      (with the disable instruction) before any message; promotional
+ *      content only after the grace window.
+ *   4. ADR-313 sponsored-downtime override — preempts everything below
+ *      while rate-limited (unconditional, not slot-based).
+ *   5. Local insight ticker (insights.ts) — a reserved 1-in-5 slot shows an
+ *      environment/task-aware suggestion (CVEs, uncommitted changes,
+ *      power-saver state) when one exists; otherwise falls through.
+ *   6. Rotation — 4:1 educational:promotional, 30-min promo repeat cap.
+ *
+ * Output is plain text (no ANSI — the renderer applies its own fixed
+ * style), ≤ 80 columns, already sanitized by the message pipeline.
+ */
+import { resolveFunnelEnabled } from './precedence.js';
+import { isCI } from './environment.js';
+import { getDisclosure, promoEligible, recordDisclosureShown, selectDisclosureMessage, } from './disclosure.js';
+import { clickTrackedUrl } from './attribution.js';
+import { selectMessage, ROTATION_SLOT_MS } from './rotation.js';
+import { recordFunnelEvent } from './events.js';
+import { getInstalledCliVersion } from '../init/helper-refresh.js';
+import { hasConsent } from './consent.js';
+import { readRateLimitStatus } from './rate-limit-notifier.js';
+import { selectLocalInsight } from './insights.js';
+/**
+ * ADR-313 priority override: when the user has manually flagged a Claude
+ * usage limit (ADR-312 Phase 0), preempt normal rotation with a dedicated
+ * CTA — same precedent as ADR-303's credit-exhaustion recovery surface.
+ * Two states depending on whether sponsored-downtime consent is granted:
+ *   - not yet enabled: an actionable CTA to enable it
+ *   - already enabled: a quiet status line confirming it's active
+ * Both message strings use the exact " · manage: " anchor the renderer
+ * already splits on (statusline-generator.ts getPromoRow) — no renderer
+ * change needed; the command portion renders bold, never as a fake link.
+ * Returns null when the rate-limit flag isn't set (no override).
+ */
+function getSponsoredDowntimeOverride(now) {
+    const status = readRateLimitStatus(now);
+    if (!status.limited)
+        return null;
+    if (hasConsent('sponsored-downtime')) {
+        return {
+            text: '⚡ Running on sponsored Cognitum capacity · manage: ruflo proxy sponsor-disable',
+            kind: 'promotional',
+        };
+    }
+    return {
+        text: '⚡ Free Cognitum capacity while you wait · manage: ruflo proxy sponsor-enable',
+        kind: 'promotional',
+    };
+}
+/** 1 in 5 slots, a different phase than rotation.ts's promo slot (slot%5==4)
+ * so the two never collide — reserved for a local insight IF one exists;
+ * otherwise falls through to the normal remote rotation untouched. This is
+ * the "ticker" cadence: insights appear periodically, never permanently
+ * take over the row, and never appear at all when nothing is actionable. */
+const INSIGHT_SLOT_MODULO = 5;
+const INSIGHT_SLOT_PHASE = 2;
+function isInsightSlot(now) {
+    const slot = Math.floor(now.getTime() / ROTATION_SLOT_MS);
+    return slot % INSIGHT_SLOT_MODULO === INSIGHT_SLOT_PHASE;
+}
+export function getFunnelPromo(ctx) {
+    const env = ctx.env ?? process.env;
+    const now = ctx.now ?? new Date();
+    if (!ctx.interactive)
+        return null;
+    if (isCI(env))
+        return null;
+    const decision = resolveFunnelEnabled(ctx.cwd ?? process.cwd(), env);
+    if (!decision.enabled)
+        return null;
+    const release = getInstalledCliVersion();
+    // Disclosure gate: never a message before the disclosure has been shown
+    // and its grace window has passed. The disclosure MESSAGE itself is now
+    // remote-sourced (ADR-311) — selectDisclosureMessage() returns null when
+    // the remote pool hasn't populated yet (cold start / outage), and per the
+    // "zero local promo content" design, null means show nothing this cycle.
+    const disclosure = getDisclosure();
+    if (disclosure.state === 'never_seen') {
+        const msg = selectDisclosureMessage(now);
+        if (!msg)
+            return null; // fail-closed: no remote disclosure cached yet
+        recordDisclosureShown(now);
+        recordFunnelEvent('disclosure_shown', 'statusline', release, { now, messageId: msg.id });
+        const url = msg.url ? clickTrackedUrl(msg.id, msg.url, {
+            medium: 'statusline', campaign: 'disclosure', content: msg.id, now,
+        }) : undefined;
+        return { text: msg.text, kind: 'disclosure', url };
+    }
+    if (!promoEligible(now)) {
+        if (disclosure.state === 'disclosed_enabled') {
+            const msg = selectDisclosureMessage(now);
+            if (!msg)
+                return null; // fail-closed
+            const url = msg.url ? clickTrackedUrl(msg.id, msg.url, {
+                medium: 'statusline', campaign: 'disclosure', content: msg.id, now,
+            }) : undefined;
+            return { text: msg.text, kind: 'disclosure', url };
+        }
+        return null; // disclosed_disabled is caught by precedence, but stay fail-closed
+    }
+    // ADR-313 priority override: a self-reported usage-limit flag preempts
+    // normal rotation, exactly the way ADR-303's credit-exhaustion recovery
+    // is designed to preempt it. Only reachable here — i.e. only after the
+    // disclosure invariant (ADR-301 "no promotional content before
+    // disclosure") has already been satisfied above.
+    const override = getSponsoredDowntimeOverride(now);
+    if (override)
+        return override;
+    // Local insight ticker: on its reserved 1-in-5 slot, show the highest-
+    // priority environment/task insight if one exists — CVEs pending,
+    // uncommitted changes, power-saver active, etc. (insights.ts). No
+    // insight this render (or no context passed) → fall straight through to
+    // the untouched remote rotation below, same as any other slot.
+    if (ctx.localInsights && isInsightSlot(now)) {
+        const insight = selectLocalInsight(ctx.localInsights);
+        if (insight)
+            return { text: insight.text, kind: 'insight' };
+    }
+    const msg = selectMessage(now, release);
+    if (!msg)
+        return null;
+    // Any message carrying a URL (educational tips included) routes through
+    // the server click-redirect so `promo_open` + coarse geo are captured
+    // before 302ing to the real target — click counting is uniform across
+    // the whole rotation, not just the promotional slot. If the click
+    // endpoint chain rejects the URL for any reason, fall back to the
+    // UTM-decorated direct link so the click still lands where it should.
+    let url;
+    if (msg.url) {
+        url = clickTrackedUrl(msg.id, msg.url, {
+            medium: 'statusline', campaign: msg.class, content: msg.id, now,
+        });
+    }
+    return { text: msg.text, kind: msg.class, url };
+}
+//# sourceMappingURL=promo.js.map

package/dist/src/funnel/rate-limit-notifier.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Rate-limit notifier — ADR-312 Phase 0 out-of-band signal path.
+ *
+ * Structural mirror of credit-notifier.ts. This is NOT automatic detection
+ * — ADR-312 established that Claude Code does not currently expose any way
+ * to detect its own usage-limit state from outside its process (verified
+ * against the actual installed CLI source, not assumed). This module is the
+ * MANUAL, self-reported alternative: the user tells ruflo they've hit a
+ * limit, ruflo remembers it, and the funnel promo row can react.
+ *
+ * State is cheap and durable:
+ *   ~/.ruflo/rate-limit-status.json = { limited: bool, since: ISO, cleared: ISO|null }
+ *
+ * A TTL (default 6h) auto-expires a forgotten flag so a stale manual mark
+ * doesn't linger indefinitely if the user forgets to clear it — Claude
+ * usage limits reset on hours-to-days cadences (five_hour / seven_day per
+ * ADR-312's grounded research), so 6h is a reasonable "the user probably
+ * forgot to clear this" bound without requiring per-type precision we
+ * don't have.
+ */
+export declare const RATE_LIMIT_STATUS_FILE = "rate-limit-status.json";
+/** Auto-expire a forgotten manual flag after 6h (see module doc). */
+export declare const RATE_LIMIT_TTL_MS: number;
+export interface RateLimitStatus {
+    limited: boolean;
+    since: string | null;
+    cleared: string | null;
+    /** ADR-314 §D1 — last time `limited` actually changed value; gates the toggle cooldown. */
+    lastToggleAt: string | null;
+}
+/** Read the current rate-limit status. Never throws. Applies the TTL. */
+export declare function readRateLimitStatus(now?: Date): RateLimitStatus;
+/**
+ * Mark as rate-limited — idempotent. Sets `since` on the first mark, leaves
+ * it alone on subsequent marks so the user sees a stable "since" timestamp
+ * until they clear it or the TTL expires. Refuses to flip false→true inside
+ * the ADR-314 §D1 cooldown window (returns false; a no-op re-mark of an
+ * already-true flag is unaffected — that's not a state change).
+ */
+export declare function markRateLimited(now?: Date): boolean;
+/**
+ * Clear rate-limited status. Called via `ruflo settings notices
+ * rate-limited --clear`, automatically by the TTL, or once a real Phase 1/2
+ * signal (ADR-312) confirms the limit has reset. Refuses to flip true→false
+ * inside the cooldown window (returns false); clearing an already-clear
+ * flag is always allowed (not a state change, and TTL auto-clear must never
+ * be blocked by a cooldown it didn't itself trigger).
+ */
+export declare function clearRateLimitStatus(now?: Date): boolean;
+/**
+ * User-facing single-line summary — plain text, no ANSI. Callers style it
+ * themselves. Returns null when not rate-limited (no surface).
+ */
+export declare function rateLimitNotice(now?: Date): string | null;
+//# sourceMappingURL=rate-limit-notifier.d.ts.map

package/dist/src/funnel/rate-limit-notifier.js

@@ -0,0 +1,102 @@
+/**
+ * Rate-limit notifier — ADR-312 Phase 0 out-of-band signal path.
+ *
+ * Structural mirror of credit-notifier.ts. This is NOT automatic detection
+ * — ADR-312 established that Claude Code does not currently expose any way
+ * to detect its own usage-limit state from outside its process (verified
+ * against the actual installed CLI source, not assumed). This module is the
+ * MANUAL, self-reported alternative: the user tells ruflo they've hit a
+ * limit, ruflo remembers it, and the funnel promo row can react.
+ *
+ * State is cheap and durable:
+ *   ~/.ruflo/rate-limit-status.json = { limited: bool, since: ISO, cleared: ISO|null }
+ *
+ * A TTL (default 6h) auto-expires a forgotten flag so a stale manual mark
+ * doesn't linger indefinitely if the user forgets to clear it — Claude
+ * usage limits reset on hours-to-days cadences (five_hour / seven_day per
+ * ADR-312's grounded research), so 6h is a reasonable "the user probably
+ * forgot to clear this" bound without requiring per-type precision we
+ * don't have.
+ */
+import { readStateJson, writeStateJson } from './state.js';
+import { cooldownActive } from './toggle-cooldown.js';
+export const RATE_LIMIT_STATUS_FILE = 'rate-limit-status.json';
+/** Auto-expire a forgotten manual flag after 6h (see module doc). */
+export const RATE_LIMIT_TTL_MS = 6 * 60 * 60 * 1000;
+/** Read the current rate-limit status. Never throws. Applies the TTL. */
+export function readRateLimitStatus(now = new Date()) {
+    const raw = readStateJson(RATE_LIMIT_STATUS_FILE);
+    const status = {
+        limited: raw?.limited ?? false,
+        since: raw?.since ?? null,
+        cleared: raw?.cleared ?? null,
+        lastToggleAt: raw?.lastToggleAt ?? null,
+    };
+    if (status.limited && status.since) {
+        const since = Date.parse(status.since);
+        if (!Number.isNaN(since) && now.getTime() - since >= RATE_LIMIT_TTL_MS) {
+            return { limited: false, since: status.since, cleared: now.toISOString(), lastToggleAt: status.lastToggleAt };
+        }
+    }
+    return status;
+}
+/**
+ * Mark as rate-limited — idempotent. Sets `since` on the first mark, leaves
+ * it alone on subsequent marks so the user sees a stable "since" timestamp
+ * until they clear it or the TTL expires. Refuses to flip false→true inside
+ * the ADR-314 §D1 cooldown window (returns false; a no-op re-mark of an
+ * already-true flag is unaffected — that's not a state change).
+ */
+export function markRateLimited(now = new Date()) {
+    const current = readRateLimitStatus(now);
+    if (current.limited && current.since)
+        return true; // already flagged, not a change
+    if (cooldownActive(current.lastToggleAt, now))
+        return false;
+    writeStateJson(RATE_LIMIT_STATUS_FILE, {
+        limited: true,
+        since: current.since ?? now.toISOString(),
+        cleared: null,
+        lastToggleAt: now.toISOString(),
+    });
+    return true;
+}
+/**
+ * Clear rate-limited status. Called via `ruflo settings notices
+ * rate-limited --clear`, automatically by the TTL, or once a real Phase 1/2
+ * signal (ADR-312) confirms the limit has reset. Refuses to flip true→false
+ * inside the cooldown window (returns false); clearing an already-clear
+ * flag is always allowed (not a state change, and TTL auto-clear must never
+ * be blocked by a cooldown it didn't itself trigger).
+ */
+export function clearRateLimitStatus(now = new Date()) {
+    const current = readRateLimitStatus(now);
+    if (!current.limited)
+        return true; // already clear, not a change
+    if (cooldownActive(current.lastToggleAt, now))
+        return false;
+    writeStateJson(RATE_LIMIT_STATUS_FILE, {
+        limited: false,
+        since: current.since,
+        cleared: now.toISOString(),
+        lastToggleAt: now.toISOString(),
+    });
+    return true;
+}
+/**
+ * User-facing single-line summary — plain text, no ANSI. Callers style it
+ * themselves. Returns null when not rate-limited (no surface).
+ */
+export function rateLimitNotice(now = new Date()) {
+    const status = readRateLimitStatus(now);
+    if (!status.limited)
+        return null;
+    const since = status.since ? Date.parse(status.since) : NaN;
+    if (Number.isNaN(since)) {
+        return 'Claude usage limit flagged · run: ruflo proxy sponsor-enable';
+    }
+    const ageMin = Math.max(0, Math.round((now.getTime() - since) / (60 * 1000)));
+    const when = ageMin < 1 ? 'just now' : ageMin < 60 ? `${ageMin}m ago` : `${Math.round(ageMin / 60)}h ago`;
+    return `Claude usage limit flagged (${when}) · run: ruflo proxy sponsor-enable`;
+}
+//# sourceMappingURL=rate-limit-notifier.js.map

package/dist/src/funnel/rotation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rotation scheduler — ADR-301 content ratio, enforced structurally.
+ *
+ *   - Educational: at least 4 of every 5 rotation slots.
+ *   - Promotional: at most 1 of every 5 slots (slot % 5 === 4), and only
+ *     when no promotion has shown in the last 30 minutes.
+ *   - Deterministic: selection is a pure function of (time slot, registry,
+ *     last-promo state) — no Math.random, so renders are reproducible and
+ *     the statusline cache can't skew the ratio.
+ */
+import type { FunnelMessage } from './types.js';
+/** One rotation slot — ADR-301 allows 15–30s; 20s sits inside the band. */
+export declare const ROTATION_SLOT_MS = 20000;
+/** The same promotion appears at most once every 30 minutes (ADR-301). */
+export declare const PROMO_REPEAT_CAP_MS: number;
+/** 1 promotional slot per 5 (ADR-301: ≤ 1 in 5 rotations). */
+export declare const PROMO_SLOT_MODULO = 5;
+export declare function selectMessage(now?: Date, release?: string): FunnelMessage | null;
+//# sourceMappingURL=rotation.d.ts.map

package/dist/src/funnel/rotation.js

@@ -0,0 +1,70 @@
+/**
+ * Rotation scheduler — ADR-301 content ratio, enforced structurally.
+ *
+ *   - Educational: at least 4 of every 5 rotation slots.
+ *   - Promotional: at most 1 of every 5 slots (slot % 5 === 4), and only
+ *     when no promotion has shown in the last 30 minutes.
+ *   - Deterministic: selection is a pure function of (time slot, registry,
+ *     last-promo state) — no Math.random, so renders are reproducible and
+ *     the statusline cache can't skew the ratio.
+ */
+import { MESSAGES, eligibleMessagesFromPools } from './messages.js';
+import { getRemoteMessages, refreshRemoteMessages } from './message-transport.js';
+import { readStateJson, writeStateJson } from './state.js';
+import { recordFunnelEvent } from './events.js';
+const ROTATION_FILE = 'funnel-rotation.json';
+/** One rotation slot — ADR-301 allows 15–30s; 20s sits inside the band. */
+export const ROTATION_SLOT_MS = 20_000;
+/** The same promotion appears at most once every 30 minutes (ADR-301). */
+export const PROMO_REPEAT_CAP_MS = 30 * 60 * 1000;
+/** 1 promotional slot per 5 (ADR-301: ≤ 1 in 5 rotations). */
+export const PROMO_SLOT_MODULO = 5;
+export function selectMessage(now = new Date(), release = 'unknown') {
+    // Kick a background refresh — never awaited, never blocks render. The
+    // remote pool becomes visible on subsequent selects once cached.
+    void refreshRemoteMessages();
+    // Merge: remote pool authoritative, in-code pool fallback (by id).
+    const pool = eligibleMessagesFromPools(MESSAGES, getRemoteMessages(), now);
+    const educational = pool.filter((m) => m.class === 'educational');
+    const promotional = pool.filter((m) => m.class === 'promotional');
+    if (educational.length === 0 && promotional.length === 0)
+        return null;
+    const slot = Math.floor(now.getTime() / ROTATION_SLOT_MS);
+    const promoSlot = slot % PROMO_SLOT_MODULO === PROMO_SLOT_MODULO - 1;
+    let selected = null;
+    if (promoSlot && promotional.length > 0 && promoCapClear(now)) {
+        selected = promotional[Math.floor(slot / PROMO_SLOT_MODULO) % promotional.length];
+        recordPromoShown(selected, now);
+    }
+    else if (educational.length > 0) {
+        selected = educational[slot % educational.length];
+    }
+    // Fire an impression event for whichever message was selected. Consent-gated
+    // (recordFunnelEvent no-ops without telemetry consent). Idempotency across
+    // renders in the same slot is handled by the same-slot deduplication in
+    // the events transport — we don't try to dedupe here because the slot
+    // math already returns the same id for the same slot, giving downstream
+    // aggregation a per-slot boolean.
+    if (selected) {
+        recordFunnelEvent('promo_impression', 'statusline', release, {
+            now, messageId: selected.id,
+        });
+    }
+    return selected;
+}
+function promoCapClear(now) {
+    const state = readStateJson(ROTATION_FILE);
+    if (!state?.lastPromoAt)
+        return true;
+    const last = Date.parse(state.lastPromoAt);
+    if (Number.isNaN(last))
+        return true;
+    return now.getTime() - last >= PROMO_REPEAT_CAP_MS;
+}
+function recordPromoShown(msg, now) {
+    writeStateJson(ROTATION_FILE, {
+        lastPromoAt: now.toISOString(),
+        lastPromoId: msg.id,
+    });
+}
+//# sourceMappingURL=rotation.js.map

package/dist/src/funnel/state.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Funnel state storage — user-level JSON files under ~/.ruflo (ADR-302/305).
+ *
+ * User-level (not project-level) so dismissals, consent, and disclosure
+ * persist across projects. Files are written 0600 and never committed.
+ * RUFLO_STATE_DIR overrides the directory (tests, unusual $HOME setups).
+ */
+export declare function funnelStateDir(): string;
+export declare function statePath(name: string): string;
+export declare function readStateJson<T>(name: string): T | null;
+export declare function writeStateJson(name: string, value: unknown): boolean;
+export declare function deleteStateFile(name: string): void;
+//# sourceMappingURL=state.d.ts.map

package/dist/src/funnel/state.js

@@ -0,0 +1,52 @@
+/**
+ * Funnel state storage — user-level JSON files under ~/.ruflo (ADR-302/305).
+ *
+ * User-level (not project-level) so dismissals, consent, and disclosure
+ * persist across projects. Files are written 0600 and never committed.
+ * RUFLO_STATE_DIR overrides the directory (tests, unusual $HOME setups).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+export function funnelStateDir() {
+    const override = process.env.RUFLO_STATE_DIR;
+    if (override && override.trim())
+        return override;
+    return path.join(os.homedir(), '.ruflo');
+}
+export function statePath(name) {
+    return path.join(funnelStateDir(), name);
+}
+export function readStateJson(name) {
+    try {
+        const raw = fs.readFileSync(statePath(name), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeStateJson(name, value) {
+    try {
+        const dir = funnelStateDir();
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const target = statePath(name);
+        // Write-then-rename so a crash never leaves a truncated state file.
+        const tmp = `${target}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(value, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        fs.renameSync(tmp, target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function deleteStateFile(name) {
+    try {
+        fs.unlinkSync(statePath(name));
+    }
+    catch {
+        // already absent — fine
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/src/funnel/toggle-cooldown.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared toggle cooldown — ADR-314 §D1.
+ *
+ * Self-reported flags (rate-limited, quota-low) have zero server-side
+ * verification (ADR-312's Phase 0 constraint carries over unchanged). A
+ * cooldown on how often the flag can actually CHANGE state is cheap,
+ * purely client-side friction against casual "always on" gaming or a
+ * scripted flip-flop loop — it does not stop a determined abuser (that
+ * needs the per-identity server-side quota ADR-314 flags as the real fix),
+ * but it raises the bar above "one line in a shell script."
+ */
+export declare const TOGGLE_COOLDOWN_MS: number;
+/** True when `lastToggleAt` is within the cooldown window of `now`. */
+export declare function cooldownActive(lastToggleAt: string | null, now: Date): boolean;
+/** Minutes remaining in the cooldown window — for user-facing messages. */
+export declare function cooldownRemainingMin(lastToggleAt: string | null, now: Date): number;
+//# sourceMappingURL=toggle-cooldown.d.ts.map

package/dist/src/funnel/toggle-cooldown.js

@@ -0,0 +1,32 @@
+/**
+ * Shared toggle cooldown — ADR-314 §D1.
+ *
+ * Self-reported flags (rate-limited, quota-low) have zero server-side
+ * verification (ADR-312's Phase 0 constraint carries over unchanged). A
+ * cooldown on how often the flag can actually CHANGE state is cheap,
+ * purely client-side friction against casual "always on" gaming or a
+ * scripted flip-flop loop — it does not stop a determined abuser (that
+ * needs the per-identity server-side quota ADR-314 flags as the real fix),
+ * but it raises the bar above "one line in a shell script."
+ */
+export const TOGGLE_COOLDOWN_MS = 10 * 60 * 1000;
+/** True when `lastToggleAt` is within the cooldown window of `now`. */
+export function cooldownActive(lastToggleAt, now) {
+    if (!lastToggleAt)
+        return false;
+    const t = Date.parse(lastToggleAt);
+    if (Number.isNaN(t))
+        return false;
+    return now.getTime() - t < TOGGLE_COOLDOWN_MS;
+}
+/** Minutes remaining in the cooldown window — for user-facing messages. */
+export function cooldownRemainingMin(lastToggleAt, now) {
+    if (!lastToggleAt)
+        return 0;
+    const t = Date.parse(lastToggleAt);
+    if (Number.isNaN(t))
+        return 0;
+    const remainingMs = TOGGLE_COOLDOWN_MS - (now.getTime() - t);
+    return Math.max(0, Math.ceil(remainingMs / (60 * 1000)));
+}
+//# sourceMappingURL=toggle-cooldown.js.map

package/dist/src/funnel/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Funnel type definitions — ADR-301..310.
+ *
+ * The funnel is the ruflo → Cognitum lifecycle system: promotional status
+ * surface (ADR-301), post-init enrollment (ADR-302), credit-exhaustion
+ * recovery (ADR-303), governed by consent receipts (ADR-302), control
+ * precedence (ADR-305), and the governance/privacy rules of ADR-309.
+ *
+ * Everything in this module is local-only: no code path here performs
+ * network I/O. Events are queued locally and only when telemetry consent
+ * is granted (ADR-308 failure policy: telemetry never blocks the CLI).
+ */
+export type FunnelDisclosureState = 'never_seen' | 'disclosed_enabled' | 'disclosed_disabled';
+export interface DisclosureRecord {
+    state: FunnelDisclosureState;
+    /** ISO timestamp of the first render of the disclosure text. */
+    firstShownAt: string | null;
+}
+export type FunnelMessageClass = 'educational' | 'promotional' | 'disclosure';
+export interface FunnelMessage {
+    id: string;
+    schemaVersion: 1;
+    text: string;
+    /** Optional link; must pass the in-code host allowlist or the message is dropped. */
+    url?: string;
+    class: FunnelMessageClass;
+    /** ISO timestamp; expired messages leave the rotation immediately. */
+    expiresAt?: string;
+}
+export interface PromoRow {
+    text: string;
+    kind: 'disclosure' | FunnelMessageClass | 'insight';
+    url?: string;
+}
+export type ConsentDomain = 'account' | 'proxy-install' | 'telemetry' | 'cloud-routing' | 'hosted-memory' | 'sponsored-downtime' | 'power-saver' | 'training-data-sharing' | 'advisor-tips' | 'rev-share-payout' | 'spinner-verbs' | 'company-announcements';
+export interface ConsentReceipt {
+    granted: boolean;
+    policyVersion: number;
+    /** ISO timestamp of the decision; null = never asked. */
+    at: string | null;
+    surface: string | null;
+}
+export type ConsentFile = Partial<Record<ConsentDomain, ConsentReceipt>>;
+/** Bump when the meaning of a consent domain changes materially (ADR-302). */
+export declare const CONSENT_POLICY_VERSION = 1;
+export type PayoutEnrollmentPolicyVersion = 1;
+/**
+ * Local mirror of enrollment state issued by the funnel.ruv.io backend.
+ * The `enrollment_token` is opaque — the client never introspects it.
+ */
+export interface PayoutEnrollment {
+    enrollment_token: string;
+    enrolled_at: string;
+    payout_account_last4: string;
+    kyc_status: 'verified' | 'pending' | 'failed';
+    policy_version: PayoutEnrollmentPolicyVersion;
+}
+export type FunnelDecisionSource = 'env' | 'enterprise-policy' | 'user-config' | 'project-config' | 'package-default' | 'remote-policy' | 'disclosure-declined';
+export interface FunnelEnabledDecision {
+    enabled: boolean;
+    decidedBy: FunnelDecisionSource;
+}
+export declare enum CreditErrorCode {
+    /** Cognitum ledger says balance is spent — the ONLY funnel trigger. */
+    COGNITUM_CREDIT_EXHAUSTED = "COGNITUM_CREDIT_EXHAUSTED",
+    /** Upstream provider's own quota, not Cognitum credits. */
+    PROVIDER_QUOTA_EXHAUSTED = "PROVIDER_QUOTA_EXHAUSTED",
+    PROVIDER_RATE_LIMITED = "PROVIDER_RATE_LIMITED",
+    AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED",
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+}
+export interface NormalizedCreditError {
+    code: CreditErrorCode | null;
+    /** 1 only when an explicit machine-readable provider code mapped; else 0. */
+    confidence: 0 | 1;
+    retryable: boolean;
+    /** Original provider error, preserved verbatim for --verbose paths. */
+    cause?: unknown;
+}
+export type FunnelEventName = 'disclosure_shown' | 'funnel_disabled' | 'signup_opened' | 'account_created' | 'proxy_activated' | 'promo_impression' | 'promo_open' | 'sponsor_mode_enabled' | 'sponsor_mode_disabled' | 'sponsor_capacity_exhausted' | 'power_saver_enabled' | 'power_saver_disabled' | 'toggle_cooldown_blocked' | 'training_share_enabled' | 'training_share_disabled' | 'advisor_tip_enabled' | 'advisor_tip_disabled';
+export type FunnelSurface = 'statusline' | 'init' | 'credit_exhaustion';
+export interface FunnelEvent {
+    schemaVersion: 1;
+    event: FunnelEventName;
+    surface: FunnelSurface;
+    release: string;
+    region?: string;
+    pseudonymousId?: string;
+    /**
+     * Message id for promo_impression / promo_open — lets the analyst
+     * attribute clicks + impressions to a specific rotation entry without
+     * carrying prompt/URL/PII data.
+     */
+    messageId?: string;
+    /** Daily bucket ("2026-07-10") — full timestamps are never recorded. */
+    timestampBucket: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/funnel/types.js

@@ -0,0 +1,26 @@
+/**
+ * Funnel type definitions — ADR-301..310.
+ *
+ * The funnel is the ruflo → Cognitum lifecycle system: promotional status
+ * surface (ADR-301), post-init enrollment (ADR-302), credit-exhaustion
+ * recovery (ADR-303), governed by consent receipts (ADR-302), control
+ * precedence (ADR-305), and the governance/privacy rules of ADR-309.
+ *
+ * Everything in this module is local-only: no code path here performs
+ * network I/O. Events are queued locally and only when telemetry consent
+ * is granted (ADR-308 failure policy: telemetry never blocks the CLI).
+ */
+/** Bump when the meaning of a consent domain changes materially (ADR-302). */
+export const CONSENT_POLICY_VERSION = 1;
+// ─── ADR-303: credit error taxonomy ─────────────────────────────────────────
+export var CreditErrorCode;
+(function (CreditErrorCode) {
+    /** Cognitum ledger says balance is spent — the ONLY funnel trigger. */
+    CreditErrorCode["COGNITUM_CREDIT_EXHAUSTED"] = "COGNITUM_CREDIT_EXHAUSTED";
+    /** Upstream provider's own quota, not Cognitum credits. */
+    CreditErrorCode["PROVIDER_QUOTA_EXHAUSTED"] = "PROVIDER_QUOTA_EXHAUSTED";
+    CreditErrorCode["PROVIDER_RATE_LIMITED"] = "PROVIDER_RATE_LIMITED";
+    CreditErrorCode["AUTHENTICATION_FAILED"] = "AUTHENTICATION_FAILED";
+    CreditErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+})(CreditErrorCode || (CreditErrorCode = {}));
+//# sourceMappingURL=types.js.map