@legioncodeinc/nectar 0.0.1

package/dist/telemetry/metrics.js

@@ -0,0 +1,148 @@
+function zeroCounts() {
+    return {
+        filesRegistered: 0,
+        nectarsMinted: 0,
+        descriptionsGenerated: 0,
+        hiveGraphVersions: 0,
+        embeddingsComputed: 0,
+    };
+}
+export class MetricsWriter {
+    db;
+    nowFn;
+    counts = zeroCounts();
+    constructor(opts) {
+        this.db = opts.db;
+        this.nowFn = opts.now ?? (() => new Date().toISOString());
+        // Establish the zero baseline immediately: a poll that lands before any
+        // pipeline work still reads a real all-zero row, never a missing one.
+        this.flush();
+    }
+    snapshot() {
+        return { ...this.counts };
+    }
+    incrementFilesRegistered() {
+        this.counts.filesRegistered += 1;
+        this.flush();
+    }
+    incrementNectarsMinted() {
+        this.counts.nectarsMinted += 1;
+        this.flush();
+    }
+    incrementDescriptionsGenerated() {
+        this.counts.descriptionsGenerated += 1;
+        this.flush();
+    }
+    incrementHiveGraphVersions() {
+        this.counts.hiveGraphVersions += 1;
+        this.flush();
+    }
+    incrementEmbeddingsComputed() {
+        this.counts.embeddingsComputed += 1;
+        this.flush();
+    }
+    flush() {
+        try {
+            this.db
+                .prepare(`INSERT INTO service_metrics (id, files_registered, nectars_minted, descriptions_generated, hive_graph_versions, embeddings_computed, updated_at)
+           VALUES (1, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET
+             files_registered = excluded.files_registered,
+             nectars_minted = excluded.nectars_minted,
+             descriptions_generated = excluded.descriptions_generated,
+             hive_graph_versions = excluded.hive_graph_versions,
+             embeddings_computed = excluded.embeddings_computed,
+             updated_at = excluded.updated_at`)
+                .run(this.counts.filesRegistered, this.counts.nectarsMinted, this.counts.descriptionsGenerated, this.counts.hiveGraphVersions, this.counts.embeddingsComputed, this.nowFn());
+        }
+        catch {
+            // fail-soft (AC-7 / AC-017b): a metrics write error never surfaces into the pipeline.
+        }
+    }
+}
+/**
+ * Wrap a {@link HiveGraphStore} so the two counters with a precise 1:1
+ * store-level definition increment at their REAL completion point, with ZERO
+ * changes to the ladder (`registration/ladder.ts`) or the store adapters:
+ *
+ *   - `nectarsMinted`: one `insertIdentity()` call = one freshly minted nectar
+ *     (the ladder's step-5 `mintOrCopy` is the only caller in this repo). A
+ *     THROWING insert (duplicate nectar, the store's own dedup guard) never
+ *     increments, because the throw happens before the increment line below -
+ *     no double counting across a rejected mint.
+ *   - `hiveGraphVersions`: one `appendVersion()` call = one
+ *     `hive_graph_versions` row written (ladder steps 2/3/4/5), the exact
+ *     PRD-005 catalog write.
+ *
+ * `descriptionsGenerated` and `embeddingsComputed` are wired to the CLOSEST
+ * REAL signal available in this repo today rather than a fabricated hook: a
+ * version row only ever carries `describeStatus === "described"` or a
+ * non-null `embedding` once the enricher (PRD-007/PRD-016) and the embeddings
+ * provider (PRD-014) actually populate those fields on the row they pass to
+ * `appendVersion`. Neither pipeline exists in this repo yet - `ladder.ts`'s
+ * `baseVersion()` always writes `title/description: ""`, `describeStatus:
+ * "pending"`, and `embedding: null` - so both counters correctly read 0 until
+ * those PRDs land. This is a documented, intentional approximation (see the
+ * PRD-017 ledger evidence): the day a future PRD starts writing a "described"
+ * row or a non-null embedding through this same `appendVersion` call, the
+ * counter starts moving with no further wiring required.
+ */
+export function wrapStoreWithMetrics(store, sink) {
+    return new Proxy(store, {
+        get(target, prop, receiver) {
+            if (prop === "insertIdentity") {
+                return (row) => {
+                    target.insertIdentity(row);
+                    sink.incrementNectarsMinted();
+                };
+            }
+            if (prop === "appendVersion") {
+                return (row) => {
+                    target.appendVersion(row);
+                    sink.incrementHiveGraphVersions();
+                    if (row.describeStatus === "described")
+                        sink.incrementDescriptionsGenerated();
+                    if (row.embedding !== null)
+                        sink.incrementEmbeddingsComputed();
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+/**
+ * The async twin of {@link wrapStoreWithMetrics}: wrap an
+ * {@link AsyncHiveGraphStore} so the same four store-level counters increment at
+ * their REAL completion point on the LIVE (durable) brood path, with ZERO
+ * changes to `runBroodAsync` or the Deep Lake adapter. The increment fires only
+ * AFTER the awaited write resolves - a rejected `insertIdentity` (the mint dedup
+ * guard) or `appendVersion` never increments, because the `await` throws before
+ * the increment line. This is what makes the PRD-017b `descriptionsGenerated` /
+ * `hiveGraphVersions` / `embeddingsComputed` / `nectarsMinted` counters move in
+ * production once the daemon actually broods against Deep Lake (the counters that
+ * previously stayed 0 because the pipeline never ran on the live boot path).
+ */
+export function wrapAsyncStoreWithMetrics(store, sink) {
+    return new Proxy(store, {
+        get(target, prop, receiver) {
+            if (prop === "insertIdentity") {
+                return async (row) => {
+                    await target.insertIdentity(row);
+                    sink.incrementNectarsMinted();
+                };
+            }
+            if (prop === "appendVersion") {
+                return async (row) => {
+                    await target.appendVersion(row);
+                    sink.incrementHiveGraphVersions();
+                    if (row.describeStatus === "described")
+                        sink.incrementDescriptionsGenerated();
+                    if (row.embedding !== null)
+                        sink.incrementEmbeddingsComputed();
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+//# sourceMappingURL=metrics.js.map

package/dist/telemetry/metrics.js.map

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

package/dist/telemetry-usage/emit.d.ts

@@ -0,0 +1,105 @@
+/** The pinned PostHog capture path. The full ingest URL is `${host}${POSTHOG_CAPTURE_PATH}`. */
+export declare const POSTHOG_CAPTURE_PATH = "/i/v0/e/";
+/** The default PostHog US cloud ingest host, used when no host was baked. */
+export declare const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
+/** The bounded POST timeout: a telemetry POST never delays a CLI verb longer than this. */
+export declare const DEFAULT_EMIT_TIMEOUT_MS = 2000;
+/** nectar's OWN opt-out env var. `NECTAR_TELEMETRY=0` silences all usage telemetry (ADR-0002: nectar depends on no honeycomb env). */
+export declare const ENV_TELEMETRY = "NECTAR_TELEMETRY";
+/**
+ * Honeycomb's family opt-out, DETECTED and honored when present (never
+ * required): an operator who silenced the honeycomb install with
+ * `HONEYCOMB_TELEMETRY=0` should not have to discover a second switch for a
+ * co-installed nectar. Detection-only per ADR-0002; nectar functions
+ * identically when honeycomb is absent.
+ */
+export declare const DETECTED_FAMILY_TELEMETRY = "HONEYCOMB_TELEMETRY";
+/** The cross-tool opt-out standard. Any value other than empty or "0" silences all usage telemetry. */
+export declare const ENV_DO_NOT_TRACK = "DO_NOT_TRACK";
+/** The installer-minted anonymous id file shared across the honeycomb product family. */
+export declare const INSTALL_ID_FILE_NAME = "install-id";
+/** The dedupe ledger + fallback distinct id file, namespaced so it coexists in the shared runtime dir. */
+export declare const USAGE_LEDGER_FILE_NAME = "nectar-usage-telemetry.json";
+/** The four lifecycle events this chokepoint may ever emit. */
+export type UsageEventName = "nectar_installed" | "nectar_uninstalled" | "nectar_first_run" | "nectar_updated";
+/** The CLOSED payload shape. Nothing outside these five keys ever leaves the machine. */
+export interface UsageProperties {
+    readonly package: "nectar";
+    readonly version: string;
+    readonly os: string;
+    readonly arch: string;
+    readonly node: string;
+}
+/** Why an emit did NOT send. Resolved, never thrown. */
+export type UsageSkipReason = "disabled" | "opted_out" | "already_reported" | "send_failed";
+/** The outcome of one emit call (always resolves, never rejects). */
+export interface UsageEmitOutcome {
+    readonly sent: boolean;
+    readonly skipped?: UsageSkipReason;
+}
+/** The minimal fetch response shape the chokepoint reads. */
+export interface UsageFetchResponse {
+    readonly ok: boolean;
+    readonly status: number;
+}
+/** The minimal request init the chokepoint passes. */
+export interface UsageFetchRequestInit {
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body: string;
+    readonly signal?: AbortSignal;
+}
+/** The injectable fetch seam so tests record the POST instead of hitting PostHog. */
+export type UsageFetch = (url: string, init: UsageFetchRequestInit) => Promise<UsageFetchResponse>;
+/** The injectable seams. Production defaults are the global fetch, process.env, and ~/.honeycomb. */
+export interface UsageEmitDeps {
+    readonly fetch?: UsageFetch;
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override the state dir (tests point this at a temp dir). Default: `~/.honeycomb`. */
+    readonly dir?: string;
+    /** Override the baked key (tests force the keyed branch without a bake). */
+    readonly posthogKey?: string;
+    /** Override the capture host. */
+    readonly posthogHost?: string;
+    readonly timeoutMs?: number;
+    /** Override the reported version (default: read from package.json). */
+    readonly version?: string;
+}
+/**
+ * True when the user opted out via nectar's own env var, the detected
+ * honeycomb family opt-out, or DO_NOT_TRACK (consoledonottrack.com convention).
+ */
+export declare function isOptedOut(env?: NodeJS.ProcessEnv): boolean;
+/** Build the full capture URL from a host (trailing slashes trimmed). */
+export declare function captureUrl(host: string): string;
+/**
+ * The nectar version, read from the package.json two levels above this
+ * module (src/telemetry-usage/ and dist/telemetry-usage/ both sit two levels
+ * below the package root). Fail-soft to "0.0.0" so a packaging anomaly never
+ * breaks a CLI verb.
+ */
+export declare function readPackageVersion(): string;
+/**
+ * THE CHOKEPOINT. Emit one lifecycle event through the gates (disabled, opted
+ * out, already reported) and, past all three, a single bounded fire-and-forget
+ * POST. On a 2xx the dedupe key is recorded in the ledger. Never throws.
+ */
+export declare function emitUsageEvent(event: UsageEventName, deps?: UsageEmitDeps): Promise<UsageEmitOutcome>;
+/** Fired by `nectar install` after the installer succeeds. Once per machine. */
+export declare function emitInstalled(deps?: UsageEmitDeps): Promise<UsageEmitOutcome>;
+/** Fired by `nectar uninstall` before teardown. Fire-and-forget. */
+export declare function emitUninstalled(deps?: UsageEmitDeps): Promise<UsageEmitOutcome>;
+/** The outcome of the daemon-start hook: which of the two events were attempted. */
+export interface DaemonStartTelemetry {
+    readonly firstRun: UsageEmitOutcome | null;
+    readonly updated: UsageEmitOutcome | null;
+}
+/**
+ * The daemon-start hook: fires `nectar_first_run` (once per machine) and,
+ * when the persisted last-seen version differs from the current one, fires
+ * `nectar_updated` (deduped per version), then persists the new version.
+ * The version bookkeeping is a local file write and happens regardless of the
+ * emit gates, so a later opt-in never replays a stale backlog. Never throws.
+ */
+export declare function recordDaemonStart(deps?: UsageEmitDeps): Promise<DaemonStartTelemetry>;
+//# sourceMappingURL=emit.d.ts.map

package/dist/telemetry-usage/emit.d.ts.map

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

package/dist/telemetry-usage/emit.js

@@ -0,0 +1,267 @@
+/**
+ * The SINGLE PostHog usage-telemetry chokepoint for nectar.
+ *
+ * NOT src/telemetry/: that module is the doctor SQLite fleet-telemetry
+ * store (check-ins, heartbeats, logs). THIS module is the only place in the
+ * codebase that posts anonymous lifecycle events (installed, uninstalled,
+ * first_run, updated) to the PostHog capture endpoint. It mirrors honeycomb's
+ * emit chokepoint posture (honeycomb src/daemon/runtime/telemetry/emit.ts):
+ *
+ *   - body is exactly { api_key, event, properties, distinct_id }, POSTed to
+ *     {host}/i/v0/e/ with a 2 second AbortController timeout;
+ *   - the payload is built from a CLOSED allow-list, never from caller input:
+ *     { package: "nectar", version, os, arch, node } and nothing else;
+ *   - gates, in order: (1) empty baked key means hard-disabled (every dev or
+ *     source build), (2) NECTAR_TELEMETRY=0 (nectar's own switch), the
+ *     DETECTED HONEYCOMB_TELEMETRY=0 family opt-out, or DO_NOT_TRACK truthy
+ *     means opted out, (3) the dedupe ledger means at most once per machine
+ *     (per version for nectar_updated);
+ *   - fail-soft everywhere: emit never throws, never blocks past the bounded
+ *     timeout, and never changes a host flow's exit code. A network error, a
+ *     timeout, a 4xx, a 5xx, or a ledger IO failure all resolve to a skipped
+ *     outcome instead of propagating.
+ *
+ * The key arrives via src/telemetry-usage/posthog-key.ts, a committed-empty
+ * stub that scripts/bake-posthog-key.mjs rewrites in dist/ at release time
+ * (plain tsc build, so there is no esbuild define mechanism here).
+ *
+ * distinct_id is anonymous: the honeycomb installer's ~/.honeycomb/install-id
+ * when present (so the funnel correlates across the product family), else a
+ * random UUID minted once and persisted in the ledger file under nectar's
+ * runtime dir (~/.honeycomb by default, resolveConfig's RUNTIME_DIR_NAME).
+ * Never an email, an account id, a hostname, or a path.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { arch, homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RUNTIME_DIR_NAME } from "../config.js";
+import { POSTHOG_HOST, POSTHOG_KEY } from "./posthog-key.js";
+/** The pinned PostHog capture path. The full ingest URL is `${host}${POSTHOG_CAPTURE_PATH}`. */
+export const POSTHOG_CAPTURE_PATH = "/i/v0/e/";
+/** The default PostHog US cloud ingest host, used when no host was baked. */
+export const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
+/** The bounded POST timeout: a telemetry POST never delays a CLI verb longer than this. */
+export const DEFAULT_EMIT_TIMEOUT_MS = 2000;
+/** nectar's OWN opt-out env var. `NECTAR_TELEMETRY=0` silences all usage telemetry (ADR-0002: nectar depends on no honeycomb env). */
+export const ENV_TELEMETRY = "NECTAR_TELEMETRY";
+/**
+ * Honeycomb's family opt-out, DETECTED and honored when present (never
+ * required): an operator who silenced the honeycomb install with
+ * `HONEYCOMB_TELEMETRY=0` should not have to discover a second switch for a
+ * co-installed nectar. Detection-only per ADR-0002; nectar functions
+ * identically when honeycomb is absent.
+ */
+export const DETECTED_FAMILY_TELEMETRY = "HONEYCOMB_TELEMETRY";
+/** The cross-tool opt-out standard. Any value other than empty or "0" silences all usage telemetry. */
+export const ENV_DO_NOT_TRACK = "DO_NOT_TRACK";
+/** The installer-minted anonymous id file shared across the honeycomb product family. */
+export const INSTALL_ID_FILE_NAME = "install-id";
+/** The dedupe ledger + fallback distinct id file, namespaced so it coexists in the shared runtime dir. */
+export const USAGE_LEDGER_FILE_NAME = "nectar-usage-telemetry.json";
+/**
+ * The falsy family a boolean-style opt-out accepts: `0`, `false`, `off`
+ * (case-insensitive), plus `no`. NEC-042 item 4 / AC-018l.11: `NECTAR_TELEMETRY`
+ * honored only the literal `"0"` before, so `NECTAR_TELEMETRY=false`/`off` were
+ * silently IGNORED (telemetry stayed on). Now the whole falsy family opts out.
+ */
+function isFalsyFlag(raw) {
+    if (raw === undefined)
+        return false;
+    const v = raw.trim().toLowerCase();
+    return v === "0" || v === "false" || v === "off" || v === "no";
+}
+/**
+ * True when the user opted out via nectar's own env var, the detected
+ * honeycomb family opt-out, or DO_NOT_TRACK (consoledonottrack.com convention).
+ */
+export function isOptedOut(env = process.env) {
+    if (isFalsyFlag(env[ENV_TELEMETRY]))
+        return true;
+    if (env[DETECTED_FAMILY_TELEMETRY] === "0")
+        return true;
+    const dnt = env[ENV_DO_NOT_TRACK];
+    return dnt !== undefined && dnt !== "" && dnt !== "0";
+}
+/** Build the full capture URL from a host (trailing slashes trimmed). */
+export function captureUrl(host) {
+    return `${host.replace(/\/+$/, "")}${POSTHOG_CAPTURE_PATH}`;
+}
+/** The default state dir: nectar's runtime dir convention (shared `~/.honeycomb`). */
+function defaultStateDir() {
+    return join(homedir(), RUNTIME_DIR_NAME);
+}
+/**
+ * The nectar version, read from the package.json two levels above this
+ * module (src/telemetry-usage/ and dist/telemetry-usage/ both sit two levels
+ * below the package root). Fail-soft to "0.0.0" so a packaging anomaly never
+ * breaks a CLI verb.
+ */
+export function readPackageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const raw = readFileSync(join(here, "..", "..", "package.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/** Load the ledger, treating a missing or corrupt file as a fresh one (fail-soft). */
+function loadLedger(dir) {
+    try {
+        const raw = readFileSync(join(dir, USAGE_LEDGER_FILE_NAME), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            ...(typeof parsed.distinctId === "string" ? { distinctId: parsed.distinctId } : {}),
+            reported: Array.isArray(parsed.reported) ? parsed.reported.filter((e) => typeof e === "string") : [],
+            ...(typeof parsed.lastSeenVersion === "string" ? { lastSeenVersion: parsed.lastSeenVersion } : {}),
+        };
+    }
+    catch {
+        return { reported: [] };
+    }
+}
+/** Persist the ledger, creating the state dir (0o700) when needed. Throws on IO failure; callers swallow. */
+function saveLedger(dir, ledger) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(join(dir, USAGE_LEDGER_FILE_NAME), `${JSON.stringify(ledger, null, 2)}\n`, "utf8");
+}
+/** Read the installer's anonymous install-id when present and non-empty, else undefined. */
+function readInstallId(dir) {
+    try {
+        const raw = readFileSync(join(dir, INSTALL_ID_FILE_NAME), "utf8").trim();
+        return raw.length > 0 ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The dedupe ledger key: plain event name, except updated which dedupes per version. */
+function dedupeKey(event, version) {
+    return event === "nectar_updated" ? `${event}@${version}` : event;
+}
+/** Assemble the closed allow-list payload. This is the only payload builder; no caller input flows in. */
+function buildProperties(version) {
+    return { package: "nectar", version, os: platform(), arch: arch(), node: process.version };
+}
+/**
+ * THE CHOKEPOINT. Emit one lifecycle event through the gates (disabled, opted
+ * out, already reported) and, past all three, a single bounded fire-and-forget
+ * POST. On a 2xx the dedupe key is recorded in the ledger. Never throws.
+ */
+export async function emitUsageEvent(event, deps = {}) {
+    const key = deps.posthogKey ?? POSTHOG_KEY;
+    // Gate 1: empty baked key means hard-disabled (dev or source build). No IO, no network.
+    if (key.length === 0)
+        return { sent: false, skipped: "disabled" };
+    // Gate 2: opted out via either env var. No IO, no network.
+    if (isOptedOut(deps.env ?? process.env))
+        return { sent: false, skipped: "opted_out" };
+    try {
+        const dir = deps.dir ?? defaultStateDir();
+        const version = deps.version ?? readPackageVersion();
+        const ledger = loadLedger(dir);
+        // distinct_id preference: the installer's install-id when present, else a
+        // UUID minted once and persisted in the ledger so it stays stable.
+        let distinctId = readInstallId(dir);
+        if (distinctId === undefined) {
+            if (ledger.distinctId === undefined) {
+                ledger.distinctId = randomUUID();
+                saveLedger(dir, ledger);
+            }
+            distinctId = ledger.distinctId;
+        }
+        // Gate 3: dedupe. Each event sends at most once per machine (per version for updated).
+        const dedupe = dedupeKey(event, version);
+        if (ledger.reported.includes(dedupe))
+            return { sent: false, skipped: "already_reported" };
+        const ok = await postCapture(event, buildProperties(version), distinctId, key, deps);
+        if (!ok)
+            return { sent: false, skipped: "send_failed" };
+        // 2xx: record the dedupe key. The persist is best-effort; a failure here
+        // must not flip a successful send into send_failed.
+        try {
+            ledger.reported.push(dedupe);
+            saveLedger(dir, ledger);
+        }
+        catch {
+            // A persist hiccup after a successful send is non-fatal.
+        }
+        return { sent: true };
+    }
+    catch {
+        // Fail-soft: any unexpected error (IO, a thrown fetch) is swallowed.
+        return { sent: false, skipped: "send_failed" };
+    }
+}
+/** Issue the ONE bounded-timeout POST and report whether it was a 2xx. Swallows everything. */
+async function postCapture(event, properties, distinctId, key, deps) {
+    const doFetch = deps.fetch ?? globalThis.fetch;
+    const host = deps.posthogHost ?? (POSTHOG_HOST.length > 0 ? POSTHOG_HOST : DEFAULT_POSTHOG_HOST);
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_EMIT_TIMEOUT_MS;
+    const body = { api_key: key, event, properties, distinct_id: distinctId };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const resp = await doFetch(captureUrl(host), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        return resp.ok;
+    }
+    catch {
+        // A dropped lifecycle event is acceptable; a hung CLI verb is not.
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Fired by `nectar install` after the installer succeeds. Once per machine. */
+export async function emitInstalled(deps = {}) {
+    return emitUsageEvent("nectar_installed", deps);
+}
+/** Fired by `nectar uninstall` before teardown. Fire-and-forget. */
+export function emitUninstalled(deps = {}) {
+    return emitUsageEvent("nectar_uninstalled", deps);
+}
+/**
+ * The daemon-start hook: fires `nectar_first_run` (once per machine) and,
+ * when the persisted last-seen version differs from the current one, fires
+ * `nectar_updated` (deduped per version), then persists the new version.
+ * The version bookkeeping is a local file write and happens regardless of the
+ * emit gates, so a later opt-in never replays a stale backlog. Never throws.
+ */
+export async function recordDaemonStart(deps = {}) {
+    try {
+        const dir = deps.dir ?? defaultStateDir();
+        const version = deps.version ?? readPackageVersion();
+        const lastSeen = loadLedger(dir).lastSeenVersion;
+        const firstRun = await emitUsageEvent("nectar_first_run", deps);
+        let updated = null;
+        if (lastSeen !== undefined && lastSeen !== version) {
+            updated = await emitUsageEvent("nectar_updated", deps);
+        }
+        if (lastSeen !== version) {
+            // Reload: the emits above may have persisted dedupe entries or a distinct id.
+            const ledger = loadLedger(dir);
+            ledger.lastSeenVersion = version;
+            try {
+                saveLedger(dir, ledger);
+            }
+            catch {
+                // Best-effort; the updated event's per-version dedupe is the backstop.
+            }
+        }
+        return { firstRun, updated };
+    }
+    catch {
+        return { firstRun: null, updated: null };
+    }
+}
+//# sourceMappingURL=emit.js.map

package/dist/telemetry-usage/emit.js.map

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

package/dist/telemetry-usage/posthog-key.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The PostHog ingest destination stub for USAGE telemetry (lifecycle events).
+ * Not related to src/telemetry/, which is the doctor SQLite fleet store.
+ *
+ * BOTH constants are committed EMPTY and MUST stay "" in source. nectar
+ * builds with plain tsc (no esbuild, so no `define` mechanism); the real
+ * values are baked into the compiled OUTPUT instead: the release workflow's
+ * gate job runs scripts/bake-posthog-key.mjs after the last build step, which
+ * rewrites dist/telemetry-usage/posthog-key.js in place from the
+ * NECTAR_POSTHOG_KEY / NECTAR_POSTHOG_HOST environment (the HONEYCOMB_* names
+ * are a detected fallback while the family shares one ingest project; never
+ * required, per ADR-0002). The baked dist/ is what the publish job ships
+ * verbatim.
+ *
+ * An empty key hard-disables usage telemetry (src/telemetry-usage/emit.ts
+ * gate 1), so every dev/source/fork build sends nothing. The key is a public
+ * write-only PostHog ingest key, not a read-capable secret; it is still kept
+ * out of source so unkeyed builds stay silent by construction.
+ */
+export declare const POSTHOG_KEY = "";
+export declare const POSTHOG_HOST = "";
+//# sourceMappingURL=posthog-key.d.ts.map

package/dist/telemetry-usage/posthog-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posthog-key.d.ts","sourceRoot":"","sources":["../../src/telemetry-usage/posthog-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,KAAK,CAAC;AAC9B,eAAO,MAAM,YAAY,KAAK,CAAC"}

package/dist/telemetry-usage/posthog-key.js

@@ -0,0 +1,22 @@
+/**
+ * The PostHog ingest destination stub for USAGE telemetry (lifecycle events).
+ * Not related to src/telemetry/, which is the doctor SQLite fleet store.
+ *
+ * BOTH constants are committed EMPTY and MUST stay "" in source. nectar
+ * builds with plain tsc (no esbuild, so no `define` mechanism); the real
+ * values are baked into the compiled OUTPUT instead: the release workflow's
+ * gate job runs scripts/bake-posthog-key.mjs after the last build step, which
+ * rewrites dist/telemetry-usage/posthog-key.js in place from the
+ * NECTAR_POSTHOG_KEY / NECTAR_POSTHOG_HOST environment (the HONEYCOMB_* names
+ * are a detected fallback while the family shares one ingest project; never
+ * required, per ADR-0002). The baked dist/ is what the publish job ships
+ * verbatim.
+ *
+ * An empty key hard-disables usage telemetry (src/telemetry-usage/emit.ts
+ * gate 1), so every dev/source/fork build sends nothing. The key is a public
+ * write-only PostHog ingest key, not a read-capable secret; it is still kept
+ * out of source so unkeyed builds stay silent by construction.
+ */
+export const POSTHOG_KEY = "";
+export const POSTHOG_HOST = "";
+//# sourceMappingURL=posthog-key.js.map

package/dist/telemetry-usage/posthog-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"posthog-key.js","sourceRoot":"","sources":["../../src/telemetry-usage/posthog-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC;AAC9B,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC"}