@descryy/runtime-adapter-python 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { RawPythonFrame } from "./python-frame-parsing.ts";
+export { CHAINED_EXCEPTION_CONNECTIVES, createPythonLineClassifier, isPythonBannerLine, isPythonLocationLine, isPythonTrailerLine, looksLikeContinuation, parsePythonFrame, } from "./python-frame-parsing.ts";
+export { createUvicornLogEnvelope } from "./python-log-envelopes.ts";
+export { createPythonSourceLocationResolver } from "./python-source-location-resolver.ts";
+export { createPythonStackTraceParser } from "./python-stack-trace-parser.ts";
+export type { PythonRuntimeAdapterOptions } from "./python-runtime-adapter.ts";
+export { createPythonRuntimeAdapter } from "./python-runtime-adapter.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kCAAkC,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,YAAY,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { CHAINED_EXCEPTION_CONNECTIVES, createPythonLineClassifier, isPythonBannerLine, isPythonLocationLine, isPythonTrailerLine, looksLikeContinuation, parsePythonFrame, } from "./python-frame-parsing.js";
+export { createUvicornLogEnvelope } from "./python-log-envelopes.js";
+export { createPythonSourceLocationResolver } from "./python-source-location-resolver.js";
+export { createPythonStackTraceParser } from "./python-stack-trace-parser.js";
+export { createPythonRuntimeAdapter } from "./python-runtime-adapter.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kCAAkC,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAE9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/python-frame-parsing.d.ts

@@ -0,0 +1,90 @@
+/**
+ * CPython traceback line shapes — the `LineClassifier` for
+ * `ExceptionBlockDetector` plus the raw-text-to-frame-parts extraction that
+ * feeds `SourceLocationResolver`.
+ *
+ * CPython's format differs from V8's in three ways that matter, and each one
+ * is a place a naive port of the V8 classifier would fail quietly rather
+ * than loudly:
+ *
+ * 1. **The opening line names no exception.** `Traceback (most recent call
+ *    last):` is a fixed banner; the type and message arrive *after* every
+ *    frame. That is what `isPythonTrailerLine` exists for — see
+ *    `LineClassifier.isTrailer`.
+ * 2. **Frames print oldest-call-first.** The failing frame is last, the
+ *    opposite of V8. The reversal is done in the parser, not here, because
+ *    `StackTrace.frames` is contractually most-recent-first.
+ * 3. **A frame is more than one line.** The `File "...", line N, in f`
+ *    line is followed by the source text, and on 3.11+ by a caret line
+ *    (`    ^^^^^^`) marking the failing expression. Those continuation
+ *    lines carry no location of their own but belong to the block, so
+ *    `isPythonFrameLine` accepts them — otherwise the first source line
+ *    would terminate the block and truncate every traceback to one frame.
+ *
+ * The banner test is deliberately not anchored to the start of the line, for
+ * the same reason the V8 header test isn't: real applications log through
+ * formatters that prefix timestamps and levels. The block detector's own
+ * "banner immediately followed by a frame" rule is what keeps that safe — a
+ * log line merely mentioning the word with nothing frame-shaped after it
+ * never becomes an exception.
+ */
+export interface RawPythonFrame {
+    /** `<module>`, `<lambda>` and `<listcomp>` are real CPython function names and are kept verbatim, not nulled. */
+    readonly functionName: string | null;
+    /** Verbatim, including CPython's pseudo-files: `<string>`, `<stdin>`, `<frozen importlib._bootstrap>`. */
+    readonly file: string;
+    readonly line: number;
+}
+/** Removes PEP 654's tree gutter, if present. Identity for an ordinary traceback line. */
+export declare function stripExceptionGroupGutter(line: string): string;
+/**
+ * Two connective lines CPython prints *between* chained tracebacks. They are
+ * deliberately NOT trailers: each chained traceback is its own complete
+ * exception block, and swallowing the connective line into the first block
+ * would attach the wrong text to it. They fall through as plain log lines,
+ * and the second `Traceback` banner opens a second block — which reports
+ * chained exceptions as two honest blocks plus the sentence linking them,
+ * rather than one block silently missing half its content.
+ */
+export declare const CHAINED_EXCEPTION_CONNECTIVES: readonly ["During handling of the above exception, another exception occurred:", "The above exception was the direct cause of the following exception:"];
+export declare function isPythonBannerLine(line: string): boolean;
+export declare function isPythonLocationLine(line: string): boolean;
+/**
+ * Indentation alone — **not** sufficient on its own to call a line a frame.
+ * See `createPythonLineClassifier`, which is what the adapter actually uses.
+ */
+export declare function looksLikeContinuation(line: string): boolean;
+export declare function isPythonTrailerLine(line: string): boolean;
+/**
+ * A stateful `LineClassifier`, and the statefulness is the point.
+ *
+ * The obvious stateless rule — "a frame is a `File` line **or** anything
+ * indented" — is wrong, and the cross-language control in this package's
+ * tests is what caught it. `ExceptionBlockDetector` opens a block the
+ * moment `isFrame` returns true from idle, so a stateless indent rule turns
+ * **every indented log line in the application's output** into the start of
+ * a spurious stack-trace block: a pretty-printed JSON payload, a wrapped
+ * message, an indented SQL statement. It also accepts another runtime's
+ * frames verbatim (`    at deleteInvoice (file:///app/db.js:17:22)` is just
+ * an indented line), so a mis-wired adapter would half-work rather than
+ * fail.
+ *
+ * A continuation is therefore only recognised **after a `File` line has
+ * been seen** — which is the actual rule CPython's format obeys, since
+ * source text and caret markers only ever appear beneath a location line.
+ * Any line that is neither a location nor a continuation clears that state,
+ * so a block that ends without a trailer cannot leave the classifier primed.
+ *
+ * This depends on lines arriving in stream order, which `ExceptionBlockDetector`
+ * provides by construction — it is a one-line-at-a-time streaming detector
+ * and `isFrame` is consulted for every line in every state. A fresh
+ * classifier per collector keeps two processes' output from sharing state.
+ */
+export declare function createPythonLineClassifier(): {
+    isHeader(line: string): boolean;
+    isFrame(line: string): boolean;
+    isTrailer(line: string): boolean;
+};
+/** `null` for a continuation line, or a `File` line with no parseable line number — never fabricated. */
+export declare function parsePythonFrame(line: string): RawPythonFrame | null;
+//# sourceMappingURL=python-frame-parsing.d.ts.map

package/dist/python-frame-parsing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-frame-parsing.d.ts","sourceRoot":"","sources":["../src/python-frame-parsing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,WAAW,cAAc;IAC7B,iHAAiH;IACjH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,0GAA0G;IAC1G,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAyDD,0FAA0F;AAC1F,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9D;AA6ED;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,0JAGhC,CAAC;AAEX,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,0BAA0B,IAAI;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC,CA+BA;AAED,yGAAyG;AACzG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAOpE"}

package/dist/python-frame-parsing.js

@@ -0,0 +1,259 @@
+/**
+ * CPython traceback line shapes — the `LineClassifier` for
+ * `ExceptionBlockDetector` plus the raw-text-to-frame-parts extraction that
+ * feeds `SourceLocationResolver`.
+ *
+ * CPython's format differs from V8's in three ways that matter, and each one
+ * is a place a naive port of the V8 classifier would fail quietly rather
+ * than loudly:
+ *
+ * 1. **The opening line names no exception.** `Traceback (most recent call
+ *    last):` is a fixed banner; the type and message arrive *after* every
+ *    frame. That is what `isPythonTrailerLine` exists for — see
+ *    `LineClassifier.isTrailer`.
+ * 2. **Frames print oldest-call-first.** The failing frame is last, the
+ *    opposite of V8. The reversal is done in the parser, not here, because
+ *    `StackTrace.frames` is contractually most-recent-first.
+ * 3. **A frame is more than one line.** The `File "...", line N, in f`
+ *    line is followed by the source text, and on 3.11+ by a caret line
+ *    (`    ^^^^^^`) marking the failing expression. Those continuation
+ *    lines carry no location of their own but belong to the block, so
+ *    `isPythonFrameLine` accepts them — otherwise the first source line
+ *    would terminate the block and truncate every traceback to one frame.
+ *
+ * The banner test is deliberately not anchored to the start of the line, for
+ * the same reason the V8 header test isn't: real applications log through
+ * formatters that prefix timestamps and levels. The block detector's own
+ * "banner immediately followed by a frame" rule is what keeps that safe — a
+ * log line merely mentioning the word with nothing frame-shaped after it
+ * never becomes an exception.
+ */
+const BANNER_PATTERN = /Traceback \(most recent call last\):/;
+/**
+ * PEP 654's tree gutter, stripped before every other pattern in this file
+ * sees a line.
+ *
+ * ## The measurement
+ *
+ * `asyncio.TaskGroup` (stdlib since 3.11) and every `ExceptionGroup` print
+ * their tracebacks inside a drawn tree:
+ *
+ * ```
+ *   + Exception Group Traceback (most recent call last):
+ *   |   File "/app/x.py", line 13, in <module>
+ *   |     asyncio.run(main())
+ *   | ExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception)
+ *   +-+---------------- 1 ----------------
+ *     | Traceback (most recent call last):
+ *     |   File "/app/x.py", line 4, in read_customer_name
+ *     | TypeError: 'NoneType' object is not subscriptable
+ *     +------------------------------------
+ * ```
+ *
+ * Every location line is `  |   File "..."`, and `FILE_LINE_LOOSE_PATTERN`
+ * anchors `^\s*File`. So **not one frame line matched**. Measured through
+ * the real detector on real output: 28 lines in, **28 plain logs out** —
+ * no EXCEPTION, no STACK_TRACE, no frames, and no degradation reported.
+ *
+ * Reachable through the front door, not a corner: a real FastAPI service
+ * with an async endpoint failing inside a `TaskGroup` produced two genuine
+ * `TypeError`s and the pipeline reported **one**. Half the failures silently
+ * gone, from a healthy-looking collector.
+ *
+ * ## Why it was invisible
+ *
+ * Every Python fixture in this repository raises from a plain synchronous
+ * call chain, so nothing was ever grouped. Lane A hit the identical shape on
+ * the JVM (RT-094): `isFrame` rejected JPMS module-qualified frames, every
+ * stack truncated at its first reflective call, and it was invisible because
+ * every JVM fixture threw directly from `main`. **A fixture that exercises
+ * only the simple call shape certifies only the simple call shape** — that
+ * is a property of the fixture, not of the language, and it has now cost two
+ * languages the same way.
+ *
+ * ## Why stripping is safe here
+ *
+ * The pattern is deliberately tighter than "any leading pipe": exactly one
+ * `|` or `+` followed by exactly one space, repeated for nesting. The
+ * separator rules (`+-+------- 1 -------`, `+---------`) have `-` after the
+ * `+` and so are never stripped — they stay unrecognised, which is correct,
+ * because they are decoration and belong to no frame. A traceback that is
+ * not in a group has no gutter and is untouched.
+ */
+const GROUP_GUTTER = /^(?:[ \t]*[|+] )+/;
+/** Removes PEP 654's tree gutter, if present. Identity for an ordinary traceback line. */
+export function stripExceptionGroupGutter(line) {
+    return line.replace(GROUP_GUTTER, "");
+}
+/**
+ * The two-space-indented location line. `, in <name>` is optional: it is
+ * absent for a frame compiled from a bare string, and `line N` is absent in
+ * a handful of exotic cases, which is why the line number is required by
+ * `parsePythonFrame` but not by the classifier — recognising a line as
+ * belonging to the block is a weaker claim than extracting a location from
+ * it, and conflating the two loses frames rather than merely their detail.
+ */
+const FILE_LINE_PATTERN = /^\s*File "(?<file>.*)", line (?<line>\d+)(?:, in (?<fn>.*))?\s*$/;
+const FILE_LINE_LOOSE_PATTERN = /^\s*File "(?<file>.*)"/;
+/**
+ * A frame's continuation: source text, or a 3.11+ caret marker. Indented
+ * strictly deeper than the `File` line's two spaces, which is what keeps a
+ * zero-indent trailer (`ValueError: ...`) from being read as one.
+ */
+const CONTINUATION_PATTERN = /^\s{3,}\S/;
+/**
+ * The closing line: `ValueError: bad input`, a dotted
+ * `myapp.errors.ConfigError: ...`, or a bare `SystemExit` with no message
+ * at all. Anchored at zero indent — every frame line in a CPython traceback
+ * is indented, so the indent is what separates "this closes the block" from
+ * "this is more of the block".
+ *
+ * ## The lookahead, and the fabrication it removes (RT-106)
+ *
+ * Without `(?=[\w.]*[a-z])` this pattern was `^[A-Za-z_][\w.]*(?::[ \t].*)?$`
+ * — **any** `WORD: text` line at zero indent, which is `logging`'s default
+ * format and uvicorn's entire access-log format. A CPython traceback is
+ * written one `write()` per line, so a second thread logging to the same fd
+ * interleaves *between* them. Measured, on real threaded CPython 3.12
+ * output, three consecutive runs of 25 failures each:
+ *
+ * | | run 1 | run 2 | run 3 |
+ * | --- | --- | --- | --- |
+ * | failures reported with an access-log line as their identity | 7 | 8 | 7 |
+ *
+ * And the damage is symmetric, which the first reading of this defect
+ * missed. An `INFO:` line landing after the `Traceback` banner closed the
+ * block **immediately**, so the emitted EXCEPTION was two lines — the
+ * banner and `INFO: 127.0.0.1:50002 - "GET /health HTTP/1.1" 200 OK`, zero
+ * frames. *A successful request reported as the failure.* The real frames
+ * and the real `TypeError:` then arrived with no header and were emitted as
+ * a bare `stack-trace` event, so the genuine failure produced **no
+ * EXCEPTION at all.** Roughly 30% of failures, both halves wrong.
+ *
+ * ## Why a lowercase letter, and what it costs
+ *
+ * A Python exception class is CapWords by PEP 8 and a log level is
+ * upper-case by universal convention, so "the class token contains at least
+ * one lowercase letter" separates them. That is a naming convention rather
+ * than a grammar, so the cost was **measured before it was accepted**: 199
+ * importable stdlib modules were walked and every `BaseException` subclass
+ * in them collected — **228 distinct exception class names, 0 of which
+ * contain no lowercase letter.** A dotted `myapp.errors.ConfigError`
+ * passes on its module path alone.
+ *
+ * **The disclosed recall cost:** an exception class named entirely in
+ * upper-case (`FOO`) no longer closes a block. Its frames still become a
+ * `stack-trace` event; what is lost is the exception identity, not the
+ * evidence. That is the deliberate direction of the trade — this defect was
+ * shipping *wrong* evidence, and a gap is disclosable in a way a
+ * confidently-wrong identity is not.
+ *
+ * **What it does not fix:** a log line whose first token happens to be
+ * CapWords — `Error: connection refused` from an application's own `print`
+ * — is still trailer-shaped and still interleaves. The structural answer to
+ * that is a declared `LogEnvelope`, whose `startsRecord` closes a block at
+ * a boundary the framework *states* rather than one this pattern guesses;
+ * `createUvicornLogEnvelope` is the first of those. This lookahead is what
+ * an **un-enveloped** stream gets, and it is a heuristic, said plainly.
+ */
+const TRAILER_PATTERN = /^(?=[\w.]*[a-z])[A-Za-z_][\w.]*(?::[ \t].*)?$/;
+/**
+ * Two connective lines CPython prints *between* chained tracebacks. They are
+ * deliberately NOT trailers: each chained traceback is its own complete
+ * exception block, and swallowing the connective line into the first block
+ * would attach the wrong text to it. They fall through as plain log lines,
+ * and the second `Traceback` banner opens a second block — which reports
+ * chained exceptions as two honest blocks plus the sentence linking them,
+ * rather than one block silently missing half its content.
+ */
+export const CHAINED_EXCEPTION_CONNECTIVES = [
+    "During handling of the above exception, another exception occurred:",
+    "The above exception was the direct cause of the following exception:",
+];
+export function isPythonBannerLine(line) {
+    return BANNER_PATTERN.test(stripExceptionGroupGutter(line));
+}
+export function isPythonLocationLine(line) {
+    return FILE_LINE_LOOSE_PATTERN.test(stripExceptionGroupGutter(line));
+}
+/**
+ * Indentation alone — **not** sufficient on its own to call a line a frame.
+ * See `createPythonLineClassifier`, which is what the adapter actually uses.
+ */
+export function looksLikeContinuation(line) {
+    return CONTINUATION_PATTERN.test(stripExceptionGroupGutter(line));
+}
+export function isPythonTrailerLine(line) {
+    if (CHAINED_EXCEPTION_CONNECTIVES.some((c) => line.trim() === c))
+        return false;
+    return TRAILER_PATTERN.test(stripExceptionGroupGutter(line));
+}
+/**
+ * A stateful `LineClassifier`, and the statefulness is the point.
+ *
+ * The obvious stateless rule — "a frame is a `File` line **or** anything
+ * indented" — is wrong, and the cross-language control in this package's
+ * tests is what caught it. `ExceptionBlockDetector` opens a block the
+ * moment `isFrame` returns true from idle, so a stateless indent rule turns
+ * **every indented log line in the application's output** into the start of
+ * a spurious stack-trace block: a pretty-printed JSON payload, a wrapped
+ * message, an indented SQL statement. It also accepts another runtime's
+ * frames verbatim (`    at deleteInvoice (file:///app/db.js:17:22)` is just
+ * an indented line), so a mis-wired adapter would half-work rather than
+ * fail.
+ *
+ * A continuation is therefore only recognised **after a `File` line has
+ * been seen** — which is the actual rule CPython's format obeys, since
+ * source text and caret markers only ever appear beneath a location line.
+ * Any line that is neither a location nor a continuation clears that state,
+ * so a block that ends without a trailer cannot leave the classifier primed.
+ *
+ * This depends on lines arriving in stream order, which `ExceptionBlockDetector`
+ * provides by construction — it is a one-line-at-a-time streaming detector
+ * and `isFrame` is consulted for every line in every state. A fresh
+ * classifier per collector keeps two processes' output from sharing state.
+ */
+export function createPythonLineClassifier() {
+    let sawLocationLine = false;
+    return {
+        isHeader(line) {
+            if (isPythonBannerLine(line)) {
+                sawLocationLine = false;
+                return true;
+            }
+            return false;
+        },
+        isFrame(line) {
+            if (isPythonLocationLine(line)) {
+                sawLocationLine = true;
+                return true;
+            }
+            if (sawLocationLine && looksLikeContinuation(line))
+                return true;
+            sawLocationLine = false;
+            return false;
+        },
+        isTrailer(line) {
+            // Only closes a block that actually had frames in it — a bare
+            // identifier-shaped log line cannot close a block that never opened.
+            if (!sawLocationLine && !isPythonTrailerLine(line))
+                return false;
+            if (!isPythonTrailerLine(line))
+                return false;
+            sawLocationLine = false;
+            return true;
+        },
+    };
+}
+/** `null` for a continuation line, or a `File` line with no parseable line number — never fabricated. */
+export function parsePythonFrame(line) {
+    const match = FILE_LINE_PATTERN.exec(stripExceptionGroupGutter(line));
+    if (!match?.groups)
+        return null;
+    const file = match.groups["file"];
+    const lineNumber = Number(match.groups["line"]);
+    if (file === undefined || !Number.isInteger(lineNumber))
+        return null;
+    return { functionName: match.groups["fn"] ?? null, file, line: lineNumber };
+}
+//# sourceMappingURL=python-frame-parsing.js.map

package/dist/python-frame-parsing.js.map

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

package/dist/python-log-envelopes.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Python's `LogEnvelope`s. Currently one: **uvicorn** (RT-106).
+ *
+ * ## This file exists because an earlier claim of mine was too broad
+ *
+ * RT-103 measured Flask, Django and FastAPI all printing
+ * `Traceback (most recent call last):` at column 0 with CPython's own
+ * two-space frame indent, because `logging` appends `exc_info` unindented,
+ * and concluded **"Python needs no envelope at all and never will."**
+ *
+ * That is right about *unwrapping* and wrong about *record boundaries*, and
+ * the two are different jobs behind one interface. Nothing needs stripping
+ * from a Python traceback line. But `UnwrappedLine.startsRecord` is the
+ * only mechanism by which a collector can know that a line **ends the
+ * previous record**, and Python is the language where that matters most:
+ *
+ * ```
+ * Traceback (most recent call last):
+ * INFO:     127.0.0.1:50002 - "GET /health HTTP/1.1" 200 OK
+ *   File "/app/service.py", line 18, in charge_invoice
+ * ```
+ *
+ * A traceback is written one `write()` per line, so any other thread
+ * logging to the same stream interleaves between them. Measured on real
+ * threaded CPython 3.12, three runs of 25 failures: 7, 8 and 7 of them were
+ * reported as an EXCEPTION whose entire identity was an access-log line for
+ * a **successful** request — see `TRAILER_PATTERN` in
+ * `python-frame-parsing.ts` for the full measurement and for the heuristic
+ * that an un-enveloped stream falls back on.
+ *
+ * This envelope makes that case structural rather than guessed. uvicorn
+ * *states* where a record begins; the trailer pattern can only infer it.
+ *
+ * ## Nothing is stripped from a traceback, and that is the whole design
+ *
+ * uvicorn formats with `"%(levelprefix)s %(message)s"`, where `levelprefix`
+ * is `f"{levelname}:".ljust(9)`. That prefix goes on the record's **first**
+ * line only. The `exc_info` traceback `logging` appends afterwards is
+ * written through untouched, at column 0, with CPython's own indentation.
+ *
+ * Measured against real `uvicorn 0.41.0` / `fastapi 0.141.1` output
+ * (`test/fixtures/uvicorn-asgi-failure.txt`): `ERROR:    Exception in ASGI
+ * application` is the header, and all 28 traceback lines beneath it are
+ * continuations returned byte-identical. So `unwrap` is the identity
+ * function for every line that carries evidence, and the envelope's entire
+ * contribution is `startsRecord` — the opposite balance to Ruby's, where
+ * unwrapping is the load-bearing half.
+ *
+ * ## Why the level set is closed rather than `\w+`
+ *
+ * `^(\w+): +` would match `TypeError:    ...` — a real trailer, wrongly
+ * read as a record boundary, closing a block one line before its identity
+ * arrives. That is the same class of over-matching this envelope exists to
+ * fix, introduced from the other side. So the set is exactly the six level
+ * names `logging` and uvicorn can produce, and a seventh would be a
+ * measured addition rather than a widened pattern.
+ *
+ * ## Two disclosed limits
+ *
+ * **Colour.** uvicorn wraps `levelprefix` in ANSI when its output is a TTY.
+ * Descry pipes, so the measured stream has none, and this pattern would not
+ * match a colourised one. Stated rather than handled: adding an optional
+ * escape-sequence prefix on an unmeasured shape is the guess this file's
+ * own argument rejects.
+ *
+ * **Application loggers are not covered.** uvicorn configures only its own
+ * `uvicorn`/`uvicorn.error`/`uvicorn.access` loggers. An application's own
+ * `logging.getLogger(__name__).info(...)` goes through the root config and
+ * usually carries no prefix at all, so it comes back from `unwrap`
+ * untouched with `startsRecord: false` — correct, because this envelope has
+ * no idea whether that line began a record, and saying so would be the
+ * inference `fields()` exists to refuse.
+ */
+import type { LogEnvelope } from "@descryy/runtime-backend-observation";
+export declare function createUvicornLogEnvelope(): LogEnvelope;
+//# sourceMappingURL=python-log-envelopes.d.ts.map

package/dist/python-log-envelopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-log-envelopes.d.ts","sourceRoot":"","sources":["../src/python-log-envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAiC,MAAM,sCAAsC,CAAC;AAqBvG,wBAAgB,wBAAwB,IAAI,WAAW,CAyCtD"}

package/dist/python-log-envelopes.js

@@ -0,0 +1,129 @@
+/**
+ * Python's `LogEnvelope`s. Currently one: **uvicorn** (RT-106).
+ *
+ * ## This file exists because an earlier claim of mine was too broad
+ *
+ * RT-103 measured Flask, Django and FastAPI all printing
+ * `Traceback (most recent call last):` at column 0 with CPython's own
+ * two-space frame indent, because `logging` appends `exc_info` unindented,
+ * and concluded **"Python needs no envelope at all and never will."**
+ *
+ * That is right about *unwrapping* and wrong about *record boundaries*, and
+ * the two are different jobs behind one interface. Nothing needs stripping
+ * from a Python traceback line. But `UnwrappedLine.startsRecord` is the
+ * only mechanism by which a collector can know that a line **ends the
+ * previous record**, and Python is the language where that matters most:
+ *
+ * ```
+ * Traceback (most recent call last):
+ * INFO:     127.0.0.1:50002 - "GET /health HTTP/1.1" 200 OK
+ *   File "/app/service.py", line 18, in charge_invoice
+ * ```
+ *
+ * A traceback is written one `write()` per line, so any other thread
+ * logging to the same stream interleaves between them. Measured on real
+ * threaded CPython 3.12, three runs of 25 failures: 7, 8 and 7 of them were
+ * reported as an EXCEPTION whose entire identity was an access-log line for
+ * a **successful** request — see `TRAILER_PATTERN` in
+ * `python-frame-parsing.ts` for the full measurement and for the heuristic
+ * that an un-enveloped stream falls back on.
+ *
+ * This envelope makes that case structural rather than guessed. uvicorn
+ * *states* where a record begins; the trailer pattern can only infer it.
+ *
+ * ## Nothing is stripped from a traceback, and that is the whole design
+ *
+ * uvicorn formats with `"%(levelprefix)s %(message)s"`, where `levelprefix`
+ * is `f"{levelname}:".ljust(9)`. That prefix goes on the record's **first**
+ * line only. The `exc_info` traceback `logging` appends afterwards is
+ * written through untouched, at column 0, with CPython's own indentation.
+ *
+ * Measured against real `uvicorn 0.41.0` / `fastapi 0.141.1` output
+ * (`test/fixtures/uvicorn-asgi-failure.txt`): `ERROR:    Exception in ASGI
+ * application` is the header, and all 28 traceback lines beneath it are
+ * continuations returned byte-identical. So `unwrap` is the identity
+ * function for every line that carries evidence, and the envelope's entire
+ * contribution is `startsRecord` — the opposite balance to Ruby's, where
+ * unwrapping is the load-bearing half.
+ *
+ * ## Why the level set is closed rather than `\w+`
+ *
+ * `^(\w+): +` would match `TypeError:    ...` — a real trailer, wrongly
+ * read as a record boundary, closing a block one line before its identity
+ * arrives. That is the same class of over-matching this envelope exists to
+ * fix, introduced from the other side. So the set is exactly the six level
+ * names `logging` and uvicorn can produce, and a seventh would be a
+ * measured addition rather than a widened pattern.
+ *
+ * ## Two disclosed limits
+ *
+ * **Colour.** uvicorn wraps `levelprefix` in ANSI when its output is a TTY.
+ * Descry pipes, so the measured stream has none, and this pattern would not
+ * match a colourised one. Stated rather than handled: adding an optional
+ * escape-sequence prefix on an unmeasured shape is the guess this file's
+ * own argument rejects.
+ *
+ * **Application loggers are not covered.** uvicorn configures only its own
+ * `uvicorn`/`uvicorn.error`/`uvicorn.access` loggers. An application's own
+ * `logging.getLogger(__name__).info(...)` goes through the root config and
+ * usually carries no prefix at all, so it comes back from `unwrap`
+ * untouched with `startsRecord: false` — correct, because this envelope has
+ * no idea whether that line began a record, and saying so would be the
+ * inference `fields()` exists to refuse.
+ */
+/**
+ * `INFO:     127.0.0.1:39334 - "GET /health HTTP/1.1" 200 OK`
+ *
+ * uvicorn's `DefaultFormatter`/`AccessFormatter` both use
+ * `"%(levelprefix)s %(message)s"` with `levelprefix = f"{levelname}:".ljust(9)`,
+ * so the separator is between 1 and 5 spaces depending on the level's own
+ * length — `CRITICAL:` needs no padding, `INFO:` needs four. Anchored at
+ * column zero: a traceback's frame lines are indented and its trailer is
+ * not level-shaped, so neither can reach this.
+ */
+const UVICORN_HEADER = /^(CRITICAL|ERROR|WARNING|INFO|DEBUG|TRACE): +/;
+/**
+ * uvicorn's access line: `127.0.0.1:39334 - "GET /health HTTP/1.1" 200 OK`.
+ * Parsed only to populate `attrs` — nothing above the envelope reads it, the
+ * same contract `attrs` has in the IR.
+ */
+const ACCESS_MESSAGE = /^(?<client>\S+) - "(?<method>[A-Z]+) (?<path>\S+) (?<protocol>\S+)" (?<status>\d{3})\b/;
+export function createUvicornLogEnvelope() {
+    let fields = null;
+    return {
+        frameworkName: "uvicorn",
+        unwrap(line) {
+            const match = UVICORN_HEADER.exec(line);
+            // Not a header: a traceback line, an application logger's own output,
+            // or anything else. Returned byte-identical, and explicitly NOT
+            // claiming a boundary — an unrecognised line is not evidence of one.
+            if (match === null)
+                return { content: line, startsRecord: false };
+            const content = line.slice(match[0].length);
+            const access = ACCESS_MESSAGE.exec(content);
+            fields = {
+                // uvicorn's own word, never normalised to a shared vocabulary.
+                level: match[1] ?? null,
+                // uvicorn's formatter discards the logger name — `uvicorn.access`
+                // and `uvicorn.error` are indistinguishable in the printed stream.
+                // Null because it is genuinely absent, not merely unparsed.
+                category: null,
+                // uvicorn has no request-id concept and prints none. Unlike
+                // Kestrel's `Request id "..."`, there is nothing here to read, and
+                // deriving one from the client port would be an invention.
+                requestId: null,
+                attrs: access?.groups === undefined
+                    ? {}
+                    : {
+                        client: access.groups["client"] ?? "",
+                        method: access.groups["method"] ?? "",
+                        path: access.groups["path"] ?? "",
+                        status: access.groups["status"] ?? "",
+                    },
+            };
+            return { content, startsRecord: true };
+        },
+        fields: () => fields,
+    };
+}
+//# sourceMappingURL=python-log-envelopes.js.map

package/dist/python-log-envelopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-log-envelopes.js","sourceRoot":"","sources":["../src/python-log-envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAIH;;;;;;;;;GASG;AACH,MAAM,cAAc,GAAG,+CAA+C,CAAC;AAEvE;;;;GAIG;AACH,MAAM,cAAc,GAAG,wFAAwF,CAAC;AAEhH,MAAM,UAAU,wBAAwB;IACtC,IAAI,MAAM,GAA0B,IAAI,CAAC;IAEzC,OAAO;QACL,aAAa,EAAE,SAAS;QAExB,MAAM,CAAC,IAAY;YACjB,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxC,sEAAsE;YACtE,gEAAgE;YAChE,qEAAqE;YACrE,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;YAElE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC5C,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC5C,MAAM,GAAG;gBACP,+DAA+D;gBAC/D,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI;gBACvB,kEAAkE;gBAClE,mEAAmE;gBACnE,4DAA4D;gBAC5D,QAAQ,EAAE,IAAI;gBACd,4DAA4D;gBAC5D,mEAAmE;gBACnE,2DAA2D;gBAC3D,SAAS,EAAE,IAAI;gBACf,KAAK,EACH,MAAM,EAAE,MAAM,KAAK,SAAS;oBAC1B,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC;wBACE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;wBACrC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;wBACrC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE;wBACjC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;qBACtC;aACR,CAAC;YACF,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QACzC,CAAC;QAED,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM;KACrB,CAAC;AACJ,CAAC"}

package/dist/python-runtime-adapter.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The concrete `RuntimeAdapter` for Python — the second language, and the
+ * first one to test whether the seam `@descryy/runtime-backend-observation`
+ * defines is genuinely language-neutral or merely V8-shaped.
+ *
+ * It was not, in two places, and both were fixed in the seam rather than
+ * worked around here:
+ *
+ * - `LineClassifier` had no notion of a line that ends a block and belongs
+ *   to it, because a V8 header names its exception up front. A CPython
+ *   traceback names it last. `isTrailer` is that concept, added
+ *   language-neutrally.
+ * - `StackTrace.frames` had no documented order, because with one language
+ *   nothing ever had to convert. Python prints the opposite of V8. The
+ *   contract now states most-recent-first and this adapter reverses.
+ *
+ * Both are recorded because they are the general lesson of adding a second
+ * anything: a seam with one implementation is a seam in name only, and the
+ * defects it hides are silent ones — a truncated traceback and a
+ * backwards frame list both look like well-formed output.
+ */
+import type { RuntimeAdapter } from "@descryy/runtime-backend-observation";
+export interface PythonRuntimeAdapterOptions {
+    /** Attributed on every emitted Evidence's `service` field (plan §16.7). Omit when not applicable. */
+    readonly service?: string;
+    /**
+     * The server whose logging layer wraps this process's output (§16).
+     *
+     * **Declared, never sniffed** — the same rule ASP.NET's option follows,
+     * and for a sharper reason here. uvicorn's format is `LEVEL:` plus
+     * padding, which is `logging`'s own default shape; detecting it from a
+     * line that looks like one would enable record-boundary flushing for any
+     * Python process that ever printed `INFO: ...`, and the cost of a wrong
+     * boundary is a truncated exception block. A caller that knows it
+     * launched uvicorn says so.
+     *
+     * Only uvicorn, and only because it was measured (RT-106). Gunicorn's
+     * default `[%(asctime)s] [%(process)d] [%(levelname)s]` and Django's
+     * `runserver` output are different formats and get no envelope until one
+     * of them is run and read.
+     */
+    readonly server?: "uvicorn";
+}
+export declare function createPythonRuntimeAdapter(options?: PythonRuntimeAdapterOptions): RuntimeAdapter;
+//# sourceMappingURL=python-runtime-adapter.d.ts.map

package/dist/python-runtime-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-runtime-adapter.d.ts","sourceRoot":"","sources":["../src/python-runtime-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,sCAAsC,CAAC;AAShG,MAAM,WAAW,2BAA2B;IAC1C,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,2BAAgC,GAAG,cAAc,CA4BpG"}

package/dist/python-runtime-adapter.js

@@ -0,0 +1,52 @@
+/**
+ * The concrete `RuntimeAdapter` for Python — the second language, and the
+ * first one to test whether the seam `@descryy/runtime-backend-observation`
+ * defines is genuinely language-neutral or merely V8-shaped.
+ *
+ * It was not, in two places, and both were fixed in the seam rather than
+ * worked around here:
+ *
+ * - `LineClassifier` had no notion of a line that ends a block and belongs
+ *   to it, because a V8 header names its exception up front. A CPython
+ *   traceback names it last. `isTrailer` is that concept, added
+ *   language-neutrally.
+ * - `StackTrace.frames` had no documented order, because with one language
+ *   nothing ever had to convert. Python prints the opposite of V8. The
+ *   contract now states most-recent-first and this adapter reverses.
+ *
+ * Both are recorded because they are the general lesson of adding a second
+ * anything: a seam with one implementation is a seam in name only, and the
+ * defects it hides are silent ones — a truncated traceback and a
+ * backwards frame list both look like well-formed output.
+ */
+import { createLogCollector } from "@descryy/runtime-backend-observation";
+import { createPythonLineClassifier } from "./python-frame-parsing.js";
+import { createUvicornLogEnvelope } from "./python-log-envelopes.js";
+import { createPythonSourceLocationResolver } from "./python-source-location-resolver.js";
+import { createPythonStackTraceParser } from "./python-stack-trace-parser.js";
+export function createPythonRuntimeAdapter(options = {}) {
+    const sourceLocationResolver = createPythonSourceLocationResolver();
+    const stackTraceParser = createPythonStackTraceParser(sourceLocationResolver);
+    function createBackendCollectors(sources) {
+        return sources.map((source) => createLogCollector({
+            source,
+            // One classifier per collector, never shared: it carries per-stream
+            // state, and two processes' output must not prime each other.
+            classifier: createPythonLineClassifier(),
+            stackTraceParser,
+            // One envelope per collector, never shared: it holds the current
+            // record's fields, and two processes' output must not attribute
+            // each other's. Its whole contribution here is `startsRecord` —
+            // nothing is stripped from a Python traceback (RT-106).
+            ...(options.server === "uvicorn" ? { envelope: createUvicornLogEnvelope() } : {}),
+            ...(options.service !== undefined ? { service: options.service } : {}),
+        }));
+    }
+    return {
+        language: "python",
+        stackTraceParser,
+        sourceLocationResolver,
+        createBackendCollectors,
+    };
+}
+//# sourceMappingURL=python-runtime-adapter.js.map

package/dist/python-runtime-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-runtime-adapter.js","sourceRoot":"","sources":["../src/python-runtime-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kCAAkC,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAwB9E,MAAM,UAAU,0BAA0B,CAAC,UAAuC,EAAE;IAClF,MAAM,sBAAsB,GAAG,kCAAkC,EAAE,CAAC;IACpE,MAAM,gBAAgB,GAAG,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;IAE9E,SAAS,uBAAuB,CAAC,OAAuC;QACtE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAC5B,kBAAkB,CAAC;YACjB,MAAM;YACN,oEAAoE;YACpE,8DAA8D;YAC9D,UAAU,EAAE,0BAA0B,EAAE;YACxC,gBAAgB;YAChB,iEAAiE;YACjE,gEAAgE;YAChE,gEAAgE;YAChE,wDAAwD;YACxD,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,wBAAwB,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjF,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvE,CAAC,CACH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,QAAQ;QAClB,gBAAgB;QAChB,sBAAsB;QACtB,uBAAuB;KACxB,CAAC;AACJ,CAAC"}

package/dist/python-source-location-resolver.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Python `SourceLocationResolver`.
+ *
+ * **Every location is `self-contained`, and that is a positive claim rather
+ * than a fallback.** CPython captures the path and line of the `.py` file it
+ * is actually executing; there is no compilation step, no separate map, and
+ * therefore nothing that can drift or go missing. The frame IS the answer.
+ * Contrast the Node resolver, which must decide between four values because
+ * a source map is a second file that can be absent, stale, or wrong.
+ *
+ * This is the first resolver in the codebase for which the reliability
+ * decision is genuinely trivial, and the RT-003 enum already anticipates it:
+ * `self-contained` means "nothing was lost", not "we didn't look".
+ *
+ * **What this deliberately does not do:** check that the file exists on
+ * disk, or that its current contents still match what ran. Neither would
+ * change the reliability value — `self-contained` is a statement about the
+ * *mechanism*, not about whether the working tree has since been edited —
+ * and a stat call per frame would buy nothing but latency. CPython's
+ * pseudo-files (`<string>`, `<stdin>`, `<frozen importlib._bootstrap>`) are
+ * passed through verbatim for the same reason: they are the honest location,
+ * and rewriting them to null would discard real information.
+ *
+ * `column` is always null. CPython does not print columns; 3.11+ prints a
+ * caret line under the failing expression, from which a column *could* be
+ * inferred by counting characters. That inference is not made here — it
+ * would be a derived guess presented in a field callers read as captured
+ * fact, and the caret line is preserved verbatim in `StackFrame.raw`
+ * regardless.
+ */
+import type { SourceLocationResolver } from "@descryy/runtime-backend-observation";
+export declare function createPythonSourceLocationResolver(): SourceLocationResolver;
+//# sourceMappingURL=python-source-location-resolver.d.ts.map

package/dist/python-source-location-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-source-location-resolver.d.ts","sourceRoot":"","sources":["../src/python-source-location-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAoB,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAErG,wBAAgB,kCAAkC,IAAI,sBAAsB,CAiB3E"}

package/dist/python-source-location-resolver.js

@@ -0,0 +1,49 @@
+/**
+ * Python `SourceLocationResolver`.
+ *
+ * **Every location is `self-contained`, and that is a positive claim rather
+ * than a fallback.** CPython captures the path and line of the `.py` file it
+ * is actually executing; there is no compilation step, no separate map, and
+ * therefore nothing that can drift or go missing. The frame IS the answer.
+ * Contrast the Node resolver, which must decide between four values because
+ * a source map is a second file that can be absent, stale, or wrong.
+ *
+ * This is the first resolver in the codebase for which the reliability
+ * decision is genuinely trivial, and the RT-003 enum already anticipates it:
+ * `self-contained` means "nothing was lost", not "we didn't look".
+ *
+ * **What this deliberately does not do:** check that the file exists on
+ * disk, or that its current contents still match what ran. Neither would
+ * change the reliability value — `self-contained` is a statement about the
+ * *mechanism*, not about whether the working tree has since been edited —
+ * and a stat call per frame would buy nothing but latency. CPython's
+ * pseudo-files (`<string>`, `<stdin>`, `<frozen importlib._bootstrap>`) are
+ * passed through verbatim for the same reason: they are the honest location,
+ * and rewriting them to null would discard real information.
+ *
+ * `column` is always null. CPython does not print columns; 3.11+ prints a
+ * caret line under the failing expression, from which a column *could* be
+ * inferred by counting characters. That inference is not made here — it
+ * would be a derived guess presented in a field callers read as captured
+ * fact, and the caret line is preserved verbatim in `StackFrame.raw`
+ * regardless.
+ */
+export function createPythonSourceLocationResolver() {
+    return {
+        // The interface is async because other languages must do I/O to answer
+        // (Node reads a source map, a JVM reader would read a LineNumberTable).
+        // Python genuinely does not, so this body never awaits — returning a
+        // resolved promise rather than inventing work to look symmetrical.
+        resolve(frame) {
+            return Promise.resolve({
+                file: frame.file,
+                line: frame.line,
+                column: frame.column,
+                functionName: frame.functionName,
+                reliability: "self-contained",
+                resolvedVia: null,
+            });
+        },
+    };
+}
+//# sourceMappingURL=python-source-location-resolver.js.map

package/dist/python-source-location-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-source-location-resolver.js","sourceRoot":"","sources":["../src/python-source-location-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,MAAM,UAAU,kCAAkC;IAChD,OAAO;QACL,uEAAuE;QACvE,wEAAwE;QACxE,qEAAqE;QACrE,mEAAmE;QACnE,OAAO,CAAC,KAAuB;YAC7B,OAAO,OAAO,CAAC,OAAO,CAAC;gBACrB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,WAAW,EAAE,gBAAgB;gBAC7B,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/python-stack-trace-parser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Composes the pure CPython line-recognition functions
+ * (`python-frame-parsing.ts`) with a `SourceLocationResolver` to implement
+ * the full async `StackTraceParser` contract.
+ *
+ * **The reversal is the load-bearing line in this file.** CPython prints
+ * oldest call first — the banner says so out loud, "most recent call last" —
+ * and `StackTrace.frames` is contractually most-recent-first. Without the
+ * reversal every consumer that reads `frames[0]` as the failing frame would
+ * instead get the process entry point: a wrong answer that looks entirely
+ * well-formed, with the right frames, the right count, and no error
+ * anywhere. Root-cause traversal would point at `main` for every Python
+ * failure ever captured.
+ *
+ * `fidelity` is always reported `"synchronous"`. A CPython traceback is
+ * built by walking the actual frame objects of the executing thread, so
+ * every frame shown is a genuine, unbroken link. What such a traceback
+ * cannot show is the logical caller across an `await` boundary or a thread
+ * hand-off, where the chain truthfully ends — the same hard limit V8 stacks
+ * have, and the same reason this is not reported as
+ * `"concurrency-fragmented"`. Detecting a genuinely lost logical caller
+ * would need interpreter-level task correlation, not text parsing; claiming
+ * fragmentation without that evidence would be a guess.
+ */
+import type { SourceLocationResolver, StackTraceParser } from "@descryy/runtime-backend-observation";
+export declare function createPythonStackTraceParser(resolver: SourceLocationResolver): StackTraceParser;
+//# sourceMappingURL=python-stack-trace-parser.d.ts.map

package/dist/python-stack-trace-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-stack-trace-parser.d.ts","sourceRoot":"","sources":["../src/python-stack-trace-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAIrG,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,sBAAsB,GAAG,gBAAgB,CAmD/F"}

package/dist/python-stack-trace-parser.js

@@ -0,0 +1,75 @@
+/**
+ * Composes the pure CPython line-recognition functions
+ * (`python-frame-parsing.ts`) with a `SourceLocationResolver` to implement
+ * the full async `StackTraceParser` contract.
+ *
+ * **The reversal is the load-bearing line in this file.** CPython prints
+ * oldest call first — the banner says so out loud, "most recent call last" —
+ * and `StackTrace.frames` is contractually most-recent-first. Without the
+ * reversal every consumer that reads `frames[0]` as the failing frame would
+ * instead get the process entry point: a wrong answer that looks entirely
+ * well-formed, with the right frames, the right count, and no error
+ * anywhere. Root-cause traversal would point at `main` for every Python
+ * failure ever captured.
+ *
+ * `fidelity` is always reported `"synchronous"`. A CPython traceback is
+ * built by walking the actual frame objects of the executing thread, so
+ * every frame shown is a genuine, unbroken link. What such a traceback
+ * cannot show is the logical caller across an `await` boundary or a thread
+ * hand-off, where the chain truthfully ends — the same hard limit V8 stacks
+ * have, and the same reason this is not reported as
+ * `"concurrency-fragmented"`. Detecting a genuinely lost logical caller
+ * would need interpreter-level task correlation, not text parsing; claiming
+ * fragmentation without that evidence would be a guess.
+ */
+import { parsePythonFrame } from "./python-frame-parsing.js";
+export function createPythonStackTraceParser(resolver) {
+    return {
+        async parse(rawText) {
+            const lines = rawText.split(/\r\n|\r|\n/);
+            const frames = [];
+            for (const line of lines) {
+                const raw = parsePythonFrame(line);
+                // Continuation lines (source text, 3.11+ caret markers) and the
+                // banner and trailer parse to null here. They are real parts of the
+                // block and are preserved in the raw text the collector keeps; they
+                // are simply not frames and none is fabricated into one.
+                if (raw === null)
+                    continue;
+                const location = await resolver.resolve({
+                    file: raw.file,
+                    line: raw.line,
+                    column: null,
+                    functionName: raw.functionName,
+                });
+                frames.push({ location, raw: line });
+            }
+            if (frames.length === 0) {
+                // Nothing frame-shaped at all — not recognisable as a CPython
+                // traceback, per this interface's contract: null, never an
+                // empty-but-structured StackTrace standing in for "couldn't parse".
+                return null;
+            }
+            // CPython prints oldest-first; the contract is most-recent-first.
+            //
+            // `primaryFrameIndex` is required so that every adapter states an
+            // answer rather than inheriting one (RT-083). Python's is 0 **after
+            // the reversal on this line** — the last frame CPython prints is the
+            // one that raised, and reversing puts it first.
+            //
+            // **Corrected from the value's first draft**, which justified index 0
+            // with "CPython prints no frames of its own above the application's".
+            // That is measurably false: `json.loads("{not json}")` called from a
+            // two-deep application chain prints
+            // `File "/usr/lib/python3.12/json/decoder.py", line 353, in raw_decode`
+            // as the LAST frame, i.e. the innermost — three stdlib frames sit
+            // above the application's own. Index 0 is still correct, but for the
+            // other reason: it marks the failure site, not the nearest owned
+            // code, and the contract says outright that a path-shaped stdlib
+            // filter "would break on any application that legitimately fails
+            // inside a library frame."
+            return { fidelity: "synchronous", frames: frames.reverse(), primaryFrameIndex: 0 };
+        },
+    };
+}
+//# sourceMappingURL=python-stack-trace-parser.js.map

package/dist/python-stack-trace-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-stack-trace-parser.js","sourceRoot":"","sources":["../src/python-stack-trace-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,UAAU,4BAA4B,CAAC,QAAgC;IAC3E,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,OAAe;YACzB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YAE1C,MAAM,MAAM,GAAiB,EAAE,CAAC;YAChC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;gBACnC,gEAAgE;gBAChE,oEAAoE;gBACpE,oEAAoE;gBACpE,yDAAyD;gBACzD,IAAI,GAAG,KAAK,IAAI;oBAAE,SAAS;gBAE3B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC;oBACtC,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,MAAM,EAAE,IAAI;oBACZ,YAAY,EAAE,GAAG,CAAC,YAAY;iBAC/B,CAAC,CAAC;gBACH,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,CAAC;YAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxB,8DAA8D;gBAC9D,2DAA2D;gBAC3D,oEAAoE;gBACpE,OAAO,IAAI,CAAC;YACd,CAAC;YAED,kEAAkE;YAClE,EAAE;YACF,kEAAkE;YAClE,oEAAoE;YACpE,qEAAqE;YACrE,gDAAgD;YAChD,EAAE;YACF,sEAAsE;YACtE,sEAAsE;YACtE,qEAAqE;YACrE,oCAAoC;YACpC,wEAAwE;YACxE,kEAAkE;YAClE,qEAAqE;YACrE,iEAAiE;YACjE,iEAAiE;YACjE,iEAAiE;YACjE,2BAA2B;YAC3B,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,EAAE,iBAAiB,EAAE,CAAC,EAAE,CAAC;QACrF,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@descryy/runtime-adapter-python",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Python runtime adapter: CPython traceback parsing, self-contained source locations, the concrete RuntimeAdapter for Python.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@descryy/runtime-contracts": "*",
+    "@descryy/runtime-backend-observation": "*"
+  }
+}