codemetrics-ai 0.4.0 → 0.6.0-preview.1

package/dist/python-async-context.js

@@ -0,0 +1,181 @@
+import { isDeepStrictEqual } from "node:util";
+import { hash } from "./evidence.js";
+import { fingerprint } from "./python-error-context.js";
+export const asyncContextPolicy = "python/async-call-context-review-v1";
+const referenceReasons = ["non-name-reference", "comprehension-local-binding", "reflective-or-cross-scope-binding",
+    "rebound-or-ambiguous-name", "not-a-direct-function-definition", "decorated-definition", "definition-not-before-reference",
+    "definition-outside-selected-owners", "no-local-definition"];
+const wrapperReasons = ["comprehension-local-binding", "reflective-or-cross-scope-binding", "deferred-execution-context",
+    "not-a-unique-same-owner-binding", "not-a-direct-wrapper-assignment", "assignment-not-before-use", "unmatched-wrapper-constructor", "unresolved-argument-layout"];
+const shapes = ["name", "attribute-path", "attribute-on-expression", "call-result", "subscript", "lambda", "other-expression"];
+const contexts = ["async-body", "deferred-generator-body"];
+function requireValue(condition, message) {
+    if (!condition)
+        throw new Error(`Invalid Python async context evidence: ${message}.`);
+}
+export 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 = (n) => Number.isSafeInteger(n) && n >= 0;
+const nonempty = (s) => typeof s === "string" && s.trim().length > 0;
+export const before = (a, b) => a.endLine < b.line || a.endLine === b.line && a.endColumn < b.column;
+export const contains = (a, b) => (a.line < b.line || a.line === b.line && a.column <= b.column) &&
+    (a.endLine > b.endLine || a.endLine === b.endLine && a.endColumn >= b.endColumn);
+export function extent(value) {
+    requireValue([value.line, value.column, value.endLine, value.endColumn].every(integer) && value.line > 0 &&
+        (value.endLine > value.line || value.endLine === value.line && value.endColumn > value.column), "invalid extent");
+}
+export function reference(value, spelling, target, kind, use, owner, owners, bindingReason) {
+    keys(value, value.status === "import-spelling" ? ["status", "reason", "target", "definition"] : ["status", "reason", "definition"]);
+    if (target !== null) {
+        requireValue(value.status === "import-spelling" && value.target === target && value.reason === "import-spelling-only" && value.definition === null, "callback import mismatch");
+        return;
+    }
+    if (kind === "Name" && ["comprehension-local-binding", "reflective-or-cross-scope-binding"].includes(bindingReason))
+        requireValue(value.status === "unresolved" && value.reason === bindingReason, "source binding veto must be preserved");
+    if (value.status === "unresolved") {
+        requireValue(value.definition === null && referenceReasons.includes(value.reason), "invalid unresolved reference");
+        requireValue(kind === "Name" || value.reason === "non-name-reference", "non-name reference cannot resolve locally");
+        return;
+    }
+    requireValue(value.status === "local-definition" && value.reason === "unique-direct-lexical-definition" && kind === "Name", "invalid local reference");
+    keys(value.definition, ["ownerId", "file", "member", "functionKind", "line", "column", "endLine", "endColumn"]);
+    const d = value.definition, selected = owners.get(d.ownerId);
+    extent(d);
+    requireValue(selected && selected.file === owner.file && d.file === selected.file && d.member === selected.member &&
+        d.line === selected.line && d.endLine === selected.endLine && d.functionKind === selected.functionKind &&
+        ["FunctionDef", "AsyncFunctionDef"].includes(d.functionKind) && spelling === d.member.split(".").at(-1), "unknown local definition");
+    requireValue(d.ownerId === hash(`${d.file}|${d.line}|${d.column}|${d.functionKind}`) && before(d, use), "definition identity or source order mismatch");
+}
+function wrapper(value, call, owner, calls) {
+    keys(value, ["status", "reason", "definition"]);
+    if (["comprehension-local-binding", "reflective-or-cross-scope-binding"].includes(call.binding.reason))
+        requireValue(value.status === "unresolved" && value.reason === call.binding.reason, "wrapper binding veto must be preserved");
+    if (value.status === "unresolved") {
+        requireValue(value.definition === null && wrapperReasons.includes(value.reason), "invalid unresolved wrapper");
+        return null;
+    }
+    requireValue(value.status === "stored-wrapper-syntax" && value.reason === "unique-direct-same-owner-assignment" && call.executionContext === "async-body", "invalid stored wrapper");
+    keys(value.definition, ["name", "assignment", "constructionCallId", "construction", "importTarget"]);
+    const d = value.definition;
+    keys(d.assignment, ["line", "column", "endLine", "endColumn"]);
+    extent(d.assignment);
+    keys(d.construction, ["line", "column", "endLine", "endColumn"]);
+    extent(d.construction);
+    const construction = calls.get(d.constructionCallId);
+    requireValue(d.name === call.binding.syntax && d.importTarget === "asgiref.sync.sync_to_async" &&
+        d.assignment.line >= owner.line && d.assignment.endLine <= owner.endLine && contains(d.assignment, d.construction) && before(d.assignment, call), "wrapper extent/name mismatch");
+    requireValue(construction && construction.category === "offload-wrapper-construction" && construction.executionContext === "async-body" &&
+        construction.callback && construction.callback.kind !== "unresolved-argument-layout" && !construction.directlyAwaited &&
+        d.constructionCallId === fingerprint([owner.id, d.construction]) &&
+        ["line", "column", "endLine", "endColumn"].every(key => construction[key] === d.construction[key]), "missing wrapper construction");
+    return construction;
+}
+function callContext(value, call, owner, owners, calls, rows) {
+    keys(value, ["callId", "executionContext", "shape", "unresolvedReason", "localCallee", "storedWrapper", "callback"]);
+    requireValue(value.callId === call.id && value.executionContext === call.executionContext && shapes.includes(value.shape), "call identity/context/shape mismatch");
+    const spelling = call.binding.syntax;
+    if (call.category === "offload-wrapped-invocation")
+        requireValue(value.shape === "call-result", "immediate wrapper shape mismatch");
+    else if (spelling !== null)
+        requireValue(value.shape === (spelling.includes(".") ? "attribute-path" : "name"), "callee shape differs from spelling");
+    else
+        requireValue(!["name", "attribute-path"].includes(value.shape), "dynamic callee cannot be a path");
+    requireValue(value.unresolvedReason === (call.binding.status === "unresolved" ? call.binding.reason : null), "unresolved reason mismatch");
+    let construction = null;
+    if (call.binding.status === "unresolved" && value.shape === "name") {
+        requireValue(value.localCallee !== null && value.storedWrapper !== null, "name context required");
+        reference(value.localCallee, spelling, null, "Name", call, owner, owners, call.binding.reason);
+        construction = wrapper(value.storedWrapper, call, owner, calls);
+        if (construction)
+            requireValue(value.localCallee.status === "unresolved" && value.localCallee.reason === "not-a-direct-function-definition", "wrapper is not a function definition");
+    }
+    else
+        requireValue(value.localCallee === null && value.storedWrapper === null, "non-name cannot claim local links");
+    const callback = construction?.callback ?? call.callback;
+    if (!callback || callback.kind === "unresolved-argument-layout") {
+        requireValue(value.callback === null, "unexpected callback context");
+        return;
+    }
+    keys(value.callback, ["kind", "evaluation", "reference"]);
+    requireValue(value.callback.kind === callback.kind && value.callback.evaluation === callback.evaluation, "callback expression mismatch");
+    reference(value.callback.reference, callback.binding.syntax, callback.binding.target, callback.kind, construction ?? call, owner, owners, callback.binding.reason);
+    if (construction)
+        requireValue(isDeepStrictEqual(value.callback, rows.get(construction.id)?.callback), "stored callback differs from construction");
+    if (call.category === "offload-wrapped-invocation") {
+        const inner = [...calls.values()].find(candidate => candidate.category === "offload-wrapper-construction" && candidate.line === call.line &&
+            candidate.column === call.column && contains(call, candidate) && candidate.id !== call.id);
+        requireValue(inner && isDeepStrictEqual(value.callback, rows.get(inner.id)?.callback), "immediate callback differs from construction");
+    }
+}
+const histogram = (values) => {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    return Object.fromEntries([...counts.entries()].sort(([a], [b]) => a.localeCompare(b, "en")));
+};
+function inventory(rows, context) {
+    const groups = new Map();
+    for (const row of rows)
+        for (const call of row.calls)
+            if (call.executionContext === context && call.unresolvedReason !== null) {
+                const key = `${call.unresolvedReason}\0${call.shape}`;
+                const group = groups.get(key) ?? { reason: call.unresolvedReason, shape: call.shape, callExpressions: 0, examples: [] };
+                group.callExpressions++;
+                if (group.examples.length < 3)
+                    group.examples.push({ ownerId: row.id, callId: call.callId });
+                groups.set(key, group);
+            }
+    return [...groups.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, group]) => group);
+}
+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(contexts.map(context => {
+            const selected = calls.filter(call => call.executionContext === context), unmatched = selected.filter(call => call.unresolvedReason !== null);
+            return [context, eligible.length ? { callExpressions: selected.length, unresolvedImportCallExpressions: unmatched.length,
+                    unresolvedReasons: histogram(unmatched.map(call => call.unresolvedReason)), unresolvedShapes: histogram(unmatched.map(call => call.shape)),
+                    unresolvedInventory: inventory(eligible, context), localCalleeLinks: selected.filter(call => call.localCallee?.status === "local-definition").length,
+                    storedWrapperInvocationLinks: selected.filter(call => call.storedWrapper?.status === "stored-wrapper-syntax").length,
+                    localCallbackReferenceLinks: selected.filter(call => call.callback?.reference.status === "local-definition").length } : null];
+        })) };
+}
+/** Check consistency against validated async evidence; not independent AST resolution or authentication. */
+export function validateAsyncContext(value, base) {
+    keys(value, ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "policy", "configuration", "configurationFingerprint", "subject", "selection", "sourceFactsProducer", "sourceFactsPolicy", "asyncRowsSha256", "status", "diagnostics", "functions", "summary", "scope"]);
+    const r = value;
+    requireValue(r.schemaVersion === 1 && r.artifactKind === "experimental-python-async-call-context-review" && r.policy === asyncContextPolicy &&
+        isDeepStrictEqual(r.producer, { name: "codemetrics-ai/python-async-call-context", version: "0.1.0-experimental" }), "unsupported producer/policy");
+    for (const key of ["runId", "auditId", "subject", "selection", "sourceFactsProducer", "sourceFactsPolicy"])
+        requireValue(isDeepStrictEqual(r[key], base[key]), "invocation or source provenance mismatch");
+    const configuration = { policy: asyncContextPolicy, asyncConfigurationFingerprint: base.configurationFingerprint, maxExamplesPerGroup: 3 };
+    requireValue(isDeepStrictEqual(r.configuration, configuration) && r.configurationFingerprint === fingerprint(configuration) &&
+        r.asyncRowsSha256 === fingerprint(base.functions), "configuration or original async rows mismatch");
+    requireValue(nonempty(r.scope) && typeof r.generatedAtUtc === "string" && Number.isFinite(Date.parse(r.generatedAtUtc)), "scope/time required");
+    requireValue(Array.isArray(r.functions) && Array.isArray(r.diagnostics), "collections required");
+    for (const d of r.diagnostics) {
+        keys(d, ["code", "message"]);
+        requireValue(d.code === "async-context-analysis" && nonempty(d.message), "invalid diagnostic");
+    }
+    if (r.status === "incomplete") {
+        requireValue(r.diagnostics.length > 0 && r.functions.length === 0 && r.summary === null, "incomplete report must withhold rows");
+        return;
+    }
+    requireValue(r.status === "complete" && base.status === "complete" && !r.diagnostics.length && r.functions.length === base.functions.length, "status/owner population mismatch");
+    const owners = new Map(base.functions.map(row => [row.id, row]));
+    for (let index = 0; index < r.functions.length; index++) {
+        const row = r.functions[index], owner = base.functions[index];
+        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"])
+            requireValue(row[key] === owner[key], "owner metadata/order mismatch");
+        const original = owner.measurement?.calls ?? [];
+        requireValue(Array.isArray(row.calls) && row.calls.length === original.length, "owned call population mismatch");
+        const calls = new Map(original.map(call => [call.id, call])), rows = new Map(row.calls.map(call => [call.callId, call]));
+        for (let i = 0; i < row.calls.length; i++)
+            callContext(row.calls[i], original[i], owner, owners, calls, rows);
+    }
+    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))])) };
+    requireValue(isDeepStrictEqual(r.summary, expected), "summary or inventory mismatch");
+}

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

@@ -0,0 +1,89 @@
+import { type Extent } from "./python-async-context.js";
+import type { PythonAsyncContext } from "./python-async-context.js";
+import type { PythonAsyncAdapters } from "./python-async-adapters.js";
+import type { PythonAsyncUsage } from "./python-async-usage.js";
+import { type Dimension } from "./evidence.js";
+export declare const asyncHelperPolicy = "python/async-local-helper-paths-review-v1";
+export declare const pythonAsyncPolicy = "python/async-blocking-owner-rate-v1";
+export declare const asyncIntentPolicy = "adjacent-simple-statement-declared-blocking-prose-v1";
+export declare const asyncLadder: {
+    percent: number;
+    inclusive: boolean;
+    score: number;
+}[];
+interface Step extends Extent {
+    ownerId: string;
+    callId: string;
+    file: string;
+    member: string;
+}
+interface Trace {
+    path: Step[];
+    executionContext: string;
+    status: string;
+    reason: string;
+    target: string | null;
+    targetOwnerId?: string;
+}
+interface HelperOwner {
+    id: string;
+    file: string;
+    member: string;
+    line: number;
+    population: string;
+    sourceSha256: string;
+    traces: Trace[];
+    disposition: string;
+}
+export interface PythonAsyncHelpers extends Omit<PythonAsyncUsage, "functions"> {
+    asyncRowsSha256: string;
+    functions: HelperOwner[];
+}
+interface Documentation {
+    file: string;
+    callId: string;
+    line: number;
+    text: string;
+}
+interface Observation extends Trace {
+    documentation: Documentation[];
+    classification: string;
+}
+interface Contribution extends Omit<HelperOwner, "traces" | "disposition"> {
+    eligible: boolean;
+    eligibilityReason: string;
+    affected: boolean;
+    observations: Observation[];
+    unresolvedPaths: Trace[];
+}
+export interface PythonAsyncScoring extends Omit<PythonAsyncHelpers, "asyncRowsSha256" | "functions"> {
+    helperRowsSha256: string;
+    functions: Contribution[];
+}
+/** Validate provenance, path/source identities and accounting; this is not independent AST replay. */
+export declare function validateAsyncHelpers(value: unknown, base: PythonAsyncUsage, context: PythonAsyncContext, adapters: PythonAsyncAdapters): asserts value is PythonAsyncHelpers;
+export declare function asyncOwnerScore(affected: number, eligible: number): number | null;
+export declare function asyncScoreSummary(rows: Contribution[]): {
+    availability: string;
+    eligibleOwners: number;
+    affectedOwners: number;
+    score: number | null;
+    affectedRate: {
+        numerator: number;
+        denominator: number;
+    } | null;
+    excludedOwnersByPopulation: {
+        [k: string]: number;
+    };
+    observationPathsByClassification: {
+        [k: string]: number;
+    };
+    distinctScoredSourceCalls: number;
+    ownersWithUnresolvedPaths: number;
+    unresolvedPathsByReason: {
+        [k: string]: number;
+    };
+};
+export declare function validateAsyncScoring(value: unknown, base: PythonAsyncHelpers, usage: PythonAsyncUsage): asserts value is PythonAsyncScoring;
+export declare function scorePythonAsync(dimension: Dimension, report: PythonAsyncScoring | null, complete: boolean): Dimension;
+export {};

package/dist/python-async-scoring.js

@@ -0,0 +1,249 @@
+import { isDeepStrictEqual } from "node:util";
+import { fingerprint } from "./python-error-context.js";
+import { keys, extent } from "./python-async-context.js";
+import { scored, hash } from "./evidence.js";
+import { firstMatch } from "./scoring-decision.js";
+export const asyncHelperPolicy = "python/async-local-helper-paths-review-v1";
+export const pythonAsyncPolicy = "python/async-blocking-owner-rate-v1";
+export const asyncIntentPolicy = "adjacent-simple-statement-declared-blocking-prose-v1";
+const locationKeys = ["line", "column", "endLine", "endColumn"];
+const identityKeys = ["id", "file", "member", "line", "population", "sourceSha256"];
+const contexts = ["async-body", "thread-helper-callback", "wrapper-callback-reference", "deferred-generator-body"];
+const blocking = ["time.sleep", "subprocess.run", "subprocess.call", "subprocess.check_call", "subprocess.check_output", "os.system", "urllib.request.urlopen"];
+export const asyncLadder = [
+    { percent: 1, inclusive: false, score: 10 }, { percent: 2, inclusive: false, score: 9 },
+    { percent: 5, inclusive: false, score: 8 }, { percent: 10, inclusive: true, score: 6 },
+    { percent: 15, inclusive: true, score: 4 }, { percent: 20, inclusive: true, score: 2 }
+];
+function check(condition, message) {
+    if (!condition)
+        throw new Error(`Invalid Python async scoring evidence: ${message}.`);
+}
+const histogram = (items) => {
+    const counts = {};
+    for (const item of items)
+        counts[item] = (counts[item] ?? 0) + 1;
+    return Object.fromEntries(Object.entries(counts).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+};
+const nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+const same = (a, b, message) => check(isDeepStrictEqual(a, b), message);
+const location = (step) => Object.fromEntries(locationKeys.map(key => [key, step[key]]));
+const commonKeys = ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "policy", "configuration", "configurationFingerprint", "subject", "selection", "sourceFactsProducer", "sourceFactsPolicy", "status", "diagnostics", "scope", "functions", "summary"];
+function envelope(report, base, policy, kind, producer, configuration) {
+    check(report.schemaVersion === 1 && report.artifactKind === kind && report.policy === policy, "unsupported policy/kind");
+    same(report.producer, { name: producer, version: "0.1.0-experimental" }, "producer mismatch");
+    for (const key of ["runId", "auditId", "subject", "selection", "sourceFactsProducer", "sourceFactsPolicy"])
+        same(report[key], base[key], "invocation/source mismatch");
+    same(report.configuration, configuration, "configuration mismatch");
+    check(report.configurationFingerprint === fingerprint(configuration), "configuration fingerprint mismatch");
+    check(nonempty(report.scope) && typeof report.generatedAtUtc === "string" && Number.isFinite(Date.parse(report.generatedAtUtc)), "scope/time required");
+    check(Array.isArray(report.functions) && Array.isArray(report.diagnostics), "collections required");
+    for (const diagnostic of report.diagnostics) {
+        keys(diagnostic, ["code", "message"]);
+        check(nonempty(diagnostic.code) && typeof diagnostic.message === "string", "invalid diagnostic");
+    }
+    if (report.status === "incomplete") {
+        check(report.diagnostics.length > 0 && !report.functions.length && report.summary === null, "incomplete report must withhold rows/score");
+        return false;
+    }
+    check(report.status === "complete" && base.status === "complete" && !report.diagnostics.length, "completion mismatch");
+    return true;
+}
+function helperCounts(rows) {
+    const traces = rows.flatMap(row => row.traces), candidates = traces.filter(row => row.status === "blocking-candidate");
+    return { asyncFunctions: rows.length, availability: rows.length ? "available" : "unavailable",
+        functionsWithDirectOrHelperCandidates: rows.length ? rows.filter(row => row.traces.some(trace => trace.status === "blocking-candidate" && trace.executionContext === "async-body")).length : null,
+        candidatePathsByContext: histogram(candidates.map(trace => trace.executionContext)),
+        unresolvedPathsByReason: histogram(traces.filter(trace => trace.status === "unresolved").map(trace => trace.reason)),
+        candidatePaths: candidates.length, localHelperLinks: traces.filter(trace => trace.status === "local-helper-link").length,
+        distinctBlockingSourceCalls: new Set(candidates.map(trace => trace.path.at(-1).callId)).size };
+}
+function validatePath(trace, row, owners, links) {
+    keys(trace, ["path", "executionContext", "status", "reason", "target", ...(trace.status === "local-helper-link" ? ["targetOwnerId"] : [])]);
+    check(contexts.includes(trace.executionContext) && nonempty(trace.reason), "invalid execution context/reason");
+    check(Array.isArray(trace.path) && trace.path.length > 0 && trace.path.length <= 4, "helper depth exceeded");
+    const used = new Set();
+    for (const [index, step] of trace.path.entries()) {
+        keys(step, ["ownerId", "callId", "file", "member", ...locationKeys]);
+        extent(step);
+        const owner = owners.get(step.ownerId);
+        check(owner && owner.file === row.file && step.file === owner.file && step.member === owner.member &&
+            step.line >= owner.line && step.endLine <= owner.endLine && !used.has(owner.id), "path owner/location mismatch");
+        used.add(owner.id);
+        check(step.callId === fingerprint([step.ownerId, location(step)]), "path call identity mismatch");
+        if (!index)
+            check(step.ownerId === row.id, "path must start at async owner");
+        else {
+            const prefix = trace.path.slice(0, index);
+            const link = links.get(fingerprint(prefix));
+            check(link?.targetOwnerId === step.ownerId && (trace.executionContext === link.executionContext || trace.executionContext === "deferred-generator-body" ||
+                link.executionContext === "async-body" && ["thread-helper-callback", "wrapper-callback-reference"].includes(trace.executionContext)), "missing or inconsistent helper path prefix");
+            check(owner.functionKind === "FunctionDef", "helper must be synchronous");
+        }
+    }
+    if (trace.status === "blocking-candidate")
+        check(blocking.includes(trace.target) && ["catalogue-import-spelling", "catalogue-callback-import-spelling"].includes(trace.reason), "invalid blocking catalogue observation");
+    else if (trace.status === "local-helper-link") {
+        const target = owners.get(trace.targetOwnerId);
+        check(trace.target === null && trace.reason === "bounded-lexical-definition" && target?.functionKind === "FunctionDef" &&
+            target.file === row.file && !used.has(target.id) && target.line < trace.path.at(-1).line && trace.path.length <= 3, "invalid local helper link");
+    }
+    else
+        check(trace.status === "unresolved" && trace.target === null, "invalid unresolved trace");
+}
+/** Validate provenance, path/source identities and accounting; this is not independent AST replay. */
+export function validateAsyncHelpers(value, base, context, adapters) {
+    keys(value, [...commonKeys, "asyncRowsSha256"]);
+    const report = value;
+    check(report.asyncRowsSha256 === fingerprint(base.functions), "async rows hash mismatch");
+    if (!envelope(report, base, asyncHelperPolicy, "experimental-python-async-helper-paths", "codemetrics-ai/python-async-helper-paths", { policy: asyncHelperPolicy, asyncConfigurationFingerprint: base.configurationFingerprint, maxHelperDepth: 3, maxSteps: 100000 }))
+        return;
+    const observed = base.functions.filter(owner => owner.status === "observed");
+    same(report.functions.map(row => row.id), observed.map(row => row.id), "async owner population/order mismatch");
+    const owners = new Map(base.functions.map(row => [row.id, row]));
+    let total = 0;
+    for (const row of report.functions) {
+        keys(row, [...identityKeys, "traces", "disposition"]);
+        const original = owners.get(row.id);
+        for (const key of identityKeys)
+            same(row[key], original[key], "owner provenance mismatch");
+        check(row.disposition === "review-only" && Array.isArray(row.traces), "invalid helper row");
+        total += row.traces.length;
+        check(total <= 200000, "trace budget exceeded");
+        const links = new Map(row.traces.filter(trace => trace.status === "local-helper-link").map(trace => [fingerprint(trace.path), trace]));
+        const unique = new Set();
+        const calls = new Map(original.measurement.calls.map(call => [call.id, call]));
+        const contextual = new Map(context.functions.find(owner => owner.id === row.id).calls.map(call => [call.callId, call]));
+        const adapted = new Map(adapters.functions.find(owner => owner.id === row.id).calls.map(call => [call.callId, call]));
+        for (const trace of row.traces) {
+            validatePath(trace, row, owners, links);
+            const identity = fingerprint(trace);
+            check(!unique.has(identity), "duplicate trace");
+            unique.add(identity);
+            const root = trace.path[0], call = calls.get(root.callId);
+            check(call && isDeepStrictEqual(location(root), location(call)), "unknown root call");
+            if (trace.path.length !== 1)
+                continue;
+            if (call.category === "blocking-call-candidate") {
+                check(trace.status === "blocking-candidate" && trace.target === call.binding.target && trace.executionContext === call.executionContext && trace.reason === "catalogue-import-spelling", "direct blocking observation changed");
+            }
+            else if (trace.status === "blocking-candidate") {
+                const old = contextual.get(call.id), adapter = adapted.get(call.id);
+                const partial = adapter.partialCallee.partial?.callback?.reference;
+                const callback = adapter.callbackPartial?.partial?.callback?.reference ?? old.callback?.reference;
+                const callbackMode = call.executionContext === "async-body" ? "thread-helper-callback" : call.executionContext;
+                check(trace.reason === "catalogue-callback-import-spelling" && [
+                    { reference: partial, mode: call.executionContext },
+                    { reference: callback, mode: call.category === "offload-wrapper-construction" ? "wrapper-callback-reference" : callbackMode }
+                ].some(item => item.reference?.status === "import-spelling" && item.reference.target === trace.target && item.mode === trace.executionContext), "callback catalogue observation has no matching reference/context");
+            }
+            else if (trace.status === "local-helper-link") {
+                const old = contextual.get(call.id), adapter = adapted.get(call.id);
+                const partial = adapter.partialCallee.partial?.callback?.reference;
+                const callback = adapter.callbackPartial?.partial?.callback?.reference ?? old.callback?.reference;
+                const callbackMode = call.executionContext === "async-body" ? "thread-helper-callback" : call.executionContext;
+                const references = [
+                    { reference: old.localCallee, mode: call.executionContext }, { reference: partial, mode: call.executionContext },
+                    { reference: adapter.decoratedCallee, mode: callbackMode },
+                    { reference: callback, mode: call.category === "offload-wrapper-construction" ? "wrapper-callback-reference" : callbackMode }
+                ];
+                check(references.some(item => item.reference?.definition?.ownerId === trace.targetOwnerId && item.mode === trace.executionContext), "root helper link has no prior source reference");
+            }
+        }
+        for (const call of calls.values())
+            if (call.category === "blocking-call-candidate")
+                check(row.traces.filter(trace => trace.path.length === 1 && trace.path[0].callId === call.id).length === 1, "missing direct blocking trace");
+            else if (call.category === "unresolved-call")
+                check(row.traces.some(trace => trace.path.length === 1 && trace.path[0].callId === call.id), "missing unresolved or linked root call");
+    }
+    const expected = { ...helperCounts(report.functions), populations: Object.fromEntries([...new Set(report.functions.map(row => row.population))].sort()
+            .map(population => [population, helperCounts(report.functions.filter(row => row.population === population))])) };
+    same(report.summary, expected, "helper summary mismatch");
+}
+export function asyncOwnerScore(affected, eligible) {
+    check(Number.isSafeInteger(affected) && Number.isSafeInteger(eligible) && affected >= 0 && affected <= eligible, "invalid owner counts");
+    if (!eligible)
+        return null;
+    for (const band of asyncLadder)
+        if (100 * affected < band.percent * eligible || band.inclusive && 100 * affected === band.percent * eligible)
+            return band.score;
+    return 0;
+}
+export function asyncScoreSummary(rows) {
+    const eligible = rows.filter(row => row.eligible), affected = eligible.filter(row => row.affected).length;
+    const observations = eligible.flatMap(row => row.observations), unresolved = eligible.flatMap(row => row.unresolvedPaths);
+    return { availability: eligible.length ? "available" : "unavailable", eligibleOwners: eligible.length, affectedOwners: affected,
+        score: asyncOwnerScore(affected, eligible.length), affectedRate: eligible.length ? { numerator: affected, denominator: eligible.length } : null,
+        excludedOwnersByPopulation: histogram(rows.filter(row => !row.eligible).map(row => row.population)),
+        observationPathsByClassification: histogram(observations.map(item => item.classification)),
+        distinctScoredSourceCalls: new Set(observations.filter(item => item.classification === "scored-signal").map(item => item.path.at(-1).callId)).size,
+        ownersWithUnresolvedPaths: eligible.filter(row => row.unresolvedPaths.length).length,
+        unresolvedPathsByReason: histogram(unresolved.map(item => item.reason)) };
+}
+export function validateAsyncScoring(value, base, usage) {
+    keys(value, [...commonKeys, "helperRowsSha256"]);
+    const report = value;
+    check(report.helperRowsSha256 === fingerprint(base.functions), "helper rows hash mismatch");
+    if (!envelope(report, base, pythonAsyncPolicy, "experimental-python-async-scoring", "codemetrics-ai/python-async-scoring", { policy: pythonAsyncPolicy, helperConfigurationFingerprint: base.configurationFingerprint, intentPolicy: asyncIntentPolicy,
+        maxSourceIndexNodes: 1000000, ladder: asyncLadder, population: "selected-production-async-implementations", unresolvedTreatment: "visible-without-deduction" }))
+        return;
+    same(report.functions.map(row => row.id), base.functions.map(row => row.id), "scoring owner population/order mismatch");
+    const owners = new Map(usage.functions.map(row => [row.id, row]));
+    for (const [index, row] of report.functions.entries()) {
+        keys(row, [...identityKeys, "eligible", "eligibilityReason", "affected", "observations", "unresolvedPaths"]);
+        const original = base.functions[index];
+        for (const key of identityKeys)
+            same(row[key], original[key], "scoring owner provenance mismatch");
+        check(row.eligible === (row.population === "production") && row.eligibilityReason === (row.eligible ? "production-async-implementation" : "nonproduction"), "scoring eligibility mismatch");
+        check(Array.isArray(row.observations), "observations required");
+        same(row.unresolvedPaths, original.traces.filter(trace => trace.status === "unresolved"), "unresolved evidence changed");
+        const candidates = original.traces.filter(trace => trace.status === "blocking-candidate");
+        check(row.observations.length === candidates.length, "candidate population mismatch");
+        for (const [at, observation] of row.observations.entries()) {
+            keys(observation, ["path", "executionContext", "status", "reason", "target", "documentation", "classification"]);
+            const { documentation, classification, ...trace } = observation;
+            same(trace, candidates[at], "candidate path changed");
+            check(Array.isArray(documentation), "documentation required");
+            const seen = new Set();
+            for (const item of documentation) {
+                keys(item, ["file", "callId", "line", "text"]);
+                const step = trace.path.find(part => part.callId === item.callId && part.file === item.file);
+                const owner = step && owners.get(step.ownerId);
+                check(owner && Number.isSafeInteger(item.line) && item.line > owner.line && item.line <= owner.endLine && nonempty(item.text), "documentation source mismatch");
+                check(/\b(blocking|synchronous|sync-over-async|sleep)\b/i.test(item.text) && /\b(intentional(ly)?|deliberate(ly)?|required|necessary|unavoidable)\b/i.test(item.text) &&
+                    !/\b(TODO|FIXME|HACK|XXX|not|never|avoid|remove|replace|shouldn't|mustn't|unnecessary)\b/i.test(item.text) && !/^(noqa\b|type:|pragma:|fmt:|pylint:|ruff:)/i.test(item.text), "documentation convention mismatch");
+                const key = fingerprint(item);
+                check(!seen.has(key), "duplicate rationale");
+                seen.add(key);
+            }
+            if (trace.executionContext !== "async-body")
+                check(!documentation.length && classification === "excluded-execution-context", "callback/deferred evidence cannot be scored");
+            else
+                check(classification === (documentation.length ? "documented-choice" : "scored-signal"), "classification mismatch");
+        }
+        check(row.affected === (row.eligible && row.observations.some(item => item.classification === "scored-signal")), "affected owner mismatch");
+    }
+    same(report.summary, asyncScoreSummary(report.functions), "async score/summary mismatch");
+}
+export function scorePythonAsync(dimension, report, complete) {
+    const scope = { id: pythonAsyncPolicy, coverage: "partial",
+        includes: ["selected-production-async-implementations", "blocking-import-catalogue", "bounded-eager-local-helpers", "documented-choice-exclusions", "explicit-unresolved-paths"],
+        excludes: ["test-support-generated-scoring", "runtime-performance", "complete-blocking-detection", "resolved-receiver-types", "cross-file-call-graphs", "business-correctness"] };
+    const details = complete && report?.status === "complete" ? asyncScoreSummary(report.functions) : null;
+    if (details?.score === null || !details)
+        return { ...dimension, scope,
+            status: complete ? "skipped" : "failed", basis: complete ? "Async/Blocking Usage unavailable: no selected production async implementations." : "Python analysis incomplete; no async score is usable." };
+    const findings = report.functions.filter(row => row.observations.length).map(row => ({
+        category: "pythonAsyncBlockingReview", ruleId: pythonAsyncPolicy, fingerprint: hash(`${pythonAsyncPolicy}:${row.id}`),
+        severity: row.affected ? "warning" : "info", confidence: "medium", file: row.file,
+        line: row.observations[0].path[0].line, member: row.member,
+        message: row.affected ? "Supported blocking-call syntax appears in this async owner's eager path. Inspect required behavior and source context before changing execution."
+            : "Blocking-call syntax is retained as excluded context or documented intent; no score deduction.",
+        observations: { ownerId: row.id, population: row.population, eligible: row.eligible, affected: row.affected,
+            paths: row.observations, classification: row.affected ? "actionableSignal" : "reviewLead" }
+    }));
+    const decision = firstMatch(pythonAsyncPolicy, { eligibleOwners: details.eligibleOwners, affectedOwners: details.affectedOwners,
+        ownersWithUnresolvedPaths: details.ownersWithUnresolvedPaths, unresolvedPathsByReason: details.unresolvedPathsByReason,
+        ladder: asyncLadder, counting: "distinct-selected-production-async-owner", intentPolicy: asyncIntentPolicy }, [{ id: "affectedOwnerRate", condition: "nonempty selected production async implementation population", matched: true, score: details.score, categories: ["pythonAsyncBlockingReview"] }]);
+    return { ...dimension, ...scored(decision, "Partial static blocking-catalogue usage score. Unresolved paths are not nonblocking evidence; score does not measure runtime performance.", findings, details, finding => finding.observations.affected === true), scope };
+}

package/dist/python-async-usage.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 asyncUsagePolicy = "python/async-owned-calls-review-v1";
+interface Binding {
+    syntax: string | null;
+    target: string | null;
+    status: string;
+    reason: string;
+}
+interface Callback {
+    kind: string;
+    binding: Binding | null;
+    evaluation?: string;
+}
+interface Call {
+    id: string;
+    line: number;
+    column: number;
+    endLine: number;
+    endColumn: number;
+    executionContext: string;
+    category: string;
+    binding: Binding;
+    directlyAwaited: boolean;
+    callback: Callback | null;
+    disposition: string;
+}
+interface Owner {
+    id: string;
+    file: string;
+    member: string;
+    line: number;
+    endLine: number;
+    population: string;
+    sourceSha256: string;
+    functionKind: string;
+    disposition: string;
+    status: string;
+    reason: string | null;
+    measurement: {
+        kind: string;
+        awaitExpressions: Record<string, number>;
+        calls: Call[];
+    } | null;
+}
+export interface PythonAsyncUsage extends Omit<PythonDecomposition, "configuration" | "functions"> {
+    configuration: Record<string, unknown>;
+    functions: Owner[];
+}
+/** Validate identity, catalogue coherence and accounting, not runtime resolution or independent AST semantics. */
+export declare function validateAsyncUsage(value: unknown, facts: SourceFacts, subject: Evidence["subject"], ids: {
+    runId: string;
+    auditId: string;
+}, decomposition: PythonDecomposition): asserts value is PythonAsyncUsage;
+export {};