# Compatibility Contract

## Immutable baseline

The compatibility baseline is `source-map-support@0.5.21` at upstream tag
commit `888339343236f0912ddc2f635e356e4ed9c0ddf3`. Its official tarball SHA-1
is `04fe7c7f9e1ed2d662233c28cb2b35b9f63f6e4f` and SHA-256 is
`5d9b04ef3e6824fdcf91cfcc03ab427fae486bc6859735805593f51b3554f636`.

The Stackline package targets Node.js 14.15.1 and newer. Native Node source
maps are preferred for ordinary modern Node execution. Compatibility claims
below are for observable residual package behavior, not a claim that every
Node process should install a userland stack formatter.

## Preserved root API

The CommonJS root remains a namespace with six enumerable functions:

1. `wrapCallSite`
2. `getErrorSource`
3. `mapSourcePosition`
4. `retrieveSourceMap`
5. `install`
6. `resetRetrieveHandlers`

The functions retain their synchronous behavior and coordinate conventions:
lines are one-based and `Position.column` is zero-based.

## Preserved installation behavior

- `install()` assigns `Error.prepareStackTrace` once.
- `environment` accepts exactly `auto`, `browser`, and `node`.
- `retrieveFile` and `retrieveSourceMap` add priority providers; the matching
  override option clears the prior list first.
- `hookRequire` wraps `Module.prototype._compile` outside browser mode to keep
  runtime-transpiler content and inline maps.
- `emptyCacheBetweenOperations` can clear map and content caches before stack
  formatting.
- `handleUncaughtExceptions` defaults to the historical Node main-thread
  behavior and can be disabled for another process-level owner.
- Worker threads do not install the uncaught-exception shim.
- `resetRetrieveHandlers()` restores retrieval defaults; it is not a global
  uninstall operation.

## Preserved source-map behavior

- The final matching line or block `sourceMappingURL` comment wins.
- Inline base64 and external maps remain supported.
- Map payloads may be JSON strings or parsed objects.
- Regular Source Map v3 payloads and indexed maps with `sections` remain
  accepted. Section offsets and mapped names are preserved, and the maintained
  `AnyMap` path also retains embedded `sourcesContent` after flattening.
- `sourceRoot`, map-relative sources, mapped names, file paths, URLs, Windows
  drive paths, and `sourcesContent` remain covered.
- A source-map gap returns the precise generated position.
- Eval origins and V8 CallSite formatting remain mapped where recognized,
  including the current native V8 form for a differently named property such
  as `Object.doSomething [as customMethod]`.
- Browser mode recognizes `SourceMap` and `X-SourceMap` response headers.
- Browser auto-detection preserves the historical Electron-renderer exception.
- Custom file and map hooks remain synchronous and ordered.

## VM, generated-code, and deep-entry behavior

A generated filename passed to `vm.runInThisContext()` can be mapped when the
corresponding inline, external, or custom-provided map is available. The
release gate compares this behavior against native Node source maps because a
Node.js 26.8.1 intake run mapped an ordinary file natively but not the
equivalent VM frame. This statement is scoped to the reproduced case.

The historical side-effect entries remain:

- `register` calls `install()`;
- `register-hook-require` calls `install({ hookRequire: true })`;
- `browser-source-map-support` supplies the browser distribution.

Both extensionless and `.js` forms are exported for those historical entries.

## Browser behavior

The standalone browser bundle targets ES2015 and preserves CommonJS, named AMD
module `browser-source-map-support`, and `globalThis.sourceMapSupport` delivery.
The six-function namespace and custom map tracing are tested in each form.

The root `browser` plus `import` condition selects a companion browser ESM
host with the same default and named identities. Root browser CommonJS selects
the UMD implementation, and the legacy package browser remap replaces
`./source-map-support.js` with that implementation. Explicit
`browser-source-map-support` deep imports remain UMD.

Default browser file and map discovery uses synchronous XHR and is subject to
origin policy. Automatic stack rewriting depends on compatible V8-style Error
and CallSite behavior. The browser contract therefore does not promise
automatic stack mapping in every JavaScript engine.

The UMD and ESM artifacts bundle a browser path implementation and resolve
relative map/source paths without a Node `process` global. Their base64 decoder
also treats malformed inline maps as retrieval misses rather than allowing a
strict browser `atob()` error to replace the generated stack.

## Maintained corrections

- The production parser graph is exact `@jridgewell/trace-mapping@0.3.31`,
  `@jridgewell/resolve-uri@3.1.2`, and
  `@jridgewell/sourcemap-codec@1.6.0`; historical `source-map` and
  `buffer-from` production dependencies are removed. Mapping uses `AnyMap` so
  regular and indexed/sectioned Source Map v3 payloads share one maintained
  consumer path.
- URL-based generated sources use URL resolution where available so a URL host
  is not interpreted as a local directory.
- Generated file content is released after map discovery instead of retained
  indefinitely when no map exists.
- Malformed map construction and lookup failures fall back to generated
  positions; malformed maps and misses are cached.
- Cache dictionaries have null prototypes, preventing special source names
  from colliding with inherited object keys.
- Inline browser base64 maps decode UTF-8 without requiring a Buffer polyfill,
  and malformed base64 falls back without escaping from strict `atob()`.
- Uncaught errors retain `Error.cause` rendering and preserve an existing
  nonzero `process.exitCode`.

These changes are compatibility-maintenance and defense-in-depth work. They do
not establish an assigned vulnerability, security advisory, or CVE.

## Additive surfaces

The package adds a scoped name, conditional exports, Node and browser ESM-host
facades, first-party CommonJS and ESM declarations, typed install options and
CallSite interfaces, explicit package metadata export, exact release
dependencies, current verification, and restored copied-V8 provenance.

The ESM default is the CommonJS namespace identity. Named ESM bindings point to
the same six functions. The root remains CommonJS when required.

## Process-level boundaries

The package does not provide isolated mapper instances. `Error.prepareStackTrace`,
the optional `process.emit` wrapper, and the optional CommonJS compiler wrapper
are realm- or process-global. Resetting retrieval handlers does not restore any
of them. Applications that combine this package with native mapping, profilers,
test runners, Electron stack capture, or another formatter must choose and test
ownership explicitly.

Retrieval, parsing, and mapping are synchronous. There are no built-in byte,
source-count, nesting, filesystem-root, URL, or network limits. Browser origin
rules and Node filesystem permissions remain outside the package.

## Provenance and independence

The source-map-support runtime remains under Evan Wallace's MIT License.
`CallSiteToString` contains code copied almost verbatim from V8 4.3.49 and
retains the applicable V8 BSD 3-Clause terms.

This is an independent continuation. It is not affiliated with or endorsed by
Evan Wallace, the upstream project, V8, Google, Justin Ridgewell, or the
@jridgewell projects.