codemetrics-ai 0.4.0 → 0.6.0-preview.1

package/dist/python-decomposition.js

@@ -0,0 +1,102 @@
+import { isDeepStrictEqual } from "node:util";
+import { hash } from "./evidence.js";
+export const decompositionPolicy = "python/owned-statements-block-nesting-v1";
+const blocks = ["If", "For", "AsyncFor", "While", "With", "AsyncWith", "Try", "TryStar", "Match"];
+const statements = [...blocks, "Return", "Delete", "Assign", "AugAssign", "AnnAssign", "Raise", "Assert", "Import", "ImportFrom", "Expr", "Break", "Continue"];
+const excluded = ["FunctionDef", "AsyncFunctionDef", "ClassDef", "Lambda", "Pass", "Global", "Nonlocal", "TypeAlias", "AnnAssign", "Expr", "docstring"];
+function requireValue(condition, message) {
+    if (!condition)
+        throw new Error(`Invalid Python decomposition evidence: ${message}.`);
+}
+function keys(value, expected) {
+    requireValue(value !== null && typeof value === "object" && !Array.isArray(value), "object required");
+    requireValue(isDeepStrictEqual(Object.keys(value).sort(), expected.sort()), "unexpected or missing fields");
+}
+const integer = (value) => Number.isSafeInteger(value) && value >= 0;
+function histogram(value, allowed) {
+    requireValue(value !== null && typeof value === "object" && !Array.isArray(value), "histogram required");
+    const entries = Object.entries(value);
+    requireValue(entries.every(([key, count]) => allowed.includes(key) && integer(count) && count > 0), "invalid histogram");
+    const total = entries.reduce((sum, [, count]) => sum + count, 0);
+    requireValue(integer(total), "histogram overflow");
+    return total;
+}
+function distribution(values) {
+    if (!values.length)
+        return null;
+    values.sort((a, b) => a - b);
+    const rank = (percent) => values[Math.ceil(percent * values.length / 100) - 1];
+    return { count: values.length, p50: rank(50), p90: rank(90), p95: rank(95), max: values.at(-1) };
+}
+function summary(rows) {
+    const measured = rows.filter(row => row.status === "measured");
+    const populations = Object.fromEntries([...new Set(rows.map(row => row.population))].map(population => {
+        const selected = rows.filter(row => row.population === population);
+        const eligible = selected.filter(row => row.status === "measured");
+        return [population, { selectedFunctions: selected.length, measuredFunctions: eligible.length,
+                unavailableFunctions: selected.length - eligible.length,
+                ownedStatements: distribution(eligible.map(row => row.measurement.ownedStatements)),
+                maxBlockNesting: distribution(eligible.map(row => row.measurement.maxBlockNesting)) }];
+    }));
+    const unavailable = rows.length - measured.length;
+    return { selectedFunctions: rows.length, measuredFunctions: measured.length, unavailableFunctions: unavailable,
+        unavailableReasons: unavailable ? { "lambda-expression-body": unavailable } : {}, populations };
+}
+/** Validate provenance and internal accounting; AST measurements remain the producer's observations. */
+export function validateDecomposition(value, facts, subject, ids) {
+    keys(value, ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "status", "policy", "configuration",
+        "configurationFingerprint", "subject", "sourceFactsProducer", "sourceFactsPolicy", "selection", "diagnostics", "scope", "functions", "summary"]);
+    const report = value;
+    requireValue(report.schemaVersion === 1 && report.artifactKind === "experimental-python-decomposition-review" && report.policy === decompositionPolicy, "unsupported policy");
+    requireValue(isDeepStrictEqual(report.producer, { name: "codemetrics-ai/python-decomposition", version: "0.1.0-experimental" }), "producer mismatch");
+    requireValue(report.runId === ids.runId && report.auditId === ids.auditId, "stale invocation identities");
+    const target = subject.entryPoint.replaceAll("\\", "/").endsWith("/pyproject.toml") ? subject.root : subject.entryPoint;
+    requireValue(isDeepStrictEqual(report.subject, { root: subject.root, entryPoint: target }), "subject mismatch");
+    requireValue(isDeepStrictEqual(report.sourceFactsProducer, facts.producer) && report.sourceFactsPolicy === facts.measurementPolicy &&
+        isDeepStrictEqual(report.selection, facts.selection), "source selection/provenance mismatch");
+    const configuration = { policy: decompositionPolicy, selectionFingerprint: facts.selection.configurationFingerprint,
+        parserVersion: facts.producer.parserVersion, maxOwners: 100000, quantiles: "nearest-rank", complexityPolicy: facts.measurementPolicy };
+    requireValue(isDeepStrictEqual(report.configuration, configuration), "configuration mismatch");
+    requireValue(report.configurationFingerprint === hash(JSON.stringify(configuration, Object.keys(configuration).sort())), "configuration fingerprint mismatch");
+    requireValue(typeof report.scope === "string" && report.scope.length > 0 && typeof report.generatedAtUtc === "string" &&
+        Number.isFinite(Date.parse(report.generatedAtUtc)), "missing scope or generation time");
+    requireValue(Array.isArray(report.functions) && Array.isArray(report.diagnostics), "collections required");
+    for (const diagnostic of report.diagnostics) {
+        keys(diagnostic, diagnostic.file === undefined ? ["code", "message"] : ["code", "message", "file"]);
+        requireValue(typeof diagnostic.code === "string" && typeof diagnostic.message === "string" &&
+            (diagnostic.file === undefined || typeof diagnostic.file === "string"), "invalid diagnostic");
+    }
+    if (report.status === "incomplete") {
+        requireValue(report.diagnostics.length > 0 && report.functions.length === 0 && report.summary === null, "incomplete results must withhold measurements");
+        return;
+    }
+    requireValue(report.status === "complete" && facts.status === "complete" && !report.diagnostics.length && report.functions.length <= 100000, "status or budget mismatch");
+    const owners = new Map(facts.functions.map(item => [item.id, item]));
+    const files = new Map(facts.selection.files.map(item => [item.file, item]));
+    const used = new Set();
+    for (const row of report.functions) {
+        keys(row, ["id", "file", "member", "line", "endLine", "population", "sourceSha256", "functionKind", "complexity", "disposition", "status", "measurement",
+            ...(row.status === "unavailable" ? ["reason"] : [])]);
+        const owner = owners.get(row.id);
+        requireValue(owner && !used.has(row.id), "unknown or repeated function");
+        used.add(row.id);
+        requireValue(row.file === owner.file && row.member === owner.member && row.line === owner.line && row.population === owner.population &&
+            row.sourceSha256 === files.get(row.file)?.contentSha256 && row.complexity === owner.complexity?.value &&
+            integer(row.endLine) && row.endLine >= row.line && row.disposition === "review-only", "location/source mismatch");
+        if (row.functionKind === "Lambda") {
+            requireValue(row.status === "unavailable" && row.measurement === null && row.reason === "lambda-expression-body", "lambda must be unavailable");
+            continue;
+        }
+        requireValue(["FunctionDef", "AsyncFunctionDef"].includes(row.functionKind) && row.status === "measured", "function measurement required");
+        keys(row.measurement, ["ownedStatements", "maxBlockNesting", "statementKinds", "excludedSyntax"]);
+        const measurement = row.measurement;
+        requireValue(integer(measurement.ownedStatements) && integer(measurement.maxBlockNesting), "invalid measurement");
+        requireValue(histogram(measurement.statementKinds, statements) === measurement.ownedStatements, "statement accounting mismatch");
+        histogram(measurement.excludedSyntax, excluded);
+        requireValue((measurement.excludedSyntax.docstring ?? 0) <= 1, "repeated leading docstring");
+        const blockCount = blocks.reduce((sum, kind) => sum + (measurement.statementKinds[kind] ?? 0), 0);
+        requireValue(measurement.maxBlockNesting <= blockCount && (measurement.maxBlockNesting === 0) === (blockCount === 0), "block accounting mismatch");
+    }
+    requireValue(used.size === owners.size, "missing selected functions");
+    requireValue(isDeepStrictEqual(report.summary, summary(report.functions)), "summary accounting mismatch");
+}

package/dist/python-duplication.d.ts

@@ -0,0 +1,65 @@
+import type { SourceFacts } from "#source-facts/contract.mjs";
+import { type Evidence, type Finding } from "./evidence.js";
+export declare const duplicationPolicy = "python/exact-function-body-v1";
+interface Location {
+    id: string;
+    file: string;
+    member: string;
+    line: number;
+    endLine: number;
+    population: string;
+    statementCount: number | null;
+    sourceSha256: string;
+}
+interface Group {
+    id: string;
+    population: string;
+    functionKind: string;
+    bodySha256: string;
+    statementCount: number;
+    occurrences: Location[];
+    disposition: "review-only";
+}
+export interface PythonDuplication {
+    schemaVersion: number;
+    artifactKind: string;
+    producer: {
+        name: string;
+        version: string;
+    };
+    generatedAtUtc: string;
+    runId: string;
+    auditId: string;
+    status: "complete" | "incomplete";
+    policy: string;
+    configuration: Record<string, string | number>;
+    configurationFingerprint: string;
+    subject: {
+        root: string;
+        entryPoint: string;
+    };
+    sourceFactsProducer: SourceFacts["producer"];
+    sourceFactsPolicy: string;
+    selection: SourceFacts["selection"];
+    scope: string;
+    diagnostics: SourceFacts["diagnostics"];
+    groups: Group[];
+    excludedFunctions: (Location & {
+        reason: string;
+    })[];
+    summary: {
+        selectedFunctions: number;
+        eligibleFunctions: number;
+        excludedFunctions: number;
+        exclusionReasons: Record<string, number>;
+        duplicateGroups: number;
+        matchedFunctions: number;
+    } | null;
+}
+/** Check provenance, population membership and accounting; source equality is a producer measurement. */
+export declare function validateDuplication(value: unknown, facts: SourceFacts, subject: Evidence["subject"], ids: {
+    runId: string;
+    auditId: string;
+}): asserts value is PythonDuplication;
+export declare function duplicationFindings(report: PythonDuplication): Finding[];
+export {};

package/dist/python-duplication.js

@@ -0,0 +1,89 @@
+import { isDeepStrictEqual } from "node:util";
+import { hash } from "./evidence.js";
+export const duplicationPolicy = "python/exact-function-body-v1";
+function requireValue(condition, message) {
+    if (!condition)
+        throw new Error(`Invalid Python duplication evidence: ${message}.`);
+}
+function keys(value, expected) {
+    requireValue(value !== null && typeof value === "object" && !Array.isArray(value), "object required");
+    requireValue(isDeepStrictEqual(Object.keys(value).sort(), expected.sort()), "unexpected or missing fields");
+}
+const hex = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const integer = (value) => Number.isSafeInteger(value) && value >= 0;
+/** Check provenance, population membership and accounting; source equality is a producer measurement. */
+export function validateDuplication(value, facts, subject, ids) {
+    keys(value, ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "status", "policy", "configuration",
+        "configurationFingerprint", "subject", "sourceFactsProducer", "sourceFactsPolicy", "selection", "diagnostics", "scope", "groups", "excludedFunctions", "summary"]);
+    const report = value;
+    requireValue(report.schemaVersion === 1 && report.artifactKind === "experimental-python-duplication-review" && report.policy === duplicationPolicy, "unsupported policy");
+    requireValue(isDeepStrictEqual(report.producer, { name: "codemetrics-ai/python-duplication", version: "0.1.0-experimental" }), "producer mismatch");
+    requireValue(report.runId === ids.runId && report.auditId === ids.auditId, "stale invocation identities");
+    const target = subject.entryPoint.replaceAll("\\", "/").endsWith("/pyproject.toml") ? subject.root : subject.entryPoint;
+    requireValue(isDeepStrictEqual(report.subject, { root: subject.root, entryPoint: target }), "subject mismatch");
+    requireValue(isDeepStrictEqual(report.sourceFactsProducer, facts.producer) && report.sourceFactsPolicy === facts.measurementPolicy &&
+        isDeepStrictEqual(report.selection, facts.selection), "source selection/provenance mismatch");
+    const configuration = { policy: duplicationPolicy, minimumStatements: 5, selectionFingerprint: facts.selection.configurationFingerprint,
+        parserVersion: facts.producer.parserVersion, maxOwners: 100000, maxNormalizedBytes: 67108864 };
+    requireValue(isDeepStrictEqual(report.configuration, configuration), "configuration mismatch");
+    requireValue(report.configurationFingerprint === hash(JSON.stringify(configuration, Object.keys(configuration).sort())), "configuration fingerprint mismatch");
+    requireValue(typeof report.scope === "string" && report.scope.length > 0 && typeof report.generatedAtUtc === "string" &&
+        Number.isFinite(Date.parse(report.generatedAtUtc)), "missing scope or generation time");
+    requireValue(Array.isArray(report.groups) && Array.isArray(report.excludedFunctions) && Array.isArray(report.diagnostics), "collections required");
+    for (const diagnostic of report.diagnostics) {
+        keys(diagnostic, diagnostic.file === undefined ? ["code", "message"] : ["code", "message", "file"]);
+        requireValue(typeof diagnostic.code === "string" && typeof diagnostic.message === "string" &&
+            (diagnostic.file === undefined || typeof diagnostic.file === "string"), "invalid diagnostic");
+    }
+    if (report.status === "incomplete") {
+        requireValue(report.diagnostics.length > 0 && report.groups.length === 0 && report.excludedFunctions.length === 0 && report.summary === null, "incomplete results must withhold groups and summary");
+        return;
+    }
+    requireValue(report.status === "complete" && facts.status === "complete" && report.diagnostics.length === 0, "status mismatch");
+    const owners = new Map(facts.functions.map(item => [item.id, item]));
+    const files = new Map(facts.selection.files.map(item => [item.file, item]));
+    const used = new Set(), groupIds = new Set(), bodies = new Set();
+    function location(item, excluded) {
+        keys(item, ["id", "file", "member", "line", "endLine", "population", "statementCount", "sourceSha256", ...(excluded ? ["reason"] : [])]);
+        const owner = owners.get(item.id);
+        requireValue(owner && !used.has(item.id), "unknown or repeated function");
+        used.add(item.id);
+        requireValue(item.file === owner.file && item.member === owner.member && item.line === owner.line && item.population === owner.population &&
+            item.sourceSha256 === files.get(item.file)?.contentSha256 && integer(item.endLine) && item.endLine >= item.line, "location/source mismatch");
+    }
+    const reasons = {};
+    for (const item of report.excludedFunctions) {
+        location(item, true);
+        requireValue(item.reason === "below-statement-minimum" ? integer(item.statementCount) && item.statementCount < 5 :
+            ["lambda", "nested-definition"].includes(item.reason) && item.statementCount === null, "exclusion mismatch");
+        reasons[item.reason] = (reasons[item.reason] ?? 0) + 1;
+    }
+    let matched = 0;
+    for (const group of report.groups) {
+        keys(group, ["id", "population", "functionKind", "bodySha256", "statementCount", "occurrences", "disposition"]);
+        requireValue(hex(group.id) && !groupIds.has(group.id) && hex(group.bodySha256), "invalid or repeated group identity");
+        groupIds.add(group.id);
+        const body = JSON.stringify([group.population, group.functionKind, group.bodySha256]);
+        requireValue(!bodies.has(body), "repeated body group");
+        bodies.add(body);
+        requireValue(["FunctionDef", "AsyncFunctionDef"].includes(group.functionKind) && group.disposition === "review-only" &&
+            integer(group.statementCount) && group.statementCount >= 5 && Array.isArray(group.occurrences) && group.occurrences.length >= 2, "invalid group");
+        for (const item of group.occurrences) {
+            location(item, false);
+            requireValue(item.population === group.population && item.statementCount === group.statementCount, "mixed group population/count");
+        }
+        matched += group.occurrences.length;
+    }
+    requireValue(isDeepStrictEqual(report.summary, { selectedFunctions: facts.functions.length, eligibleFunctions: facts.functions.length - report.excludedFunctions.length,
+        excludedFunctions: report.excludedFunctions.length, exclusionReasons: reasons, duplicateGroups: report.groups.length, matchedFunctions: matched }), "summary accounting mismatch");
+}
+export function duplicationFindings(report) {
+    return report.groups.map(group => {
+        const first = group.occurrences[0];
+        return { category: "exactBodyDuplicationReview", ruleId: "python/duplication/exact-function-body-v1",
+            fingerprint: group.id, severity: "info", confidence: "high", file: first.file, line: first.line, member: first.member,
+            message: `${group.occurrences.length} matching whole-function bodies (${group.statementCount} statements each); review context before suggesting extraction.`,
+            observations: { groupId: group.id, policy: report.policy, occurrences: group.occurrences, statementCount: group.statementCount,
+                scoringDisposition: "unscored", semanticEquivalence: "not-established" } };
+    });
+}

package/dist/python-error-context.d.ts

@@ -0,0 +1,84 @@
+import type { PythonErrorHandling } from "./python-error-handling.js";
+export declare const contextPolicy = "python/exception-context-patterns-v1";
+type Handler = PythonErrorHandling["handlers"][number];
+interface Statement {
+    kind: string;
+    line: number;
+    endLine: number;
+    literalReturnKind: string | null;
+    literalAssignment: {
+        targets: string[];
+        valueKind: string;
+    } | null;
+}
+interface Suite {
+    statementCount: number;
+    statements: Statement[];
+    truncated: boolean;
+}
+interface Context {
+    handlerId: string;
+    file: string;
+    line: number;
+    sourceSha256: string;
+    population: string;
+    owner: Handler["owner"];
+    tryStatement: {
+        line: number;
+        endLine: number;
+        kind: string;
+        body: Suite;
+        else: Suite;
+        finally: Suite;
+        handlerLines: number[];
+    };
+    handlerBody: Suite;
+    followingInSameSuite: Suite & {
+        suite: string;
+    };
+    enclosingConstructs: {
+        kind: string;
+        line: number;
+    }[];
+    surroundingDocumentation: {
+        items: {
+            kind: string;
+            line: number;
+            text: string;
+            truncated: boolean;
+        }[];
+        truncated: boolean;
+    };
+    classification: {
+        status: string;
+        pattern: string | null;
+        evidenceLines: number[];
+        unresolvedReasons: string[];
+    };
+    disposition: string;
+}
+export interface PythonErrorContext {
+    schemaVersion: number;
+    artifactKind: string;
+    producer: {
+        name: string;
+        version: string;
+    };
+    generatedAtUtc: string;
+    runId: string;
+    auditId: string;
+    policy: string;
+    configuration: Record<string, string | number>;
+    configurationFingerprint: string;
+    handlerReview: PythonErrorHandling;
+    handlerRowsSha256: string;
+    status: string;
+    diagnostics: PythonErrorHandling["diagnostics"];
+    contexts: Context[];
+    summary: unknown;
+    scope: string;
+}
+export declare function fingerprint(value: unknown): string;
+/** Validate source-bound consistency; syntax is not independently remeasured or authenticated. */
+export declare function validateErrorContext(value: unknown, base: PythonErrorHandling): asserts value is PythonErrorContext;
+export {};

package/dist/python-error-context.js

@@ -0,0 +1,165 @@
+import { isDeepStrictEqual } from "node:util";
+import { hash } from "./evidence.js";
+export const contextPolicy = "python/exception-context-patterns-v1";
+function requireValue(value, message) {
+    if (!value)
+        throw new Error(`Invalid Python exception context: ${message}.`);
+}
+function keys(value, names) {
+    requireValue(value !== null && typeof value === "object" && !Array.isArray(value), "object required");
+    requireValue(isDeepStrictEqual(Object.keys(value).sort(), names.sort()), "unexpected or missing fields");
+}
+const integer = (value) => Number.isSafeInteger(value) && value >= 0;
+const nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+const literalKinds = ["none", "bool", "int", "float", "complex", "str", "bytes"];
+const statementKinds = ["FunctionDef", "AsyncFunctionDef", "ClassDef", "Return", "Delete", "Assign", "TypeAlias", "AugAssign", "AnnAssign", "For", "AsyncFor", "While", "If", "With", "AsyncWith", "Match", "Raise", "Try", "TryStar", "Assert", "Import", "ImportFrom", "Global", "Nonlocal", "Expr", "Pass", "Break", "Continue"];
+const patterns = ["locally-documented-no-op", "direct-literal-fallback-return", "direct-bare-rethrow", "guarded-import-shape", "guarded-import-literal-default", "no-op-then-literal-return"];
+const reasons = ["exception-group-semantics", "enclosing-finally", "enclosing-context-manager", "nested-handler", "import-exception-binding-unresolved", "no-supported-local-shape"];
+// Match Python json.dumps(sort_keys=True, ensure_ascii=True, separators=(",", ":")) for this integer/string contract.
+export function fingerprint(value) {
+    const json = JSON.stringify(value, (_key, item) => item !== null && typeof item === "object" && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : item);
+    return hash(json.replace(/[\u007f-\uffff]/g, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`));
+}
+function suite(value, maximum, start, end, following = false) {
+    keys(value, ["statementCount", "statements", "truncated", ...(following ? ["suite"] : [])]);
+    requireValue(integer(value.statementCount) && Array.isArray(value.statements) && value.statements.length === Math.min(maximum, value.statementCount) &&
+        value.truncated === (value.statementCount > maximum), "suite accounting mismatch");
+    for (const [index, item] of value.statements.entries()) {
+        keys(item, ["kind", "line", "endLine", "literalReturnKind", "literalAssignment"]);
+        requireValue(statementKinds.includes(item.kind) && integer(item.line) && item.line >= start && integer(item.endLine) && item.endLine >= item.line && item.endLine <= end &&
+            (!index || item.line >= value.statements[index - 1].endLine), "invalid statement location or kind");
+        requireValue(item.literalReturnKind === null || item.kind === "Return" && literalKinds.includes(item.literalReturnKind), "invalid literal return");
+        if (item.literalAssignment !== null) {
+            keys(item.literalAssignment, ["targets", "valueKind"]);
+            requireValue(item.kind === "Assign" && literalKinds.includes(item.literalAssignment.valueKind) && Array.isArray(item.literalAssignment.targets) &&
+                item.literalAssignment.targets.length > 0 && item.literalAssignment.targets.every(nonempty), "invalid literal assignment");
+        }
+    }
+}
+function documentation(value, row) {
+    keys(value, ["items", "truncated"]);
+    requireValue(Array.isArray(value.items) && typeof value.truncated === "boolean", "documentation required");
+    let length = 0;
+    for (const item of value.items) {
+        keys(item, ["kind", "line", "text", "truncated"]);
+        requireValue(["preceding-try-comment", "owner-docstring"].includes(item.kind) && integer(item.line) && item.line > 0 && item.line < row.tryStatement.line &&
+            typeof item.text === "string" && item.text.length > 0 && typeof item.truncated === "boolean", "invalid surrounding prose");
+        length += [...item.text].length;
+    }
+    requireValue(length <= 2000 && (!value.items.some(item => item.truncated) || value.truncated), "documentation budget mismatch");
+}
+function classification(row, handler) {
+    const value = row.classification;
+    keys(value, ["status", "pattern", "evidenceLines", "unresolvedReasons"]);
+    requireValue(Array.isArray(value.evidenceLines) && value.evidenceLines.length > 0 && value.evidenceLines.every(line => integer(line) && line > 0) &&
+        Array.isArray(value.unresolvedReasons) && value.unresolvedReasons.every(reason => reasons.includes(reason)) && new Set(value.unresolvedReasons).size === value.unresolvedReasons.length, "invalid classification evidence");
+    const blockers = [
+        ...(handler.exceptionGroup ? ["exception-group-semantics"] : []),
+        ...(handler.enclosingFinallyLines.length ? ["enclosing-finally"] : []),
+        ...(row.enclosingConstructs.some(item => ["With", "AsyncWith"].includes(item.kind)) ? ["enclosing-context-manager"] : []),
+        ...(row.enclosingConstructs.some(item => item.kind === "ExceptHandler") ? ["nested-handler"] : [])
+    ];
+    if (value.status === "unresolved") {
+        requireValue(value.pattern === null && value.unresolvedReasons.length > 0 && isDeepStrictEqual(value.evidenceLines, [row.line]) &&
+            (blockers.length ? isDeepStrictEqual(value.unresolvedReasons, blockers) : value.unresolvedReasons.length === 1 && ["import-exception-binding-unresolved", "no-supported-local-shape"].includes(value.unresolvedReasons[0])), "unresolved classification mismatch");
+        requireValue(handler.classification !== "documented-no-op", "local documentation pattern missing");
+        return;
+    }
+    requireValue(value.status === "recognized-shape" && patterns.includes(value.pattern) && !value.unresolvedReasons.length, "invalid pattern");
+    const first = row.handlerBody.statements[0];
+    const imported = row.tryStatement.body;
+    let lines = [];
+    if (value.pattern === "locally-documented-no-op") {
+        requireValue(handler.classification === "documented-no-op", "documentation pattern mismatch");
+        lines = handler.documentation.map(item => item.line);
+    }
+    else {
+        requireValue(!blockers.length && handler.classification !== "documented-no-op", "pattern bypasses context or documentation precedence");
+        if (value.pattern === "direct-literal-fallback-return") {
+            requireValue(row.handlerBody.statementCount === 1 && first.literalReturnKind !== null && handler.classification === "terminal-return", "fallback pattern mismatch");
+            lines = [row.line, first.line];
+        }
+        else if (value.pattern === "direct-bare-rethrow") {
+            requireValue(row.handlerBody.statementCount === 1 && first.kind === "Raise" && handler.bodyObservations.raises.length === 1 && handler.bodyObservations.raises[0].bare, "rethrow pattern mismatch");
+            lines = [row.line, first.line];
+        }
+        else if (value.pattern === "no-op-then-literal-return") {
+            requireValue(handler.classification === "undocumented-no-op" && row.followingInSameSuite.statements[0]?.literalReturnKind != null, "fallthrough pattern mismatch");
+            lines = [row.line, row.followingInSameSuite.statements[0].line];
+        }
+        else {
+            requireValue(imported.statementCount === 1 && ["Import", "ImportFrom"].includes(imported.statements[0].kind) &&
+                /^(?:ImportError|ModuleNotFoundError|\((?:ImportError|ModuleNotFoundError)(?:, (?:ImportError|ModuleNotFoundError))*,?\))$/.test(handler.exceptionTypeSyntax ?? ""), "import pattern mismatch");
+            lines = [imported.statements[0].line, row.line];
+            if (value.pattern === "guarded-import-shape")
+                requireValue(handler.classification === "undocumented-no-op", "import no-op mismatch");
+            else {
+                requireValue(row.handlerBody.statementCount === 1 && first.literalAssignment !== null, "import default mismatch");
+                lines.push(first.line);
+            }
+        }
+        lines = [...new Set(lines)].sort((a, b) => a - b);
+    }
+    requireValue(isDeepStrictEqual(value.evidenceLines, lines), "pattern evidence locations mismatch");
+}
+function histogram(values) {
+    return Object.fromEntries([...new Set(values)].sort().map(key => [key, values.filter(value => value === key).length]));
+}
+function summary(rows) {
+    const counts = (items) => ({ handlers: items.length, recognizedShapes: items.filter(row => row.classification.status === "recognized-shape").length,
+        unresolved: items.filter(row => row.classification.status === "unresolved").length,
+        byPattern: histogram(items.flatMap(row => row.classification.pattern ? [row.classification.pattern] : [])),
+        unresolvedReasons: histogram(items.flatMap(row => row.classification.unresolvedReasons)) });
+    return { ...counts(rows), populations: Object.fromEntries([...new Set(rows.map(row => row.population))].sort().map(kind => [kind, counts(rows.filter(row => row.population === kind))])) };
+}
+/** Validate source-bound consistency; syntax is not independently remeasured or authenticated. */
+export function validateErrorContext(value, base) {
+    keys(value, ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "policy", "configuration", "configurationFingerprint", "handlerReview", "handlerRowsSha256", "status", "diagnostics", "contexts", "summary", "scope"]);
+    const report = value;
+    requireValue(report.schemaVersion === 1 && report.artifactKind === "experimental-python-exception-context-review" && report.policy === contextPolicy &&
+        isDeepStrictEqual(report.producer, { name: "codemetrics-ai/python-exception-context", version: "0.1.0-experimental" }), "unsupported producer or policy");
+    requireValue(report.runId === base.runId && report.auditId === base.auditId && isDeepStrictEqual(report.handlerReview, base) && report.handlerRowsSha256 === fingerprint(base.handlers), "handler provenance mismatch");
+    const configuration = { policy: contextPolicy, handlerPolicy: base.policy, maxStatementsPerSuite: 32, maxFollowingStatements: 3,
+        maxDocumentationCharacters: 2000, selectionFingerprint: base.selection.configurationFingerprint, parserVersion: base.sourceFactsProducer.parserVersion };
+    requireValue(isDeepStrictEqual(report.configuration, configuration) && report.configurationFingerprint === fingerprint(configuration), "configuration mismatch");
+    requireValue(nonempty(report.scope) && typeof report.generatedAtUtc === "string" && Number.isFinite(Date.parse(report.generatedAtUtc)) && Array.isArray(report.contexts) && Array.isArray(report.diagnostics), "missing metadata or collections");
+    for (const diagnostic of report.diagnostics) {
+        keys(diagnostic, diagnostic.file === undefined ? ["code", "message"] : ["code", "message", "file"]);
+        requireValue(nonempty(diagnostic.code) && nonempty(diagnostic.message) && (diagnostic.file === undefined || nonempty(diagnostic.file)), "invalid diagnostic");
+    }
+    if (report.status === "incomplete") {
+        requireValue(report.diagnostics.length > 0 && !report.contexts.length && report.summary === null, "incomplete results must withhold contexts");
+        return;
+    }
+    requireValue(report.status === "complete" && base.status === "complete" && !report.diagnostics.length && report.contexts.length === base.handlers.length, "status or population mismatch");
+    const handlers = new Map(base.handlers.map(row => [row.id, row]));
+    const used = new Set();
+    for (const row of report.contexts) {
+        keys(row, ["handlerId", "file", "line", "sourceSha256", "population", "owner", "tryStatement", "handlerBody", "followingInSameSuite", "enclosingConstructs", "surroundingDocumentation", "classification", "disposition"]);
+        const handler = handlers.get(row.handlerId);
+        requireValue(handler && !used.has(row.handlerId), "missing or repeated handler identity");
+        used.add(row.handlerId);
+        requireValue(row.file === handler.file && row.line === handler.line && row.sourceSha256 === handler.sourceSha256 && row.population === handler.population &&
+            isDeepStrictEqual(row.owner, handler.owner) && row.disposition === "review-only", "handler location/source mismatch");
+        const attempt = row.tryStatement;
+        keys(attempt, ["line", "endLine", "kind", "body", "else", "finally", "handlerLines"]);
+        requireValue(integer(attempt.line) && attempt.line > 0 && attempt.line < row.line && integer(attempt.endLine) && attempt.endLine >= handler.endLine &&
+            attempt.kind === (handler.exceptionGroup ? "TryStar" : "Try") && Array.isArray(attempt.handlerLines) && attempt.handlerLines.includes(row.line) &&
+            attempt.handlerLines.every((line, index, list) => integer(line) && line > attempt.line && line <= attempt.endLine && (!index || line > list[index - 1])), "invalid containing try");
+        for (const key of ["body", "else", "finally"])
+            suite(attempt[key], 32, attempt.line, attempt.endLine);
+        requireValue(attempt.body.statementCount > 0 && (attempt.finally.statementCount > 0) === handler.enclosingFinallyLines.includes(attempt.line), "try/finally mismatch");
+        suite(row.handlerBody, 32, handler.line, handler.endLine);
+        requireValue(row.handlerBody.statementCount > 0, "empty handler suite");
+        suite(row.followingInSameSuite, 3, attempt.endLine, Number.MAX_SAFE_INTEGER, true);
+        requireValue(["body", "orelse", "finalbody"].includes(row.followingInSameSuite.suite), "invalid containing suite");
+        requireValue(Array.isArray(row.enclosingConstructs) && row.enclosingConstructs.every(item => {
+            keys(item, ["kind", "line"]);
+            return [...statementKinds, "ExceptHandler"].includes(item.kind) && integer(item.line) && item.line > 0 && item.line < row.line;
+        }), "invalid ancestors");
+        documentation(row.surroundingDocumentation, row);
+        classification(row, handler);
+    }
+    requireValue(isDeepStrictEqual(report.summary, summary(report.contexts)), "summary accounting mismatch");
+}

package/dist/python-error-handling.d.ts

@@ -0,0 +1,56 @@
+import type { SourceFacts } from "#source-facts/contract.mjs";
+import { type Evidence } from "./evidence.js";
+import type { PythonDecomposition } from "./python-decomposition.js";
+export declare const errorHandlingPolicy = "python/exception-handler-observations-v1";
+interface Annotation {
+    kind: string;
+    line: number;
+    text: string;
+}
+interface Handler {
+    id: string;
+    file: string;
+    line: number;
+    endLine: number;
+    sourceSha256: string;
+    population: string;
+    owner: {
+        kind: string;
+        member: string;
+        functionId: string | null;
+    };
+    exceptionTypeSyntax: string | null;
+    bareExcept: boolean;
+    exceptionGroup: boolean;
+    enclosingFinallyLines: number[];
+    classification: string;
+    documentation: Annotation[];
+    directiveComments: Annotation[];
+    disposition: string;
+    bodyObservations: {
+        raises: {
+            line: number;
+            bare: boolean;
+            explicitCause: boolean;
+        }[];
+        returns: {
+            line: number;
+            hasValue: boolean;
+        }[];
+        loopTransfers: {
+            line: number;
+            kind: string;
+        }[];
+        calls: number;
+        nestedHandlersExcluded: number;
+    };
+}
+export interface PythonErrorHandling extends Omit<PythonDecomposition, "functions"> {
+    handlers: Handler[];
+}
+/** Checks provenance and internal consistency, not independent AST remeasurement or authentication. */
+export declare function validateErrorHandling(value: unknown, facts: SourceFacts, subject: Evidence["subject"], ids: {
+    runId: string;
+    auditId: string;
+}): asserts value is PythonErrorHandling;
+export {};