@legioncodeinc/nectar 0.0.1

package/dist/health.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The `/health` contract for the nectar daemon.
+ *
+ * Per PRD-001b (decision #20, revised): the top-level coarse `status` bit is
+ * what doctor classifies on (modeled on honeycomb's `PipelineStatus`,
+ * honeycomb/src/daemon/runtime/health.ts:42), and the body carries
+ * nectar-native subsystem fields honeycomb's `/health` does not have
+ * (brooding, enricher queue, projection, cost, provider state). The HTTP status
+ * gates 200 when ok / 503 when degraded (PRD-003a; mirrors server.ts:318-341).
+ */
+export type PipelineStatus = "ok" | "degraded";
+export interface HealthBody {
+    status: PipelineStatus;
+    uptimeMs: number;
+    brooding: {
+        active: boolean;
+        /**
+         * Machine-readable reason brooding is inactive, or null when active/ready
+         * (PRD-018k AC-018k.3). `"credentials_missing"` / `"portkey_disabled"` name
+         * the unmet prerequisite so supervision and humans can both see WHY a booted
+         * daemon describes nothing, rather than inferring it from the provider bits.
+         */
+        reason: string | null;
+        filesDescribed: number;
+        filesTotal: number;
+        lastEventAt: string | null;
+    };
+    enricher: {
+        queueDepth: number;
+        lastCycleAt: string | null;
+        consecutiveFailures: number;
+        lastFileDescribed: string | null;
+    };
+    projection: {
+        lastWriteAt: string | null;
+        lastContentHash: string | null;
+    };
+    cost: {
+        broodTotalTokens: number;
+        broodTotalUsd: number;
+    };
+    embeddings: {
+        provider: "local-nomic" | "hosted" | "off";
+    };
+    portkey: {
+        enabled: boolean;
+    };
+    watch: {
+        /** True once the update-on-change registration pipeline's NodeFS watcher is running (PRD-018b). */
+        running: boolean;
+        /**
+         * Why the watch leg is not running, when it is not: `"no-credentials"` when
+         * the daemon booted without a durable store (the pipeline is dormant, not
+         * broken - AC-018b.7), `"disabled"` when explicitly turned off, or null when
+         * running (or simply not yet started). Surfaced so a dormant watch leg is
+         * observable rather than silent.
+         */
+        reason: string | null;
+        /** Durable flushes from the sync/async bridge that failed (surfaced, not swallowed - AC-018b.4). */
+        flushFailures: number;
+        /** ISO 8601 timestamp of the most recent durable-flush failure, or null when none has failed. */
+        lastFlushErrorAt: string | null;
+        /**
+         * PRD-018c AC-018c.6/7: the watcher's own liveness, independent of
+         * `reason` (which explains why the watch leg is dormant AT ALL, e.g.
+         * no-credentials). `"running"` mirrors `running=true`; `"restarting"`
+         * surfaces an active error-backoff recovery; `"degraded"` means restart
+         * attempts were exhausted (the periodic resync backstop keeps
+         * reconciling); `"stopped"` is the pre-start/post-shutdown default.
+         */
+        state: "stopped" | "running" | "restarting" | "degraded";
+    };
+}
+/**
+ * Mutable daemon health state. Subsystems update their slices as later PRDs
+ * (007 brooding, 016 enricher, 011 projection, 010 portkey, 014 embeddings) land;
+ * until then the fields report their honest zero/off values. `degrade()` flips
+ * the coarse bit doctor classifies on.
+ */
+export declare class HealthState {
+    private startedAtMs;
+    private status;
+    readonly brooding: HealthBody["brooding"];
+    readonly enricher: HealthBody["enricher"];
+    readonly projection: HealthBody["projection"];
+    readonly cost: HealthBody["cost"];
+    readonly embeddings: HealthBody["embeddings"];
+    readonly portkey: HealthBody["portkey"];
+    readonly watch: HealthBody["watch"];
+    markStarted(atMs?: number): void;
+    /**
+     * Record the resolved provider state (PRD-010 / PRD-014, decision #20's
+     * purpose-built health shape). Resolved ONCE at assemble/start from the
+     * env-backed config, never per `/health` request. `new HealthState()` keeps
+     * the honest defaults (`portkey.enabled = false`, `embeddings.provider = off`)
+     * until a composition root calls this.
+     */
+    setProviderState(state: {
+        portkeyEnabled: boolean;
+        embeddingsProvider: HealthBody["embeddings"]["provider"];
+    }): void;
+    /**
+     * Merge the brooding subsystem slice (PRD-007 / decision #20). Called by the
+     * daemon's auto-brood path and the CLI/API brood mechanic as a brood advances.
+     * Fail-soft: an absent subsystem never calls this and the honest zero defaults
+     * stand; a partial only overwrites the fields it carries.
+     */
+    setBroodingState(state: Partial<HealthBody["brooding"]>): void;
+    /**
+     * Merge the enricher subsystem slice (PRD-016 / decision #20). Fed by the
+     * enricher loop's per-cycle sink; absent subsystems leave the zero defaults.
+     */
+    setEnricherState(state: Partial<HealthBody["enricher"]>): void;
+    /** Merge the projection subsystem slice (PRD-011): last write time + content hash. */
+    setProjectionState(state: Partial<HealthBody["projection"]>): void;
+    /**
+     * Accumulate brooding cost (PRD-007b / decision #20). Additive: each completed
+     * brood adds its estimated input tokens + USD to the running totals. Negative
+     * or non-finite deltas are ignored so a bad estimate never corrupts the total.
+     */
+    addBroodCost(delta: {
+        tokens?: number;
+        usd?: number;
+    }): void;
+    /**
+     * Merge the watch-leg slice (PRD-018b): whether the NodeFS watcher is running
+     * and, when it is not, why. The daemon calls this at start (running once the
+     * pipeline starts after auto-brood settles, or dormant with `"no-credentials"`
+     * when no durable store resolved) and at shutdown (running false). Only the
+     * fields the partial carries are overwritten.
+     */
+    setWatchState(state: Partial<Pick<HealthBody["watch"], "running" | "reason" | "state">>): void;
+    /**
+     * Record a durable-flush failure from the sync/async bridge (PRD-018b
+     * AC-018b.4): bump the count and stamp the time, so a failed durable write is
+     * visible on `/health` rather than silently dropped.
+     */
+    recordWatchFlushFailure(atIso?: string): void;
+    setStatus(status: PipelineStatus): void;
+    degrade(): void;
+    get pipelineStatus(): PipelineStatus;
+    /** The full `/health` body, snapshotted from cached state (no synchronous probe). */
+    snapshot(nowMs?: number): HealthBody;
+}
+/** Map the coarse pipeline bit to the HTTP status code (200 ok / 503 degraded). */
+export declare function healthHttpStatus(status: PipelineStatus): 200 | 503;
+//# sourceMappingURL=health.d.ts.map

package/dist/health.d.ts.map

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

package/dist/health.js

@@ -0,0 +1,168 @@
+/**
+ * The `/health` contract for the nectar daemon.
+ *
+ * Per PRD-001b (decision #20, revised): the top-level coarse `status` bit is
+ * what doctor classifies on (modeled on honeycomb's `PipelineStatus`,
+ * honeycomb/src/daemon/runtime/health.ts:42), and the body carries
+ * nectar-native subsystem fields honeycomb's `/health` does not have
+ * (brooding, enricher queue, projection, cost, provider state). The HTTP status
+ * gates 200 when ok / 503 when degraded (PRD-003a; mirrors server.ts:318-341).
+ */
+/**
+ * Mutable daemon health state. Subsystems update their slices as later PRDs
+ * (007 brooding, 016 enricher, 011 projection, 010 portkey, 014 embeddings) land;
+ * until then the fields report their honest zero/off values. `degrade()` flips
+ * the coarse bit doctor classifies on.
+ */
+export class HealthState {
+    startedAtMs = Date.now();
+    status = "ok";
+    brooding = {
+        active: false,
+        reason: null,
+        filesDescribed: 0,
+        filesTotal: 0,
+        lastEventAt: null,
+    };
+    enricher = {
+        queueDepth: 0,
+        lastCycleAt: null,
+        consecutiveFailures: 0,
+        lastFileDescribed: null,
+    };
+    projection = {
+        lastWriteAt: null,
+        lastContentHash: null,
+    };
+    cost = {
+        broodTotalTokens: 0,
+        broodTotalUsd: 0,
+    };
+    embeddings = { provider: "off" };
+    portkey = { enabled: false };
+    watch = {
+        running: false,
+        reason: null,
+        flushFailures: 0,
+        lastFlushErrorAt: null,
+        state: "stopped",
+    };
+    markStarted(atMs = Date.now()) {
+        this.startedAtMs = atMs;
+    }
+    /**
+     * Record the resolved provider state (PRD-010 / PRD-014, decision #20's
+     * purpose-built health shape). Resolved ONCE at assemble/start from the
+     * env-backed config, never per `/health` request. `new HealthState()` keeps
+     * the honest defaults (`portkey.enabled = false`, `embeddings.provider = off`)
+     * until a composition root calls this.
+     */
+    setProviderState(state) {
+        this.portkey.enabled = state.portkeyEnabled;
+        this.embeddings.provider = state.embeddingsProvider;
+    }
+    /**
+     * Merge the brooding subsystem slice (PRD-007 / decision #20). Called by the
+     * daemon's auto-brood path and the CLI/API brood mechanic as a brood advances.
+     * Fail-soft: an absent subsystem never calls this and the honest zero defaults
+     * stand; a partial only overwrites the fields it carries.
+     */
+    setBroodingState(state) {
+        if (state.active !== undefined)
+            this.brooding.active = state.active;
+        if (state.reason !== undefined)
+            this.brooding.reason = state.reason;
+        if (state.filesDescribed !== undefined)
+            this.brooding.filesDescribed = state.filesDescribed;
+        if (state.filesTotal !== undefined)
+            this.brooding.filesTotal = state.filesTotal;
+        if (state.lastEventAt !== undefined)
+            this.brooding.lastEventAt = state.lastEventAt;
+    }
+    /**
+     * Merge the enricher subsystem slice (PRD-016 / decision #20). Fed by the
+     * enricher loop's per-cycle sink; absent subsystems leave the zero defaults.
+     */
+    setEnricherState(state) {
+        if (state.queueDepth !== undefined)
+            this.enricher.queueDepth = state.queueDepth;
+        if (state.lastCycleAt !== undefined)
+            this.enricher.lastCycleAt = state.lastCycleAt;
+        if (state.consecutiveFailures !== undefined)
+            this.enricher.consecutiveFailures = state.consecutiveFailures;
+        if (state.lastFileDescribed !== undefined)
+            this.enricher.lastFileDescribed = state.lastFileDescribed;
+    }
+    /** Merge the projection subsystem slice (PRD-011): last write time + content hash. */
+    setProjectionState(state) {
+        if (state.lastWriteAt !== undefined)
+            this.projection.lastWriteAt = state.lastWriteAt;
+        if (state.lastContentHash !== undefined)
+            this.projection.lastContentHash = state.lastContentHash;
+    }
+    /**
+     * Accumulate brooding cost (PRD-007b / decision #20). Additive: each completed
+     * brood adds its estimated input tokens + USD to the running totals. Negative
+     * or non-finite deltas are ignored so a bad estimate never corrupts the total.
+     */
+    addBroodCost(delta) {
+        if (typeof delta.tokens === "number" && Number.isFinite(delta.tokens) && delta.tokens > 0) {
+            this.cost.broodTotalTokens += delta.tokens;
+        }
+        if (typeof delta.usd === "number" && Number.isFinite(delta.usd) && delta.usd > 0) {
+            this.cost.broodTotalUsd += delta.usd;
+        }
+    }
+    /**
+     * Merge the watch-leg slice (PRD-018b): whether the NodeFS watcher is running
+     * and, when it is not, why. The daemon calls this at start (running once the
+     * pipeline starts after auto-brood settles, or dormant with `"no-credentials"`
+     * when no durable store resolved) and at shutdown (running false). Only the
+     * fields the partial carries are overwritten.
+     */
+    setWatchState(state) {
+        if (state.running !== undefined)
+            this.watch.running = state.running;
+        if (state.reason !== undefined)
+            this.watch.reason = state.reason;
+        if (state.state !== undefined)
+            this.watch.state = state.state;
+    }
+    /**
+     * Record a durable-flush failure from the sync/async bridge (PRD-018b
+     * AC-018b.4): bump the count and stamp the time, so a failed durable write is
+     * visible on `/health` rather than silently dropped.
+     */
+    recordWatchFlushFailure(atIso = new Date().toISOString()) {
+        this.watch.flushFailures += 1;
+        this.watch.lastFlushErrorAt = atIso;
+    }
+    setStatus(status) {
+        this.status = status;
+    }
+    degrade() {
+        this.status = "degraded";
+    }
+    get pipelineStatus() {
+        return this.status;
+    }
+    /** The full `/health` body, snapshotted from cached state (no synchronous probe). */
+    snapshot(nowMs = Date.now()) {
+        return {
+            status: this.status,
+            uptimeMs: Math.max(0, nowMs - this.startedAtMs),
+            brooding: { ...this.brooding },
+            enricher: { ...this.enricher },
+            projection: { ...this.projection },
+            cost: { ...this.cost },
+            embeddings: { ...this.embeddings },
+            portkey: { ...this.portkey },
+            watch: { ...this.watch },
+        };
+    }
+}
+/** Map the coarse pipeline bit to the HTTP status code (200 ok / 503 degraded). */
+export function healthHttpStatus(status) {
+    return status === "ok" ? 200 : 503;
+}
+//# sourceMappingURL=health.js.map

package/dist/health.js.map

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

package/dist/hive-graph/deeplake-credentials.d.ts

@@ -0,0 +1,68 @@
+/** The SHARED credentials directory name under the user's home. */
+export declare const CREDENTIALS_DIR_NAME = ".deeplake";
+/** The credentials file name within the dir. */
+export declare const CREDENTIALS_FILE_NAME = "credentials.json";
+/** The canonical Deep Lake API base URL used when a file omits `apiUrl`. */
+export declare const DEFAULT_DEEPLAKE_API_URL = "https://api.deeplake.ai";
+/** The validated Deep Lake connection details the transport is built from. */
+export interface DeepLakeCredentials {
+    /** Deep Lake HTTP query endpoint. Defaults to {@link DEFAULT_DEEPLAKE_API_URL}. */
+    readonly apiUrl: string;
+    /** The org-bound bearer token (SECRET; never logged in full). */
+    readonly token: string;
+    /** The org id the token is bound to. */
+    readonly orgId: string;
+    /** The active workspace id. */
+    readonly workspaceId: string;
+}
+/**
+ * Options for {@link loadDeepLakeCredentials}, injectable so a test points the
+ * file read at a temp dir without touching the real `~/.deeplake` (mirrors
+ * honeycomb's `CredentialsFileProviderOptions`). All optional.
+ */
+export interface LoadCredentialsOptions {
+    /** Override the credentials directory (tests). Defaults to `~/.deeplake`. */
+    readonly dir?: string;
+    /**
+     * Warning sink for the group/other-readable advisory (NEC-042 item 13 /
+     * AC-018l.20). Defaults to stderr. A no-op on Windows, where POSIX mode bits
+     * do not map to a meaningful readability check.
+     */
+    readonly warn?: (message: string) => void;
+    /**
+     * The platform whose permission model applies (default: `process.platform`).
+     * Injectable so a test can exercise the POSIX advisory path deterministically.
+     */
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * Structured, fail-closed rejection. Carries exactly which fields were missing
+ * or invalid so a caller (or an operator reading a log line) knows what to
+ * fix without the loader ever echoing the file's contents (which may hold the
+ * token).
+ */
+export declare class DeepLakeCredentialsError extends Error {
+    readonly missing: readonly string[];
+    constructor(missing: readonly string[]);
+}
+/** Resolve the credentials directory, honoring the test override. */
+export declare function credentialsDir(options?: LoadCredentialsOptions): string;
+/** Resolve the full credentials file path within the (possibly overridden) dir. */
+export declare function credentialsPath(options?: LoadCredentialsOptions): string;
+/**
+ * Load and validate `~/.deeplake/credentials.json` (or the overridden dir in
+ * `options.dir`). Throws {@link DeepLakeCredentialsError} listing every
+ * problem found: a missing file, invalid JSON, a non-object payload, or a
+ * missing/empty `token` / `orgId` / `workspaceId`. Never returns a partial
+ * credential — the caller either gets a fully-populated `DeepLakeCredentials`
+ * or a clear, typed reason it could not.
+ */
+export declare function loadDeepLakeCredentials(options?: LoadCredentialsOptions): DeepLakeCredentials;
+/**
+ * Redact a token for logs and errors. Never echoes a token in full: keeps the
+ * last 4 chars for correlation, masks the rest. An empty/short value collapses
+ * to a fixed mask so length isn't leaked either. Mirrors honeycomb's
+ * `redactToken` (`src/daemon/runtime/auth/credentials-store.ts:254-257`).
+ */
+export declare function redactToken(value: string): string;
+//# sourceMappingURL=deeplake-credentials.d.ts.map

package/dist/hive-graph/deeplake-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplake-credentials.d.ts","sourceRoot":"","sources":["../../src/hive-graph/deeplake-credentials.ts"],"names":[],"mappings":"AA4BA,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAChD,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AACxD,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAElE,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACrC;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;gBACxB,OAAO,EAAE,SAAS,MAAM,EAAE;CAKvC;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAE3E;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAE5E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,sBAA2B,GAAG,mBAAmB,CAoCjG;AA2BD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD"}

package/dist/hive-graph/deeplake-credentials.js

@@ -0,0 +1,135 @@
+/**
+ * Deep Lake credentials loader for nectar (PRD-005).
+ *
+ * Reads the SHARED `~/.deeplake/credentials.json` file that `hivemind login`
+ * (and honeycomb) already write, mirroring the shape honeycomb's
+ * `loadDiskCredentials` / `deeplakeCredentialsFileProvider`
+ * (`src/daemon/runtime/auth/credentials-store.ts`,
+ * `src/daemon/storage/config.ts`) read: `{ apiUrl, token, orgId, workspaceId }`.
+ * Per ADR-0002, nectar never imports honeycomb's runtime for this; it
+ * reads the same on-disk file with its own loader.
+ *
+ * Fail-closed by design (mirrors honeycomb's `StorageConfigError` posture): a
+ * missing file, malformed JSON, or a missing required field throws a
+ * `DeepLakeCredentialsError` listing exactly what is wrong, rather than
+ * returning a partially-undefined credential object a caller could
+ * accidentally use. `apiUrl` is the one field with a documented default (a
+ * legacy or hand-written file may omit it); `token`, `orgId`, and
+ * `workspaceId` are load-bearing and always required.
+ *
+ * The token is never logged or included in an error message in full;
+ * `redactToken` keeps only the last 4 characters, exactly like honeycomb's
+ * `redactToken` (`src/daemon/runtime/auth/credentials-store.ts:254-257`, its
+ * `defaultCredentialProvider` variant).
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** The SHARED credentials directory name under the user's home. */
+export const CREDENTIALS_DIR_NAME = ".deeplake";
+/** The credentials file name within the dir. */
+export const CREDENTIALS_FILE_NAME = "credentials.json";
+/** The canonical Deep Lake API base URL used when a file omits `apiUrl`. */
+export const DEFAULT_DEEPLAKE_API_URL = "https://api.deeplake.ai";
+/**
+ * Structured, fail-closed rejection. Carries exactly which fields were missing
+ * or invalid so a caller (or an operator reading a log line) knows what to
+ * fix without the loader ever echoing the file's contents (which may hold the
+ * token).
+ */
+export class DeepLakeCredentialsError extends Error {
+    missing;
+    constructor(missing) {
+        super(`Invalid Deep Lake credentials: ${missing.join("; ")}`);
+        this.name = "DeepLakeCredentialsError";
+        this.missing = missing;
+    }
+}
+/** Resolve the credentials directory, honoring the test override. */
+export function credentialsDir(options = {}) {
+    return options.dir ?? join(homedir(), CREDENTIALS_DIR_NAME);
+}
+/** Resolve the full credentials file path within the (possibly overridden) dir. */
+export function credentialsPath(options = {}) {
+    return join(credentialsDir(options), CREDENTIALS_FILE_NAME);
+}
+/**
+ * Load and validate `~/.deeplake/credentials.json` (or the overridden dir in
+ * `options.dir`). Throws {@link DeepLakeCredentialsError} listing every
+ * problem found: a missing file, invalid JSON, a non-object payload, or a
+ * missing/empty `token` / `orgId` / `workspaceId`. Never returns a partial
+ * credential — the caller either gets a fully-populated `DeepLakeCredentials`
+ * or a clear, typed reason it could not.
+ */
+export function loadDeepLakeCredentials(options = {}) {
+    const path = credentialsPath(options);
+    if (!existsSync(path)) {
+        throw new DeepLakeCredentialsError([`credentials file not found at ${path}`]);
+    }
+    warnIfWorldReadable(path, options);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new DeepLakeCredentialsError([`credentials file at ${path} is not valid JSON`]);
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new DeepLakeCredentialsError([`credentials file at ${path} does not contain a JSON object`]);
+    }
+    const record = parsed;
+    const missing = [];
+    if (typeof record.token !== "string" || record.token.length === 0)
+        missing.push("token");
+    if (typeof record.orgId !== "string" || record.orgId.length === 0)
+        missing.push("orgId");
+    if (typeof record.workspaceId !== "string" || record.workspaceId.length === 0)
+        missing.push("workspaceId");
+    if (missing.length > 0) {
+        throw new DeepLakeCredentialsError(missing);
+    }
+    const apiUrl = typeof record.apiUrl === "string" && record.apiUrl.length > 0 ? record.apiUrl : DEFAULT_DEEPLAKE_API_URL;
+    return {
+        apiUrl,
+        token: record.token,
+        orgId: record.orgId,
+        workspaceId: record.workspaceId,
+    };
+}
+/**
+ * Advisory (NEC-042 item 13 / AC-018l.20): warn when the token file is
+ * group- or other-readable on a POSIX platform, naming the octal mode, mirroring
+ * ssh's posture toward a loose private key. nectar is not the file's writer, so
+ * this never throws or blocks the load; it is a no-op on Windows (mode bits do
+ * not map) and when the stat itself fails.
+ */
+function warnIfWorldReadable(path, options) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32")
+        return;
+    let mode;
+    try {
+        mode = statSync(path).mode & 0o777;
+    }
+    catch {
+        return; // cannot stat; skip the advisory rather than failing the load
+    }
+    if ((mode & 0o077) === 0)
+        return; // owner-only (0600/0400): silent
+    const octal = `0${mode.toString(8).padStart(3, "0")}`;
+    const warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    warn(`nectar: ${path} is group/other-readable (mode ${octal}); this token file should be owner-only. ` +
+        `Tighten it with: chmod 600 ${path}`);
+}
+/**
+ * Redact a token for logs and errors. Never echoes a token in full: keeps the
+ * last 4 chars for correlation, masks the rest. An empty/short value collapses
+ * to a fixed mask so length isn't leaked either. Mirrors honeycomb's
+ * `redactToken` (`src/daemon/runtime/auth/credentials-store.ts:254-257`).
+ */
+export function redactToken(value) {
+    if (value.length <= 4)
+        return "****";
+    return `****${value.slice(-4)}`;
+}
+//# sourceMappingURL=deeplake-credentials.js.map

package/dist/hive-graph/deeplake-credentials.js.map

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

package/dist/hive-graph/deeplake-heal.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Heal-on-first-write for the Deep Lake adapter (PRD-005).
+ *
+ * Mirrors the missing-table branch of honeycomb's `withHeal`
+ * (`src/daemon/storage/heal.ts:286-313`), scoped down to what the
+ * hive-graph tables need: a write that fails because its table does not
+ * exist yet triggers exactly ONE create-then-retry. Any other failure
+ * (permission, connection, timeout, a genuine syntax error) propagates
+ * unchanged and never triggers a create — the same anti-mask rule honeycomb's
+ * `classifyFailure` documents: a credentials or syntax problem must never be
+ * misread as a schema gap behind a confusing CREATE attempt.
+ *
+ * Column healing (honeycomb's `healColumns` / `ALTER TABLE ADD COLUMN`) is now
+ * ported for the additive case (PRD-018i / NEC-018): a write whose statement
+ * references a column the live table does not carry yet (an additive nullable
+ * column added to the catalog after CREATE, e.g. `embed_model`) triggers exactly
+ * ONE `ALTER TABLE ADD COLUMN`-then-retry, mirroring the missing-table branch.
+ * Any other failure still propagates unhealed.
+ */
+import type { CatalogTable } from "./schema.js";
+import type { DeepLakeRow } from "./deeplake-transport.js";
+import { TransportError } from "./deeplake-transport.js";
+/**
+ * The minimal shape `withHeal` needs from a transport: one method that runs a
+ * SQL statement. `HttpDeepLakeTransport` satisfies this structurally (its
+ * `query` method is public even though its connection fields are private), so
+ * production callers pass it directly; a test can pass a plain fake object
+ * with a `query` method instead, without needing to construct a real
+ * `HttpDeepLakeTransport` or reach for a mocking library (nectar has
+ * none, by design).
+ */
+export interface QueryRunner {
+    query(sql: string): Promise<DeepLakeRow[]>;
+}
+/**
+ * Classify a `query`-kind `TransportError` message as a missing-table failure
+ * (mirrors honeycomb's `classifyFailure`, `src/daemon/storage/heal.ts:77-98`,
+ * missing-table branch only). Auth/permission failures are excluded first so a
+ * message that happens to mention a relation is never misread as a schema gap.
+ */
+export declare function isMissingTableError(err: TransportError): boolean;
+/**
+ * Extract the missing-column name from a `query`-kind `TransportError`, or null
+ * when the message is not a missing-column failure. Auth/permission failures are
+ * excluded first (same anti-mask rule as {@link isMissingTableError}) so a
+ * message that happens to mention a column is never misread as a schema gap.
+ * Recognizes the common phrasings across SQL backends (`column "x" does not
+ * exist`, `no such column: x`, `unknown column 'x'`, `undefined column: x`).
+ */
+export declare function missingColumnName(err: TransportError): string | null;
+/**
+ * Run a write, healing the two additive schema gaps EXACTLY ONCE each:
+ *   - a missing-table failure -> CREATE the table (IF NOT EXISTS) and retry;
+ *   - a missing-column failure whose column is a nullable additive column in
+ *     `table` -> `ALTER TABLE ADD COLUMN` and retry (PRD-018i / NEC-018).
+ * Any other failure (or a success) returns/throws immediately and unhealed. A
+ * second failure after a heal propagates without a further retry (no loop).
+ *
+ * `runWrite` is the original statement's thunk so the retry re-issues the
+ * identical write.
+ */
+export declare function withHeal(transport: QueryRunner, table: CatalogTable, runWrite: () => Promise<DeepLakeRow[]>): Promise<DeepLakeRow[]>;
+//# sourceMappingURL=deeplake-heal.d.ts.map

package/dist/hive-graph/deeplake-heal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplake-heal.d.ts","sourceRoot":"","sources":["../../src/hive-graph/deeplake-heal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,aAAa,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAahE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CA6BpE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,GACrC,OAAO,CAAC,WAAW,EAAE,CAAC,CAwCxB"}