@descryy/runtime-adapter-python 0.3.0 → 0.4.0

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

@@ -1,39 +1,23 @@
 /**
- * Python `SourceLocationResolver`.
+ * 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.
+ * Every location is `self-contained` (a positive claim, not a fallback):
+ * CPython captures the path/line of the .py file it's actually executing,
+ * no compile step or map to drift. Contrast the Node resolver, which must
+ * choose between four values because a source map can be absent/stale/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".
+ * Deliberately does not check the file exists on disk or still matches what
+ * ran — `self-contained` is a statement about mechanism, not the working
+ * tree, and a stat call per frame buys only latency. Pseudo-files
+ * (`<string>`, `<stdin>`, `<frozen importlib._bootstrap>`) pass through verbatim.
  *
- * **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.
+ * `column` is always null — CPython doesn't print one. 3.11+'s caret line
+ * could be used to infer a column by counting characters, but that would be
+ * a derived guess in a field callers read as fact; the caret line stays verbatim in `StackFrame.raw`.
  */
 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.
+        // Async to satisfy the interface (other languages do real I/O here); Python never awaits.
         resolve(frame) {
             return Promise.resolve({
                 file: frame.file,

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

@@ -1 +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"}
+{"version":3,"file":"python-source-location-resolver.js","sourceRoot":"","sources":["../src/python-source-location-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,MAAM,UAAU,kCAAkC;IAChD,OAAO;QACL,0FAA0F;QAC1F,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

@@ -1,26 +1,16 @@
 /**
- * Composes the pure CPython line-recognition functions
- * (`python-frame-parsing.ts`) with a `SourceLocationResolver` to implement
- * the full async `StackTraceParser` contract.
+ * Composes the pure CPython line-recognition functions (python-frame-parsing.ts)
+ * with a SourceLocationResolver to implement the 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.
+ * The reversal is the load-bearing line: CPython prints oldest call first
+ * ("most recent call last") but StackTrace.frames is contractually
+ * most-recent-first. Without it, `frames[0]` would be the process entry
+ * point — well-formed-looking but wrong, and root-cause traversal would
+ * point at `main` for every Python failure.
  *
- * `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.
+ * `fidelity` is always `"synchronous"` — walks real frame objects of the
+ * executing thread, but cannot show a logical caller across an await
+ * boundary or thread hand-off, same limit V8 stacks have.
  */
 import type { SourceLocationResolver, StackTraceParser } from "@descryy/runtime-backend-observation";
 export declare function createPythonStackTraceParser(resolver: SourceLocationResolver): StackTraceParser;

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

@@ -1 +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"}
+{"version":3,"file":"python-stack-trace-parser.d.ts","sourceRoot":"","sources":["../src/python-stack-trace-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAIrG,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,sBAAsB,GAAG,gBAAgB,CAkC/F"}

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

@@ -1,26 +1,16 @@
 /**
- * Composes the pure CPython line-recognition functions
- * (`python-frame-parsing.ts`) with a `SourceLocationResolver` to implement
- * the full async `StackTraceParser` contract.
+ * Composes the pure CPython line-recognition functions (python-frame-parsing.ts)
+ * with a SourceLocationResolver to implement the 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.
+ * The reversal is the load-bearing line: CPython prints oldest call first
+ * ("most recent call last") but StackTrace.frames is contractually
+ * most-recent-first. Without it, `frames[0]` would be the process entry
+ * point — well-formed-looking but wrong, and root-cause traversal would
+ * point at `main` for every Python failure.
  *
- * `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.
+ * `fidelity` is always `"synchronous"` — walks real frame objects of the
+ * executing thread, but cannot show a logical caller across an await
+ * boundary or thread hand-off, same limit V8 stacks have.
  */
 import { parsePythonFrame } from "./python-frame-parsing.js";
 export function createPythonStackTraceParser(resolver) {
@@ -30,10 +20,7 @@ export function createPythonStackTraceParser(resolver) {
             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.
+                // Continuation lines, banner, and trailer parse to null — real parts of the block, never fabricated into a frame.
                 if (raw === null)
                     continue;
                 const location = await resolver.resolve({
@@ -45,29 +32,15 @@ export function createPythonStackTraceParser(resolver) {
                 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".
+                // Nothing frame-shaped — null, never an empty 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."
+            // primaryFrameIndex 0, after reversal (RT-083): the last frame CPython
+            // prints is the one that raised. Not because CPython prints no frames
+            // above the application's own — it can (three stdlib frames can sit
+            // above it, e.g. json.loads failures) — but because index 0 marks the
+            // failure site, not the nearest owned code; a path-shaped stdlib
+            // filter would break on any app that legitimately fails inside a library frame.
             return { fidelity: "synchronous", frames: frames.reverse(), primaryFrameIndex: 0 };
         },
     };

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

@@ -1 +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"}
+{"version":3,"file":"python-stack-trace-parser.js","sourceRoot":"","sources":["../src/python-stack-trace-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;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,kHAAkH;gBAClH,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,2FAA2F;gBAC3F,OAAO,IAAI,CAAC;YACd,CAAC;YAED,uEAAuE;YACvE,sEAAsE;YACtE,oEAAoE;YACpE,sEAAsE;YACtE,iEAAiE;YACjE,gFAAgF;YAChF,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

@@ -1,9 +1,14 @@
 {
   "name": "@descryy/runtime-adapter-python",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Python runtime adapter: CPython traceback parsing, self-contained source locations, outbound httpx call-site instrumentation, the concrete RuntimeAdapter for Python.",
   "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/descryhq-wq/descry-runtime.git",
+    "directory": "packages/adapter-python"
+  },
   "engines": {
     "node": ">=22.5"
   },
@@ -25,7 +30,7 @@
     "build": "tsc -b"
   },
   "dependencies": {
-    "@descryy/runtime-contracts": "0.2.0",
-    "@descryy/runtime-backend-observation": "0.2.0"
+    "@descryy/runtime-contracts": "0.3.0",
+    "@descryy/runtime-backend-observation": "0.3.0"
   }
 }