@effect-vfs/core 0.4.0 → 0.6.0

package/dist/Metadata.js

@@ -0,0 +1,125 @@
+/**
+ * Metadata schemas for virtual filesystem objects: timestamps, permission modes,
+ * the metadata record every observation returns, and the owner and time updates
+ * that mutations accept.
+ *
+ * @since 0.6.0
+ */
+import * as Schema from "effect/Schema";
+const MAX_TIMESTAMP = 10n ** 128n - 1n;
+/**
+ * Schema for a timestamp in nanoseconds since the Unix epoch. Values stay
+ * within 128 decimal digits so they round-trip through snapshot encodings.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const Timestamp = Schema.BigInt.check(Schema.isGreaterThanOrEqualToBigInt(-MAX_TIMESTAMP), Schema.isLessThanOrEqualToBigInt(MAX_TIMESTAMP));
+/**
+ * Schema for a POSIX permission mode: the permission, setuid, setgid and sticky
+ * bits without any file-type bits.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const Mode = Schema.Natural.check(Schema.isLessThanOrEqualTo(0o7777));
+/**
+ * Schema for the metadata of a filesystem object.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const Metadata = Schema.Struct({
+    kind: Schema.Literals(["directory", "file", "symlink"]),
+    ino: Schema.BigInt,
+    nlink: Schema.Natural,
+    size: Schema.BigInt,
+    uid: Schema.Natural,
+    gid: Schema.Natural,
+    mode: Mode,
+    atimeNs: Timestamp,
+    mtimeNs: Timestamp,
+    ctimeNs: Timestamp,
+    birthtimeNs: Timestamp,
+    /** The object's revision, advanced by every committed change to it. */
+    revision: Schema.BigInt
+});
+/**
+ * Mask of the file-type bits in a POSIX `st_mode`.
+ *
+ * @category constants
+ * @since 0.6.0
+ */
+export const S_IFMT = 0o170000;
+/**
+ * File-type bits of a regular file in a POSIX `st_mode`.
+ *
+ * @category constants
+ * @since 0.6.0
+ */
+export const S_IFREG = 0o100000;
+/**
+ * File-type bits of a directory in a POSIX `st_mode`.
+ *
+ * @category constants
+ * @since 0.6.0
+ */
+export const S_IFDIR = 0o040000;
+/**
+ * File-type bits of a symbolic link in a POSIX `st_mode`.
+ *
+ * @category constants
+ * @since 0.6.0
+ */
+export const S_IFLNK = 0o120000;
+const FILE_TYPE_BITS = { directory: S_IFDIR, file: S_IFREG, symlink: S_IFLNK };
+/**
+ * The POSIX `st_mode` of an object: the file-type bits of its `kind` joined
+ * with its permission `mode`. `mode` itself never carries type bits, so the
+ * kind has a single source.
+ *
+ * A volume has no device nodes, so a `stat` built from metadata reports `dev`
+ * and `rdev` as 0, and `(dev, ino)` identifies an object only within one volume.
+ *
+ * @example
+ * ```ts
+ * import { S_IFDIR, S_IFMT, typedMode } from "@effect-vfs/core/Metadata"
+ *
+ * const stMode = typedMode({ kind: "directory", mode: 0o755 })
+ *
+ * console.log(stMode.toString(8)) // "40755"
+ * console.log((stMode & S_IFMT) === S_IFDIR) // true
+ * ```
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export const typedMode = (metadata) => FILE_TYPE_BITS[metadata.kind] | metadata.mode;
+/**
+ * Schema for an ownership update; an omitted field keeps its current value.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const OwnerUpdate = Schema.Struct({
+    uid: Schema.optionalKey(Schema.Natural),
+    gid: Schema.optionalKey(Schema.Natural)
+});
+/**
+ * Schema for one timestamp update: the current time, no change, or an explicit value.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const TimeUpdate = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("now") }),
+    Schema.Struct({ kind: Schema.Literal("omit") }),
+    Schema.Struct({ kind: Schema.Literal("value"), nanoseconds: Timestamp })
+]);
+/**
+ * Schema for the access and modification time updates a mutation applies together.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const Times = Schema.Struct({ access: TimeUpdate, modification: TimeUpdate });

package/dist/Snapshot.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Opaque virtual filesystem snapshots and their decoding limits.
+ *
+ * A snapshot is the immutable value of a volume at one committed state, so
+ * capturing one copies nothing. It holds the reachable namespace and metadata,
+ * but excludes callers, open handles, watch subscriptions, and unlinked
+ * content. Use the encoding, decoding, and restoration functions in
+ * `VirtualFileSystem`.
+ *
+ * @since 0.1.0
+ */
 import * as Schema from "effect/Schema";
 /**
  * Type identifier for opaque filesystem snapshots.
@@ -22,68 +33,30 @@ export type SnapshotTypeId = typeof SnapshotTypeId;
 export interface Snapshot {
     readonly [SnapshotTypeId]: SnapshotTypeId;
 }
-declare const ImageError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "ImageError";
-} & Readonly<A>;
 /**
- * Describes a snapshot encoding, decoding, structure, or resource-limit failure.
- *
- * @example
- * ```ts
- * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
- * import { ByteSize, Effect } from "effect"
- *
- * // Decoding is a trust boundary. `code` says what went wrong and `field` says
- * // which input or limit it was, so a caller can decline just the bad payload.
- * const program = Effect.gen(function*() {
- *   const volume = yield* Vfs.make()
- *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
- *
- *   return yield* Vfs.decodeSnapshot(bytes, {
- *     maxEncodedBytes: ByteSize.bytes(16),
- *     maxRecords: 10_000,
- *     maxEntries: 10_000,
- *     maxDecodedBytes: ByteSize.megabytes(16)
- *   }).pipe(
- *     Effect.as("accepted"),
- *     Effect.catchTag("ImageError", (error) =>
- *       error.code === "LimitExceeded"
- *         ? Effect.succeed(`declined at ${error.field}`)
- *         : Effect.fail(error))
- *   )
- * })
+ * Schema for the mandatory resource limits applied while decoding a snapshot.
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
- * // declined at encodedBytes
- * ```
+ * **Details**
  *
- * @category errors
- * @since 0.1.0
- */
-export declare class ImageError extends ImageError_base<{
-    /** Machine-readable encoding, version, structure, or limit failure. */
-    readonly code: "InvalidEncoding" | "UnsupportedVersion" | "InvalidStructure" | "LimitExceeded";
-    /** Input area or configured limit associated with the failure, when available. */
-    readonly field?: string;
-}> {
-}
-/**
- * Schema for the mandatory resource limits applied while decoding a snapshot.
+ * A snapshot is encoded one line per node, and a decoder checks each line as
+ * it ends, so input that breaks a limit is refused before the decoder holds
+ * more than one line of it. `maxLineBytes` bounds that line; the other limits
+ * bound what the accepted lines add up to.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { ByteSize, Effect } from "effect"
  *
- * // All four are required: each bounds a different resource. `maxEncodedBytes`
+ * // The four counts are required: each bounds a different resource. `maxEncodedBytes`
  * // caps the wire payload before parsing; `maxDecodedBytes` caps memory after it.
+ * // `maxLineBytes` is optional and caps one line, which holds at most one file.
  * const limits: Vfs.DecodeLimits = {
  *   maxEncodedBytes: ByteSize.megabytes(4),
  *   maxRecords: 10_000,
  *   maxEntries: 10_000,
- *   maxDecodedBytes: ByteSize.megabytes(16)
+ *   maxDecodedBytes: ByteSize.megabytes(16),
+ *   maxLineBytes: ByteSize.megabytes(4)
  * }
  *
  * const program = Effect.gen(function*() {
@@ -95,7 +68,7 @@ export declare class ImageError extends ImageError_base<{
  *   return "accepted"
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // accepted
  * ```
  *
@@ -105,12 +78,18 @@ export declare class ImageError extends ImageError_base<{
 export declare const DecodeLimits: Schema.Struct<{
     /** Maximum accepted encoded input length in bytes. */
     readonly maxEncodedBytes: Schema.ByteSize;
-    /** Maximum number of stored metadata and content records. */
+    /** Maximum number of stored objects, one node each, the root included. */
     readonly maxRecords: Schema.Natural;
-    /** Maximum number of namespace entries. */
+    /** Maximum number of namespace entries, counting every name of a hard-linked file. */
     readonly maxEntries: Schema.Natural;
-    /** Maximum combined decoded byte content. */
+    /** Maximum combined decoded bytes of names, file contents and symbolic-link targets. */
     readonly maxDecodedBytes: Schema.ByteSize;
+    /**
+     * Maximum bytes of one line of the encoding, without its newline: the most a decoder holds before it can check
+     * what the line says. A file's line holds its whole content, so this also bounds the largest file. Defaults to
+     * `maxEncodedBytes`.
+     */
+    readonly maxLineBytes: Schema.optionalKey<Schema.ByteSize>;
 }>;
 /**
  * Resource limits applied while decoding a snapshot.
@@ -119,5 +98,4 @@ export declare const DecodeLimits: Schema.Struct<{
  * @since 0.1.0
  */
 export type DecodeLimits = typeof DecodeLimits.Type;
-export {};
 //# sourceMappingURL=Snapshot.d.ts.map

package/dist/Snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Snapshot.d.ts","sourceRoot":"","sources":["../src/Snapshot.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAG,2BAAoC,CAAA;AAElE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;CAC1C;;;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,oBAAoB,GAAG,kBAAkB,GAAG,eAAe,CAAA;IAC9F,kFAAkF;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB,CAAC;CAAG;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,YAAY;IACvB,sDAAsD;;IAEtD,6DAA6D;;IAE7D,2CAA2C;;IAE3C,6CAA6C;;EAE7C,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA"}
+{"version":3,"file":"Snapshot.d.ts","sourceRoot":"","sources":["../src/Snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAG,2BAAoC,CAAA;AAElE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,YAAY;IACvB,sDAAsD;;IAEtD,0EAA0E;;IAE1E,sFAAsF;;IAEtF,wFAAwF;;IAExF;;;;OAIG;;EAEH,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA"}

package/dist/Snapshot.js

@@ -1,13 +1,14 @@
 /**
  * Opaque virtual filesystem snapshots and their decoding limits.
  *
- * Snapshots contain a volume's reachable namespace and metadata, but exclude
- * callers, open handles, watch subscriptions, and unlinked content. Use the
- * encoding, decoding, and restoration functions in `VirtualFileSystem`.
+ * A snapshot is the immutable value of a volume at one committed state, so
+ * capturing one copies nothing. It holds the reachable namespace and metadata,
+ * but excludes callers, open handles, watch subscriptions, and unlinked
+ * content. Use the encoding, decoding, and restoration functions in
+ * `VirtualFileSystem`.
  *
  * @since 0.1.0
  */
-import * as Data from "effect/Data";
 import * as Schema from "effect/Schema";
 /**
  * Type identifier for opaque filesystem snapshots.
@@ -17,59 +18,29 @@ import * as Schema from "effect/Schema";
  */
 export const SnapshotTypeId = "@effect-vfs/core/Snapshot";
 /**
- * Describes a snapshot encoding, decoding, structure, or resource-limit failure.
- *
- * @example
- * ```ts
- * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
- * import { ByteSize, Effect } from "effect"
- *
- * // Decoding is a trust boundary. `code` says what went wrong and `field` says
- * // which input or limit it was, so a caller can decline just the bad payload.
- * const program = Effect.gen(function*() {
- *   const volume = yield* Vfs.make()
- *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
- *
- *   return yield* Vfs.decodeSnapshot(bytes, {
- *     maxEncodedBytes: ByteSize.bytes(16),
- *     maxRecords: 10_000,
- *     maxEntries: 10_000,
- *     maxDecodedBytes: ByteSize.megabytes(16)
- *   }).pipe(
- *     Effect.as("accepted"),
- *     Effect.catchTag("ImageError", (error) =>
- *       error.code === "LimitExceeded"
- *         ? Effect.succeed(`declined at ${error.field}`)
- *         : Effect.fail(error))
- *   )
- * })
+ * Schema for the mandatory resource limits applied while decoding a snapshot.
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
- * // declined at encodedBytes
- * ```
+ * **Details**
  *
- * @category errors
- * @since 0.1.0
- */
-export class ImageError extends Data.TaggedError("ImageError") {
-}
-/**
- * Schema for the mandatory resource limits applied while decoding a snapshot.
+ * A snapshot is encoded one line per node, and a decoder checks each line as
+ * it ends, so input that breaks a limit is refused before the decoder holds
+ * more than one line of it. `maxLineBytes` bounds that line; the other limits
+ * bound what the accepted lines add up to.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { ByteSize, Effect } from "effect"
  *
- * // All four are required: each bounds a different resource. `maxEncodedBytes`
+ * // The four counts are required: each bounds a different resource. `maxEncodedBytes`
  * // caps the wire payload before parsing; `maxDecodedBytes` caps memory after it.
+ * // `maxLineBytes` is optional and caps one line, which holds at most one file.
  * const limits: Vfs.DecodeLimits = {
  *   maxEncodedBytes: ByteSize.megabytes(4),
  *   maxRecords: 10_000,
  *   maxEntries: 10_000,
- *   maxDecodedBytes: ByteSize.megabytes(16)
+ *   maxDecodedBytes: ByteSize.megabytes(16),
+ *   maxLineBytes: ByteSize.megabytes(4)
  * }
  *
  * const program = Effect.gen(function*() {
@@ -81,7 +52,7 @@ export class ImageError extends Data.TaggedError("ImageError") {
  *   return "accepted"
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // accepted
  * ```
  *
@@ -91,10 +62,16 @@ export class ImageError extends Data.TaggedError("ImageError") {
 export const DecodeLimits = Schema.Struct({
     /** Maximum accepted encoded input length in bytes. */
     maxEncodedBytes: Schema.ByteSize,
-    /** Maximum number of stored metadata and content records. */
+    /** Maximum number of stored objects, one node each, the root included. */
     maxRecords: Schema.Natural,
-    /** Maximum number of namespace entries. */
+    /** Maximum number of namespace entries, counting every name of a hard-linked file. */
     maxEntries: Schema.Natural,
-    /** Maximum combined decoded byte content. */
-    maxDecodedBytes: Schema.ByteSize
+    /** Maximum combined decoded bytes of names, file contents and symbolic-link targets. */
+    maxDecodedBytes: Schema.ByteSize,
+    /**
+     * Maximum bytes of one line of the encoding, without its newline: the most a decoder holds before it can check
+     * what the line says. A file's line holds its whole content, so this also bounds the largest file. Defaults to
+     * `maxEncodedBytes`.
+     */
+    maxLineBytes: Schema.optionalKey(Schema.ByteSize)
 });

package/dist/SnapshotDelta.d.ts

@@ -1,6 +1,10 @@
 /**
  * Opaque portable snapshot deltas and their public inspection models.
  *
+ * A delta names its base and target snapshots by their semantic identities and
+ * holds one change per path that differs, each carrying only the node it
+ * leaves behind, so its size follows what changed rather than the tree.
+ *
  * @since 0.1.0
  */
 import * as ByteSize from "effect/ByteSize";
@@ -168,55 +172,26 @@ export declare const SnapshotChangesOptions: Schema.Struct<{
  * @since 0.1.0
  */
 export type SnapshotChangesOptions = typeof SnapshotChangesOptions.Type;
-declare const SnapshotDeltaError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "SnapshotDeltaError";
-} & Readonly<A>;
-/**
- * A valid snapshot delta was inspected or applied against a valid but semantically different base.
- *
- * @example
- * ```ts
- * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
- * import { Effect } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const volume = yield* Vfs.make()
- *   const caller = yield* volume.caller()
- *   const base = yield* volume.snapshot
- *
- *   yield* caller.mkdir("/work")
- *
- *   // Omitting limits uses `default`; `constrained` suits memory-sensitive hosts.
- *   const tight = { ...Vfs.SnapshotDeltaLimits.constrained, maxOutputRecords: 0 }
- *
- *   return yield* Vfs.diffSnapshots(base, yield* volume.snapshot, tight).pipe(
- *     Effect.as("diffed"),
- *     Effect.catchTag("ImageError", (error) => Effect.succeed(`${error.code} at ${error.field}`))
- *   )
- * }).pipe(Effect.provide(NodeCrypto.layer))
- *
- * Effect.runPromise(program).then(console.log)
- * // LimitExceeded at outputRecords
- * ```
- *
- * @category errors
- * @since 0.1.0
- */
-export declare class SnapshotDeltaError extends SnapshotDeltaError_base<{
-    readonly code: "BaseMismatch";
-}> {
-}
 declare const SnapshotDeltaLimitsSchema: Schema.Struct<{
+    /** Maximum encoded delta length in bytes. */
     readonly maxEncodedBytes: Schema.ByteSize;
+    /** Maximum bytes hashed for one snapshot's identity. */
     readonly maxIdentityBytes: Schema.ByteSize;
+    /** Maximum number of changes a delta holds. */
     readonly maxDeltaRecords: Schema.Natural;
+    /** Maximum decoded bytes of a delta's digests, paths and payloads. */
     readonly maxDecodedDeltaBytes: Schema.ByteSize;
+    /** Maximum number of nodes in the base snapshot. */
     readonly maxBaseRecords: Schema.Natural;
+    /** Maximum number of nodes in the target snapshot. */
     readonly maxTargetRecords: Schema.Natural;
+    /** Maximum number of names in either snapshot, and of names a delta writes. */
     readonly maxEntries: Schema.Natural;
+    /** Maximum number of nodes an applied delta produces. */
     readonly maxOutputRecords: Schema.Natural;
+    /** Maximum payload bytes of the target, and of the payloads a delta carries. */
     readonly maxOutputBytes: Schema.ByteSize;
+    /** Maximum number of target nodes carried over from the base rather than written by the delta. */
     readonly maxInheritedRecords: Schema.Natural;
 }>;
 /**
@@ -263,15 +238,25 @@ export declare const makeSnapshotDeltaLimits: (limits: SnapshotDeltaLimits) => S
  * @since 0.1.0
  */
 export declare const SnapshotDeltaLimits: Schema.Struct<{
+    /** Maximum encoded delta length in bytes. */
     readonly maxEncodedBytes: Schema.ByteSize;
+    /** Maximum bytes hashed for one snapshot's identity. */
     readonly maxIdentityBytes: Schema.ByteSize;
+    /** Maximum number of changes a delta holds. */
     readonly maxDeltaRecords: Schema.Natural;
+    /** Maximum decoded bytes of a delta's digests, paths and payloads. */
     readonly maxDecodedDeltaBytes: Schema.ByteSize;
+    /** Maximum number of nodes in the base snapshot. */
     readonly maxBaseRecords: Schema.Natural;
+    /** Maximum number of nodes in the target snapshot. */
     readonly maxTargetRecords: Schema.Natural;
+    /** Maximum number of names in either snapshot, and of names a delta writes. */
     readonly maxEntries: Schema.Natural;
+    /** Maximum number of nodes an applied delta produces. */
     readonly maxOutputRecords: Schema.Natural;
+    /** Maximum payload bytes of the target, and of the payloads a delta carries. */
     readonly maxOutputBytes: Schema.ByteSize;
+    /** Maximum number of target nodes carried over from the base rather than written by the delta. */
     readonly maxInheritedRecords: Schema.Natural;
 }> & {
     constrained: {

package/dist/SnapshotDelta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SnapshotDelta.d.ts","sourceRoot":"","sources":["../src/SnapshotDelta.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAE3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGxC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,gCAA+D,CAAA;AAEjG;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAA;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;CACpD;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,8CAA0D,CAAA;AAEpF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,4DAAoD,CAAA;AAEjF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,4IAY7B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;IASzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,sBAAsB;IACjC,6FAA6F;;EAE7F,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;;;;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC7E,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAC9B,CAAC;CAAG;AAEL,QAAA,MAAM,yBAAyB;;;;;;;;;;;EAW7B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAEvE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,WAAY,mBAAmB,KAAG,mBACxC,CAAA;AA4B9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAG9B,CAAA"}
+{"version":3,"file":"SnapshotDelta.d.ts","sourceRoot":"","sources":["../src/SnapshotDelta.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGxC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,gCAA+D,CAAA;AAEjG;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAA;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;CACpD;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,8CAA0D,CAAA;AAEpF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,4DAAoD,CAAA;AAEjF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,4IAY7B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;IASzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,sBAAsB;IACjC,6FAA6F;;EAE7F,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;AAEvE,QAAA,MAAM,yBAAyB;IAC7B,6CAA6C;;IAE7C,wDAAwD;;IAExD,+CAA+C;;IAE/C,sEAAsE;;IAEtE,oDAAoD;;IAEpD,sDAAsD;;IAEtD,+EAA+E;;IAE/E,yDAAyD;;IAEzD,gFAAgF;;IAEhF,kGAAkG;;EAElG,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAEvE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,WAAY,mBAAmB,KAAG,mBACxC,CAAA;AA4B9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,mBAAmB;IA9F9B,6CAA6C;;IAE7C,wDAAwD;;IAExD,+CAA+C;;IAE/C,sEAAsE;;IAEtE,oDAAoD;;IAEpD,sDAAsD;;IAEtD,+EAA+E;;IAE/E,yDAAyD;;IAEzD,gFAAgF;;IAEhF,kGAAkG;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+ElG,CAAA"}

package/dist/SnapshotDelta.js

@@ -1,10 +1,13 @@
 /**
  * Opaque portable snapshot deltas and their public inspection models.
  *
+ * A delta names its base and target snapshots by their semantic identities and
+ * holds one change per path that differs, each carrying only the node it
+ * leaves behind, so its size follows what changed rather than the tree.
+ *
  * @since 0.1.0
  */
 import * as ByteSize from "effect/ByteSize";
-import * as Data from "effect/Data";
 import * as Schema from "effect/Schema";
 import { BytePath } from "./BytePath.js";
 import * as Internal from "./internal/snapshotDeltaModel.js";
@@ -137,50 +140,26 @@ export const SnapshotChangesOptions = Schema.Struct({
     /** Include access, modification, change, and birth-time differences. Defaults to `false`. */
     includeTimestamps: Schema.optionalKey(Schema.Boolean)
 });
-/**
- * A valid snapshot delta was inspected or applied against a valid but semantically different base.
- *
- * @example
- * ```ts
- * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
- * import { Effect } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const volume = yield* Vfs.make()
- *   const caller = yield* volume.caller()
- *   const base = yield* volume.snapshot
- *
- *   yield* caller.mkdir("/work")
- *
- *   // Omitting limits uses `default`; `constrained` suits memory-sensitive hosts.
- *   const tight = { ...Vfs.SnapshotDeltaLimits.constrained, maxOutputRecords: 0 }
- *
- *   return yield* Vfs.diffSnapshots(base, yield* volume.snapshot, tight).pipe(
- *     Effect.as("diffed"),
- *     Effect.catchTag("ImageError", (error) => Effect.succeed(`${error.code} at ${error.field}`))
- *   )
- * }).pipe(Effect.provide(NodeCrypto.layer))
- *
- * Effect.runPromise(program).then(console.log)
- * // LimitExceeded at outputRecords
- * ```
- *
- * @category errors
- * @since 0.1.0
- */
-export class SnapshotDeltaError extends Data.TaggedError("SnapshotDeltaError") {
-}
 const SnapshotDeltaLimitsSchema = Schema.Struct({
+    /** Maximum encoded delta length in bytes. */
     maxEncodedBytes: Schema.ByteSize,
+    /** Maximum bytes hashed for one snapshot's identity. */
     maxIdentityBytes: Schema.ByteSize,
+    /** Maximum number of changes a delta holds. */
     maxDeltaRecords: Schema.Natural,
+    /** Maximum decoded bytes of a delta's digests, paths and payloads. */
     maxDecodedDeltaBytes: Schema.ByteSize,
+    /** Maximum number of nodes in the base snapshot. */
     maxBaseRecords: Schema.Natural,
+    /** Maximum number of nodes in the target snapshot. */
     maxTargetRecords: Schema.Natural,
+    /** Maximum number of names in either snapshot, and of names a delta writes. */
     maxEntries: Schema.Natural,
+    /** Maximum number of nodes an applied delta produces. */
     maxOutputRecords: Schema.Natural,
+    /** Maximum payload bytes of the target, and of the payloads a delta carries. */
     maxOutputBytes: Schema.ByteSize,
+    /** Maximum number of target nodes carried over from the base rather than written by the delta. */
     maxInheritedRecords: Schema.Natural
 });
 /**