knitbrain 0.1.0

package/dist/engine/agents.js

@@ -0,0 +1,88 @@
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Domains that warrant a mandatory review/verify gate before edits. */
+const SENSITIVE = /\b(auth|security|secret|payment|billing|crypto|db|database|migration|schema)\b/i;
+const DEFAULT_TOOLS = ["Read", "Grep", "Glob", "Edit", "Write"];
+/**
+ * Auto-detect candidate domain agents from the knowledge graph: group source
+ * files by their directory; each directory with ≥2 files becomes a proposal
+ * with sensible, project-specific guardrails. The agent then interviews the
+ * user to confirm/edit before create_agent writes them.
+ */
+export function proposeAgents(files) {
+    const byDir = new Map();
+    for (const f of files) {
+        const dir = dirname(f);
+        if (dir === "." || dir === "")
+            continue;
+        const arr = byDir.get(dir);
+        if (arr)
+            arr.push(f);
+        else
+            byDir.set(dir, [f]);
+    }
+    const proposals = [];
+    for (const [dir, dirFiles] of byDir) {
+        if (dirFiles.length < 2)
+            continue;
+        const name = dir.split("/").pop();
+        const reviewGate = SENSITIVE.test(dir);
+        proposals.push({
+            name,
+            scope: `${dir}/**`,
+            files: dirFiles,
+            tools: reviewGate ? ["Read", "Grep", "Glob"] : DEFAULT_TOOLS,
+            reviewGate,
+            contextBudget: 8000,
+        });
+    }
+    return proposals.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Render a project-specific subagent definition with all four guardrails baked
+ * in: file/domain scope, allowed-tools allowlist, review gate, context budget.
+ */
+export function generateAgentMarkdown(spec) {
+    const tools = (spec.tools ?? DEFAULT_TOOLS).join(", ");
+    const scope = spec.scope ?? "(whole project)";
+    const budget = spec.contextBudget ?? 8000;
+    const description = spec.description ?? `Project agent scoped to ${scope}.`;
+    const gate = spec.reviewGate
+        ? "- **Review gate:** this is a sensitive domain — before any edit, re-verify the exact source (knitbrain_query_dependents + read the real file via knitbrain_retrieve) and have the change reviewed.\n"
+        : "";
+    return `---
+name: ${spec.name}
+description: ${description}
+tools: ${tools}
+---
+
+You are the **${spec.name}** agent for this project.
+
+## Guardrails
+- **Scope:** only touch files under \`${scope}\`. Do not edit outside this domain.
+- **Allowed tools:** ${tools}.
+${gate}- **Context budget:** keep your working context under ~${budget} tokens. For large payloads, call \`knitbrain_optimize\` and page originals back with \`knitbrain_retrieve\` only when needed.
+
+## How to work
+1. Ground yourself: \`knitbrain_query_imports\` / \`knitbrain_query_dependents\` before editing.
+2. Make the smallest correct change within scope.
+3. Record non-obvious findings with \`knitbrain_record_learning\`.
+`;
+}
+/** Write a generated agent to the project's .claude/agents directory. */
+export function writeAgent(projectRoot, spec) {
+    // SECURITY: the name becomes a filename — restrict to a safe slug so it can
+    // never escape .claude/agents (no separators, dots, or empty names).
+    const safeName = spec.name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
+    if (safeName.length === 0)
+        throw new Error(`invalid agent name: ${JSON.stringify(spec.name)}`);
+    const dir = join(projectRoot, ".claude", "agents");
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${safeName}.md`);
+    spec = { ...spec, name: safeName };
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, generateAgentMarkdown(spec), "utf8");
+    renameSync(tmp, path);
+    return path;
+}
+//# sourceMappingURL=agents.js.map

package/dist/engine/agents.js.map

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

package/dist/engine/calibration.d.ts

@@ -0,0 +1,29 @@
+import type { Tier } from "./workflow.js";
+/**
+ * Classifier calibration — the false-positive self-healing loop.
+ *
+ * When the tier classifier gets it wrong, the agent records a false positive
+ * (claimed tier vs what it actually was). After 3 same-direction FPs the
+ * scope threshold shifts by 1 (then the counter resets, so the next shift
+ * needs 3 fresh votes). Deterministic and per-project, like TOIN: a wrong
+ * verdict becomes a training signal, never a permanent annoyance.
+ */
+export interface CalibrationState {
+    /** "<claimed>-was-<actual>" → count toward the next shift. */
+    fpDirections: Record<string, number>;
+    /**
+     * Shifts the file-count threshold for "complex". Positive = classifier was
+     * over-sensitive (called things complex that weren't) → require more files.
+     */
+    scopeAdjust: number;
+    updatedAt: string;
+}
+export interface Calibration {
+    /** Record a wrong classification. Returns the new state (post-shift if tripped). */
+    recordFalsePositive(claimed: Tier, actual: Tier): CalibrationState & {
+        shifted: boolean;
+    };
+    get(): CalibrationState;
+    reset(): CalibrationState;
+}
+export declare function createCalibration(root: string): Calibration;

package/dist/engine/calibration.js

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** Same-direction FPs needed before a threshold shift. */
+const ADJUSTMENT_THRESHOLD = 3;
+/** scopeAdjust is clamped — calibration tunes, it must never disable the classifier. */
+const MAX_ADJUST = 2;
+const TIERS = new Set(["inquiry", "trivial", "standard", "complex"]);
+const fresh = () => ({
+    fpDirections: {},
+    scopeAdjust: 0,
+    updatedAt: new Date(0).toISOString(),
+});
+export function createCalibration(root) {
+    mkdirSync(root, { recursive: true });
+    const path = join(root, "calibration.json");
+    // Multiple processes may share this store — re-read disk before every
+    // public operation (same lesson as feedback/meter: no stale reads).
+    const load = () => {
+        if (!existsSync(path))
+            return fresh();
+        try {
+            const p = JSON.parse(readFileSync(path, "utf8"));
+            return {
+                fpDirections: p.fpDirections && typeof p.fpDirections === "object" ? { ...p.fpDirections } : {},
+                scopeAdjust: typeof p.scopeAdjust === "number" ? p.scopeAdjust : 0,
+                updatedAt: typeof p.updatedAt === "string" ? p.updatedAt : new Date(0).toISOString(),
+            };
+        }
+        catch {
+            return fresh();
+        }
+    };
+    const save = (state) => {
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(state, null, 2), "utf8");
+        renameSync(tmp, path);
+    };
+    const clamp = (v) => Math.max(-MAX_ADJUST, Math.min(MAX_ADJUST, v));
+    return {
+        recordFalsePositive(claimed, actual) {
+            if (!TIERS.has(claimed) || !TIERS.has(actual) || claimed === actual) {
+                return { ...load(), shifted: false };
+            }
+            const state = load();
+            const direction = `${claimed}-was-${actual}`;
+            state.fpDirections[direction] = (state.fpDirections[direction] ?? 0) + 1;
+            let shifted = false;
+            if (state.fpDirections[direction] >= ADJUSTMENT_THRESHOLD) {
+                // Over-sensitive: we said complex, it wasn't → raise the bar.
+                if (claimed === "complex")
+                    state.scopeAdjust = clamp(state.scopeAdjust + 1);
+                // Under-sensitive: it WAS complex and we missed it → lower the bar.
+                else if (actual === "complex")
+                    state.scopeAdjust = clamp(state.scopeAdjust - 1);
+                // Other directions are counted but don't shift today.
+                state.fpDirections[direction] = 0; // next shift needs 3 fresh votes
+                shifted = true;
+            }
+            state.updatedAt = new Date().toISOString();
+            save(state);
+            return { ...state, shifted };
+        },
+        get: load,
+        reset() {
+            const state = fresh();
+            state.updatedAt = new Date().toISOString();
+            save(state);
+            return state;
+        },
+    };
+}
+//# sourceMappingURL=calibration.js.map

package/dist/engine/calibration.js.map

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

package/dist/engine/feedback.d.ts

@@ -0,0 +1,30 @@
+import type { ContentType } from "../optimizer/types.js";
+export interface FeedbackStat {
+    kind: ContentType;
+    compressions: number;
+    retrievals: number;
+    /** retrievals / compressions — high means we over-compressed this kind. */
+    rate: number;
+    /** true once we've backed off (stopped compressing this kind). */
+    skipping: boolean;
+}
+export interface Feedback {
+    /** Record that a payload of `kind` was compressed under `handle`. */
+    onCompress(kind: ContentType, handle: string): void;
+    /** Record that a stored `handle` was paged back (a vote that the skeleton wasn't enough). */
+    onRetrieve(handle: string): void;
+    /** Self-tuning verdict: should we STOP compressing this kind (over-retrieved)? */
+    shouldSkip(kind: ContentType): boolean;
+    stats(): FeedbackStat[];
+}
+export interface FeedbackOptions {
+    /** Minimum compressions before the skip verdict can trigger. */
+    minSamples?: number;
+    /** Retrieval rate above which we back off and stop compressing a kind. */
+    maxRate?: number;
+}
+/**
+ * TOIN feedback — deterministic, local self-tuning. Because CCR is lossless, a
+ * wrong verdict only costs efficiency (more retrievals), never correctness.
+ */
+export declare function createFeedback(root: string, opts?: FeedbackOptions): Feedback;

package/dist/engine/feedback.js

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const KINDS = ["json", "code", "text", "prose"];
+/**
+ * TOIN feedback — deterministic, local self-tuning. Because CCR is lossless, a
+ * wrong verdict only costs efficiency (more retrievals), never correctness.
+ */
+export function createFeedback(root, opts = {}) {
+    const minSamples = opts.minSamples ?? 8;
+    const maxRate = opts.maxRate ?? 0.6;
+    mkdirSync(root, { recursive: true });
+    const path = join(root, "feedback.json");
+    let state = { kinds: {}, handleKind: {} };
+    // Multiple processes share this store (MCP server, proxy, dashboard), so
+    // every public operation re-reads disk first — a constructed-once instance
+    // must never serve stale counters from another process's writes.
+    const reload = () => {
+        if (!existsSync(path))
+            return;
+        try {
+            state = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            /* keep current in-memory state */
+        }
+    };
+    reload();
+    const bucket = (kind) => {
+        const b = state.kinds[kind] ?? { compressions: 0, retrievals: 0 };
+        state.kinds[kind] = b;
+        return b;
+    };
+    const save = () => {
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(state), "utf8");
+        renameSync(tmp, path);
+    };
+    const rate = (kind) => {
+        const b = state.kinds[kind];
+        if (!b || b.compressions === 0)
+            return 0;
+        return b.retrievals / b.compressions;
+    };
+    const skip = (kind) => {
+        const b = state.kinds[kind];
+        return Boolean(b && b.compressions >= minSamples && rate(kind) > maxRate);
+    };
+    return {
+        onCompress(kind, handle) {
+            reload();
+            bucket(kind).compressions += 1;
+            state.handleKind[handle] = kind;
+            save();
+        },
+        onRetrieve(handle) {
+            reload();
+            const kind = state.handleKind[handle];
+            if (!kind)
+                return;
+            bucket(kind).retrievals += 1;
+            save();
+        },
+        shouldSkip(kind) {
+            reload();
+            return skip(kind);
+        },
+        stats() {
+            reload();
+            return KINDS.map((kind) => {
+                const b = state.kinds[kind] ?? { compressions: 0, retrievals: 0 };
+                return {
+                    kind,
+                    compressions: b.compressions,
+                    retrievals: b.retrievals,
+                    rate: Math.round(rate(kind) * 100) / 100,
+                    skipping: skip(kind),
+                };
+            });
+        },
+    };
+}
+//# sourceMappingURL=feedback.js.map

package/dist/engine/feedback.js.map

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

package/dist/engine/knowledge.d.ts

@@ -0,0 +1,22 @@
+export interface ImportEdge {
+    /** The raw module specifier, e.g. "./foo" or "node:fs". */
+    from: string;
+    /** Imported names (best-effort). */
+    names: string[];
+}
+export interface FileNode {
+    file: string;
+    imports: ImportEdge[];
+    exports: string[];
+}
+export interface Knowledge {
+    scan(): {
+        files: number;
+    };
+    queryImports(file: string): ImportEdge[] | null;
+    queryExports(file: string): string[] | null;
+    queryDependents(file: string): string[];
+    listFiles(): string[];
+}
+/** Project-scoped import/export graph. Regex-based (TS/JS), dependency-free. */
+export declare function createKnowledge(projectRoot: string, cacheDir: string): Knowledge;

package/dist/engine/knowledge.js

@@ -0,0 +1,154 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+const SOURCE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "coverage", "build", ".next"]);
+function parseImports(src) {
+    const edges = [];
+    const fromRe = /import\s+(?:type\s+)?([\s\S]*?)\s+from\s*['"]([^'"]+)['"]/g;
+    const bareRe = /import\s*['"]([^'"]+)['"]/g;
+    const reqRe = /require\(\s*['"]([^'"]+)['"]\s*\)/g;
+    let m;
+    while ((m = fromRe.exec(src)))
+        edges.push({ from: m[2], names: parseClause(m[1]) });
+    while ((m = bareRe.exec(src)))
+        edges.push({ from: m[1], names: [] });
+    while ((m = reqRe.exec(src)))
+        edges.push({ from: m[1], names: [] });
+    return edges;
+}
+function parseClause(clause) {
+    const names = [];
+    const braced = clause.match(/\{([^}]*)\}/);
+    if (braced) {
+        for (const part of braced[1].split(",")) {
+            const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+            if (name)
+                names.push(name);
+        }
+    }
+    const star = clause.match(/\*\s+as\s+([A-Za-z0-9_$]+)/);
+    if (star)
+        names.push(star[1]);
+    const def = clause.replace(/\{[^}]*\}/, "").replace(/\*\s+as\s+[A-Za-z0-9_$]+/, "").trim().replace(/,$/, "").trim();
+    if (def && /^[A-Za-z0-9_$]+$/.test(def))
+        names.push(def);
+    return names;
+}
+function parseExports(src) {
+    const names = new Set();
+    const declRe = /export\s+(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var|interface|type|enum)\s+([A-Za-z0-9_$]+)/g;
+    const listRe = /export\s*\{([^}]*)\}/g;
+    let m;
+    while ((m = declRe.exec(src)))
+        names.add(m[1]);
+    while ((m = listRe.exec(src))) {
+        for (const part of m[1].split(",")) {
+            const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+            if (name)
+                names.add(name);
+        }
+    }
+    if (/export\s+default\b/.test(src))
+        names.add("default");
+    return [...names];
+}
+/** Project-scoped import/export graph. Regex-based (TS/JS), dependency-free. */
+export function createKnowledge(projectRoot, cacheDir) {
+    mkdirSync(cacheDir, { recursive: true });
+    const cachePath = join(cacheDir, "graph.json");
+    const graph = new Map();
+    let scanned = false;
+    if (existsSync(cachePath)) {
+        try {
+            const nodes = JSON.parse(readFileSync(cachePath, "utf8"));
+            for (const n of nodes)
+                graph.set(n.file, n);
+            scanned = true;
+        }
+        catch {
+            /* rebuild on next query */
+        }
+    }
+    const norm = (file) => relative(projectRoot, resolve(projectRoot, file)).split("\\").join("/");
+    function walk(dir, out) {
+        for (const entry of readdirSync(dir)) {
+            if (SKIP_DIRS.has(entry) || entry.startsWith("."))
+                continue;
+            const full = join(dir, entry);
+            const st = statSync(full);
+            if (st.isDirectory())
+                walk(full, out);
+            else if (SOURCE_EXT.test(entry))
+                out.push(full);
+        }
+    }
+    function doScan() {
+        graph.clear();
+        const files = [];
+        walk(projectRoot, files);
+        for (const full of files) {
+            const src = readFileSync(full, "utf8");
+            const file = norm(full);
+            graph.set(file, { file, imports: parseImports(src), exports: parseExports(src) });
+        }
+        const tmp = `${cachePath}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify([...graph.values()]), "utf8");
+        renameSync(tmp, cachePath);
+        scanned = true;
+        return { files: graph.size };
+    }
+    const ensure = () => {
+        if (!scanned || graph.size === 0)
+            doScan();
+    };
+    /** Resolve a relative import specifier from `nodeFile` to a known graph file. */
+    function resolveEdge(nodeFile, spec) {
+        if (!spec.startsWith("."))
+            return null; // external/node module
+        const base = resolve(projectRoot, dirname(nodeFile), spec);
+        const baseRel = relative(projectRoot, base).split("\\").join("/");
+        const candidates = [
+            baseRel,
+            ...["ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs"].flatMap((e) => [
+                `${baseRel}.${e}`,
+                `${baseRel}/index.${e}`,
+            ]),
+            // imports often use .js for NodeNext — also try swapping to .ts
+            baseRel.replace(/\.js$/, ".ts"),
+        ];
+        for (const c of candidates)
+            if (graph.has(c))
+                return c;
+        return null;
+    }
+    return {
+        scan: doScan,
+        queryImports(file) {
+            ensure();
+            return graph.get(norm(file))?.imports ?? null;
+        },
+        queryExports(file) {
+            ensure();
+            return graph.get(norm(file))?.exports ?? null;
+        },
+        listFiles() {
+            ensure();
+            return [...graph.keys()];
+        },
+        queryDependents(file) {
+            ensure();
+            const target = norm(file);
+            const deps = [];
+            for (const node of graph.values()) {
+                for (const edge of node.imports) {
+                    if (resolveEdge(node.file, edge.from) === target) {
+                        deps.push(node.file);
+                        break;
+                    }
+                }
+            }
+            return deps;
+        },
+    };
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/engine/knowledge.js.map

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

package/dist/engine/memory.d.ts

@@ -0,0 +1,35 @@
+/** A recorded project learning. */
+export interface Learning {
+    id: string;
+    date: string;
+    summary: string;
+    lesson: string;
+    tags: string[];
+}
+/** A search hit: headline only (call getLearning for the full lesson). */
+export interface LearningHeadline {
+    id: string;
+    summary: string;
+    tags: string[];
+    score: number;
+}
+export interface Memory {
+    recordLearning(input: {
+        summary: string;
+        lesson: string;
+        tags?: string[];
+    }): {
+        id: string;
+        duplicate: boolean;
+    };
+    searchLearnings(query: string, limit?: number): LearningHeadline[];
+    getLearning(id: string): Learning | undefined;
+    listLearnings(): Learning[];
+    saveHandoff(state: string): void;
+    loadSession(): {
+        handoff: string | null;
+        topLearnings: LearningHeadline[];
+    };
+}
+/** Per-project, file-backed memory (learnings + handoff). Deterministic, local. */
+export declare function createMemory(root: string): Memory;

package/dist/engine/memory.js

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const tokenize = (s) => s.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1);
+function writeAtomic(path, data) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, data, "utf8");
+    renameSync(tmp, path);
+}
+/** Per-project, file-backed memory (learnings + handoff). Deterministic, local. */
+export function createMemory(root) {
+    mkdirSync(root, { recursive: true });
+    const learningsPath = join(root, "learnings.json");
+    const handoffPath = join(root, "handoff.txt");
+    const load = () => {
+        if (!existsSync(learningsPath))
+            return [];
+        try {
+            return JSON.parse(readFileSync(learningsPath, "utf8"));
+        }
+        catch {
+            return [];
+        }
+    };
+    const headline = (l, score) => ({
+        id: l.id,
+        summary: l.summary,
+        tags: l.tags,
+        score,
+    });
+    return {
+        recordLearning(input) {
+            const all = load();
+            const summary = input.summary.trim();
+            // Dedup by substring match on summary (mirrors engram behavior).
+            const dup = all.find((l) => l.summary.includes(summary) || summary.includes(l.summary));
+            if (dup)
+                return { id: dup.id, duplicate: true };
+            const id = createHash("sha256")
+                .update(summary + Date.now())
+                .digest("hex")
+                .slice(0, 12);
+            const learning = {
+                id,
+                date: new Date().toISOString().slice(0, 10),
+                summary,
+                lesson: input.lesson,
+                tags: input.tags ?? [],
+            };
+            writeAtomic(learningsPath, JSON.stringify([...all, learning], null, 2));
+            return { id, duplicate: false };
+        },
+        searchLearnings(query, limit = 5) {
+            const terms = new Set(tokenize(query));
+            if (terms.size === 0)
+                return [];
+            const scored = load().map((l) => {
+                const summaryTerms = new Set(tokenize(l.summary + " " + l.tags.join(" ")));
+                const lessonTerms = new Set(tokenize(l.lesson));
+                let score = 0;
+                for (const t of terms) {
+                    if (summaryTerms.has(t))
+                        score += 2; // headline/tag match weighted higher
+                    else if (lessonTerms.has(t))
+                        score += 1;
+                }
+                return headline(l, score);
+            });
+            return scored
+                .filter((h) => h.score > 0)
+                .sort((a, b) => b.score - a.score)
+                .slice(0, limit);
+        },
+        getLearning(id) {
+            return load().find((l) => l.id === id);
+        },
+        listLearnings() {
+            return load();
+        },
+        saveHandoff(state) {
+            writeAtomic(handoffPath, state);
+        },
+        loadSession() {
+            const handoff = existsSync(handoffPath) ? readFileSync(handoffPath, "utf8") : null;
+            const top = load()
+                .slice(-5)
+                .reverse()
+                .map((l) => headline(l, 0));
+            return { handoff, topLearnings: top };
+        },
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/engine/memory.js.map

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