@claude-flow/cli 3.32.3 → 3.32.4

package/dist/src/funnel/disclosure.js

@@ -0,0 +1,109 @@
+/**
+ * Existing-install disclosure gate — ADR-301, amended by ADR-311 to source
+ * the disclosure MESSAGE itself from the remote feed rather than hardcoding
+ * it in the CLI. Everything about WHETHER/WHEN to show a disclosure stays
+ * local (state machine below); everything about WHAT it says comes from
+ * the same remote pool as tips/promos, validated through the identical
+ * ADR-301 content pipeline (isValidMessage in messages.ts).
+ *
+ * Invariants (release-blocking, tested):
+ *   - No promotional content before disclosure.
+ *   - The manage instruction appears in the disclosure text itself.
+ *   - Shown once per user (user-level receipt), not once per project.
+ *   - Declining disables all funnel surfaces (enforced in precedence.ts).
+ *   - Fail-closed: if the remote feed has never successfully populated a
+ *     disclosure-class message, there is nothing to show — no local
+ *     fallback text exists (ADR-311 "zero local promo content").
+ *
+ * The disclosure text stays on the promo row for a grace window after its
+ * first render so a single flash can't count as "the user was told"; only
+ * after the window do promotional messages become eligible.
+ */
+import { readStateJson, writeStateJson } from './state.js';
+import { getRemoteMessages } from './message-transport.js';
+const DISCLOSURE_FILE = 'funnel-disclosure.json';
+/** How long the disclosure text keeps the row before promo becomes eligible. */
+export const DISCLOSURE_GRACE_MS = 24 * 60 * 60 * 1000; // 24h
+// One disclosure variant per 5-minute wall-clock slot. Longer than the
+// 20-second rotation cadence so a user watching the statusline sees the
+// same variant long enough to read it, but short enough that a fresh
+// session gets a different one than the previous one did.
+export const DISCLOSURE_ROTATION_SLOT_MS = 5 * 60 * 1000;
+/** Remote-cached messages tagged class==='disclosure' — the only source. */
+function getDisclosureMessagePool() {
+    return getRemoteMessages().filter((m) => m.class === 'disclosure');
+}
+/**
+ * Deterministic slot-based selection over the remote disclosure pool — no
+ * RNG so the choice is reproducible for a given wall-clock instant. Returns
+ * null when the pool is empty (cold start before first fetch, or the remote
+ * feed is unreachable) — the caller must treat null as "show nothing".
+ */
+export function selectDisclosureMessage(now = new Date()) {
+    const pool = getDisclosureMessagePool();
+    if (pool.length === 0)
+        return null;
+    const slot = Math.floor(now.getTime() / DISCLOSURE_ROTATION_SLOT_MS);
+    return pool[slot % pool.length];
+}
+export function getDisclosure() {
+    const rec = readStateJson(DISCLOSURE_FILE);
+    if (rec && isValidState(rec.state))
+        return rec;
+    return { state: 'never_seen', firstShownAt: null };
+}
+function isValidState(s) {
+    return s === 'never_seen' || s === 'disclosed_enabled' || s === 'disclosed_disabled';
+}
+/** Record that the disclosure text was rendered (idempotent). */
+export function recordDisclosureShown(now = new Date()) {
+    const current = getDisclosure();
+    if (current.state !== 'never_seen')
+        return current;
+    const rec = { state: 'disclosed_enabled', firstShownAt: now.toISOString() };
+    writeStateJson(DISCLOSURE_FILE, rec);
+    return rec;
+}
+/** User explicitly declined (e.g. `ruflo funnel disable`). */
+export function recordDisclosureDeclined(now = new Date()) {
+    const current = getDisclosure();
+    const rec = {
+        state: 'disclosed_disabled',
+        firstShownAt: current.firstShownAt ?? now.toISOString(),
+    };
+    writeStateJson(DISCLOSURE_FILE, rec);
+    return rec;
+}
+/** Re-enable after a prior decline (explicit user action only). */
+export function recordDisclosureReenabled(now = new Date()) {
+    const rec = { state: 'disclosed_enabled', firstShownAt: now.toISOString() };
+    writeStateJson(DISCLOSURE_FILE, rec);
+    return rec;
+}
+// Explicit user acknowledgement — bypasses the 24h grace so rotation starts
+// on the next render. The grace window's purpose is anti-flash (a single
+// glance can't count as "the user was told"); an explicit CLI action IS the
+// user saying they were told, so backdating firstShownAt past the window is
+// the correct semantics — not a policy hole. Stamps 1s past grace to avoid
+// clock-skew edge cases where now-grace lands exactly on the boundary.
+export function recordDisclosureAccepted(now = new Date()) {
+    const backdated = new Date(now.getTime() - DISCLOSURE_GRACE_MS - 1000);
+    const rec = { state: 'disclosed_enabled', firstShownAt: backdated.toISOString() };
+    writeStateJson(DISCLOSURE_FILE, rec);
+    return rec;
+}
+/**
+ * Whether promotional/educational messages may render. True only after the
+ * disclosure was shown AND its grace window has elapsed. While the window is
+ * open the row must carry the disclosure text itself.
+ */
+export function promoEligible(now = new Date()) {
+    const rec = getDisclosure();
+    if (rec.state !== 'disclosed_enabled' || !rec.firstShownAt)
+        return false;
+    const first = Date.parse(rec.firstShownAt);
+    if (Number.isNaN(first))
+        return false;
+    return now.getTime() - first >= DISCLOSURE_GRACE_MS;
+}
+//# sourceMappingURL=disclosure.js.map

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

@@ -0,0 +1,36 @@
+/**
+ * Post-initialization capability enrollment — ADR-302.
+ *
+ * One-time, non-blocking, skippable. Gates, all of which must pass:
+ *   - interactive TTY (never in CI / piped / automation)
+ *   - not skipped via --no-signup
+ *   - funnel enabled under the ADR-305 precedence chain
+ *   - never shown before (user-level record, not per-project)
+ *
+ * Accepting authorizes exactly ONE thing: a pointer to `ruflo auth login`.
+ * It does not install the proxy, does not enable telemetry, and does not
+ * enable cloud routing (separate consent domains — ADR-302). The enrollment
+ * outcome never affects init's exit code.
+ */
+interface EnrollmentRecord {
+    shownAt: string;
+    outcome: 'accepted' | 'skipped';
+}
+export declare function getEnrollmentRecord(): EnrollmentRecord | null;
+export declare const ENROLLMENT_SCREEN: string;
+export declare const ENROLLMENT_SKIP_TEXT = "You can enable later:\n  ruflo auth login";
+export interface EnrollmentGateContext {
+    noSignup: boolean;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** All ADR-302 gates. Pure check — does not write state. */
+export declare function shouldOfferEnrollment(ctx: EnrollmentGateContext): boolean;
+/**
+ * Record the user's decision. Both accept and skip are terminal — the
+ * prompt never reappears (ADR-302). Accepting records the `account`
+ * consent receipt; skipping records the decline.
+ */
+export declare function recordEnrollmentOutcome(accepted: boolean, now?: Date): void;
+export {};
+//# sourceMappingURL=enrollment.d.ts.map

package/dist/src/funnel/enrollment.js

@@ -0,0 +1,64 @@
+/**
+ * Post-initialization capability enrollment — ADR-302.
+ *
+ * One-time, non-blocking, skippable. Gates, all of which must pass:
+ *   - interactive TTY (never in CI / piped / automation)
+ *   - not skipped via --no-signup
+ *   - funnel enabled under the ADR-305 precedence chain
+ *   - never shown before (user-level record, not per-project)
+ *
+ * Accepting authorizes exactly ONE thing: a pointer to `ruflo auth login`.
+ * It does not install the proxy, does not enable telemetry, and does not
+ * enable cloud routing (separate consent domains — ADR-302). The enrollment
+ * outcome never affects init's exit code.
+ */
+import { isCI, isInteractive } from './environment.js';
+import { resolveFunnelEnabled } from './precedence.js';
+import { recordConsent } from './consent.js';
+import { readStateJson, writeStateJson } from './state.js';
+const ENROLLMENT_FILE = 'enrollment.json';
+export function getEnrollmentRecord() {
+    return readStateJson(ENROLLMENT_FILE);
+}
+export const ENROLLMENT_SCREEN = [
+    '────────────────────────────',
+    'Unlock additional capabilities?',
+    '',
+    '  ✓ Local Meta LLM Proxy',
+    '  ✓ Multi-model routing',
+    '  ✓ Hosted memory',
+    '  ✓ Enterprise rate limits',
+    '  ✓ Premium agents',
+    '  ✓ Cloud synchronization',
+    '',
+    'Free account: https://cognitum.one',
+].join('\n');
+export const ENROLLMENT_SKIP_TEXT = 'You can enable later:\n  ruflo auth login';
+/** All ADR-302 gates. Pure check — does not write state. */
+export function shouldOfferEnrollment(ctx) {
+    const env = ctx.env ?? process.env;
+    if (ctx.noSignup)
+        return false;
+    if (isCI(env))
+        return false;
+    if (!isInteractive())
+        return false;
+    if (!resolveFunnelEnabled(ctx.cwd ?? process.cwd(), env).enabled)
+        return false;
+    if (getEnrollmentRecord() !== null)
+        return false; // one-time only
+    return true;
+}
+/**
+ * Record the user's decision. Both accept and skip are terminal — the
+ * prompt never reappears (ADR-302). Accepting records the `account`
+ * consent receipt; skipping records the decline.
+ */
+export function recordEnrollmentOutcome(accepted, now = new Date()) {
+    writeStateJson(ENROLLMENT_FILE, {
+        shownAt: now.toISOString(),
+        outcome: accepted ? 'accepted' : 'skipped',
+    });
+    recordConsent('account', accepted, 'post-init', now);
+}
+//# sourceMappingURL=enrollment.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * Environment gates for funnel surfaces (ADR-301/302).
+ *
+ * CI and non-interactive environments never see funnel content; reduced
+ * motion / screen readers get static text only (which is all the funnel
+ * renders anyway — there is deliberately no animation path in this module).
+ */
+export declare function isCI(env?: NodeJS.ProcessEnv): boolean;
+export declare function isInteractive(): boolean;
+/**
+ * Statusline invocations are spawned by an interactive host (Claude Code)
+ * with piped stdio, so isTTY is false there even though the session is
+ * interactive. Surfaces pass their own interactivity signal; this helper is
+ * the strict check used by directly-invoked prompts (init enrollment).
+ */
+export declare function reducedMotion(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=environment.d.ts.map

package/dist/src/funnel/environment.js

@@ -0,0 +1,39 @@
+/**
+ * Environment gates for funnel surfaces (ADR-301/302).
+ *
+ * CI and non-interactive environments never see funnel content; reduced
+ * motion / screen readers get static text only (which is all the funnel
+ * renders anyway — there is deliberately no animation path in this module).
+ */
+const CI_ENV_VARS = [
+    'CI',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'CIRCLECI',
+    'TRAVIS',
+    'BUILDKITE',
+    'JENKINS_URL',
+    'TEAMCITY_VERSION',
+    'TF_BUILD', // Azure Pipelines
+];
+export function isCI(env = process.env) {
+    return CI_ENV_VARS.some((v) => {
+        const val = env[v];
+        return val !== undefined && val !== '' && val !== '0' && val.toLowerCase?.() !== 'false';
+    });
+}
+export function isInteractive() {
+    return Boolean(process.stdout.isTTY && process.stdin.isTTY);
+}
+/**
+ * Statusline invocations are spawned by an interactive host (Claude Code)
+ * with piped stdio, so isTTY is false there even though the session is
+ * interactive. Surfaces pass their own interactivity signal; this helper is
+ * the strict check used by directly-invoked prompts (init enrollment).
+ */
+export function reducedMotion(env = process.env) {
+    return Boolean(env.NO_COLOR !== undefined ||
+        env.RUFLO_REDUCED_MOTION === '1' ||
+        env.TERM === 'dumb');
+}
+//# sourceMappingURL=environment.js.map

package/dist/src/funnel/event-transport.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Event transport — batches the local funnel event queue and posts it to the
+ * Cognitum analytics Cloud Function (ADR-308 endpoint contract).
+ *
+ * Design discipline (ADR-308 client failure policy — all normative):
+ *   1. Telemetry never blocks the CLI. Every network call is best-effort,
+ *      capped by a short timeout, and swallows every error path.
+ *   2. Events are LOCAL FIRST. The queue in `events.ts` accumulates
+ *      regardless of API reachability. This transport is the flush layer.
+ *   3. Idempotency: every batch carries a UUIDv4 idempotency key so a retry
+ *      never double-counts (ADR-308 idempotent-batches invariant).
+ *   4. Exponential backoff on transient failures. Successful flushes stamp
+ *      a "last flush" timestamp so we don't hammer the API each render.
+ *   5. Consent-gated. Zero network activity when telemetry consent is off.
+ *   6. Bounded. Never send more than MAX_BATCH events at once, so a large
+ *      backlog doesn't blow the endpoint request-size limit.
+ *   7. Credit-exhaustion detection. If the endpoint replies 402 (Payment
+ *      Required) or the body carries the ADR-303
+ *      `COGNITUM_CREDIT_EXHAUSTED` code, we surface via `credit-notifier.ts`
+ *      — the same recovery UX ADR-303 already ships.
+ */
+/**
+ * Default endpoint — the ruflo-funnel-analytics endpoint on the ruv.io
+ * domain, mapped via Cloud Run domain mapping to the cognitum-analytics
+ * Cloud Function on cognitum-20260110. Overridable by env for staging or
+ * self-hosted deploys. The domain choice is deliberate: an rUv-authored
+ * OSS project's telemetry endpoint belongs on rUv's own domain, not on
+ * cognitum.one — that keeps the CLI attribution honest.
+ */
+export declare const DEFAULT_ENDPOINT: string;
+/** Cap per POST — server enforces its own limits too; this is a safety net. */
+export declare const MAX_BATCH = 100;
+/** Min interval between flushes (ms). Rate limits the client from within. */
+export declare const MIN_FLUSH_INTERVAL_MS = 60000;
+/** POST timeout — telemetry must not stall the CLI. */
+export declare const FLUSH_TIMEOUT_MS = 4000;
+/**
+ * Best-effort flush of the local event queue to the endpoint. Returns a
+ * summary the CLI can log at --verbose; the caller should never fail on it.
+ */
+export declare function flushEvents(opts?: {
+    endpoint?: string;
+    release?: string;
+    force?: boolean;
+    now?: Date;
+}): Promise<{
+    flushed: number;
+    skipped: string | null;
+    status?: number;
+}>;
+//# sourceMappingURL=event-transport.d.ts.map

package/dist/src/funnel/event-transport.js

@@ -0,0 +1,199 @@
+/**
+ * Event transport — batches the local funnel event queue and posts it to the
+ * Cognitum analytics Cloud Function (ADR-308 endpoint contract).
+ *
+ * Design discipline (ADR-308 client failure policy — all normative):
+ *   1. Telemetry never blocks the CLI. Every network call is best-effort,
+ *      capped by a short timeout, and swallows every error path.
+ *   2. Events are LOCAL FIRST. The queue in `events.ts` accumulates
+ *      regardless of API reachability. This transport is the flush layer.
+ *   3. Idempotency: every batch carries a UUIDv4 idempotency key so a retry
+ *      never double-counts (ADR-308 idempotent-batches invariant).
+ *   4. Exponential backoff on transient failures. Successful flushes stamp
+ *      a "last flush" timestamp so we don't hammer the API each render.
+ *   5. Consent-gated. Zero network activity when telemetry consent is off.
+ *   6. Bounded. Never send more than MAX_BATCH events at once, so a large
+ *      backlog doesn't blow the endpoint request-size limit.
+ *   7. Credit-exhaustion detection. If the endpoint replies 402 (Payment
+ *      Required) or the body carries the ADR-303
+ *      `COGNITUM_CREDIT_EXHAUSTED` code, we surface via `credit-notifier.ts`
+ *      — the same recovery UX ADR-303 already ships.
+ */
+import * as fs from 'fs';
+import * as https from 'https';
+import { URL as NodeUrl } from 'url';
+import { randomUUID } from 'crypto';
+import { hasConsent } from './consent.js';
+import { readStateJson, statePath, writeStateJson } from './state.js';
+import { markCreditExhausted } from './credit-notifier.js';
+const EVENTS_FILE = 'funnel-events.jsonl';
+const FLUSH_STATE_FILE = 'funnel-events-flush.json';
+/**
+ * Default endpoint — the ruflo-funnel-analytics endpoint on the ruv.io
+ * domain, mapped via Cloud Run domain mapping to the cognitum-analytics
+ * Cloud Function on cognitum-20260110. Overridable by env for staging or
+ * self-hosted deploys. The domain choice is deliberate: an rUv-authored
+ * OSS project's telemetry endpoint belongs on rUv's own domain, not on
+ * cognitum.one — that keeps the CLI attribution honest.
+ */
+export const DEFAULT_ENDPOINT = process.env.RUFLO_FUNNEL_EVENTS_ENDPOINT ?? 'https://funnel.ruv.io/v1/events';
+/** Cap per POST — server enforces its own limits too; this is a safety net. */
+export const MAX_BATCH = 100;
+/** Min interval between flushes (ms). Rate limits the client from within. */
+export const MIN_FLUSH_INTERVAL_MS = 60_000; // 1 min
+/** POST timeout — telemetry must not stall the CLI. */
+export const FLUSH_TIMEOUT_MS = 4_000;
+/** Read the current flush bookkeeping state (never throws). */
+function readFlushState() {
+    const raw = readStateJson(FLUSH_STATE_FILE);
+    return {
+        lastFlushAt: raw?.lastFlushAt ?? null,
+        consecutiveFailures: raw?.consecutiveFailures ?? 0,
+        lastError: raw?.lastError,
+    };
+}
+/** Persist flush bookkeeping. Never throws. */
+function writeFlushState(state) {
+    writeStateJson(FLUSH_STATE_FILE, state);
+}
+/** Read the local event queue as JSON lines. Returns [] when absent. */
+function readQueue() {
+    try {
+        const raw = fs.readFileSync(statePath(EVENTS_FILE), 'utf-8');
+        return raw
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((x) => x !== null);
+    }
+    catch {
+        return [];
+    }
+}
+/** Overwrite the local queue with the survivors (events we didn't flush). */
+function writeQueue(events) {
+    try {
+        const body = events.length === 0 ? '' : events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+        fs.writeFileSync(statePath(EVENTS_FILE), body, { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch {
+        /* telemetry must never block */
+    }
+}
+/** Exponential backoff — cap at 30 minutes. */
+function backoffElapsed(state, now) {
+    if (!state.lastFlushAt)
+        return true;
+    const last = Date.parse(state.lastFlushAt);
+    if (Number.isNaN(last))
+        return true;
+    const base = MIN_FLUSH_INTERVAL_MS;
+    const factor = Math.min(2 ** state.consecutiveFailures, 30); // cap at 30x → ~30 min
+    const nextAllowed = last + base * factor;
+    return now.getTime() >= nextAllowed;
+}
+/**
+ * POST a batch to the endpoint. Resolves to { ok, status } — never rejects.
+ * Kept internal so callers can't hand it a URL that dodges the allowlist.
+ */
+function postBatch(endpoint, batch) {
+    return new Promise((resolve) => {
+        let target;
+        try {
+            target = new NodeUrl(endpoint);
+        }
+        catch {
+            resolve({ ok: false, status: 0, body: 'bad-endpoint' });
+            return;
+        }
+        if (target.protocol !== 'https:') {
+            resolve({ ok: false, status: 0, body: 'non-https-endpoint' });
+            return;
+        }
+        const body = JSON.stringify(batch);
+        const req = https.request({
+            hostname: target.hostname,
+            port: target.port || 443,
+            path: target.pathname + target.search,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(body),
+                'Idempotency-Key': batch.batchId,
+                'User-Agent': `ruflo-funnel/${batch.release}`,
+            },
+        }, (res) => {
+            let chunks = '';
+            res.setEncoding('utf-8');
+            res.on('data', (chunk) => { chunks += chunk; });
+            res.on('end', () => {
+                const status = res.statusCode ?? 0;
+                resolve({ ok: status >= 200 && status < 300, status, body: chunks });
+            });
+        });
+        req.setTimeout(FLUSH_TIMEOUT_MS, () => {
+            req.destroy();
+            resolve({ ok: false, status: 0, body: 'timeout' });
+        });
+        req.on('error', (err) => resolve({ ok: false, status: 0, body: String(err) }));
+        req.write(body);
+        req.end();
+    });
+}
+/**
+ * Best-effort flush of the local event queue to the endpoint. Returns a
+ * summary the CLI can log at --verbose; the caller should never fail on it.
+ */
+export async function flushEvents(opts) {
+    const now = opts?.now ?? new Date();
+    const endpoint = opts?.endpoint ?? DEFAULT_ENDPOINT;
+    if (!hasConsent('telemetry'))
+        return { flushed: 0, skipped: 'no-consent' };
+    const state = readFlushState();
+    if (!opts?.force && !backoffElapsed(state, now)) {
+        return { flushed: 0, skipped: 'backoff' };
+    }
+    const queue = readQueue();
+    if (queue.length === 0) {
+        // Nothing to send — record the check anyway so we don't retry every render.
+        writeFlushState({ ...state, lastFlushAt: now.toISOString() });
+        return { flushed: 0, skipped: 'empty-queue' };
+    }
+    const batchEvents = queue.slice(0, MAX_BATCH);
+    const batch = {
+        batchId: randomUUID(),
+        events: batchEvents,
+        release: opts?.release ?? 'unknown',
+        emittedAt: now.toISOString(),
+    };
+    const res = await postBatch(endpoint, batch);
+    // Credit-exhaustion detection (ADR-303 route in).
+    //   402 Payment Required  → out of Cognitum credits.
+    //   Body carrying the exact ADR-303 machine-readable code → same.
+    if (res.status === 402 || (typeof res.body === 'string' && res.body.includes('COGNITUM_CREDIT_EXHAUSTED'))) {
+        markCreditExhausted(now);
+    }
+    if (res.ok) {
+        // Drop the sent events; keep survivors.
+        writeQueue(queue.slice(batchEvents.length));
+        writeFlushState({
+            lastFlushAt: now.toISOString(),
+            consecutiveFailures: 0,
+        });
+        return { flushed: batchEvents.length, skipped: null, status: res.status };
+    }
+    writeFlushState({
+        lastFlushAt: now.toISOString(),
+        consecutiveFailures: state.consecutiveFailures + 1,
+        lastError: `HTTP ${res.status}`,
+    });
+    return { flushed: 0, skipped: `transport-failed`, status: res.status };
+}
+//# sourceMappingURL=event-transport.js.map

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

@@ -0,0 +1,42 @@
+/**
+ * Funnel events — ADR-305 attribution / ADR-309 constrained schema.
+ *
+ * LOCAL-ONLY by design: this module performs no network I/O. Events are
+ * appended to a bounded local queue only when the telemetry consent domain
+ * is granted (ADR-302). Server-side ingestion (POST /v1/events, ADR-308)
+ * is a separate opt-in transport that does not exist in this build — until
+ * it does, the queue is simply a bounded local record the user can inspect
+ * and delete.
+ *
+ * Constraints enforced here, permanently (ADR-309): closed event set, daily
+ * timestamp buckets (never full timestamps), no raw prompts/commands/paths/
+ * repo names — the schema has no field that could carry them.
+ */
+import type { FunnelEventName, FunnelSurface } from './types.js';
+/**
+ * Lazily created pseudonymous funnel ID — random UUID, derived from nothing
+ * (no hardware, account, email, or path). Exists only when attribution
+ * consent (telemetry domain) is granted; deleted on opt-out.
+ */
+export declare function getFunnelId(now?: Date): string | null;
+/** Opt-out: stop emission, delete the ID and the local queue (ADR-305). */
+export declare function deleteFunnelData(): void;
+/**
+ * Most recent local record of `event`, as a daily bucket (`YYYY-MM-DD`) —
+ * events never carry a full timestamp (ADR-309). Returns null when nothing
+ * is recorded, which is also what you get with telemetry consent off (the
+ * queue is never written at all in that case) — this can't distinguish
+ * "never happened" from "not being recorded," by design.
+ */
+export declare function lastRecordedEvent(event: FunnelEventName): string | null;
+/**
+ * Record a funnel event to the local queue. No-op (returns false) when
+ * telemetry consent is absent — consent-off means zero funnel records.
+ * `messageId` is only carried for promo_impression / promo_open events; on
+ * every other event it is dropped so the schema stays clean.
+ */
+export declare function recordFunnelEvent(event: FunnelEventName, surface: FunnelSurface, release: string, optsOrNow?: Date | {
+    now?: Date;
+    messageId?: string;
+}): boolean;
+//# sourceMappingURL=events.d.ts.map