@kernlang/python 4.0.1-canary.224.1.1a92ac0a → 4.1.0

package/dist/codegen-body-python.d.ts

@@ -171,6 +171,16 @@ interface BodyEmitContext {
     /** Depth of nested `finally` blocks. Propagation from finally would
      *  override pending control flow, so it gets a finally-specific error. */
     finallyDepth: number;
+    /** Error-substrate Slice 1 — names currently bound by an enclosing
+     *  `except Exception as <name>:` (a body-statement `catch name=<name>`). A
+     *  caught binding's `.message` read lowers to `str(<name>)` (Python exceptions
+     *  have no `.message` attribute; `str(Exception("x"))` === TS
+     *  `Error("x").message`). Populated on catch-body entry, restored on exit
+     *  (a `Set`, so nested catches with distinct names stack; a re-bound same name
+     *  is idempotent). Only `.message` is rewritten — `.name`/`.stack`/etc. are NOT
+     *  in the parity domain and emit verbatim (the runner abstains on them, so they
+     *  never reach a certified differential row). */
+    caughtBindings: Set<string>;
     standaloneExpression: boolean;
     /** When true, helper-dependent JS value→string coercion is emitted
      *  (`__kern_add`, `_kern_fmt`-wrapped templates, the `_KERN_UNDEFINED`

package/dist/codegen-body-python.js

@@ -40,7 +40,7 @@
  *  threads a `indent` string. The propagation hoist embeds its own 4-space
  *  relative indent on the `return __k_tN` line; the wrapper prepends the
  *  surrounding indent so the post-emit result nests correctly. */
-import { applyTemplate, classifyRegexLiteralIndexReadFailClose, classifyRegexLiteralMemberReadFailClose, emitStringKeyArray, expandRegexIFold, instanceofRhsPythonType, instanceofRhsRejectReasonForName, isHostNamespaceRoot, isPostfixMutationOperator, isSupportedAssignOperator, isZeroWidthCapableRegex, KERN_STDLIB_MODULES, lookupStdlibCall, lookupStdlibProperty, lowerRegexAnchorsPython, lowerRegexNamedGroupsPython, needsArgParens, needsBinaryParens, normalizeRegexClasses, parseExpression, parseKeys, REGEX_EXEC_FAILCLOSE, REGEX_HOST_REGEXP_FAILCLOSE, REGEX_MATCHALL_NO_G_FAILCLOSE, REGEX_NONLITERAL_FAILCLOSE, REGEX_REPLACE_NONLITERAL_REPL_FAILCLOSE, REGEX_REPLACEALL_NO_G_FAILCLOSE, REGEX_SPLIT_LIMIT_FAILCLOSE, REGEX_SPLIT_ZEROWIDTH_FAILCLOSE, REGEX_TEST_G_FAILCLOSE, regexAstralFailMessage, regexCaptureMeta, regexIFoldFailMessage, regexLiteralReceiverIR, regexMethodRegexArgIdent, scanRegexAstral, suggestStdlibMethod, translateReplStringToPython, unmappedHostNamespaceMessage, unwrapTransparentReceiverIR, validateRegexNamedGroupsPortable, } from '@kernlang/core';
+import { applyTemplate, assertNoDecimalOperator, classifyRegexLiteralIndexReadFailClose, classifyRegexLiteralMemberReadFailClose, decimalBareConstructionFailMessage, emitStringKeyArray, expandRegexIFold, instanceofRhsPythonType, instanceofRhsRejectReasonForName, isHostNamespaceRoot, isPostfixMutationOperator, isSupportedAssignOperator, isZeroWidthCapableRegex, KERN_DECIMAL_OPS_HELPER_PY, KERN_STDLIB_MODULES, lookupStdlibCall, lookupStdlibProperty, lowerRegexAnchorsPython, lowerRegexNamedGroupsPython, needsArgParens, needsBinaryParens, normalizeRegexClasses, parseExpression, parseKeys, REGEX_EXEC_FAILCLOSE, REGEX_HOST_REGEXP_FAILCLOSE, REGEX_MATCHALL_NO_G_FAILCLOSE, REGEX_NONLITERAL_FAILCLOSE, REGEX_REPLACE_NONLITERAL_REPL_FAILCLOSE, REGEX_REPLACEALL_NO_G_FAILCLOSE, REGEX_SPLIT_LIMIT_FAILCLOSE, REGEX_SPLIT_ZEROWIDTH_FAILCLOSE, REGEX_TEST_G_FAILCLOSE, regexAstralFailMessage, regexCaptureMeta, regexIFoldFailMessage, regexLiteralReceiverIR, regexMethodRegexArgIdent, scanRegexAstral, suggestStdlibMethod, translateReplStringToPython, unmappedHostNamespaceMessage, unwrapTransparentReceiverIR, validateDecimalConstructionArg, validateDecimalDivModArgs, validateDecimalOperands, validateDecimalPowArgs, validateRegexNamedGroupsPortable, } from '@kernlang/core';
 // Slice 0.9 — the TypeScript-AST closure helpers + classifier live on the Node
 // subpath (the barrel is browser-safe). Python codegen is Node-side and parses
 // block-bodied arrows, so it injects `typescriptClosureClassifier`.
@@ -75,6 +75,7 @@ function freshCtx(options) {
         usedPropagation: false,
         tryDepth: 0,
         finallyDepth: 0,
+        caughtBindings: new Set(),
         standaloneExpression: false,
         coerceJsValues: options?.coerceJsValues ?? true,
         traceHooks: options?.traceHooks,
@@ -310,6 +311,13 @@ function emitChildrenPy(children, ctx, indent, initialBindings = [], isLoopBody
                     lines.push(`${indent}${line}`);
             }
             else if (child.type === 'let') {
+                // Error-substrate Slice 1 (codex review: shadowing) — a `let` that rebinds
+                // a caught-error name SHADOWS the catch binding, so from here on its
+                // `.message` is an ordinary property access (matching TS), NOT `str(e)`.
+                // Drop it from the caught set so the rewrite no longer fires.
+                const letName = child.props?.name;
+                if (typeof letName === 'string')
+                    ctx.caughtBindings.delete(letName);
                 for (const line of emitLetPy(child, ctx))
                     lines.push(`${indent}${line}`);
             }
@@ -322,6 +330,11 @@ function emitChildrenPy(children, ctx, indent, initialBindings = [], isLoopBody
                     lines.push(line);
             }
             else if (child.type === 'assign') {
+                // Same shadowing guard for a bare-identifier assignment target: after
+                // `assign target="e" …`, `e` is no longer the caught error.
+                const tgt = child.props?.target;
+                if (typeof tgt === 'string' && /^[A-Za-z_$][\w$]*$/.test(tgt))
+                    ctx.caughtBindings.delete(tgt);
                 for (const line of emitAssignPy(child, ctx))
                     lines.push(`${indent}${line}`);
             }
@@ -492,7 +505,16 @@ function emitChildrenPy(children, ctx, indent, initialBindings = [], isLoopBody
                 if (catchNode !== null) {
                     const errName = String(catchNode.props?.name ?? 'e');
                     lines.push(`${indent}except Exception as ${errName}:`);
+                    // Error-substrate Slice 1 — mark `errName` as a caught binding for the
+                    // duration of the catch body so a `<errName>.message` read lowers to
+                    // `str(<errName>)` (see `lowerChain`'s member case). Restore the prior
+                    // membership on exit so a SHADOWED outer catch binding of the same name
+                    // is unaffected and the flag never leaks past the catch block.
+                    const hadCaught = ctx.caughtBindings.has(errName);
+                    ctx.caughtBindings.add(errName);
                     const catchInner = emitChildrenPy(catchNode.children ?? [], ctx, indent + INDENT_STEP);
+                    if (!hadCaught)
+                        ctx.caughtBindings.delete(errName);
                     if (catchInner.length === 0)
                         lines.push(`${indent}${INDENT_STEP}pass`);
                     for (const cl of catchInner)
@@ -1862,8 +1884,10 @@ function emitPyExprCtx(node, ctx) {
             const lowered = lowerChain(node, ctx);
             return wrapGuardIfAny(lowered, ctx);
         }
-        case 'await':
-            return `await ${emitPyExprCtx(node.argument, ctx)}`;
+        case 'await': {
+            const arg = emitPyExprCtx(node.argument, ctx);
+            return `await ${needsLowPrecedenceOperandParens(node.argument) ? `(${arg})` : arg}`;
+        }
         case 'new': {
             // Host Error mapping (spec §1): `new Error(args)` → `Exception(args)` on
             // Python, since `raise Error(...)` / `isinstance(x, Error)` would
@@ -1930,6 +1954,20 @@ function emitPyExprCtx(node, ctx) {
             return out;
         }
         case 'binary': {
+            // DECIMAL Slice 2 (item 3) — fail closed on `+`/`-`/`*` over a syntactically-
+            // proven Decimal operand (`Decimal.of(...)`/`Decimal.<m>(...)`), the SAME
+            // decision the TS leg makes (shared `assertNoDecimalOperator` + message), so
+            // the refusal is byte-identical across targets. Conservative: a no-op for plain
+            // numeric arithmetic and for every non-`+`/`-`/`*` operator below.
+            //
+            // Slice-2 remediation (Finding 2): the assert is now performed AFTER the
+            // operands are lowered (see below, after `emitPyExprCtx(node.left/right)`),
+            // mirroring the TS leg's lower-then-assert order. A bad Decimal operand — an
+            // unknown member (`Decimal.nope(...)`) or a non-canonical literal
+            // (`Decimal.of("1.10")`) — then throws its OWN specific diagnostic during
+            // lowering instead of being masked by the generic operator error. The blocked
+            // operators are only `+`/`-`/`*`, so deferring the assert past the bitwise /
+            // shift / modulo branches below is safe (they never trip the Decimal check).
             // Slice 6 — bitwise / shift on the slice-0.75 ToInt32 substrate. Emitted
             // DIRECTLY as helper-wrapped strings (operands recurse through
             // `emitPyExprCtx`), so nested bitwise ops compose without the double-
@@ -1958,6 +1996,11 @@ function emitPyExprCtx(node, ctx) {
             // expected `(a == b) < c` evaluation order.
             const left = emitPyExprCtx(node.left, ctx);
             const right = emitPyExprCtx(node.right, ctx);
+            // DECIMAL Slice 2 (item 3) — operator fail-close, now AFTER operand lowering
+            // (Finding-2 remediation) so a bad Decimal operand surfaces its own diagnostic
+            // first. No-op for every operator except `+`/`-`/`*`, so it never affects the
+            // bitwise/shift/modulo paths handled above or the comparison/logical paths below.
+            assertNoDecimalOperator(node);
             if (node.op === 'instanceof') {
                 // JS `a instanceof B` → Python `isinstance(a, B)`. Emitting `instanceof`
                 // verbatim would be a Python *syntax* error, so this lowering is
@@ -2137,8 +2180,12 @@ function emitPyExprCtx(node, ctx) {
             }
             const forceLeft = needsComparisonChainParens(node.left, node.op);
             const forceRight = needsComparisonChainParens(node.right, node.op);
-            const lp = forceLeft || needsBinaryParens(node.left, node.op, 'left') ? `(${left})` : left;
-            const rp = forceRight || needsBinaryParens(node.right, node.op, 'right') ? `(${right})` : right;
+            const lp = forceLeft || needsLowPrecedenceOperandParens(node.left) || needsBinaryParens(node.left, node.op, 'left')
+                ? `(${left})`
+                : left;
+            const rp = forceRight || needsLowPrecedenceOperandParens(node.right) || needsBinaryParens(node.right, node.op, 'right')
+                ? `(${right})`
+                : right;
             const op = mapBinaryOpToPython(node.op);
             return `${lp} ${op} ${rp}`;
         }
@@ -2698,6 +2745,17 @@ function lowerOptionalLink(inner, objectNode, ctx) {
 function lowerChain(node, ctx) {
     if (node.kind === 'member') {
         const obj = node.object;
+        // Error-substrate Slice 1 — a `<caughtBinding>.message` read lowers to
+        // `str(<caughtBinding>)`. Python exceptions have NO `.message` attribute
+        // (a bare `e.message` raises AttributeError), but `str(Exception("x"))`
+        // === V8 `Error("x").message`, so this restores cross-target parity for the
+        // ONE admitted error-binding read. Scoped exactly: a NON-optional `.message`
+        // on a bare ident that is currently a caught binding. `e?.message`, a member
+        // chain root (`e.cause.message`), or any non-caught ident is NOT rewritten
+        // and emits verbatim — out of the parity domain (the runner abstains there).
+        if (!node.optional && node.property === 'message' && obj.kind === 'ident' && ctx.caughtBindings.has(obj.name)) {
+            return { guard: null, expr: `str(${emitPyExprCtx(obj, ctx)})` };
+        }
         // Slice 2 — a bare property READ on a DIRECT regex LITERAL (`/x/.source`,
         // `/x/.flags`) launders the pattern/flags back into a string. Routed through
         // the SHARED classifier (via the ValueIR adapter) so this site agrees with
@@ -2864,6 +2922,13 @@ function lowerChain(node, ctx) {
     if (node.callee.kind === 'ident') {
         rejectHostRegExpValuePython(node.callee.name, ctx);
     }
+    // DECIMAL Slice 1 — bare `Decimal(...)` (ident callee) fail-closes
+    // SYMMETRICALLY with the TS leg. Only `Decimal.of`/`Decimal.add` (member
+    // callees, handled by `applyStdlibLoweringPython` above) are portable. A
+    // proven user binding named `Decimal` is left alone.
+    if (node.callee.kind === 'ident' && node.callee.name === 'Decimal' && !isProvenUserBinding(ctx, 'Decimal')) {
+        throw new Error(decimalBareConstructionFailMessage());
+    }
     // Slice H — fail-closed on an UNMAPPED host-namespace member CALL. This runs
     // AFTER every explicit lowering hook above (stdlib, regex, lambda/array,
     // portable-array, super/String/Error) and BEFORE generic call emission, so a
@@ -2881,7 +2946,13 @@ function lowerChain(node, ctx) {
     const callee = node.callee;
     const inner = callee.kind === 'member' || callee.kind === 'call' || callee.kind === 'index'
         ? lowerChain(callee, ctx)
-        : { guard: null, expr: emitPyExprCtx(callee, ctx) };
+        : {
+            guard: null,
+            expr: (() => {
+                const emitted = emitPyExprCtx(callee, ctx);
+                return needsLowPrecedenceOperandParens(callee) ? `(${emitted})` : emitted;
+            })(),
+        };
     const args = node.args.map((a) => emitPyExprCtx(a, ctx)).join(', ');
     return { guard: inner.guard, expr: `${inner.expr}(${args})`, lambdaBind: inner.lambdaBind };
 }
@@ -3549,6 +3620,15 @@ function wrapGuardIfAny(g, ctx) {
 function needsWalrusOperandParens(child) {
     return child.kind === 'conditional' || child.kind === 'lambda';
 }
+/** Low-precedence operand positions (`a <op> b`, `await x`, `<callee>(...)`)
+ *  must wrap a conditional child so the surrounding operator/call binds to the
+ *  whole operand instead of one ternary arm. */
+function needsLowPrecedenceOperandParens(child) {
+    let node = child;
+    while (node.kind === 'typeAssert' || node.kind === 'nonNull')
+        node = node.expression;
+    return node.kind === 'conditional';
+}
 /** S5 review fix — run `fn` with `ctx.banWalrus` set (save/restore), for
  *  emitting an operand that will be interpolated into a comprehension/
  *  generator ITERABLE position, where CPython rejects `:=` outright (see
@@ -3846,6 +3926,22 @@ function applyStdlibLoweringPython(call, ctx) {
     if (moduleName === 'Array' && methodName === 'from' && call.args.some((arg) => arg.kind === 'spread')) {
         throw new Error('Array.from portable lowering does not accept spread arguments; pass source and mapper directly.');
     }
+    // DECIMAL Slice 1 — `Decimal.of(arg)` string-literal + canonical-scale check,
+    // running the SAME shared-core validator the TS leg runs, so the fail-close is
+    // byte-identical across targets.
+    validateDecimalConstructionArg(moduleName, methodName, call);
+    // DECIMAL Slice 3 — same shared compile-time pow fail-close the TS leg runs, so a
+    // non-integer / non-literal exponent or a negative base is refused byte-identically.
+    validateDecimalPowArgs(moduleName, methodName, call);
+    // DECIMAL Slice 3 (robustness) — same shared non-Decimal-operand fail-close the TS
+    // leg runs: a provably-non-Decimal LITERAL operand (a host number/string/…) passed
+    // to any Decimal op but `of` is refused byte-identically, closing the silent
+    // cross-target divergence a raw `0.1` operand would otherwise emit.
+    validateDecimalOperands(moduleName, methodName, call);
+    // DECIMAL Slice 3 — same shared compile-time zero-divisor fail-close: a literal
+    // `Decimal.of("0")` divisor to `Decimal.div`/`Decimal.mod` is refused byte-
+    // identically with the runtime guard's message (a dynamic zero stays runtime-caught).
+    validateDecimalDivModArgs(moduleName, methodName, call);
     const listLambda = lowerListLambdaPython(moduleName, methodName, call, ctx);
     if (listLambda !== null)
         return listLambda;
@@ -3904,6 +4000,19 @@ function registerStdlibRequirementPython(requirement, ctx) {
         ctx.helpers.add(KERN_JS_NUMBER_HELPERS_PY);
         return;
     }
+    // DECIMAL Slice 3 — `Decimal.div/mod/pow` register the guarded-ops helper block
+    // (single-sourced in `decimal-contract.ts`) AND the `decimal` import (the helper
+    // body references `_KernDecimal` for the `0**0 → 1` special-case). The block's
+    // own `from decimal import Decimal as _KernDecimal` line supplies that binding;
+    // we still register the `decimal` module import so the Decimal VALUES the helper
+    // operates on (`__k_decimal.Decimal(...)` from their `Decimal.of` producers) keep
+    // their existing import path — and so a div/mod/pow used WITHOUT a co-located
+    // `Decimal.of` literal still imports decimal.
+    if (requirement === 'decimal-ops') {
+        ctx.helpers.add(KERN_DECIMAL_OPS_HELPER_PY);
+        ctx.imports.add('decimal');
+        return;
+    }
     ctx.imports.add(requirement);
 }
 function lowerListLambdaPython(moduleName, methodName, call, ctx) {