@kernlang/python 3.5.2

package/dist/ir-semantics/python-leg.js

@@ -0,0 +1,291 @@
+/**
+ * Python emitter leg — Phase 1 PR-3b.
+ *
+ * Council-approved design (6-engine agon brainstorm, run 1778871685720):
+ *
+ *   - **(A) Fresh `python3 -u` subprocess per fixture.** Clean isolation;
+ *     ~50-100ms overhead × 19 fixtures = ~1-2s test cost; no shared state.
+ *     `-u` flag forces unbuffered stdio so short-lived fixtures cannot
+ *     drop trace events to a half-flushed buffer.
+ *   - **(ii) Dedicated FD 3 for trace transport.** stdout is reserved for
+ *     emitted-code `print()` calls; FD3 carries one JSON event per line.
+ *     This keeps user output from polluting the trace channel.
+ *   - **(B1) Codegen hook injected in production Python emitter** behind
+ *     `BodyEmitOptions.traceHooks.eachIterNext` (opt-in only; production
+ *     callers never set it). Symmetric with TS leg's hook contract.
+ *   - **(P1) Sentinel exception classes** `_KernReturn`/`_KernThrow`
+ *     defined in the prelude. Lowered `throw` body-stmts raise them;
+ *     a wrapping `async def __kern_run()` catches and resolves them
+ *     into [[CompletionRecord]]s. Symmetric with TS sentinel approach.
+ *
+ * Council-flagged mitigations applied:
+ *   - Deterministic JSON: `sort_keys=True` on Python side; we already do
+ *     key-sorted serialization on TS side via `serializeValue`.
+ *   - Unbuffered stdio: `python3 -u`.
+ *   - Async-aware timeout: subprocess SIGKILLed after 10s if it hasn't
+ *     exited; surfaces as PythonLegError.
+ *
+ * Fixture authors: do NOT use Python `print()` inside fixture bodies — the
+ * harness writes the completion record to stdout. Use `__trace` events with
+ * `op: 'stdout'` if you need to observe stdout-style output through the
+ * trace channel (FD 3).
+ */
+import { spawn } from 'node:child_process';
+import { lowerFixtureForTarget } from '@kernlang/core';
+import { emitNativeKernBodyPythonWithImports } from '../codegen-body-python.js';
+const PYTHON_LEG_TIMEOUT_MS = 10_000;
+/**
+ * Serialise a fixture binding into a Python literal expression. Mirrors
+ * `serializeValue` from `@kernlang/core/ir/semantics/fixture-lowering`
+ * but with `target='python'` semantics so booleans, null, etc. map to
+ * their Python equivalents.
+ */
+function pyLiteral(value) {
+    if (value === null || value === undefined)
+        return 'None';
+    if (typeof value === 'boolean')
+        return value ? 'True' : 'False';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error(`pyLiteral: ${value} is not cross-target portable`);
+        }
+        return String(value);
+    }
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(pyLiteral).join(', ')}]`;
+    if (value instanceof Map) {
+        // Python dict (3.7+) preserves insertion order; emit in Map iteration
+        // order to keep `.keys()` / `.values()` / `.items()` iteration semantics
+        // aligned with the reference runner (which uses `Map` insertion order).
+        const pairs = Array.from(value.entries()).map(([k, v]) => `${JSON.stringify(String(k))}: ${pyLiteral(v)}`);
+        return `{${pairs.join(', ')}}`;
+    }
+    if (typeof value === 'object') {
+        // Preserve JS object insertion order — Python dict iteration mirrors it.
+        // Sort-keys here would silently reorder entry-mode iteration.
+        const pairs = Object.entries(value).map(([k, v]) => `${JSON.stringify(k)}: ${pyLiteral(v)}`);
+        return `{${pairs.join(', ')}}`;
+    }
+    throw new Error(`pyLiteral: unsupported type "${typeof value}"`);
+}
+/**
+ * Python prelude — injected as the first statements in the spawned
+ * subprocess. Defines the sentinel classes the lowered IR raises, the
+ * trace sink that writes one JSON event per line to FD 3, and the
+ * async wrapper that converts sentinel exceptions into CompletionRecords.
+ */
+function buildPrelude() {
+    return [
+        'import asyncio',
+        'import json',
+        'import os',
+        'import sys',
+        '',
+        'class _KernReturn(Exception):',
+        '    def __init__(self, value):',
+        '        self.value = value',
+        '',
+        'class _KernThrow(Exception):',
+        '    def __init__(self, kind):',
+        '        self.kind = kind',
+        '',
+        '_kern_trace_fd = 3',
+        '',
+        'def _kern_trace(event):',
+        '    line = json.dumps(event, sort_keys=True)',
+        '    os.write(_kern_trace_fd, (line + "\\n").encode("utf-8"))',
+        '',
+    ].join('\n');
+}
+/**
+ * Wrap the emitted body in an async function that returns a JSON
+ * CompletionRecord on stdout, catching the sentinel exceptions.
+ *
+ * `helpers` are emitted at module scope ABOVE the env bindings so they're
+ * visible from inside `__kern_run`. This matches production codegen: helpers
+ * (`_kern_pairs`, `_kern_async_pairs`) are module-level defs, not nested
+ * inside the running function.
+ */
+function buildProgram(bodyCode, envBindings, helpers) {
+    const bindingLines = envBindings.map(([name, value]) => `${name} = ${pyLiteral(value)}`);
+    const indented = bodyCode
+        .split('\n')
+        .map((line) => (line.length === 0 ? '' : `        ${line}`))
+        .join('\n');
+    const helperBlock = helpers.length > 0 ? `${helpers.join('\n\n')}\n` : '';
+    return [
+        buildPrelude(),
+        helperBlock,
+        ...bindingLines,
+        '',
+        'async def __kern_run():',
+        '    try:',
+        indented || '        pass',
+        `        return {"kind": "normal"}`,
+        '    except _KernReturn as r:',
+        '        return {"kind": "return", "value": r.value}',
+        '    except _KernThrow as t:',
+        '        return {"kind": "throw", "error": {"kind": t.kind}}',
+        '',
+        '_completion = asyncio.run(__kern_run())',
+        'sys.stdout.write(json.dumps(_completion, sort_keys=True))',
+        'sys.stdout.flush()',
+    ].join('\n');
+}
+export class PythonLegError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PythonLegError';
+    }
+}
+function runPython(program) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn('python3', ['-u', '-c', program], {
+                stdio: ['ignore', 'pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            reject(new PythonLegError(`python3 spawn failed: ${err.message}`));
+            return;
+        }
+        // Single-settle guard — `error` and `close` can both fire; we want
+        // exactly one terminal resolution.
+        let settled = false;
+        const settle = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            action();
+        };
+        let stdout = '';
+        let stderr = '';
+        let fd3 = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        // FD 3 is the trace channel. Parent's view is Readable because the child
+        // writes to FD 3 via `os.write(3, ...)`.
+        const fd3Stream = child.stdio[3];
+        if (fd3Stream && typeof fd3Stream.on === 'function') {
+            fd3Stream.on('data', (chunk) => {
+                fd3 += chunk.toString();
+            });
+            fd3Stream.on('error', (err) => {
+                settle(() => {
+                    clearTimeout(killTimer);
+                    reject(new PythonLegError(`fd3 stream error: ${err.message}`));
+                });
+            });
+        }
+        const killTimer = setTimeout(() => {
+            child.kill('SIGKILL');
+            settle(() => reject(new PythonLegError(`python3 timed out after ${PYTHON_LEG_TIMEOUT_MS}ms`)));
+        }, PYTHON_LEG_TIMEOUT_MS);
+        killTimer.unref?.();
+        child.on('error', (err) => {
+            settle(() => {
+                clearTimeout(killTimer);
+                reject(new PythonLegError(`python3 process error: ${err.message}`));
+            });
+        });
+        // Resolve on `close` — fires only after ALL stdio streams have closed,
+        // so stdout/stderr/FD3 buffers are fully drained. `exit` races stdio
+        // drain (claude + codex agreed in PR-3b review).
+        child.on('close', (code) => {
+            settle(() => {
+                clearTimeout(killTimer);
+                resolve({ stdout, fd3, stderr, exitCode: code });
+            });
+        });
+    });
+}
+function parseTraceEvents(fd3) {
+    const events = [];
+    for (const raw of fd3.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            throw new PythonLegError(`malformed trace line on FD3: ${line.slice(0, 200)}`);
+        }
+    }
+    return events;
+}
+function isCompletion(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const k = value.kind;
+    return k === 'normal' || k === 'return' || k === 'throw';
+}
+/**
+ * Run the Python emitter leg of the differential harness.
+ *
+ * Error model mirrors `runTsEmitterLeg`: ONLY the sentinel-resolved
+ * completions count as fixture-comparable; any other failure (spawn
+ * error, non-zero exit, malformed FD3 output) is thrown so the harness
+ * records `leg-error`.
+ */
+export async function runPythonEmitterLeg(fixture, env) {
+    const lowered = lowerFixtureForTarget(fixture.ir, 'python');
+    const handlerWrapper = {
+        type: 'handler',
+        props: { lang: 'kern' },
+        children: [lowered],
+    };
+    let bodyCode;
+    let bodyHelpers;
+    try {
+        const result = emitNativeKernBodyPythonWithImports(handlerWrapper, {
+            traceHooks: { eachIterNext: true },
+        });
+        if (result.imports.size > 0) {
+            // Differential fixtures don't exercise stdlib-import codegen (math, etc.);
+            // if a future fixture does, this leg will need an import-emission
+            // strategy. Fail loud rather than silently producing broken Python.
+            const list = [...result.imports].sort().join(', ');
+            throw new PythonLegError(`fixture body requires Python imports [${list}] — unsupported by harness`);
+        }
+        bodyCode = result.code;
+        bodyHelpers = [...result.helpers];
+    }
+    catch (err) {
+        if (err instanceof PythonLegError)
+            throw err;
+        throw new PythonLegError(`emitNativeKernBodyPythonWithImports failed: ${err.message}`);
+    }
+    const program = buildProgram(bodyCode, Array.from(env.bindings.entries()), bodyHelpers);
+    const result = await runPython(program);
+    if (result.exitCode !== 0) {
+        throw new PythonLegError(`python3 exited with code ${result.exitCode}; stderr=${result.stderr.slice(0, 1000)}`);
+    }
+    const events = parseTraceEvents(result.fd3);
+    let completion;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (!isCompletion(parsed)) {
+            throw new Error(`unexpected completion shape: ${result.stdout.slice(0, 500)}`);
+        }
+        completion = parsed;
+        // Canonicalise error: Python sends `{"kind": "throw", "error": {"kind": "TypeError"}}`.
+        // The CompletionRecord shape matches our reference; nothing more to do.
+        if (completion.kind === 'throw' && completion.error) {
+            const canonical = { kind: completion.error.kind };
+            completion = { kind: 'throw', error: canonical };
+        }
+    }
+    catch (err) {
+        throw new PythonLegError(`failed to parse Python completion JSON: ${err.message}; stdout=${result.stdout.slice(0, 500)}`);
+    }
+    return { events, completion };
+}
+//# sourceMappingURL=python-leg.js.map

package/dist/ir-semantics/python-leg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-leg.js","sourceRoot":"","sources":["../../src/ir-semantics/python-leg.ts"],"names":[],"mappings":"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"}

package/dist/python-stdlib-preamble.d.ts

@@ -0,0 +1,32 @@
+/** Slice 4 follow-up — Python equivalent of the TS `kernStdlibPreamble`.
+ *
+ *  When a KERN module references the reserved type names `Result<T, E>`
+ *  or `Option<T>` AND the compile target is FastAPI, the generated
+ *  `main.py` needs the corresponding type aliases + frozen-dataclass
+ *  wrappers in scope. Without them, `Result[User, ParseError]` in a fn
+ *  signature would resolve to an undefined name at runtime.
+ *
+ *  Spec: docs/language/result-option-spec.md (per-target table). The
+ *  spec calls for **frozen dataclass** wrappers — NOT `Optional[T]` —
+ *  so `Some(None)` and `None_()` round-trip distinctly through Pydantic
+ *  and the discriminant `kind` field stays uniform across all targets.
+ *
+ *  Detection reuses `detectKernStdlibUsage` from @kernlang/core, the same
+ *  scanner the TS-family targets consume. Insertion is performed by the
+ *  FastAPI transpiler entry between the `import …` block and the first
+ *  emitted core node. */
+import type { IRNode, KernStdlibUsage } from '@kernlang/core';
+/** Module-level imports the preamble needs. The transpiler merges these
+ *  into its existing `serverImports` set so duplicates are deduped. */
+export declare const PYTHON_STDLIB_IMPORTS: string[];
+/** Build the preamble lines. Returns an empty array when neither Result
+ *  nor Option is detected so the FastAPI output stays unchanged for
+ *  modules that don't use the compact form. */
+export declare function pythonStdlibPreamble(usage: KernStdlibUsage): string[];
+/** Convenience wrapper that pairs detection + emission. The transpiler
+ *  calls this once per build to know whether to merge the imports and
+ *  what lines to insert ahead of the first core artifact. */
+export declare function buildPythonStdlibPreamble(root: IRNode): {
+    imports: string[];
+    lines: string[];
+};

package/dist/python-stdlib-preamble.js

@@ -0,0 +1,86 @@
+/** Slice 4 follow-up — Python equivalent of the TS `kernStdlibPreamble`.
+ *
+ *  When a KERN module references the reserved type names `Result<T, E>`
+ *  or `Option<T>` AND the compile target is FastAPI, the generated
+ *  `main.py` needs the corresponding type aliases + frozen-dataclass
+ *  wrappers in scope. Without them, `Result[User, ParseError]` in a fn
+ *  signature would resolve to an undefined name at runtime.
+ *
+ *  Spec: docs/language/result-option-spec.md (per-target table). The
+ *  spec calls for **frozen dataclass** wrappers — NOT `Optional[T]` —
+ *  so `Some(None)` and `None_()` round-trip distinctly through Pydantic
+ *  and the discriminant `kind` field stays uniform across all targets.
+ *
+ *  Detection reuses `detectKernStdlibUsage` from @kernlang/core, the same
+ *  scanner the TS-family targets consume. Insertion is performed by the
+ *  FastAPI transpiler entry between the `import …` block and the first
+ *  emitted core node. */
+import { detectKernStdlibUsage } from '@kernlang/core';
+/** Module-level imports the preamble needs. The transpiler merges these
+ *  into its existing `serverImports` set so duplicates are deduped. */
+export const PYTHON_STDLIB_IMPORTS = [
+    'from dataclasses import dataclass',
+    'from typing import Generic, Literal, TypeAlias, TypeVar, Union',
+];
+/** TypeVars used by both Result and Option. Kern-namespaced names avoid
+ *  collisions with user-defined `T` / `E` TypeVars in the same module. */
+const TYPE_VARS = ['_T_kern = TypeVar("_T_kern")', '_E_kern = TypeVar("_E_kern")'];
+/** Frozen-dataclass wrappers for Result. `value` / `error` come first
+ *  (no defaults); `kind` last with a default literal so constructors can
+ *  be called as `Ok(value=user)` without restating the discriminant. */
+const RESULT_TYPES = [
+    '@dataclass(frozen=True)',
+    'class Ok(Generic[_T_kern]):',
+    '    value: _T_kern',
+    '    kind: Literal["ok"] = "ok"',
+    '',
+    '@dataclass(frozen=True)',
+    'class Err(Generic[_E_kern]):',
+    '    error: _E_kern',
+    '    kind: Literal["err"] = "err"',
+    '',
+    'Result: TypeAlias = Union[Ok[_T_kern], Err[_E_kern]]',
+];
+const OPTION_TYPES = [
+    '@dataclass(frozen=True)',
+    'class Some(Generic[_T_kern]):',
+    '    value: _T_kern',
+    '    kind: Literal["some"] = "some"',
+    '',
+    // `None_` (trailing underscore) — Python `None` is reserved as a
+    // singleton/null literal, so the spec uses `None_` for the "absent"
+    // variant of Option. Frozen + parameterless to model the unit case.
+    '@dataclass(frozen=True)',
+    'class None_:',
+    '    kind: Literal["none"] = "none"',
+    '',
+    'Option: TypeAlias = Union[Some[_T_kern], None_]',
+];
+/** Build the preamble lines. Returns an empty array when neither Result
+ *  nor Option is detected so the FastAPI output stays unchanged for
+ *  modules that don't use the compact form. */
+export function pythonStdlibPreamble(usage) {
+    if (!usage.result && !usage.option)
+        return [];
+    const lines = ['# ── KERN stdlib (auto-emitted) ──────────────────────────────────────', ...TYPE_VARS, ''];
+    if (usage.result) {
+        lines.push(...RESULT_TYPES);
+        lines.push('');
+    }
+    if (usage.option) {
+        lines.push(...OPTION_TYPES);
+        lines.push('');
+    }
+    return lines;
+}
+/** Convenience wrapper that pairs detection + emission. The transpiler
+ *  calls this once per build to know whether to merge the imports and
+ *  what lines to insert ahead of the first core artifact. */
+export function buildPythonStdlibPreamble(root) {
+    const usage = detectKernStdlibUsage(root);
+    const lines = pythonStdlibPreamble(usage);
+    if (lines.length === 0)
+        return { imports: [], lines: [] };
+    return { imports: PYTHON_STDLIB_IMPORTS, lines };
+}
+//# sourceMappingURL=python-stdlib-preamble.js.map

package/dist/python-stdlib-preamble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-stdlib-preamble.js","sourceRoot":"","sources":["../src/python-stdlib-preamble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;yBAgByB;AAGzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;uEACuE;AACvE,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,mCAAmC;IACnC,gEAAgE;CACjE,CAAC;AAEF;0EAC0E;AAC1E,MAAM,SAAS,GAAG,CAAC,8BAA8B,EAAE,8BAA8B,CAAC,CAAC;AAEnF;;wEAEwE;AACxE,MAAM,YAAY,GAAG;IACnB,yBAAyB;IACzB,6BAA6B;IAC7B,oBAAoB;IACpB,gCAAgC;IAChC,EAAE;IACF,yBAAyB;IACzB,8BAA8B;IAC9B,oBAAoB;IACpB,kCAAkC;IAClC,EAAE;IACF,sDAAsD;CACvD,CAAC;AAEF,MAAM,YAAY,GAAG;IACnB,yBAAyB;IACzB,+BAA+B;IAC/B,oBAAoB;IACpB,oCAAoC;IACpC,EAAE;IACF,iEAAiE;IACjE,oEAAoE;IACpE,oEAAoE;IACpE,yBAAyB;IACzB,cAAc;IACd,oCAAoC;IACpC,EAAE;IACF,iDAAiD;CAClD,CAAC;AAEF;;+CAE+C;AAC/C,MAAM,UAAU,oBAAoB,CAAC,KAAsB;IACzD,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAE9C,MAAM,KAAK,GAAa,CAAC,wEAAwE,EAAE,GAAG,SAAS,EAAE,EAAE,CAAC,CAAC;IACrH,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;6DAE6D;AAC7D,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC1D,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,KAAK,EAAE,CAAC;AACnD,CAAC"}

package/dist/transpiler-fastapi.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @kernlang/python — FastAPI Python backend transpiler
+ *
+ * IR → Python/FastAPI multi-file output.
+ * Blueprint: transpiler-express.ts — same IR nodes, same multi-file pattern, Python output.
+ */
+import type { IRNode, ResolvedKernConfig, TranspileResult } from '@kernlang/core';
+export declare function transpileFastAPI(root: IRNode, _config?: ResolvedKernConfig): TranspileResult;