@effected/lockfiles 0.10.0 → 0.12.0-next-20260927062352

package/ConfigDependencyLock.js

@@ -0,0 +1,36 @@
+import { Schema } from "effect";
+
+//#region src/ConfigDependencyLock.ts
+/**
+* One config dependency a `pnpm-lock.yaml` records, with the integrity pnpm
+* recorded for it — read from the lockfile's env preamble by
+* `PnpmEnvLockfile.configDependencies`.
+*
+* @remarks
+* pnpm 11 and 12 record each `configDependencies` entry of
+* `pnpm-workspace.yaml` as the root importer's `configDependencies` in the env
+* preamble document, and its integrity in the preamble's `packages:` section.
+* A workspace that writes its `configDependencies` as bare versions keeps the
+* integrity only here, which makes the lockfile the checksum store for its
+* config dependencies, as it is for the package manager
+* (`PackageManagerLock`).
+*
+* - `name` — the config dependency's package name.
+* - `specifier` — the specifier pnpm recorded, verbatim. pnpm records the bare
+*   version even when `pnpm-workspace.yaml` declares the legacy inline
+*   `<version>+<integrity>` form.
+* - `version` — the exact version pnpm resolved the specifier to.
+* - `integrity` — the SRI integrity (`sha512-<base64>`) of
+*   `<name>@<version>`.
+*
+* @public
+*/
+var ConfigDependencyLock = class extends Schema.Class("ConfigDependencyLock")({
+	name: Schema.String,
+	specifier: Schema.String,
+	version: Schema.String,
+	integrity: Schema.String
+}) {};
+
+//#endregion
+export { ConfigDependencyLock };

package/Lockfile.js

@@ -61,9 +61,14 @@ var LockfileParseError = class extends Schema.TaggedError()("LockfileParseError"
 *     such a file as having no lockfile.
 *   - `"noImporters"` — the located document declares no importers, so it
 *     describes no workspace. pnpm always records at least the root importer.
-*   - `"unexpectedDocuments"` — the stream carries several documents in a
-*     format that defines no document framing (yarn). Rather than silently
-*     taking the first, parsing refuses to guess.
+*   - `"unexpectedDocuments"` — the stream carries more documents than the
+*     format's framing defines: several in a format that defines none
+*     (yarn), or more than the env preamble and the lockfile when reading a
+*     pnpm env preamble. Rather than silently picking one, parsing refuses to
+*     guess. For pnpm the limit is the env reader's alone:
+*     `PnpmEnvLockfile` enforces at most two documents, while
+*     `Lockfile.parse` reads the last document of a stream of any count and
+*     never fails with this reason.
 *
 * It carries typed fields rather than a `cause`: unlike
 * {@link LockfileParseError}, there is no underlying engine failure to wrap —
@@ -81,10 +86,27 @@ var LockfileFramingError = class extends Schema.TaggedError()("LockfileFramingEr
 	documents: Schema.Int
 }) {
 	get message() {
-		const detail = this.reason === "noImporters" ? "the lockfile document declares no importers, so it describes no workspace" : this.reason === "unexpectedDocuments" ? `expected a single YAML document but the content carries ${this.documents}` : `the content carries no lockfile document (${this.documents} YAML document(s) found)`;
+		const detail = this.reason === "noImporters" ? "the lockfile document declares no importers, so it describes no workspace" : this.reason === "unexpectedDocuments" ? this.format === "pnpm" ? `expected at most two YAML documents (an env preamble and the lockfile) but the content carries ${this.documents}` : `expected a single YAML document but the content carries ${this.documents}` : `the content carries no lockfile document (${this.documents} YAML document(s) found)`;
 		return `Failed to parse ${this.format} lockfile: ${detail}`;
 	}
 };
+/**
+* Materialize an internal {@link ParseFailure} record into the public error
+* union — the one mapping every public fallible boundary shares, so
+* `Lockfile.parse` and `PnpmEnvLockfile.packageManager` cannot disagree about
+* which failure is which.
+*
+* @internal
+*/
+const materializeFailure = (format, failure) => failure.stage === "framing" ? new LockfileFramingError({
+	format,
+	reason: failure.reason,
+	documents: failure.documents
+}) : new LockfileParseError({
+	format,
+	stage: failure.stage,
+	cause: failure.cause
+});
 const dispatch = (format, content) => {
 	switch (format) {
 		case "bun": return parseBun(content);
@@ -144,15 +166,7 @@ var Lockfile = class Lockfile extends Schema.Class("Lockfile")({
 	*   multi-document `pnpm-lock.yaml` needs it).
 	*/
 	static parse = Effect.fn("Lockfile.parse")(function* (content, options) {
-		const fields = yield* dispatch(options.format, content).pipe(Effect.mapError((failure) => failure.stage === "framing" ? new LockfileFramingError({
-			format: options.format,
-			reason: failure.reason,
-			documents: failure.documents
-		}) : new LockfileParseError({
-			format: options.format,
-			stage: failure.stage,
-			cause: failure.cause
-		})));
+		const fields = yield* dispatch(options.format, content).pipe(Effect.mapError((failure) => materializeFailure(options.format, failure)));
 		return Lockfile.make({
 			format: options.format,
 			lockfileVersion: fields.lockfileVersion,
@@ -288,4 +302,4 @@ var Lockfile = class Lockfile extends Schema.Class("Lockfile")({
 };
 
 //#endregion
-export { Lockfile, LockfileFramingError, LockfileParseError };
+export { Lockfile, LockfileFramingError, LockfileParseError, materializeFailure };

package/PackageManagerLock.js

@@ -0,0 +1,42 @@
+import { Schema } from "effect";
+
+//#region src/PackageManagerLock.ts
+/**
+* The package manager a `pnpm-lock.yaml` pins, with the integrity pnpm
+* recorded for it — read from the lockfile's env preamble by
+* `PnpmEnvLockfile.packageManager`.
+*
+* @remarks
+* pnpm records the package manager a workspace declares in
+* `devEngines.packageManager` as the root importer's
+* `packageManagerDependencies` in the env preamble document, and resolves it
+* like any other dependency: the preamble's `packages:` section carries its
+* integrity, and pnpm refuses to run a manager whose identity does not match.
+* That makes the lockfile, not the `+sha512.<hex>` suffix on the declared
+* version, the checksum store for the manager itself.
+*
+* - `name` — the package-manager package, always `"pnpm"`.
+* - `specifier` — the declared specifier, verbatim. It may still carry the
+*   corepack-style `+sha512.<hex>` suffix the manifest declared it with.
+* - `version` — the exact version pnpm resolved the specifier to.
+* - `integrity` — the SRI integrity (`sha512-<base64>`) of the
+*   `pnpm@<version>` package.
+* - `nativeIntegrity` — SRI integrity per native package, keyed by package
+*   name with no version (`"@pnpm/exe.linux-x64"`): every package the lockfile
+*   records as an optional dependency of `pnpm@<version>`. pnpm 12 records one
+*   `@pnpm/exe.<target>` entry per platform there; pnpm 11 records none, so
+*   the record is empty — pnpm 11 hangs its platform binaries off a separate
+*   `@pnpm/exe` wrapper entry instead, which this model does not carry.
+*
+* @public
+*/
+var PackageManagerLock = class extends Schema.Class("PackageManagerLock")({
+	name: Schema.Literal("pnpm"),
+	specifier: Schema.String,
+	version: Schema.String,
+	integrity: Schema.String,
+	nativeIntegrity: Schema.Record(Schema.String, Schema.String)
+}) {};
+
+//#endregion
+export { PackageManagerLock };

package/PnpmEnvLockfile.js

@@ -0,0 +1,37 @@
+import { materializeFailure } from "./Lockfile.js";
+import { readPnpmConfigDependencies, readPnpmPackageManager } from "./internal/pnpmEnv.js";
+import { Effect, Option } from "effect";
+
+//#region src/PnpmEnvLockfile.ts
+/** Both readers surface an internal `ParseFailure` the one way `Lockfile.parse` does. */
+const materialize = Effect.mapError((failure) => materializeFailure("pnpm", failure));
+const packageManager = Effect.fn("PnpmEnvLockfile.packageManager")((content) => readPnpmPackageManager(content).pipe(materialize, Effect.map(Option.fromUndefinedOr)));
+const configDependencies = Effect.fn("PnpmEnvLockfile.configDependencies")((content) => readPnpmConfigDependencies(content).pipe(materialize));
+/**
+* Readers over the env ("preamble") document of a `pnpm-lock.yaml` — see
+* {@link PnpmEnvLockfileReaders}.
+*
+* @example
+* ```typescript
+* import { PnpmEnvLockfile } from "@effected/lockfiles";
+* import { Effect, Option } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const lock = yield* PnpmEnvLockfile.packageManager(content);
+*   const configDependencies = yield* PnpmEnvLockfile.configDependencies(content);
+*   return {
+*     pnpm: Option.map(lock, (pm) => pm.integrity),
+*     plugin: configDependencies.get("@effected/pnpm-plugin-effect")?.integrity,
+*   };
+* });
+* ```
+*
+* @public
+*/
+const PnpmEnvLockfile = {
+	packageManager,
+	configDependencies
+};
+
+//#endregion
+export { PnpmEnvLockfile };

package/index.d.ts

@@ -1,4 +1,5 @@
 import { Effect, Option, Schema } from "effect";
+import "@effected/npm";
 //#region src/BunExtension.d.ts
 declare const BunExtension_base: Schema.Class<BunExtension, Schema.Struct<{
   readonly _tag: Schema.tag<"bun">;
@@ -21,6 +22,39 @@ declare const BunExtension_base: Schema.Class<BunExtension, Schema.Struct<{
  */
 export declare class BunExtension extends BunExtension_base {}
 //#endregion
+//#region src/ConfigDependencyLock.d.ts
+declare const ConfigDependencyLock_base: Schema.Class<ConfigDependencyLock, Schema.Struct<{
+  readonly name: Schema.String;
+  readonly specifier: Schema.String;
+  readonly version: Schema.String;
+  readonly integrity: Schema.String;
+}>, {}>;
+/**
+ * One config dependency a `pnpm-lock.yaml` records, with the integrity pnpm
+ * recorded for it — read from the lockfile's env preamble by
+ * `PnpmEnvLockfile.configDependencies`.
+ *
+ * @remarks
+ * pnpm 11 and 12 record each `configDependencies` entry of
+ * `pnpm-workspace.yaml` as the root importer's `configDependencies` in the env
+ * preamble document, and its integrity in the preamble's `packages:` section.
+ * A workspace that writes its `configDependencies` as bare versions keeps the
+ * integrity only here, which makes the lockfile the checksum store for its
+ * config dependencies, as it is for the package manager
+ * (`PackageManagerLock`).
+ *
+ * - `name` — the config dependency's package name.
+ * - `specifier` — the specifier pnpm recorded, verbatim. pnpm records the bare
+ *   version even when `pnpm-workspace.yaml` declares the legacy inline
+ *   `<version>+<integrity>` form.
+ * - `version` — the exact version pnpm resolved the specifier to.
+ * - `integrity` — the SRI integrity (`sha512-<base64>`) of
+ *   `<name>@<version>`.
+ *
+ * @public
+ */
+export declare class ConfigDependencyLock extends ConfigDependencyLock_base {}
+//#endregion
 //#region src/ImporterDependency.d.ts
 declare const ImporterDependency_base: Schema.Class<ImporterDependency, Schema.Struct<{
   readonly name: Schema.NonEmptyString;
@@ -60,77 +94,6 @@ declare const ImporterDependency_base: Schema.Class<ImporterDependency, Schema.S
  */
 export declare class ImporterDependency extends ImporterDependency_base {}
 //#endregion
-//#region src/LockfileFormat.d.ts
-/**
- * The lockfile formats this package parses: bun's `bun.lock` (JSONC), npm's
- * `package-lock.json` (JSON), pnpm's `pnpm-lock.yaml` and yarn Berry's
- * `yarn.lock` (both YAML).
- *
- * @remarks
- * The literal names the *lockfile format*, not the package manager that
- * happens to write it — this package models lockfiles. Yarn support is
- * 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
- */
-export declare const LockfileFormat: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
-/**
- * The union of supported lockfile format names.
- *
- * @public
- */
-export type LockfileFormat = typeof LockfileFormat.Type;
-/**
- * The conventional lockfile filename for a format: `"bun.lock"`,
- * `"package-lock.json"`, `"pnpm-lock.yaml"` or `"yarn.lock"`.
- *
- * @remarks
- * The primary name only — the first element of {@link filenamesFor}, which is
- * what detection that must also see the genuine alternates should use.
- *
- * @public
- */
-export declare const filenameFor: (format: LockfileFormat) => string;
-/**
- * Every filename a format is genuinely written under, primary first.
- *
- * @remarks
- * Real detection needs more than the conventional name: npm honours
- * `npm-shrinkwrap.json` (and prefers it over `package-lock.json` when both
- * exist — the ordering here is conventional-name-first, not npm's own
- * precedence), and bun has shipped two formats, the current text `bun.lock`
- * and the older **binary** `bun.lockb`. pnpm and yarn each have exactly one.
- *
- * Only genuine *lockfile* spellings appear here. Files that merely influence
- * what an install resolves to — `pnpm-workspace.yaml`, `.pnpmfile.cjs`, yarn's
- * PnP artifacts — are a consumer's cache policy, not alternates of the
- * lockfile.
- *
- * Two deliberate asymmetries with the rest of this module: `bun.lockb` is a
- * detection alternate but not a parse target (`Lockfile.parse` takes text; the
- * binary format fails typed), and {@link fromFilename} keeps answering for the
- * primary names only.
- *
- * @public
- */
-export declare const filenamesFor: (format: LockfileFormat) => readonly [string, ...ReadonlyArray<string>];
-/**
- * The format a lockfile filename identifies, if any.
- *
- * @remarks
- * Matches exact conventional filenames only (`"bun.lock"`,
- * `"package-lock.json"`, `"pnpm-lock.yaml"`, `"yarn.lock"`) — paths, other
- * spellings and the {@link filenamesFor} alternates return `Option.none()`.
- *
- * @public
- */
-export declare const fromFilename: (name: string) => Option.Option<LockfileFormat>;
-//#endregion
 //#region src/LockfileImporter.d.ts
 declare const LockfileImporter_base: Schema.Class<LockfileImporter, Schema.Struct<{
   readonly path: Schema.NonEmptyString;
@@ -317,6 +280,77 @@ declare const WorkspaceDependency_base: Schema.Class<WorkspaceDependency, Schema
  */
 export declare class WorkspaceDependency extends WorkspaceDependency_base {}
 //#endregion
+//#region src/LockfileFormat.d.ts
+/**
+ * The lockfile formats this package parses: bun's `bun.lock` (JSONC), npm's
+ * `package-lock.json` (JSON), pnpm's `pnpm-lock.yaml` and yarn Berry's
+ * `yarn.lock` (both YAML).
+ *
+ * @remarks
+ * The literal names the *lockfile format*, not the package manager that
+ * happens to write it — this package models lockfiles. Yarn support is
+ * 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
+ */
+export declare const LockfileFormat: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
+/**
+ * The union of supported lockfile format names.
+ *
+ * @public
+ */
+export type LockfileFormat = typeof LockfileFormat.Type;
+/**
+ * The conventional lockfile filename for a format: `"bun.lock"`,
+ * `"package-lock.json"`, `"pnpm-lock.yaml"` or `"yarn.lock"`.
+ *
+ * @remarks
+ * The primary name only — the first element of {@link filenamesFor}, which is
+ * what detection that must also see the genuine alternates should use.
+ *
+ * @public
+ */
+export declare const filenameFor: (format: LockfileFormat) => string;
+/**
+ * Every filename a format is genuinely written under, primary first.
+ *
+ * @remarks
+ * Real detection needs more than the conventional name: npm honours
+ * `npm-shrinkwrap.json` (and prefers it over `package-lock.json` when both
+ * exist — the ordering here is conventional-name-first, not npm's own
+ * precedence), and bun has shipped two formats, the current text `bun.lock`
+ * and the older **binary** `bun.lockb`. pnpm and yarn each have exactly one.
+ *
+ * Only genuine *lockfile* spellings appear here. Files that merely influence
+ * what an install resolves to — `pnpm-workspace.yaml`, `.pnpmfile.cjs`, yarn's
+ * PnP artifacts — are a consumer's cache policy, not alternates of the
+ * lockfile.
+ *
+ * Two deliberate asymmetries with the rest of this module: `bun.lockb` is a
+ * detection alternate but not a parse target (`Lockfile.parse` takes text; the
+ * binary format fails typed), and {@link fromFilename} keeps answering for the
+ * primary names only.
+ *
+ * @public
+ */
+export declare const filenamesFor: (format: LockfileFormat) => readonly [string, ...ReadonlyArray<string>];
+/**
+ * The format a lockfile filename identifies, if any.
+ *
+ * @remarks
+ * Matches exact conventional filenames only (`"bun.lock"`,
+ * `"package-lock.json"`, `"pnpm-lock.yaml"`, `"yarn.lock"`) — paths, other
+ * spellings and the {@link filenamesFor} alternates return `Option.none()`.
+ *
+ * @public
+ */
+export declare const fromFilename: (name: string) => Option.Option<LockfileFormat>;
+//#endregion
 //#region src/Lockfile.d.ts
 declare const LockfileParseError_base: Schema.Class<LockfileParseError, Schema.TaggedStruct<"LockfileParseError", {
   readonly format: Schema.Literals<readonly ["bun", "npm", "pnpm", "yarn"]>;
@@ -371,9 +405,14 @@ declare const LockfileFramingError_base: Schema.Class<LockfileFramingError, Sche
  *     such a file as having no lockfile.
  *   - `"noImporters"` — the located document declares no importers, so it
  *     describes no workspace. pnpm always records at least the root importer.
- *   - `"unexpectedDocuments"` — the stream carries several documents in a
- *     format that defines no document framing (yarn). Rather than silently
- *     taking the first, parsing refuses to guess.
+ *   - `"unexpectedDocuments"` — the stream carries more documents than the
+ *     format's framing defines: several in a format that defines none
+ *     (yarn), or more than the env preamble and the lockfile when reading a
+ *     pnpm env preamble. Rather than silently picking one, parsing refuses to
+ *     guess. For pnpm the limit is the env reader's alone:
+ *     `PnpmEnvLockfile` enforces at most two documents, while
+ *     `Lockfile.parse` reads the last document of a stream of any count and
+ *     never fails with this reason.
  *
  * It carries typed fields rather than a `cause`: unlike
  * {@link LockfileParseError}, there is no underlying engine failure to wrap —
@@ -568,6 +607,131 @@ export declare class LockfileIntegrity extends LockfileIntegrity_base {
   static compare(lockfile: Lockfile, manifests: ReadonlyArray<WorkspaceManifest>): LockfileIntegrity;
 }
 //#endregion
+//#region src/PackageManagerLock.d.ts
+declare const PackageManagerLock_base: Schema.Class<PackageManagerLock, Schema.Struct<{
+  readonly name: Schema.Literal<"pnpm">;
+  readonly specifier: Schema.String;
+  readonly version: Schema.String;
+  readonly integrity: Schema.String;
+  readonly nativeIntegrity: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+/**
+ * The package manager a `pnpm-lock.yaml` pins, with the integrity pnpm
+ * recorded for it — read from the lockfile's env preamble by
+ * `PnpmEnvLockfile.packageManager`.
+ *
+ * @remarks
+ * pnpm records the package manager a workspace declares in
+ * `devEngines.packageManager` as the root importer's
+ * `packageManagerDependencies` in the env preamble document, and resolves it
+ * like any other dependency: the preamble's `packages:` section carries its
+ * integrity, and pnpm refuses to run a manager whose identity does not match.
+ * That makes the lockfile, not the `+sha512.<hex>` suffix on the declared
+ * version, the checksum store for the manager itself.
+ *
+ * - `name` — the package-manager package, always `"pnpm"`.
+ * - `specifier` — the declared specifier, verbatim. It may still carry the
+ *   corepack-style `+sha512.<hex>` suffix the manifest declared it with.
+ * - `version` — the exact version pnpm resolved the specifier to.
+ * - `integrity` — the SRI integrity (`sha512-<base64>`) of the
+ *   `pnpm@<version>` package.
+ * - `nativeIntegrity` — SRI integrity per native package, keyed by package
+ *   name with no version (`"@pnpm/exe.linux-x64"`): every package the lockfile
+ *   records as an optional dependency of `pnpm@<version>`. pnpm 12 records one
+ *   `@pnpm/exe.<target>` entry per platform there; pnpm 11 records none, so
+ *   the record is empty — pnpm 11 hangs its platform binaries off a separate
+ *   `@pnpm/exe` wrapper entry instead, which this model does not carry.
+ *
+ * @public
+ */
+export declare class PackageManagerLock extends PackageManagerLock_base {}
+//#endregion
+//#region src/PnpmEnvLockfile.d.ts
+/**
+ * Readers over the env ("preamble") document of a `pnpm-lock.yaml`.
+ *
+ * @remarks
+ * A `pnpm-lock.yaml` is a YAML stream. When a workspace declares
+ * `devEngines.packageManager` or `configDependencies`, pnpm writes an env
+ * preamble document ahead of the lockfile proper: the preamble is always the
+ * **first** of two documents, the lockfile always the **last**.
+ * `Lockfile.parse` reads the last; these readers read the first.
+ *
+ * @public
+ */
+interface PnpmEnvLockfileReaders {
+  /**
+   * Read the package manager a `pnpm-lock.yaml` pins, with its recorded
+   * integrity. Pure: takes the lockfile text, performs no IO.
+   *
+   * @param content - The `pnpm-lock.yaml` text.
+   * @returns `Option.none()` when the lockfile records no package manager —
+   *   a single-document lockfile (no preamble; pnpm writes none for a
+   *   workspace declaring neither `devEngines.packageManager` nor
+   *   `configDependencies`), or a preamble whose root importer declares no
+   *   `pnpm` in `packageManagerDependencies`. Otherwise `Option.some` of the
+   *   {@link PackageManagerLock}.
+   *
+   * Fails with {@link LockfileParseError} when the text is not well-formed
+   * YAML (`stage: "syntax"`), or when the preamble is malformed or records a
+   * claim it cannot back (`stage: "validation"`): `pnpm@<version>` with no
+   * `packages` entry, snapshot or SRI integrity, or a native optional
+   * dependency with no SRI integrity. A lockfile that names a version it
+   * cannot account for is a failure, never `none`. Fails with
+   * {@link LockfileFramingError} (`reason: "unexpectedDocuments"`) when the
+   * stream carries more than two documents, since no position then
+   * identifies the preamble.
+   */
+  readonly packageManager: (content: string) => Effect.Effect<Option.Option<PackageManagerLock>, LockfileParseError | LockfileFramingError>;
+  /**
+   * Read the config dependencies a `pnpm-lock.yaml` records, each with its
+   * recorded integrity. Pure: takes the lockfile text, performs no IO.
+   *
+   * @remarks
+   * The integrity source for a `configDependencies` entry written as a bare
+   * version: pnpm 11 and 12 keep it here rather than inline in
+   * `pnpm-workspace.yaml`. Read by `@effected/workspaces` to verify a config
+   * dependency it fetches at a version this checkout never installed.
+   *
+   * @param content - The `pnpm-lock.yaml` text.
+   * @returns A map keyed by config-dependency name. Empty when the lockfile
+   *   records none — a single-document lockfile (no preamble), or a preamble
+   *   whose root importer declares no `configDependencies`.
+   *
+   * Fails exactly as {@link PnpmEnvLockfileReaders.packageManager} does, with
+   * {@link LockfileParseError} for broken YAML (`stage: "syntax"`) or a
+   * malformed preamble (`stage: "validation"`), and with
+   * {@link LockfileFramingError} (`reason: "unexpectedDocuments"`) for more
+   * than two documents. A recorded entry the lockfile cannot back fails at
+   * `stage: "validation"`: an empty version, or a `<name>@<version>` with no
+   * `packages` entry, no `resolution.integrity`, or an integrity that is not
+   * SRI. An entry is never silently dropped.
+   */
+  readonly configDependencies: (content: string) => Effect.Effect<ReadonlyMap<string, ConfigDependencyLock>, LockfileParseError | LockfileFramingError>;
+}
+/**
+ * Readers over the env ("preamble") document of a `pnpm-lock.yaml` — see
+ * {@link PnpmEnvLockfileReaders}.
+ *
+ * @example
+ * ```typescript
+ * import { PnpmEnvLockfile } from "@effected/lockfiles";
+ * import { Effect, Option } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const lock = yield* PnpmEnvLockfile.packageManager(content);
+ *   const configDependencies = yield* PnpmEnvLockfile.configDependencies(content);
+ *   return {
+ *     pnpm: Option.map(lock, (pm) => pm.integrity),
+ *     plugin: configDependencies.get("@effected/pnpm-plugin-effect")?.integrity,
+ *   };
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare const PnpmEnvLockfile: PnpmEnvLockfileReaders;
+//#endregion
 //#region src/UnsupportedLockfileVersion.d.ts
 /**
  * The cause a {@link LockfileParseError} carries when a lockfile predates the
@@ -633,5 +797,5 @@ interface UnsupportedLockfileVersion {
  */
 export declare const isUnsupportedLockfileVersion: (cause: unknown) => cause is UnsupportedLockfileVersion;
 //#endregion
-export type { PnpmCatalogs, UnsupportedLockfileVersion };
+export type { PnpmCatalogs, PnpmEnvLockfileReaders, UnsupportedLockfileVersion };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,4 +1,5 @@
 import { BunExtension } from "./BunExtension.js";
+import { ConfigDependencyLock } from "./ConfigDependencyLock.js";
 import { ImporterDependency } from "./ImporterDependency.js";
 import { LockfileImporter } from "./LockfileImporter.js";
 import { ResolvedPackage } from "./ResolvedPackage.js";
@@ -7,6 +8,8 @@ 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 { PackageManagerLock } from "./PackageManagerLock.js";
+import { PnpmEnvLockfile } from "./PnpmEnvLockfile.js";
 import { isUnsupportedLockfileVersion } from "./UnsupportedLockfileVersion.js";
 
-export { BunExtension, ImporterDependency, Lockfile, LockfileFormat, LockfileFramingError, LockfileImporter, LockfileIntegrity, LockfileParseError, PnpmExtension, ResolvedPackage, WorkspaceDependency, WorkspaceManifest, filenameFor, filenamesFor, fromFilename, isUnsupportedLockfileVersion };
+export { BunExtension, ConfigDependencyLock, ImporterDependency, Lockfile, LockfileFormat, LockfileFramingError, LockfileImporter, LockfileIntegrity, LockfileParseError, PackageManagerLock, PnpmEnvLockfile, PnpmExtension, ResolvedPackage, WorkspaceDependency, WorkspaceManifest, filenameFor, filenamesFor, fromFilename, isUnsupportedLockfileVersion };

package/internal/documents.js

@@ -36,6 +36,10 @@ const isEmptyDocument = (document) => document === null || document === void 0;
 * document. pnpm reads that as "no lockfile"; so do we, through the typed
 * framing failure — never by silently falling back to the preamble.
 *
+* It takes the last document of a stream of **any** count and never fails
+* with `unexpectedDocuments`; only {@link selectPnpmEnvDocument}, the env
+* reader's selector, enforces the at-most-two limit.
+*
 * @internal
 */
 const selectPnpmDocument = (content) => Effect.gen(function* () {
@@ -71,6 +75,46 @@ const selectSoleDocument = (content) => Effect.gen(function* () {
 		documents: documents.length
 	};
 });
+/**
+* The number of documents pnpm's env-lockfile writer can compose: the env
+* preamble and the main lockfile. See {@link selectPnpmEnvDocument}.
+*
+* @internal
+*/
+const MAX_PNPM_DOCUMENTS = 2;
+/**
+* Select the env ("preamble") document from a `pnpm-lock.yaml` YAML stream,
+* or `undefined` when the stream carries none.
+*
+* @remarks
+* The same position rule as {@link selectPnpmDocument}, read from the other
+* end: pnpm's `writeEnvLockfile` composes `${env}---${main}`, so the preamble
+* is the **first** of exactly two documents. A single-document stream has no
+* preamble — that is how pnpm writes a lockfile for a workspace that declares
+* neither `configDependencies` nor `devEngines.packageManager` — and neither
+* does an empty one. An empty first document is no preamble either: there is
+* nothing in it to read.
+*
+* A stream carrying **more** than two documents is outside the writer
+* contract, so no position identifies the preamble in it. Rather than guess —
+* this selection feeds integrity verification, where a guess is a trust
+* decision — it fails through the typed framing channel. That limit is this
+* selector's alone: {@link selectPnpmDocument}, behind `Lockfile.parse`, takes
+* the last document of a stream of any count.
+*
+* @internal
+*/
+const selectPnpmEnvDocument = (content) => Effect.gen(function* () {
+	const documents = yield* Yaml.parseAll(content).pipe(Effect.mapError(syntaxFailure));
+	if (documents.length > MAX_PNPM_DOCUMENTS) return yield* Effect.fail(framingFailure("unexpectedDocuments", documents.length));
+	if (documents.length < MAX_PNPM_DOCUMENTS) return void 0;
+	const document = documents.at(0);
+	if (isEmptyDocument(document)) return void 0;
+	return {
+		document,
+		documents: documents.length
+	};
+});
 
 //#endregion
-export { selectPnpmDocument, selectSoleDocument };
+export { selectPnpmDocument, selectPnpmEnvDocument, selectSoleDocument };

package/internal/pnpm.js

@@ -1,6 +1,6 @@
 import { LockfileImporter } from "../LockfileImporter.js";
 import { ResolvedPackage } from "../ResolvedPackage.js";
-import { extractWorkspaceDeps, framingFailure, importerDependencies, peerDeclarations, requireLockfileVersion, splitPeerSuffix, toIntegrityHash, validationFailure } from "./shared.js";
+import { extractWorkspaceDeps, framingFailure, gatePnpmVersion, importerDependencies, peerDeclarations, splitPeerSuffix, toIntegrityHash, validationFailure } from "./shared.js";
 import { PnpmExtension } from "../PnpmExtension.js";
 import { selectPnpmDocument } from "./documents.js";
 import { Effect, Schema } from "effect";
@@ -17,18 +17,6 @@ const PnpmImporter = Schema.Struct({
 	optionalDependencies: PnpmImporterDeps,
 	publishDirectory: Schema.optionalKey(Schema.String)
 });
-/**
-* 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({
@@ -71,8 +59,7 @@ 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);
+	yield* gatePnpmVersion(document);
 	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);

package/internal/pnpmEnv.js

@@ -0,0 +1,135 @@
+import { ConfigDependencyLock } from "../ConfigDependencyLock.js";
+import { gatePnpmVersion, validationFailure } from "./shared.js";
+import { selectPnpmEnvDocument } from "./documents.js";
+import { PackageManagerLock } from "../PackageManagerLock.js";
+import { Effect, Schema } from "effect";
+import { IntegrityHash } from "@effected/npm";
+
+//#region src/internal/pnpmEnv.ts
+const PnpmEnvImporterDeps = Schema.optionalKey(Schema.Record(Schema.String, Schema.Struct({
+	specifier: Schema.String,
+	version: Schema.String
+})));
+const PnpmEnvRaw = Schema.Struct({
+	importers: Schema.optionalKey(Schema.Record(Schema.String, Schema.Struct({
+		packageManagerDependencies: PnpmEnvImporterDeps,
+		configDependencies: PnpmEnvImporterDeps
+	}))),
+	packages: Schema.optionalKey(Schema.Record(Schema.String, Schema.Struct({ resolution: Schema.optionalKey(Schema.Struct({ integrity: Schema.optionalKey(Schema.String) })) }))),
+	snapshots: Schema.optionalKey(Schema.Record(Schema.String, Schema.Struct({ optionalDependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)) })))
+});
+/** The package-manager package this reader resolves. */
+const PNPM = "pnpm";
+/** The importer pnpm records `packageManagerDependencies` under. */
+const ROOT_IMPORTER = ".";
+/**
+* Own-property read of a decoded record. The records come from YAML, so a key
+* such as `constructor` or `__proto__` must never be answered by
+* `Object.prototype`.
+*/
+const own = (record, key) => record !== void 0 && Object.hasOwn(record, key) ? record[key] : void 0;
+/**
+* A located, well-formed preamble that does not hold what it promises: the
+* importer names a package the `packages:` section cannot account for. A
+* shape failure of a located document, so it rides the validation channel.
+*/
+const unaccounted = (message) => validationFailure(/* @__PURE__ */ new Error(`pnpm-lock.yaml env preamble: ${message}`));
+/**
+* The SRI integrity of `packages["<key>"]`, failing when the entry, its
+* integrity, or the SRI form of that integrity is missing. Never `undefined`:
+* the caller only asks for keys the lockfile's own graph names.
+*/
+const integrityOf = (raw, key) => {
+	const integrity = own(raw.packages, key)?.resolution?.integrity;
+	if (integrity === void 0) return Effect.fail(unaccounted(`packages[${JSON.stringify(key)}] records no resolution.integrity`));
+	if (!IntegrityHash.isSri(integrity)) return Effect.fail(unaccounted(`packages[${JSON.stringify(key)}].resolution.integrity is not an SRI integrity string`));
+	return Effect.succeed(integrity);
+};
+/**
+* The SRI integrity of the `<name>@<version>` a preamble entry records,
+* failing first when the version is empty: an empty version names no
+* `packages` entry, and saying so beats reporting the malformed key.
+* `subject` is the entry as the empty-version message names it.
+*/
+const recordedIntegrity = (raw, subject, name, version) => version === "" ? Effect.fail(unaccounted(`${subject} is recorded with an empty version`)) : integrityOf(raw, `${name}@${version}`);
+/**
+* Locate and decode the env preamble of a `pnpm-lock.yaml`: `undefined` when
+* the stream carries none, typed when it is malformed or below the supported
+* lockfile version. The one decode every preamble reader shares, so they
+* cannot disagree about which document is the preamble or what shape it has.
+*/
+const decodePreamble = (content) => Effect.gen(function* () {
+	const selected = yield* selectPnpmEnvDocument(content);
+	if (selected === void 0) return void 0;
+	yield* gatePnpmVersion(selected.document);
+	return yield* Schema.decodeUnknownEffect(PnpmEnvRaw)(selected.document).pipe(Effect.mapError(validationFailure));
+});
+/**
+* Read the package manager pinned by a `pnpm-lock.yaml`'s env preamble.
+*
+* @remarks
+* `undefined` means the lockfile records no package manager: no preamble, or
+* a preamble whose root importer declares no `pnpm` package-manager
+* dependency. Everything past that point is a claim the lockfile made, so a
+* claim it cannot back — a missing `pnpm@<version>` entry, a missing snapshot,
+* a missing or non-SRI integrity for pnpm or any native it lists — fails typed
+* rather than degrading to "nothing recorded".
+*
+* Native packages come from the lockfile's own graph — the optional
+* dependencies of the `pnpm@<version>` snapshot — not from a name pattern.
+*
+* @internal
+*/
+const readPnpmPackageManager = (content) => Effect.gen(function* () {
+	const raw = yield* decodePreamble(content);
+	if (raw === void 0) return void 0;
+	const declared = own(own(raw.importers, ROOT_IMPORTER)?.packageManagerDependencies, PNPM);
+	if (declared === void 0) return void 0;
+	const integrity = yield* recordedIntegrity(raw, PNPM, PNPM, declared.version);
+	const key = `${PNPM}@${declared.version}`;
+	const snapshot = own(raw.snapshots, key);
+	if (snapshot === void 0) return yield* Effect.fail(unaccounted(`snapshots[${JSON.stringify(key)}] is missing`));
+	const natives = [];
+	for (const [name, version] of Object.entries(snapshot.optionalDependencies ?? {})) natives.push([name, yield* integrityOf(raw, `${name}@${version}`)]);
+	return PackageManagerLock.make({
+		name: PNPM,
+		specifier: declared.specifier,
+		version: declared.version,
+		integrity,
+		nativeIntegrity: Object.fromEntries(natives)
+	});
+});
+/**
+* Read the config dependencies recorded by a `pnpm-lock.yaml`'s env preamble,
+* keyed by name, each with the integrity pnpm recorded for it.
+*
+* @remarks
+* An empty map means the lockfile records none: no preamble, or a preamble
+* whose root importer declares no `configDependencies`. As with
+* {@link readPnpmPackageManager}, every entry the importer names is a claim,
+* so an entry whose `<name>@<version>` has no `packages` entry, no integrity,
+* a non-SRI integrity, or an empty version fails typed rather than being
+* dropped. The map is built from own keys only, so a hostile name such as
+* `__proto__` is an ordinary entry.
+*
+* @internal
+*/
+const readPnpmConfigDependencies = (content) => Effect.gen(function* () {
+	const raw = yield* decodePreamble(content);
+	const declared = own(raw?.importers, ROOT_IMPORTER)?.configDependencies;
+	const locks = /* @__PURE__ */ new Map();
+	if (raw === void 0 || declared === void 0) return locks;
+	for (const [name, entry] of Object.entries(declared)) {
+		const integrity = yield* recordedIntegrity(raw, `config dependency ${JSON.stringify(name)}`, name, entry.version);
+		locks.set(name, ConfigDependencyLock.make({
+			name,
+			specifier: entry.specifier,
+			version: entry.version,
+			integrity
+		}));
+	}
+	return locks;
+});
+
+//#endregion
+export { readPnpmConfigDependencies, readPnpmPackageManager };

package/internal/shared.js

@@ -187,6 +187,26 @@ const requireLockfileVersion = (format, raw) => {
 	};
 	return Effect.fail(validationFailure(cause));
 };
+/**
+* The pnpm 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 in the lockfile shape 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]) });
+/**
+* Gate a located pnpm document (lockfile or env preamble) on its format
+* version: decode {@link PnpmVersionProbe}, then {@link requireLockfileVersion}.
+* Call it BEFORE the shape decode, for the reason the probe documents.
+*
+* @internal
+*/
+const gatePnpmVersion = (document) => Schema.decodeUnknownEffect(PnpmVersionProbe)(document).pipe(Effect.mapError(validationFailure), Effect.flatMap((probe) => requireLockfileVersion("pnpm", probe.lockfileVersion)));
 /** @internal */
 const syntaxFailure = (cause) => ({
 	stage: "syntax",
@@ -235,4 +255,4 @@ const extractWorkspaceDeps = (workspaces, workspaceNames) => {
 };
 
 //#endregion
-export { DEP_TYPES, MINIMUM_LOCKFILE_VERSION, extractWorkspaceDeps, framingFailure, importerDependencies, isWorkspaceSpecifier, peerDeclarations, requireLockfileVersion, splitPeerSuffix, syntaxFailure, toIntegrityHash, validationFailure };
+export { DEP_TYPES, MINIMUM_LOCKFILE_VERSION, extractWorkspaceDeps, framingFailure, gatePnpmVersion, importerDependencies, isWorkspaceSpecifier, peerDeclarations, requireLockfileVersion, splitPeerSuffix, syntaxFailure, toIntegrityHash, validationFailure };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/lockfiles",
-	"version": "0.10.0",
+	"version": "0.12.0-next-20260927062352",
 	"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": [
@@ -40,11 +40,11 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/jsonc": "^0.12.0",
-		"@effected/npm": "^0.15.0",
-		"@effected/semver": "^0.8.0",
-		"@effected/yaml": "^0.16.0",
-		"effect": "4.0.0-rc.116"
+		"@effected/jsonc": "^0.13.0",
+		"@effected/npm": "^0.17.0-next-20260927062352",
+		"@effected/semver": "^0.9.0",
+		"@effected/yaml": "^0.17.0",
+		"effect": "4.0.0-rc.117"
 	},
 	"engines": {
 		"node": ">=24.11.0"