@gracker/smartperfetto 1.0.13

package/dist/agentv3/mcpToolRegistry.js

@@ -0,0 +1,152 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpToolRegistry = exports.MCP_NAME_PREFIX = void 0;
+exports.filterByExposure = filterByExposure;
+exports.buildAllowedTools = buildAllowedTools;
+/**
+ * McpToolRegistry — single source of truth for MCP tools registered
+ * by SmartPerfetto.
+ *
+ * Plan 41 M0 (this file): extract the registry that
+ * `claudeMcpServer.ts` already maintained as an inline
+ * `toolEntries: Array<{tool, name}>` array. The registry adds:
+ *   - explicit `McpToolExposure` per entry (public / internal /
+ *     deprecated) so future hosts (stdio, A2A) can filter without
+ *     re-deciding policy
+ *   - shared `MCP_NAME_PREFIX` handling so `allowedTools` always
+ *     matches the SDK's expectation
+ *   - one place to derive an `McpToolAci[]` snapshot (used by M1
+ *     to populate `McpPublicApiContract`)
+ *
+ * Critical invariant: this file changes NO runtime behavior. The
+ * existing in-process SDK MCP server keeps registering the same
+ * tools with the same short names; the registry is just the named
+ * vehicle. Trace regression 6/6 PASS proves zero impact.
+ *
+ * Out of scope for M0:
+ *   - stdio adapter (lands in M1 as `standaloneMcpServer.ts`)
+ *   - A2A AgentCard (M2)
+ *   - SupersedeStoreReadOnlyAdapter (M1a, prerequisite for raising
+ *     `recall_patterns` exposure from internal back to public)
+ *
+ * @module mcpToolRegistry
+ */
+const claude_agent_sdk_1 = require("@anthropic-ai/claude-agent-sdk");
+const sparkContracts_1 = require("../types/sparkContracts");
+/** MCP tool name prefix — derived from the server name `'smartperfetto'`.
+ * `claudeMcpServer.ts` exports the same constant; both files agree
+ * because both import from this module. The SDK consumes prefixed
+ * names in its `allowedTools` array; the MCP protocol itself uses
+ * short names. */
+exports.MCP_NAME_PREFIX = 'mcp__smartperfetto__';
+/**
+ * Filter the registry contents by one or more exposure levels.
+ *
+ * Useful for stdio adapter (`['public']`) or admin-only paths
+ * (`['internal']`). The default `claudeMcpServer.ts` consumer takes
+ * everything, including internal session-protocol tools, because the
+ * Claude SDK is the agent itself and is the legitimate caller of
+ * those tools.
+ */
+function filterByExposure(defs, exposures) {
+    const wanted = new Set(exposures);
+    return defs.filter(d => wanted.has(d.exposure));
+}
+/** Derive the SDK `allowedTools` array — short names with the
+ * SmartPerfetto prefix. Order is preserved so callers that care
+ * about deterministic ordering get it. */
+function buildAllowedTools(defs) {
+    return defs.map(d => `${exports.MCP_NAME_PREFIX}${d.name}`);
+}
+/**
+ * The McpToolRegistry collects tool definitions and emits the views
+ * the existing `claudeMcpServer.ts` consumer needs (SDK server +
+ * allowedTools list) plus the views M1 will need (stdio dispatcher,
+ * ACI snapshot for `McpPublicApiContract`).
+ *
+ * Stateful registration order matters — the SDK uses array order to
+ * match `allowedTools[i]` to `tools[i]`. `register()` appends; later
+ * calls cannot reorder the registry.
+ */
+class McpToolRegistry {
+    constructor() {
+        this.entries = [];
+    }
+    /** Add a tool to the registry. Does NOT prevent duplicates by
+     * name; callers control ordering and uniqueness explicitly so the
+     * existing conditional registration patterns
+     * (`if (writeAnalysisNote) registry.register(...)`) keep working. */
+    register(def) {
+        this.entries.push(def);
+    }
+    /** Convenience for the existing call sites that pass `(tool,
+     * name)` — keeps the migration patch in `claudeMcpServer.ts`
+     * minimal. */
+    registerSdk(tool, name, exposure, extras) {
+        this.register({ tool, name, exposure, ...extras });
+    }
+    /** Read-only view of every entry in registration order. */
+    list() {
+        return this.entries;
+    }
+    /** Build the SDK's in-process MCP server. The SDK names the server
+     * `smartperfetto` to align with `MCP_NAME_PREFIX`; that linkage is
+     * preserved here. */
+    buildSdkServer(opts = {}) {
+        return (0, claude_agent_sdk_1.createSdkMcpServer)({
+            name: opts.name ?? 'smartperfetto',
+            version: opts.version ?? '1.0.0',
+            // The SDK accepts `unknown[]` here because tool() returns its own
+            // opaque shape. Cast at the boundary; consumers do not get to
+            // peek inside a tool descriptor.
+            tools: this.entries.map(e => e.tool),
+        });
+    }
+    /** Allowed-tools array prefixed for the SDK call site. Matches the
+     * exact format `claudeMcpServer.ts` returned before the refactor. */
+    buildAllowedTools() {
+        return buildAllowedTools(this.entries);
+    }
+    /** Snapshot of the registry as `McpToolAci[]` — drives the future
+     * `McpPublicApiContract.tools` field once M1 populates summary /
+     * inputSchema / examples per tool. M0 emits a minimal ACI with
+     * just name + qualified name + exposure; the description / schema
+     * fields stay optional so older snapshots remain readable. */
+    getAci() {
+        return this.entries.map(e => ({
+            toolName: e.name,
+            qualifiedName: `${exports.MCP_NAME_PREFIX}${e.name}`,
+            exposure: e.exposure,
+            summary: e.summary ?? '',
+            ...(e.requires ? { requires: e.requires } : {}),
+        }));
+    }
+    /** Build a minimal `McpPublicApiContract` for export / inspection.
+     * `agentCards` is empty for now (Plan 41 M2 populates it once A2A
+     * is opt-in enabled). */
+    buildPublicApiContract(opts = {}) {
+        return {
+            ...(0, sparkContracts_1.makeSparkProvenance)({ source: 'mcpToolRegistry' }),
+            tools: this.getAci(),
+            serverVersion: opts.serverVersion ?? '1.0.0',
+            protocolVersion: opts.protocolVersion ?? '2024-11-05',
+            coverage: [
+                { sparkId: 91, planId: '41', status: 'scaffolded' },
+                { sparkId: 92, planId: '41', status: 'scaffolded' },
+                { sparkId: 96, planId: '41', status: 'scaffolded' },
+                { sparkId: 133, planId: '41', status: 'scaffolded' },
+                { sparkId: 139, planId: '41', status: 'scaffolded' },
+                { sparkId: 173, planId: '41', status: 'scaffolded' },
+            ],
+        };
+    }
+    /** Number of registered tools — useful in tests. */
+    size() {
+        return this.entries.length;
+    }
+}
+exports.McpToolRegistry = McpToolRegistry;
+//# sourceMappingURL=mcpToolRegistry.js.map

package/dist/agentv3/mcpToolRegistry.js.map

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

package/dist/agentv3/outputLanguage.d.ts

@@ -0,0 +1,6 @@
+export type OutputLanguage = 'zh-CN' | 'en';
+export declare const DEFAULT_OUTPUT_LANGUAGE: OutputLanguage;
+export declare function parseOutputLanguage(value: unknown): OutputLanguage;
+export declare function outputLanguageDisplayName(language: OutputLanguage): string;
+export declare function localize(language: OutputLanguage, zh: string, en: string): string;
+//# sourceMappingURL=outputLanguage.d.ts.map

package/dist/agentv3/outputLanguage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputLanguage.d.ts","sourceRoot":"","sources":["../../src/agentv3/outputLanguage.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,IAAI,CAAC;AAE5C,eAAO,MAAM,uBAAuB,EAAE,cAAwB,CAAC;AAE/D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAqBlE;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAE1E;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEjF"}

package/dist/agentv3/outputLanguage.js

@@ -0,0 +1,37 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OUTPUT_LANGUAGE = void 0;
+exports.parseOutputLanguage = parseOutputLanguage;
+exports.outputLanguageDisplayName = outputLanguageDisplayName;
+exports.localize = localize;
+exports.DEFAULT_OUTPUT_LANGUAGE = 'zh-CN';
+function parseOutputLanguage(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (!normalized)
+        return exports.DEFAULT_OUTPUT_LANGUAGE;
+    if (['en', 'en-us', 'en_us', 'english'].includes(normalized)) {
+        return 'en';
+    }
+    if ([
+        'zh',
+        'zh-cn',
+        'zh_cn',
+        'cn',
+        'chinese',
+        'simplified-chinese',
+        'simplified_chinese',
+    ].includes(normalized)) {
+        return 'zh-CN';
+    }
+    return exports.DEFAULT_OUTPUT_LANGUAGE;
+}
+function outputLanguageDisplayName(language) {
+    return language === 'en' ? 'English' : '简体中文';
+}
+function localize(language, zh, en) {
+    return language === 'en' ? en : zh;
+}
+//# sourceMappingURL=outputLanguage.js.map

package/dist/agentv3/outputLanguage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputLanguage.js","sourceRoot":"","sources":["../../src/agentv3/outputLanguage.ts"],"names":[],"mappings":";AAAA,6CAA6C;AAC7C,0CAA0C;AAC1C,+DAA+D;;;AAM/D,kDAqBC;AAED,8DAEC;AAED,4BAEC;AA/BY,QAAA,uBAAuB,GAAmB,OAAO,CAAC;AAE/D,SAAgB,mBAAmB,CAAC,KAAc;IAChD,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5D,IAAI,CAAC,UAAU;QAAE,OAAO,+BAAuB,CAAC;IAEhD,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI;QACF,IAAI;QACJ,OAAO;QACP,OAAO;QACP,IAAI;QACJ,SAAS;QACT,oBAAoB;QACpB,oBAAoB;KACrB,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACvB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,+BAAuB,CAAC;AACjC,CAAC;AAED,SAAgB,yBAAyB,CAAC,QAAwB;IAChE,OAAO,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;AAChD,CAAC;AAED,SAAgB,QAAQ,CAAC,QAAwB,EAAE,EAAU,EAAE,EAAU;IACvE,OAAO,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACrC,CAAC"}

package/dist/agentv3/phaseHintMatcher.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure phase-hint matching used by `update_plan_phase` to pick the
+ * restatement to inject into a tool response. Extracted from
+ * `claudeMcpServer.ts` (Phase 4 of v2.1) so the algorithm can be unit
+ * tested without standing up a full MCP server.
+ *
+ * Match by weighted keyword overlap against the next phase's `name + goal`.
+ * Phase names are weighted higher than goals so a phase named "综合结论"
+ * is not stolen by goal text that happens to mention "根因/代表帧".
+ *
+ * Do not use an unconditional critical fallback here. Real e2e runs showed
+ * that fallback injecting root-cause reminders into identity/global-context
+ * phases is worse than omitting a reminder.
+ */
+import type { PhaseHint } from './strategyLoader';
+interface PhaseSnapshot {
+    name: string;
+    goal?: string;
+    summary?: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'skipped';
+}
+/**
+ * Resolve the hint to inject into the response of a phase transition.
+ * Returns `undefined` when no hint is applicable (e.g. agent's phase
+ * matches no keywords AND every critical hint has already been covered).
+ */
+export declare function matchPhaseHintForNextPhase(input: {
+    hints: ReadonlyArray<PhaseHint>;
+    nextPhase: {
+        name: string;
+        goal?: string;
+    };
+    finishedPhases: ReadonlyArray<PhaseSnapshot>;
+}): PhaseHint | undefined;
+export {};
+//# sourceMappingURL=phaseHintMatcher.d.ts.map

package/dist/agentv3/phaseHintMatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phaseHintMatcher.d.ts","sourceRoot":"","sources":["../../src/agentv3/phaseHintMatcher.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;CAC7D;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAChC,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,cAAc,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;CAC9C,GAAG,SAAS,GAAG,SAAS,CAiCxB"}

package/dist/agentv3/phaseHintMatcher.js

@@ -0,0 +1,48 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchPhaseHintForNextPhase = matchPhaseHintForNextPhase;
+/**
+ * Resolve the hint to inject into the response of a phase transition.
+ * Returns `undefined` when no hint is applicable (e.g. agent's phase
+ * matches no keywords AND every critical hint has already been covered).
+ */
+function matchPhaseHintForNextPhase(input) {
+    const { hints, nextPhase, finishedPhases } = input;
+    if (hints.length === 0)
+        return undefined;
+    const phaseName = nextPhase.name.toLowerCase();
+    const phaseGoal = (nextPhase.goal ?? '').toLowerCase();
+    const keywordWeight = (keyword) => {
+        const normalized = keyword.trim();
+        if (normalized.length <= 1)
+            return 0;
+        if (normalized.length <= 2)
+            return 4;
+        return 6 + Math.min(normalized.length, 12);
+    };
+    const scoreHint = (hint) => {
+        let score = 0;
+        for (const keyword of hint.keywords) {
+            const kw = keyword.toLowerCase();
+            if (!kw)
+                continue;
+            const weight = keywordWeight(kw);
+            if (phaseName.includes(kw))
+                score += weight * 5;
+            if (phaseGoal.includes(kw))
+                score += weight;
+        }
+        return score;
+    };
+    const keywordMatches = hints
+        .map((hint, index) => ({ hint, index, score: scoreHint(hint) }))
+        .filter(item => item.score > 0)
+        .sort((a, b) => b.score - a.score || a.index - b.index);
+    if (keywordMatches.length > 0)
+        return keywordMatches[0].hint;
+    return undefined;
+}
+//# sourceMappingURL=phaseHintMatcher.js.map

package/dist/agentv3/phaseHintMatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phaseHintMatcher.js","sourceRoot":"","sources":["../../src/agentv3/phaseHintMatcher.ts"],"names":[],"mappings":";AAAA,6CAA6C;AAC7C,0CAA0C;AAC1C,+DAA+D;;AA+B/D,gEAqCC;AA1CD;;;;GAIG;AACH,SAAgB,0BAA0B,CAAC,KAI1C;IACC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzC,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IAC/C,MAAM,SAAS,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAEvD,MAAM,aAAa,GAAG,CAAC,OAAe,EAAU,EAAE;QAChD,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;QACrC,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;QACrC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,IAAe,EAAU,EAAE;QAC5C,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YACjC,IAAI,CAAC,EAAE;gBAAE,SAAS;YAClB,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,CAAC,CAAC;YACjC,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAAE,KAAK,IAAI,MAAM,GAAG,CAAC,CAAC;YAChD,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAAE,KAAK,IAAI,MAAM,CAAC;QAC9C,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,MAAM,cAAc,GAAG,KAAK;SACzB,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;SAC/D,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;SAC9B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1D,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE7D,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/agentv3/projectMemory.d.ts

@@ -0,0 +1,80 @@
+import { type ProjectMemoryEntry, type MemoryPromotionPolicy, type MemoryScope } from '../types/sparkContracts';
+import { type KnowledgeScope } from '../services/scopedKnowledgeStore';
+/** One audit-log row recording a cross-scope promotion. */
+export interface PromotionAuditEntry {
+    entryId: string;
+    policy: MemoryPromotionPolicy;
+    /** Wall-clock when the audit row was written (epoch ms). */
+    auditedAt: number;
+}
+export interface ListOptions {
+    scope?: Exclude<MemoryScope, 'session'>;
+    projectKey?: string;
+    /** Restrict to entries whose `tags` overlap with at least one of these. */
+    anyOfTags?: string[];
+}
+export interface RecallOptions {
+    /** Restrict to a scope. Defaults to all (project + world). */
+    scope?: Exclude<MemoryScope, 'session'>;
+    /** Restrict to a project key prefix (exact match). */
+    projectKey?: string;
+    /** Tag tokens to score against — entries with overlap rank higher. */
+    tags?: string[];
+    /** Maximum hits returned. Defaults to 5. */
+    topK?: number;
+}
+/** One recall hit with the score that ranked it. The hit object is a
+ * shallow copy of the stored entry — recall never mutates the store
+ * even via reference sharing. */
+export interface RecallHit {
+    entry: ProjectMemoryEntry;
+    score: number;
+}
+/**
+ * ProjectMemory — local file-backed store for project + world entries.
+ * Session entries stay in `analysisPatternMemory.ts` and are not
+ * touched by this class.
+ */
+export declare class ProjectMemory {
+    private readonly storagePath;
+    private readonly entries;
+    private readonly auditLog;
+    private loaded;
+    constructor(storagePath: string);
+    /** Idempotently load on-disk state into memory. */
+    load(): void;
+    /**
+     * Save (insert or replace) an entry. Throws when:
+     *   - scope is 'session' (those belong in analysisPatternMemory.ts)
+     *   - scope is 'world' but promotionPolicy is missing
+     *   - promotionPolicy carries a trigger outside the canonical enum
+     */
+    saveProjectMemoryEntry(entry: ProjectMemoryEntry, storageScope?: KnowledgeScope): void;
+    /** Get an entry by id. */
+    getProjectMemoryEntry(entryId: string, storageScope?: KnowledgeScope): ProjectMemoryEntry | undefined;
+    /** Remove an entry. Returns whether it was present. The promotion
+     * audit log is NOT redacted — past promotions stay traceable. */
+    removeProjectMemoryEntry(entryId: string, storageScope?: KnowledgeScope): boolean;
+    /** Filtered list, deterministically ordered by entryId. */
+    listProjectMemoryEntries(opts?: ListOptions, storageScope?: KnowledgeScope): ProjectMemoryEntry[];
+    /**
+     * Pure-read recall. Scores entries by tag overlap with the query
+     * tags. Never writes — `lastSeenAt` and any other mutable counters
+     * remain frozen even after thousands of recall calls.
+     */
+    recallProjectMemory(opts?: RecallOptions, storageScope?: KnowledgeScope): RecallHit[];
+    /**
+     * Promote an entry across scopes per the supplied policy. Throws on
+     * any trigger outside the enum; appends a row to the promotion
+     * audit log; sets `entry.promotionPolicy` to the supplied policy.
+     */
+    promoteEntry(entryId: string, policy: MemoryPromotionPolicy, storageScope?: KnowledgeScope): void;
+    /** Read-only view of the audit log, sorted by audit time ascending. */
+    getPromotionAudit(): PromotionAuditEntry[];
+    /** Count entries currently in storage by scope. */
+    getStats(storageScope?: KnowledgeScope): Record<'project' | 'world', number>;
+    private assertSaveInvariants;
+    /** Atomic temp+rename. Same contract as ragStore / baselineStore. */
+    private persist;
+}
+//# sourceMappingURL=projectMemory.d.ts.map

package/dist/agentv3/projectMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectMemory.d.ts","sourceRoot":"","sources":["../../src/agentv3/projectMemory.ts"],"names":[],"mappings":"AA2CA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAE1B,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAIL,KAAK,cAAc,EAKpB,MAAM,kCAAkC,CAAC;AAQ1C,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;CACnB;AAYD,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACxC,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;iCAEiC;AACjC,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IACjE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,MAAM,CAAS;gBAEX,WAAW,EAAE,MAAM;IAI/B,mDAAmD;IACnD,IAAI,IAAI,IAAI;IAqBZ;;;;;OAKG;IACH,sBAAsB,CACpB,KAAK,EAAE,kBAAkB,EACzB,YAAY,CAAC,EAAE,cAAc,GAC5B,IAAI;IAuBP,0BAA0B;IAC1B,qBAAqB,CACnB,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,cAAc,GAC5B,kBAAkB,GAAG,SAAS;IAYjC;qEACiE;IACjE,wBAAwB,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,cAAc,GAC5B,OAAO;IAcV,2DAA2D;IAC3D,wBAAwB,CACtB,IAAI,GAAE,WAAgB,EACtB,YAAY,CAAC,EAAE,cAAc,GAC5B,kBAAkB,EAAE;IAuBvB;;;;OAIG;IACH,mBAAmB,CACjB,IAAI,GAAE,aAAkB,EACxB,YAAY,CAAC,EAAE,cAAc,GAC5B,SAAS,EAAE;IAqCd;;;;OAIG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,qBAAqB,EAC7B,YAAY,CAAC,EAAE,cAAc,GAC5B,IAAI;IAoEP,uEAAuE;IACvE,iBAAiB,IAAI,mBAAmB,EAAE;IAK1C,mDAAmD;IACnD,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,SAAS,GAAG,OAAO,EAAE,MAAM,CAAC;IAiB5E,OAAO,CAAC,oBAAoB;IAqB5B,qEAAqE;IACrE,OAAO,CAAC,OAAO;CAahB"}