@descryy/runtime-adapter-python 0.1.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) Descry
+
+All rights reserved. This software is proprietary and confidential.
+No license, express or implied, to reproduce, distribute, modify, or
+create derivative works is granted except as explicitly agreed in
+writing.

package/dist/outbound-http-instrumentation.d.ts

@@ -2,38 +2,25 @@
  * Where Python's outbound-HTTP instrumentation lives, and how a caller
  * launches a process with it.
  *
- * The artifact itself is Python (`../python-preload/`), so it cannot live in
- * `src/` and be compiled — it is loaded by CPython, not by tsc. It sits in a
- * sibling directory of `src/` and `dist/` and is resolved by walking out of
- * whichever of the two this module is running from, the identical arrangement
- * `jvm-agent/build.ts` already uses for `Agent.java` and for the identical
- * reason: an `import.meta.url`-relative path that stays *inside* `src` or
- * `dist` resolves to a directory that only exists in one of them.
+ * The artifact is Python (`../python-preload/`), loaded by CPython not tsc,
+ * so it can't live in `src/` and be compiled. Sits as a sibling of `src/`
+ * and `dist/`, resolved by walking out of whichever this module runs from —
+ * same arrangement as jvm-agent/build.ts's Agent.java, one hop not two
+ * (this file sits one directory shallower). Getting the hop count wrong
+ * produces a path that exists nowhere and a child process that starts fine
+ * and observes nothing — measured, hence this module's test checks the
+ * directory is really on disk.
  *
- * The hop count is one, not `jvm-agent/build.ts`'s two, because that file
- * sits a directory deeper than this one. Getting it wrong produces a path
- * that exists nowhere and a child process that starts perfectly and observes
- * nothing — measured, not hypothetical, and the reason this module's test
- * asserts the directory is really on disk rather than only that the two
- * spellings of the constant agree with each other.
- *
- * **Env, not a rewritten command.** CPython has no `--import`, and rewriting
- * a caller's command string to inject a flag would be this runtime editing
- * how the application boots. `site` imports a module named `sitecustomize` at
- * interpreter startup, so prepending this directory to `PYTHONPATH` runs the
- * instrumentation before the application's own code through a hook CPython
- * already provides. See `sitecustomize.py` for the one real cost of that
- * mechanism, stated there rather than discovered later.
+ * Env, not a rewritten command: CPython has no `--import`. `site` imports
+ * `sitecustomize` at startup, so prepending this dir to PYTHONPATH runs
+ * instrumentation before the app's own code via a hook CPython already provides.
  */
 /** Absolute path to the directory holding `sitecustomize.py` and the instrumentation it installs. Prepend it to `PYTHONPATH`; never import it from Node. */
 export declare const PYTHON_OUTBOUND_HTTP_PRELOAD_DIR: string;
 /**
  * The environment a Python process must be launched with for its outbound
- * `httpx` calls to be observed.
- *
- * `existingPythonPath` is **prepended to, never replaced**: a target whose own
- * `PYTHONPATH` matters would otherwise stop finding its own modules, which is
- * a way of breaking the application in order to watch it.
+ * httpx calls to be observed. `existingPythonPath` is prepended to, never
+ * replaced — a target's own PYTHONPATH must still resolve its own modules.
  */
 export declare function pythonOutboundHttpEnv(existingPythonPath?: string): {
     readonly PYTHONPATH: string;

package/dist/outbound-http-instrumentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"outbound-http-instrumentation.d.ts","sourceRoot":"","sources":["../src/outbound-http-instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,4JAA4J;AAC5J,eAAO,MAAM,gCAAgC,QAA+D,CAAC;AAE7G;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAOlG"}
+{"version":3,"file":"outbound-http-instrumentation.d.ts","sourceRoot":"","sources":["../src/outbound-http-instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,4JAA4J;AAC5J,eAAO,MAAM,gCAAgC,QAA+D,CAAC;AAE7G;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAOlG"}

package/dist/outbound-http-instrumentation.js

@@ -2,28 +2,18 @@
  * Where Python's outbound-HTTP instrumentation lives, and how a caller
  * launches a process with it.
  *
- * The artifact itself is Python (`../python-preload/`), so it cannot live in
- * `src/` and be compiled — it is loaded by CPython, not by tsc. It sits in a
- * sibling directory of `src/` and `dist/` and is resolved by walking out of
- * whichever of the two this module is running from, the identical arrangement
- * `jvm-agent/build.ts` already uses for `Agent.java` and for the identical
- * reason: an `import.meta.url`-relative path that stays *inside* `src` or
- * `dist` resolves to a directory that only exists in one of them.
+ * The artifact is Python (`../python-preload/`), loaded by CPython not tsc,
+ * so it can't live in `src/` and be compiled. Sits as a sibling of `src/`
+ * and `dist/`, resolved by walking out of whichever this module runs from —
+ * same arrangement as jvm-agent/build.ts's Agent.java, one hop not two
+ * (this file sits one directory shallower). Getting the hop count wrong
+ * produces a path that exists nowhere and a child process that starts fine
+ * and observes nothing — measured, hence this module's test checks the
+ * directory is really on disk.
  *
- * The hop count is one, not `jvm-agent/build.ts`'s two, because that file
- * sits a directory deeper than this one. Getting it wrong produces a path
- * that exists nowhere and a child process that starts perfectly and observes
- * nothing — measured, not hypothetical, and the reason this module's test
- * asserts the directory is really on disk rather than only that the two
- * spellings of the constant agree with each other.
- *
- * **Env, not a rewritten command.** CPython has no `--import`, and rewriting
- * a caller's command string to inject a flag would be this runtime editing
- * how the application boots. `site` imports a module named `sitecustomize` at
- * interpreter startup, so prepending this directory to `PYTHONPATH` runs the
- * instrumentation before the application's own code through a hook CPython
- * already provides. See `sitecustomize.py` for the one real cost of that
- * mechanism, stated there rather than discovered later.
+ * Env, not a rewritten command: CPython has no `--import`. `site` imports
+ * `sitecustomize` at startup, so prepending this dir to PYTHONPATH runs
+ * instrumentation before the app's own code via a hook CPython already provides.
  */
 import { delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -31,11 +21,8 @@ import { fileURLToPath } from "node:url";
 export const PYTHON_OUTBOUND_HTTP_PRELOAD_DIR = fileURLToPath(new URL("../python-preload", import.meta.url));
 /**
  * The environment a Python process must be launched with for its outbound
- * `httpx` calls to be observed.
- *
- * `existingPythonPath` is **prepended to, never replaced**: a target whose own
- * `PYTHONPATH` matters would otherwise stop finding its own modules, which is
- * a way of breaking the application in order to watch it.
+ * httpx calls to be observed. `existingPythonPath` is prepended to, never
+ * replaced — a target's own PYTHONPATH must still resolve its own modules.
  */
 export function pythonOutboundHttpEnv(existingPythonPath) {
     return {

package/dist/outbound-http-instrumentation.js.map

@@ -1 +1 @@
-{"version":3,"file":"outbound-http-instrumentation.js","sourceRoot":"","sources":["../src/outbound-http-instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,4JAA4J;AAC5J,MAAM,CAAC,MAAM,gCAAgC,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7G;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,kBAA2B;IAC/D,OAAO;QACL,UAAU,EACR,kBAAkB,KAAK,SAAS,IAAI,kBAAkB,KAAK,EAAE;YAC3D,CAAC,CAAC,gCAAgC;YAClC,CAAC,CAAC,GAAG,gCAAgC,GAAG,SAAS,GAAG,kBAAkB,EAAE;KAC7E,CAAC;AACJ,CAAC"}
+{"version":3,"file":"outbound-http-instrumentation.js","sourceRoot":"","sources":["../src/outbound-http-instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,4JAA4J;AAC5J,MAAM,CAAC,MAAM,gCAAgC,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7G;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,kBAA2B;IAC/D,OAAO;QACL,UAAU,EACR,kBAAkB,KAAK,SAAS,IAAI,kBAAkB,KAAK,EAAE;YAC3D,CAAC,CAAC,gCAAgC;YAClC,CAAC,CAAC,GAAG,gCAAgC,GAAG,SAAS,GAAG,kBAAkB,EAAE;KAC7E,CAAC;AACJ,CAAC"}

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

@@ -1,32 +1,19 @@
 /**
- * CPython traceback line shapes — the `LineClassifier` for
- * `ExceptionBlockDetector` plus the raw-text-to-frame-parts extraction that
- * feeds `SourceLocationResolver`.
+ * CPython traceback line shapes — LineClassifier for ExceptionBlockDetector
+ * plus raw-text-to-frame-parts extraction feeding 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:
+ * Differs from V8 in three ways a naive port would miss:
+ * 1. Opening line names no exception — `Traceback (most recent call last):`
+ *    is a fixed banner; type/message arrive after every frame (isPythonTrailerLine).
+ * 2. Frames print oldest-call-first (failing frame last) — reversed in the
+ *    parser, not here, since 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 source text and (3.11+) a caret line — continuation lines
+ *    with no location of their own that isPythonFrameLine must still accept,
+ *    or the first source line would truncate every traceback to one frame.
  *
- * 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.
+ * Banner test isn't anchored to line start (loggers prefix timestamps/levels),
+ * safe because the block detector requires a frame immediately after.
  */
 export interface RawPythonFrame {
     /** `<module>`, `<lambda>` and `<listcomp>` are real CPython function names and are kept verbatim, not nulled. */
@@ -38,13 +25,10 @@ export interface RawPythonFrame {
 /** 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.
+ * Two connective lines CPython prints between chained tracebacks. Deliberately
+ * NOT trailers: each chained traceback is its own complete block, so these
+ * fall through as plain log lines and the second banner opens a second block —
+ * two honest blocks plus the linking sentence, not one block 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;
@@ -56,29 +40,18 @@ export declare function isPythonLocationLine(line: string): boolean;
 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.
+ * Stateful, and the statefulness is the point. The obvious stateless rule —
+ * "a frame is a File line OR anything indented" — is wrong: ExceptionBlockDetector
+ * opens a block the moment isFrame returns true from idle, so a stateless
+ * indent rule turns every indented log line (pretty-printed JSON, a wrapped
+ * message, indented SQL) into a spurious block, and would accept another
+ * runtime's frames verbatim too.
  *
- * 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.
+ * A continuation is only recognised after a File line has been seen —
+ * the actual rule CPython's format obeys. Any other line clears the state,
+ * so a block without a trailer can't leave the classifier primed. Relies on
+ * stream order (guaranteed by ExceptionBlockDetector); a fresh classifier
+ * per collector keeps two processes' output from sharing state.
  */
 export declare function createPythonLineClassifier(): {
     isHeader(line: string): boolean;

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

@@ -1 +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"}
+{"version":3,"file":"python-frame-parsing.d.ts","sourceRoot":"","sources":["../src/python-frame-parsing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;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;AA0BD,0FAA0F;AAC1F,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9D;AA+CD;;;;;GAKG;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;;;;;;;;;;;;;GAaG;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,CA8BA;AAED,yGAAyG;AACzG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAOpE"}

package/dist/python-frame-parsing.js

@@ -1,84 +1,40 @@
 /**
- * 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.
+ * CPython traceback line shapes — LineClassifier for ExceptionBlockDetector
+ * plus raw-text-to-frame-parts extraction feeding SourceLocationResolver.
+ *
+ * Differs from V8 in three ways a naive port would miss:
+ * 1. Opening line names no exception — `Traceback (most recent call last):`
+ *    is a fixed banner; type/message arrive after every frame (isPythonTrailerLine).
+ * 2. Frames print oldest-call-first (failing frame last) — reversed in the
+ *    parser, not here, since 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 source text and (3.11+) a caret line — continuation lines
+ *    with no location of their own that isPythonFrameLine must still accept,
+ *    or the first source line would truncate every traceback to one frame.
+ *
+ * Banner test isn't anchored to line start (loggers prefix timestamps/levels),
+ * safe because the block detector requires a frame immediately after.
  */
 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.
+ * PEP 654's tree gutter, stripped before every other pattern in this file sees a line.
+ *
+ * asyncio.TaskGroup/ExceptionGroup print tracebacks inside a drawn tree
+ * (`  |   File "..."` prefixed with `|`/`+`). FILE_LINE_LOOSE_PATTERN anchors
+ * `^\s*File`, so without stripping, not one frame line matched: measured
+ * through the real detector, 28 lines in -> 28 plain logs out, no EXCEPTION,
+ * no STACK_TRACE, no degradation reported. On a real FastAPI service with an
+ * async TaskGroup failure, two genuine TypeErrors were reported as one.
+ *
+ * Invisible because every fixture here raises from a plain synchronous call
+ * chain — same shape as RT-094's JVM defect (isFrame rejecting JPMS frames,
+ * invisible because every JVM fixture threw from main). A fixture that only
+ * exercises the simple call shape certifies only that shape.
+ *
+ * Stripping is safe: the pattern requires exactly one `|`/`+` plus one space,
+ * repeated for nesting — separator rules like `+-+------- 1 -------` have `-`
+ * right after `+` and are never stripped, staying unrecognised decoration.
+ * An ungrouped traceback has no gutter and is untouched.
  */
 const GROUP_GUTTER = /^(?:[ \t]*[|+] )+/;
 /** Removes PEP 654's tree gutter, if present. Identity for an ordinary traceback line. */
@@ -86,85 +42,52 @@ 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.
+ * The two-space-indented location line. `, in <name>` is optional (absent for
+ * a frame compiled from a bare string). Line number is required by
+ * parsePythonFrame but not the classifier — recognising a line as belonging
+ * to the block is a weaker claim than extracting a location from it.
  */
 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.
+ * strictly deeper than the `File` line's two spaces, so a zero-indent
+ * trailer (`ValueError: ...`) is never 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.
+ * The closing line: `ValueError: bad input`, a dotted `myapp.errors.ConfigError:
+ * ...`, or a bare `SystemExit`. Anchored at zero indent — every frame line is indented.
+ *
+ * The lookahead `(?=[\w.]*[a-z])` (RT-106): without it, this pattern matched
+ * ANY `WORD: text` at zero indent — logging's default format and uvicorn's
+ * whole access-log format. A traceback is written one write() per line, so a
+ * second thread's logging interleaves between them. Measured on real
+ * threaded CPython 3.12, three runs of 25 failures each: 7, 8, 7 reported
+ * with an access-log line as their identity. Damage was symmetric: an INFO:
+ * line right after the banner closed the block immediately (a successful
+ * request reported as the failure), and the real frames then arrived
+ * headerless as a bare stack-trace event — the genuine failure produced no
+ * EXCEPTION at all. Roughly 30% of failures, both halves wrong.
+ *
+ * Why a lowercase letter: exception classes are CapWords (PEP 8), log levels
+ * are upper-case by convention. Measured before accepting the heuristic: 199
+ * stdlib modules walked, 228 distinct BaseException subclasses collected, 0
+ * with no lowercase letter.
+ *
+ * Disclosed recall cost: an all-upper-case exception class (`FOO`) no longer
+ * closes a block — its frames still become a stack-trace event, only the
+ * identity is lost, not the evidence. Does not fix a log line whose first
+ * token happens to be CapWords (`Error: connection refused` from a print) —
+ * the structural fix is a declared LogEnvelope (createUvicornLogEnvelope is
+ * the first); this lookahead is the heuristic an un-enveloped stream gets.
  */
 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.
+ * Two connective lines CPython prints between chained tracebacks. Deliberately
+ * NOT trailers: each chained traceback is its own complete block, so these
+ * fall through as plain log lines and the second banner opens a second block —
+ * two honest blocks plus the linking sentence, not one block missing half its content.
  */
 export const CHAINED_EXCEPTION_CONNECTIVES = [
     "During handling of the above exception, another exception occurred:",
@@ -189,29 +112,18 @@ export function isPythonTrailerLine(line) {
     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.
+ * Stateful, and the statefulness is the point. The obvious stateless rule —
+ * "a frame is a File line OR anything indented" — is wrong: ExceptionBlockDetector
+ * opens a block the moment isFrame returns true from idle, so a stateless
+ * indent rule turns every indented log line (pretty-printed JSON, a wrapped
+ * message, indented SQL) into a spurious block, and would accept another
+ * runtime's frames verbatim too.
+ *
+ * A continuation is only recognised after a File line has been seen —
+ * the actual rule CPython's format obeys. Any other line clears the state,
+ * so a block without a trailer can't leave the classifier primed. Relies on
+ * stream order (guaranteed by ExceptionBlockDetector); a fresh classifier
+ * per collector keeps two processes' output from sharing state.
  */
 export function createPythonLineClassifier() {
     let sawLocationLine = false;
@@ -234,8 +146,7 @@ export function createPythonLineClassifier() {
             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.
+            // Only closes a block that actually had frames — a bare identifier-shaped log line can't close one that never opened.
             if (!sawLocationLine && !isPythonTrailerLine(line))
                 return false;
             if (!isPythonTrailerLine(line))

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

@@ -1 +1 @@
-{"version":3,"file":"python-frame-parsing.js","sourceRoot":"","sources":["../src/python-frame-parsing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAUH,MAAM,cAAc,GAAG,sCAAsC,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAEzC,0FAA0F;AAC1F,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,iBAAiB,GAAG,kEAAkE,CAAC;AAC7F,MAAM,uBAAuB,GAAG,wBAAwB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,WAAW,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,eAAe,GAAG,+CAA+C,CAAC;AAExE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,qEAAqE;IACrE,sEAAsE;CAC9D,CAAC;AAEX,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,cAAc,CAAC,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,uBAAuB,CAAC,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,oBAAoB,CAAC,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,6BAA6B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/E,OAAO,eAAe,CAAC,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,0BAA0B;IAKxC,IAAI,eAAe,GAAG,KAAK,CAAC;IAE5B,OAAO;QACL,QAAQ,CAAC,IAAY;YACnB,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7B,eAAe,GAAG,KAAK,CAAC;gBACxB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,CAAC,IAAY;YAClB,IAAI,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/B,eAAe,GAAG,IAAI,CAAC;gBACvB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,eAAe,IAAI,qBAAqB,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YAChE,eAAe,GAAG,KAAK,CAAC;YACxB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,SAAS,CAAC,IAAY;YACpB,8DAA8D;YAC9D,qEAAqE;YACrE,IAAI,CAAC,eAAe,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC;gBAAE,OAAO,KAAK,CAAC;YACjE,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC7C,eAAe,GAAG,KAAK,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC;IACtE,IAAI,CAAC,KAAK,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"python-frame-parsing.js","sourceRoot":"","sources":["../src/python-frame-parsing.ts"],"names":[],"mappings":"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"}