codemetrics-ai 0.5.0 → 0.6.0-preview.1

package/dist/python-error-handling.js

@@ -0,0 +1,120 @@
+import { isDeepStrictEqual } from "node:util";
+import { hash } from "./evidence.js";
+export const errorHandlingPolicy = "python/exception-handler-observations-v1";
+const documentationPolicy = "suite-comments-or-string-statements/tool-directives-excluded/content-not-adjudicated-v1";
+const classifications = ["documented-no-op", "undocumented-no-op", "terminal-raise", "terminal-return", "terminal-loop-control", "other-body"];
+function requireValue(condition, message) {
+    if (!condition)
+        throw new Error(`Invalid Python error-handling 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;
+const nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+function histogram(values) {
+    return Object.fromEntries([...new Set(values)].sort().map(value => [value, values.filter(item => item === value).length]));
+}
+function summary(rows) {
+    const counts = (items) => ({ handlers: items.length, byClassification: histogram(items.map(item => item.classification)) });
+    return { ...counts(rows), functionsWithHandlers: new Set(rows.map(row => row.owner.functionId).filter(Boolean)).size,
+        byOwnerKind: histogram(rows.map(row => row.owner.kind)),
+        populations: Object.fromEntries([...new Set(rows.map(row => row.population))].sort().map(kind => [kind, counts(rows.filter(row => row.population === kind))])) };
+}
+function annotations(value, row, directives) {
+    requireValue(Array.isArray(value), "annotations required");
+    for (const item of value) {
+        keys(item, ["kind", "line", "text"]);
+        requireValue((directives ? ["comment"] : ["comment", "string-statement"]).includes(item.kind) &&
+            integer(item.line) && item.line >= row.line && nonempty(item.text) && /[\p{L}\p{N}]/u.test(item.text), "invalid annotation");
+        // Trailing suite comments can extend beyond the AST handler's endLine.
+        const directive = /^(?:noqa\b|type:\s*ignore\b|pragma:\s*no cover\b|fmt:|pylint:|ruff:)/i.test(item.text);
+        requireValue(item.kind !== "comment" || directive === directives, "directive/documentation mismatch");
+        requireValue(item.kind !== "string-statement" || item.line <= row.endLine, "string outside handler");
+    }
+}
+function body(row) {
+    const value = row.bodyObservations;
+    keys(value, ["raises", "returns", "loopTransfers", "calls", "nestedHandlersExcluded"]);
+    requireValue(integer(value.calls) && integer(value.nestedHandlersExcluded), "invalid owned counts");
+    for (const [kind, fields] of [["raises", ["line", "bare", "explicitCause"]], ["returns", ["line", "hasValue"]], ["loopTransfers", ["line", "kind"]]]) {
+        requireValue(Array.isArray(value[kind]), "owned transfers required");
+        for (const item of value[kind]) {
+            keys(item, [...fields]);
+            requireValue(integer(item.line) && item.line >= row.line && item.line <= row.endLine, "transfer outside handler");
+            if ("bare" in item)
+                requireValue(typeof item.bare === "boolean" && typeof item.explicitCause === "boolean", "invalid raise");
+            if ("hasValue" in item)
+                requireValue(typeof item.hasValue === "boolean", "invalid return");
+            if ("kind" in item)
+                requireValue(["break", "continue"].includes(item.kind), "invalid loop transfer");
+        }
+    }
+    const inert = row.classification.endsWith("no-op");
+    if (inert)
+        requireValue(!value.raises.length && !value.returns.length && !value.loopTransfers.length && !value.calls && !value.nestedHandlersExcluded, "no-op has active syntax");
+    else
+        requireValue(!row.documentation.length && !row.directiveComments.length, "non-inert annotations outside policy");
+    requireValue(row.classification !== "documented-no-op" || row.documentation.length > 0, "documented no-op needs annotation");
+    requireValue(row.classification !== "undocumented-no-op" || !row.documentation.length, "undocumented no-op has annotation");
+    for (const [kind, count] of [["terminal-raise", value.raises.length], ["terminal-return", value.returns.length], ["terminal-loop-control", value.loopTransfers.length]])
+        requireValue(row.classification !== kind || Number(count) > 0, "terminal classification lacks transfer");
+}
+/** Checks provenance and internal consistency, not independent AST remeasurement or authentication. */
+export function validateErrorHandling(value, facts, subject, ids) {
+    keys(value, ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "status", "policy", "configuration",
+        "configurationFingerprint", "subject", "sourceFactsProducer", "sourceFactsPolicy", "selection", "diagnostics", "scope", "handlers", "summary"]);
+    const report = value;
+    requireValue(report.schemaVersion === 1 && report.artifactKind === "experimental-python-error-handling-review" && report.policy === errorHandlingPolicy, "unsupported policy");
+    requireValue(isDeepStrictEqual(report.producer, { name: "codemetrics-ai/python-error-handling", 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: errorHandlingPolicy, selectionFingerprint: facts.selection.configurationFingerprint,
+        parserVersion: facts.producer.parserVersion, maxHandlers: 100000, documentationPolicy };
+    requireValue(isDeepStrictEqual(report.configuration, configuration), "configuration mismatch");
+    requireValue(report.configurationFingerprint === hash(JSON.stringify(configuration, Object.keys(configuration).sort())), "configuration fingerprint mismatch");
+    requireValue(nonempty(report.scope) && typeof report.generatedAtUtc === "string" && Number.isFinite(Date.parse(report.generatedAtUtc)), "missing scope or generation time");
+    requireValue(Array.isArray(report.handlers) && Array.isArray(report.diagnostics), "collections required");
+    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.handlers.length === 0 && report.summary === null, "incomplete results must withhold measurements");
+        return;
+    }
+    requireValue(report.status === "complete" && facts.status === "complete" && !report.diagnostics.length && report.handlers.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.handlers) {
+        keys(row, ["id", "file", "line", "endLine", "sourceSha256", "population", "owner", "exceptionTypeSyntax", "bareExcept", "exceptionGroup",
+            "enclosingFinallyLines", "classification", "documentation", "directiveComments", "bodyObservations", "disposition"]);
+        const file = files.get(row.file);
+        requireValue(typeof row.id === "string" && /^[a-f0-9]{64}$/.test(row.id) && !used.has(row.id), "invalid or repeated handler identity");
+        used.add(row.id);
+        requireValue(file?.disposition === "analyzed" && row.sourceSha256 === file.contentSha256 && row.population === file.category &&
+            integer(row.line) && row.line > 0 && integer(row.endLine) && row.endLine >= row.line && row.disposition === "review-only", "location/source mismatch");
+        keys(row.owner, ["kind", "member", "functionId"]);
+        requireValue(nonempty(row.owner.member), "owner member required");
+        if (row.owner.kind === "function") {
+            const owner = owners.get(row.owner.functionId);
+            requireValue(owner && owner.file === row.file && owner.member === row.owner.member && owner.population === row.population && row.line >= owner.line, "function owner mismatch");
+        }
+        else
+            requireValue(["module", "class-body"].includes(row.owner.kind) && row.owner.functionId === null &&
+                (row.owner.kind !== "module" || row.owner.member === "<module>"), "invalid nonfunction owner");
+        requireValue(typeof row.bareExcept === "boolean" && typeof row.exceptionGroup === "boolean" &&
+            (row.bareExcept ? row.exceptionTypeSyntax === null && !row.exceptionGroup : nonempty(row.exceptionTypeSyntax)), "exception syntax mismatch");
+        requireValue(Array.isArray(row.enclosingFinallyLines) && row.enclosingFinallyLines.every((line, index, lines) => integer(line) && line > 0 && line < row.line && (index === 0 || line > lines[index - 1])), "invalid finally context");
+        requireValue(classifications.includes(row.classification), "unknown classification");
+        annotations(row.documentation, row, false);
+        annotations(row.directiveComments, row, true);
+        body(row);
+    }
+    requireValue(isDeepStrictEqual(report.summary, summary(report.handlers)), "summary accounting mismatch");
+}

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

@@ -0,0 +1,44 @@
+import { type PythonErrorContext } from "./python-error-context.js";
+import { type Expression, type PythonTransfers } from "./python-error-transfers.js";
+type Transfer = PythonTransfers["handlers"][number];
+interface Location {
+    id: string;
+    line: number;
+    column: number;
+    endLine: number;
+    endColumn: number;
+    ancestors: {
+        kind: string;
+        line: number;
+    }[];
+    ancestorsTruncated: boolean;
+    containsNamedExpression: boolean;
+}
+interface Call extends Location {
+    callee: Expression;
+    loggingNameSyntax: string | null;
+    directStatement: boolean;
+    immediatelyAwaited: boolean;
+    positionalArguments: number;
+    keywordArguments: number;
+    starredArguments: number;
+    keywordUnpacks: number;
+}
+interface Return extends Location {
+    direct: boolean;
+    expression: Expression;
+    awaitedExpression: Expression | null;
+}
+interface Handler extends Pick<Transfer, "handlerId" | "file" | "line" | "sourceSha256" | "population" | "owner" | "originalClassification" | "classification" | "disposition"> {
+    calls: Call[];
+    returns: Return[];
+    suite: PythonErrorContext["contexts"][number]["handlerBody"];
+}
+export interface PythonOperations extends Omit<PythonTransfers, "contextReview" | "contextRowsSha256" | "handlers"> {
+    transferReview: PythonTransfers;
+    transferRowsSha256: string;
+    handlers: Handler[];
+}
+/** Base must already be validated. Checks consistency, not independent AST measurement or authenticity. */
+export declare function validateOperations(value: unknown, base: PythonTransfers): asserts value is PythonOperations;
+export {};

package/dist/python-error-operations.js

@@ -0,0 +1,155 @@
+import { isDeepStrictEqual } from "node:util";
+import { hash } from "./evidence.js";
+import { fingerprint } from "./python-error-context.js";
+import { expression } from "./python-error-transfers.js";
+const policy = "python/exception-call-return-v1";
+const loggingNames = ["critical", "debug", "error", "exception", "fatal", "info", "log", "warn", "warning"];
+function requireValue(value, message) {
+    if (!value)
+        throw new Error(`Invalid Python call/return evidence: ${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 histogram = (values) => Object.fromEntries([...new Set(values)].sort().map(key => [key, values.filter(value => value === key).length]));
+function inventory(rows) {
+    const items = rows.filter(row => row.originalClassification.status === "unresolved");
+    const shapes = new Map();
+    for (const row of items) {
+        const kinds = row.suite.statements.map(item => item.kind), truncated = row.suite.truncated;
+        const key = JSON.stringify([kinds, truncated]);
+        const entry = shapes.get(key) ?? { kinds, truncated, handlers: 0 };
+        entry.handlers++;
+        shapes.set(key, entry);
+    }
+    const compareKinds = (left, right) => {
+        for (let index = 0; index < Math.min(left.length, right.length); index++)
+            if (left[index] !== right[index])
+                return left[index] < right[index] ? -1 : 1;
+        return left.length - right.length;
+    };
+    return { handlers: items.length, singleStatement: items.filter(row => row.suite.statementCount === 1).length,
+        multiStatement: items.filter(row => row.suite.statementCount > 1).length, withCalls: items.filter(row => row.calls.length).length,
+        withReturns: items.filter(row => row.returns.length).length, withLoggingNameSyntax: items.filter(row => row.calls.some(call => call.loggingNameSyntax)).length,
+        byReason: histogram(items.flatMap(row => row.originalClassification.unresolvedReasons)),
+        suiteShapes: [...shapes.values()].sort((a, b) => b.handlers - a.handlers || compareKinds(a.kinds, b.kinds) || Number(a.truncated) - Number(b.truncated)) };
+}
+function summary(rows) {
+    const counts = (items) => {
+        const calls = items.flatMap(row => row.calls), returns = items.flatMap(row => row.returns);
+        return { 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)), callExpressions: calls.length, returnStatements: returns.length,
+            handlersWithCalls: items.filter(row => row.calls.length).length, handlersWithReturns: items.filter(row => row.returns.length).length,
+            loggingNameSyntaxCalls: calls.filter(row => row.loggingNameSyntax !== null).length, immediatelyAwaitedCalls: calls.filter(row => row.immediatelyAwaited).length,
+            byReturnExpression: histogram(returns.map(row => row.expression.kind)),
+            newlyRecognizedShapes: items.filter(row => row.originalClassification.status === "unresolved" && row.classification.status === "recognized-shape").length,
+            inputUnresolvedInventory: inventory(items) };
+    };
+    return { ...counts(rows), populations: Object.fromEntries([...new Set(rows.map(row => row.population))].sort().map(kind => [kind, counts(rows.filter(row => row.population === kind))])) };
+}
+function classification(row, prior) {
+    if (prior.classification.status === "recognized-shape" || !isDeepStrictEqual(prior.classification.unresolvedReasons, ["no-supported-local-shape"]) ||
+        row.calls.some(call => call.containsNamedExpression) || row.returns.some(item => item.containsNamedExpression))
+        return prior.classification;
+    let pattern = null;
+    let lines = [];
+    const returned = row.returns.find(item => item.direct);
+    if (row.suite.statementCount === 1 && returned && ["name", "attribute", "call"].includes(returned.expression.kind) && returned.expression.symbol !== null) {
+        pattern = "direct-symbol-or-call-return";
+        lines = [returned.line];
+    }
+    else {
+        const calls = row.calls.filter(call => call.directStatement);
+        const raises = prior.raises.filter(item => item.direct);
+        const rethrow = raises.length === 1 && raises[0].exception.kind === "absent" && row.suite.statementCount > 1;
+        if (calls.length > 0 && calls.length + Number(rethrow) === row.suite.statementCount && !returned &&
+            calls.every(call => !call.immediatelyAwaited && ["name", "attribute"].includes(call.callee.kind) && call.callee.symbol !== null) &&
+            (!rethrow || calls.every(call => call.line < raises[0].line || call.line === raises[0].line && call.column < raises[0].column))) {
+            pattern = rethrow ? "direct-calls-then-bare-raise" : "direct-call-statement-sequence";
+            lines = calls.map(call => call.ancestors[0].line).concat(rethrow ? [raises[0].line] : []);
+        }
+    }
+    return pattern ? { status: "recognized-shape", pattern, evidenceLines: [...new Set([row.line, ...lines])].sort((a, b) => a - b), unresolvedReasons: [] } : prior.classification;
+}
+const locationKeys = ["id", "line", "column", "endLine", "endColumn", "ancestors", "ancestorsTruncated", "containsNamedExpression"];
+function location(item, previous, row, endLine, kind, seen) {
+    requireValue(integer(item.line) && item.line >= row.line && integer(item.column) && integer(item.endLine) && item.endLine >= item.line && item.endLine <= endLine && integer(item.endColumn) && (item.endLine > item.line || item.endColumn > item.column) &&
+        (!previous || item.line > previous.line || item.line === previous.line && item.column > previous.column || item.line === previous.line && item.column === previous.column && (item.endLine < previous.endLine || item.endLine === previous.endLine && item.endColumn < previous.endColumn)), "invalid location/order");
+    requireValue(item.id === hash(`${row.file}|${item.line}|${item.column}|${item.endLine}|${item.endColumn}|${kind}`) && !seen.has(item.id), "operation identity mismatch");
+    seen.add(item.id);
+    requireValue(typeof item.containsNamedExpression === "boolean" && typeof item.ancestorsTruncated === "boolean" && Array.isArray(item.ancestors) &&
+        item.ancestors.length <= 32 && (!item.ancestorsTruncated || item.ancestors.length === 32), "invalid ancestor accounting");
+    for (const [index, ancestor] of item.ancestors.entries()) {
+        keys(ancestor, ["kind", "line"]);
+        requireValue(typeof ancestor.kind === "string" && /^[A-Z][A-Za-z]*$/.test(ancestor.kind) && integer(ancestor.line) && ancestor.line >= row.line &&
+            ancestor.line <= item.line && (!index || ancestor.line <= item.ancestors[index - 1].line), "invalid ancestor metadata");
+    }
+}
+/** Base must already be validated. Checks consistency, not independent AST measurement or authenticity. */
+export function validateOperations(value, base) {
+    keys(value, ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "policy", "configuration", "configurationFingerprint", "transferReview", "transferRowsSha256", "status", "diagnostics", "handlers", "summary", "scope"]);
+    const report = value;
+    requireValue(report.schemaVersion === 1 && report.artifactKind === "experimental-python-exception-operation-review" && report.policy === policy &&
+        isDeepStrictEqual(report.producer, { name: "codemetrics-ai/python-exception-operations", version: "0.2.0-experimental" }), "unsupported producer/policy");
+    requireValue(report.runId === base.runId && report.auditId === base.auditId && isDeepStrictEqual(report.transferReview, base) && report.transferRowsSha256 === fingerprint(base.handlers), "transfer provenance mismatch");
+    const configuration = { policy, transferPolicy: base.policy, transferConfigurationFingerprint: base.configurationFingerprint,
+        maxOperations: 100000, maxAncestors: 32, maxSuiteStatements: 32, maxSymbolCharacters: 200, maxSymbolAttributes: 8, loggingNames };
+    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.handlers) && Array.isArray(report.diagnostics), "invalid metadata/collections");
+    for (const item of report.diagnostics) {
+        keys(item, item.file === undefined ? ["code", "message"] : ["code", "message", "file"]);
+        requireValue(nonempty(item.code) && nonempty(item.message) && (item.file === undefined || nonempty(item.file)), "invalid diagnostic");
+    }
+    if (report.status === "incomplete") {
+        requireValue(report.diagnostics.length > 0 && !report.handlers.length && report.summary === null, "incomplete report must withhold rows");
+        return;
+    }
+    requireValue(report.status === "complete" && base.status === "complete" && !report.diagnostics.length && report.handlers.length === base.handlers.length, "status/population mismatch");
+    const prior = new Map(base.handlers.map(row => [row.handlerId, row]));
+    const contexts = new Map(base.contextReview.contexts.map(row => [row.handlerId, row]));
+    const originals = new Map(base.contextReview.handlerReview.handlers.map(row => [row.id, row]));
+    const used = new Set(), seen = new Set();
+    for (const row of report.handlers) {
+        keys(row, ["handlerId", "file", "line", "sourceSha256", "population", "owner", "calls", "returns", "suite", "originalClassification", "classification", "disposition"]);
+        const old = prior.get(row.handlerId), context = contexts.get(row.handlerId), original = originals.get(row.handlerId);
+        requireValue(old && context && original && !used.has(row.handlerId), "missing or repeated handler");
+        used.add(row.handlerId);
+        requireValue(["file", "line", "sourceSha256", "population", "owner"].every(key => isDeepStrictEqual(row[key], old[key])) &&
+            row.disposition === "review-only" && isDeepStrictEqual(row.originalClassification, old.classification) && isDeepStrictEqual(row.suite, context.handlerBody) &&
+            Array.isArray(row.calls) && Array.isArray(row.returns), "handler provenance or suite mismatch");
+        for (const [index, call] of row.calls.entries()) {
+            keys(call, [...locationKeys, "callee", "loggingNameSyntax", "directStatement", "immediatelyAwaited", "positionalArguments", "keywordArguments", "starredArguments", "keywordUnpacks"]);
+            location(call, row.calls[index - 1], row, original.endLine, "Call", seen);
+            expression(call.callee, old.handlerNameSyntax);
+            const terminal = ["name", "attribute"].includes(call.callee.kind) ? call.callee.symbol?.split(".").at(-1) : undefined;
+            requireValue(call.loggingNameSyntax === (terminal && loggingNames.includes(terminal) ? terminal : null), "logging-name hint mismatch");
+            requireValue(call.immediatelyAwaited === (call.ancestors[0]?.kind === "Await") && call.directStatement === (!call.ancestorsTruncated &&
+                (call.ancestors.length === 1 && call.ancestors[0].kind === "Expr" || call.ancestors.length === 2 && call.ancestors[0].kind === "Await" && call.ancestors[1].kind === "Expr")), "call context mismatch");
+            requireValue([call.positionalArguments, call.keywordArguments, call.starredArguments, call.keywordUnpacks].every(integer) &&
+                call.starredArguments <= call.positionalArguments && call.keywordUnpacks <= call.keywordArguments, "invalid argument accounting");
+            if (call.directStatement && !row.suite.truncated)
+                requireValue(row.suite.statements.some(item => item.kind === "Expr" && item.line === call.ancestors.at(-1).line && item.endLine >= call.endLine), "direct call absent from suite");
+        }
+        for (const [index, item] of row.returns.entries()) {
+            keys(item, [...locationKeys, "direct", "expression", "awaitedExpression"]);
+            location(item, row.returns[index - 1], row, original.endLine, "Return", seen);
+            expression(item.expression, old.handlerNameSyntax);
+            requireValue(item.direct === (item.ancestors.length === 0), "return context mismatch");
+            if (item.expression.astKind === "Await")
+                expression(item.awaitedExpression, old.handlerNameSyntax);
+            else
+                requireValue(item.awaitedExpression === null, "unexpected awaited expression");
+            if (item.direct && !row.suite.truncated)
+                requireValue(row.suite.statements.some(statement => statement.kind === "Return" && statement.line === item.line && statement.endLine === item.endLine), "direct return absent from suite");
+        }
+        requireValue(seen.size <= 100000 && row.calls.length === original.bodyObservations.calls &&
+            isDeepStrictEqual(row.returns.map(item => ({ line: item.line, hasValue: item.expression.kind !== "absent" })), original.bodyObservations.returns), "owned call/return population mismatch");
+        requireValue(isDeepStrictEqual(row.classification, classification(row, old)), "classification mismatch");
+    }
+    requireValue(isDeepStrictEqual(report.summary, summary(report.handlers)), "summary/inventory mismatch");
+}

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

@@ -0,0 +1,38 @@
+import { type PythonErrorContext } from "./python-error-context.js";
+type Context = PythonErrorContext["contexts"][number];
+export interface Expression {
+    kind: string;
+    astKind: string | null;
+    symbol: string | null;
+    matchesHandlerNameSyntax: boolean;
+}
+interface Raise {
+    id: string;
+    line: number;
+    column: number;
+    endLine: number;
+    direct: boolean;
+    exception: Expression;
+    cause: Expression;
+    containsNamedExpression: boolean;
+    containers: {
+        kind: string;
+        line: number;
+    }[];
+    containersTruncated: boolean;
+}
+interface Handler extends Pick<Context, "handlerId" | "file" | "line" | "sourceSha256" | "population" | "owner" | "disposition"> {
+    handlerNameSyntax: string | null;
+    raises: Raise[];
+    originalClassification: Context["classification"];
+    classification: Context["classification"];
+}
+export interface PythonTransfers extends Omit<PythonErrorContext, "handlerReview" | "handlerRowsSha256" | "contexts"> {
+    contextReview: PythonErrorContext;
+    contextRowsSha256: string;
+    handlers: Handler[];
+}
+export declare function expression(value: Expression, handlerName: string | null): void;
+/** Internal/source-bound consistency only, not AST remeasurement or authentication. Base must be validated first. */
+export declare function validateTransfers(value: unknown, base: PythonErrorContext): asserts value is PythonTransfers;
+export {};

package/dist/python-error-transfers.js

@@ -0,0 +1,125 @@
+import { isDeepStrictEqual } from "node:util";
+import { hash } from "./evidence.js";
+import { fingerprint } from "./python-error-context.js";
+const policy = "python/exception-raise-chaining-v1";
+function requireValue(value, message) {
+    if (!value)
+        throw new Error(`Invalid Python raise/chaining evidence: ${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 name = (value) => typeof value === "string" && /^[_\p{ID_Start}][_\p{ID_Continue}]*$/u.test(value);
+export function expression(value, handlerName) {
+    keys(value, ["kind", "astKind", "symbol", "matchesHandlerNameSyntax"]);
+    requireValue(["absent", "none", "name", "attribute", "call", "other"].includes(value.kind) && typeof value.matchesHandlerNameSyntax === "boolean", "invalid expression kind");
+    const expected = { absent: null, none: "Constant", name: "Name", attribute: "Attribute", call: "Call" };
+    requireValue(value.kind === "other" ? nonempty(value.astKind) && !["Name", "Attribute", "Call"].includes(value.astKind)
+        : value.astKind === expected[value.kind], "AST kind mismatch");
+    if (value.symbol !== null) {
+        requireValue(["name", "attribute", "call"].includes(value.kind) && typeof value.symbol === "string" && [...value.symbol].length <= 200 &&
+            value.symbol.split(".").length <= 9 && value.symbol.split(".").every(name), "invalid symbol path");
+        requireValue(value.kind !== "name" || !value.symbol.includes("."), "name cannot be a path");
+        requireValue(value.kind !== "attribute" || value.symbol.includes("."), "attribute needs a path");
+    }
+    // Long names intentionally have no bounded symbol, but can still match the original handler name.
+    requireValue(!value.matchesHandlerNameSyntax || value.kind === "name" && handlerName !== null && (value.symbol === null ? [...handlerName].length > 200 : value.symbol === handlerName), "handler-name correspondence mismatch");
+    if (value.kind === "name" && value.symbol !== null)
+        requireValue(value.matchesHandlerNameSyntax === (value.symbol === handlerName), "handler-name match omitted");
+}
+function classification(row, original) {
+    const prior = original.classification;
+    if (prior.status === "recognized-shape" || !isDeepStrictEqual(prior.unresolvedReasons, ["no-supported-local-shape"]) ||
+        original.handlerBody.statementCount !== 1 || original.handlerBody.statements[0].kind !== "Raise")
+        return prior;
+    requireValue(row.raises.length === 1 && row.raises[0].direct, "single raise suite mismatch");
+    const item = row.raises[0];
+    let pattern = null;
+    if (!item.containsNamedExpression && item.exception.symbol !== null) {
+        if (item.cause.kind === "none")
+            pattern = "direct-raise-from-none";
+        else if (item.cause.matchesHandlerNameSyntax)
+            pattern = "direct-raise-from-handler-name";
+        else if (item.cause.kind === "absent")
+            pattern = item.exception.matchesHandlerNameSyntax ? "direct-handler-name-raise" : "direct-symbol-or-call-raise";
+    }
+    return pattern ? { status: "recognized-shape", pattern, evidenceLines: [...new Set([row.line, item.line])].sort((a, b) => a - b), unresolvedReasons: [] }
+        : { status: "unresolved", pattern: null, evidenceLines: [row.line], unresolvedReasons: ["raise-expression-or-cause-unresolved"] };
+}
+const histogram = (values) => Object.fromEntries([...new Set(values)].sort().map(key => [key, values.filter(value => value === key).length]));
+function summary(rows) {
+    const counts = (items) => {
+        const raises = items.flatMap(row => row.raises);
+        return { 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)), raiseStatements: raises.length,
+            handlersWithRaises: items.filter(row => row.raises.length).length,
+            newlyRecognizedShapes: items.filter(row => row.originalClassification.status === "unresolved" && row.classification.status === "recognized-shape").length,
+            byExceptionSyntax: histogram(raises.map(row => row.exception.kind)), byCauseSyntax: histogram(raises.map(row => row.cause.kind)),
+            handlerNameRaiseSyntax: raises.filter(row => row.exception.matchesHandlerNameSyntax).length,
+            handlerNameCauseSyntax: raises.filter(row => row.cause.matchesHandlerNameSyntax).length };
+    };
+    return { ...counts(rows), populations: Object.fromEntries([...new Set(rows.map(row => row.population))].sort().map(kind => [kind, counts(rows.filter(row => row.population === kind))])) };
+}
+/** Internal/source-bound consistency only, not AST remeasurement or authentication. Base must be validated first. */
+export function validateTransfers(value, base) {
+    keys(value, ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "policy", "configuration", "configurationFingerprint", "contextReview", "contextRowsSha256", "status", "diagnostics", "handlers", "summary", "scope"]);
+    const report = value;
+    requireValue(report.schemaVersion === 1 && report.artifactKind === "experimental-python-exception-transfer-review" && report.policy === policy &&
+        isDeepStrictEqual(report.producer, { name: "codemetrics-ai/python-exception-transfers", version: "0.1.0-experimental" }), "unsupported producer or policy");
+    requireValue(report.runId === base.runId && report.auditId === base.auditId && isDeepStrictEqual(report.contextReview, base) && report.contextRowsSha256 === fingerprint(base.contexts), "context provenance mismatch");
+    const configuration = { policy, contextPolicy: base.policy, contextConfigurationFingerprint: base.configurationFingerprint,
+        maxRaises: 100000, maxSymbolCharacters: 200, maxContainers: 32, maxSymbolAttributes: 8 };
+    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.handlers) && Array.isArray(report.diagnostics), "invalid metadata or collections");
+    for (const item of report.diagnostics) {
+        keys(item, item.file === undefined ? ["code", "message"] : ["code", "message", "file"]);
+        requireValue(nonempty(item.code) && nonempty(item.message) && (item.file === undefined || nonempty(item.file)), "invalid diagnostic");
+    }
+    if (report.status === "incomplete") {
+        requireValue(report.diagnostics.length > 0 && !report.handlers.length && report.summary === null, "incomplete report must withhold rows");
+        return;
+    }
+    requireValue(report.status === "complete" && base.status === "complete" && !report.diagnostics.length && report.handlers.length === base.contexts.length, "status or population mismatch");
+    const contexts = new Map(base.contexts.map(row => [row.handlerId, row]));
+    const handlers = new Map(base.handlerReview.handlers.map(row => [row.id, row]));
+    const used = new Set(), raiseIds = new Set();
+    for (const row of report.handlers) {
+        keys(row, ["handlerId", "file", "line", "sourceSha256", "population", "owner", "handlerNameSyntax", "raises", "originalClassification", "classification", "disposition"]);
+        const original = contexts.get(row.handlerId), handler = handlers.get(row.handlerId);
+        requireValue(original && handler && !used.has(row.handlerId), "missing or repeated handler identity");
+        used.add(row.handlerId);
+        requireValue(["file", "line", "sourceSha256", "population", "owner"].every(key => isDeepStrictEqual(row[key], original[key])) &&
+            row.disposition === "review-only" && isDeepStrictEqual(row.originalClassification, original.classification) &&
+            (row.handlerNameSyntax === null || name(row.handlerNameSyntax)) && Array.isArray(row.raises), "handler/context mismatch");
+        for (const [index, item] of row.raises.entries()) {
+            keys(item, ["id", "line", "column", "endLine", "direct", "exception", "cause", "containsNamedExpression", "containers", "containersTruncated"]);
+            requireValue(integer(item.line) && item.line >= row.line && integer(item.endLine) && item.endLine >= item.line && item.endLine <= handler.endLine && integer(item.column) &&
+                (!index || item.line > row.raises[index - 1].line || item.line === row.raises[index - 1].line && item.column > row.raises[index - 1].column), "invalid raise location/order");
+            requireValue(item.id === hash(`${row.file}|${item.line}|${item.column}|Raise`) && !raiseIds.has(item.id), "raise identity mismatch");
+            raiseIds.add(item.id);
+            expression(item.exception, row.handlerNameSyntax);
+            expression(item.cause, row.handlerNameSyntax);
+            requireValue(item.exception.kind !== "absent" || item.cause.kind === "absent", "bare raise cannot have a cause");
+            requireValue(typeof item.direct === "boolean" && typeof item.containsNamedExpression === "boolean" && typeof item.containersTruncated === "boolean" &&
+                Array.isArray(item.containers) && item.containers.length <= 32 && (!item.containersTruncated || item.containers.length === 32) && item.direct === !item.containers.length, "invalid container accounting");
+            for (const [position, container] of item.containers.entries()) {
+                keys(container, ["kind", "line"]);
+                requireValue(["If", "For", "AsyncFor", "While", "Try", "TryStar", "With", "AsyncWith", "Match"].includes(container.kind) && integer(container.line) &&
+                    container.line >= row.line && container.line <= item.line && (!position || container.line <= item.containers[position - 1].line), "invalid enclosing statement");
+            }
+            const direct = original.handlerBody.statements.find(statement => statement.kind === "Raise" && statement.line === item.line && statement.endLine === item.endLine);
+            requireValue(!direct || item.direct, "direct raise marked nested");
+            if (item.direct && !original.handlerBody.truncated)
+                requireValue(direct, "direct raise absent from suite");
+        }
+        const projected = row.raises.map(item => ({ line: item.line, bare: item.exception.kind === "absent", explicitCause: item.cause.kind !== "absent" }));
+        requireValue(isDeepStrictEqual(projected, handler.bodyObservations.raises), "owned raises disagree with original observations");
+        requireValue(isDeepStrictEqual(row.classification, classification(row, original)), "classification mismatch");
+    }
+    requireValue(raiseIds.size <= 100000 && isDeepStrictEqual(report.summary, summary(report.handlers)), "summary or budget mismatch");
+}

package/dist/python-evidence.d.ts

@@ -0,0 +1,23 @@
+import { type PythonAsyncHelpers, type PythonAsyncScoring } from "./python-async-scoring.js";
+import { type PythonAsyncAdapters } from "./python-async-adapters.js";
+import { type PythonAsyncContext } from "./python-async-context.js";
+import { type PythonAsyncUsage } from "./python-async-usage.js";
+import { type SourceFacts } from "#source-facts/contract.mjs";
+import { type Evidence } from "./evidence.js";
+import { type PythonDuplication } from "./python-duplication.js";
+import { type PythonCoverage } from "./python-coverage.js";
+import { type PythonDecomposition } from "./python-decomposition.js";
+import { type PythonErrorHandling } from "./python-error-handling.js";
+import { type PythonErrorContext } from "./python-error-context.js";
+import { type PythonOperations } from "./python-error-operations.js";
+import { type PythonTransfers } from "./python-error-transfers.js";
+export declare const pythonVersion = "0.15.0";
+export declare const pythonRuleset = "python-2026-10-28-async-scoring-v1";
+export declare function pythonEvidence(facts: SourceFacts | null, subject: Evidence["subject"], ids: {
+    runId: string;
+    auditId: string;
+}, error?: string, duplication?: PythonDuplication | null, coverage?: PythonCoverage | null, decomposition?: PythonDecomposition | null, errorHandling?: PythonErrorHandling | null, context?: PythonErrorContext | null, transfers?: PythonTransfers | null, operations?: PythonOperations | null, asyncReview?: PythonAsyncUsage | null, asyncContext?: PythonAsyncContext | null, asyncAdapters?: PythonAsyncAdapters | null, asyncHelpers?: PythonAsyncHelpers | null, asyncScoring?: PythonAsyncScoring | null): Evidence;
+/** Validate supported scoring and historical review contracts within the shared v3 envelope. */
+export declare function validatePythonEvidence(evidence: Evidence): void;
+/** Historical previews and unavailable populations cannot participate in score comparisons. */
+export declare function supportsPythonComparison(evidence: Evidence): boolean;