@gamaze/hicortex 0.4.3 → 0.4.5

package/dist/claude-md.d.ts

@@ -18,10 +18,10 @@ export declare function injectLessons(db: Database.Database, options?: {
     claudeMdPath?: string;
     stateDir?: string;
     project?: string;
-}): {
+}): Promise<{
     lessonsCount: number;
     path: string;
-};
+}>;
 /**
  * Remove the Hicortex Learnings block from CLAUDE.md.
  * Used by the uninstall command.

package/dist/claude-md.js

@@ -49,7 +49,8 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
 const storage = __importStar(require("./storage.js"));
-const license_js_1 = require("./license.js");
+const features_js_1 = require("./features.js");
+const extensions_js_1 = require("./extensions.js");
 const START_MARKER = "<!-- HICORTEX-LEARNINGS:START -->";
 const END_MARKER = "<!-- HICORTEX-LEARNINGS:END -->";
 const DEFAULT_CLAUDE_MD = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "CLAUDE.md");
@@ -58,15 +59,16 @@ const DEFAULT_CLAUDE_MD = (0, node_path_1.join)((0, node_os_1.homedir)(), ".clau
  * Creates the file if it doesn't exist.
  * Replaces existing block if present, appends if not.
  */
-function injectLessons(db, options = {}) {
+async function injectLessons(db, options = {}) {
     const claudeMdPath = options.claudeMdPath ?? DEFAULT_CLAUDE_MD;
-    const stateDir = options.stateDir ?? (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
     // Determine limits based on license
-    const features = (0, license_js_1.getFeatures)(stateDir);
-    const maxLessons = features.maxMemories === -1 ? 10 : 5;
+    const maxLessons = (0, features_js_1.lessonsLimit)();
     // --- Lessons ---
     const lessons = storage.getLessons(db, 30, options.project);
-    const selected = lessons.slice(0, maxLessons);
+    const selected = await (0, extensions_js_1.getLessonSelector)().select(lessons, {
+        maxLessons,
+        project: options.project,
+    });
     const lessonLines = selected.map((l) => {
         const titleMatch = l.content.match(/## Lesson: (.+)/);
         const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);

package/dist/consolidate.js

@@ -43,13 +43,11 @@ exports.parseJsonLenient = parseJsonLenient;
 exports.runConsolidation = runConsolidation;
 exports.msUntilHour = msUntilHour;
 exports.scheduleConsolidation = scheduleConsolidation;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const node_os_1 = require("node:os");
 const retrieval_js_1 = require("./retrieval.js");
 const storage = __importStar(require("./storage.js"));
 const prompts_js_1 = require("./prompts.js");
-const LAST_CONSOLIDATED_PATH = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex", "last-consolidated.txt");
+const features_js_1 = require("./features.js");
+const state_js_1 = require("./state.js");
 // Default config constants (matching Python config.py)
 const CONSOLIDATE_MAX_LLM_CALLS = 200;
 const CONSOLIDATE_PRUNE_MIN_AGE_DAYS = 90;
@@ -130,12 +128,7 @@ function parseJsonLenient(text, fallback) {
 // Stage 1: Pre-check
 // ---------------------------------------------------------------------------
 function readLastConsolidated() {
-    try {
-        return (0, node_fs_1.readFileSync)(LAST_CONSOLIDATED_PATH, "utf-8").trim();
-    }
-    catch {
-        return "";
-    }
+    return (0, state_js_1.loadState)().lastConsolidated ?? "";
 }
 function stagePrecheck(db) {
     const lastTs = readLastConsolidated();
@@ -273,10 +266,8 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
             };
             try {
                 // Check memory cap before storing lesson
-                const { getFeatures } = await import("./license.js");
-                const features = getFeatures("");
-                if (features.maxMemories > 0 && storage.countMemories(db) >= features.maxMemories) {
-                    console.log(`[hicortex] Free tier limit (${features.maxMemories} memories). ` +
+                if ((0, features_js_1.memoryCapReached)(storage.countMemories(db))) {
+                    console.log(`[hicortex] Free tier limit (${(0, features_js_1.maxMemoriesAllowed)()} memories). ` +
                         `Existing memories and lessons still work. New lessons won't be saved. ` +
                         `Upgrade for unlimited usage: https://hicortex.gamaze.com/`);
                     break;
@@ -445,14 +436,10 @@ async function runConsolidation(db, llm, embedFn, dryRun = false) {
     }
     // Update last-consolidated timestamp
     if (!dryRun && report.status === "completed") {
-        try {
-            const dir = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "memory");
-            (0, node_fs_1.mkdirSync)(dir, { recursive: true });
-            (0, node_fs_1.writeFileSync)(LAST_CONSOLIDATED_PATH, new Date().toISOString());
-        }
-        catch {
-            // Non-fatal
-        }
+        (0, state_js_1.updateState)((s) => {
+            s.lastConsolidated = new Date().toISOString();
+            return s;
+        });
     }
     report.budget = budget.summary();
     report.completed_at = new Date().toISOString();

package/dist/db.d.ts

@@ -18,6 +18,8 @@ export declare function resolveDbPath(override?: string): string;
  * Returns the open Database instance (caller manages lifetime).
  */
 export declare function initDb(dbPath: string): Database.Database;
+/** Read the currently-applied schema version. Returns 0 if no migrations applied. */
+export declare function getSchemaVersion(db: Database.Database): number;
 /**
  * Return database statistics.
  */

package/dist/db.js

@@ -9,6 +9,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveDbPath = resolveDbPath;
 exports.initDb = initDb;
+exports.getSchemaVersion = getSchemaVersion;
 exports.getStats = getStats;
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const node_fs_1 = require("node:fs");
@@ -175,18 +176,96 @@ function initDb(dbPath) {
     return db;
 }
 /**
- * Apply schema migrations for existing databases.
+ * Helper: check if a column exists on a table without aborting.
+ * Used by migrations to stay idempotent across partially-migrated databases.
+ */
+function hasColumn(db, table, column) {
+    const cols = db.pragma(`table_info(${table})`);
+    return cols.some((c) => c.name === column);
+}
+/**
+ * Migrations are append-only. Add new entries at the end with monotonically
+ * increasing version numbers. Each migration runs in a single transaction
+ * and the schema_version row is inserted only on success.
+ *
+ * IMPORTANT: never edit a migration after it has shipped — write a new one.
+ *
+ * IMPORTANT: sqlite-vec virtual tables (memory_vectors) and FTS5 virtual
+ * tables (memories_fts) cannot be ALTER'd. If a future Pro feature needs
+ * per-vector metadata, add a sidecar table and JOIN, do not try to extend
+ * the virtual table in place.
+ */
+const MIGRATIONS = [
+    {
+        version: 1,
+        name: "add_ingested_at",
+        up: (db) => {
+            if (!hasColumn(db, "memories", "ingested_at")) {
+                db.exec("ALTER TABLE memories ADD COLUMN ingested_at TIMESTAMP");
+                db.exec("UPDATE memories SET ingested_at = created_at WHERE ingested_at IS NULL");
+            }
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memories_ingested ON memories(ingested_at)");
+        },
+    },
+    {
+        version: 2,
+        name: "add_updated_at",
+        up: (db) => {
+            if (!hasColumn(db, "memories", "updated_at")) {
+                db.exec("ALTER TABLE memories ADD COLUMN updated_at TIMESTAMP");
+            }
+        },
+    },
+];
+/**
+ * Run all pending migrations against the database.
+ *
+ * Creates the schema_version tracking table if missing, then applies any
+ * migration whose version > the current max. Each migration runs inside its
+ * own transaction so a partial failure rolls back cleanly. Existing databases
+ * with the relevant columns already present pass through as no-ops because
+ * each migration's up() is idempotent.
  */
 function migrate(db) {
-    const cols = db.pragma("table_info(memories)");
-    const colNames = new Set(cols.map((c) => c.name));
-    if (!colNames.has("ingested_at")) {
-        db.exec("ALTER TABLE memories ADD COLUMN ingested_at TIMESTAMP");
-        db.exec("UPDATE memories SET ingested_at = created_at");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_memories_ingested ON memories(ingested_at)");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_version (
+      version INTEGER PRIMARY KEY,
+      name TEXT NOT NULL,
+      applied_at TEXT NOT NULL
+    );
+  `);
+    const row = db
+        .prepare("SELECT MAX(version) as v FROM schema_version")
+        .get();
+    const currentVersion = row.v ?? 0;
+    const pending = MIGRATIONS.filter((m) => m.version > currentVersion);
+    if (pending.length === 0)
+        return;
+    for (const m of pending) {
+        const tx = db.transaction(() => {
+            m.up(db);
+            db.prepare("INSERT INTO schema_version (version, name, applied_at) VALUES (?, ?, ?)").run(m.version, m.name, new Date().toISOString());
+        });
+        try {
+            tx();
+            console.log(`[hicortex] Applied migration ${m.version}: ${m.name}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Migration ${m.version} (${m.name}) failed: ${msg}`);
+        }
     }
-    if (!colNames.has("updated_at")) {
-        db.exec("ALTER TABLE memories ADD COLUMN updated_at TIMESTAMP");
+}
+/** Read the currently-applied schema version. Returns 0 if no migrations applied. */
+function getSchemaVersion(db) {
+    try {
+        const row = db
+            .prepare("SELECT MAX(version) as v FROM schema_version")
+            .get();
+        return row.v ?? 0;
+    }
+    catch {
+        return 0;
     }
 }
 /**

package/dist/extensions.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Extension interfaces for the OSS/Pro split.
+ *
+ * The OSS client defines these interfaces and ships default implementations
+ * (the current behaviour). Pro features (in src/pro/, never published) provide
+ * alternative implementations that are loaded at runtime via dynamic import,
+ * gated by the license check in features.ts.
+ *
+ * Why these specific interfaces:
+ *
+ *   LessonSelector — there are exactly 3 lesson selection sites in the OSS
+ *     code (claude-md.ts:injectLessons, index.ts:before_agent_start,
+ *     nightly.ts:injectLessonsFromServer). All three currently do
+ *     `lessons.slice(0, maxLessons)` after a DB or HTTP fetch. The Pro
+ *     selector ranks lessons against project context, recency, and
+ *     effectiveness scores instead of dumb-truncating.
+ *
+ *   PromptStrategy — the current prompts.ts exports three pure functions
+ *     (distillation, reflection, importanceScoring). The Pro variant has
+ *     prescriptive prompts (`when X do Y` format) and re-trained reflection
+ *     that produces a richer schema. The strategy bundles the prompt WITH
+ *     its parser so a Pro prompt with a different output schema cannot
+ *     silently fail when the OSS consumer parses it with the wrong shape.
+ *
+ * NOT in this file (deliberately deferred):
+ *   - ContextAssembler — over-abstracted; the real seam is buildProjectContext
+ *     in claude-md.ts, not the whole assembler. Will add when needed.
+ *   - LessonValidator — speculative; no validation exists today. Will add
+ *     when the first Pro use case demands it.
+ */
+/**
+ * Minimum fields a lesson must have for the selector to work.
+ *
+ * The default selector only needs `content`. Pro selectors may need more
+ * (project for in-project weighting, base_strength for ranking, etc.).
+ *
+ * Memory satisfies this interface (it's a structural subset), and the
+ * client-mode HTTP shape `{content, created_at, base_strength, access_count}`
+ * also satisfies it. The selector is generic over T so call sites get back
+ * the same shape they passed in.
+ */
+export interface SelectableLesson {
+    content: string;
+    project?: string | null;
+    created_at?: string;
+    base_strength?: number;
+    access_count?: number;
+    id?: string;
+    memory_type?: string;
+}
+export interface LessonSelectorContext {
+    /** Maximum number of lessons to return. Caller decides this from features.lessonsLimit(). */
+    maxLessons: number;
+    /** Current project, if known. Pro selectors weight in-project lessons higher. */
+    project?: string | null;
+    /** Optional: agent id, for cross-agent learning context (Pro). */
+    agentId?: string;
+    /** Optional: current task description, for relevance scoring (Pro). */
+    currentTask?: string;
+}
+export interface LessonSelector {
+    /**
+     * Pick `ctx.maxLessons` lessons from the candidate pool.
+     * Default impl: take the first N (caller passes them in priority order).
+     * Pro impl: rank by relevance to ctx.project / ctx.currentTask / effectiveness.
+     *
+     * Generic so the output type matches the input type — Memory[] in returns
+     * Memory[] out, partial-shape in returns partial-shape out.
+     */
+    select<T extends SelectableLesson>(lessons: T[], ctx: LessonSelectorContext): T[] | Promise<T[]>;
+}
+/**
+ * Default LessonSelector — preserves current OSS behaviour exactly.
+ * `slice(0, maxLessons)` over the candidate pool, no re-ranking.
+ */
+export declare const defaultLessonSelector: LessonSelector;
+/** Output schema produced by the reflection prompt and consumed by consolidate.ts. */
+export interface ReflectionLesson {
+    lesson: string;
+    type: "reinforce" | "correct" | "principle" | string;
+    project: string;
+    severity: "critical" | "important" | "minor" | string;
+    confidence: "high" | "medium" | "low" | string;
+    source_pattern?: string;
+}
+export interface PromptStrategy {
+    /** Build the distillation prompt (transcript → memories). */
+    distillation(project: string, date: string, transcript: string): string;
+    /** Build the reflection prompt (recent memories → lessons). */
+    reflection(memoriesBlock: string, recentLessons?: string): string;
+    /** Build the importance scoring prompt (batch of memories → scores). */
+    importanceScoring(memoriesBlock: string): string;
+    /**
+     * Parse the LLM's reflection output. Bundled with the prompt so a Pro prompt
+     * with a different output schema cannot silently fail downstream.
+     */
+    parseReflection(raw: string): ReflectionLesson[];
+    /**
+     * Parse the LLM's importance scoring output.
+     * @param raw The LLM response
+     * @param expectedCount The number of memories scored — used to pad/trim
+     * @returns Array of scores (length === expectedCount), each in [0, 1]
+     */
+    parseImportanceScores(raw: string, expectedCount: number): number[];
+}
+export declare const defaultPromptStrategy: PromptStrategy;
+/**
+ * Holder for the active extension implementations. The OSS client always uses
+ * the defaults; Pro features (in src/pro/, loaded via dynamic import) replace
+ * these at boot if a valid license is present.
+ *
+ * Wiring will happen via setExtensions() called from src/pro/ after license
+ * validation (not yet implemented in OSS). Until Pro code exists and is loaded,
+ * every call site uses the defaults — zero behavioural change for OSS users.
+ */
+declare let activeExtensions: {
+    selector: LessonSelector;
+    prompts: PromptStrategy;
+};
+/** Replace the active extensions (called from features.ts when Pro loads). */
+export declare function setExtensions(ext: Partial<typeof activeExtensions>): void;
+/** Get the active LessonSelector (default unless Pro is loaded). */
+export declare function getLessonSelector(): LessonSelector;
+/** Get the active PromptStrategy (default unless Pro is loaded). */
+export declare function getPromptStrategy(): PromptStrategy;
+export {};

package/dist/extensions.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Extension interfaces for the OSS/Pro split.
+ *
+ * The OSS client defines these interfaces and ships default implementations
+ * (the current behaviour). Pro features (in src/pro/, never published) provide
+ * alternative implementations that are loaded at runtime via dynamic import,
+ * gated by the license check in features.ts.
+ *
+ * Why these specific interfaces:
+ *
+ *   LessonSelector — there are exactly 3 lesson selection sites in the OSS
+ *     code (claude-md.ts:injectLessons, index.ts:before_agent_start,
+ *     nightly.ts:injectLessonsFromServer). All three currently do
+ *     `lessons.slice(0, maxLessons)` after a DB or HTTP fetch. The Pro
+ *     selector ranks lessons against project context, recency, and
+ *     effectiveness scores instead of dumb-truncating.
+ *
+ *   PromptStrategy — the current prompts.ts exports three pure functions
+ *     (distillation, reflection, importanceScoring). The Pro variant has
+ *     prescriptive prompts (`when X do Y` format) and re-trained reflection
+ *     that produces a richer schema. The strategy bundles the prompt WITH
+ *     its parser so a Pro prompt with a different output schema cannot
+ *     silently fail when the OSS consumer parses it with the wrong shape.
+ *
+ * NOT in this file (deliberately deferred):
+ *   - ContextAssembler — over-abstracted; the real seam is buildProjectContext
+ *     in claude-md.ts, not the whole assembler. Will add when needed.
+ *   - LessonValidator — speculative; no validation exists today. Will add
+ *     when the first Pro use case demands it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultPromptStrategy = exports.defaultLessonSelector = void 0;
+exports.setExtensions = setExtensions;
+exports.getLessonSelector = getLessonSelector;
+exports.getPromptStrategy = getPromptStrategy;
+/**
+ * Default LessonSelector — preserves current OSS behaviour exactly.
+ * `slice(0, maxLessons)` over the candidate pool, no re-ranking.
+ */
+exports.defaultLessonSelector = {
+    select(lessons, ctx) {
+        return lessons.slice(0, ctx.maxLessons);
+    },
+};
+// ---------------------------------------------------------------------------
+// Default PromptStrategy — wraps the current prompts.ts and the lenient JSON
+// parser from consolidate.ts. Preserves current OSS behaviour exactly.
+// ---------------------------------------------------------------------------
+const prompts_js_1 = require("./prompts.js");
+/**
+ * Lenient JSON parser — tolerates markdown fences and indexed list formats.
+ * Extracted from consolidate.ts to keep prompt+parser together.
+ */
+function parseJsonLenient(text, fallback) {
+    text = text.trim();
+    // Strip markdown code fences
+    if (text.startsWith("```")) {
+        const lines = text.split("\n");
+        const stripped = lines.slice(1);
+        if (stripped.length > 0 && stripped[stripped.length - 1].trim() === "```") {
+            stripped.pop();
+        }
+        text = stripped.join("\n").trim();
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Fall through
+    }
+    // Handle "[0] 0.7\n[1] 0.6\n..." indexed format
+    const indexed = [...text.matchAll(/\[\d+\]\s*([\d.]+)/g)];
+    if (indexed.length > 0) {
+        try {
+            return indexed.map((m) => parseFloat(m[1]));
+        }
+        catch {
+            // Fall through
+        }
+    }
+    return fallback;
+}
+exports.defaultPromptStrategy = {
+    distillation: prompts_js_1.distillation,
+    reflection: prompts_js_1.reflection,
+    importanceScoring: prompts_js_1.importanceScoring,
+    parseReflection(raw) {
+        const parsed = parseJsonLenient(raw, []);
+        if (!Array.isArray(parsed))
+            return [];
+        const out = [];
+        for (const item of parsed) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const lo = item;
+            const lessonText = String(lo.lesson ?? "");
+            if (!lessonText)
+                continue;
+            out.push({
+                lesson: lessonText,
+                type: String(lo.type ?? "principle"),
+                project: String(lo.project ?? "global"),
+                severity: String(lo.severity ?? "important"),
+                confidence: String(lo.confidence ?? "medium"),
+                source_pattern: lo.source_pattern ? String(lo.source_pattern) : undefined,
+            });
+        }
+        return out;
+    },
+    parseImportanceScores(raw, expectedCount) {
+        let scores = parseJsonLenient(raw, null);
+        if (!Array.isArray(scores)) {
+            scores = new Array(expectedCount).fill(0.5);
+        }
+        while (scores.length < expectedCount)
+            scores.push(0.5);
+        scores = scores.slice(0, expectedCount);
+        return scores.map((s) => {
+            const v = Number(s);
+            if (isNaN(v))
+                return 0.5;
+            return Math.max(0, Math.min(1, v));
+        });
+    },
+};
+// ---------------------------------------------------------------------------
+// Loader — used by call sites to get either the OSS default or a Pro override
+// ---------------------------------------------------------------------------
+/**
+ * Holder for the active extension implementations. The OSS client always uses
+ * the defaults; Pro features (in src/pro/, loaded via dynamic import) replace
+ * these at boot if a valid license is present.
+ *
+ * Wiring will happen via setExtensions() called from src/pro/ after license
+ * validation (not yet implemented in OSS). Until Pro code exists and is loaded,
+ * every call site uses the defaults — zero behavioural change for OSS users.
+ */
+let activeExtensions = {
+    selector: exports.defaultLessonSelector,
+    prompts: exports.defaultPromptStrategy,
+};
+/** Replace the active extensions (called from features.ts when Pro loads). */
+function setExtensions(ext) {
+    activeExtensions = { ...activeExtensions, ...ext };
+}
+/** Get the active LessonSelector (default unless Pro is loaded). */
+function getLessonSelector() {
+    return activeExtensions.selector;
+}
+/** Get the active PromptStrategy (default unless Pro is loaded). */
+function getPromptStrategy() {
+    return activeExtensions.prompts;
+}

package/dist/features.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Centralized feature gating — single source of truth for tier-dependent values.
+ *
+ * Why this exists:
+ *   - getFeatures() in license.ts was sync but validateLicense was async, creating
+ *     a race where Pro users got free-tier features during the validation window.
+ *   - License checks were scattered across 8+ call sites with subtly different
+ *     handling (e.g., consolidate.ts:308 had a dynamic import in a hot loop to
+ *     dodge a circular import).
+ *
+ * All feature decisions now flow through this module. Call initFeatures() once at
+ * process boot before serving any requests; sync getters become deterministic.
+ */
+import type { LicenseInfo } from "./types.js";
+/**
+ * Initialize the feature cache. Call ONCE at process boot before any feature
+ * gating queries. Race fix:
+ *   1. Synchronously load persisted tier from disk (instant, deterministic)
+ *   2. If no persisted tier and we have a key, AWAIT first validation
+ *   3. If persisted tier exists, kick off background re-validation
+ *
+ * After this returns, sync getters (isPro, lessonsLimit, etc.) are deterministic
+ * and reflect the user's actual tier — no more "free during validation window".
+ */
+export declare function initFeatures(licenseKey: string | undefined, stateDir?: string): Promise<void>;
+/** Are we on a paid tier (Pro, Team, Lifetime)? */
+export declare function isPro(): boolean;
+/** Memory count cap. -1 = unlimited (paid). */
+export declare function maxMemoriesAllowed(): number;
+/** Has the memory cap been hit? Pass current count from caller. */
+export declare function memoryCapReached(currentCount: number): boolean;
+/** Number of lessons to inject into CLAUDE.md / before_agent_start. */
+export declare function lessonsLimit(): number;
+/** Is remote /ingest allowed? Free + Team yes, Pro (single-machine) no. */
+export declare function remoteIngestAllowed(): boolean;
+/** Direct read of the underlying features (for callers that need the full record). */
+export declare function getCurrentFeatures(): LicenseInfo["features"];

package/dist/features.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Centralized feature gating — single source of truth for tier-dependent values.
+ *
+ * Why this exists:
+ *   - getFeatures() in license.ts was sync but validateLicense was async, creating
+ *     a race where Pro users got free-tier features during the validation window.
+ *   - License checks were scattered across 8+ call sites with subtly different
+ *     handling (e.g., consolidate.ts:308 had a dynamic import in a hot loop to
+ *     dodge a circular import).
+ *
+ * All feature decisions now flow through this module. Call initFeatures() once at
+ * process boot before serving any requests; sync getters become deterministic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initFeatures = initFeatures;
+exports.isPro = isPro;
+exports.maxMemoriesAllowed = maxMemoriesAllowed;
+exports.memoryCapReached = memoryCapReached;
+exports.lessonsLimit = lessonsLimit;
+exports.remoteIngestAllowed = remoteIngestAllowed;
+exports.getCurrentFeatures = getCurrentFeatures;
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const license_js_1 = require("./license.js");
+const state_js_1 = require("./state.js");
+const DEFAULT_STATE_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
+const FREE_FEATURES = {
+    reflection: true,
+    vectorSearch: true,
+    maxMemories: 250,
+    crossAgent: true,
+    remoteIngest: true,
+};
+let currentFeatures = FREE_FEATURES;
+let initialized = false;
+function persistTier(stateDir, info) {
+    (0, state_js_1.updateState)((s) => {
+        s.tier = {
+            tier: info.tier,
+            validatedAt: new Date().toISOString(),
+            features: info.features,
+        };
+        return s;
+    }, stateDir);
+}
+/**
+ * Initialize the feature cache. Call ONCE at process boot before any feature
+ * gating queries. Race fix:
+ *   1. Synchronously load persisted tier from disk (instant, deterministic)
+ *   2. If no persisted tier and we have a key, AWAIT first validation
+ *   3. If persisted tier exists, kick off background re-validation
+ *
+ * After this returns, sync getters (isPro, lessonsLimit, etc.) are deterministic
+ * and reflect the user's actual tier — no more "free during validation window".
+ */
+async function initFeatures(licenseKey, stateDir = DEFAULT_STATE_DIR) {
+    if (initialized)
+        return;
+    initialized = true;
+    // Step 1: Load persisted tier from state.json (instant)
+    const persisted = (0, state_js_1.loadState)(stateDir).tier;
+    if (persisted) {
+        currentFeatures = persisted.features;
+    }
+    else {
+        currentFeatures = FREE_FEATURES;
+    }
+    // Step 2: No key → free tier, done
+    if (!licenseKey)
+        return;
+    // Step 3: Validate
+    if (!persisted) {
+        // First-time: AWAIT validation so the very first request sees the right tier
+        try {
+            const info = await (0, license_js_1.validateLicense)(licenseKey, stateDir);
+            currentFeatures = info.features;
+            if (info.valid) {
+                persistTier(stateDir, info);
+            }
+        }
+        catch {
+            // Validation failed (network, etc.) — stay on free
+        }
+    }
+    else {
+        // Already have a persisted tier; re-validate in background
+        (0, license_js_1.validateLicense)(licenseKey, stateDir)
+            .then((info) => {
+            currentFeatures = info.features;
+            if (info.valid) {
+                persistTier(stateDir, info);
+            }
+        })
+            .catch(() => {
+            // Keep persisted features
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API — sync getters used everywhere in the codebase
+// ---------------------------------------------------------------------------
+/** Are we on a paid tier (Pro, Team, Lifetime)? */
+function isPro() {
+    return currentFeatures.maxMemories === -1;
+}
+/** Memory count cap. -1 = unlimited (paid). */
+function maxMemoriesAllowed() {
+    return currentFeatures.maxMemories;
+}
+/** Has the memory cap been hit? Pass current count from caller. */
+function memoryCapReached(currentCount) {
+    const max = maxMemoriesAllowed();
+    return max > 0 && currentCount >= max;
+}
+/** Number of lessons to inject into CLAUDE.md / before_agent_start. */
+function lessonsLimit() {
+    return isPro() ? 20 : 10;
+}
+/** Is remote /ingest allowed? Free + Team yes, Pro (single-machine) no. */
+function remoteIngestAllowed() {
+    return currentFeatures.remoteIngest !== false;
+}
+/** Direct read of the underlying features (for callers that need the full record). */
+function getCurrentFeatures() {
+    return currentFeatures;
+}