codemetrics-ai 0.4.0 → 0.6.0-preview.1

package/dist/python/source_selection.py

@@ -0,0 +1,157 @@
+"""Deterministic, overridable selection. These categories are scope, not defects."""
+
+import ast
+from fnmatch import fnmatchcase
+import hashlib
+import io
+import json
+from pathlib import PurePosixPath
+import re
+import tokenize
+
+
+POLICY = "python/source-selection-v1"
+GENERATED = re.compile(r"^\s*#\s*(?:generated by\b|this file (?:is|was) (?:automatically )?generated\b|automatically generated\b|code generated\b)", re.I)
+
+
+def matches(file, patterns):
+    for pattern in patterns:
+        if fnmatchcase(file, pattern):
+            return True
+        while pattern.startswith("**/"):
+            pattern = pattern[3:]
+            if fnmatchcase(file, pattern):
+                return True
+    return False
+
+
+def selection_options(include=(), exclude=(), test_paths=(), production_paths=(), include_tests=False, include_generated=False, include_support=False):
+    options = {
+        "include": sorted(set(include)), "exclude": sorted(set(exclude)),
+        "testPaths": sorted(set(test_paths)), "productionPaths": sorted(set(production_paths)),
+        "includeTests": include_tests, "includeGenerated": include_generated, "includeSupport": include_support,
+    }
+    for key in ("include", "exclude", "testPaths", "productionPaths"):
+        for pattern in options[key]:
+            if not pattern or "\\" in pattern or pattern.startswith("/") or ":" in pattern or ".." in pattern.split("/"):
+                raise ValueError("Selection patterns must be nonempty root-relative POSIX patterns without '..'.")
+    return options
+
+
+def inventory(options):
+    fingerprint = hashlib.sha256(json.dumps({"policy": POLICY, "options": options}, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+    return {"policy": POLICY, "configurationFingerprint": fingerprint, "options": options,
+            "files": [], "prunedDirectories": [], "excludedFunctions": []}
+
+
+def category(file, options):
+    path = PurePosixPath(file)
+    if path.suffix == ".pyi":
+        return "declaration", "stub-file"
+    if matches(file, options["productionPaths"]):
+        return "production", "explicit-production-path"
+    if matches(file, options["testPaths"]):
+        return "test", "explicit-test-path"
+    if any(part in {"test", "tests"} for part in path.parts[:-1]) or path.name == "conftest.py" or path.name.startswith("test_") or path.name.endswith("_test.py"):
+        return "test", "test-path-convention"
+    if any(part in {"docs", "doc", "examples", "benchmarks"} for part in path.parts[:-1]) or file in {"setup.py", "noxfile.py"}:
+        return "support", "support-path-convention"
+    return "production", "production-candidate"
+
+
+def file_record(file, options):
+    kind, reason = category(file, options)
+    disposition = "analyzed"
+    if options["include"] and not matches(file, options["include"]):
+        disposition, reason = "excluded", "outside-include-selection"
+    elif matches(file, options["exclude"]):
+        disposition, reason = "excluded", "explicit-exclusion"
+    elif kind == "declaration" or (kind == "test" and not options["includeTests"]) or (kind == "support" and not options["includeSupport"]):
+        disposition = "excluded"
+    return {"file": file, "category": kind, "disposition": disposition, "reason": reason, "contentSha256": None}
+
+
+def generated_source(source):
+    try:
+        for token in tokenize.generate_tokens(io.StringIO(source).readline):
+            if token.start[0] > 20:
+                break
+            if token.type == tokenize.COMMENT and GENERATED.match(token.string):
+                return True
+    except (tokenize.TokenError, IndentationError):
+        pass  # The AST parser will report malformed selected source.
+    return False
+
+
+def bound_names(node):
+    """Conservative whole-file shadow check; uncertainty keeps implementations in scope."""
+    names = set()
+    for child in ast.walk(node):
+        if isinstance(child, ast.Name) and isinstance(child.ctx, (ast.Store, ast.Del)):
+            names.add(child.id)
+        elif isinstance(child, ast.arg):
+            names.add(child.arg)
+        elif isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            names.add(child.name)
+        elif isinstance(child, ast.ExceptHandler) and child.name:
+            names.add(child.name)
+        elif isinstance(child, (ast.MatchAs, ast.MatchStar)) and child.name:
+            names.add(child.name)
+        elif isinstance(child, ast.MatchMapping) and child.rest:
+            names.add(child.rest)
+        elif isinstance(child, (ast.Attribute, ast.Subscript)) and isinstance(child.ctx, (ast.Store, ast.Del)):
+            base = child.value
+            while isinstance(base, (ast.Attribute, ast.Subscript)):
+                base = base.value
+            if isinstance(base, ast.Name):
+                names.add(base.id)
+    return names
+
+
+def import_bindings(tree):
+    bindings, seen = {}, {}
+    top_level = {id(node) for node in tree.body}
+    for node in ast.walk(tree):
+        pairs = []
+        if isinstance(node, ast.Import):
+            pairs = [(item.asname or item.name.split(".")[0], item.name if item.asname else item.name.split(".")[0]) for item in node.names]
+        elif isinstance(node, ast.ImportFrom):
+            pairs = [(item.asname or item.name, f"{node.module}.{item.name}" if not node.level else "<relative>") for item in node.names]
+        for name, target in pairs:
+            seen.setdefault(name, set()).add(target)
+            if id(node) in top_level:
+                bindings[name] = target
+    blocked = bound_names(tree)
+    if "*" in seen:
+        return {}
+    return {name: target for name, target in bindings.items() if name not in blocked and seen[name] == {target}}
+
+
+def resolve(node, bindings):
+    if isinstance(node, ast.Subscript):
+        return resolve(node.value, bindings)
+    if isinstance(node, ast.Name):
+        return bindings.get(node.id)
+    if isinstance(node, ast.Attribute):
+        owner = resolve(node.value, bindings)
+        return f"{owner}.{node.attr}" if owner else None
+    return None
+
+
+def declaration_reason(node, bindings, protocol_method=False):
+    if isinstance(node, ast.Lambda):
+        return None
+    body = node.body
+    if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant) and isinstance(body[0].value.value, str):
+        body = body[1:]
+    placeholder = all(isinstance(item, ast.Pass) or (isinstance(item, ast.Expr) and isinstance(item.value, ast.Constant) and item.value.value is Ellipsis) for item in body)
+    if not placeholder:
+        return None
+    decorators = {resolve(item, bindings) for item in node.decorator_list}
+    if decorators & {"typing.overload", "typing_extensions.overload"}:
+        return "overload-declaration"
+    if "abc.abstractmethod" in decorators:
+        return "abstract-declaration"
+    if protocol_method:
+        return "protocol-declaration"
+    return None

package/dist/python-analyzer.d.ts

@@ -0,0 +1,21 @@
+export interface PythonOptions {
+    project: string;
+    python?: string;
+    runId?: string;
+    auditId?: string;
+    include?: string[];
+    exclude?: string[];
+    testPath?: string[];
+    productionPath?: string[];
+    includeTests?: boolean;
+    includeGenerated?: boolean;
+    includeSupport?: boolean;
+    coverageJson?: string;
+    collectionManifest?: string;
+}
+export declare function pythonTarget(project: string): {
+    entryPoint: string;
+    root: string;
+    target: string;
+};
+export declare function analyzePython(options: PythonOptions): import("./evidence.js").Evidence;

package/dist/python-analyzer.js

@@ -0,0 +1,123 @@
+import { validateAsyncHelpers, validateAsyncScoring } from "./python-async-scoring.js";
+import { validateAsyncAdapters } from "./python-async-adapters.js";
+import { validateAsyncContext } from "./python-async-context.js";
+import { validateAsyncUsage } from "./python-async-usage.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { validateSourceFacts } from "#source-facts/contract.mjs";
+import { invocationIds } from "./evidence.js";
+import { pythonEvidence } from "./python-evidence.js";
+import { validateDuplication } from "./python-duplication.js";
+import { validateCoverage } from "./python-coverage.js";
+import { validateOperations } from "./python-error-operations.js";
+import { validateTransfers } from "./python-error-transfers.js";
+import { validateErrorContext } from "./python-error-context.js";
+import { validateErrorHandling } from "./python-error-handling.js";
+import { validateDecomposition } from "./python-decomposition.js";
+export function pythonTarget(project) {
+    const requested = path.resolve(project);
+    if (fs.lstatSync(requested).isSymbolicLink())
+        throw new Error("Linked Python entry points are not supported.");
+    // Python's collection receipts expand Windows short names with Path.resolve().
+    // Normalize at collection/analysis entry, never by consulting disk when reading historical evidence.
+    const entryPoint = fs.realpathSync.native(requested);
+    const directory = fs.statSync(entryPoint).isDirectory();
+    const manifest = path.basename(entryPoint) === "pyproject.toml";
+    if (!directory && !manifest && !/\.pyi?$/.test(entryPoint))
+        throw new Error("Python entry point must be a directory, pyproject.toml, .py, or .pyi file.");
+    const root = directory ? entryPoint : path.dirname(entryPoint);
+    return { entryPoint, root, target: manifest ? root : entryPoint };
+}
+export function analyzePython(options) {
+    const ids = invocationIds(options.runId, options.auditId);
+    const { target, root, entryPoint } = pythonTarget(options.project);
+    const script = fileURLToPath(new URL("./python/analysis.py", import.meta.url));
+    // Isolated stdlib interpreter; only the packaged analyzer directory is added to sys.path.
+    const bootstrap = "import runpy,sys; from pathlib import Path; script=sys.argv[1]; sys.path.insert(0,str(Path(script).parent)); sys.argv=sys.argv[1:]; runpy.run_path(script,run_name='__main__')";
+    const command = options.python ?? (process.platform === "win32" ? "py" : "python3");
+    if (options.python && !path.isAbsolute(options.python))
+        throw new Error("--python must be an absolute interpreter path.");
+    const args = [...(!options.python && process.platform === "win32" ? ["-3.12"] : []), "-I", "-S", "-B", "-c", bootstrap, script, target];
+    for (const [flag, items] of [["include", options.include], ["exclude", options.exclude], ["test-path", options.testPath], ["production-path", options.productionPath]])
+        for (const item of items ?? [])
+            args.push(`--${flag}`, item);
+    for (const [flag, enabled] of [["include-tests", options.includeTests], ["include-generated", options.includeGenerated], ["include-support", options.includeSupport]])
+        if (enabled)
+            args.push(`--${flag}`);
+    let asyncHelpers = null;
+    let asyncScoring = null;
+    let asyncAdapters = null;
+    let asyncContext = null;
+    let asyncReview = null;
+    let operations = null;
+    let transfers = null;
+    let context = null;
+    let errorHandling = null;
+    let facts = null;
+    let duplication = null;
+    let decomposition = null;
+    let coverage = null;
+    for (const [flag, value] of [["coverage-json", options.coverageJson], ["collection-manifest", options.collectionManifest]])
+        if (value)
+            args.push(`--${flag}`, path.resolve(value));
+    const subject = { root, entryPoint, name: path.basename(root), variant: "source" };
+    args.push("--run-id", ids.runId, "--audit-id", ids.auditId);
+    let error;
+    const result = spawnSync(command, args, { cwd: path.dirname(script), encoding: "utf8", windowsHide: true, timeout: 1_800_000, maxBuffer: 128 * 1024 * 1024 });
+    try {
+        if (result.error)
+            throw new Error(`Python 3.12 could not run: ${result.error.message}`);
+        if (result.status !== 0 && result.status !== 2)
+            throw new Error(`Python exited ${result.status}: ${result.stderr.slice(0, 2000)}`);
+        if (!result.stdout.trim())
+            throw new Error(`Python emitted no facts (exit ${result.status}): ${result.stderr.slice(0, 2000)}`);
+        const parsed = JSON.parse(result.stdout);
+        validateSourceFacts(parsed.sourceFacts);
+        validateDuplication(parsed.duplication, parsed.sourceFacts, subject, ids);
+        validateCoverage(parsed.coverageReview, parsed.sourceFacts, subject, ids);
+        validateDecomposition(parsed.decomposition, parsed.sourceFacts, subject, ids);
+        validateErrorHandling(parsed.errorHandlingReview, parsed.sourceFacts, subject, ids);
+        validateErrorContext(parsed.errorHandlingContext, parsed.errorHandlingReview);
+        validateTransfers(parsed.errorHandlingTransfers, parsed.errorHandlingContext);
+        validateOperations(parsed.errorHandlingOperations, parsed.errorHandlingTransfers);
+        validateAsyncUsage(parsed.asyncUsageReview, parsed.sourceFacts, subject, ids, parsed.decomposition);
+        validateAsyncContext(parsed.asyncContextReview, parsed.asyncUsageReview);
+        validateAsyncAdapters(parsed.asyncAdapterReview, parsed.asyncUsageReview, parsed.asyncContextReview);
+        validateAsyncHelpers(parsed.asyncHelperReview, parsed.asyncUsageReview, parsed.asyncContextReview, parsed.asyncAdapterReview);
+        validateAsyncScoring(parsed.asyncScoring, parsed.asyncHelperReview, parsed.asyncUsageReview);
+        asyncHelpers = parsed.asyncHelperReview;
+        asyncScoring = parsed.asyncScoring;
+        asyncAdapters = parsed.asyncAdapterReview;
+        asyncContext = parsed.asyncContextReview;
+        asyncReview = parsed.asyncUsageReview;
+        operations = parsed.errorHandlingOperations;
+        transfers = parsed.errorHandlingTransfers;
+        context = parsed.errorHandlingContext;
+        errorHandling = parsed.errorHandlingReview;
+        decomposition = parsed.decomposition;
+        facts = parsed.sourceFacts;
+        duplication = parsed.duplication;
+        coverage = parsed.coverageReview;
+        if ((result.status === 0) !== (facts.status === "complete" && duplication.status === "complete" && coverage.status === "complete" && decomposition.status === "complete" && errorHandling.status === "complete" && context.status === "complete" && transfers.status === "complete" && operations.status === "complete" && asyncReview.status === "complete" && asyncContext.status === "complete" && asyncAdapters.status === "complete" && asyncHelpers.status === "complete" && asyncScoring.status === "complete"))
+            throw new Error("Python exit status and facts disagree.");
+    }
+    catch (failure) {
+        asyncHelpers = null;
+        asyncScoring = null;
+        asyncAdapters = null;
+        asyncContext = null;
+        asyncReview = null;
+        operations = null;
+        transfers = null;
+        context = null;
+        errorHandling = null;
+        facts = null;
+        decomposition = null;
+        duplication = null;
+        coverage = null;
+        error = failure instanceof Error ? failure.message : String(failure);
+    }
+    return pythonEvidence(facts, subject, ids, error, duplication, coverage, decomposition, errorHandling, context, transfers, operations, asyncReview, asyncContext, asyncAdapters, asyncHelpers, asyncScoring);
+}

package/dist/python-async-adapters.d.ts

@@ -0,0 +1,67 @@
+import { type Extent, type Reference, type PythonAsyncContext } from "./python-async-context.js";
+import type { PythonAsyncUsage } from "./python-async-usage.js";
+export declare const asyncAdaptersPolicy = "python/async-callback-adapters-review-v1";
+interface Expression extends Extent {
+    kind: string;
+    shape: string;
+}
+interface Partial {
+    status: string;
+    importTarget: string;
+    construction: Extent;
+    argumentLayout: string;
+    callback: (Expression & {
+        reference: Reference;
+    }) | null;
+    boundPositionalExpressions: Expression[] | null;
+    keywordExpressions: {
+        name: string | null;
+        unpacking: boolean;
+        value: Expression;
+    }[];
+}
+interface PartialLink {
+    status: string;
+    reason?: string;
+    definition?: null;
+    name?: string;
+    assignment?: Extent;
+    constructionCallId?: string;
+    partial?: Partial;
+}
+interface DecoratorLink {
+    status: string;
+    reason?: string;
+    importTarget?: string;
+    definition: (Extent & {
+        ownerId: string;
+        file: string;
+        member: string;
+        functionKind: string;
+    }) | null;
+    decorator?: Extent & {
+        form: string;
+        options: {
+            name: string;
+            value: boolean;
+        }[];
+    };
+}
+interface AdapterCall {
+    callId: string;
+    executionContext: string;
+    partialConstruction: Partial | null;
+    partialCallee: PartialLink;
+    decoratedCallee: DecoratorLink;
+    callbackPartial: PartialLink | null;
+    callbackDecorator: DecoratorLink | null;
+}
+interface AdapterOwner extends Omit<PythonAsyncContext["functions"][number], "calls"> {
+    calls: AdapterCall[];
+}
+export interface PythonAsyncAdapters extends Omit<PythonAsyncContext, "functions"> {
+    functions: AdapterOwner[];
+}
+/** Internal consistency checks against validated source evidence, not AST remeasurement or authentication. */
+export declare function validateAsyncAdapters(value: unknown, base: PythonAsyncUsage, context: PythonAsyncContext): asserts value is PythonAsyncAdapters;
+export {};

package/dist/python-async-adapters.js

@@ -0,0 +1,197 @@
+import { isDeepStrictEqual } from "node:util";
+import { hash } from "./evidence.js";
+import { fingerprint } from "./python-error-context.js";
+import { before, contains, extent, keys, reference } from "./python-async-context.js";
+export const asyncAdaptersPolicy = "python/async-callback-adapters-review-v1";
+const locationKeys = ["line", "column", "endLine", "endColumn"];
+const partialReasons = ["not-a-name-or-matched-partial", "comprehension-local-binding", "reflective-or-cross-scope-binding",
+    "deferred-execution-context", "not-a-unique-same-owner-binding", "no-direct-assignment-before-use", "not-a-matched-partial-assignment", "unresolved-argument-layout"];
+const decoratorReasons = ["non-name-reference", "comprehension-local-binding", "reflective-or-cross-scope-binding",
+    "rebound-or-ambiguous-name", "no-direct-definition-before-reference", "unsupported-decorated-definition",
+    "unmatched-decorator-import", "unsupported-decorator-arguments", "definition-outside-selected-owners", "no-local-definition"];
+const nonempty = (v) => typeof v === "string" && v.trim().length > 0;
+const path = (v) => typeof v === "string" && /^[\p{ID_Start}_][\p{ID_Continue}]*(\.[\p{ID_Start}_][\p{ID_Continue}]*)*$/u.test(v);
+function check(condition, message) {
+    if (!condition)
+        throw new Error(`Invalid Python async adapter evidence: ${message}.`);
+}
+function location(value) { keys(value, locationKeys); extent(value); }
+function sameExtent(a, b) { return locationKeys.every(key => a[key] === b[key]); }
+function expression(value, container, extra = []) {
+    keys(value, [...locationKeys, "kind", "shape", ...extra]);
+    extent(value);
+    check(contains(container, value), "expression outside construction");
+    const kinds = ["Name", "Attribute", "Call", "Subscript", "Lambda", "Constant", "Starred", "BoolOp", "NamedExpr", "BinOp", "UnaryOp", "IfExp", "Dict", "Set", "ListComp", "SetComp", "DictComp", "GeneratorExp", "Await", "Yield", "YieldFrom", "Compare", "FormattedValue", "JoinedStr", "List", "Tuple"];
+    check(kinds.includes(value.kind), "unknown expression kind");
+    const expected = { Name: ["name"], Attribute: ["attribute-path", "attribute-on-expression"], Call: ["call-result"], Subscript: ["subscript"], Lambda: ["lambda"] }[value.kind] ?? ["other-expression"];
+    check(expected.includes(value.shape), "expression kind/shape mismatch");
+}
+function construction(value, call, owner, owners) {
+    keys(value, ["status", "importTarget", "construction", "argumentLayout", "callback", "boundPositionalExpressions", "keywordExpressions"]);
+    check(value.status === "partial-construction-syntax" && value.importTarget === "functools.partial" && call.binding.target === value.importTarget, "unmatched partial constructor");
+    location(value.construction);
+    check(sameExtent(value.construction, call), "construction extent mismatch");
+    check(Array.isArray(value.keywordExpressions), "keyword collection required");
+    if (value.argumentLayout === "unresolved") {
+        check(value.callback === null && value.boundPositionalExpressions === null, "unresolved argument layout must withhold callback");
+    }
+    else {
+        check(value.argumentLayout === "first-positional-callback" && value.callback && value.callback.kind !== "Starred" && Array.isArray(value.boundPositionalExpressions), "invalid callback layout");
+        const callback = value.callback;
+        expression(callback, call, ["reference"]);
+        const r = callback.reference;
+        if (r.status === "import-spelling")
+            check(path(r.target) && ["Name", "Attribute"].includes(callback.kind), "invalid callback import spelling");
+        reference(r, r.status === "local-definition" ? r.definition?.member.split(".").at(-1) ?? null : null, r.status === "import-spelling" ? r.target : null, callback.kind, { ...call, ...callback }, owner, owners, "");
+        let previous = callback;
+        for (const arg of value.boundPositionalExpressions) {
+            expression(arg, call);
+            check(before(previous, arg), "positional arguments out of order");
+            previous = arg;
+        }
+    }
+    let previousKeyword = null;
+    for (const kw of value.keywordExpressions) {
+        keys(kw, ["name", "unpacking", "value"]);
+        check(kw.name === null || path(kw.name) && !kw.name.includes("."), "invalid keyword name");
+        check(kw.unpacking === (kw.name === null), "keyword unpacking mismatch");
+        expression(kw.value, call);
+        check(!previousKeyword || before(previousKeyword, kw.value), "keywords out of order");
+        previousKeyword = kw.value;
+    }
+}
+function unresolvedLink(value, reasons) {
+    keys(value, ["status", "reason", "definition"]);
+    check(value.status === "unresolved" && value.definition === null && reasons.includes(value.reason), "invalid unresolved link");
+}
+function partialLink(value, use, owner, calls, rows, kind, spelling, bindingReason) {
+    if (kind === "Name" && ["comprehension-local-binding", "reflective-or-cross-scope-binding"].includes(bindingReason))
+        check(value.status === "unresolved" && value.reason === bindingReason, "partial binding veto lost");
+    if (value.status === "unresolved") {
+        unresolvedLink(value, partialReasons);
+        return;
+    }
+    const stored = value.status === "stored-partial-syntax";
+    keys(value, stored ? ["status", "name", "assignment", "constructionCallId", "partial"] : ["status", "constructionCallId", "partial"]);
+    check(stored || value.status === "inline-partial-syntax", "unsupported partial link");
+    const call = calls.get(value.constructionCallId), original = rows.get(value.constructionCallId)?.partialConstruction;
+    check(call && original && isDeepStrictEqual(value.partial, original) && value.constructionCallId === fingerprint([owner.id, original.construction]), "missing or inconsistent construction link");
+    if (stored) {
+        check(kind === "Name" && value.name === spelling && use.executionContext === "async-body" && call.executionContext === "async-body" && !call.directlyAwaited && original.argumentLayout === "first-positional-callback", "invalid stored partial context");
+        location(value.assignment);
+        check(value.assignment.line >= owner.line && value.assignment.endLine <= owner.endLine && contains(value.assignment, call) && before(value.assignment, use), "invalid partial assignment/source order");
+    }
+    else
+        check(kind === "Call" && call.id !== use.id && contains(use, call) && use.executionContext === call.executionContext, "invalid inline partial context");
+}
+function decoratorLink(value, use, owner, owners, kind, spelling, bindingReason, old) {
+    if (kind === "Name" && ["comprehension-local-binding", "reflective-or-cross-scope-binding"].includes(bindingReason))
+        check(value.status === "unresolved" && value.reason === bindingReason, "decorator binding veto lost");
+    if (value.status === "unresolved") {
+        unresolvedLink(value, decoratorReasons);
+        return;
+    }
+    keys(value, ["status", "importTarget", "definition", "decorator"]);
+    check(value.status === "decorated-wrapper-syntax" && value.importTarget === "asgiref.sync.sync_to_async" && kind === "Name" &&
+        old?.status === "unresolved" && old.reason === "decorated-definition", "unsupported decorated reference");
+    const d = value.definition;
+    keys(d, [...locationKeys, "ownerId", "file", "member", "functionKind"]);
+    extent(d);
+    const selected = owners.get(d.ownerId);
+    check(selected && selected.functionKind === "FunctionDef" && d.functionKind === "FunctionDef" && d.file === owner.file && d.file === selected.file && d.member === selected.member &&
+        d.line === selected.line && d.endLine === selected.endLine && spelling === d.member.split(".").at(-1) &&
+        d.ownerId === hash(`${d.file}|${d.line}|${d.column}|FunctionDef`) && before(d, use), "decorated definition mismatch");
+    const decorator = value.decorator;
+    keys(decorator, [...locationKeys, "form", "options"]);
+    extent(decorator);
+    check(before(decorator, d) && ["bare", "factory"].includes(decorator.form) && Array.isArray(decorator.options) &&
+        decorator.options.length <= (decorator.form === "bare" ? 0 : 1), "invalid decorator header");
+    for (const option of decorator.options) {
+        keys(option, ["name", "value"]);
+        check(option.name === "thread_sensitive" && typeof option.value === "boolean", "unsupported decorator option");
+    }
+}
+function validateCall(row, call, owner, owners, calls, rows, old) {
+    keys(row, ["callId", "executionContext", "partialConstruction", "partialCallee", "decoratedCallee", "callbackPartial", "callbackDecorator"]);
+    check(row.callId === call.id && row.executionContext === call.executionContext, "call identity/context mismatch");
+    if (call.binding.target === "functools.partial") {
+        check(row.partialConstruction, "missing partial construction");
+        construction(row.partialConstruction, call, owner, owners);
+    }
+    else
+        check(row.partialConstruction === null, "unexpected partial construction");
+    const kind = old.shape === "name" ? "Name" : old.shape === "call-result" ? "Call" : "Other";
+    partialLink(row.partialCallee, call, owner, calls, rows, kind, call.binding.syntax, call.binding.reason);
+    decoratorLink(row.decoratedCallee, call, owner, owners, kind, call.binding.syntax, call.binding.reason, old.localCallee);
+    let use = call;
+    if (old.storedWrapper?.status === "stored-wrapper-syntax")
+        use = calls.get(old.storedWrapper.definition.constructionCallId);
+    const callback = use.callback;
+    if (!old.callback) {
+        check(row.callbackPartial === null && row.callbackDecorator === null, "unexpected callback adapter");
+        return;
+    }
+    check(callback?.binding && row.callbackPartial && row.callbackDecorator, "missing callback adapter");
+    partialLink(row.callbackPartial, use, owner, calls, rows, callback.kind, callback.binding.syntax, callback.binding.reason);
+    decoratorLink(row.callbackDecorator, use, owner, owners, callback.kind, callback.binding.syntax, callback.binding.reason, old.callback.reference);
+    if (use !== call) {
+        check(isDeepStrictEqual(row.callbackPartial, rows.get(use.id)?.callbackPartial) && isDeepStrictEqual(row.callbackDecorator, rows.get(use.id)?.callbackDecorator), "stored wrapper callback differs from construction");
+    }
+    if (call.category === "offload-wrapped-invocation") {
+        const inner = [...calls.values()].find(c => c.category === "offload-wrapper-construction" && c.line === call.line && c.column === call.column && contains(call, c) && c.id !== call.id);
+        check(inner && isDeepStrictEqual(row.callbackPartial, rows.get(inner.id)?.callbackPartial) && isDeepStrictEqual(row.callbackDecorator, rows.get(inner.id)?.callbackDecorator), "immediate wrapper callback differs from construction");
+    }
+}
+function counts(rows) {
+    const eligible = rows.filter(row => row.status === "observed"), calls = eligible.flatMap(row => row.calls);
+    return { selectedFunctions: rows.length, asyncFunctions: eligible.length, excludedSynchronousFunctions: rows.length - eligible.length,
+        availability: eligible.length ? "available" : "unavailable", contexts: Object.fromEntries(["async-body", "deferred-generator-body"].map(context => {
+            const selected = calls.filter(call => call.executionContext === context);
+            const links = (field, statuses) => selected.filter(call => call[field] && statuses.includes(call[field].status)).length;
+            return [context, eligible.length ? { callExpressions: selected.length,
+                    partialConstructions: links("partialConstruction", ["partial-construction-syntax"]),
+                    partialCalleeReferences: links("partialCallee", ["inline-partial-syntax", "stored-partial-syntax"]),
+                    partialCallbackReferences: links("callbackPartial", ["inline-partial-syntax", "stored-partial-syntax"]),
+                    decoratedCalleeReferences: links("decoratedCallee", ["decorated-wrapper-syntax"]),
+                    decoratedCallbackReferences: links("callbackDecorator", ["decorated-wrapper-syntax"]) } : null];
+        })) };
+}
+/** Internal consistency checks against validated source evidence, not AST remeasurement or authentication. */
+export function validateAsyncAdapters(value, base, context) {
+    keys(value, ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "policy", "configuration", "configurationFingerprint", "subject", "selection", "sourceFactsProducer", "sourceFactsPolicy", "asyncRowsSha256", "status", "diagnostics", "functions", "summary", "scope"]);
+    const r = value;
+    check(r.schemaVersion === 1 && r.artifactKind === "experimental-python-async-callback-adapters-review" && r.policy === asyncAdaptersPolicy &&
+        isDeepStrictEqual(r.producer, { name: "codemetrics-ai/python-async-callback-adapters", version: "0.1.0-experimental" }), "unsupported producer/policy");
+    for (const key of ["runId", "auditId", "subject", "selection", "sourceFactsProducer", "sourceFactsPolicy"])
+        check(isDeepStrictEqual(r[key], base[key]), "invocation/source mismatch");
+    const configuration = { policy: asyncAdaptersPolicy, asyncConfigurationFingerprint: base.configurationFingerprint };
+    check(isDeepStrictEqual(r.configuration, configuration) && r.configurationFingerprint === fingerprint(configuration) && r.asyncRowsSha256 === fingerprint(base.functions), "configuration/original rows mismatch");
+    check(nonempty(r.scope) && typeof r.generatedAtUtc === "string" && Number.isFinite(Date.parse(r.generatedAtUtc)), "scope/time required");
+    check(Array.isArray(r.functions) && Array.isArray(r.diagnostics), "collections required");
+    for (const d of r.diagnostics) {
+        keys(d, ["code", "message"]);
+        check(d.code === "async-adapter-analysis" && nonempty(d.message), "invalid diagnostic");
+    }
+    if (r.status === "incomplete") {
+        check(r.diagnostics.length > 0 && r.functions.length === 0 && r.summary === null, "incomplete report must withhold rows");
+        return;
+    }
+    check(r.status === "complete" && base.status === "complete" && !r.diagnostics.length && r.functions.length === base.functions.length, "status/owner population mismatch");
+    // A context-only failure can coexist with valid adapter syntax, but cannot restore a score.
+    const owners = new Map(base.functions.map(row => [row.id, row]));
+    for (let i = 0; i < r.functions.length; i++) {
+        const row = r.functions[i], owner = base.functions[i];
+        keys(row, ["id", "file", "member", "line", "endLine", "population", "sourceSha256", "status", "reason", "disposition", "calls"]);
+        for (const key of ["id", "file", "member", "line", "endLine", "population", "sourceSha256", "status", "reason", "disposition"])
+            check(row[key] === owner[key], "owner metadata/order mismatch");
+        const original = owner.measurement?.calls ?? [];
+        check(Array.isArray(row.calls) && row.calls.length === original.length, "call population mismatch");
+        const calls = new Map(original.map(call => [call.id, call])), rows = new Map(row.calls.map(call => [call.callId, call]));
+        check(context.status === "complete" || !row.calls.length, "complete adapter calls require validated context");
+        for (let j = 0; j < row.calls.length; j++)
+            validateCall(row.calls[j], original[j], owner, owners, calls, rows, context.functions[i].calls[j]);
+    }
+    const expected = { ...counts(r.functions), populations: Object.fromEntries([...new Set(r.functions.map(row => row.population))].sort()
+            .map(population => [population, counts(r.functions.filter(row => row.population === population))])) };
+    check(isDeepStrictEqual(r.summary, expected), "summary mismatch");
+}

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

@@ -0,0 +1,73 @@
+import type { PythonAsyncUsage } from "./python-async-usage.js";
+export declare const asyncContextPolicy = "python/async-call-context-review-v1";
+type Owner = PythonAsyncUsage["functions"][number];
+type Call = NonNullable<Owner["measurement"]>["calls"][number];
+export interface Extent {
+    line: number;
+    column: number;
+    endLine: number;
+    endColumn: number;
+}
+interface Definition extends Extent {
+    ownerId: string;
+    file: string;
+    member: string;
+    functionKind: string;
+}
+interface WrapperDefinition {
+    name: string;
+    assignment: Extent;
+    constructionCallId: string;
+    construction: Extent;
+    importTarget: string;
+}
+export interface Reference {
+    status: string;
+    reason: string;
+    target?: string;
+    definition: Definition | null;
+}
+interface Wrapper {
+    status: string;
+    reason: string;
+    definition: WrapperDefinition | null;
+}
+interface Callback {
+    kind: string;
+    evaluation: string;
+    reference: Reference;
+}
+interface ContextCall {
+    callId: string;
+    executionContext: string;
+    shape: string;
+    unresolvedReason: string | null;
+    localCallee: Reference | null;
+    storedWrapper: Wrapper | null;
+    callback: Callback | null;
+}
+interface ContextOwner {
+    id: string;
+    file: string;
+    member: string;
+    line: number;
+    endLine: number;
+    population: string;
+    sourceSha256: string;
+    status: string;
+    reason: string | null;
+    disposition: string;
+    calls: ContextCall[];
+}
+export interface PythonAsyncContext extends Omit<PythonAsyncUsage, "functions"> {
+    asyncRowsSha256: string;
+    functions: ContextOwner[];
+}
+export declare function keys(value: unknown, names: string[]): void;
+export declare const before: (a: Extent, b: Extent) => boolean;
+export declare const contains: (a: Extent, b: Extent) => boolean;
+export declare function extent(value: Extent): void;
+export declare function reference(value: Reference, spelling: string | null, target: string | null, kind: string, use: Call, owner: Owner, owners: Map<string, Owner>, bindingReason: string): void;
+/** Check consistency against validated async evidence; not independent AST resolution or authentication. */
+export declare function validateAsyncContext(value: unknown, base: PythonAsyncUsage): asserts value is PythonAsyncContext;
+export {};