@theglitchking/hit-em-with-the-docs 2.2.0 → 2.3.0

package/dist/core/knowledge-base/citers.js

@@ -0,0 +1,249 @@
+/**
+ * Citation graph walker for knowledge-base primitives (2.3.0).
+ *
+ * Builds the per-fact citation index from three source kinds:
+ *   - Facts (`<vault>/facts/<id>.md`) — the canonical fact corpus.
+ *   - Incident-facts bridges (`<vault>/incidents/<slug>/facts.md`) — produced /
+ *     strengthened / weakened edges.
+ *   - Playbooks (any file with `symptoms: [...]` frontmatter) — `cites` edges
+ *     from each symptom entry to the facts the playbook step depends on.
+ *
+ * Used by:
+ *   - `facts/INDEX.md` generator (PR2) — to compute citer counts per fact.
+ *   - `hewtd find-citers <fact-id>` CLI command (PR3) — typed structure output.
+ *   - Dangling-citation linting (future PR) — flags `cites:` pointing at
+ *     non-existent facts.
+ */
+import { readFile } from 'fs/promises';
+import { join, relative, resolve } from 'path';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+const isString = (v) => typeof v === 'string';
+const isStringArray = (v) => Array.isArray(v) && v.every(isString);
+/**
+ * Walk the corpus and build a citer index. Designed to be cheap on no-vault
+ * trees: if the vault root doesn't exist, returns an empty index without
+ * scanning playbooks for symptoms (no point — no facts to cite).
+ */
+export async function buildCiterIndex(options) {
+    const { projectRoot, vaultRoot, playbookGlobs } = options;
+    const facts = new Map();
+    const incidents = new Map();
+    const citers = new Map();
+    // ----- Facts -----
+    const factFiles = await glob(join(vaultRoot, 'facts/*.md'), {
+        nodir: true,
+        absolute: true,
+    });
+    for (const factPath of factFiles) {
+        const ref = await readFactRef(factPath, projectRoot);
+        if (ref)
+            facts.set(ref.id, ref);
+    }
+    // ----- Incidents -----
+    const narrativeFiles = await glob(join(vaultRoot, 'incidents/*/narrative.md'), { nodir: true, absolute: true });
+    for (const narrativePath of narrativeFiles) {
+        const ref = await readIncidentRef(narrativePath, projectRoot);
+        if (ref)
+            incidents.set(ref.id, ref);
+    }
+    // Short-circuit: if no facts and no incidents, no point scanning playbooks.
+    if (facts.size === 0 && incidents.size === 0) {
+        return { facts, incidents, citers };
+    }
+    // ----- Playbook citations -----
+    // Cheap pre-filter: read each candidate file and skip if frontmatter has
+    // no `symptoms` key. Avoids paying for full YAML parse on every doc.
+    const playbookCandidates = new Set();
+    for (const pattern of playbookGlobs) {
+        const matches = await glob(pattern, { nodir: true, absolute: true });
+        for (const m of matches)
+            playbookCandidates.add(m);
+    }
+    for (const playbookPath of playbookCandidates) {
+        const cits = await extractPlaybookCitations(playbookPath, projectRoot);
+        for (const c of cits) {
+            // Each citation has a list of fact ids implicit in the symptoms entry.
+            const factIds = c.factIds;
+            for (const factId of factIds) {
+                const existing = citers.get(factId) ?? [];
+                existing.push(c.citation);
+                citers.set(factId, existing);
+            }
+        }
+    }
+    return { facts, incidents, citers };
+}
+async function readFactRef(path, projectRoot) {
+    try {
+        const content = await readFile(path, 'utf-8');
+        const { data } = matter(content);
+        if (data.tier !== 'fact' || !isString(data.id))
+            return null;
+        const tags = isStringArray(data.tags) ? data.tags : [];
+        const lastVerified = normalizeDate(data.last_verified);
+        return {
+            id: data.id,
+            path,
+            relPath: relative(projectRoot, path),
+            title: isString(data.title) ? data.title : data.id,
+            confidence: isString(data.confidence) ? data.confidence : undefined,
+            lastVerified,
+            tags,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function readIncidentRef(narrativePath, projectRoot) {
+    try {
+        const narrativeContent = await readFile(narrativePath, 'utf-8');
+        const { data: narrative } = matter(narrativeContent);
+        if (narrative.tier !== 'incident-narrative' || !isString(narrative.id)) {
+            return null;
+        }
+        const folderPath = resolve(narrativePath, '..');
+        const factsMdPath = join(folderPath, 'facts.md');
+        let produced = [];
+        let strengthened = [];
+        let weakened = [];
+        try {
+            const factsContent = await readFile(factsMdPath, 'utf-8');
+            const { data: facts } = matter(factsContent);
+            if (facts.tier === 'incident-facts') {
+                if (isStringArray(facts.produced))
+                    produced = facts.produced;
+                if (isStringArray(facts.strengthened))
+                    strengthened = facts.strengthened;
+                if (isStringArray(facts.weakened))
+                    weakened = facts.weakened;
+            }
+        }
+        catch {
+            // facts.md missing — incident has no produced/strengthened/weakened edges
+        }
+        return {
+            id: narrative.id,
+            folderPath,
+            relFolderPath: relative(projectRoot, folderPath),
+            title: isString(narrative.title) ? narrative.title : narrative.id,
+            date: normalizeDate(narrative.date),
+            severity: isString(narrative.severity) ? narrative.severity : undefined,
+            resolution_status: isString(narrative.resolution_status)
+                ? narrative.resolution_status
+                : undefined,
+            components: isStringArray(narrative.components) ? narrative.components : [],
+            produced,
+            strengthened,
+            weakened,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function extractPlaybookCitations(playbookPath, projectRoot) {
+    try {
+        const content = await readFile(playbookPath, 'utf-8');
+        const { data } = matter(content);
+        if (!Array.isArray(data.symptoms) || data.symptoms.length === 0) {
+            return [];
+        }
+        const title = isString(data.title) ? data.title : playbookPath;
+        const results = [];
+        for (const sym of data.symptoms) {
+            const s = sym;
+            if (!isString(s.target) || !isStringArray(s.cites))
+                continue;
+            let kind;
+            let key;
+            if (isString(s.alert_name)) {
+                kind = 'alert_name';
+                key = s.alert_name;
+            }
+            else if (isStringArray(s.user_phrase) || isString(s.user_phrase)) {
+                kind = 'user_phrase';
+                key = s.user_phrase;
+            }
+            else if (isString(s.error_pattern)) {
+                kind = 'error_pattern';
+                key = s.error_pattern;
+            }
+            else {
+                continue; // malformed — caught by audit-strict, ignored here
+            }
+            results.push({
+                citation: {
+                    relPath: relative(projectRoot, playbookPath),
+                    path: playbookPath,
+                    title,
+                    target: s.target,
+                    kind,
+                    key,
+                    severity: isString(s.severity) ? s.severity : undefined,
+                },
+                factIds: s.cites,
+            });
+        }
+        return results;
+    }
+    catch {
+        return [];
+    }
+}
+function normalizeDate(value) {
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return value;
+    }
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString().slice(0, 10);
+    }
+    return undefined;
+}
+/**
+ * Public lookup: typed structure for one fact id. Matches the shape the
+ * `hewtd find-citers` CLI command prints.
+ */
+export function findCitersInIndex(index, factId) {
+    // Dedup citers by playbook relPath — multiple symptoms entries in the same
+    // playbook citing the same fact count as ONE citer.
+    const citerSet = new Set();
+    for (const c of index.citers.get(factId) ?? []) {
+        citerSet.add(c.relPath);
+    }
+    const incidents_produced_in = [];
+    const incidents_strengthened_by = [];
+    const incidents_weakened_by = [];
+    for (const inc of index.incidents.values()) {
+        if (inc.produced.includes(factId))
+            incidents_produced_in.push(inc.id);
+        if (inc.strengthened.includes(factId))
+            incidents_strengthened_by.push(inc.id);
+        if (inc.weakened.includes(factId))
+            incidents_weakened_by.push(inc.id);
+    }
+    return {
+        fact_id: factId,
+        fact_exists: index.facts.has(factId),
+        citers: [...citerSet].sort(),
+        incidents_produced_in: incidents_produced_in.sort(),
+        incidents_strengthened_by: incidents_strengthened_by.sort(),
+        incidents_weakened_by: incidents_weakened_by.sort(),
+    };
+}
+/**
+ * Count distinct citers for a fact id. Used by the facts-index generator.
+ */
+export function citerCount(index, factId) {
+    const list = index.citers.get(factId);
+    if (!list)
+        return 0;
+    // Distinct by playbook relPath (multiple symptoms in the same playbook
+    // citing the same fact count once).
+    const seen = new Set();
+    for (const c of list)
+        seen.add(c.relPath);
+    return seen.size;
+}
+//# sourceMappingURL=citers.js.map

package/dist/core/knowledge-base/citers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citers.js","sourceRoot":"","sources":["../../../src/core/knowledge-base/citers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,MAAM,MAAM,aAAa,CAAC;AA+FjC,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;AACpE,MAAM,aAAa,GAAG,CAAC,CAAU,EAAiB,EAAE,CAClD,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA+B;IAE/B,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAE1D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8B,CAAC;IAErD,oBAAoB;IACpB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE;QAC1D,KAAK,EAAE,IAAI;QACX,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IACH,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QACrD,IAAI,GAAG;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,wBAAwB;IACxB,MAAM,cAAc,GAAG,MAAM,IAAI,CAC/B,IAAI,CAAC,SAAS,EAAE,0BAA0B,CAAC,EAC3C,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAChC,CAAC;IACF,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;QAC9D,IAAI,GAAG;YAAE,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,4EAA4E;IAC5E,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IACtC,CAAC;IAED,iCAAiC;IACjC,yEAAyE;IACzE,qEAAqE;IACrE,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC7C,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACrE,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,MAAM,YAAY,IAAI,kBAAkB,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,MAAM,wBAAwB,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QACvE,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,uEAAuE;YACvE,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;YAC1B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC1C,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAC1B,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,IAAY,EACZ,WAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QAE5D,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAEvD,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI;YACJ,OAAO,EAAE,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;YACpC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE;YAClD,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YACnE,YAAY;YACZ,IAAI;SACL,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAC5B,aAAqB,EACrB,WAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,gBAAgB,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAChE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACrD,IAAI,SAAS,CAAC,IAAI,KAAK,oBAAoB,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;YACvE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QAChD,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAEjD,IAAI,QAAQ,GAAa,EAAE,CAAC;QAC5B,IAAI,YAAY,GAAa,EAAE,CAAC;QAChC,IAAI,QAAQ,GAAa,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YAC1D,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;YAC7C,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;gBACpC,IAAI,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC;oBAAE,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;gBAC7D,IAAI,aAAa,CAAC,KAAK,CAAC,YAAY,CAAC;oBAAE,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;gBACzE,IAAI,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC;oBAAE,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;YAC/D,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;QAC5E,CAAC;QAED,OAAO;YACL,EAAE,EAAE,SAAS,CAAC,EAAE;YAChB,UAAU;YACV,aAAa,EAAE,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;YAChD,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE;YACjE,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC;YACnC,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;YACvE,iBAAiB,EAAE,QAAQ,CAAC,SAAS,CAAC,iBAAiB,CAAC;gBACtD,CAAC,CAAC,SAAS,CAAC,iBAAiB;gBAC7B,CAAC,CAAC,SAAS;YACb,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;YAC3E,QAAQ;YACR,YAAY;YACZ,QAAQ;SACT,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAOD,KAAK,UAAU,wBAAwB,CACrC,YAAoB,EACpB,WAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACtD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChE,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC;QAC/D,MAAM,OAAO,GAAgC,EAAE,CAAC;QAEhD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,GAA8B,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC;gBAAE,SAAS;YAE7D,IAAI,IAA8B,CAAC;YACnC,IAAI,GAAsB,CAAC;YAC3B,IAAI,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC3B,IAAI,GAAG,YAAY,CAAC;gBACpB,GAAG,GAAG,CAAC,CAAC,UAAU,CAAC;YACrB,CAAC;iBAAM,IAAI,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;gBACnE,IAAI,GAAG,aAAa,CAAC;gBACrB,GAAG,GAAG,CAAC,CAAC,WAAgC,CAAC;YAC3C,CAAC;iBAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC;gBACrC,IAAI,GAAG,eAAe,CAAC;gBACvB,GAAG,GAAG,CAAC,CAAC,aAAa,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,mDAAmD;YAC/D,CAAC;YAED,OAAO,CAAC,IAAI,CAAC;gBACX,QAAQ,EAAE;oBACR,OAAO,EAAE,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;oBAC5C,IAAI,EAAE,YAAY;oBAClB,KAAK;oBACL,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,IAAI;oBACJ,GAAG;oBACH,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;iBACxD;gBACD,OAAO,EAAE,CAAC,CAAC,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACnE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAC5D,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAiB,EACjB,MAAc;IAEd,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,qBAAqB,GAAa,EAAE,CAAC;IAC3C,MAAM,yBAAyB,GAAa,EAAE,CAAC;IAC/C,MAAM,qBAAqB,GAAa,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QAC3C,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtE,IAAI,GAAG,CAAC,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,yBAAyB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9E,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,OAAO;QACL,OAAO,EAAE,MAAM;QACf,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QACpC,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE;QAC5B,qBAAqB,EAAE,qBAAqB,CAAC,IAAI,EAAE;QACnD,yBAAyB,EAAE,yBAAyB,CAAC,IAAI,EAAE;QAC3D,qBAAqB,EAAE,qBAAqB,CAAC,IAAI,EAAE;KACpD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,KAAiB,EAAE,MAAc;IAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,uEAAuE;IACvE,oCAAoC;IACpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC"}

package/dist/core/knowledge-base/extract.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Fact-extraction writer (2.3.0 PR3).
+ *
+ * The CLI side of `hewtd extract-facts <incident-folder>`. Takes accepted
+ * fact specs and writes them to `<vault>/facts/<id>.md` with provenance
+ * auto-populated to the source incident folder. Idempotent — re-running
+ * with an already-committed fact spec is a no-op.
+ *
+ * The LLM proposal step (read narrative → suggest fact specs) lives in the
+ * `/hit-em-with-the-docs:extract-facts` slash command, NOT here. This
+ * module is the deterministic writer that the slash command invokes after
+ * the user accepts proposals.
+ */
+export interface FactSpec {
+    id: string;
+    title: string;
+    confidence: 'high' | 'medium' | 'low' | 'hypothesis';
+    verifyCommand?: string;
+    /** Claim paragraph (will be inserted as `## Claim`). */
+    claim: string;
+    /** Optional how-to-verify paragraph. */
+    howToVerify?: string;
+    /** Optional consequences paragraph. */
+    consequences?: string;
+    /** Optional tags (will be merged with auto-derived tags). */
+    tags?: string[];
+    /** Optional domains. Defaults to ['knowledge-base'] if not specified. */
+    domains?: string[];
+}
+export interface ExtractFactsOptions {
+    /** Absolute path to the incident folder (must contain narrative.md). */
+    incidentFolder: string;
+    /** Absolute path to the vault root. Facts go into `<vault>/facts/`. */
+    vaultRoot: string;
+    /** Project root for provenance relpath computation. */
+    projectRoot: string;
+    /** Accepted fact specs (already curated by the LLM proposer + user). */
+    accept: FactSpec[];
+    /** If true, returns the plan without writing files. */
+    dryRun?: boolean;
+}
+export interface ExtractedFact {
+    id: string;
+    factPath: string;
+    action: 'created' | 'already_exists';
+    content: string;
+}
+export interface ExtractFactsResult {
+    incidentId: string;
+    incidentFolder: string;
+    extractedFacts: ExtractedFact[];
+    /** Whether the incident's facts.md was updated. */
+    factsMdUpdated: boolean;
+    factsMdPath: string;
+}
+export declare function extractFacts(options: ExtractFactsOptions): Promise<ExtractFactsResult>;
+/**
+ * Re-export the resolved vault root so callers don't have to recompute it.
+ */
+export declare function defaultVaultRoot(projectRoot: string): string;
+//# sourceMappingURL=extract.d.ts.map

package/dist/core/knowledge-base/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../../src/core/knowledge-base/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,YAAY,CAAC;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,gBAAgB,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,mDAAmD;IACnD,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAqG7B;AAsBD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/core/knowledge-base/extract.js

@@ -0,0 +1,132 @@
+/**
+ * Fact-extraction writer (2.3.0 PR3).
+ *
+ * The CLI side of `hewtd extract-facts <incident-folder>`. Takes accepted
+ * fact specs and writes them to `<vault>/facts/<id>.md` with provenance
+ * auto-populated to the source incident folder. Idempotent — re-running
+ * with an already-committed fact spec is a no-op.
+ *
+ * The LLM proposal step (read narrative → suggest fact specs) lives in the
+ * `/hit-em-with-the-docs:extract-facts` slash command, NOT here. This
+ * module is the deterministic writer that the slash command invokes after
+ * the user accepts proposals.
+ */
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { basename, dirname, join, relative, resolve } from 'path';
+import matter from 'gray-matter';
+export async function extractFacts(options) {
+    const { incidentFolder, vaultRoot, projectRoot, accept, dryRun = false } = options;
+    const narrativePath = join(incidentFolder, 'narrative.md');
+    const narrativeRaw = await readFile(narrativePath, 'utf-8');
+    const narrative = matter(narrativeRaw);
+    const incidentId = typeof narrative.data.id === 'string'
+        ? narrative.data.id
+        : basename(incidentFolder);
+    const provenanceRelPath = relative(projectRoot, incidentFolder).replace(/\\/g, '/');
+    const factsDir = join(vaultRoot, 'facts');
+    const today = new Date().toISOString().slice(0, 10);
+    const extractedFacts = [];
+    for (const spec of accept) {
+        const factPath = join(factsDir, `${spec.id}.md`);
+        if (existsSync(factPath)) {
+            extractedFacts.push({
+                id: spec.id,
+                factPath,
+                action: 'already_exists',
+                content: await readFile(factPath, 'utf-8'),
+            });
+            continue;
+        }
+        const frontmatter = {
+            title: spec.title,
+            tier: 'fact',
+            domains: spec.domains ?? ['knowledge-base'],
+            status: 'active',
+            last_updated: today,
+            id: spec.id,
+            confidence: spec.confidence,
+            last_verified: today,
+            provenance: [provenanceRelPath + '/'],
+            tags: spec.tags ?? [],
+        };
+        if (spec.verifyCommand) {
+            frontmatter.verify_command = spec.verifyCommand;
+        }
+        const body = renderFactBody(spec);
+        const content = matter.stringify(body, frontmatter);
+        if (!dryRun) {
+            await mkdir(dirname(factPath), { recursive: true });
+            await writeFile(factPath, content, 'utf-8');
+        }
+        extractedFacts.push({
+            id: spec.id,
+            factPath,
+            action: 'created',
+            content,
+        });
+    }
+    // Update incident's facts.md `produced:` list (idempotent — only adds new
+    // ids, never removes existing ones).
+    const factsMdPath = join(incidentFolder, 'facts.md');
+    let factsMdUpdated = false;
+    if (existsSync(factsMdPath)) {
+        const factsMdRaw = await readFile(factsMdPath, 'utf-8');
+        const factsMd = matter(factsMdRaw);
+        // Important: gray-matter caches parse results keyed by content. Mutating
+        // factsMd.data leaks across calls with identical input strings (notably
+        // in tests). Always build a fresh data object.
+        const existing = Array.isArray(factsMd.data.produced)
+            ? [...factsMd.data.produced]
+            : [];
+        const newIds = extractedFacts
+            .filter((e) => e.action === 'created')
+            .map((e) => e.id);
+        const toAdd = newIds.filter((id) => !existing.includes(id));
+        if (toAdd.length > 0) {
+            const newData = {
+                ...factsMd.data,
+                produced: [...existing, ...toAdd],
+                last_updated: today,
+            };
+            const newContent = matter.stringify(factsMd.content, newData);
+            if (!dryRun) {
+                await writeFile(factsMdPath, newContent, 'utf-8');
+            }
+            factsMdUpdated = true;
+        }
+    }
+    return {
+        incidentId,
+        incidentFolder,
+        extractedFacts,
+        factsMdUpdated,
+        factsMdPath,
+    };
+}
+function renderFactBody(spec) {
+    const sections = [];
+    sections.push(`# ${spec.title}`);
+    sections.push('');
+    sections.push('## Claim');
+    sections.push(spec.claim.trim());
+    sections.push('');
+    if (spec.howToVerify) {
+        sections.push('## How to verify');
+        sections.push(spec.howToVerify.trim());
+        sections.push('');
+    }
+    if (spec.consequences) {
+        sections.push('## Consequences');
+        sections.push(spec.consequences.trim());
+        sections.push('');
+    }
+    return '\n' + sections.join('\n');
+}
+/**
+ * Re-export the resolved vault root so callers don't have to recompute it.
+ */
+export function defaultVaultRoot(projectRoot) {
+    return resolve(projectRoot, '.documentation/knowledge-base');
+}
+//# sourceMappingURL=extract.js.map

package/dist/core/knowledge-base/extract.js.map

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

package/dist/core/knowledge-base/migrate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Flat-file incident → folder migration (2.3.0 PR3).
+ *
+ * Reads a legacy flat-file incident (e.g. `knowledge-base/2026-04-23-foo.md`)
+ * and converts it into the folder form:
+ *
+ *   <flat-file>.md  →  <slug>/narrative.md
+ *                      <slug>/facts.md (skeleton)
+ *                      <slug>/evidence/ (empty, ready for artifacts)
+ *
+ * Idempotent: re-running on an already-migrated incident detects the folder
+ * exists and warns + no-ops.
+ */
+export interface MigrateIncidentOptions {
+    /** Absolute path to the flat-file incident markdown. */
+    flatFilePath: string;
+    /** If true, returns the migration plan without writing. */
+    dryRun?: boolean;
+}
+export interface MigrateIncidentResult {
+    flatFilePath: string;
+    targetFolder: string;
+    action: 'migrated' | 'already_migrated' | 'dry_run';
+    narrativePath: string;
+    factsPath: string;
+    evidencePath: string;
+    /** What the narrative.md content will be. */
+    narrativeContent: string;
+    /** What the facts.md content will be. */
+    factsContent: string;
+}
+export declare function migrateIncident(options: MigrateIncidentOptions): Promise<MigrateIncidentResult>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/core/knowledge-base/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/core/knowledge-base/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAwGhC"}

package/dist/core/knowledge-base/migrate.js

@@ -0,0 +1,112 @@
+/**
+ * Flat-file incident → folder migration (2.3.0 PR3).
+ *
+ * Reads a legacy flat-file incident (e.g. `knowledge-base/2026-04-23-foo.md`)
+ * and converts it into the folder form:
+ *
+ *   <flat-file>.md  →  <slug>/narrative.md
+ *                      <slug>/facts.md (skeleton)
+ *                      <slug>/evidence/ (empty, ready for artifacts)
+ *
+ * Idempotent: re-running on an already-migrated incident detects the folder
+ * exists and warns + no-ops.
+ */
+import { readFile, writeFile, mkdir, rename } from 'fs/promises';
+import { existsSync } from 'fs';
+import { basename, dirname, join } from 'path';
+import matter from 'gray-matter';
+export async function migrateIncident(options) {
+    const { flatFilePath, dryRun = false } = options;
+    const sourceContent = await readFile(flatFilePath, 'utf-8');
+    const parsed = matter(sourceContent);
+    const fm = (parsed.data ?? {});
+    // Derive the target folder name. Priority:
+    //   1. Frontmatter `id:` (if YYYY-MM-DD-slug shape)
+    //   2. The flat file's basename minus `.md`
+    const flatBase = basename(flatFilePath, '.md');
+    const idFromFrontmatter = typeof fm.id === 'string' ? fm.id : undefined;
+    const folderSlug = idFromFrontmatter && /^\d{4}-\d{2}-\d{2}-[a-z0-9-]+$/.test(idFromFrontmatter)
+        ? idFromFrontmatter
+        : flatBase;
+    const parentDir = dirname(flatFilePath);
+    const targetFolder = join(parentDir, folderSlug);
+    const narrativePath = join(targetFolder, 'narrative.md');
+    const factsPath = join(targetFolder, 'facts.md');
+    const evidencePath = join(targetFolder, 'evidence');
+    // Build narrative.md frontmatter — promote/normalize fields, set tier.
+    const narrativeFrontmatter = {
+        title: fm.title ?? flatBase,
+        tier: 'incident-narrative',
+        domains: Array.isArray(fm.domains) ? fm.domains : ['incidents'],
+        status: typeof fm.status === 'string' ? fm.status : 'active',
+        last_updated: typeof fm.last_updated === 'string'
+            ? fm.last_updated
+            : new Date().toISOString().slice(0, 10),
+        id: folderSlug,
+        date: deriveDateFromSlug(folderSlug) ?? fm.date ?? folderSlug.slice(0, 10),
+        severity: typeof fm.severity === 'string' ? fm.severity : 'medium',
+        resolution_status: typeof fm.resolution_status === 'string' ? fm.resolution_status : 'resolved',
+        components: Array.isArray(fm.components) ? fm.components : ['unknown'],
+    };
+    if (Array.isArray(fm.tags))
+        narrativeFrontmatter.tags = fm.tags;
+    const narrativeContent = matter.stringify(parsed.content, narrativeFrontmatter);
+    // Build facts.md skeleton.
+    const factsFrontmatter = {
+        title: `Facts from ${folderSlug}`,
+        tier: 'incident-facts',
+        domains: ['incidents'],
+        status: 'active',
+        last_updated: new Date().toISOString().slice(0, 10),
+        incident_id: folderSlug,
+        produced: [],
+    };
+    const factsContent = matter.stringify(`\n# Facts from ${folderSlug}\n\n## Produced\n_(No facts extracted yet. Use \`hewtd extract-facts ${folderSlug}/\` to propose facts from the narrative.)_\n`, factsFrontmatter);
+    // Idempotency check: if target folder already exists, no-op.
+    if (existsSync(targetFolder)) {
+        return {
+            flatFilePath,
+            targetFolder,
+            action: 'already_migrated',
+            narrativePath,
+            factsPath,
+            evidencePath,
+            narrativeContent,
+            factsContent,
+        };
+    }
+    if (dryRun) {
+        return {
+            flatFilePath,
+            targetFolder,
+            action: 'dry_run',
+            narrativePath,
+            factsPath,
+            evidencePath,
+            narrativeContent,
+            factsContent,
+        };
+    }
+    // Execute the migration.
+    await mkdir(evidencePath, { recursive: true }); // also creates targetFolder
+    await writeFile(narrativePath, narrativeContent, 'utf-8');
+    await writeFile(factsPath, factsContent, 'utf-8');
+    // Move the flat file to a `.migrated` extension so consumers don't read it
+    // accidentally. Preserves the original for rollback.
+    await rename(flatFilePath, `${flatFilePath}.migrated`);
+    return {
+        flatFilePath,
+        targetFolder,
+        action: 'migrated',
+        narrativePath,
+        factsPath,
+        evidencePath,
+        narrativeContent,
+        factsContent,
+    };
+}
+function deriveDateFromSlug(slug) {
+    const m = slug.match(/^(\d{4}-\d{2}-\d{2})/);
+    return m ? m[1] : undefined;
+}
+//# sourceMappingURL=migrate.js.map

package/dist/core/knowledge-base/migrate.js.map

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

package/dist/core/maintain/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/core/maintain/orchestrator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAI3E,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,kBAAkB,CAAC;IACjC,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA0JtF;AA4OD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,CAoBD"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/core/maintain/orchestrator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAa3E,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,kBAAkB,CAAC;IACjC,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAoKtF;AAwRD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,CAoBD"}