@balpal4495/quorum 3.0.4 → 3.1.0

package/dist/oracle/types.d.ts

@@ -0,0 +1,31 @@
+import type { ChronicleEntry } from "../shared/types.js";
+/**
+ * Abstract vector store interface.
+ * Swap implementations without changing Oracle logic.
+ * Default implementation: LanceDB (see adapters/lance-db.ts).
+ */
+export interface VectorStore {
+    /**
+     * Upsert a Chronicle entry with its embedding vector.
+     * If an entry with this ID already exists, it is replaced.
+     */
+    upsert: (id: string, vector: number[], metadata: ChronicleEntry) => Promise<void>;
+    /**
+     * Return the top-K most similar entries to the given query vector.
+     * Scores should be in [0, 1] (higher = more similar).
+     */
+    search: (vector: number[], limit: number) => Promise<Array<{
+        entry: ChronicleEntry;
+        score: number;
+    }>>;
+    /** Return all stored entries (used for full-corpus BM25 if needed). */
+    getAll: () => Promise<ChronicleEntry[]>;
+}
+export interface OracleDeps {
+    /** Converts text to a numeric embedding vector. */
+    embedder: (text: string) => Promise<number[]>;
+    vectorStore: VectorStore;
+    /** Root directory for Chronicle data. Default: ".chronicle" */
+    chronicleDir?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/oracle/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../modules/oracle/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACjF;;;OAGG;IACH,MAAM,EAAE,CACN,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAA;IAC7D,uEAAuE;IACvE,MAAM,EAAE,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAC7C,WAAW,EAAE,WAAW,CAAA;IACxB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB"}

package/dist/oracle/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/oracle/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../modules/oracle/types.ts"],"names":[],"mappings":""}

package/dist/sentinel/assert.d.ts

@@ -0,0 +1,28 @@
+import type { LLMProvider } from "../shared/types.js";
+export interface SentinelAssertOptions {
+    chronicleDir?: string;
+    codebasePath?: string;
+    /** When provided, drift detection runs. When absent, drift tests are skipped. */
+    llm?: LLMProvider;
+    extensions?: string[];
+    /**
+     * Chronicle coverage must reach this percentage for the CI test to pass.
+     * Default 0 = report gaps as advisory output without failing the build.
+     * Raise this as the project matures (e.g. 50 for an established codebase).
+     */
+    minCoveragePercent?: number;
+}
+/**
+ * Returns a set of named assertions designed to be called inside a Vitest
+ * describe block. Coverage assertions are deterministic and always run.
+ * Drift assertions skip gracefully when no LLM is provided.
+ *
+ * @example
+ * import { describe } from "vitest"
+ * import { sentinelAssertions } from "../modules/sentinel/assert.js"
+ *
+ * const assertions = sentinelAssertions({ chronicleDir: ".chronicle", codebasePath: "modules" })
+ * describe("sentinel", () => { assertions.forEach(a => a()) })
+ */
+export declare function sentinelAssertions(options?: SentinelAssertOptions): Array<() => void>;
+//# sourceMappingURL=assert.d.ts.map

package/dist/sentinel/assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../modules/sentinel/assert.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD,MAAM,WAAW,qBAAqB;IACpC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iFAAiF;IACjF,GAAG,CAAC,EAAE,WAAW,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,qBAA0B,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,CAgEzF"}

package/dist/sentinel/assert.js

@@ -0,0 +1,63 @@
+import { coverage } from "./coverage.js";
+import { detectDrift } from "./drift.js";
+/**
+ * Returns a set of named assertions designed to be called inside a Vitest
+ * describe block. Coverage assertions are deterministic and always run.
+ * Drift assertions skip gracefully when no LLM is provided.
+ *
+ * @example
+ * import { describe } from "vitest"
+ * import { sentinelAssertions } from "../modules/sentinel/assert.js"
+ *
+ * const assertions = sentinelAssertions({ chronicleDir: ".chronicle", codebasePath: "modules" })
+ * describe("sentinel", () => { assertions.forEach(a => a()) })
+ */
+export function sentinelAssertions(options = {}) {
+    const { chronicleDir = ".chronicle", codebasePath = ".", llm, extensions, minCoveragePercent = 0, } = options;
+    // Import vitest lazily so this file is usable outside of a test context too
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { it, expect, describe: _describe } = require("vitest");
+    const assertions = [];
+    // ── Coverage (deterministic, always run) ──────────────────────────────────
+    assertions.push(() => {
+        const label = minCoveragePercent > 0
+            ? `coverage: Chronicle coverage ≥ ${minCoveragePercent}%`
+            : "coverage: Chronicle coverage report [advisory]";
+        it(label, async () => {
+            const report = await coverage(chronicleDir, codebasePath, { extensions });
+            if (report.uncoveredFiles.length > 0) {
+                const list = report.uncoveredFiles.slice(0, 10).join("\n  ");
+                const msg = `${report.uncoveredFiles.length} source file(s) have no Chronicle coverage (${report.percentage}% covered):\n  ${list}`;
+                if (minCoveragePercent > 0) {
+                    expect(report.percentage, msg).toBeGreaterThanOrEqual(minCoveragePercent);
+                }
+                else {
+                    // New project or no threshold set — surface gaps without failing the build
+                    console.info(`[sentinel] ${msg}`);
+                }
+            }
+        });
+    });
+    assertions.push(() => {
+        it("coverage: report is readable and well-formed", async () => {
+            const report = await coverage(chronicleDir, codebasePath, { extensions });
+            expect(report.totalFiles).toBeGreaterThanOrEqual(0);
+            expect(report.percentage).toBeGreaterThanOrEqual(0);
+            expect(report.percentage).toBeLessThanOrEqual(100);
+        });
+    });
+    // ── Drift (advisory, skips when no LLM configured) ────────────────────────
+    assertions.push(() => {
+        it.skipIf(!llm)("drift: no Chronicle entries flagged as potentially stale [advisory]", async () => {
+            const report = await detectDrift(chronicleDir, codebasePath, llm);
+            if (report.flags.length > 0) {
+                const detail = report.flags
+                    .map(f => `  [${f.entryId.slice(0, 8)}] ${f.keyInsight}\n    → ${f.reasoning}`)
+                    .join("\n");
+                expect(report.flags, `${report.flags.length} Chronicle entry/entries may have drifted (advisory — review before marking refuted):\n${detail}`).toHaveLength(0);
+            }
+        });
+    });
+    return assertions;
+}
+//# sourceMappingURL=assert.js.map

package/dist/sentinel/assert.js.map

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

package/dist/sentinel/coverage.d.ts

@@ -0,0 +1,14 @@
+import type { CoverageReport } from "../shared/types.js";
+/**
+ * Scan the codebase and report which files have Chronicle entries referencing
+ * them in affected_areas and which do not.
+ *
+ * Matching is substring-based — "oracle/propose.ts" in affected_areas covers
+ * "modules/oracle/propose.ts" in the codebase. Treat percentage as directional
+ * signal, not a precision metric.
+ */
+export declare function coverage(chronicleDir: string, codebasePath: string, options?: {
+    extensions?: string[];
+    excludeTestFiles?: boolean;
+}): Promise<CoverageReport>;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/sentinel/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../modules/sentinel/coverage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAkB,cAAc,EAAgB,MAAM,oBAAoB,CAAA;AAmEtF;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAC5B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAClE,OAAO,CAAC,cAAc,CAAC,CAwBzB"}

package/dist/sentinel/coverage.js

@@ -0,0 +1,96 @@
+import { promises as fs } from "fs";
+import path from "path";
+const IGNORED_DIRS = new Set(["node_modules", "dist", ".git", ".chronicle", "coverage", "__tests__"]);
+const TEST_SUFFIXES = [".test.ts", ".spec.ts", ".test.js", ".spec.js"];
+async function walkFiles(dir, extensions, excludeTestFiles) {
+    const results = [];
+    async function recurse(current) {
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true, encoding: "utf8" });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (!IGNORED_DIRS.has(entry.name))
+                    await recurse(path.join(current, entry.name));
+            }
+            else if (extensions.some(ext => entry.name.endsWith(ext))) {
+                if (excludeTestFiles && TEST_SUFFIXES.some(s => entry.name.endsWith(s)))
+                    continue;
+                results.push(path.join(current, entry.name));
+            }
+        }
+    }
+    await recurse(dir);
+    return results;
+}
+async function readCommittedEntries(chronicleDir) {
+    const committedDir = path.join(chronicleDir, "committed");
+    let files;
+    try {
+        files = await fs.readdir(committedDir);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const raw = await fs.readFile(path.join(committedDir, file), "utf8");
+            entries.push(JSON.parse(raw));
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return entries;
+}
+function isCovered(relativePath, entries) {
+    const matched = [];
+    const normalised = relativePath.replace(/\\/g, "/");
+    for (const entry of entries) {
+        const hits = entry.affected_areas.some(area => {
+            const normArea = area.replace(/\\/g, "/");
+            return normalised.includes(normArea) || normArea.includes(normalised);
+        });
+        if (hits)
+            matched.push(entry.id);
+    }
+    return { covered: matched.length > 0, entryIds: matched };
+}
+/**
+ * Scan the codebase and report which files have Chronicle entries referencing
+ * them in affected_areas and which do not.
+ *
+ * Matching is substring-based — "oracle/propose.ts" in affected_areas covers
+ * "modules/oracle/propose.ts" in the codebase. Treat percentage as directional
+ * signal, not a precision metric.
+ */
+export async function coverage(chronicleDir, codebasePath, options = {}) {
+    const extensions = options.extensions ?? [".ts"];
+    const excludeTestFiles = options.excludeTestFiles ?? true;
+    const [entries, files] = await Promise.all([
+        readCommittedEntries(chronicleDir),
+        walkFiles(codebasePath, extensions, excludeTestFiles),
+    ]);
+    const coverageByFile = files.map(absolute => {
+        const relative = path.relative(codebasePath, absolute).replace(/\\/g, "/");
+        const { covered, entryIds } = isCovered(relative, entries);
+        return { file: relative, covered, entryIds };
+    });
+    const covered = coverageByFile.filter(f => f.covered);
+    const uncovered = coverageByFile.filter(f => !f.covered);
+    return {
+        totalFiles: files.length,
+        coveredFiles: covered.length,
+        uncoveredFiles: uncovered.map(f => f.file),
+        coverageByFile,
+        percentage: files.length === 0 ? 0 : Math.round((covered.length / files.length) * 100),
+    };
+}
+//# sourceMappingURL=coverage.js.map

package/dist/sentinel/coverage.js.map

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

package/dist/sentinel/drift.d.ts

@@ -0,0 +1,12 @@
+import type { DriftReport, LLMProvider } from "../shared/types.js";
+/**
+ * For each Chronicle entry whose affected_areas resolves to at least one local
+ * source file, ask the LLM whether the key_insight still accurately describes
+ * the current code.
+ *
+ * Output is strictly advisory — entries are never updated autonomously.
+ * Entries where no affected_areas value resolves to a local file are skipped
+ * (e.g. entries about external tools, workflows, or conceptual areas).
+ */
+export declare function detectDrift(chronicleDir: string, codebasePath: string, llm: LLMProvider): Promise<DriftReport>;
+//# sourceMappingURL=drift.d.ts.map

package/dist/sentinel/drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.d.ts","sourceRoot":"","sources":["../../modules/sentinel/drift.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA6B,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AA6G7F;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,WAAW,CAAC,CAsCtB"}

package/dist/sentinel/drift.js

@@ -0,0 +1,149 @@
+import { promises as fs } from "fs";
+import path from "path";
+import { entryText } from "../shared/types.js";
+const FILE_CONTENT_LIMIT = 3000;
+async function readCommittedEntries(chronicleDir) {
+    const committedDir = path.join(chronicleDir, "committed");
+    let files;
+    try {
+        files = await fs.readdir(committedDir);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const raw = await fs.readFile(path.join(committedDir, file), "utf8");
+            entries.push(JSON.parse(raw));
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return entries;
+}
+async function resolveLocalFiles(areas, codebasePath) {
+    const resolved = [];
+    for (const area of areas) {
+        // Try as a direct relative path first
+        const candidate = path.join(codebasePath, area);
+        try {
+            await fs.access(candidate);
+            resolved.push(candidate);
+            continue;
+        }
+        catch {
+            // not a direct path — try substring search
+        }
+        // Walk up to two levels to find files whose relative path contains the area string
+        try {
+            const all = await fs.readdir(codebasePath, { recursive: true, encoding: "utf8" });
+            for (const f of all) {
+                const normalised = f.replace(/\\/g, "/");
+                if (normalised.includes(area.replace(/\\/g, "/")) && normalised.endsWith(".ts")) {
+                    resolved.push(path.join(codebasePath, f));
+                    break;
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return [...new Set(resolved)];
+}
+async function evaluateDrift(entry, files, llm) {
+    const fileSection = files
+        .map(f => `### ${path.basename(f.filePath)}\n\`\`\`\n${f.content.slice(0, FILE_CONTENT_LIMIT)}\n\`\`\``)
+        .join("\n\n");
+    const response = await llm([
+        {
+            role: "system",
+            content: "You are a code reviewer checking whether a documented insight still accurately describes the current source code. " +
+                "Reply with a JSON object only — no markdown, no explanation outside the object.",
+        },
+        {
+            role: "user",
+            content: `Documented insight:
+"${entryText(entry)}"
+
+` +
+                `Current source:\n${fileSection}\n\n` +
+                `Does this insight still accurately describe the code above?\n` +
+                `{"stillValid": boolean, "confidence": number, "reasoning": "one sentence"}`,
+        },
+    ]);
+    try {
+        const match = response.match(/\{[\s\S]*?\}/);
+        if (!match)
+            throw new Error("no JSON");
+        const parsed = JSON.parse(match[0]);
+        return {
+            entryId: entry.id,
+            keyInsight: entryText(entry),
+            affectedFiles: files.map(f => f.filePath),
+            stillValid: Boolean(parsed.stillValid),
+            confidence: typeof parsed.confidence === "number" ? Math.max(0, Math.min(1, parsed.confidence)) : 0.5,
+            reasoning: typeof parsed.reasoning === "string" ? parsed.reasoning : "no reasoning provided",
+        };
+    }
+    catch {
+        // Parse failure → conservative: flag for human review
+        return {
+            entryId: entry.id,
+            keyInsight: entryText(entry),
+            affectedFiles: files.map(f => f.filePath),
+            stillValid: false,
+            confidence: 0,
+            reasoning: "LLM response could not be parsed — manual review recommended",
+        };
+    }
+}
+/**
+ * For each Chronicle entry whose affected_areas resolves to at least one local
+ * source file, ask the LLM whether the key_insight still accurately describes
+ * the current code.
+ *
+ * Output is strictly advisory — entries are never updated autonomously.
+ * Entries where no affected_areas value resolves to a local file are skipped
+ * (e.g. entries about external tools, workflows, or conceptual areas).
+ */
+export async function detectDrift(chronicleDir, codebasePath, llm) {
+    const entries = await readCommittedEntries(chronicleDir);
+    const flags = [];
+    const confirmed = [];
+    const skipped = [];
+    for (const entry of entries) {
+        const localPaths = await resolveLocalFiles(entry.affected_areas, codebasePath);
+        if (localPaths.length === 0) {
+            skipped.push(entry.id);
+            continue;
+        }
+        const files = [];
+        for (const p of localPaths) {
+            try {
+                const content = await fs.readFile(p, "utf8");
+                files.push({ filePath: p, content });
+            }
+            catch {
+                // file unreadable — skip this path
+            }
+        }
+        if (files.length === 0) {
+            skipped.push(entry.id);
+            continue;
+        }
+        const result = await evaluateDrift(entry, files, llm);
+        if (result.stillValid) {
+            confirmed.push(result);
+        }
+        else {
+            flags.push(result);
+        }
+    }
+    return { checkedAt: new Date().toISOString(), flags, confirmed, skipped };
+}
+//# sourceMappingURL=drift.js.map

package/dist/sentinel/drift.js.map

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

package/dist/sentinel/index.d.ts

@@ -0,0 +1,7 @@
+export { coverage } from "./coverage.js";
+export { detectDrift } from "./drift.js";
+export { reviewContext } from "./review.js";
+export { sentinelAssertions } from "./assert.js";
+export type { CoverageReport, FileCoverage, DriftReport, DriftFlag } from "../shared/types.js";
+export type { SentinelAssertOptions } from "./assert.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sentinel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../modules/sentinel/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9F,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA"}

package/dist/sentinel/index.js

@@ -0,0 +1,5 @@
+export { coverage } from "./coverage.js";
+export { detectDrift } from "./drift.js";
+export { reviewContext } from "./review.js";
+export { sentinelAssertions } from "./assert.js";
+//# sourceMappingURL=index.js.map

package/dist/sentinel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../modules/sentinel/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/sentinel/review.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Generate a PR-level Chronicle coverage map as a markdown string ready to
+ * post as a PR comment.
+ *
+ * Produces three zones:
+ *   1. Coverage table — all modules with coverage %, entry count, file count,
+ *      PR delta, and risk. Changed modules are bolded.
+ *   2. Heatmap diagram — Chronicle → modules, nodes coloured by risk level,
+ *      labels show coverage % and change count in one visual.
+ *   3. Chronicle context — entries for touched modules only.
+ *
+ * Deterministic — no LLM required. Pass changedFiles from `git diff --name-only`.
+ */
+export declare function reviewContext(changedFiles: string[], chronicleDir: string, codebasePath: string): Promise<string>;
+//# sourceMappingURL=review.d.ts.map

package/dist/sentinel/review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../modules/sentinel/review.ts"],"names":[],"mappings":"AAoEA;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,MAAM,EAAE,EACtB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CA0HjB"}