@praneeth_54/agentdoctor 1.0.0 → 1.1.0

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

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+import { discoverOwnership } from "../ownership/index.js";
+import { discoverRisks } from "../risks/index.js";
+import { createSnapshotIdentity } from "../snapshot/index.js";
+import { buildClaim } from "./claims/index.js";
+import { applyClaimLifecycle } from "./claims/lifecycle.js";
+import { buildComponents } from "./components/index.js";
+import { CONFIDENCE_CONTRACT, clampBrainConfidence } from "./confidence.js";
+import { detectContradictions } from "./contradictions/index.js";
+import { buildEvidence, redactEvidenceList } from "./evidence/index.js";
+import { PROJECT_BRAIN_LIMITATIONS } from "./types.js";
+import { PROJECT_BRAIN_SCHEMA_VERSION } from "./version.js";
+function brainIdFor(projectName, contentHash) {
+    return `brain_${createHash("sha256").update(projectName).update(contentHash).digest("hex").slice(0, 16)}`;
+}
+function pathEvidence(evidence, snapshotId, locator, source, epistemics = "observed") {
+    const ev = buildEvidence({
+        kind: "path",
+        locator,
+        source,
+        snapshotId,
+        epistemics,
+        redaction: "path-only",
+    });
+    evidence.push(ev);
+    return ev.id;
+}
+function claimsFromModel(options) {
+    const { model, ownership, risks, snapshotId, createdAt, evidence } = options;
+    const claims = [];
+    const add = (subject, predicate, object, source, confidence, locs, epistemics = "inferred") => {
+        const evidenceIds = locs.map((locator) => pathEvidence(evidence, snapshotId, locator, source, epistemics));
+        claims.push(buildClaim({
+            subject,
+            predicate,
+            object,
+            snapshotId,
+            evidenceIds,
+            confidence: clampBrainConfidence(confidence),
+            source,
+            createdAt,
+        }));
+    };
+    for (const domain of model.domains) {
+        add(domain.name, "is-domain", "true", "domain-discovery", domain.confidence, domain.evidence);
+    }
+    for (const entry of model.entrypoints) {
+        add(entry.file, "is-entrypoint", entry.framework, "entrypoint-discovery", entry.confidence, entry.evidence, "observed");
+    }
+    for (const dep of model.dependencies) {
+        add(dep.from, "depends-on", `${dep.to}:${dep.type}`, "dependency-discovery", dep.confidence, dep.evidence, "observed");
+    }
+    for (const rel of model.relationships) {
+        add(rel.source, rel.relationship, rel.target, "relationship-discovery", rel.confidence, rel.evidence);
+    }
+    for (const arch of model.architectures) {
+        add(model.metadata.project.name, "architecture", arch.pattern, "architecture-inference", arch.confidence, arch.evidence);
+    }
+    for (const own of ownership.ownerships) {
+        add(own.path, "owned-by", own.owners.join(","), "ownership-discovery", own.confidence, own.evidence, "observed");
+    }
+    for (const risk of risks.risks) {
+        add(risk.target, "has-risk", risk.kind, "risk-discovery", risk.confidence, risk.evidence);
+    }
+    return claims;
+}
+export async function buildProjectBrain(model, options = {}) {
+    const createdAt = options.generatedAt ?? model.compilerMetadata.generatedAt;
+    const snapshot = createSnapshotIdentity(model, options.generatedAt !== undefined ? { generatedAt: options.generatedAt } : {});
+    let ownership;
+    if (options.ownership) {
+        ownership = options.ownership;
+    }
+    else if (options.cwd !== undefined) {
+        ownership = await discoverOwnership({ cwd: options.cwd });
+    }
+    else {
+        ownership = {
+            ownerships: [],
+            timingMs: 0,
+            filesConsidered: 0,
+            unknowns: ["Ownership not discovered (no cwd provided); UNKNOWN"],
+        };
+    }
+    const risks = options.risks ?? discoverRisks(model, ownership);
+    let evidence = [];
+    const freshClaims = claimsFromModel({
+        model,
+        ownership,
+        risks,
+        snapshotId: snapshot.id,
+        createdAt,
+        evidence,
+    });
+    const lifecycleClaims = applyClaimLifecycle({
+        previous: options.previousClaims ?? [],
+        nextActive: freshClaims,
+        at: createdAt,
+    });
+    const { claims, contradictions } = detectContradictions(lifecycleClaims, snapshot.id);
+    const componentBuild = buildComponents({
+        model,
+        ownership,
+        risks,
+        snapshotId: snapshot.id,
+        evidence,
+    });
+    evidence = redactEvidenceList(componentBuild.evidence);
+    const unknowns = [
+        ...new Set([
+            ...ownership.unknowns,
+            ...risks.unknowns,
+            ...model.architectures.flatMap((a) => a.unknowns),
+            ...(model.domains.length === 0
+                ? ["No domains discovered at current confidence thresholds"]
+                : []),
+        ]),
+    ].sort((a, b) => a.localeCompare(b));
+    // Ensure every ACTIVE claim has evidence
+    for (const claim of claims) {
+        if (claim.status === "ACTIVE" && claim.evidenceIds.length === 0) {
+            throw new Error(`ACTIVE claim ${claim.id} missing evidence`);
+        }
+    }
+    const brain = {
+        metadata: {
+            schemaVersion: PROJECT_BRAIN_SCHEMA_VERSION,
+            brainId: brainIdFor(model.metadata.project.name, snapshot.contentHash),
+            projectName: model.metadata.project.name,
+            createdAt,
+            updatedAt: createdAt,
+        },
+        snapshot,
+        model,
+        ownership,
+        risks,
+        components: componentBuild.components,
+        claims,
+        evidence,
+        contradictions,
+        unknowns,
+        limitations: [...PROJECT_BRAIN_LIMITATIONS],
+        confidenceContract: CONFIDENCE_CONTRACT,
+    };
+    return Object.freeze(deepFreezeBrain(brain));
+}
+function deepFreezeBrain(brain) {
+    Object.freeze(brain.metadata);
+    Object.freeze(brain.snapshot);
+    Object.freeze(brain.components);
+    Object.freeze(brain.claims);
+    Object.freeze(brain.evidence);
+    Object.freeze(brain.contradictions);
+    Object.freeze(brain.unknowns);
+    Object.freeze(brain.limitations);
+    Object.freeze(brain.confidenceContract);
+    return Object.freeze(brain);
+}

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

@@ -0,0 +1,3 @@
+export type { BrainClaim, ClaimSource, ClaimStatus } from "./types.js";
+export { buildClaim, createClaimId } from "./types.js";
+export { applyClaimLifecycle, withClaimStatus } from "./lifecycle.js";

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

@@ -0,0 +1,2 @@
+export { buildClaim, createClaimId } from "./types.js";
+export { applyClaimLifecycle, withClaimStatus } from "./lifecycle.js";

package/dist/core/understanding/brain/claims/lifecycle.d.ts

@@ -0,0 +1,16 @@
+import type { BrainClaim, ClaimStatus } from "./types.js";
+export declare function withClaimStatus(claim: BrainClaim, status: ClaimStatus, options?: {
+    invalidatedAt?: string;
+    supersededBy?: string;
+    contradictionIds?: readonly string[];
+}): BrainClaim;
+/**
+ * Apply lifecycle transitions when moving from beforeClaims → afterClaims for a new snapshot.
+ * Claims missing in after become INVALIDATED (kept in history with status).
+ * Same subject+predicate with different object → prior SUPERSEDED, both retained.
+ */
+export declare function applyClaimLifecycle(options: {
+    previous: readonly BrainClaim[];
+    nextActive: readonly BrainClaim[];
+    at: string;
+}): BrainClaim[];

package/dist/core/understanding/brain/claims/lifecycle.js

@@ -0,0 +1,78 @@
+export function withClaimStatus(claim, status, options = {}) {
+    const next = {
+        ...claim,
+        status,
+        contradictionIds: options.contradictionIds
+            ? [...options.contradictionIds]
+            : [...claim.contradictionIds],
+    };
+    if (options.invalidatedAt !== undefined) {
+        next.invalidatedAt = options.invalidatedAt;
+    }
+    else if (status === "ACTIVE") {
+        delete next.invalidatedAt;
+    }
+    if (options.supersededBy !== undefined) {
+        next.supersededBy = options.supersededBy;
+    }
+    else if (status === "ACTIVE") {
+        delete next.supersededBy;
+    }
+    return next;
+}
+/**
+ * Apply lifecycle transitions when moving from beforeClaims → afterClaims for a new snapshot.
+ * Claims missing in after become INVALIDATED (kept in history with status).
+ * Same subject+predicate with different object → prior SUPERSEDED, both retained.
+ */
+export function applyClaimLifecycle(options) {
+    const { previous, nextActive, at } = options;
+    const byKey = new Map();
+    const keyOf = (c) => `${c.subject}\0${c.predicate}\0${c.object}`;
+    const subjectPred = (c) => `${c.subject}\0${c.predicate}`;
+    const nextByKey = new Map(nextActive.map((c) => [keyOf(c), c]));
+    const nextBySubjectPred = new Map();
+    for (const claim of nextActive) {
+        const sp = subjectPred(claim);
+        const list = nextBySubjectPred.get(sp) ?? [];
+        list.push(claim);
+        nextBySubjectPred.set(sp, list);
+    }
+    const result = [];
+    for (const claim of nextActive) {
+        result.push({ ...claim, status: "ACTIVE" });
+        byKey.set(keyOf(claim), claim);
+    }
+    for (const prior of previous) {
+        if (prior.status === "INVALIDATED" && !nextByKey.has(keyOf(prior))) {
+            result.push(prior);
+            continue;
+        }
+        const k = keyOf(prior);
+        if (nextByKey.has(k)) {
+            continue;
+        }
+        const rivals = nextBySubjectPred.get(subjectPred(prior)) ?? [];
+        if (rivals.length > 0) {
+            const successor = rivals[0];
+            result.push(withClaimStatus(prior, "SUPERSEDED", successor ? { invalidatedAt: at, supersededBy: successor.id } : { invalidatedAt: at }));
+            continue;
+        }
+        result.push(withClaimStatus(prior, "INVALIDATED", { invalidatedAt: at }));
+    }
+    // Dedupe by id preferring ACTIVE > CONTRADICTED > SUPERSEDED > INVALIDATED
+    const rank = {
+        ACTIVE: 4,
+        CONTRADICTED: 3,
+        SUPERSEDED: 2,
+        INVALIDATED: 1,
+    };
+    const byId = new Map();
+    for (const claim of result) {
+        const existing = byId.get(claim.id);
+        if (!existing || rank[claim.status] >= rank[existing.status]) {
+            byId.set(claim.id, claim);
+        }
+    }
+    return [...byId.values()].sort((a, b) => rank[b.status] - rank[a.status] || b.confidence - a.confidence || a.id.localeCompare(b.id));
+}

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

@@ -0,0 +1,32 @@
+import type { ClaimSchemaVersion } from "../version.js";
+export type ClaimStatus = "ACTIVE" | "INVALIDATED" | "SUPERSEDED" | "CONTRADICTED";
+export type ClaimSource = "domain-discovery" | "entrypoint-discovery" | "dependency-discovery" | "relationship-discovery" | "architecture-inference" | "ownership-discovery" | "risk-discovery" | "component-model" | "project-brain";
+export interface BrainClaim {
+    schemaVersion: ClaimSchemaVersion;
+    id: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    snapshotId: string;
+    evidenceIds: readonly string[];
+    confidence: number;
+    source: ClaimSource;
+    status: ClaimStatus;
+    createdAt: string;
+    invalidatedAt?: string;
+    supersededBy?: string;
+    contradictionIds: readonly string[];
+}
+export declare function createClaimId(subject: string, predicate: string, object: string): string;
+export declare function buildClaim(input: {
+    subject: string;
+    predicate: string;
+    object: string;
+    snapshotId: string;
+    evidenceIds: readonly string[];
+    confidence: number;
+    source: ClaimSource;
+    createdAt: string;
+    status?: ClaimStatus;
+    contradictionIds?: readonly string[];
+}): BrainClaim;

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

@@ -0,0 +1,25 @@
+import { CLAIM_SCHEMA_VERSION } from "../version.js";
+export function createClaimId(subject, predicate, object) {
+    const key = `${subject}\0${predicate}\0${object}`;
+    let hash = 0;
+    for (let i = 0; i < key.length; i++) {
+        hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
+    }
+    return `claim_${hash.toString(16).padStart(8, "0")}`;
+}
+export function buildClaim(input) {
+    return {
+        schemaVersion: CLAIM_SCHEMA_VERSION,
+        id: createClaimId(input.subject, input.predicate, input.object),
+        subject: input.subject,
+        predicate: input.predicate,
+        object: input.object,
+        snapshotId: input.snapshotId,
+        evidenceIds: [...input.evidenceIds],
+        confidence: input.confidence,
+        source: input.source,
+        status: input.status ?? "ACTIVE",
+        createdAt: input.createdAt,
+        contradictionIds: [...(input.contradictionIds ?? [])],
+    };
+}

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

@@ -0,0 +1,17 @@
+import type { ProjectModel } from "../../model/types.js";
+import type { OwnershipDiscoveryResult } from "../../ownership/types.js";
+import type { RiskDiscoveryResult } from "../../risks/types.js";
+import type { BrainEvidence } from "../evidence/types.js";
+import { type BrainComponent } from "./types.js";
+export declare function buildComponents(options: {
+    model: ProjectModel;
+    ownership: OwnershipDiscoveryResult;
+    risks: RiskDiscoveryResult;
+    snapshotId: string;
+    evidence: BrainEvidence[];
+}): {
+    components: BrainComponent[];
+    evidence: BrainEvidence[];
+};
+export type { BrainComponent, BrainComponentType } from "./types.js";
+export { createComponentId } from "./types.js";

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

@@ -0,0 +1,97 @@
+import { ownersForPath } from "../../ownership/index.js";
+import { averageBrainConfidence, clampBrainConfidence } from "../confidence.js";
+import { buildEvidence } from "../evidence/types.js";
+import { createComponentId } from "./types.js";
+export function buildComponents(options) {
+    const { model, ownership, risks, snapshotId } = options;
+    const evidence = [...options.evidence];
+    const pushEv = (locator, source) => {
+        const ev = buildEvidence({
+            kind: "path",
+            locator,
+            source,
+            snapshotId,
+            epistemics: "observed",
+            redaction: "path-only",
+        });
+        evidence.push(ev);
+        return ev.id;
+    };
+    const nodes = new Map();
+    for (const domain of model.domains) {
+        for (const p of domain.paths.slice(0, 20)) {
+            nodes.set(p, { path: p, type: "domain-surface", name: domain.name });
+        }
+    }
+    for (const entry of model.entrypoints) {
+        nodes.set(entry.file, {
+            path: entry.file,
+            type: "entrypoint",
+            name: entry.file.split(/[/\\]/).pop() ?? entry.file,
+        });
+    }
+    for (const dep of model.dependencies) {
+        if (!nodes.has(dep.from)) {
+            nodes.set(dep.from, { path: dep.from, type: "module", name: dep.from });
+        }
+        if (!nodes.has(dep.to)) {
+            nodes.set(dep.to, { path: dep.to, type: "module", name: dep.to });
+        }
+    }
+    for (const rel of model.relationships) {
+        if (!nodes.has(rel.source)) {
+            nodes.set(rel.source, { path: rel.source, type: "module", name: rel.source });
+        }
+        if (!nodes.has(rel.target)) {
+            nodes.set(rel.target, { path: rel.target, type: "module", name: rel.target });
+        }
+    }
+    const components = [];
+    for (const node of [...nodes.values()].sort((a, b) => a.path.localeCompare(b.path))) {
+        const id = createComponentId(node.type, node.path);
+        const evId = pushEv(node.path, "component-model");
+        const ownerMatch = ownersForPath(node.path, ownership.ownerships);
+        const domainIds = model.domains
+            .filter((d) => d.paths.some((p) => node.path.includes(p) || p.includes(node.path)))
+            .map((d) => d.id);
+        const dependencyIds = model.dependencies
+            .filter((d) => d.from === node.path || d.from.includes(node.path))
+            .map((d) => d.id);
+        const dependentIds = model.dependencies
+            .filter((d) => d.to === node.path || d.to.includes(node.path))
+            .map((d) => d.id);
+        const entrypointIds = model.entrypoints
+            .filter((e) => e.file === node.path || node.path.includes(e.file))
+            .map((e) => e.id);
+        const riskKinds = [
+            ...new Set(risks.risks
+                .filter((r) => r.target === node.path || node.path.includes(r.target))
+                .map((r) => r.kind)),
+        ];
+        const confidences = [
+            ...model.dependencies
+                .filter((d) => d.from === node.path || d.to === node.path)
+                .map((d) => d.confidence),
+            ...model.entrypoints.filter((e) => e.file === node.path).map((e) => e.confidence),
+        ];
+        const component = {
+            id,
+            type: node.type,
+            name: node.name,
+            path: node.path,
+            domainIds,
+            dependencyIds,
+            dependentIds,
+            entrypointIds,
+            riskKinds,
+            evidenceIds: [evId],
+            confidence: clampBrainConfidence(confidences.length > 0 ? averageBrainConfidence(confidences) : 0.55),
+        };
+        if (ownerMatch?.owners[0]) {
+            component.owner = ownerMatch.owners[0];
+        }
+        components.push(component);
+    }
+    return { components, evidence };
+}
+export { createComponentId } from "./types.js";

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

@@ -0,0 +1,16 @@
+export type BrainComponentType = "module" | "entrypoint" | "package" | "domain-surface";
+export interface BrainComponent {
+    id: string;
+    type: BrainComponentType;
+    name: string;
+    path: string;
+    domainIds: readonly string[];
+    dependencyIds: readonly string[];
+    dependentIds: readonly string[];
+    entrypointIds: readonly string[];
+    owner?: string;
+    riskKinds: readonly string[];
+    evidenceIds: readonly string[];
+    confidence: number;
+}
+export declare function createComponentId(type: BrainComponentType, path: string): string;

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

@@ -0,0 +1,8 @@
+export function createComponentId(type, path) {
+    const key = `${type}\0${path}`;
+    let hash = 0;
+    for (let i = 0; i < key.length; i++) {
+        hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
+    }
+    return `comp_${hash.toString(16).padStart(8, "0")}`;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Shared confidence contract for all Project Brain surfaces.
+ * Range: [0, 1]. Meaning: subjective support strength given current evidence.
+ * 0 = no support / unknown claim should not be ACTIVE with fabricated certainty.
+ * 1 = maximum support the deterministic compiler can assert for this evidence class.
+ * Calibration: values are rule-derived, not probabilistically calibrated to human labels.
+ */
+export declare const CONFIDENCE_MIN = 0;
+export declare const CONFIDENCE_MAX = 1;
+export interface ConfidenceMetadata {
+    range: readonly [number, number];
+    meaning: string;
+    calibration: "rule-derived-uncalibrated";
+    unknownPolicy: "preserve-unknown-never-invent";
+}
+export declare const CONFIDENCE_CONTRACT: ConfidenceMetadata;
+export declare function clampBrainConfidence(value: number): number;
+export declare function assertBrainConfidence(value: number, path?: string): number;
+export declare function averageBrainConfidence(values: readonly number[]): number;

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

@@ -0,0 +1,39 @@
+/**
+ * Shared confidence contract for all Project Brain surfaces.
+ * Range: [0, 1]. Meaning: subjective support strength given current evidence.
+ * 0 = no support / unknown claim should not be ACTIVE with fabricated certainty.
+ * 1 = maximum support the deterministic compiler can assert for this evidence class.
+ * Calibration: values are rule-derived, not probabilistically calibrated to human labels.
+ */
+export const CONFIDENCE_MIN = 0;
+export const CONFIDENCE_MAX = 1;
+export const CONFIDENCE_CONTRACT = {
+    range: [CONFIDENCE_MIN, CONFIDENCE_MAX],
+    meaning: "Deterministic support strength from explicit repository evidence for this claim class",
+    calibration: "rule-derived-uncalibrated",
+    unknownPolicy: "preserve-unknown-never-invent",
+};
+export function clampBrainConfidence(value) {
+    if (Number.isNaN(value) || value < CONFIDENCE_MIN) {
+        return CONFIDENCE_MIN;
+    }
+    if (value > CONFIDENCE_MAX) {
+        return CONFIDENCE_MAX;
+    }
+    return Math.round(value * 100) / 100;
+}
+export function assertBrainConfidence(value, path = "confidence") {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new Error(`${path} must be a number`);
+    }
+    if (value < CONFIDENCE_MIN || value > CONFIDENCE_MAX) {
+        throw new Error(`${path} must be in [0,1]`);
+    }
+    return clampBrainConfidence(value);
+}
+export function averageBrainConfidence(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    return clampBrainConfidence(values.reduce((a, b) => a + b, 0) / values.length);
+}

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

@@ -0,0 +1,17 @@
+import type { ProjectBrain } from "./types.js";
+export declare class BrainContractError extends Error {
+    constructor(message: string);
+}
+/** Machine-consumption contract: required top-level ProjectBrain fields (schema 1.0.0). */
+export declare const PROJECT_BRAIN_CONTRACT: {
+    readonly schemaVersion: "1.0.0";
+    readonly requiredFields: readonly ["metadata", "snapshot", "model", "ownership", "risks", "components", "claims", "evidence", "contradictions", "unknowns", "limitations", "confidenceContract"];
+    readonly claimStatuses: readonly ["ACTIVE", "INVALIDATED", "SUPERSEDED", "CONTRADICTED"];
+    readonly confidenceRange: readonly [0, 1];
+    readonly notes: readonly ["Project Brain is a parallel local intelligence layer; not part of the published safety CLI pack.", "Consumers must treat INVALIDATED/SUPERSEDED claims as historical, not active truth.", "Evidence locators are references only; secret contents are never embedded."];
+};
+/**
+ * Fail-closed structural validation for persisted / loaded Brain payloads.
+ * Does not invent missing semantics — rejects malformed data.
+ */
+export declare function assertBrainContract(payload: unknown): ProjectBrain;

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

@@ -0,0 +1,100 @@
+import { PROJECT_BRAIN_SCHEMA_VERSION } from "./version.js";
+import { CONFIDENCE_MIN, CONFIDENCE_MAX } from "./confidence.js";
+export class BrainContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BrainContractError";
+    }
+}
+const CLAIM_STATUSES = new Set(["ACTIVE", "INVALIDATED", "SUPERSEDED", "CONTRADICTED"]);
+/** Machine-consumption contract: required top-level ProjectBrain fields (schema 1.0.0). */
+export const PROJECT_BRAIN_CONTRACT = {
+    schemaVersion: PROJECT_BRAIN_SCHEMA_VERSION,
+    requiredFields: [
+        "metadata",
+        "snapshot",
+        "model",
+        "ownership",
+        "risks",
+        "components",
+        "claims",
+        "evidence",
+        "contradictions",
+        "unknowns",
+        "limitations",
+        "confidenceContract",
+    ],
+    claimStatuses: ["ACTIVE", "INVALIDATED", "SUPERSEDED", "CONTRADICTED"],
+    confidenceRange: [CONFIDENCE_MIN, CONFIDENCE_MAX],
+    notes: [
+        "Project Brain is a parallel local intelligence layer; not part of the published safety CLI pack.",
+        "Consumers must treat INVALIDATED/SUPERSEDED claims as historical, not active truth.",
+        "Evidence locators are references only; secret contents are never embedded.",
+    ],
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Fail-closed structural validation for persisted / loaded Brain payloads.
+ * Does not invent missing semantics — rejects malformed data.
+ */
+export function assertBrainContract(payload) {
+    if (!isRecord(payload)) {
+        throw new BrainContractError("brain payload must be an object");
+    }
+    for (const field of PROJECT_BRAIN_CONTRACT.requiredFields) {
+        if (!(field in payload)) {
+            throw new BrainContractError(`missing required field: ${field}`);
+        }
+    }
+    const metadata = payload.metadata;
+    if (!isRecord(metadata) || typeof metadata.schemaVersion !== "string") {
+        throw new BrainContractError("metadata.schemaVersion required");
+    }
+    if (metadata.schemaVersion !== PROJECT_BRAIN_SCHEMA_VERSION) {
+        throw new BrainContractError(`incompatible schemaVersion ${metadata.schemaVersion}; expected ${PROJECT_BRAIN_SCHEMA_VERSION}`);
+    }
+    if (typeof metadata.brainId !== "string" || metadata.brainId.length === 0) {
+        throw new BrainContractError("metadata.brainId required");
+    }
+    const snapshot = payload.snapshot;
+    if (!isRecord(snapshot) || typeof snapshot.id !== "string") {
+        throw new BrainContractError("snapshot.id required");
+    }
+    if (!Array.isArray(payload.claims) || !Array.isArray(payload.evidence)) {
+        throw new BrainContractError("claims and evidence must be arrays");
+    }
+    for (const claim of payload.claims) {
+        if (!isRecord(claim)) {
+            throw new BrainContractError("malformed claim");
+        }
+        if (typeof claim.id !== "string" || typeof claim.status !== "string") {
+            throw new BrainContractError("claim id/status required");
+        }
+        if (!CLAIM_STATUSES.has(claim.status)) {
+            throw new BrainContractError(`unsupported claim status: ${String(claim.status)}`);
+        }
+        if (typeof claim.confidence !== "number" || claim.confidence < 0 || claim.confidence > 1) {
+            throw new BrainContractError(`invalid claim confidence for ${claim.id}`);
+        }
+        if (!Array.isArray(claim.evidenceIds)) {
+            throw new BrainContractError(`claim ${claim.id} missing evidenceIds`);
+        }
+        if (claim.status === "ACTIVE" && claim.evidenceIds.length === 0) {
+            throw new BrainContractError(`ACTIVE claim ${claim.id} missing evidence`);
+        }
+    }
+    for (const evidence of payload.evidence) {
+        if (!isRecord(evidence)) {
+            throw new BrainContractError("malformed evidence");
+        }
+        if (typeof evidence.id !== "string" || typeof evidence.locator !== "string") {
+            throw new BrainContractError("evidence id/locator required");
+        }
+        if (evidence.epistemics !== "observed" && evidence.epistemics !== "inferred") {
+            throw new BrainContractError(`invalid evidence epistemics on ${evidence.id}`);
+        }
+    }
+    return payload;
+}

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

@@ -0,0 +1,12 @@
+import type { BrainClaim } from "../claims/types.js";
+import { type BrainContradiction } from "./types.js";
+/**
+ * Detect contradictory ACTIVE claims sharing subject+predicate with different objects.
+ * Marks those claims CONTRADICTED and returns contradiction records.
+ */
+export declare function detectContradictions(claims: readonly BrainClaim[], snapshotId: string): {
+    claims: BrainClaim[];
+    contradictions: BrainContradiction[];
+};
+export type { BrainContradiction } from "./types.js";
+export { createContradictionId } from "./types.js";