@effected/lockfiles 0.5.1 → 0.6.0

package/Lockfile.js

@@ -182,10 +182,15 @@ var Lockfile = class Lockfile extends Schema.Class("Lockfile")({
 			return ResolvedPackage.make({
 				name: realName,
 				version: pkg.version,
+				instanceId: pkg.instanceId,
 				...pkg.integrity !== void 0 ? { integrity: pkg.integrity } : {},
 				isWorkspace: pkg.isWorkspace,
 				relativePath: pkg.relativePath,
-				dependencies: pkg.dependencies
+				dependencies: pkg.dependencies,
+				peerDependencies: pkg.peerDependencies,
+				peerDependenciesMeta: pkg.peerDependenciesMeta,
+				resolved: pkg.resolved,
+				unresolvedEdges: pkg.unresolvedEdges
 			});
 		});
 		const workspaceDependencies = this.workspaceDependencies.map((dep) => {

package/LockfileFormat.js

@@ -3,7 +3,7 @@ import { Option, Schema } from "effect";
 //#region src/LockfileFormat.ts
 /**
 * The lockfile formats this package parses: bun's `bun.lock` (JSONC), npm's
-* `package-lock.json` (v2/v3 JSON), pnpm's `pnpm-lock.yaml` and yarn Berry's
+* `package-lock.json` (JSON), pnpm's `pnpm-lock.yaml` and yarn Berry's
 * `yarn.lock` (both YAML).
 *
 * @remarks
@@ -12,6 +12,10 @@ import { Option, Schema } from "effect";
 * Berry only; classic (v1) `yarn.lock` is not YAML and fails
 * `Lockfile.parse` with a typed `LockfileParseError`.
 *
+* The format literal says nothing about which *versions* of that format are
+* supported: pnpm `lockfileVersion` 9+ and npm `lockfileVersion` 3+ parse,
+* and older ones fail typed. See `Lockfile.parse`.
+*
 * @public
 */
 const LockfileFormat = Schema.Literals([

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Lockfile parsing for [Effect](https://effect.website) v4: bun (`bun.lock`), npm (`package-lock.json` v2/v3), pnpm (`pnpm-lock.yaml`) and yarn Berry (`yarn.lock`) all normalized into one `Lockfile` schema model, plus pure integrity checking of that model against workspace manifests. Four formats, one model, no IO and no external runtime dependencies.
+Lockfile parsing for [Effect](https://effect.website) v4: bun (`bun.lock`), npm (`package-lock.json`), pnpm (`pnpm-lock.yaml`) and yarn Berry (`yarn.lock`) all normalized into one `Lockfile` schema model, plus pure integrity checking of that model against workspace manifests. Four formats, one model, no IO and no external runtime dependencies.
 
 > **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
 > development against a single pinned Effect v4 prerelease. Packages graduate to
@@ -77,10 +77,44 @@ Effect.runPromise(program).then(console.log);
 | Format | Filename | Dialect | Notes |
 | ------ | -------- | ------- | ----- |
 | `"bun"` | `bun.lock` | JSONC | Trusted dependencies preserved on `BunExtension` |
-| `"npm"` | `package-lock.json` | JSON | v2 and v3 |
-| `"pnpm"` | `pnpm-lock.yaml` | YAML | Catalogs preserved on `PnpmExtension`; see below |
+| `"npm"` | `package-lock.json` | JSON | `lockfileVersion` 3+ — v2 and older fail typed |
+| `"pnpm"` | `pnpm-lock.yaml` | YAML | `lockfileVersion` 9+ — older fails typed. Catalogs preserved on `PnpmExtension`; see below |
 | `"yarn"` | `yarn.lock` | YAML | Berry only — classic v1 fails typed |
 
+### Supported lockfile versions
+
+The gate is on the **lockfile format version**, which is the only version a lockfile records:
+
+| Format | Minimum | Older input |
+| ------ | ------- | ----------- |
+| pnpm | `lockfileVersion` 9 | `LockfileParseError`, `stage: "validation"` |
+| npm | `lockfileVersion` 3 | `LockfileParseError`, `stage: "validation"` |
+| bun, yarn | not gated | — |
+
+The `cause` is a structured `{ _tag: "UnsupportedLockfileVersion", format, lockfileVersion, minimumSupported, message }`, so a consumer can distinguish "your lockfile is too old" from "your lockfile is malformed" without parsing prose. `isUnsupportedLockfileVersion` is the exported predicate that narrows to it — discriminate on the tag, never on `message`, which is a summary rather than contract:
+
+```ts
+import { isUnsupportedLockfileVersion, Lockfile } from "@effected/lockfiles";
+import { Effect } from "effect";
+
+declare const content: string;
+
+const program = Lockfile.parse(content, { format: "pnpm" }).pipe(
+  Effect.catchTag("LockfileParseError", (error) =>
+    isUnsupportedLockfileVersion(error.cause)
+      ? Effect.fail(`lockfileVersion ${error.cause.lockfileVersion}; need ${error.cause.minimumSupported}+`)
+      : Effect.fail("malformed lockfile"),
+  ),
+);
+// a pre-v9 pnpm lockfile takes the first branch, a truncated one the second
+```
+
+`cause` stays an open channel deliberately: it carries whatever the delegated parsing engines throw, so declaring it as a closed union would present an open channel as an exhaustive one. The predicate is what makes narrowing it honest.
+
+Older formats are rejected rather than parsed because they cannot answer the questions the model now asks: pre-v9 pnpm has no `snapshots:` section, and npm v1/v2 trees record no per-instance nesting, so both would decode into rows with no resolution data.
+
+**Tested against** pnpm 11.22.0, npm 11.19.0, bun 1.3.14 and yarn 4.9.1 — a separate claim from the gate, and deliberately so. A lockfile does not record which package manager wrote it, and the mapping is many-to-one (pnpm 9, 10 and 11 all write format `9.0`), so no manager-version requirement could be enforced here even in principle.
+
 ## Errors
 
 `Lockfile.parse` is the only fallible entrypoint, and it fails two ways.
@@ -94,6 +128,21 @@ The framing error exists because `pnpm-lock.yaml` is a YAML **stream**, not a YA
 
 yarn defines no document framing at all, so multi-document `yarn.lock` content fails with `"unexpectedDocuments"` rather than being silently truncated to its first document. Where a format states no rule, this package refuses to guess.
 
+## Instances and resolution
+
+A row in `lockfile.packages` is one package **instance**, not one package. A dependency installed twice under different peers is two rows, and `instanceId` is that row's lockfile-native identity, carried verbatim. Treat it as **opaque**: look an id up in the model, never split or pattern-match one, because its spelling is the format's business and differs per manager.
+
+`resolved` maps each dependency name — and each peer name the lockfile records a resolution for — to the `instanceId` it actually resolved to, which is what lets a consumer walk the real graph rather than re-resolving ranges itself. `peerDependencies` and `peerDependenciesMeta` carry the declarations as written, defaulting to `{}`.
+
+```ts
+const [instance] = lockfile.packagesNamed("react-dom");
+const reactId = instance?.resolved["react"];
+const react = lockfile.packages.find((p) => p.instanceId === reactId);
+// react?.version: the version this particular react-dom instance resolved to
+```
+
+`unresolvedEdges` names the edges the lockfile **records** but the model could not name. A name listed there is not absent — it is unanswered, so a missing `resolved` key must not be read as "nothing is there". A gate that cares about completeness checks that array before trusting an empty result.
+
 ## Features
 
 - `Lockfile.parse(content, { format })` — the package's only fallible boundary; fails with `LockfileParseError` or `LockfileFramingError`.
@@ -102,7 +151,8 @@ yarn defines no document framing at all, so multi-document `yarn.lock` content f
 - `LockfileFormat` with `filenameFor` / `fromFilename` — the format literal and its mapping to lockfile filenames.
 - `LockfileIntegrity.compare(lockfile, manifests)` — total, pure integrity checking with no error channel; the report carries `valid`, `missingWorkspaces`, `extraWorkspaces` and `unsatisfiedConstraints`. Constraint checking is best-effort by design: `workspace:` / `link:` / `file:` specifiers and rows whose range does not parse as SemVer are skipped.
 - `WorkspaceManifest` — the manifest input shape for integrity checking: a package name plus four optional dependency records. Deliberately a plain value rather than a strict manifest model, so consumers can derive it from anything.
-- `ResolvedPackage` — name, version, optional integrity hash, workspace flag and relative path, dependency map.
+- `ResolvedPackage` — one package *instance*: name, version, optional integrity hash, workspace flag and relative path, dependency map, the peer declarations (`peerDependencies`, `peerDependenciesMeta`), the opaque `instanceId`, the `resolved` name-to-instance map and the `unresolvedEdges` the model could not name.
+- `isUnsupportedLockfileVersion` and the `UnsupportedLockfileVersion` type — the predicate that narrows a `LockfileParseError.cause` to a version-gate rejection, so "too old" and "malformed" are told apart on a tag rather than on prose.
 - `WorkspaceDependency` — a `from`/`to` edge between workspace packages, with `depType` spelled in `@effected/npm`'s `DependencyField` vocabulary and its declared constraint.
 - `PnpmExtension` and `BunExtension` — format-specific data such as pnpm catalogs and bun trusted dependencies, preserved on the model's optional `extension` field.
 

package/ResolvedPackage.js

@@ -3,12 +3,21 @@ import { IntegrityHash } from "@effected/npm";
 
 //#region src/ResolvedPackage.ts
 const EMPTY_DEPENDENCIES = {};
+const EMPTY_PEER_META = {};
+const EMPTY_EDGE_NAMES = [];
 /**
 * A package resolved from a lockfile.
 *
 * @remarks
 * The common shape every format's entries normalize into:
 *
+* - `instanceId` — the lockfile-native identity of this *instance*, verbatim:
+*   pnpm's snapshot key (`react-dom@18.3.1(react@17.0.2)`), npm's full entry
+*   key (`node_modules/express/node_modules/debug`), bun's `packages` key
+*   (`@acme/lib/react-dom`) or yarn's locator (`react-dom@npm:18.3.1`). It is
+*   **opaque** — no scheme is synthesized and none should be parsed by a
+*   consumer; it exists so `resolved` can name an instance, and so two
+*   peer-resolved variants of one `name@version` stay distinguishable.
 * - `name` — the resolved package name. For pnpm *workspace* packages
 *   straight out of `Lockfile.parse` this is the importer path until
 *   `Lockfile#withImporterNames` rewrites it.
@@ -24,16 +33,62 @@ const EMPTY_DEPENDENCIES = {};
 *   packages, when the lockfile records one.
 * - `dependencies` — the package's own dependency map, defaulting to `{}`
 *   both at construction and when decoding serialized data.
+* - `peerDependencies` — the package's *declared* peer ranges, keyed by peer
+*   name. Every format records them (pnpm and npm as their own section, bun
+*   inline in the package tuple's info object, yarn Berry as an entry
+*   section), so this is populated across all four. Declarations only: what
+*   the package *asks for*, never what actually resolved.
+* - `peerDependenciesMeta` — the per-peer flags, normalized to
+*   `{ optional: boolean }`. bun spells optional peers as an `optionalPeers`
+*   array of names rather than a meta object; that spelling is normalized
+*   into this shape so one consumer algorithm serves every format. A peer
+*   with no meta entry is required.
+* - `resolved` — this instance's *outgoing edges*: dependency (and, where the
+*   format records it, peer) name → the `instanceId` that name actually
+*   resolved to in this instance's context. This is the answer to "which
+*   concrete version of P did X get", which `peerDependencies` deliberately
+*   does not answer.
+*
+*   Every entry is **verified**: an edge is emitted only when the composed or
+*   walked-up identity matches a real instance in the same lockfile. An edge
+*   that cannot be resolved honestly is *omitted*, never guessed — a wrong
+*   resolved edge is a silent wrong answer, an absent one is a visible gap.
+*   yarn records peer resolution virtually and is therefore dependency-edges
+*   only.
+*
+* - `unresolvedEdges` — dependency names whose edge the lockfile **records**
+*   but this model could not name: a `link:` target that is not a workspace
+*   importer, a composed identity matching no instance. It is the companion
+*   `resolved` needs to be honest, because an absent key in `resolved` would
+*   otherwise mean two different things — "nothing is there" and "something is
+*   there that I could not name" — and a consumer reading the first meaning
+*   for the second turns this package's gap into its own false positive.
+*
+*   A dependency the lockfile simply does not record is **not** an unresolved
+*   edge; it is an absence, and must not appear here. npm and bun contribute
+*   nothing at all: their sections are *declarations* resolved positionally, so
+*   "the walk found nothing" is genuine absence. A fail-closed signal that is
+*   always on is a signal nobody reads.
+*
+* All four record fields — `dependencies`, `peerDependencies`,
+* `peerDependenciesMeta` and `resolved` — default to `{}` at construction and
+* when decoding, and `unresolvedEdges` defaults to `[]`. An absent section is
+* therefore an empty collection, never `undefined`.
 *
 * @public
 */
 var ResolvedPackage = class extends Schema.Class("ResolvedPackage")({
 	name: Schema.NonEmptyString,
 	version: Schema.String,
+	instanceId: Schema.NonEmptyString,
 	integrity: Schema.optionalKey(IntegrityHash),
 	isWorkspace: Schema.Boolean,
 	relativePath: Schema.optionalKey(Schema.String),
-	dependencies: Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY_DEPENDENCIES)), Schema.withConstructorDefault(Effect.succeed(EMPTY_DEPENDENCIES)))
+	dependencies: Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY_DEPENDENCIES)), Schema.withConstructorDefault(Effect.succeed(EMPTY_DEPENDENCIES))),
+	peerDependencies: Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY_DEPENDENCIES)), Schema.withConstructorDefault(Effect.succeed(EMPTY_DEPENDENCIES))),
+	peerDependenciesMeta: Schema.Record(Schema.String, Schema.Struct({ optional: Schema.Boolean })).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY_PEER_META)), Schema.withConstructorDefault(Effect.succeed(EMPTY_PEER_META))),
+	resolved: Schema.Record(Schema.String, Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY_DEPENDENCIES)), Schema.withConstructorDefault(Effect.succeed(EMPTY_DEPENDENCIES))),
+	unresolvedEdges: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(EMPTY_EDGE_NAMES)), Schema.withConstructorDefault(Effect.succeed(EMPTY_EDGE_NAMES)))
 }) {};
 
 //#endregion

package/UnsupportedLockfileVersion.js

@@ -0,0 +1,35 @@
+//#region src/UnsupportedLockfileVersion.ts
+/**
+* Whether a `LockfileParseError.cause` is an {@link UnsupportedLockfileVersion}.
+*
+* @remarks
+* `LockfileParseError.cause` is deliberately `Schema.Defect` — it has to carry
+* whatever the delegated jsonc/yaml/JSON engines throw, which is genuinely
+* open. Widening that field to a union would not make it closed, and would
+* misrepresent an open channel as an exhaustive one. So the *type* is exported
+* and narrowing is a predicate, which is the honest tool for an intentionally
+* open value.
+*
+* @example
+* ```ts
+* import { Lockfile, isUnsupportedLockfileVersion } from "@effected/lockfiles";
+* import { Effect } from "effect";
+*
+* const parsed = Lockfile.parse(text, { format: "npm" }).pipe(
+*   Effect.catchTag("LockfileParseError", (error) =>
+*     isUnsupportedLockfileVersion(error.cause)
+*       ? Effect.fail(`upgrade: ${error.cause.format} needs lockfileVersion ${error.cause.minimumSupported}+`)
+*       : Effect.fail("malformed lockfile"),
+*   ),
+* );
+* ```
+*
+* @param cause - the `cause` of a `LockfileParseError`, or any unknown value
+* @returns `true` when `cause` is the version-gate record
+*
+* @public
+*/
+const isUnsupportedLockfileVersion = (cause) => typeof cause === "object" && cause !== null && Object.hasOwn(cause, "_tag") && cause._tag === "UnsupportedLockfileVersion" && typeof cause.format === "string" && typeof cause.minimumSupported === "number";
+
+//#endregion
+export { isUnsupportedLockfileVersion };

package/index.d.ts

@@ -63,7 +63,7 @@ declare class ImporterDependency extends ImporterDependency_base {}
 //#region src/LockfileFormat.d.ts
 /**
  * The lockfile formats this package parses: bun's `bun.lock` (JSONC), npm's
- * `package-lock.json` (v2/v3 JSON), pnpm's `pnpm-lock.yaml` and yarn Berry's
+ * `package-lock.json` (JSON), pnpm's `pnpm-lock.yaml` and yarn Berry's
  * `yarn.lock` (both YAML).
  *
  * @remarks
@@ -72,6 +72,10 @@ declare class ImporterDependency extends ImporterDependency_base {}
  * Berry only; classic (v1) `yarn.lock` is not YAML and fails
  * `Lockfile.parse` with a typed `LockfileParseError`.
  *
+ * The format literal says nothing about which *versions* of that format are
+ * supported: pnpm `lockfileVersion` 9+ and npm `lockfileVersion` 3+ parse,
+ * and older ones fail typed. See `Lockfile.parse`.
+ *
  * @public
  */
 declare const LockfileFormat: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
@@ -197,6 +201,7 @@ declare class PnpmExtension extends PnpmExtension_base {}
 declare const ResolvedPackage_base: Schema.Class<ResolvedPackage, Schema.Struct<{
   readonly name: Schema.NonEmptyString;
   readonly version: Schema.String;
+  readonly instanceId: Schema.NonEmptyString;
   readonly integrity: Schema.optionalKey<Schema.brand<Schema.String, "IntegrityHash"> & {
     isSri: (value: string) => boolean;
     isCorepack: (value: string) => boolean;
@@ -208,6 +213,12 @@ declare const ResolvedPackage_base: Schema.Class<ResolvedPackage, Schema.Struct<
   readonly isWorkspace: Schema.Boolean;
   readonly relativePath: Schema.optionalKey<Schema.String>;
   readonly dependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  readonly peerDependencies: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  readonly peerDependenciesMeta: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.Struct<{
+    readonly optional: Schema.Boolean;
+  }>>, never>>;
+  readonly resolved: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>>;
+  readonly unresolvedEdges: Schema.withConstructorDefault<Schema.withDecodingDefaultKey<Schema.$Array<Schema.String>, never>>;
 }>, {}>;
 /**
  * A package resolved from a lockfile.
@@ -215,6 +226,13 @@ declare const ResolvedPackage_base: Schema.Class<ResolvedPackage, Schema.Struct<
  * @remarks
  * The common shape every format's entries normalize into:
  *
+ * - `instanceId` — the lockfile-native identity of this *instance*, verbatim:
+ *   pnpm's snapshot key (`react-dom@18.3.1(react@17.0.2)`), npm's full entry
+ *   key (`node_modules/express/node_modules/debug`), bun's `packages` key
+ *   (`@acme/lib/react-dom`) or yarn's locator (`react-dom@npm:18.3.1`). It is
+ *   **opaque** — no scheme is synthesized and none should be parsed by a
+ *   consumer; it exists so `resolved` can name an instance, and so two
+ *   peer-resolved variants of one `name@version` stay distinguishable.
  * - `name` — the resolved package name. For pnpm *workspace* packages
  *   straight out of `Lockfile.parse` this is the importer path until
  *   `Lockfile#withImporterNames` rewrites it.
@@ -230,6 +248,47 @@ declare const ResolvedPackage_base: Schema.Class<ResolvedPackage, Schema.Struct<
  *   packages, when the lockfile records one.
  * - `dependencies` — the package's own dependency map, defaulting to `{}`
  *   both at construction and when decoding serialized data.
+ * - `peerDependencies` — the package's *declared* peer ranges, keyed by peer
+ *   name. Every format records them (pnpm and npm as their own section, bun
+ *   inline in the package tuple's info object, yarn Berry as an entry
+ *   section), so this is populated across all four. Declarations only: what
+ *   the package *asks for*, never what actually resolved.
+ * - `peerDependenciesMeta` — the per-peer flags, normalized to
+ *   `{ optional: boolean }`. bun spells optional peers as an `optionalPeers`
+ *   array of names rather than a meta object; that spelling is normalized
+ *   into this shape so one consumer algorithm serves every format. A peer
+ *   with no meta entry is required.
+ * - `resolved` — this instance's *outgoing edges*: dependency (and, where the
+ *   format records it, peer) name → the `instanceId` that name actually
+ *   resolved to in this instance's context. This is the answer to "which
+ *   concrete version of P did X get", which `peerDependencies` deliberately
+ *   does not answer.
+ *
+ *   Every entry is **verified**: an edge is emitted only when the composed or
+ *   walked-up identity matches a real instance in the same lockfile. An edge
+ *   that cannot be resolved honestly is *omitted*, never guessed — a wrong
+ *   resolved edge is a silent wrong answer, an absent one is a visible gap.
+ *   yarn records peer resolution virtually and is therefore dependency-edges
+ *   only.
+ *
+ * - `unresolvedEdges` — dependency names whose edge the lockfile **records**
+ *   but this model could not name: a `link:` target that is not a workspace
+ *   importer, a composed identity matching no instance. It is the companion
+ *   `resolved` needs to be honest, because an absent key in `resolved` would
+ *   otherwise mean two different things — "nothing is there" and "something is
+ *   there that I could not name" — and a consumer reading the first meaning
+ *   for the second turns this package's gap into its own false positive.
+ *
+ *   A dependency the lockfile simply does not record is **not** an unresolved
+ *   edge; it is an absence, and must not appear here. npm and bun contribute
+ *   nothing at all: their sections are *declarations* resolved positionally, so
+ *   "the walk found nothing" is genuine absence. A fail-closed signal that is
+ *   always on is a signal nobody reads.
+ *
+ * All four record fields — `dependencies`, `peerDependencies`,
+ * `peerDependenciesMeta` and `resolved` — default to `{}` at construction and
+ * when decoding, and `unresolvedEdges` defaults to `[]`. An absent section is
+ * therefore an empty collection, never `undefined`.
  *
  * @public
  */
@@ -490,5 +549,70 @@ declare class LockfileIntegrity extends LockfileIntegrity_base {
   static compare(lockfile: Lockfile, manifests: ReadonlyArray<WorkspaceManifest>): LockfileIntegrity;
 }
 //#endregion
-export { BunExtension, ImporterDependency, Lockfile, LockfileFormat, LockfileFramingError, LockfileImporter, LockfileIntegrity, LockfileParseError, type PnpmCatalogs, PnpmExtension, ResolvedPackage, WorkspaceDependency, WorkspaceManifest, filenameFor, filenamesFor, fromFilename };
+//#region src/UnsupportedLockfileVersion.d.ts
+/**
+ * The cause a {@link LockfileParseError} carries when a lockfile predates the
+ * supported format version.
+ *
+ * @remarks
+ * `@effected/lockfiles` parses pnpm `lockfileVersion` 9+ and npm
+ * `lockfileVersion` 3+. An older format fails typed at `stage: "validation"`,
+ * and the failure carries this record rather than an engine error, so a
+ * consumer can tell **"your lockfile is too old" from "your lockfile is
+ * malformed" without parsing prose**.
+ *
+ * `message` is for humans and its wording is not contract; discriminate on
+ * `_tag` — through {@link isUnsupportedLockfileVersion}, which is why that
+ * predicate exists.
+ *
+ * bun and yarn are ungated (neither records a comparable format-version line),
+ * so `format` is narrowed to the two that are.
+ *
+ * @public
+ */
+interface UnsupportedLockfileVersion {
+  /** Discriminant. */
+  readonly _tag: "UnsupportedLockfileVersion";
+  /** The gated format that rejected the input. */
+  readonly format: "npm" | "pnpm";
+  /** The `lockfileVersion` found, verbatim — a number or a string like `"6.0"`. */
+  readonly lockfileVersion: number | string;
+  /** The lowest format version this package parses for that format. */
+  readonly minimumSupported: number;
+  /** A human-readable summary. Not contract — narrow on `_tag` instead. */
+  readonly message: string;
+}
+/**
+ * Whether a `LockfileParseError.cause` is an {@link UnsupportedLockfileVersion}.
+ *
+ * @remarks
+ * `LockfileParseError.cause` is deliberately `Schema.Defect` — it has to carry
+ * whatever the delegated jsonc/yaml/JSON engines throw, which is genuinely
+ * open. Widening that field to a union would not make it closed, and would
+ * misrepresent an open channel as an exhaustive one. So the *type* is exported
+ * and narrowing is a predicate, which is the honest tool for an intentionally
+ * open value.
+ *
+ * @example
+ * ```ts
+ * import { Lockfile, isUnsupportedLockfileVersion } from "@effected/lockfiles";
+ * import { Effect } from "effect";
+ *
+ * const parsed = Lockfile.parse(text, { format: "npm" }).pipe(
+ *   Effect.catchTag("LockfileParseError", (error) =>
+ *     isUnsupportedLockfileVersion(error.cause)
+ *       ? Effect.fail(`upgrade: ${error.cause.format} needs lockfileVersion ${error.cause.minimumSupported}+`)
+ *       : Effect.fail("malformed lockfile"),
+ *   ),
+ * );
+ * ```
+ *
+ * @param cause - the `cause` of a `LockfileParseError`, or any unknown value
+ * @returns `true` when `cause` is the version-gate record
+ *
+ * @public
+ */
+declare const isUnsupportedLockfileVersion: (cause: unknown) => cause is UnsupportedLockfileVersion;
+//#endregion
+export { BunExtension, ImporterDependency, Lockfile, LockfileFormat, LockfileFramingError, LockfileImporter, LockfileIntegrity, LockfileParseError, type PnpmCatalogs, PnpmExtension, ResolvedPackage, type UnsupportedLockfileVersion, WorkspaceDependency, WorkspaceManifest, filenameFor, filenamesFor, fromFilename, isUnsupportedLockfileVersion };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -7,5 +7,6 @@ import { PnpmExtension } from "./PnpmExtension.js";
 import { LockfileFormat, filenameFor, filenamesFor, fromFilename } from "./LockfileFormat.js";
 import { Lockfile, LockfileFramingError, LockfileParseError } from "./Lockfile.js";
 import { LockfileIntegrity, WorkspaceManifest } from "./LockfileIntegrity.js";
+import { isUnsupportedLockfileVersion } from "./UnsupportedLockfileVersion.js";
 
-export { BunExtension, ImporterDependency, Lockfile, LockfileFormat, LockfileFramingError, LockfileImporter, LockfileIntegrity, LockfileParseError, PnpmExtension, ResolvedPackage, WorkspaceDependency, WorkspaceManifest, filenameFor, filenamesFor, fromFilename };
+export { BunExtension, ImporterDependency, Lockfile, LockfileFormat, LockfileFramingError, LockfileImporter, LockfileIntegrity, LockfileParseError, PnpmExtension, ResolvedPackage, WorkspaceDependency, WorkspaceManifest, filenameFor, filenamesFor, fromFilename, isUnsupportedLockfileVersion };

package/internal/bun.js

@@ -1,20 +1,42 @@
 import { BunExtension } from "../BunExtension.js";
 import { LockfileImporter } from "../LockfileImporter.js";
 import { ResolvedPackage } from "../ResolvedPackage.js";
-import { extractWorkspaceDeps, importerDependencies, syntaxFailure, toIntegrityHash, validationFailure } from "./shared.js";
-import { Effect, Schema } from "effect";
+import { extractWorkspaceDeps, importerDependencies, peerDeclarations, syntaxFailure, toIntegrityHash, validationFailure } from "./shared.js";
+import { Effect, Exit, Schema } from "effect";
 import { Jsonc } from "@effected/jsonc";
 
 //#region src/internal/bun.ts
 const DepRecord = Schema.optionalKey(Schema.Record(Schema.String, Schema.String));
+const OptionalPeers = Schema.optionalKey(Schema.Array(Schema.String));
 const BunWorkspaceEntry = Schema.Struct({
 	name: Schema.optionalKey(Schema.String),
 	version: Schema.optionalKey(Schema.String),
 	dependencies: DepRecord,
 	devDependencies: DepRecord,
 	peerDependencies: DepRecord,
-	optionalDependencies: DepRecord
+	optionalDependencies: DepRecord,
+	optionalPeers: OptionalPeers
 });
+/**
+* The info object at package-tuple index 2. bun's tuple shape is
+* under-documented upstream, so it is read permissively and *out of band*: a
+* shape that does not decode is skipped (the package still lands, with no
+* peers) rather than failing the whole parse.
+*
+* @internal
+*/
+const BunPackageInfo = Schema.Struct({
+	dependencies: DepRecord,
+	devDependencies: DepRecord,
+	optionalDependencies: DepRecord,
+	peerDependencies: DepRecord,
+	optionalPeers: OptionalPeers
+});
+const decodeBunPackageInfo = Schema.decodeUnknownExit(BunPackageInfo);
+const readBunPackageInfo = (value) => {
+	const exit = decodeBunPackageInfo(value);
+	return Exit.isSuccess(exit) ? exit.value : void 0;
+};
 const BunLockfileRaw = Schema.Struct({
 	lockfileVersion: Schema.Number,
 	workspaces: Schema.optionalKey(Schema.Record(Schema.String, BunWorkspaceEntry)),
@@ -37,8 +59,60 @@ const parseBun = (content) => Effect.gen(function* () {
 	const validated = yield* Schema.decodeUnknownEffect(BunLockfileRaw)(parsed).pipe(Effect.mapError(validationFailure));
 	return yield* toFields(validated);
 });
+/**
+* Resolve one entry's outgoing edges by replaying bun's own key scheme.
+*
+* bun encodes install position in the `packages` key: a nested install is
+* keyed `<parent-key>/<name>`, so `"react-dom/react"` is literally "the react
+* react-dom got". Package names are themselves slash-bearing when scoped, so
+* the parent chain is **not** computed by splitting on `/` — it is read off
+* the key space, taking those prefixes of the key that are themselves keys,
+* longest first. Deepest wins; the root (`<name>` alone) is tried last.
+*
+* Only keys that exist are emitted, so an edge bun did not record is omitted
+* rather than invented.
+*
+* @internal
+*/
+const resolveBunEdges = (key, sections, keys) => {
+	const names = /* @__PURE__ */ new Set();
+	for (const section of sections) {
+		if (!section) continue;
+		for (const name of Object.keys(section)) if (name !== "") names.add(name);
+	}
+	if (names.size === 0) return {};
+	const prefixes = [key];
+	for (let i = key.indexOf("/"); i !== -1; i = key.indexOf("/", i + 1)) {
+		const candidate = key.slice(0, i);
+		if (keys.has(candidate)) prefixes.push(candidate);
+	}
+	prefixes.sort((a, b) => b.length - a.length);
+	prefixes.push("");
+	const edges = /* @__PURE__ */ new Map();
+	for (const name of names) for (const prefix of prefixes) {
+		const candidate = prefix === "" ? name : `${prefix}/${name}`;
+		if (keys.has(candidate)) {
+			edges.set(name, candidate);
+			break;
+		}
+	}
+	return Object.fromEntries(edges);
+};
+const infoSections = (info) => [
+	info?.dependencies,
+	info?.devDependencies,
+	info?.optionalDependencies,
+	info?.peerDependencies
+];
+const workspaceSections = (entry) => [
+	entry.dependencies,
+	entry.devDependencies,
+	entry.optionalDependencies,
+	entry.peerDependencies
+];
 const toFields = (raw) => Effect.gen(function* () {
 	const packages = [];
+	const keys = new Set(raw.packages ? Object.keys(raw.packages) : []);
 	const workspaceNames = /* @__PURE__ */ new Set();
 	const workspaceEntries = /* @__PURE__ */ new Map();
 	const importers = [];
@@ -51,11 +125,16 @@ const toFields = (raw) => Effect.gen(function* () {
 			if (wsPath === "") continue;
 			const name = wsEntry.name === void 0 || wsEntry.name === "" ? wsPath : wsEntry.name;
 			workspaceNames.add(name);
+			const instanceId = keys.has(name) ? name : wsPath;
+			if (instanceId === "") continue;
 			packages.push(ResolvedPackage.make({
 				name,
 				version: wsEntry.version ?? "0.0.0",
+				instanceId,
 				isWorkspace: true,
-				relativePath: wsPath
+				relativePath: wsPath,
+				...peerDeclarations(wsEntry.peerDependencies, void 0, wsEntry.optionalPeers),
+				resolved: resolveBunEdges(instanceId, workspaceSections(wsEntry), keys)
 			}));
 			workspaceEntries.set(name, {
 				...wsEntry.dependencies ? { dependencies: wsEntry.dependencies } : {},
@@ -65,7 +144,8 @@ const toFields = (raw) => Effect.gen(function* () {
 			});
 		}
 	}
-	if (raw.packages) for (const tuple of Object.values(raw.packages)) {
+	if (raw.packages) for (const [key, tuple] of Object.entries(raw.packages)) {
+		if (key === "") continue;
 		if (tuple.length < 1) continue;
 		const first = tuple[0];
 		if (typeof first !== "string") continue;
@@ -75,11 +155,15 @@ const toFields = (raw) => Effect.gen(function* () {
 		const version = first.slice(atIdx + 1);
 		if (workspaceNames.has(name)) continue;
 		const integrity = yield* toIntegrityHash(tuple.length >= 4 && typeof tuple[3] === "string" ? tuple[3] : void 0);
+		const info = tuple.length >= 3 ? readBunPackageInfo(tuple[2]) : void 0;
 		packages.push(ResolvedPackage.make({
 			name,
 			version,
+			instanceId: key,
 			...integrity !== void 0 ? { integrity } : {},
-			isWorkspace: false
+			isWorkspace: false,
+			...peerDeclarations(info?.peerDependencies, void 0, info?.optionalPeers),
+			resolved: resolveBunEdges(key, infoSections(info), keys)
 		}));
 	}
 	const workspaceDependencies = extractWorkspaceDeps(workspaceEntries, workspaceNames);

package/internal/npm.js

@@ -1,10 +1,11 @@
 import { LockfileImporter } from "../LockfileImporter.js";
 import { ResolvedPackage } from "../ResolvedPackage.js";
-import { extractWorkspaceDeps, importerDependencies, syntaxFailure, toIntegrityHash, validationFailure } from "./shared.js";
+import { extractWorkspaceDeps, importerDependencies, peerDeclarations, requireLockfileVersion, syntaxFailure, toIntegrityHash, validationFailure } from "./shared.js";
 import { Effect, Schema } from "effect";
 
 //#region src/internal/npm.ts
 const DepRecord = Schema.optionalKey(Schema.Record(Schema.String, Schema.String));
+const PeerMetaRecord = Schema.optionalKey(Schema.Record(Schema.String, Schema.Struct({ optional: Schema.optionalKey(Schema.Boolean) })));
 const NpmPackageEntry = Schema.Struct({
 	name: Schema.optionalKey(Schema.String),
 	version: Schema.optionalKey(Schema.String),
@@ -15,8 +16,22 @@ const NpmPackageEntry = Schema.Struct({
 	dependencies: DepRecord,
 	devDependencies: DepRecord,
 	peerDependencies: DepRecord,
+	peerDependenciesMeta: PeerMetaRecord,
 	optionalDependencies: DepRecord
 });
+/**
+* The version gate's own input: `lockfileVersion` and nothing else.
+*
+* The gate has to read the version *before* the shape decode, because the
+* shape it would decode against is the shape of a supported version. `packages`
+* is a required key here and a v1 tree does not have one, so a shape-first
+* order reports npm v1 as **malformed** rather than as **too old** — losing
+* exactly the distinction the `UnsupportedLockfileVersion` cause exists to
+* carry.
+*
+* @internal
+*/
+const NpmVersionProbe = Schema.Struct({ lockfileVersion: Schema.Union([Schema.Number, Schema.String]) });
 const NpmLockfileRaw = Schema.Struct({
 	name: Schema.optionalKey(Schema.String),
 	version: Schema.optionalKey(Schema.String),
@@ -25,10 +40,73 @@ const NpmLockfileRaw = Schema.Struct({
 	packages: Schema.Record(Schema.String, NpmPackageEntry)
 });
 const NODE_MODULES_PREFIX = "node_modules/";
+const NESTED_NODE_MODULES = "/node_modules/";
 /**
-* Parse npm `package-lock.json` (v2/v3) content into the unified field
-* bundle. Native `JSON.parse` inside `Effect.try` — its throw on hostile
-* input (including V8's `RangeError` on pathological depth) lands typed as
+* Where a `packages` key's package name starts: after the **last**
+* `node_modules/` segment, not the first.
+*
+* npm encodes the whole install position in the key, so
+* `node_modules/express/node_modules/debug` is *debug*, nested under express —
+* and `packages/lib/node_modules/react` is *react*, nested under a workspace
+* directory and carrying no `node_modules/` prefix at all. Returns `-1` for a
+* key that is not a package position (the root `""` entry, a workspace path
+* entry), which the caller skips.
+*
+* @internal
+*/
+const packageNameIndex = (key) => {
+	const nested = key.lastIndexOf(NESTED_NODE_MODULES);
+	if (nested !== -1) return nested + 14;
+	return key.startsWith(NODE_MODULES_PREFIX) ? 13 : -1;
+};
+/**
+* Resolve one entry's outgoing edges by replaying node resolution over the key
+* space: from the depending package's own directory, try
+* `<prefix>/node_modules/<name>`, then strip one path segment and try again,
+* out to the root — **deepest first**, first hit wins. That order is the whole
+* algorithm: outermost-first would return the hoisted copy and silently
+* mis-report every shadowed dependency.
+*
+* Only keys that actually exist in the lockfile are emitted, so an edge npm
+* did not record is omitted rather than invented.
+*
+* @internal
+*/
+const resolveNpmEdges = (start, sections, packages) => {
+	const names = /* @__PURE__ */ new Set();
+	for (const section of sections) {
+		if (!section) continue;
+		for (const name of Object.keys(section)) if (name !== "") names.add(name);
+	}
+	if (names.size === 0) return {};
+	const prefixes = [];
+	for (let prefix = start;;) {
+		prefixes.push(prefix);
+		if (prefix === "") break;
+		const slash = prefix.lastIndexOf("/");
+		prefix = slash === -1 ? "" : prefix.slice(0, slash);
+	}
+	const edges = /* @__PURE__ */ new Map();
+	for (const name of names) for (const prefix of prefixes) {
+		const candidate = prefix === "" ? `${NODE_MODULES_PREFIX}${name}` : `${prefix}${NESTED_NODE_MODULES}${name}`;
+		if (Object.hasOwn(packages, candidate)) {
+			edges.set(name, candidate);
+			break;
+		}
+	}
+	return Object.fromEntries(edges);
+};
+const entrySections = (entry) => [
+	entry?.dependencies,
+	entry?.devDependencies,
+	entry?.optionalDependencies,
+	entry?.peerDependencies
+];
+/**
+* Parse npm `package-lock.json` content into the unified field bundle —
+* `lockfileVersion` 3 and newer; v2 and older fail typed at validation.
+* Native `JSON.parse` inside `Effect.try` — its throw on hostile input
+* (including V8's `RangeError` on pathological depth) lands typed as
 * `stage: "syntax"`.
 *
 * @internal
@@ -38,6 +116,8 @@ const parseNpm = (content) => Effect.gen(function* () {
 		try: () => JSON.parse(content),
 		catch: syntaxFailure
 	});
+	const probe = yield* Schema.decodeUnknownEffect(NpmVersionProbe)(raw).pipe(Effect.mapError(validationFailure));
+	yield* requireLockfileVersion("npm", probe.lockfileVersion);
 	const validated = yield* Schema.decodeUnknownEffect(NpmLockfileRaw)(raw).pipe(Effect.mapError(validationFailure));
 	return yield* toFields(validated);
 });
@@ -51,22 +131,30 @@ const toFields = (raw) => Effect.gen(function* () {
 		path: ".",
 		dependencies: importerDependencies(rootEntry, (s) => ({ specifier: s }))
 	}));
-	for (const [key, entry] of Object.entries(raw.packages)) if (key.startsWith(NODE_MODULES_PREFIX) && entry.link === true) {
-		const name = (entry.resolved !== void 0 ? raw.packages[entry.resolved] : void 0)?.name ?? entry.name ?? key.slice(13);
-		if (name !== "") workspaceNames.add(name);
+	for (const [key, entry] of Object.entries(raw.packages)) {
+		const nameIndex = packageNameIndex(key);
+		if (nameIndex !== -1 && entry.link === true) {
+			const name = (entry.resolved !== void 0 ? raw.packages[entry.resolved] : void 0)?.name ?? entry.name ?? key.slice(nameIndex);
+			if (name !== "") workspaceNames.add(name);
+		}
 	}
 	for (const [key, entry] of Object.entries(raw.packages)) {
 		if (key === "") continue;
-		if (key.startsWith(NODE_MODULES_PREFIX) && entry.link === true) {
+		const nameIndex = packageNameIndex(key);
+		if (nameIndex === -1) continue;
+		if (entry.link === true) {
 			const resolved = entry.resolved;
 			const wsEntry = resolved !== void 0 ? raw.packages[resolved] : void 0;
-			const name = wsEntry?.name ?? entry.name ?? key.slice(13);
+			const name = wsEntry?.name ?? entry.name ?? key.slice(nameIndex);
 			if (name === "") continue;
 			packages.push(ResolvedPackage.make({
 				name,
 				version: wsEntry?.version ?? "0.0.0",
+				instanceId: key,
 				isWorkspace: true,
-				...resolved !== void 0 ? { relativePath: resolved } : {}
+				...resolved !== void 0 ? { relativePath: resolved } : {},
+				...peerDeclarations(wsEntry?.peerDependencies, wsEntry?.peerDependenciesMeta),
+				resolved: resolveNpmEdges(resolved !== void 0 && resolved !== "" ? resolved : key, entrySections(wsEntry), raw.packages)
 			}));
 			if (wsEntry) workspaceEntries.set(name, {
 				...wsEntry.dependencies ? { dependencies: wsEntry.dependencies } : {},
@@ -78,16 +166,19 @@ const toFields = (raw) => Effect.gen(function* () {
 				path: resolved,
 				dependencies: wsEntry ? importerDependencies(wsEntry, (s) => ({ specifier: s })) : []
 			}));
-		} else if (key.startsWith(NODE_MODULES_PREFIX)) {
-			const name = key.slice(13);
+		} else {
+			const name = key.slice(nameIndex);
 			if (name !== "" && entry.version !== void 0) {
 				const integrity = yield* toIntegrityHash(entry.integrity);
 				packages.push(ResolvedPackage.make({
 					name,
 					version: entry.version,
+					instanceId: key,
 					...integrity !== void 0 ? { integrity } : {},
 					isWorkspace: false,
-					dependencies: entry.dependencies ?? {}
+					dependencies: entry.dependencies ?? {},
+					...peerDeclarations(entry.peerDependencies, entry.peerDependenciesMeta),
+					resolved: resolveNpmEdges(key, entrySections(entry), raw.packages)
 				}));
 			}
 		}

package/internal/pnpm.js

@@ -1,6 +1,6 @@
 import { LockfileImporter } from "../LockfileImporter.js";
 import { ResolvedPackage } from "../ResolvedPackage.js";
-import { extractWorkspaceDeps, framingFailure, importerDependencies, splitPeerSuffix, toIntegrityHash, validationFailure } from "./shared.js";
+import { extractWorkspaceDeps, framingFailure, importerDependencies, peerDeclarations, requireLockfileVersion, splitPeerSuffix, toIntegrityHash, validationFailure } from "./shared.js";
 import { PnpmExtension } from "../PnpmExtension.js";
 import { selectPnpmDocument } from "./documents.js";
 import { Effect, Schema } from "effect";
@@ -16,6 +16,18 @@ const PnpmImporter = Schema.Struct({
 	peerDependencies: PnpmImporterDeps,
 	optionalDependencies: PnpmImporterDeps
 });
+/**
+* The version gate's own input: `lockfileVersion` and nothing else.
+*
+* The gate has to read the version *before* the shape decode, because the
+* shape it decodes against is the shape of a supported version. `importers` is
+* a required key here and a pre-v9 single-project lockfile has none — it
+* records its dependencies at the top level — so a shape-first order reports a
+* lockfile we reject for being too old as merely malformed instead.
+*
+* @internal
+*/
+const PnpmVersionProbe = Schema.Struct({ lockfileVersion: Schema.Union([Schema.String, Schema.Number]) });
 const PnpmLockfileRaw = Schema.Struct({
 	lockfileVersion: Schema.Union([Schema.String, Schema.Number]),
 	settings: Schema.optionalKey(Schema.Struct({
@@ -28,7 +40,17 @@ const PnpmLockfileRaw = Schema.Struct({
 		version: Schema.String
 	})])))),
 	importers: Schema.Record(Schema.String, PnpmImporter),
-	packages: Schema.optionalKey(Schema.Record(Schema.String, Schema.Struct({ resolution: Schema.optionalKey(Schema.Struct({ integrity: Schema.optionalKey(Schema.String) })) })))
+	packages: Schema.optionalKey(Schema.Record(Schema.String, Schema.Struct({
+		resolution: Schema.optionalKey(Schema.Struct({ integrity: Schema.optionalKey(Schema.String) })),
+		peerDependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+		peerDependenciesMeta: Schema.optionalKey(Schema.Record(Schema.String, Schema.Struct({ optional: Schema.optionalKey(Schema.Boolean) }))),
+		dependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+		optionalDependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String))
+	}))),
+	snapshots: Schema.optionalKey(Schema.Record(Schema.String, Schema.Struct({
+		dependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+		optionalDependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String))
+	})))
 });
 /**
 * Parse pnpm `pnpm-lock.yaml` content into the unified field bundle.
@@ -48,10 +70,103 @@ const PnpmLockfileRaw = Schema.Struct({
 */
 const parsePnpm = (content) => Effect.gen(function* () {
 	const { document, documents } = yield* selectPnpmDocument(content);
+	const probe = yield* Schema.decodeUnknownEffect(PnpmVersionProbe)(document).pipe(Effect.mapError(validationFailure));
+	yield* requireLockfileVersion("pnpm", probe.lockfileVersion);
 	const validated = yield* Schema.decodeUnknownEffect(PnpmLockfileRaw)(document).pipe(Effect.mapError(validationFailure));
 	if (Object.keys(validated.importers).length === 0) return yield* Effect.fail(framingFailure("noImporters", documents));
 	return yield* toFields(validated);
 });
+/**
+* Resolve one instance's outgoing edges to instance ids.
+*
+* pnpm names a resolved dependency as `name` → `version`, where the version may
+* itself carry a peer suffix (`1.6.0(react@17.0.2)`); the referenced instance's
+* key is those two composed back together. The composition is *verified*
+* against the lockfile's own key set rather than trusted — the composed key is
+* v9's bare `name@version` and nothing else, because the format gate admits no
+* lockfile that spells keys the pre-v9 leading-slash way — and an edge that
+* matches nothing is **omitted**. That is what keeps a `link:`/`file:`
+* resolution, which names no instance in this lockfile, from becoming a
+* plausible lie.
+*
+* @internal
+*/
+const resolveEdges = (sections, instanceIds) => {
+	const edges = /* @__PURE__ */ new Map();
+	const unnameable = /* @__PURE__ */ new Set();
+	for (const section of sections) {
+		if (!section) continue;
+		for (const [name, version] of Object.entries(section)) {
+			if (name === "") continue;
+			if (version.startsWith(LINK_PREFIX)) {
+				const target = resolveLinkTarget("", version.slice(LINK_PREFIX.length));
+				if (target !== void 0 && instanceIds.has(target)) edges.set(name, target);
+				else unnameable.add(name);
+				continue;
+			}
+			const bare = `${name}@${version}`;
+			if (instanceIds.has(bare)) edges.set(name, bare);
+			else unnameable.add(name);
+		}
+	}
+	return {
+		resolved: Object.fromEntries(edges),
+		unresolvedEdges: [...unnameable].sort()
+	};
+};
+/** The protocol pnpm records a workspace-directory resolution under. @internal */
+const LINK_PREFIX = "link:";
+/**
+* Normalize a `link:` target against the linking importer's path, so a
+* workspace edge can name the workspace importer's instance id.
+* Total: a target that walks above the root yields `undefined`.
+*
+* @internal
+*/
+const resolveLinkTarget = (importerPath, target) => {
+	const segments = [];
+	for (const segment of `${importerPath}/${target}`.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			if (segments.pop() === void 0) return void 0;
+			continue;
+		}
+		segments.push(segment);
+	}
+	return segments.length === 0 ? void 0 : segments.join("/");
+};
+/**
+* Resolve one importer's outgoing edges. pnpm records `{ specifier, version }`
+* per importer dependency, where the version is either a registry version (the
+* instance-id composition {@link resolveEdges} performs) or a `link:` target
+* naming another importer — normalized against this importer's own path. Both
+* are checked against the lockfile's instance ids before being emitted.
+*
+* @internal
+*/
+const resolveImporterEdges = (importer, importerPath, instanceIds) => {
+	const edges = /* @__PURE__ */ new Map();
+	const unnameable = /* @__PURE__ */ new Set();
+	for (const group of importerDepGroups(importer)) {
+		if (!group) continue;
+		for (const [name, info] of Object.entries(group)) {
+			if (name === "") continue;
+			if (info.version.startsWith(LINK_PREFIX)) {
+				const target = resolveLinkTarget(importerPath, info.version.slice(5));
+				if (target !== void 0 && instanceIds.has(target)) edges.set(name, target);
+				else unnameable.add(name);
+				continue;
+			}
+			const bare = `${name}@${info.version}`;
+			if (instanceIds.has(bare)) edges.set(name, bare);
+			else unnameable.add(name);
+		}
+	}
+	return {
+		resolved: Object.fromEntries(edges),
+		unresolvedEdges: [...unnameable].sort()
+	};
+};
 const toVersionMap = (deps) => {
 	if (!deps) return void 0;
 	return Object.fromEntries(Object.entries(deps).map(([name, info]) => [name, info.specifier]));
@@ -92,28 +207,50 @@ const toFields = (raw) => Effect.gen(function* () {
 	}
 	for (const path of Object.keys(raw.importers)) if (path !== "." && path !== "") workspaceNames.add(path);
 	const packages = [];
-	for (const importerPath of Object.keys(raw.importers)) {
+	const snapshots = raw.snapshots;
+	const instanceIds = /* @__PURE__ */ new Set([
+		...snapshots ? Object.keys(snapshots) : [],
+		...raw.packages ? Object.keys(raw.packages) : [],
+		...Object.keys(raw.importers)
+	]);
+	const emitted = /* @__PURE__ */ new Set();
+	for (const [importerPath, importer] of Object.entries(raw.importers)) {
 		if (importerPath === "." || importerPath === "") continue;
 		packages.push(ResolvedPackage.make({
 			name: importerPath,
 			version: "0.0.0",
+			instanceId: importerPath,
 			isWorkspace: true,
-			relativePath: importerPath
+			relativePath: importerPath,
+			...resolveImporterEdges(importer, importerPath, instanceIds)
 		}));
 	}
-	if (raw.packages) for (const [key, pkg] of Object.entries(raw.packages)) {
-		const { plain: bare } = splitPeerSuffix(key);
+	const emit = (instanceId, meta, edges) => Effect.gen(function* () {
+		const { plain: bare } = splitPeerSuffix(instanceId);
 		const atIndex = bare.lastIndexOf("@");
-		if (atIndex <= 0) continue;
+		if (atIndex <= 0) return;
 		const name = bare.slice(0, atIndex);
 		const version = bare.slice(atIndex + 1);
-		const integrity = yield* toIntegrityHash(pkg.resolution?.integrity);
+		const integrity = yield* toIntegrityHash(meta?.resolution?.integrity);
+		emitted.add(instanceId);
 		packages.push(ResolvedPackage.make({
 			name,
 			version,
+			instanceId,
 			...integrity !== void 0 ? { integrity } : {},
-			isWorkspace: false
+			isWorkspace: false,
+			...peerDeclarations(meta?.peerDependencies, meta?.peerDependenciesMeta),
+			...resolveEdges(edges, instanceIds)
 		}));
+	});
+	if (snapshots) for (const [key, snapshot] of Object.entries(snapshots)) {
+		const plain = splitPeerSuffix(key).plain;
+		yield* emit(key, raw.packages !== void 0 && Object.hasOwn(raw.packages, plain) ? raw.packages[plain] : void 0, [snapshot.dependencies, snapshot.optionalDependencies]);
+	}
+	const covered = new Set([...emitted].map((key) => splitPeerSuffix(key).plain));
+	if (raw.packages) for (const [key, pkg] of Object.entries(raw.packages)) {
+		if (covered.has(key)) continue;
+		yield* emit(key, pkg, [pkg.dependencies, pkg.optionalDependencies]);
 	}
 	const workspaceDependencies = extractWorkspaceDeps(workspaceEntries, workspaceNames);
 	const extension = PnpmExtension.make({

package/internal/shared.js

@@ -114,6 +114,79 @@ const importerDependencies = (entry, read) => {
 	}
 	return deps;
 };
+const EMPTY_PEERS = {
+	peerDependencies: {},
+	peerDependenciesMeta: {}
+};
+/**
+* Normalize one format's peer declarations into the unified pair.
+*
+* Every format records the ranges the same way (a name→range map), but the
+* optional flag has two spellings: a `peerDependenciesMeta` object (pnpm, npm,
+* yarn Berry) and bun's `optionalPeers` array of names. Both are accepted and
+* collapse to `{ optional: boolean }` per peer, so a consumer reads one shape
+* regardless of which manager wrote the lockfile.
+*
+* Absence yields empty records, never `undefined` — an absent section means
+* "declares no peers", which is a fact, not a gap. Records are built with
+* `Object.fromEntries` (own-property semantics), so a `__proto__` peer name
+* neither pollutes nor drops.
+*
+* @internal
+*/
+const peerDeclarations = (peers, meta, optionalPeers) => {
+	if (peers === void 0 && meta === void 0 && optionalPeers === void 0) return EMPTY_PEERS;
+	const flags = /* @__PURE__ */ new Map();
+	if (meta !== void 0) for (const [name, value] of Object.entries(meta)) flags.set(name, value?.optional === true);
+	if (optionalPeers !== void 0) for (const name of optionalPeers) flags.set(name, true);
+	return {
+		peerDependencies: peers === void 0 ? {} : Object.fromEntries(Object.entries(peers)),
+		peerDependenciesMeta: Object.fromEntries([...flags].map(([name, optional]) => [name, { optional }]))
+	};
+};
+/**
+* The minimum lockfile-format version each gated format is parsed at.
+*
+* This is a deliberate narrowing of the supported input domain, not an
+* implementation detail: an older lockfile fails typed rather than parsing
+* into a model that cannot answer resolution questions. Note the gate is on
+* the **lockfile format version**, which is the only version a lockfile
+* records — the writing package manager's version is not recoverable from the
+* file, so no manager-version claim could be enforced here.
+*
+* @internal
+*/
+const MINIMUM_LOCKFILE_VERSION = {
+	pnpm: 9,
+	npm: 3
+};
+/**
+* Fail typed when a lockfile predates the supported format version.
+*
+* Routed through {@link validationFailure} rather than {@link framingFailure}:
+* the document was located perfectly well, so this is a shape judgement about
+* a located document, not a framing problem. The cause is a structured record
+* rather than an engine error, so a consumer can tell "your lockfile is too
+* old" from "your lockfile is malformed" without parsing a message.
+*
+* A version that is not a number at all (`lockfileVersion: "next"`) is not a
+* supported version either, and fails the same way.
+*
+* @internal
+*/
+const requireLockfileVersion = (format, raw) => {
+	const minimum = MINIMUM_LOCKFILE_VERSION[format];
+	const parsed = typeof raw === "number" ? raw : Number.parseFloat(raw);
+	if (Number.isFinite(parsed) && parsed >= minimum) return Effect.void;
+	const cause = {
+		_tag: "UnsupportedLockfileVersion",
+		format,
+		lockfileVersion: raw,
+		minimumSupported: minimum,
+		message: `${format} lockfileVersion ${JSON.stringify(raw)} is not supported: @effected/lockfiles parses ${format} lockfileVersion ${minimum} and newer`
+	};
+	return Effect.fail(validationFailure(cause));
+};
 /** @internal */
 const syntaxFailure = (cause) => ({
 	stage: "syntax",
@@ -162,4 +235,4 @@ const extractWorkspaceDeps = (workspaces, workspaceNames) => {
 };
 
 //#endregion
-export { DEP_TYPES, extractWorkspaceDeps, framingFailure, importerDependencies, isWorkspaceSpecifier, splitPeerSuffix, syntaxFailure, toIntegrityHash, validationFailure };
+export { DEP_TYPES, MINIMUM_LOCKFILE_VERSION, extractWorkspaceDeps, framingFailure, importerDependencies, isWorkspaceSpecifier, peerDeclarations, requireLockfileVersion, splitPeerSuffix, syntaxFailure, toIntegrityHash, validationFailure };

package/internal/yarn.js

@@ -1,5 +1,5 @@
 import { ResolvedPackage } from "../ResolvedPackage.js";
-import { extractWorkspaceDeps, toIntegrityHash, validationFailure } from "./shared.js";
+import { extractWorkspaceDeps, peerDeclarations, toIntegrityHash, validationFailure } from "./shared.js";
 import { selectSoleDocument } from "./documents.js";
 import { Effect, Schema } from "effect";
 
@@ -12,6 +12,7 @@ const YarnEntry = Schema.Struct({
 	dependencies: DepRecord,
 	devDependencies: DepRecord,
 	peerDependencies: DepRecord,
+	peerDependenciesMeta: Schema.optionalKey(Schema.Record(Schema.String, Schema.Struct({ optional: Schema.optionalKey(Schema.Boolean) }))),
 	optionalDependencies: DepRecord,
 	checksum: Schema.optionalKey(Schema.String),
 	languageName: Schema.optionalKey(Schema.String),
@@ -45,6 +46,13 @@ const toFields = (lockfileVersion, decoded) => Effect.gen(function* () {
 	const packages = [];
 	const workspaceNames = /* @__PURE__ */ new Set();
 	const workspaceEntries = /* @__PURE__ */ new Map();
+	const locators = /* @__PURE__ */ new Map();
+	for (const [key, entry] of decoded) {
+		const descriptors = key.split(", ");
+		const locator = entry.resolution ?? descriptors[0];
+		if (locator === void 0 || locator === "") continue;
+		for (const descriptor of descriptors) if (descriptor !== "") locators.set(descriptor, locator);
+	}
 	for (const [key, entry] of decoded) if (entry.linkType === "soft") {
 		const name = extractYarnPackageName(key);
 		if (name !== void 0) workspaceNames.add(name);
@@ -55,12 +63,17 @@ const toFields = (lockfileVersion, decoded) => Effect.gen(function* () {
 		const isWorkspace = entry.linkType === "soft";
 		const relativePath = isWorkspace ? extractYarnWorkspacePath(key) : void 0;
 		const integrity = yield* toIntegrityHash(entry.checksum);
+		const instanceId = entry.resolution ?? key.split(", ")[0] ?? "";
+		if (instanceId === "") continue;
 		packages.push(ResolvedPackage.make({
 			name,
 			version: entry.version ?? "0.0.0",
+			instanceId,
 			...integrity !== void 0 ? { integrity } : {},
 			isWorkspace,
-			...relativePath !== void 0 ? { relativePath } : {}
+			...relativePath !== void 0 ? { relativePath } : {},
+			...peerDeclarations(entry.peerDependencies, entry.peerDependenciesMeta),
+			...resolveYarnEdges(entry, locators)
 		}));
 		if (isWorkspace) {
 			const deps = cleanYarnDeps(entry.dependencies);
@@ -83,6 +96,46 @@ const toFields = (lockfileVersion, decoded) => Effect.gen(function* () {
 	};
 });
 /**
+* Resolve one entry's outgoing edges through the descriptor→locator index.
+*
+* A yarn dependency value is a *descriptor* range (`"npm:5.3.0"`), and the
+* lockfile keys enumerate exactly which descriptors resolve to which locator,
+* so the lookup is exact rather than reconstructed.
+*
+* **`devDependencies` is not a section a Berry lockfile has.** yarn folds a
+* workspace's dev declarations into the entry's `dependencies` map — the
+* lockfile a project produces is byte-identical whether a dependency is
+* declared under `dependencies` or `devDependencies` (probed against yarn
+* 4.9.1). Dev edges are therefore already resolved here; iterating
+* `entry.devDependencies` would be dead code, and the schema keeps the field
+* only as permissive scaffolding for hand-edited input.
+*
+* **Dependency edges only.** yarn resolves peers virtually — a peer-bearing
+* package gets a `@virtual:` locator per consumer, and this lockfile shape does
+* not record which one satisfied which peer. Emitting a peer edge here would
+* mean guessing, so peers are left out: an absent edge is a true statement, a
+* plausible one would not be.
+*
+* @internal
+*/
+const resolveYarnEdges = (entry, locators) => {
+	const edges = /* @__PURE__ */ new Map();
+	const unnameable = /* @__PURE__ */ new Set();
+	for (const section of [entry.dependencies, entry.optionalDependencies]) {
+		if (!section) continue;
+		for (const [name, range] of Object.entries(section)) {
+			if (name === "") continue;
+			const locator = locators.get(`${name}@${range}`);
+			if (locator !== void 0) edges.set(name, locator);
+			else unnameable.add(name);
+		}
+	}
+	return {
+		resolved: Object.fromEntries(edges),
+		unresolvedEdges: [...unnameable].sort()
+	};
+};
+/**
 * Extract the package name from a yarn lockfile key. Handles compound keys
 * (`"a@workspace:*, a@workspace:packages/a"`) via the first descriptor and
 * `@patch:` descriptors (which embed `@npm:` inside). Total: malformed keys

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/lockfiles",
-	"version": "0.5.1",
+	"version": "0.6.0",
 	"private": false,
 	"description": "Pure lockfile parsing for bun, npm, pnpm and yarn Berry into one unified Effect schema model, with pure integrity checking against workspace manifests.",
 	"keywords": [