@nac3/forge-cli 0.2.0-alpha.4 → 0.2.0-alpha.59z.118

package/dist/core/cost_router.js

@@ -0,0 +1,465 @@
+/**
+ * Cost router -- which brain (provider + model + key) services a
+ * given chat turn (alpha.51 + smart-auto alpha.55).
+ *
+ * Inputs:
+ *   - The verb id the LLM is about to / has just invoked (when
+ *     known).
+ *   - The current workflow.state phase (when readable).
+ *   - User override via slash command (`/eco` / `/frontier`).
+ *   - The user message text (when present, enables smart-auto:
+ *     reasoning_gate + turn_classifier).
+ *
+ * Output:
+ *   - { tier, provider, model, api_key, reason, runtime_wired,
+ *       gate_signals?, classifier_signals?, classifier_used? }.
+ *
+ * Decision algorithm (alpha.55):
+ *
+ *   1. If the user typed `/eco` or `/frontier` for THIS turn,
+ *      honour it. Highest priority.
+ *   2. If we know the verb id and the verb-tier map says
+ *      'frontier', use frontier. Same for 'eco'.
+ *   3. If we can read workflow.state and the user is in
+ *      FRONTIER_WORKFLOW_PHASES (phase_iii, phase_v), use
+ *      frontier.
+ *   4. Otherwise (smart-auto path):
+ *      a. Run reasoning_gate.classifyGate(text). Fast, no LLM.
+ *      b. If gate.confidence > 0.85 -> use gate.tier (skip classifier).
+ *      c. If gate.ambiguous -> run turn_classifier.classifyTurn()
+ *         which calls Gemini (eco) for a verdict. The classifier
+ *         is FAILSAFE: any error falls back to the gate tier.
+ *      d. Final tier = result.
+ *   5. If after picking a tier the API key is NOT in the vault
+ *      OR the provider is not yet wired (alpha.55 -- anthropic
+ *      + google_ai), the router logs that fact so the chat
+ *      caller can fall back to the default Anthropic client.
+ *
+ * Logging:
+ *   ~/.yujin-forge/brain_routing.jsonl -- one line per decision
+ *   so we can audit how often eco vs frontier was picked. Same
+ *   redaction rules as nac3 dispatch log.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { readBrainConfig, vaultSlotForProvider, } from './brain_config.js';
+import { getKey } from './provider_keys.js';
+import { getVerbTier, FRONTIER_WORKFLOW_PHASES, } from '../nac3/verb_tier_map.js';
+import { classifyGate } from './reasoning_gate.js';
+import { classifyTurn } from './turn_classifier.js';
+/** alpha.59z.7 -- heuristic: does the user text look like a
+ *  request to violate one of the active SQ rules? Catches the
+ *  most common patterns where the user pushes Forge to skip
+ *  tests, ignore docs, etc. False positives are cheap (we just
+ *  escalate to frontier); false negatives let the eco brain
+ *  capitulate. */
+export function looksLikeRuleViolation(userText) {
+    if (!userText)
+        return { hit: false };
+    const lower = userText.toLowerCase();
+    const patterns = [
+        { re: /\b(no escribas|sin)\s+tests?\b/, tag: 'skip-tests-es' },
+        { re: /\b(skip|no)\s+tests?\b/, tag: 'skip-tests-en' },
+        { re: /\bsin\s+cover(age)?\b/, tag: 'skip-coverage-es' },
+        { re: /\bsin\s+docs?\b/, tag: 'skip-docs-es' },
+        { re: /\bskip\s+(docs?|documentaci)/, tag: 'skip-docs-en' },
+        { re: /\b(no|sin)\s+(audit|auditor)/, tag: 'skip-audit' },
+        { re: /\bsalt[ae]r?\s+(los|las)?\s*(tests?|docs|valid)/, tag: 'salta-checks' },
+        { re: /\b(va con prisa|tengo prisa|deadline|urgent)/, tag: 'time-pressure' },
+        { re: /\b(direct(amente)?|just ship|ship it)\b/, tag: 'ship-direct' },
+        { re: /\bp[eé]gam?e?\s+(la|el|mi)?\s*(api|secret|key|token)/, tag: 'paste-secret' },
+    ];
+    for (const p of patterns) {
+        if (p.re.test(lower))
+            return { hit: true, pattern: p.tag };
+    }
+    return { hit: false };
+}
+/** alpha.59z.7 -- heuristic: does the user text suggest a phase
+ *  cross-over (e.g. asking to revisit a prior phase, jump
+ *  forward, change an approved doc)? */
+export function looksLikePhaseCrossover(userText, workflowPhase) {
+    if (!userText)
+        return { hit: false };
+    const lower = userText.toLowerCase();
+    const patterns = [
+        { re: /\b(revis(ar|emos)|discut(ir|amos)|cambi[ae]r)\b.{0,40}\b(rfp|arch|design|spec)\b/, tag: 'revisit-spec' },
+        { re: /\b(volv[ae]mos|retroced[ae]mos)\s+a\b/, tag: 'go-back' },
+        { re: /\b(jump|salt(emos|amos|a|e|ar|emos|en)?)\s+(al?|to)\s+(deploy|prod|ship)/, tag: 'jump-forward' },
+        { re: /\bcost\s+cap\b/, tag: 'cost-cap-revisit' },
+        { re: /\b(approve|aprobar)\s+(otro|another|early)/, tag: 'force-approve' },
+    ];
+    for (const p of patterns) {
+        if (p.re.test(lower))
+            return { hit: true, pattern: p.tag };
+    }
+    void workflowPhase; /* reserved for phase-specific heuristics */
+    return { hit: false };
+}
+/** Providers wired with a runtime client. Must stay in sync with
+ *  the `makeUnifiedClient` switch in
+ *  src/llm/multi_provider_client.ts. */
+const RUNTIME_WIRED = new Set([
+    'anthropic', 'google_ai', 'openai', 'deepseek',
+    'xai', 'mistral', 'cohere',
+    'yujin_managed',
+]);
+function brainLogPath() {
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const base = process.env.YF_CONFIG_DIR || path.join(home, '.yujin-forge');
+    return path.join(base, 'brain_routing.jsonl');
+}
+async function logDecision(entry) {
+    try {
+        const p = brainLogPath();
+        await fs.mkdir(path.dirname(p), { recursive: true });
+        await fs.appendFile(p, JSON.stringify({ ts: new Date().toISOString(), ...entry }) + '\n', 'utf-8');
+    }
+    catch {
+        /* swallow -- routing must not depend on log durability */
+    }
+}
+/**
+ * Synchronous tier decision for the cheap paths (user_override,
+ * verb_tier, workflow_phase). Returns null when none of these
+ * apply -- the caller should run the smart-auto path
+ * (gate + classifier).
+ */
+function decideCheapTier(ctx, _cfg) {
+    if (ctx.user_override === 'frontier') {
+        return { tier: 'frontier', reason: 'user slash command /frontier' };
+    }
+    if (ctx.user_override === 'eco') {
+        return { tier: 'eco', reason: 'user slash command /eco' };
+    }
+    if (ctx.verb_id) {
+        const t = getVerbTier(ctx.verb_id);
+        if (t === 'frontier') {
+            return { tier: 'frontier', reason: 'verb_tier_map[' + ctx.verb_id + '] = frontier' };
+        }
+        if (t === 'eco') {
+            return { tier: 'eco', reason: 'verb_tier_map[' + ctx.verb_id + '] = eco' };
+        }
+        /* 'mixto' falls through to smart-auto. */
+    }
+    if (ctx.workflow_phase && FRONTIER_WORKFLOW_PHASES.includes(ctx.workflow_phase)) {
+        return { tier: 'frontier', reason: 'workflow_phase=' + ctx.workflow_phase + ' is frontier-required' };
+    }
+    return null;
+}
+/**
+ * Legacy synchronous decideTier (kept for callers that have no
+ * user_text). Equivalent to decideCheapTier with a fallback to
+ * the configured default. Used by tests.
+ */
+export function decideTier(ctx, cfg) {
+    const cheap = decideCheapTier(ctx, cfg);
+    if (cheap)
+        return cheap;
+    return {
+        tier: cfg.chat_default_tier,
+        reason: 'default chat tier=' + cfg.chat_default_tier + (ctx.caller_hint ? ' (' + ctx.caller_hint + ')' : ''),
+    };
+}
+/**
+ * Run the smart-auto path: reasoning_gate first, then
+ * turn_classifier if the gate is ambiguous. Returns the chosen
+ * tier + the telemetry needed for the cost log.
+ */
+async function decideSmartAutoTier(ctx, cfg) {
+    /* alpha.56 -- if the turn has any attachment (file, image,
+     *  voice note, pasted doc), route to frontier without asking
+     *  gate or classifier. The classifier only sees the user
+     *  *text* prompt -- it cannot inspect the attached content,
+     *  which can be a 600 KB design doc or a complex source file.
+     *  Misrouting that to eco gives Gemini Lite a load it cannot
+     *  reason about, and the user perceives a "the assistant
+     *  doesn't understand the doc" bug. Frontier is the safe
+     *  default whenever there is an attached payload. */
+    if (typeof ctx.attachments === 'number' && ctx.attachments > 0) {
+        const telemetry = {
+            gate_decision: 'frontier',
+            gate_confidence: 1.0,
+            gate_signals: ['attachments_force_frontier[' + ctx.attachments + ']'],
+            gate_ambiguous: false,
+            classifier_used: false,
+        };
+        return {
+            tier: 'frontier',
+            reason: 'attachments=' + ctx.attachments + ' -> frontier (no gate / classifier)',
+            telemetry,
+        };
+    }
+    /* alpha.59z.7 -- if the user text looks like a rule-violation
+     *  request AND we have active SQ rules to defend, escalate to
+     *  frontier. Brain matrix run 3 showed Haiku capitulating to
+     *  "no escribas tests" even with the imperative SQ enforcement
+     *  block. Sonnet and Gemini-with-eco-hint defend correctly,
+     *  but Haiku does not. Routing these turns to frontier closes
+     *  the gap. */
+    if (ctx.active_sq_rules && ctx.active_sq_rules.length > 0) {
+        const viol = looksLikeRuleViolation(ctx.user_text);
+        if (viol.hit) {
+            const telemetry = {
+                gate_decision: 'frontier',
+                gate_confidence: 0.95,
+                gate_signals: ['sq_rule_defense[' + (viol.pattern || '?') + ']'],
+                gate_ambiguous: false,
+                classifier_used: false,
+            };
+            return {
+                tier: 'frontier',
+                reason: 'sq_rule_defense ' + (viol.pattern || '') + ' -> frontier',
+                telemetry,
+            };
+        }
+    }
+    /* alpha.59z.7 -- phase cross-over heuristic. Eco brains do not
+     *  reliably acknowledge the active step before proposing tool
+     *  calls, even with the SCAN-FIRST imperative. When the user
+     *  request suggests a phase boundary touch, force frontier. */
+    if (ctx.phase_crossover === true
+        || looksLikePhaseCrossover(ctx.user_text, ctx.workflow_phase).hit) {
+        const tag = ctx.phase_crossover === true
+            ? 'explicit'
+            : (looksLikePhaseCrossover(ctx.user_text, ctx.workflow_phase).pattern || '?');
+        const telemetry = {
+            gate_decision: 'frontier',
+            gate_confidence: 0.92,
+            gate_signals: ['phase_crossover[' + tag + ']'],
+            gate_ambiguous: false,
+            classifier_used: false,
+        };
+        return {
+            tier: 'frontier',
+            reason: 'phase_crossover ' + tag + ' -> frontier',
+            telemetry,
+        };
+    }
+    /* alpha.56 -- if the previous turn loaded a document via a
+     *  reader / fs read verb, route to frontier. The next user
+     *  message is almost certainly going to ask the model to
+     *  reason over that doc; eco would choke. */
+    if (ctx.previous_doc_loaded === true) {
+        const telemetry = {
+            gate_decision: 'frontier',
+            gate_confidence: 0.95,
+            gate_signals: ['previous_doc_loaded'],
+            gate_ambiguous: false,
+            classifier_used: false,
+        };
+        return {
+            tier: 'frontier',
+            reason: 'previous turn loaded a doc -> frontier (no gate / classifier)',
+            telemetry,
+        };
+    }
+    const gate = classifyGate({
+        text: ctx.user_text || '',
+        attachments: ctx.attachments,
+        history: ctx.history,
+        previous_tier: ctx.previous_tier,
+    });
+    /* Telemetry baseline -- always reported. */
+    const telemetry = {
+        gate_decision: gate.tier,
+        gate_confidence: gate.confidence,
+        gate_signals: gate.signals,
+        gate_ambiguous: gate.ambiguous,
+        classifier_used: false,
+    };
+    /* Gate is confident -- skip the classifier. */
+    if (!gate.ambiguous) {
+        return {
+            tier: gate.tier,
+            reason: 'gate confident -> ' + gate.tier +
+                ' (conf=' + gate.confidence.toFixed(2) + ')',
+            telemetry,
+        };
+    }
+    /* Ambiguous -> classifier call. We resolve the eco API key via
+     * the existing slot; if missing, the classifier itself returns
+     * a fallback verdict + signals. */
+    let ecoKey = null;
+    try {
+        ecoKey = await getKey(vaultSlotForProvider(cfg.eco.provider));
+    }
+    catch {
+        ecoKey = null;
+    }
+    const cls = await classifyTurn({
+        text: ctx.user_text || '',
+        gate_tier: gate.tier,
+        previous_tier: ctx.previous_tier,
+        api_key: ecoKey,
+        model: cfg.eco.model,
+    });
+    telemetry.classifier_used = true;
+    telemetry.classifier_verdict = cls.verdict;
+    telemetry.classifier_confidence = cls.confidence;
+    telemetry.classifier_signals = cls.signals;
+    telemetry.classifier_cached = cls.cached;
+    return {
+        tier: cls.tier,
+        reason: 'smart-auto -> ' + cls.tier +
+            ' (gate=' + gate.tier + '/' + gate.confidence.toFixed(2) +
+            ', classifier=' + (cls.verdict ?? 'fallback') + '/' + cls.confidence.toFixed(2) + ')',
+        telemetry,
+    };
+}
+/**
+ * Full routing decision. Reads brain_config + vault to resolve a
+ * concrete provider+model+key. Logs the decision.
+ *
+ * alpha.55: when no cheap signal applies, runs reasoning_gate +
+ * turn_classifier for a smart-auto decision instead of falling
+ * back to the configured default tier blindly.
+ */
+export async function selectBrainForTurn(ctx = {}) {
+    const cfg = await readBrainConfig();
+    const cheap = decideCheapTier(ctx, cfg);
+    let tier;
+    let reason;
+    let smartTelemetry = null;
+    if (cheap) {
+        tier = cheap.tier;
+        reason = cheap.reason;
+    }
+    else if (typeof ctx.user_text === 'string' && ctx.user_text.length > 0) {
+        /* Smart-auto path. */
+        const r = await decideSmartAutoTier(ctx, cfg);
+        tier = r.tier;
+        reason = r.reason;
+        smartTelemetry = r.telemetry;
+    }
+    else {
+        /* No user_text + no cheap signal -- last resort, use the
+         * configured default. This path keeps back-compat with
+         * callers that did not migrate to the smart-auto API yet. */
+        tier = cfg.chat_default_tier;
+        reason = 'default chat tier=' + cfg.chat_default_tier + (ctx.caller_hint ? ' (' + ctx.caller_hint + ')' : '');
+    }
+    /* alpha.59 -- managed routing branch. When the user's plan is
+     * NOT byok_only AND the vault has a yf_server_api_key + the
+     * license cache has a user_handle, route through the managed
+     * proxy regardless of the chat_default_tier config. This
+     * keeps Yujin's provider keys server-side. byok_only plans
+     * + missing license credentials fall back to BYOK exactly as
+     * before. The user_override slash command path is respected
+     * either way -- if you typed /eco /frontier the tier still
+     * holds; the provider just changes between yujin_managed and
+     * the configured BYOK provider. */
+    const managed = await resolveManagedRouting(tier);
+    const provider = managed ? 'yujin_managed' : cfg[tier].provider;
+    const model = managed ? cfg[tier].model : cfg[tier].model;
+    /* yujin_managed has no client-side key (auth uses
+     *  yf_server_api_key + license handle, not a byok_ slot). */
+    let apiKey = null;
+    if (!managed) {
+        const slot = vaultSlotForProvider(cfg[tier].provider);
+        try {
+            apiKey = await getKey(slot);
+        }
+        catch {
+            apiKey = null;
+        }
+    }
+    const wired = RUNTIME_WIRED.has(provider);
+    if (managed) {
+        reason = '[managed] ' + reason;
+    }
+    const sel = {
+        tier,
+        provider,
+        model,
+        api_key: apiKey,
+        reason,
+        runtime_wired: wired,
+    };
+    const logEntry = {
+        tier: sel.tier,
+        provider: sel.provider,
+        model: sel.model,
+        reason: sel.reason,
+        has_key: apiKey !== null,
+        runtime_wired: wired,
+        verb_id: ctx.verb_id,
+        workflow_phase: ctx.workflow_phase,
+        user_override: ctx.user_override,
+    };
+    if (smartTelemetry) {
+        logEntry.smart_auto = smartTelemetry;
+    }
+    await logDecision(logEntry);
+    return sel;
+}
+/**
+ * alpha.59 -- decide whether THIS turn should route to the
+ * managed proxy. Three preconditions must all hold:
+ *
+ *   1. The user has a non-byok plan (free / starter / pro /
+ *      pro_plus -- anything that the server can bill).
+ *   2. The vault has the yf_server_api_key slot populated.
+ *   3. The license cache has a user_handle.
+ *
+ * When any of those is missing we fall back to BYOK so the
+ * client still works offline / pre-signup.
+ *
+ * Reasons for failure are NOT exposed in the routing reason
+ * string -- only that "managed" was applied or not. The
+ * managed-config CLI surfaces the granular reason for the user.
+ */
+async function resolveManagedRouting(_tier) {
+    /* Plan check first. byok_only -> skip. */
+    let plan = 'byok_only';
+    try {
+        const { readBudgetStatus } = await import('./budget.js');
+        const s = await readBudgetStatus();
+        plan = s.plan;
+    }
+    catch {
+        plan = 'byok_only';
+    }
+    if (plan === 'byok_only')
+        return false;
+    /* Vault has yf_server_api_key? */
+    try {
+        const { Vault } = await import('../vault/store.js');
+        const { configDir } = await import('../license/index.js');
+        const vault = await Vault.open({ configDir: configDir() });
+        if (!vault.has('yf_server_api_key'))
+            return false;
+    }
+    catch {
+        return false;
+    }
+    /* license.json has user_handle? */
+    try {
+        const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+        const base = process.env.YF_CONFIG_DIR || path.join(home, '.yujin-forge');
+        const raw = await fs.readFile(path.join(base, 'license.json'), 'utf-8');
+        const j = JSON.parse(raw);
+        if (typeof j.user_handle !== 'string' || j.user_handle.length === 0)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/**
+ * Convenience: resolve only the anthropic key when the caller
+ * doesn't need full routing.
+ */
+export async function resolveAnthropicKey() {
+    try {
+        return await getKey('anthropic_api_key');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=cost_router.js.map

package/dist/core/cost_router.js.map

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

package/dist/core/doctrine_resolver.d.ts

@@ -0,0 +1,23 @@
+/** Force-clear cache. Used by tests. */
+export declare function _clearDoctrineCache(): void;
+export interface DoctrineResult {
+    ok: true;
+    slug: string;
+    content: string;
+    source: string;
+}
+export interface DoctrineError {
+    ok: false;
+    slug: string;
+    error: string;
+    available?: string[];
+}
+/** Fetch a single doctrine. Returns the markdown content. */
+export declare function getDoctrine(slug: string): Promise<DoctrineResult | DoctrineError>;
+/** Fetch multiple doctrines in one round (bulk). Same return shape
+ *  as nac3 discover-schemas: keyed object. */
+export declare function getDoctrines(slugs: string[]): Promise<Record<string, DoctrineResult | DoctrineError>>;
+/** List the available doctrine slugs (markdown files in any
+ *  doctrine dir). Used for the discovery verb. */
+export declare function listDoctrineSlugs(): Promise<string[]>;
+//# sourceMappingURL=doctrine_resolver.d.ts.map

package/dist/core/doctrine_resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctrine_resolver.d.ts","sourceRoot":"","sources":["../../src/core/doctrine_resolver.ts"],"names":[],"mappings":"AAsEA,wCAAwC;AACxC,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,6DAA6D;AAC7D,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,aAAa,CAAC,CAiBvF;AAED;8CAC8C;AAC9C,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAM3G;AAED;kDACkD;AAClD,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAW3D"}

package/dist/core/doctrine_resolver.js

@@ -0,0 +1,108 @@
+/**
+ * Doctrine resolver (alpha.59z.0).
+ *
+ * On-demand fetch of docrine blocks (long-form rules + reference
+ * material) so the system prompt does not have to carry them
+ * every turn. Same pattern as yujin.nac3.discover-schemas: the
+ * LLM sees a short pointer + calls the resolver when it needs
+ * the full text.
+ *
+ * Storage: docs/doctrine/{slug}.md -- one markdown file per
+ * doctrine block. Authored manually. Cached in-process; cache
+ * invalidates by mtime on each lookup (so dev iterations don't
+ * require restart).
+ *
+ * Known slugs (alpha.59z.0):
+ *  - workflow        -- 6 phases / 18 steps reference
+ *  - nac3-attrs      -- the 5 data-nac-* HTML attributes
+ *  - g-doc           -- generation doctrine for adopter apps
+ *
+ * More slugs added in alpha.59z.4 / .5 (pizarron-condensed,
+ * r8-modal, gates).
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DOCTRINE_DIR_HINTS = [
+    /* dist/core -> ../../docs/doctrine (repo root) */
+    path.resolve(__dirname, '..', '..', 'docs', 'doctrine'),
+    /* dist/core -> ../docs/doctrine (after copy_qa_assets bundles them) */
+    path.resolve(__dirname, '..', 'docs', 'doctrine'),
+    /* src/core -> ../../docs/doctrine */
+    path.resolve(__dirname, '..', '..', 'docs', 'doctrine'),
+    /* cwd / docs/doctrine */
+    path.resolve(process.cwd(), 'docs', 'doctrine'),
+];
+const _cache = new Map();
+/** Slug must be kebab-case, no path separators. Defensive against
+ *  path traversal -- the resolver only opens files inside the
+ *  doctrine dirs above. */
+function isValidSlug(slug) {
+    return /^[a-z0-9][a-z0-9-]{0,60}$/.test(slug);
+}
+async function resolveDoctrineFile(slug) {
+    for (const dir of DOCTRINE_DIR_HINTS) {
+        const p = path.join(dir, slug + '.md');
+        try {
+            const stat = await fs.stat(p);
+            if (stat.isFile()) {
+                return { path: p, mtimeMs: stat.mtimeMs };
+            }
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}
+/** Force-clear cache. Used by tests. */
+export function _clearDoctrineCache() {
+    _cache.clear();
+}
+/** Fetch a single doctrine. Returns the markdown content. */
+export async function getDoctrine(slug) {
+    if (!isValidSlug(slug)) {
+        return { ok: false, slug, error: 'invalid slug -- must be kebab-case, max 60 chars' };
+    }
+    const file = await resolveDoctrineFile(slug);
+    if (!file) {
+        const list = await listDoctrineSlugs();
+        return { ok: false, slug, error: 'doctrine not found', available: list };
+    }
+    /* Cache check by mtime. */
+    const cached = _cache.get(slug);
+    if (cached && cached.mtimeMs === file.mtimeMs && cached.resolvedPath === file.path) {
+        return { ok: true, slug, content: cached.content, source: file.path };
+    }
+    const content = await fs.readFile(file.path, 'utf-8');
+    _cache.set(slug, { content, mtimeMs: file.mtimeMs, resolvedPath: file.path });
+    return { ok: true, slug, content, source: file.path };
+}
+/** Fetch multiple doctrines in one round (bulk). Same return shape
+ *  as nac3 discover-schemas: keyed object. */
+export async function getDoctrines(slugs) {
+    const out = {};
+    for (const s of slugs) {
+        out[s] = await getDoctrine(s);
+    }
+    return out;
+}
+/** List the available doctrine slugs (markdown files in any
+ *  doctrine dir). Used for the discovery verb. */
+export async function listDoctrineSlugs() {
+    const seen = new Set();
+    for (const dir of DOCTRINE_DIR_HINTS) {
+        try {
+            const files = await fs.readdir(dir);
+            for (const f of files) {
+                if (f.endsWith('.md'))
+                    seen.add(f.slice(0, -3));
+            }
+        }
+        catch { /* dir missing -- ok */ }
+    }
+    return Array.from(seen).sort();
+}
+//# sourceMappingURL=doctrine_resolver.js.map

package/dist/core/doctrine_resolver.js.map

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