@praneeth_54/agentdoctor 0.3.0-beta → 1.1.0

package/dist/core/understanding/model/builder.js

@@ -0,0 +1,209 @@
+import { averageConfidence, clampModelConfidence, deepFreeze, stableModelId } from "./ids.js";
+import { COMPILER_PASSES } from "./schema.js";
+import { PROJECT_MODEL_SCHEMA_VERSION, UNDERSTANDING_COMPILER_VERSION } from "./version.js";
+import { validateProjectModel } from "./validator.js";
+function assertBuilderInput(input) {
+    if (!input.domains ||
+        !input.entrypoints ||
+        !input.dependencies ||
+        !input.relationships ||
+        !input.architectures) {
+        throw new Error("ProjectModelBuilder requires domains, entrypoints, dependencies, relationships, and architectures");
+    }
+}
+function countEvidence(lists) {
+    let total = 0;
+    for (const list of lists) {
+        total += list.length;
+    }
+    return total;
+}
+function buildSummary(options) {
+    const { domains, entrypoints, dependencies, relationships, architectures, input } = options;
+    const confidences = [
+        ...domains.map((d) => d.confidence),
+        ...entrypoints.map((e) => e.confidence),
+        ...dependencies.map((d) => d.confidence),
+        ...relationships.map((r) => r.confidence),
+        ...architectures.map((a) => a.confidence),
+    ];
+    const statistics = {
+        domainCount: domains.length,
+        entrypointCount: entrypoints.length,
+        dependencyCount: dependencies.length,
+        relationshipCount: relationships.length,
+        architectureCount: architectures.length,
+        evidenceCount: countEvidence([
+            ...domains.map((d) => d.evidence),
+            ...entrypoints.map((e) => e.evidence),
+            ...dependencies.map((d) => d.evidence),
+            ...relationships.map((r) => r.evidence),
+            ...architectures.map((a) => a.evidence),
+        ]),
+        averageConfidence: averageConfidence(confidences),
+        passTimingMs: {
+            domains: input.domains.timingMs,
+            entrypoints: input.entrypoints.timingMs,
+            dependencies: input.dependencies.timingMs,
+            relationships: input.relationships.timingMs,
+            architectures: input.architectures.timingMs,
+        },
+    };
+    return {
+        topDomains: domains
+            .slice()
+            .sort((a, b) => b.confidence - a.confidence || a.name.localeCompare(b.name))
+            .slice(0, 5)
+            .map((d) => d.name),
+        topArchitectures: architectures
+            .slice()
+            .sort((a, b) => b.confidence - a.confidence || a.pattern.localeCompare(b.pattern))
+            .slice(0, 5)
+            .map((a) => a.pattern),
+        frameworks: [...new Set(entrypoints.map((e) => e.framework))].sort((a, b) => a.localeCompare(b)),
+        statistics,
+    };
+}
+/**
+ * Builds a canonical immutable ProjectModel from compiler pass outputs.
+ */
+export class ProjectModelBuilder {
+    build(input) {
+        assertBuilderInput(input);
+        const generatedAt = input.generatedAt ?? new Date().toISOString();
+        const projectName = input.projectName?.trim() || "project";
+        const domains = input.domains.domains
+            .map((domain) => ({
+            id: stableModelId("domain-discovery", "domain", domain.name),
+            name: domain.name,
+            paths: [...domain.evidence].sort((a, b) => a.localeCompare(b)),
+            evidence: [...domain.evidence].sort((a, b) => a.localeCompare(b)),
+            confidence: clampModelConfidence(domain.confidence),
+            sourcePass: "domain-discovery",
+            timestamp: generatedAt,
+        }))
+            .sort((a, b) => b.confidence - a.confidence || a.name.localeCompare(b.name));
+        const entrypoints = input.entrypoints.entrypoints
+            .map((entry) => ({
+            id: stableModelId("entrypoint-discovery", "entrypoint", `${entry.framework}:${entry.file}`),
+            framework: entry.framework,
+            file: entry.file,
+            evidence: [...entry.evidence].sort((a, b) => a.localeCompare(b)),
+            confidence: clampModelConfidence(entry.confidence),
+            sourcePass: "entrypoint-discovery",
+            timestamp: generatedAt,
+        }))
+            .sort((a, b) => b.confidence - a.confidence ||
+            a.framework.localeCompare(b.framework) ||
+            a.file.localeCompare(b.file));
+        const dependencies = input.dependencies.dependencies
+            .map((dep) => ({
+            id: stableModelId("dependency-discovery", "dependency", `${dep.from}->${dep.to}:${dep.type}`),
+            from: dep.from,
+            to: dep.to,
+            type: dep.type,
+            evidence: [...dep.evidence].sort((a, b) => a.localeCompare(b)),
+            confidence: clampModelConfidence(dep.confidence),
+            sourcePass: "dependency-discovery",
+            timestamp: generatedAt,
+        }))
+            .sort((a, b) => b.confidence - a.confidence ||
+            a.from.localeCompare(b.from) ||
+            a.to.localeCompare(b.to) ||
+            a.type.localeCompare(b.type));
+        const relationships = input.relationships.relationships
+            .map((rel) => ({
+            id: stableModelId("relationship-discovery", "relationship", `${rel.source}->${rel.target}:${rel.relationship}`),
+            source: rel.source,
+            target: rel.target,
+            relationship: rel.relationship,
+            strength: rel.strength,
+            bidirectional: Boolean(rel.bidirectional),
+            evidence: [...rel.evidence].sort((a, b) => a.localeCompare(b)),
+            confidence: clampModelConfidence(rel.confidence),
+            sourcePass: "relationship-discovery",
+            timestamp: generatedAt,
+        }))
+            .sort((a, b) => b.confidence - a.confidence ||
+            a.relationship.localeCompare(b.relationship) ||
+            a.source.localeCompare(b.source) ||
+            a.target.localeCompare(b.target));
+        const architectures = input.architectures.architectures
+            .map((arch) => ({
+            id: stableModelId("architecture-inference", "architecture", arch.pattern),
+            pattern: arch.pattern,
+            matchedRules: [...arch.matchedRules].sort((a, b) => a.localeCompare(b)),
+            conflictingEvidence: [...arch.conflictingEvidence].sort((a, b) => a.localeCompare(b)),
+            unknowns: [...arch.unknowns].sort((a, b) => a.localeCompare(b)),
+            evidence: [...arch.evidence].sort((a, b) => a.localeCompare(b)),
+            confidence: clampModelConfidence(arch.confidence),
+            sourcePass: "architecture-inference",
+            timestamp: generatedAt,
+        }))
+            .sort((a, b) => b.confidence - a.confidence || a.pattern.localeCompare(b.pattern));
+        const projectEvidence = [
+            `domains:${domains.length}`,
+            `entrypoints:${entrypoints.length}`,
+            `dependencies:${dependencies.length}`,
+            `relationships:${relationships.length}`,
+            `architectures:${architectures.length}`,
+        ];
+        const project = {
+            id: stableModelId("project-model", "project", projectName),
+            name: projectName,
+            evidence: projectEvidence,
+            confidence: averageConfidence([
+                ...domains.map((d) => d.confidence),
+                ...entrypoints.map((e) => e.confidence),
+                ...dependencies.map((d) => d.confidence),
+                ...relationships.map((r) => r.confidence),
+                ...architectures.map((a) => a.confidence),
+            ]),
+            sourcePass: "project-model",
+            timestamp: generatedAt,
+        };
+        const metadata = {
+            id: stableModelId("project-model", "metadata", `${projectName}:${PROJECT_MODEL_SCHEMA_VERSION}`),
+            schemaVersion: PROJECT_MODEL_SCHEMA_VERSION,
+            project,
+            evidence: [`schema:${PROJECT_MODEL_SCHEMA_VERSION}`, ...projectEvidence],
+            confidence: project.confidence,
+            sourcePass: "project-model",
+            timestamp: generatedAt,
+        };
+        const compilerMetadata = {
+            compilerVersion: UNDERSTANDING_COMPILER_VERSION,
+            schemaVersion: PROJECT_MODEL_SCHEMA_VERSION,
+            generatedAt,
+            passes: COMPILER_PASSES,
+        };
+        const summary = buildSummary({
+            domains,
+            entrypoints,
+            dependencies,
+            relationships,
+            architectures,
+            input,
+        });
+        const model = deepFreeze({
+            metadata,
+            domains,
+            entrypoints,
+            dependencies,
+            relationships,
+            architectures,
+            summary,
+            compilerMetadata,
+        });
+        const validation = validateProjectModel(model);
+        if (!validation.ok) {
+            const detail = validation.issues.map((i) => `${i.path}: ${i.message}`).join("; ");
+            throw new Error(`ProjectModel validation failed: ${detail}`);
+        }
+        return model;
+    }
+}
+/** Convenience function wrapping ProjectModelBuilder. */
+export function buildProjectModel(input) {
+    return new ProjectModelBuilder().build(input);
+}

package/dist/core/understanding/model/ids.d.ts

@@ -0,0 +1,7 @@
+import type { CompilerPassId } from "./types.js";
+/** Deterministic short stable id from pass + kind + natural key. */
+export declare function stableModelId(pass: CompilerPassId, kind: string, key: string): string;
+export declare function clampModelConfidence(value: number): number;
+export declare function averageConfidence(values: readonly number[]): number;
+export declare function deepFreeze<T>(value: T): T;
+export declare function isIsoTimestamp(value: string): boolean;

package/dist/core/understanding/model/ids.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+/** Deterministic short stable id from pass + kind + natural key. */
+export function stableModelId(pass, kind, key) {
+    const digest = createHash("sha256")
+        .update(pass)
+        .update("\0")
+        .update(kind)
+        .update("\0")
+        .update(key)
+        .digest("hex")
+        .slice(0, 16);
+    return `${kind}_${digest}`;
+}
+export function clampModelConfidence(value) {
+    if (Number.isNaN(value) || value < 0) {
+        return 0;
+    }
+    if (value > 1) {
+        return 1;
+    }
+    return Math.round(value * 100) / 100;
+}
+export function averageConfidence(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sum = values.reduce((acc, value) => acc + value, 0);
+    return clampModelConfidence(sum / values.length);
+}
+export function deepFreeze(value) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Object.isFrozen(value)) {
+        return value;
+    }
+    for (const child of Object.values(value)) {
+        deepFreeze(child);
+    }
+    return Object.freeze(value);
+}
+export function isIsoTimestamp(value) {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value)) {
+        return false;
+    }
+    const parsed = Date.parse(value);
+    return !Number.isNaN(parsed);
+}

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

@@ -0,0 +1,7 @@
+export { ProjectModelBuilder, buildProjectModel } from "./builder.js";
+export { serializeProjectModel, parseProjectModel } from "./serializer.js";
+export { validateProjectModel } from "./validator.js";
+export { PROJECT_MODEL_SCHEMA } from "./schema.js";
+export { PROJECT_MODEL_SCHEMA_VERSION, UNDERSTANDING_COMPILER_VERSION } from "./version.js";
+export { stableModelId, clampModelConfidence } from "./ids.js";
+export type { CompilerMetadata, CompilerPassId, ProjectArchitecture, ProjectDependency, ProjectDomain, ProjectEntrypoint, ProjectModel, ProjectModelBuilderInput, ProjectModelValidationResult, ProjectRelationship, ProjectSummary, } from "./types.js";

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

@@ -0,0 +1,6 @@
+export { ProjectModelBuilder, buildProjectModel } from "./builder.js";
+export { serializeProjectModel, parseProjectModel } from "./serializer.js";
+export { validateProjectModel } from "./validator.js";
+export { PROJECT_MODEL_SCHEMA } from "./schema.js";
+export { PROJECT_MODEL_SCHEMA_VERSION, UNDERSTANDING_COMPILER_VERSION } from "./version.js";
+export { stableModelId, clampModelConfidence } from "./ids.js";

package/dist/core/understanding/model/schema.d.ts

@@ -0,0 +1,12 @@
+import type { CompilerPassId } from "./types.js";
+export declare const PROJECT_MODEL_REQUIRED_ROOT_KEYS: readonly ["metadata", "domains", "entrypoints", "dependencies", "relationships", "architectures", "summary", "compilerMetadata"];
+export declare const MODEL_PROVENANCE_KEYS: readonly ["id", "evidence", "confidence", "sourcePass", "timestamp"];
+export declare const COMPILER_PASSES: readonly CompilerPassId[];
+export declare const PROJECT_MODEL_SCHEMA: {
+    readonly schemaVersion: "1.0.0";
+    readonly compilerVersion: "0.1.0";
+    readonly requiredRootKeys: readonly ["metadata", "domains", "entrypoints", "dependencies", "relationships", "architectures", "summary", "compilerMetadata"];
+    readonly provenanceKeys: readonly ["id", "evidence", "confidence", "sourcePass", "timestamp"];
+    readonly passes: readonly CompilerPassId[];
+};
+export type ProjectModelSchema = typeof PROJECT_MODEL_SCHEMA;

package/dist/core/understanding/model/schema.js

@@ -0,0 +1,33 @@
+import { PROJECT_MODEL_SCHEMA_VERSION, UNDERSTANDING_COMPILER_VERSION } from "./version.js";
+export const PROJECT_MODEL_REQUIRED_ROOT_KEYS = [
+    "metadata",
+    "domains",
+    "entrypoints",
+    "dependencies",
+    "relationships",
+    "architectures",
+    "summary",
+    "compilerMetadata",
+];
+export const MODEL_PROVENANCE_KEYS = [
+    "id",
+    "evidence",
+    "confidence",
+    "sourcePass",
+    "timestamp",
+];
+export const COMPILER_PASSES = [
+    "domain-discovery",
+    "entrypoint-discovery",
+    "dependency-discovery",
+    "relationship-discovery",
+    "architecture-inference",
+    "project-model",
+];
+export const PROJECT_MODEL_SCHEMA = {
+    schemaVersion: PROJECT_MODEL_SCHEMA_VERSION,
+    compilerVersion: UNDERSTANDING_COMPILER_VERSION,
+    requiredRootKeys: PROJECT_MODEL_REQUIRED_ROOT_KEYS,
+    provenanceKeys: MODEL_PROVENANCE_KEYS,
+    passes: COMPILER_PASSES,
+};

package/dist/core/understanding/model/serializer.d.ts

@@ -0,0 +1,9 @@
+import type { ProjectModel } from "./types.js";
+/**
+ * Serialize a ProjectModel to deterministic JSON (sorted keys, 2-space indent).
+ */
+export declare function serializeProjectModel(model: ProjectModel): string;
+/**
+ * Parse JSON into a ProjectModel and validate schema/provenance.
+ */
+export declare function parseProjectModel(json: string): ProjectModel;

package/dist/core/understanding/model/serializer.js

@@ -0,0 +1,46 @@
+import { validateProjectModel } from "./validator.js";
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeysDeep);
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        const sorted = {};
+        for (const key of Object.keys(record).sort((a, b) => a.localeCompare(b))) {
+            sorted[key] = sortKeysDeep(record[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/**
+ * Serialize a ProjectModel to deterministic JSON (sorted keys, 2-space indent).
+ */
+export function serializeProjectModel(model) {
+    const validation = validateProjectModel(model);
+    if (!validation.ok) {
+        const detail = validation.issues.map((i) => `${i.path}: ${i.message}`).join("; ");
+        throw new Error(`Cannot serialize invalid ProjectModel: ${detail}`);
+    }
+    return `${JSON.stringify(sortKeysDeep(model), null, 2)}\n`;
+}
+/**
+ * Parse JSON into a ProjectModel and validate schema/provenance.
+ */
+export function parseProjectModel(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "invalid JSON";
+        throw new Error(`ProjectModel parse failed: ${message}`);
+    }
+    const model = parsed;
+    const validation = validateProjectModel(model);
+    if (!validation.ok) {
+        const detail = validation.issues.map((i) => `${i.path}: ${i.message}`).join("; ");
+        throw new Error(`ProjectModel parse validation failed: ${detail}`);
+    }
+    return model;
+}

package/dist/core/understanding/model/types.d.ts

@@ -0,0 +1,110 @@
+import type { ArchitectureInferenceResult, ArchitecturePattern } from "../architecture/types.js";
+import type { DependencyDiscoveryResult, DependencyRelationType } from "../dependencies/types.js";
+import type { EntrypointDiscoveryResult, EntrypointFramework } from "../entrypoints/types.js";
+import type { RelationshipDiscoveryResult, RelationshipKind, RelationshipStrength } from "../relationships/types.js";
+import type { DomainDiscoveryResult } from "../types/index.js";
+import type { ProjectModelSchemaVersion, UnderstandingCompilerVersion } from "./version.js";
+export type CompilerPassId = "domain-discovery" | "entrypoint-discovery" | "dependency-discovery" | "relationship-discovery" | "architecture-inference" | "project-model";
+/**
+ * Every modeled object carries provenance required by the compiler contract.
+ */
+export interface ModelProvenance {
+    id: string;
+    evidence: readonly string[];
+    confidence: number;
+    sourcePass: CompilerPassId;
+    timestamp: string;
+}
+export interface ProjectIdentity extends ModelProvenance {
+    name: string;
+}
+export interface ProjectDomain extends ModelProvenance {
+    name: string;
+    paths: readonly string[];
+}
+export interface ProjectEntrypoint extends ModelProvenance {
+    framework: EntrypointFramework;
+    file: string;
+}
+export interface ProjectDependency extends ModelProvenance {
+    from: string;
+    to: string;
+    type: DependencyRelationType;
+}
+export interface ProjectRelationship extends ModelProvenance {
+    source: string;
+    target: string;
+    relationship: RelationshipKind;
+    strength: RelationshipStrength;
+    bidirectional: boolean;
+}
+export interface ProjectArchitecture extends ModelProvenance {
+    pattern: ArchitecturePattern;
+    matchedRules: readonly string[];
+    conflictingEvidence: readonly string[];
+    unknowns: readonly string[];
+}
+export interface ProjectStatistics {
+    domainCount: number;
+    entrypointCount: number;
+    dependencyCount: number;
+    relationshipCount: number;
+    architectureCount: number;
+    evidenceCount: number;
+    averageConfidence: number;
+    passTimingMs: {
+        domains: number;
+        entrypoints: number;
+        dependencies: number;
+        relationships: number;
+        architectures: number;
+    };
+}
+export interface ProjectSummary {
+    topDomains: readonly string[];
+    topArchitectures: readonly string[];
+    frameworks: readonly string[];
+    statistics: ProjectStatistics;
+}
+export interface ProjectMetadata extends ModelProvenance {
+    schemaVersion: ProjectModelSchemaVersion;
+    project: ProjectIdentity;
+}
+export interface CompilerMetadata {
+    compilerVersion: UnderstandingCompilerVersion;
+    schemaVersion: ProjectModelSchemaVersion;
+    generatedAt: string;
+    passes: readonly CompilerPassId[];
+}
+/**
+ * Canonical immutable output of the Software Understanding Compiler.
+ */
+export interface ProjectModel {
+    metadata: ProjectMetadata;
+    domains: readonly ProjectDomain[];
+    entrypoints: readonly ProjectEntrypoint[];
+    dependencies: readonly ProjectDependency[];
+    relationships: readonly ProjectRelationship[];
+    architectures: readonly ProjectArchitecture[];
+    summary: ProjectSummary;
+    compilerMetadata: CompilerMetadata;
+}
+export interface ProjectModelBuilderInput {
+    domains: DomainDiscoveryResult;
+    entrypoints: EntrypointDiscoveryResult;
+    dependencies: DependencyDiscoveryResult;
+    relationships: RelationshipDiscoveryResult;
+    architectures: ArchitectureInferenceResult;
+    /** Optional display name; defaults to "project". */
+    projectName?: string;
+    /** Fixed ISO timestamp for deterministic builds (tests). */
+    generatedAt?: string;
+}
+export interface ProjectModelValidationIssue {
+    path: string;
+    message: string;
+}
+export interface ProjectModelValidationResult {
+    ok: boolean;
+    issues: readonly ProjectModelValidationIssue[];
+}

package/dist/core/understanding/model/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/understanding/model/validator.d.ts

@@ -0,0 +1,5 @@
+import type { ProjectModel, ProjectModelValidationResult } from "./types.js";
+/**
+ * Validate a ProjectModel against the versioned schema contract.
+ */
+export declare function validateProjectModel(model: ProjectModel): ProjectModelValidationResult;

package/dist/core/understanding/model/validator.js

@@ -0,0 +1,126 @@
+import { COMPILER_PASSES, MODEL_PROVENANCE_KEYS, PROJECT_MODEL_REQUIRED_ROOT_KEYS, } from "./schema.js";
+import { isIsoTimestamp } from "./ids.js";
+import { PROJECT_MODEL_SCHEMA_VERSION, UNDERSTANDING_COMPILER_VERSION } from "./version.js";
+function issue(path, message) {
+    return { path, message };
+}
+function validateProvenance(path, value, issues) {
+    const before = issues.length;
+    if (!value || typeof value !== "object") {
+        issues.push(issue(path, "expected provenance object"));
+        return false;
+    }
+    const record = value;
+    for (const key of MODEL_PROVENANCE_KEYS) {
+        if (!(key in record)) {
+            issues.push(issue(`${path}.${key}`, "missing required provenance field"));
+        }
+    }
+    if (typeof record.id !== "string" || record.id.length === 0) {
+        issues.push(issue(`${path}.id`, "id must be a non-empty string"));
+    }
+    if (!Array.isArray(record.evidence) || record.evidence.some((e) => typeof e !== "string")) {
+        issues.push(issue(`${path}.evidence`, "evidence must be string[]"));
+    }
+    else if (record.evidence.length === 0) {
+        issues.push(issue(`${path}.evidence`, "evidence must not be empty"));
+    }
+    if (typeof record.confidence !== "number" || record.confidence < 0 || record.confidence > 1) {
+        issues.push(issue(`${path}.confidence`, "confidence must be a number in [0,1]"));
+    }
+    if (typeof record.sourcePass !== "string" ||
+        !COMPILER_PASSES.includes(record.sourcePass)) {
+        issues.push(issue(`${path}.sourcePass`, "sourcePass must be a known compiler pass"));
+    }
+    if (typeof record.timestamp !== "string" || !isIsoTimestamp(record.timestamp)) {
+        issues.push(issue(`${path}.timestamp`, "timestamp must be an ISO-8601 UTC string"));
+    }
+    return issues.length === before;
+}
+/**
+ * Validate a ProjectModel against the versioned schema contract.
+ */
+export function validateProjectModel(model) {
+    const issues = [];
+    if (!model || typeof model !== "object") {
+        return { ok: false, issues: [issue("$", "model must be an object")] };
+    }
+    for (const key of PROJECT_MODEL_REQUIRED_ROOT_KEYS) {
+        if (!(key in model)) {
+            issues.push(issue(key, "missing required root key"));
+        }
+    }
+    validateProvenance("metadata", model.metadata, issues);
+    if (model.metadata) {
+        if (model.metadata.schemaVersion !== PROJECT_MODEL_SCHEMA_VERSION) {
+            issues.push(issue("metadata.schemaVersion", `expected ${PROJECT_MODEL_SCHEMA_VERSION}, got ${String(model.metadata.schemaVersion)}`));
+        }
+        validateProvenance("metadata.project", model.metadata.project, issues);
+        if (model.metadata.project && typeof model.metadata.project.name !== "string") {
+            issues.push(issue("metadata.project.name", "project name must be a string"));
+        }
+    }
+    const collections = [
+        { path: "domains", items: model.domains },
+        { path: "entrypoints", items: model.entrypoints },
+        { path: "dependencies", items: model.dependencies },
+        { path: "relationships", items: model.relationships },
+        { path: "architectures", items: model.architectures },
+    ];
+    for (const collection of collections) {
+        if (!Array.isArray(collection.items)) {
+            issues.push(issue(collection.path, "must be an array"));
+            continue;
+        }
+        collection.items.forEach((item, index) => {
+            validateProvenance(`${collection.path}[${index}]`, item, issues);
+        });
+    }
+    if (!model.summary || typeof model.summary !== "object") {
+        issues.push(issue("summary", "summary must be an object"));
+    }
+    else if (!model.summary.statistics || typeof model.summary.statistics !== "object") {
+        issues.push(issue("summary.statistics", "statistics must be an object"));
+    }
+    if (!model.compilerMetadata || typeof model.compilerMetadata !== "object") {
+        issues.push(issue("compilerMetadata", "compilerMetadata must be an object"));
+    }
+    else {
+        if (model.compilerMetadata.compilerVersion !== UNDERSTANDING_COMPILER_VERSION) {
+            issues.push(issue("compilerMetadata.compilerVersion", `expected ${UNDERSTANDING_COMPILER_VERSION}`));
+        }
+        if (model.compilerMetadata.schemaVersion !== PROJECT_MODEL_SCHEMA_VERSION) {
+            issues.push(issue("compilerMetadata.schemaVersion", `expected ${PROJECT_MODEL_SCHEMA_VERSION}`));
+        }
+        if (typeof model.compilerMetadata.generatedAt !== "string" ||
+            !isIsoTimestamp(model.compilerMetadata.generatedAt)) {
+            issues.push(issue("compilerMetadata.generatedAt", "must be ISO-8601 UTC"));
+        }
+        if (!Array.isArray(model.compilerMetadata.passes)) {
+            issues.push(issue("compilerMetadata.passes", "passes must be an array"));
+        }
+    }
+    // Stable id uniqueness across all provenance-bearing objects
+    const ids = new Map();
+    const track = (path, id) => {
+        const existing = ids.get(id);
+        if (existing) {
+            issues.push(issue(path, `duplicate id ${id} (also at ${existing})`));
+        }
+        else {
+            ids.set(id, path);
+        }
+    };
+    if (model.metadata?.id) {
+        track("metadata", model.metadata.id);
+    }
+    if (model.metadata?.project?.id) {
+        track("metadata.project", model.metadata.project.id);
+    }
+    model.domains?.forEach((d, i) => track(`domains[${i}]`, d.id));
+    model.entrypoints?.forEach((e, i) => track(`entrypoints[${i}]`, e.id));
+    model.dependencies?.forEach((d, i) => track(`dependencies[${i}]`, d.id));
+    model.relationships?.forEach((r, i) => track(`relationships[${i}]`, r.id));
+    model.architectures?.forEach((a, i) => track(`architectures[${i}]`, a.id));
+    return { ok: issues.length === 0, issues };
+}

package/dist/core/understanding/model/version.d.ts

@@ -0,0 +1,9 @@
+/** Semver of the Project Model JSON schema shape. */
+export declare const PROJECT_MODEL_SCHEMA_VERSION: "1.0.0";
+/**
+ * Internal understanding compiler version that produced the model.
+ * Independent of the published AgentDoctor package version.
+ */
+export declare const UNDERSTANDING_COMPILER_VERSION: "0.1.0";
+export type ProjectModelSchemaVersion = typeof PROJECT_MODEL_SCHEMA_VERSION;
+export type UnderstandingCompilerVersion = typeof UNDERSTANDING_COMPILER_VERSION;

package/dist/core/understanding/model/version.js

@@ -0,0 +1,7 @@
+/** Semver of the Project Model JSON schema shape. */
+export const PROJECT_MODEL_SCHEMA_VERSION = "1.0.0";
+/**
+ * Internal understanding compiler version that produced the model.
+ * Independent of the published AgentDoctor package version.
+ */
+export const UNDERSTANDING_COMPILER_VERSION = "0.1.0";

package/dist/core/understanding/ownership/discover.d.ts

@@ -0,0 +1,12 @@
+import type { OwnershipDiscoveryOptions, OwnershipDiscoveryResult, OwnershipMatch } from "./types.js";
+export declare function scoreOwnershipConfidence(source: OwnershipMatch["source"]): number;
+/** Match a repo-relative path against a CODEOWNERS pattern (subset of GitHub rules). */
+export declare function matchCodeownersPattern(filePath: string, pattern: string): boolean;
+/**
+ * Discover ownership from explicit repository evidence only.
+ * Sources: CODEOWNERS, MAINTAINERS, package.json author/maintainers.
+ * No git-blame guessing.
+ */
+export declare function discoverOwnership(options?: OwnershipDiscoveryOptions): Promise<OwnershipDiscoveryResult>;
+/** Resolve owners for a path using last-matching CODEOWNERS rule semantics when possible. */
+export declare function ownersForPath(filePath: string, ownerships: readonly OwnershipMatch[]): OwnershipMatch | null;