@praneeth_54/agentdoctor 1.0.0 → 1.1.1

package/dist/core/understanding/brain/contradictions/index.js

@@ -0,0 +1,57 @@
+import { withClaimStatus } from "../claims/lifecycle.js";
+import { createContradictionId } from "./types.js";
+/**
+ * Detect contradictory ACTIVE claims sharing subject+predicate with different objects.
+ * Marks those claims CONTRADICTED and returns contradiction records.
+ */
+export function detectContradictions(claims, snapshotId) {
+    const groups = new Map();
+    for (const claim of claims) {
+        if (claim.status !== "ACTIVE" && claim.status !== "CONTRADICTED") {
+            continue;
+        }
+        const key = `${claim.subject}\0${claim.predicate}`;
+        const list = groups.get(key) ?? [];
+        list.push(claim);
+        groups.set(key, list);
+    }
+    const contradictions = [];
+    const contradictedIds = new Map();
+    for (const [, group] of groups) {
+        const uniqueObjects = [...new Set(group.map((c) => c.object))];
+        if (uniqueObjects.length < 2) {
+            continue;
+        }
+        const subject = group[0]?.subject ?? "";
+        const predicate = group[0]?.predicate ?? "";
+        const id = createContradictionId(subject, predicate, uniqueObjects);
+        const claimIds = group.map((c) => c.id);
+        const evidenceIds = [...new Set(group.flatMap((c) => c.evidenceIds))];
+        contradictions.push({
+            id,
+            snapshotId,
+            claimIds,
+            subject,
+            predicate,
+            values: uniqueObjects.sort((a, b) => a.localeCompare(b)),
+            evidenceIds,
+            confidence: Math.min(...group.map((c) => c.confidence)),
+            rationale: `Multiple ACTIVE values for ${predicate} on ${subject}`,
+        });
+        for (const claim of group) {
+            const list = contradictedIds.get(claim.id) ?? [];
+            list.push(id);
+            contradictedIds.set(claim.id, list);
+        }
+    }
+    const nextClaims = claims.map((claim) => {
+        const contra = contradictedIds.get(claim.id);
+        if (!contra) {
+            return claim;
+        }
+        return withClaimStatus(claim, "CONTRADICTED", { contradictionIds: contra });
+    });
+    contradictions.sort((a, b) => a.id.localeCompare(b.id));
+    return { claims: nextClaims, contradictions };
+}
+export { createContradictionId } from "./types.js";

package/dist/core/understanding/brain/contradictions/types.d.ts

@@ -0,0 +1,12 @@
+export interface BrainContradiction {
+    id: string;
+    snapshotId: string;
+    claimIds: readonly string[];
+    subject: string;
+    predicate: string;
+    values: readonly string[];
+    evidenceIds: readonly string[];
+    confidence: number;
+    rationale: string;
+}
+export declare function createContradictionId(subject: string, predicate: string, values: readonly string[]): string;

package/dist/core/understanding/brain/contradictions/types.js

@@ -0,0 +1,8 @@
+export function createContradictionId(subject, predicate, values) {
+    const key = `${subject}\0${predicate}\0${[...values].sort().join("|")}`;
+    let hash = 0;
+    for (let i = 0; i < key.length; i++) {
+        hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
+    }
+    return `contra_${hash.toString(16).padStart(8, "0")}`;
+}

package/dist/core/understanding/brain/delta.d.ts

@@ -0,0 +1,25 @@
+import type { ProjectBrain } from "./types.js";
+import { type DeltaSchemaVersion } from "./version.js";
+export interface BrainDelta {
+    schemaVersion: DeltaSchemaVersion;
+    beforeSnapshotId: string;
+    afterSnapshotId: string;
+    addedClaimIds: readonly string[];
+    removedClaimIds: readonly string[];
+    changedClaimIds: readonly string[];
+    invalidatedClaimIds: readonly string[];
+    supersededClaimIds: readonly string[];
+    contradictedClaimIds: readonly string[];
+    newContradictionIds: readonly string[];
+    resolvedContradictionIds: readonly string[];
+    addedComponentIds: readonly string[];
+    removedComponentIds: readonly string[];
+    dependencyChanges: readonly string[];
+    ownershipChanges: readonly string[];
+    riskChanges: readonly string[];
+    summary: readonly string[];
+    createdAt: string;
+}
+export declare function buildBrainDelta(before: ProjectBrain, after: ProjectBrain): BrainDelta;
+export declare function serializeBrainDelta(delta: BrainDelta): string;
+export declare function parseBrainDelta(json: string): BrainDelta;

package/dist/core/understanding/brain/delta.js

@@ -0,0 +1,116 @@
+import { DELTA_SCHEMA_VERSION } from "./version.js";
+function claimFinger(c) {
+    return `${c.subject}|${c.predicate}|${c.object}|${c.status}|${c.confidence}`;
+}
+export function buildBrainDelta(before, after) {
+    const beforeClaims = new Map(before.claims.map((c) => [c.id, c]));
+    const afterClaims = new Map(after.claims.map((c) => [c.id, c]));
+    const addedClaimIds = [];
+    const removedClaimIds = [];
+    const changedClaimIds = [];
+    const invalidatedClaimIds = [];
+    const supersededClaimIds = [];
+    const contradictedClaimIds = [];
+    for (const [id, claim] of afterClaims) {
+        const prev = beforeClaims.get(id);
+        if (!prev) {
+            addedClaimIds.push(id);
+            continue;
+        }
+        if (claimFinger(prev) !== claimFinger(claim)) {
+            changedClaimIds.push(id);
+        }
+        if (claim.status === "INVALIDATED" && prev.status !== "INVALIDATED") {
+            invalidatedClaimIds.push(id);
+        }
+        if (claim.status === "SUPERSEDED" && prev.status !== "SUPERSEDED") {
+            supersededClaimIds.push(id);
+        }
+        if (claim.status === "CONTRADICTED" && prev.status !== "CONTRADICTED") {
+            contradictedClaimIds.push(id);
+        }
+    }
+    for (const id of beforeClaims.keys()) {
+        if (!afterClaims.has(id)) {
+            removedClaimIds.push(id);
+        }
+    }
+    const beforeContra = new Set(before.contradictions.map((c) => c.id));
+    const afterContra = new Set(after.contradictions.map((c) => c.id));
+    const newContradictionIds = [...afterContra].filter((id) => !beforeContra.has(id)).sort();
+    const resolvedContradictionIds = [...beforeContra].filter((id) => !afterContra.has(id)).sort();
+    const beforeComps = new Set(before.components.map((c) => c.id));
+    const afterComps = new Set(after.components.map((c) => c.id));
+    const addedComponentIds = [...afterComps].filter((id) => !beforeComps.has(id)).sort();
+    const removedComponentIds = [...beforeComps].filter((id) => !afterComps.has(id)).sort();
+    const depKey = (b) => b.model.dependencies.map((d) => `${d.from}->${d.to}:${d.type}`).sort();
+    const beforeDeps = new Set(depKey(before));
+    const afterDeps = new Set(depKey(after));
+    const dependencyChanges = [
+        ...[...afterDeps].filter((k) => !beforeDeps.has(k)).map((k) => `+${k}`),
+        ...[...beforeDeps].filter((k) => !afterDeps.has(k)).map((k) => `-${k}`),
+    ].sort();
+    const ownKey = (b) => b.ownership.ownerships.map((o) => `${o.path}:${o.owners.join(",")}`).sort();
+    const beforeOwn = new Set(ownKey(before));
+    const afterOwn = new Set(ownKey(after));
+    const ownershipChanges = [
+        ...[...afterOwn].filter((k) => !beforeOwn.has(k)).map((k) => `+${k}`),
+        ...[...beforeOwn].filter((k) => !afterOwn.has(k)).map((k) => `-${k}`),
+    ].sort();
+    const riskKey = (b) => b.risks.risks.map((r) => `${r.kind}:${r.target}`).sort();
+    const beforeRisk = new Set(riskKey(before));
+    const afterRisk = new Set(riskKey(after));
+    const riskChanges = [
+        ...[...afterRisk].filter((k) => !beforeRisk.has(k)).map((k) => `+${k}`),
+        ...[...beforeRisk].filter((k) => !afterRisk.has(k)).map((k) => `-${k}`),
+    ].sort();
+    const summary = [];
+    if (addedClaimIds.length || invalidatedClaimIds.length) {
+        summary.push(`Claims +${addedClaimIds.length} / invalidated ${invalidatedClaimIds.length}`);
+    }
+    if (dependencyChanges.length) {
+        summary.push(`Dependency changes: ${dependencyChanges.length}`);
+    }
+    if (ownershipChanges.length) {
+        summary.push(`Ownership changes: ${ownershipChanges.length}`);
+    }
+    if (riskChanges.length) {
+        summary.push(`Risk changes: ${riskChanges.length}`);
+    }
+    if (newContradictionIds.length || resolvedContradictionIds.length) {
+        summary.push(`Contradictions +${newContradictionIds.length}/-${resolvedContradictionIds.length}`);
+    }
+    if (summary.length === 0) {
+        summary.push("No structural brain changes");
+    }
+    return {
+        schemaVersion: DELTA_SCHEMA_VERSION,
+        beforeSnapshotId: before.snapshot.id,
+        afterSnapshotId: after.snapshot.id,
+        addedClaimIds: addedClaimIds.sort(),
+        removedClaimIds: removedClaimIds.sort(),
+        changedClaimIds: changedClaimIds.sort(),
+        invalidatedClaimIds: invalidatedClaimIds.sort(),
+        supersededClaimIds: supersededClaimIds.sort(),
+        contradictedClaimIds: contradictedClaimIds.sort(),
+        newContradictionIds,
+        resolvedContradictionIds,
+        addedComponentIds,
+        removedComponentIds,
+        dependencyChanges,
+        ownershipChanges,
+        riskChanges,
+        summary,
+        createdAt: after.metadata.updatedAt,
+    };
+}
+export function serializeBrainDelta(delta) {
+    return `${JSON.stringify(delta, null, 2)}\n`;
+}
+export function parseBrainDelta(json) {
+    const parsed = JSON.parse(json);
+    if (parsed.schemaVersion !== DELTA_SCHEMA_VERSION) {
+        throw new Error(`incompatible delta schema ${String(parsed.schemaVersion)}`);
+    }
+    return parsed;
+}

package/dist/core/understanding/brain/evidence/index.d.ts

@@ -0,0 +1,3 @@
+export type { BrainEvidence, EvidenceEpistemics, EvidenceKind, EvidenceRedactionStatus, } from "./types.js";
+export { buildEvidence, createEvidenceId } from "./types.js";
+export { redactEvidence, redactEvidenceList } from "./redact.js";

package/dist/core/understanding/brain/evidence/index.js

@@ -0,0 +1,2 @@
+export { buildEvidence, createEvidenceId } from "./types.js";
+export { redactEvidence, redactEvidenceList } from "./redact.js";

package/dist/core/understanding/brain/evidence/redact.d.ts

@@ -0,0 +1,4 @@
+import type { BrainEvidence } from "./types.js";
+/** Ensure evidence never carries secret plaintext; paths for sensitive files become path-only. */
+export declare function redactEvidence(evidence: BrainEvidence): BrainEvidence;
+export declare function redactEvidenceList(list: readonly BrainEvidence[]): BrainEvidence[];

package/dist/core/understanding/brain/evidence/redact.js

@@ -0,0 +1,36 @@
+import { looksLikeSensitiveFilename, redactSecretValue } from "../../../../security/redaction.js";
+const SECRETISH = /(password|secret|token|api[_-]?key|private[_-]?key|credential)/i;
+/** Ensure evidence never carries secret plaintext; paths for sensitive files become path-only. */
+export function redactEvidence(evidence) {
+    const locator = evidence.locator;
+    let redaction = evidence.redaction;
+    let safeLocator = locator;
+    let symbol = evidence.symbol;
+    if (looksLikeSensitiveFilename(locator) || SECRETISH.test(locator)) {
+        redaction = "path-only";
+        // Keep path reference only; never attach contents.
+        safeLocator = locator.split(/[/\\]/).slice(0, -1).concat("[REDACTED_NAME]").join("/");
+        if (safeLocator === "[REDACTED_NAME]") {
+            safeLocator = "[REDACTED_PATH]";
+        }
+    }
+    if (symbol && SECRETISH.test(symbol)) {
+        symbol = redactSecretValue(symbol);
+        redaction = "redacted";
+    }
+    const next = {
+        ...evidence,
+        locator: safeLocator,
+        redaction,
+    };
+    if (symbol !== undefined) {
+        next.symbol = symbol;
+    }
+    else {
+        delete next.symbol;
+    }
+    return next;
+}
+export function redactEvidenceList(list) {
+    return list.map(redactEvidence);
+}

package/dist/core/understanding/brain/evidence/types.d.ts

@@ -0,0 +1,34 @@
+import type { EvidenceSchemaVersion } from "../version.js";
+export type EvidenceKind = "path" | "file-presence" | "config-key" | "import-edge" | "role-signal" | "pattern-match" | "ownership-rule" | "model-statistic" | "derived";
+export type EvidenceEpistemics = "observed" | "inferred";
+export type EvidenceRedactionStatus = "none" | "path-only" | "redacted";
+export interface BrainEvidence {
+    schemaVersion: EvidenceSchemaVersion;
+    id: string;
+    kind: EvidenceKind;
+    /** Repository-relative locator (path, pattern, or symbolic key). Never secret contents. */
+    locator: string;
+    source: string;
+    snapshotId: string;
+    epistemics: EvidenceEpistemics;
+    symbol?: string;
+    range?: {
+        startLine: number;
+        endLine: number;
+    };
+    redaction: EvidenceRedactionStatus;
+}
+export declare function createEvidenceId(parts: readonly string[]): string;
+export declare function buildEvidence(input: {
+    kind: EvidenceKind;
+    locator: string;
+    source: string;
+    snapshotId: string;
+    epistemics: EvidenceEpistemics;
+    symbol?: string;
+    range?: {
+        startLine: number;
+        endLine: number;
+    };
+    redaction?: EvidenceRedactionStatus;
+}): BrainEvidence;

package/dist/core/understanding/brain/evidence/types.js

@@ -0,0 +1,35 @@
+import { EVIDENCE_SCHEMA_VERSION } from "../version.js";
+export function createEvidenceId(parts) {
+    const key = parts.join("\0");
+    let hash = 0;
+    for (let i = 0; i < key.length; i++) {
+        hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
+    }
+    return `ev_${hash.toString(16).padStart(8, "0")}`;
+}
+export function buildEvidence(input) {
+    const evidence = {
+        schemaVersion: EVIDENCE_SCHEMA_VERSION,
+        id: createEvidenceId([
+            input.kind,
+            input.locator,
+            input.source,
+            input.snapshotId,
+            input.epistemics,
+            input.symbol ?? "",
+        ]),
+        kind: input.kind,
+        locator: input.locator,
+        source: input.source,
+        snapshotId: input.snapshotId,
+        epistemics: input.epistemics,
+        redaction: input.redaction ?? "path-only",
+    };
+    if (input.symbol !== undefined) {
+        evidence.symbol = input.symbol;
+    }
+    if (input.range !== undefined) {
+        evidence.range = input.range;
+    }
+    return evidence;
+}

package/dist/core/understanding/brain/explain.d.ts

@@ -0,0 +1,17 @@
+import type { BrainClaim } from "./claims/types.js";
+import type { BrainEvidence } from "./evidence/types.js";
+import type { ProjectBrain } from "./types.js";
+export interface ClaimExplanation {
+    claim: BrainClaim;
+    status: BrainClaim["status"];
+    confidence: number;
+    supportingEvidence: readonly BrainEvidence[];
+    contradictions: readonly ProjectBrain["contradictions"][number][];
+    invalidationState: {
+        invalidated: boolean;
+        invalidatedAt?: string;
+        supersededBy?: string;
+    };
+    unknowns: readonly string[];
+}
+export declare function explainClaim(brain: ProjectBrain, claimId: string): ClaimExplanation | null;

package/dist/core/understanding/brain/explain.js

@@ -0,0 +1,33 @@
+export function explainClaim(brain, claimId) {
+    const claim = brain.claims.find((c) => c.id === claimId);
+    if (!claim) {
+        return null;
+    }
+    const supportingEvidence = brain.evidence.filter((e) => claim.evidenceIds.includes(e.id));
+    const contradictions = brain.contradictions.filter((c) => c.claimIds.includes(claim.id));
+    const unknowns = [];
+    if (supportingEvidence.length === 0) {
+        unknowns.push("No typed evidence records resolved for claim evidenceIds");
+    }
+    if (claim.status === "CONTRADICTED") {
+        unknowns.push("Claim is contradicted by one or more sibling values");
+    }
+    const invalidationState = {
+        invalidated: claim.status === "INVALIDATED",
+    };
+    if (claim.invalidatedAt !== undefined) {
+        invalidationState.invalidatedAt = claim.invalidatedAt;
+    }
+    if (claim.supersededBy !== undefined) {
+        invalidationState.supersededBy = claim.supersededBy;
+    }
+    return {
+        claim,
+        status: claim.status,
+        confidence: claim.confidence,
+        supportingEvidence,
+        contradictions,
+        invalidationState,
+        unknowns,
+    };
+}

package/dist/core/understanding/brain/index.d.ts

@@ -0,0 +1,28 @@
+export { PROJECT_BRAIN_LIMITATIONS } from "./types.js";
+export type { ProjectBrain, ProjectBrainMetadata } from "./types.js";
+export { buildProjectBrain } from "./build.js";
+export type { BuildProjectBrainOptions } from "./build.js";
+export { PROJECT_BRAIN_SCHEMA_VERSION, CLAIM_SCHEMA_VERSION, EVIDENCE_SCHEMA_VERSION, DELTA_SCHEMA_VERSION, SNAPSHOT_META_SCHEMA_VERSION, BRAIN_STORAGE_FORMAT_VERSION, } from "./version.js";
+export { CONFIDENCE_CONTRACT, clampBrainConfidence, assertBrainConfidence, averageBrainConfidence, } from "./confidence.js";
+export type { ConfidenceMetadata } from "./confidence.js";
+export { buildEvidence, redactEvidence, redactEvidenceList } from "./evidence/index.js";
+export type { BrainEvidence, EvidenceKind, EvidenceEpistemics, EvidenceRedactionStatus, } from "./evidence/index.js";
+export { buildClaim, createClaimId, applyClaimLifecycle, withClaimStatus } from "./claims/index.js";
+export type { BrainClaim, ClaimStatus, ClaimSource } from "./claims/index.js";
+export { detectContradictions } from "./contradictions/index.js";
+export type { BrainContradiction } from "./contradictions/index.js";
+export { buildComponents } from "./components/index.js";
+export type { BrainComponent, BrainComponentType } from "./components/index.js";
+export { LocalBrainStore, BrainStorageError, serializeBrain, checksumPayload, } from "./storage/index.js";
+export type { BrainStoreMeta, SnapshotMeta, SnapshotComparison } from "./storage/index.js";
+export { buildBrainDelta, serializeBrainDelta, parseBrainDelta } from "./delta.js";
+export type { BrainDelta } from "./delta.js";
+export { createBrainQueryEngine, BrainQueryEngine } from "./query.js";
+export type { BrainQuery, BrainQueryType, BrainQueryResponse } from "./query.js";
+export { explainClaim } from "./explain.js";
+export type { ClaimExplanation } from "./explain.js";
+export { traceBrain } from "./trace.js";
+export type { TraceResult, TraceMode, TraceNode, TraceEdge } from "./trace.js";
+export { redactBrainForStorage } from "./security.js";
+export { checkBrainCompatibility, migrateBrain, currentVersions } from "./migrate.js";
+export { PROJECT_BRAIN_CONTRACT, assertBrainContract, BrainContractError } from "./contract.js";

package/dist/core/understanding/brain/index.js

@@ -0,0 +1,16 @@
+export { PROJECT_BRAIN_LIMITATIONS } from "./types.js";
+export { buildProjectBrain } from "./build.js";
+export { PROJECT_BRAIN_SCHEMA_VERSION, CLAIM_SCHEMA_VERSION, EVIDENCE_SCHEMA_VERSION, DELTA_SCHEMA_VERSION, SNAPSHOT_META_SCHEMA_VERSION, BRAIN_STORAGE_FORMAT_VERSION, } from "./version.js";
+export { CONFIDENCE_CONTRACT, clampBrainConfidence, assertBrainConfidence, averageBrainConfidence, } from "./confidence.js";
+export { buildEvidence, redactEvidence, redactEvidenceList } from "./evidence/index.js";
+export { buildClaim, createClaimId, applyClaimLifecycle, withClaimStatus } from "./claims/index.js";
+export { detectContradictions } from "./contradictions/index.js";
+export { buildComponents } from "./components/index.js";
+export { LocalBrainStore, BrainStorageError, serializeBrain, checksumPayload, } from "./storage/index.js";
+export { buildBrainDelta, serializeBrainDelta, parseBrainDelta } from "./delta.js";
+export { createBrainQueryEngine, BrainQueryEngine } from "./query.js";
+export { explainClaim } from "./explain.js";
+export { traceBrain } from "./trace.js";
+export { redactBrainForStorage } from "./security.js";
+export { checkBrainCompatibility, migrateBrain, currentVersions } from "./migrate.js";
+export { PROJECT_BRAIN_CONTRACT, assertBrainContract, BrainContractError } from "./contract.js";

package/dist/core/understanding/brain/migrate.d.ts

@@ -0,0 +1,21 @@
+import { type BrainStorageFormatVersion, type ProjectBrainSchemaVersion } from "./version.js";
+import type { ProjectBrain } from "./types.js";
+export interface CompatibilityResult {
+    compatible: boolean;
+    reason?: string;
+}
+/** Reject incompatible brain / storage versions safely. */
+export declare function checkBrainCompatibility(options: {
+    schemaVersion: string;
+    storageFormatVersion?: string;
+}): CompatibilityResult;
+export type MigrationFn = (brain: ProjectBrain) => ProjectBrain;
+/**
+ * Migrate a loaded brain payload to the current schema when possible.
+ * Unknown versions are rejected (no silent best-effort parse).
+ */
+export declare function migrateBrain(brain: ProjectBrain, fromVersion?: string): ProjectBrain;
+export declare function currentVersions(): {
+    projectBrain: ProjectBrainSchemaVersion;
+    storage: BrainStorageFormatVersion;
+};

package/dist/core/understanding/brain/migrate.js

@@ -0,0 +1,47 @@
+import { BRAIN_STORAGE_FORMAT_VERSION, PROJECT_BRAIN_SCHEMA_VERSION, } from "./version.js";
+import { BrainStorageError } from "./storage/store.js";
+/** Reject incompatible brain / storage versions safely. */
+export function checkBrainCompatibility(options) {
+    if (options.schemaVersion !== PROJECT_BRAIN_SCHEMA_VERSION) {
+        return {
+            compatible: false,
+            reason: `incompatible ProjectBrain schema ${options.schemaVersion}; expected ${PROJECT_BRAIN_SCHEMA_VERSION}`,
+        };
+    }
+    if (options.storageFormatVersion !== undefined &&
+        options.storageFormatVersion !== BRAIN_STORAGE_FORMAT_VERSION) {
+        return {
+            compatible: false,
+            reason: `incompatible storage format ${options.storageFormatVersion}; expected ${BRAIN_STORAGE_FORMAT_VERSION}`,
+        };
+    }
+    return { compatible: true };
+}
+const MIGRATIONS = {
+    // V1: identity. Future versions register here keyed by from→to.
+    "1.0.0": (brain) => brain,
+};
+/**
+ * Migrate a loaded brain payload to the current schema when possible.
+ * Unknown versions are rejected (no silent best-effort parse).
+ */
+export function migrateBrain(brain, fromVersion = brain.metadata.schemaVersion) {
+    if (fromVersion === PROJECT_BRAIN_SCHEMA_VERSION) {
+        return brain;
+    }
+    const migrate = MIGRATIONS[fromVersion];
+    if (!migrate) {
+        throw new BrainStorageError(`no migration path from schema ${fromVersion} to ${PROJECT_BRAIN_SCHEMA_VERSION}`);
+    }
+    const next = migrate(brain);
+    if (next.metadata.schemaVersion !== PROJECT_BRAIN_SCHEMA_VERSION) {
+        throw new BrainStorageError(`migration from ${fromVersion} did not reach ${PROJECT_BRAIN_SCHEMA_VERSION}`);
+    }
+    return next;
+}
+export function currentVersions() {
+    return {
+        projectBrain: PROJECT_BRAIN_SCHEMA_VERSION,
+        storage: BRAIN_STORAGE_FORMAT_VERSION,
+    };
+}

package/dist/core/understanding/brain/query.d.ts

@@ -0,0 +1,60 @@
+import type { ProjectBrain } from "./types.js";
+export type BrainQueryType = "ProjectSummary" | "ListDomains" | "ListComponents" | "ListEntrypoints" | "ListDependencies" | "ListRelationships" | "ListArchitectures" | "ListOwnership" | "ListRisks" | "ListClaims" | "ListEvidence" | "ListContradictions" | "ListUnknowns" | "ListChanges" | "ListInvalidations" | "Impact" | "BlastRadius";
+export type BrainQuery = {
+    type: "ProjectSummary";
+} | {
+    type: "ListDomains";
+} | {
+    type: "ListComponents";
+} | {
+    type: "ListEntrypoints";
+} | {
+    type: "ListDependencies";
+} | {
+    type: "ListRelationships";
+} | {
+    type: "ListArchitectures";
+} | {
+    type: "ListOwnership";
+} | {
+    type: "ListRisks";
+} | {
+    type: "ListClaims";
+    status?: string;
+} | {
+    type: "ListEvidence";
+} | {
+    type: "ListContradictions";
+} | {
+    type: "ListUnknowns";
+} | {
+    type: "ListChanges";
+    previous?: ProjectBrain;
+} | {
+    type: "ListInvalidations";
+} | {
+    type: "Impact";
+    target: string;
+} | {
+    type: "BlastRadius";
+    target: string;
+};
+export interface BrainQueryResponse<T> {
+    result: T;
+    evidenceIds: readonly string[];
+    confidence: number;
+    snapshotId: string;
+    metadata: {
+        queryType: BrainQueryType;
+        brainId: string;
+        schemaVersion: string;
+        projectName: string;
+    };
+    executionTimeMs: number;
+}
+export declare class BrainQueryEngine {
+    private readonly brain;
+    constructor(brain: ProjectBrain);
+    execute(query: BrainQuery): BrainQueryResponse<unknown>;
+}
+export declare function createBrainQueryEngine(brain: ProjectBrain): BrainQueryEngine;