# Migration

## Source-preserving npm alias

The lowest-risk migration retains the historical dependency key:

```json
{
  "dependencies": {
    "har-validator": "npm:@stackline/har-validator@1.0.0"
  }
}
```

Existing `require('har-validator')` and
`require('har-validator/lib/async')` calls then remain unchanged.

Commit `package.json` and the lockfile together. Confirm that the installed
tree contains `@stackline/har-validator@1.0.0`, `ajv@6.15.0`, and
`har-schema@2.0.0`, and reject an unexpected duplicate validator graph.

## Scoped imports

Callers may instead install `@stackline/har-validator` and update imports. The
root Promise API and the `lib/async` and `lib/error` deep entries are preserved.
ESM consumers may use the default namespace or named validators.

## Browser choices

Browser bundlers should normally use the same root and deep imports as Node.
This lets the bundler create one shared graph, so errors rejected by a Promise
or passed to a callback retain identity with the constructor imported from
`lib/error`.

The additive `@stackline/har-validator/browser` entry is a self-contained,
root-only CJS/ESM bundle. It is appropriate when only Promise validators are
needed. Review Ajv's runtime code generation against the application's Content
Security Policy.

## Compatibility notes

The validation schemas and Ajv 6 error shapes are unchanged. The only intended
observable correction is proper `HARError` prototype isolation. Review code
that relied on the upstream bug where an ordinary `Error` passed `instanceof
HARError`.

Ajv or a different HAR toolkit is also a reasonable neutral alternative when
the caller wants to own schema loading, error normalization, and migration
testing rather than preserve this API.

## Verification checklist

Before merging an adoption:

1. run the application's valid and invalid HAR fixtures;
2. compare complete error arrays, including `dataPath`, `schemaPath`, keyword,
   parameters, and message where callers inspect them;
3. exercise root and every historical deep import used by the application;
4. verify callback timing and callback return values if `lib/async` is used;
5. test falsy inputs if callers depend on upstream empty-object normalization;
6. build and run the browser target when applicable; and
7. keep the previous manifest and lockfile diff available for a one-commit
   rollback.

## Rollback

Restore the previous dependency declaration and lockfile together, reinstall
from the project's normal clean-install path, and rerun the same focused
fixtures. Do not mix the old manifest with a lockfile that still resolves the
scoped alias.