@descryy/runtime-adapter-ruby 0.0.0

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

@@ -0,0 +1,101 @@
+/**
+ * The two `LogEnvelope`s Ruby actually ships with: the stdlib `Logger`'s
+ * default formatter, and Rails' `ActiveSupport::TaggedLogging`.
+ *
+ * ## Why Ruby needs these when Python does not
+ *
+ * RT-090's leading measurement. A real Ruby backtrace logged through a real
+ * `Logger` detects **correctly** — right frame count, right function, right
+ * line — and reports
+ *
+ * ```
+ * file: "E, [2026-08-19T04:55:54.126478 #763304] ERROR -- : logenv.rb"
+ * ```
+ *
+ * Confident evidence, every number a reviewer would check correct, and the
+ * one field that has to resolve to a graph node resolving to nothing.
+ * Ruby's header pattern is deliberately unanchored — its own comment
+ * anticipates a leveled logger prefixing a timestamp — so the prefix does
+ * not stop it matching; the greedy `(?<file>.+)` before `:(\d+):in` simply
+ * absorbs the prefix into the path. There is no shape that separates a log
+ * prefix from a path containing spaces and a colon, so the wrapper has to
+ * come off first. That is this file.
+ *
+ * By contrast Python needs no **unwrapping**: measured across real Flask
+ * 3.1.3, Django 6.1 and FastAPI 0.141.1, all three print
+ * `Traceback (most recent call last):` at column 0 with CPython's own
+ * two-space frame indent, because `logging` appends `exc_info` unindented.
+ * PHP escapes for a different reason again — its header anchors the location
+ * at the *end* of the line, so a prefix falls outside the capture.
+ *
+ * **This paragraph used to end "and never will", and that was wrong**
+ * (corrected in RT-106). It is right about unwrapping and wrong about the
+ * other half of what this interface does: `startsRecord` is the only way a
+ * collector can learn that a line *ended the previous record*, and Python
+ * is where that matters most, because a traceback is written one `write()`
+ * per line and any concurrent logger interleaves between them.
+ * `createUvicornLogEnvelope` in `packages/adapter-python` is the result —
+ * an envelope whose `unwrap` is the identity function for every line
+ * carrying evidence, and whose entire contribution is the boundary. The
+ * general lesson is that "does this framework decorate its lines" and "does
+ * this framework tell us where a record starts" are separate questions, and
+ * the first one's answer does not settle the second.
+ *
+ * ## Both formats were measured, and the guess was wrong
+ *
+ * Written against real output from ruby 3.4.2 and activesupport 8.1.3.1, not
+ * from documentation. That mattered: the first version of this work assumed
+ * Rails tags looked like `[req-abc] [ERROR] message`, by analogy with every
+ * other framework surveyed. Real `TaggedLogging` emits **no level token at
+ * all** — it installs its own formatter deriving from `SimpleFormatter`,
+ * which discards the severity, pid and timestamp the stdlib formatter would
+ * have written. The two formats are therefore disjoint rather than nested,
+ * which is why they are two envelopes and not one with a branch.
+ *
+ * ## What Rails does NOT give, stated because ASP.NET does give it
+ *
+ * RT-089 found Kestrel writing `Request id "0HNNTFUBAD72K:00000001"` — §16's
+ * framework-correlation row arriving for free. **Rails has no equivalent.**
+ * Its tags are positional and untyped: `[req-ABC123] [user-42]` is two
+ * strings in the order `config.log_tags` listed them, with nothing in the
+ * stream saying which is a request id. The near-universal default is
+ * `[:request_id]` first, and treating the first tag as `requestId` on that
+ * basis would be inferring from a convention rather than reading a
+ * declaration — the exact distinction `fields()` exists to keep. So tags go
+ * to `attrs` verbatim and `requestId` stays null.
+ *
+ * ## The disclosed ambiguity in the tagged format
+ *
+ * `[anything] rest` is not a format Rails owns. An application logging
+ * `[fixture] GET /api/invoices/3 failed` matches it, and this envelope will
+ * unwrap that line to `GET /api/invoices/3 failed`. Bounded, and stated
+ * rather than discovered:
+ *
+ * - The line is a plain log either way, so no exception is created or lost.
+ * - `payload.envelopedRaw` keeps the printed bytes, so nothing is destroyed.
+ * - `startsRecord` firing on it is *correct* for the case that matters — a
+ *   foreign line interleaved into a traceback genuinely does end the record,
+ *   which is the defect `startsRecord` exists to close.
+ *
+ * **That third bullet was wrong, and booting a real Rails application is
+ * what showed it** (RT-111). `TaggedLogging` tags every line of a multi-line
+ * message, so a backtrace arrives as forty lines each looking like a record
+ * header; a boundary on all of them makes a multi-line block impossible to
+ * assemble. `startsRecord` is `false` for this envelope now — see the
+ * comment at the return. The stdlib `Logger` envelope above keeps `true`,
+ * because its prefix genuinely appears once per record.
+ *
+ * The one genuine false positive is a Ruby source line beginning with `[` at
+ * column zero, since `error_highlight` prints the offending source line
+ * unindented — `[1, 2].each do |x|` would be unwrapped. The anchor requires
+ * the bracket at column zero with no leading whitespace, which excludes
+ * every indented source line and every `\tfrom` frame; a top-level array
+ * literal on the raising line is what remains, and it costs a prefix on a
+ * snippet line rather than any part of a frame.
+ */
+import type { LogEnvelope } from "@descryy/runtime-backend-observation";
+/** The stdlib `Logger` default formatter. */
+export declare function createRubyLoggerEnvelope(): LogEnvelope;
+/** Rails' `ActiveSupport::TaggedLogging`. */
+export declare function createRailsTaggedLogEnvelope(): LogEnvelope;
+//# sourceMappingURL=ruby-log-envelopes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ruby-log-envelopes.d.ts","sourceRoot":"","sources":["../src/ruby-log-envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAiC,MAAM,sCAAsC,CAAC;AA0CvG,6CAA6C;AAC7C,wBAAgB,wBAAwB,IAAI,WAAW,CAgCtD;AAED,6CAA6C;AAC7C,wBAAgB,4BAA4B,IAAI,WAAW,CAoD1D"}

package/dist/ruby-log-envelopes.js

@@ -0,0 +1,214 @@
+/**
+ * The two `LogEnvelope`s Ruby actually ships with: the stdlib `Logger`'s
+ * default formatter, and Rails' `ActiveSupport::TaggedLogging`.
+ *
+ * ## Why Ruby needs these when Python does not
+ *
+ * RT-090's leading measurement. A real Ruby backtrace logged through a real
+ * `Logger` detects **correctly** — right frame count, right function, right
+ * line — and reports
+ *
+ * ```
+ * file: "E, [2026-08-19T04:55:54.126478 #763304] ERROR -- : logenv.rb"
+ * ```
+ *
+ * Confident evidence, every number a reviewer would check correct, and the
+ * one field that has to resolve to a graph node resolving to nothing.
+ * Ruby's header pattern is deliberately unanchored — its own comment
+ * anticipates a leveled logger prefixing a timestamp — so the prefix does
+ * not stop it matching; the greedy `(?<file>.+)` before `:(\d+):in` simply
+ * absorbs the prefix into the path. There is no shape that separates a log
+ * prefix from a path containing spaces and a colon, so the wrapper has to
+ * come off first. That is this file.
+ *
+ * By contrast Python needs no **unwrapping**: measured across real Flask
+ * 3.1.3, Django 6.1 and FastAPI 0.141.1, all three print
+ * `Traceback (most recent call last):` at column 0 with CPython's own
+ * two-space frame indent, because `logging` appends `exc_info` unindented.
+ * PHP escapes for a different reason again — its header anchors the location
+ * at the *end* of the line, so a prefix falls outside the capture.
+ *
+ * **This paragraph used to end "and never will", and that was wrong**
+ * (corrected in RT-106). It is right about unwrapping and wrong about the
+ * other half of what this interface does: `startsRecord` is the only way a
+ * collector can learn that a line *ended the previous record*, and Python
+ * is where that matters most, because a traceback is written one `write()`
+ * per line and any concurrent logger interleaves between them.
+ * `createUvicornLogEnvelope` in `packages/adapter-python` is the result —
+ * an envelope whose `unwrap` is the identity function for every line
+ * carrying evidence, and whose entire contribution is the boundary. The
+ * general lesson is that "does this framework decorate its lines" and "does
+ * this framework tell us where a record starts" are separate questions, and
+ * the first one's answer does not settle the second.
+ *
+ * ## Both formats were measured, and the guess was wrong
+ *
+ * Written against real output from ruby 3.4.2 and activesupport 8.1.3.1, not
+ * from documentation. That mattered: the first version of this work assumed
+ * Rails tags looked like `[req-abc] [ERROR] message`, by analogy with every
+ * other framework surveyed. Real `TaggedLogging` emits **no level token at
+ * all** — it installs its own formatter deriving from `SimpleFormatter`,
+ * which discards the severity, pid and timestamp the stdlib formatter would
+ * have written. The two formats are therefore disjoint rather than nested,
+ * which is why they are two envelopes and not one with a branch.
+ *
+ * ## What Rails does NOT give, stated because ASP.NET does give it
+ *
+ * RT-089 found Kestrel writing `Request id "0HNNTFUBAD72K:00000001"` — §16's
+ * framework-correlation row arriving for free. **Rails has no equivalent.**
+ * Its tags are positional and untyped: `[req-ABC123] [user-42]` is two
+ * strings in the order `config.log_tags` listed them, with nothing in the
+ * stream saying which is a request id. The near-universal default is
+ * `[:request_id]` first, and treating the first tag as `requestId` on that
+ * basis would be inferring from a convention rather than reading a
+ * declaration — the exact distinction `fields()` exists to keep. So tags go
+ * to `attrs` verbatim and `requestId` stays null.
+ *
+ * ## The disclosed ambiguity in the tagged format
+ *
+ * `[anything] rest` is not a format Rails owns. An application logging
+ * `[fixture] GET /api/invoices/3 failed` matches it, and this envelope will
+ * unwrap that line to `GET /api/invoices/3 failed`. Bounded, and stated
+ * rather than discovered:
+ *
+ * - The line is a plain log either way, so no exception is created or lost.
+ * - `payload.envelopedRaw` keeps the printed bytes, so nothing is destroyed.
+ * - `startsRecord` firing on it is *correct* for the case that matters — a
+ *   foreign line interleaved into a traceback genuinely does end the record,
+ *   which is the defect `startsRecord` exists to close.
+ *
+ * **That third bullet was wrong, and booting a real Rails application is
+ * what showed it** (RT-111). `TaggedLogging` tags every line of a multi-line
+ * message, so a backtrace arrives as forty lines each looking like a record
+ * header; a boundary on all of them makes a multi-line block impossible to
+ * assemble. `startsRecord` is `false` for this envelope now — see the
+ * comment at the return. The stdlib `Logger` envelope above keeps `true`,
+ * because its prefix genuinely appears once per record.
+ *
+ * The one genuine false positive is a Ruby source line beginning with `[` at
+ * column zero, since `error_highlight` prints the offending source line
+ * unindented — `[1, 2].each do |x|` would be unwrapped. The anchor requires
+ * the bracket at column zero with no leading whitespace, which excludes
+ * every indented source line and every `\tfrom` frame; a top-level array
+ * literal on the raising line is what remains, and it costs a prefix on a
+ * snippet line rather than any part of a frame.
+ */
+/**
+ * `E, [2026-08-19T04:55:36.409952 #762887] ERROR -- : message`
+ *
+ * `Logger::Formatter::Format` is `"%s, [%s #%d] %5s -- %s: %s\n"` — severity
+ * letter, timestamp, pid, right-padded severity label, progname, message.
+ * Anchored at the start and requiring every field, because a partial match
+ * is evidence the line is not a header rather than a reason to guess at one.
+ * `progname` is `[^:]*` and routinely empty, which is what the bare `-- : `
+ * in the measured output is.
+ */
+const STDLIB_HEADER = /^([A-Z]), \[([^\]]*) #(\d+)\] +(\w+) -- ([^:]*): /;
+/**
+ * One or more `[tag] ` groups at column zero.
+ *
+ * `ActiveSupport::TaggedLogging::Formatter#tagged` writes `"[#{tag}] "` per
+ * tag and then the message, with no other decoration — verified against
+ * activesupport 8.1.3.1 for both a single tag and two.
+ */
+const TAGGED_HEADER = /^((?:\[[^\]]*\] )+)/;
+/** Every `[tag]` inside a matched tag run. */
+const TAG = /\[([^\]]*)\]/g;
+/**
+ * A continuation line, for both envelopes.
+ *
+ * Neither Ruby formatter wraps anything after the record's first line — the
+ * `full_message` body (blank line, `error_highlight` snippet, caret line,
+ * `\tfrom` frames) is written through untouched. Measured for both. So
+ * "unwrap a continuation" is the identity function here, and the only thing
+ * an envelope has to get right is not mistaking a continuation for a header.
+ *
+ * This is the property that makes Ruby cheap and .NET expensive: .NET
+ * indents every line of the record and so must strip on every line.
+ */
+function continuation(line) {
+    return { content: line, startsRecord: false };
+}
+/** The stdlib `Logger` default formatter. */
+export function createRubyLoggerEnvelope() {
+    let fields = null;
+    return {
+        frameworkName: "ruby-stdlib-logger",
+        unwrap(line) {
+            const match = STDLIB_HEADER.exec(line);
+            if (match === null)
+                return continuation(line);
+            const [, severityChar, timestamp, pid, level, progname] = match;
+            fields = {
+                level: level ?? null,
+                // `progname` is Logger's own word for it and is usually empty. Mapped
+                // to `category` because that is the field's meaning, not because
+                // Ruby uses the word.
+                category: progname !== undefined && progname !== "" ? progname : null,
+                // Ruby's stdlib logger has no concept of a request. Null rather than
+                // scavenged from the message text — that is `extractCorrelationIds`'
+                // job and it still runs on the unwrapped content.
+                requestId: null,
+                attrs: {
+                    severityChar: severityChar ?? "",
+                    timestamp: timestamp ?? "",
+                    pid: pid ?? "",
+                },
+            };
+            return { content: line.slice(match[0].length), startsRecord: true };
+        },
+        fields: () => fields,
+    };
+}
+/** Rails' `ActiveSupport::TaggedLogging`. */
+export function createRailsTaggedLogEnvelope() {
+    let fields = null;
+    return {
+        frameworkName: "rails-tagged-logging",
+        unwrap(line) {
+            const match = TAGGED_HEADER.exec(line);
+            if (match === null)
+                return continuation(line);
+            const run = match[1] ?? "";
+            const tags = [...run.matchAll(TAG)].map((m) => m[1] ?? "");
+            fields = {
+                // TaggedLogging's formatter derives from SimpleFormatter, which
+                // writes no severity. Measured: the level is genuinely absent from
+                // the stream, not merely unparsed.
+                level: null,
+                category: null,
+                // Positional and untyped — see this file's header. Rails does not
+                // say which tag is a request id, so neither does this.
+                requestId: null,
+                attrs: Object.fromEntries(tags.map((t, i) => [`tag${i}`, t])),
+            };
+            // **`false`, and this is the one place in this repository where a
+            // recognised header does NOT declare a record boundary** (RT-111).
+            //
+            // `ActiveSupport::TaggedLogging::Formatter` tags **every line** of a
+            // multi-line message, not the first. So a Rails backtrace arrives as
+            // forty consecutive lines each carrying the same `[request-id] ` run,
+            // and each of them looks exactly like a record header. Claiming a
+            // boundary on all of them makes a multi-line exception block
+            // impossible to assemble: the collector flushes the detector before
+            // every line, so every frame becomes its own one-line STACK_TRACE.
+            //
+            // Measured against a live Rails 8.0.4 failure: **80 evidence records,
+            // 60 of them single-frame STACK_TRACEs, zero EXCEPTIONs**, from a
+            // grammar that recognised every line correctly.
+            //
+            // RT-103 wrote `true` here with the argument that a foreign line
+            // interleaved into a backtrace genuinely does end the record. That
+            // argument is sound for a format where only the record's first line
+            // carries the prefix — Kestrel's, and Ruby's own stdlib `Logger`
+            // above, both of which keep `true`. It is false for a format where
+            // the prefix is per *line*, and Rails' is. The distinction is not
+            // "does this envelope recognise the line" but "does this framework's
+            // marker mean a record began", and only the second one may be
+            // reported here.
+            return { content: line.slice(run.length), startsRecord: false };
+        },
+        fields: () => fields,
+    };
+}
+//# sourceMappingURL=ruby-log-envelopes.js.map

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

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

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

@@ -0,0 +1,51 @@
+/**
+ * The concrete `RuntimeAdapter` for Ruby.
+ *
+ * Ruby's grammar needed no seam changes: unlike CPython (which forced
+ * `isTrailer` and the most-recent-first contract into existence — RT-035),
+ * Ruby's header-embeds-the-innermost-frame shape and native
+ * most-recent-first order both fit the existing `LineClassifier` /
+ * `StackTrace.frames` contracts without modification. See
+ * `ruby-frame-parsing.ts` for why, and for the one disclosed gap (a
+ * top-level raise with zero caller frames) that shape leaves behind.
+ */
+import type { RuntimeAdapter } from "@descryy/runtime-backend-observation";
+export interface RubyRuntimeAdapterOptions {
+    /** Attributed on every emitted Evidence's `service` field (plan §16.7). Omit when not applicable. */
+    readonly service?: string;
+    /**
+     * The framework whose exception reporting this process uses (§16, RT-111).
+     *
+     * **Declared, never sniffed**, the same rule ASP.NET's option follows.
+     * Rails does not log `Exception#full_message` — `ActionDispatch::DebugExceptions`
+     * composes `Class (message):` followed by bare `file:line:in 'name'` lines
+     * with no `from` prefix, which matches neither of Ruby's two patterns.
+     * Measured against a live Rails 8.0.4 request pipeline: **77 lines in,
+     * zero exceptions out.**
+     *
+     * Selecting this swaps in a different classifier *and* a different stack
+     * trace parser, because the two grammars disagree about where the raise
+     * site is: Ruby's header is the innermost frame, Rails' header has no
+     * location at all.
+     *
+     * Detecting it from a line that looks like Rails output would apply this
+     * grammar to a plain Ruby process that happened to print one, and Rails'
+     * frame shape is loose enough that the cost would be silent.
+     *
+     * `"sinatra"` is the same declared-not-sniffed answer for Sinatra
+     * **running in production mode** (`set :environment, :production`) —
+     * measured (plan 1C) against a real Sinatra 4.1.1 process:
+     * `Sinatra::Base#dump_errors!` composes `TIMESTAMP - Class - message:`
+     * followed by raw, `from`-less `Exception#backtrace` lines, matching
+     * neither of Ruby's own two patterns. See `sinatra-frame-parsing.ts`.
+     *
+     * Bare Rack — no framework at all — needs **no** option here: its own
+     * dispatch frames (`Rackup::Handler::WEBrick#service`, …) print in
+     * Ruby's ordinary `file:line:in 'name'` / `from …` shape and the plain
+     * classifier below reads them unchanged. Measured, not assumed — see
+     * `rack-framework-lifecycle.test.ts`.
+     */
+    readonly framework?: "rails" | "sinatra";
+}
+export declare function createRubyRuntimeAdapter(options?: RubyRuntimeAdapterOptions): RuntimeAdapter;
+//# sourceMappingURL=ruby-runtime-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ruby-runtime-adapter.d.ts","sourceRoot":"","sources":["../src/ruby-runtime-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,sCAAsC,CAAC;AAahG,MAAM,WAAW,yBAAyB;IACxC,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC1C;AAED,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,yBAA8B,GAAG,cAAc,CAsChG"}

package/dist/ruby-runtime-adapter.js

@@ -0,0 +1,56 @@
+/**
+ * The concrete `RuntimeAdapter` for Ruby.
+ *
+ * Ruby's grammar needed no seam changes: unlike CPython (which forced
+ * `isTrailer` and the most-recent-first contract into existence — RT-035),
+ * Ruby's header-embeds-the-innermost-frame shape and native
+ * most-recent-first order both fit the existing `LineClassifier` /
+ * `StackTrace.frames` contracts without modification. See
+ * `ruby-frame-parsing.ts` for why, and for the one disclosed gap (a
+ * top-level raise with zero caller frames) that shape leaves behind.
+ */
+import { createLogCollector } from "@descryy/runtime-backend-observation";
+import { createRailsLineClassifier } from "./rails-frame-parsing.js";
+import { createRailsStackTraceParser } from "./rails-stack-trace-parser.js";
+import { createRubyLineClassifier } from "./ruby-frame-parsing.js";
+import { createRailsTaggedLogEnvelope } from "./ruby-log-envelopes.js";
+import { createRubySourceLocationResolver } from "./ruby-source-location-resolver.js";
+import { createRubyStackTraceParser } from "./ruby-stack-trace-parser.js";
+import { createSinatraLineClassifier } from "./sinatra-frame-parsing.js";
+import { createSinatraStackTraceParser } from "./sinatra-stack-trace-parser.js";
+export function createRubyRuntimeAdapter(options = {}) {
+    const sourceLocationResolver = createRubySourceLocationResolver();
+    const isRails = options.framework === "rails";
+    const isSinatra = options.framework === "sinatra";
+    const stackTraceParser = isRails
+        ? createRailsStackTraceParser(sourceLocationResolver)
+        : isSinatra
+            ? createSinatraStackTraceParser(sourceLocationResolver)
+            : createRubyStackTraceParser(sourceLocationResolver);
+    function createBackendCollectors(sources) {
+        return sources.map((source) => createLogCollector({
+            source,
+            // Ruby's classifier is stateless (its markers — the "from " prefix
+            // and the trailing ": message" — are unambiguous per-line), but a
+            // fresh instance per collector costs nothing and keeps the
+            // construction pattern identical across every language adapter.
+            classifier: isRails ? createRailsLineClassifier() : isSinatra ? createSinatraLineClassifier() : createRubyLineClassifier(),
+            stackTraceParser,
+            // Rails logs through `ActiveSupport::TaggedLogging` by default, and
+            // the tag run corrupts the file path of every frame (RT-103). The
+            // envelope comes with the framework rather than as a separate
+            // option, because a caller that knows it launched Rails knows both.
+            // Sinatra's `dump_errors!` writes straight to `rack.errors` with no
+            // tag run, so it needs no envelope.
+            ...(isRails ? { envelope: createRailsTaggedLogEnvelope() } : {}),
+            ...(options.service !== undefined ? { service: options.service } : {}),
+        }));
+    }
+    return {
+        language: "ruby",
+        stackTraceParser,
+        sourceLocationResolver,
+        createBackendCollectors,
+    };
+}
+//# sourceMappingURL=ruby-runtime-adapter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ruby-runtime-adapter.js","sourceRoot":"","sources":["../src/ruby-runtime-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE1E,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,gCAAgC,EAAE,MAAM,oCAAoC,CAAC;AACtF,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAwChF,MAAM,UAAU,wBAAwB,CAAC,UAAqC,EAAE;IAC9E,MAAM,sBAAsB,GAAG,gCAAgC,EAAE,CAAC;IAClE,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,KAAK,OAAO,CAAC;IAC9C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC;IAClD,MAAM,gBAAgB,GAAG,OAAO;QAC9B,CAAC,CAAC,2BAA2B,CAAC,sBAAsB,CAAC;QACrD,CAAC,CAAC,SAAS;YACT,CAAC,CAAC,6BAA6B,CAAC,sBAAsB,CAAC;YACvD,CAAC,CAAC,0BAA0B,CAAC,sBAAsB,CAAC,CAAC;IAEzD,SAAS,uBAAuB,CAAC,OAAuC;QACtE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAC5B,kBAAkB,CAAC;YACjB,MAAM;YACN,mEAAmE;YACnE,kEAAkE;YAClE,2DAA2D;YAC3D,gEAAgE;YAChE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,yBAAyB,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,2BAA2B,EAAE,CAAC,CAAC,CAAC,wBAAwB,EAAE;YAC1H,gBAAgB;YAChB,oEAAoE;YACpE,kEAAkE;YAClE,8DAA8D;YAC9D,oEAAoE;YACpE,oEAAoE;YACpE,oCAAoC;YACpC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,4BAA4B,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,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,MAAM;QAChB,gBAAgB;QAChB,sBAAsB;QACtB,uBAAuB;KACxB,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,34 @@
+/**
+ * Ruby `SourceLocationResolver`.
+ *
+ * **Almost every location is `self-contained`, and that is a positive claim
+ * rather than a fallback** — the same category RT-003 already assigns Ruby
+ * backtraces alongside Python tracebacks and PHP traces. A Ruby backtrace
+ * line names the `.rb` file and line the interpreter was actually
+ * executing; there is no compilation step and no separate map that can
+ * drift or go missing. The frame IS the answer.
+ *
+ * **What this deliberately does not do:** check that the file exists on
+ * disk, or that its contents still match what ran. `self-contained` is a
+ * statement about the *mechanism* (nothing was lost in translation), not
+ * about whether the working tree has since been edited.
+ *
+ * **The one exception: `instance_eval`/`eval` frames.** Ruby names their
+ * location `(eval at file.rb:12):1` — `file.rb:12` is where `eval` was
+ * called from, but `1` counts lines *within the evaluated string*, not
+ * within `file.rb`. Opening `file.rb` at line 1 would show unrelated code,
+ * so calling this `self-contained` would be false: something *was* lost —
+ * the line no longer indexes the named file. `isEvalSyntheticPath` detects
+ * Ruby's own synthetic-path shape (verbatim, not reparsed here — the
+ * parser already hands it through unchanged; see `ruby-frame-parsing.ts`)
+ * and this resolver reports `self-contained-eval-line` instead. The path
+ * itself is still reported verbatim, never rewritten to a guessed
+ * `file.rb:12` — a guess could be wrong and nothing downstream could tell.
+ *
+ * `column` is always null. Ruby backtraces never print one — there is
+ * nothing to derive it from, unlike CPython's 3.11+ caret line, so this
+ * isn't even a "could infer but won't" case.
+ */
+import type { SourceLocationResolver } from "@descryy/runtime-backend-observation";
+export declare function createRubySourceLocationResolver(): SourceLocationResolver;
+//# sourceMappingURL=ruby-source-location-resolver.d.ts.map

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

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

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

@@ -0,0 +1,61 @@
+/**
+ * Ruby `SourceLocationResolver`.
+ *
+ * **Almost every location is `self-contained`, and that is a positive claim
+ * rather than a fallback** — the same category RT-003 already assigns Ruby
+ * backtraces alongside Python tracebacks and PHP traces. A Ruby backtrace
+ * line names the `.rb` file and line the interpreter was actually
+ * executing; there is no compilation step and no separate map that can
+ * drift or go missing. The frame IS the answer.
+ *
+ * **What this deliberately does not do:** check that the file exists on
+ * disk, or that its contents still match what ran. `self-contained` is a
+ * statement about the *mechanism* (nothing was lost in translation), not
+ * about whether the working tree has since been edited.
+ *
+ * **The one exception: `instance_eval`/`eval` frames.** Ruby names their
+ * location `(eval at file.rb:12):1` — `file.rb:12` is where `eval` was
+ * called from, but `1` counts lines *within the evaluated string*, not
+ * within `file.rb`. Opening `file.rb` at line 1 would show unrelated code,
+ * so calling this `self-contained` would be false: something *was* lost —
+ * the line no longer indexes the named file. `isEvalSyntheticPath` detects
+ * Ruby's own synthetic-path shape (verbatim, not reparsed here — the
+ * parser already hands it through unchanged; see `ruby-frame-parsing.ts`)
+ * and this resolver reports `self-contained-eval-line` instead. The path
+ * itself is still reported verbatim, never rewritten to a guessed
+ * `file.rb:12` — a guess could be wrong and nothing downstream could tell.
+ *
+ * `column` is always null. Ruby backtraces never print one — there is
+ * nothing to derive it from, unlike CPython's 3.11+ caret line, so this
+ * isn't even a "could infer but won't" case.
+ */
+/**
+ * Ruby's synthetic path for a frame inside `eval`/`instance_eval`:
+ * `(eval)` on <3.4, `(eval at file.rb:12)` on 3.4+ (Feature #19117), and
+ * `(eval at (eval at file.rb:12):3)` when an eval nests inside another
+ * eval — all confirmed against a real `ruby` binary (see
+ * `ruby-call-shapes.test.ts`). `.+` is greedy so a nested case still
+ * matches as a whole; there is nothing to extract from inside it, since
+ * the value is reported verbatim either way.
+ */
+const EVAL_SYNTHETIC_PATH_PATTERN = /^\(eval(?: at .+)?\)$/;
+function isEvalSyntheticPath(file) {
+    return file !== null && EVAL_SYNTHETIC_PATH_PATTERN.test(file);
+}
+export function createRubySourceLocationResolver() {
+    return {
+        // Async to satisfy the interface; Ruby needs no I/O to answer, so this
+        // never awaits — same as the Python resolver, for the same reason.
+        resolve(frame) {
+            return Promise.resolve({
+                file: frame.file,
+                line: frame.line,
+                column: frame.column,
+                functionName: frame.functionName,
+                reliability: isEvalSyntheticPath(frame.file) ? "self-contained-eval-line" : "self-contained",
+                resolvedVia: null,
+            });
+        },
+    };
+}
+//# sourceMappingURL=ruby-source-location-resolver.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ruby-source-location-resolver.js","sourceRoot":"","sources":["../src/ruby-source-location-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH;;;;;;;;GAQG;AACH,MAAM,2BAA2B,GAAG,uBAAuB,CAAC;AAE5D,SAAS,mBAAmB,CAAC,IAAmB;IAC9C,OAAO,IAAI,KAAK,IAAI,IAAI,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,gCAAgC;IAC9C,OAAO;QACL,uEAAuE;QACvE,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,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,gBAAgB;gBAC5F,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,24 @@
+/**
+ * Composes the pure Ruby line-recognition functions
+ * (`ruby-frame-parsing.ts`) with a `SourceLocationResolver` to implement the
+ * full async `StackTraceParser` contract.
+ *
+ * **No reversal.** Unlike CPython, Ruby prints most-recent-call first
+ * already — the header line IS the innermost frame, and each `from` line
+ * walks outward toward `<main>`. `StackTrace.frames` is contractually
+ * most-recent-first, so this parser emits frames in the order it reads
+ * them. (Of the languages implemented against this seam so far, CPython is
+ * the outlier that reverses; V8, and now Ruby, both print native
+ * most-recent-first order.)
+ *
+ * `fidelity` is always reported `"synchronous"`. A Ruby backtrace is built
+ * by walking the actual call frames of the raising thread/fiber — every
+ * frame shown is a genuine, unbroken link in the call chain that was
+ * executing. What it cannot show is a logical caller across a `Thread.new`
+ * hand-off or a Fiber resumption boundary, the same class of limit V8 and
+ * CPython stacks share; detecting that would need scheduler-level task
+ * correlation, not text parsing, so it is not claimed here.
+ */
+import type { SourceLocationResolver, StackTraceParser } from "@descryy/runtime-backend-observation";
+export declare function createRubyStackTraceParser(resolver: SourceLocationResolver): StackTraceParser;
+//# sourceMappingURL=ruby-stack-trace-parser.d.ts.map

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

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

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

@@ -0,0 +1,71 @@
+/**
+ * Composes the pure Ruby line-recognition functions
+ * (`ruby-frame-parsing.ts`) with a `SourceLocationResolver` to implement the
+ * full async `StackTraceParser` contract.
+ *
+ * **No reversal.** Unlike CPython, Ruby prints most-recent-call first
+ * already — the header line IS the innermost frame, and each `from` line
+ * walks outward toward `<main>`. `StackTrace.frames` is contractually
+ * most-recent-first, so this parser emits frames in the order it reads
+ * them. (Of the languages implemented against this seam so far, CPython is
+ * the outlier that reverses; V8, and now Ruby, both print native
+ * most-recent-first order.)
+ *
+ * `fidelity` is always reported `"synchronous"`. A Ruby backtrace is built
+ * by walking the actual call frames of the raising thread/fiber — every
+ * frame shown is a genuine, unbroken link in the call chain that was
+ * executing. What it cannot show is a logical caller across a `Thread.new`
+ * hand-off or a Fiber resumption boundary, the same class of limit V8 and
+ * CPython stacks share; detecting that would need scheduler-level task
+ * correlation, not text parsing, so it is not claimed here.
+ */
+import { parseRubyHeaderFrame, parseRubyFromFrame } from "./ruby-frame-parsing.js";
+export function createRubyStackTraceParser(resolver) {
+    return {
+        async parse(rawText) {
+            const lines = rawText.split(/\r\n|\r|\n/);
+            const frames = [];
+            for (const line of lines) {
+                // A header line's trailing `: message` makes it more specific than
+                // a bare `from` line, so it is tried first; a genuine `from` line
+                // never matches the header pattern (see FROM_FRAME_PATTERN's
+                // required prefix), so trying both in either order is safe.
+                const raw = parseRubyHeaderFrame(line) ?? parseRubyFromFrame(line);
+                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 Ruby
+                // backtrace, per this interface's contract: null, never an
+                // empty-but-structured StackTrace standing in for "couldn't parse".
+                return null;
+            }
+            // `primaryFrameIndex` is required so that every adapter states an
+            // answer rather than inheriting one (RT-083). Ruby's is 0, and the
+            // reason is structural rather than incidental: **Ruby's header line
+            // IS the raise site** (`file:line:in 'method': message (Class)`), it
+            // is parsed as a frame, and it is always the first line of the block.
+            // Ruby prints no unwinding frames above it — the `from` lines walk
+            // strictly outward toward `<main>`.
+            //
+            // **It is not necessarily application code, and that is fine.**
+            // Measured: `JSON.parse("{not json}")` from a two-deep call chain
+            // gives a header of
+            // `.../3.4.0/json/common.rb:221:in 'JSON::Ext::Parser.parse': ...`,
+            // a stdlib frame, with the application's own frames below it. Index 0
+            // still names it, because this field marks the failure site rather
+            // than the nearest owned code — see the contract's own note that
+            // nothing here denylists a stdlib path, since that "would break on
+            // any application that legitimately fails inside a library frame."
+            return { fidelity: "synchronous", frames, primaryFrameIndex: 0 };
+        },
+    };
+}
+//# sourceMappingURL=ruby-stack-trace-parser.js.map