@effect-vfs/core 0.2.0 → 0.3.1

package/dist/internal/snapshotDeltaModel.d.ts

@@ -0,0 +1,10 @@
+import type { SnapshotDelta } from "../SnapshotDelta.js";
+/** @internal */
+export declare const SnapshotDeltaTypeId: "@effect-vfs/core/SnapshotDelta";
+/** @internal */
+export declare const make: (value: WeakKey) => SnapshotDelta;
+/** @internal */
+export declare const value: (delta: SnapshotDelta) => WeakKey | undefined;
+/** @internal */
+export declare const isSnapshotDelta: (input: unknown) => input is SnapshotDelta;
+//# sourceMappingURL=snapshotDeltaModel.d.ts.map

package/dist/internal/snapshotDeltaModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotDeltaModel.d.ts","sourceRoot":"","sources":["../../src/internal/snapshotDeltaModel.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,EAAG,gCAAyC,CAAA;AAI5E,gBAAgB;AAChB,eAAO,MAAM,IAAI,UAAW,OAAO,KAAG,aAKrC,CAAA;AAED,gBAAgB;AAChB,eAAO,MAAM,KAAK,UAAW,aAAa,KAAG,OAAO,GAAG,SAAsC,CAAA;AAE7F,gBAAgB;AAChB,eAAO,MAAM,eAAe,UAAW,OAAO,KAAG,KAAK,IAAI,aACF,CAAA"}

package/dist/internal/snapshotDeltaModel.js

@@ -0,0 +1,15 @@
+// Opaque snapshot-delta representation and authenticity checks.
+import * as Predicate from "effect/Predicate";
+/** @internal */
+export const SnapshotDeltaTypeId = "@effect-vfs/core/SnapshotDelta";
+const snapshotDeltas = new WeakMap();
+/** @internal */
+export const make = (value) => {
+    const delta = Object.freeze({ [SnapshotDeltaTypeId]: SnapshotDeltaTypeId });
+    snapshotDeltas.set(delta, value);
+    return delta;
+};
+/** @internal */
+export const value = (delta) => snapshotDeltas.get(delta);
+/** @internal */
+export const isSnapshotDelta = (input) => Predicate.isObject(input) && snapshotDeltas.has(input);

package/dist/internal/virtualFileSystem/errors.d.ts

@@ -0,0 +1,31 @@
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import type { PathInput } from "../../VirtualFileSystem.js";
+/** @internal */
+export declare const FsCode: Schema.Literals<readonly ["NotFound", "AlreadyExists", "NotEmpty", "NotDirectory", "AccessDenied", "InvalidHandle", "ForeignHandle", "InvalidReference", "ForeignReference", "StaleReference", "ClosedCaller", "InvalidArgument", "InvalidPathEncoding", "PathTooLong", "NoSpace", "IsDirectory", "FileTooLarge", "NoData", "SymlinkLoop", "UnrepresentableName"]>;
+/** @internal */
+export type FsCode = typeof FsCode.Type;
+declare const FsError_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: "FsError";
+} & Readonly<A>;
+/** @internal */
+export declare class FsError extends FsError_base<{
+    readonly code: FsCode;
+    readonly operation: string;
+    readonly path?: PathInput;
+}> {
+    get message(): string;
+}
+declare const ConfigurationError_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: "ConfigurationError";
+} & Readonly<A>;
+/** @internal */
+export declare class ConfigurationError extends ConfigurationError_base<{
+    readonly field: string;
+}> {
+    get message(): string;
+}
+/** @internal */
+export declare const decodeConfiguration: <A>(schema: Schema.Codec<A>, value: typeof Schema.Unknown.Type) => Result.Result<A, ConfigurationError>;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/internal/virtualFileSystem/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/internal/virtualFileSystem/errors.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAE3D,gBAAgB;AAChB,eAAO,MAAM,MAAM,oWAqBjB,CAAA;AAEF,gBAAgB;AAChB,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;;;;AAEvC,gBAAgB;AAChB,qBAAa,OAAQ,SAAQ,aAA4B;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAC1B,CAAC;IAEA,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;;;;AAED,gBAAgB;AAChB,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB,CAAC;IACA,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;AAWD,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,GAAI,CAAC,UAAU,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,yCAG9F,CAAA"}

package/dist/internal/virtualFileSystem/errors.js

@@ -0,0 +1,51 @@
+// Virtual filesystem failure schemas and identities shared by the runtime implementation.
+import * as Data from "effect/Data";
+import * as Predicate from "effect/Predicate";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+/** @internal */
+export const FsCode = Schema.Literals([
+    "NotFound",
+    "AlreadyExists",
+    "NotEmpty",
+    "NotDirectory",
+    "AccessDenied",
+    "InvalidHandle",
+    "ForeignHandle",
+    "InvalidReference",
+    "ForeignReference",
+    "StaleReference",
+    "ClosedCaller",
+    "InvalidArgument",
+    "InvalidPathEncoding",
+    "PathTooLong",
+    "NoSpace",
+    "IsDirectory",
+    "FileTooLarge",
+    "NoData",
+    "SymlinkLoop",
+    "UnrepresentableName"
+]);
+/** @internal */
+export class FsError extends Data.TaggedError("FsError") {
+    // The path is omitted on purpose: byte paths are not printable and may carry user data.
+    get message() {
+        return `${this.operation} failed with ${this.code}`;
+    }
+}
+/** @internal */
+export class ConfigurationError extends Data.TaggedError("ConfigurationError") {
+    get message() {
+        return `Invalid option: ${this.field}`;
+    }
+}
+// Names the offending option so the caller learns which key it got wrong, not just that decoding failed.
+const configurationField = (issue) => {
+    if (Predicate.isTagged("Pointer")(issue))
+        return issue.path.map(String).join(".");
+    if (Predicate.isTagged("Composite")(issue))
+        return configurationField(issue.issues[0]);
+    return "options";
+};
+/** @internal */
+export const decodeConfiguration = (schema, value) => Schema.decodeUnknownResult(schema, { onExcessProperty: "error" })(value).pipe(Result.mapError((error) => new ConfigurationError({ field: configurationField(error.issue) })));

package/dist/internal/virtualFileSystem/fixture.d.ts

@@ -0,0 +1,63 @@
+import * as Effect from "effect/Effect";
+import { ImageError } from "../../Snapshot.js";
+/** @internal */
+export declare const fromFixture: (fixture: {
+    readonly rootMetadata?: {
+        readonly uid?: number;
+        readonly gid?: number;
+        readonly mode?: number;
+        readonly atimeNs?: bigint;
+        readonly mtimeNs?: bigint;
+        readonly ctimeNs?: bigint;
+        readonly birthtimeNs?: bigint;
+    };
+    readonly entries: readonly ({
+        readonly kind: "directory";
+        readonly path: string | import("../../BytePath.js").BytePath;
+        readonly metadata?: {
+            readonly uid?: number;
+            readonly gid?: number;
+            readonly mode?: number;
+            readonly atimeNs?: bigint;
+            readonly mtimeNs?: bigint;
+            readonly ctimeNs?: bigint;
+            readonly birthtimeNs?: bigint;
+        };
+    } | {
+        readonly kind: "file";
+        readonly path: string | import("../../BytePath.js").BytePath;
+        readonly bytes: Uint8Array<ArrayBufferLike>;
+        readonly metadata?: {
+            readonly uid?: number;
+            readonly gid?: number;
+            readonly mode?: number;
+            readonly atimeNs?: bigint;
+            readonly mtimeNs?: bigint;
+            readonly ctimeNs?: bigint;
+            readonly birthtimeNs?: bigint;
+        };
+    } | {
+        readonly kind: "symlink";
+        readonly path: string | import("../../BytePath.js").BytePath;
+        readonly target: string | import("../../BytePath.js").BytePath;
+        readonly metadata?: {
+            readonly uid?: number;
+            readonly gid?: number;
+            readonly mode?: number;
+            readonly atimeNs?: bigint;
+            readonly mtimeNs?: bigint;
+            readonly ctimeNs?: bigint;
+            readonly birthtimeNs?: bigint;
+        };
+    } | {
+        readonly kind: "hardLink";
+        readonly path: string | import("../../BytePath.js").BytePath;
+        readonly target: string | import("../../BytePath.js").BytePath;
+    })[];
+}, options?: {
+    readonly maxEntries?: number;
+    readonly maxBytes?: import("effect/ByteSize").ByteSize;
+    readonly maxFileBytes?: import("effect/ByteSize").ByteSize;
+    readonly maxPathBytes?: import("effect/ByteSize").ByteSize;
+} | undefined) => Effect.Effect<import("../../VirtualFileSystem.js").Volume, import("./errors.js").ConfigurationError | ImageError, never>;
+//# sourceMappingURL=fixture.d.ts.map

package/dist/internal/virtualFileSystem/fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture.d.ts","sourceRoot":"","sources":["../../../src/internal/virtualFileSystem/fixture.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAmB9C,gBAAgB;AAChB,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0IAiLvB,CAAA"}

package/dist/internal/virtualFileSystem/fixture.js

@@ -0,0 +1,144 @@
+// Fixture image construction.
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { ImageError } from "../../Snapshot.js";
+import { CanonicalBase64 } from "../canonicalBase64.js";
+import * as Image from "../image.js";
+import { Fixture as FixtureSchema, FixtureEntry, makeVolume, VolumeOptions as VolumeOptionsSchema, VolumeSource } from "../virtualFileSystem.js";
+import { decodeConfiguration, FsError } from "./errors.js";
+import { inputBytes, isAttachedBytes, isDotComponent, nameBytes, preparePath } from "./path.js";
+const DEFAULT_MODE = { directory: 0o755, file: 0o644, symlink: 0o777 };
+const EPOCH_NS = 0n;
+/** @internal */
+export const fromFixture = Effect.fn("VirtualFileSystem.fromFixture")(function* (fixture, options) {
+    const config = decodeConfiguration(VolumeOptionsSchema, options ?? {});
+    if (Result.isFailure(config))
+        return yield* config.failure;
+    const decoded = Schema.decodeResult(FixtureSchema, { onExcessProperty: "error" })(fixture);
+    if (Result.isFailure(decoded))
+        return yield* new ImageError({ code: "InvalidStructure", field: "fixture" });
+    const source = decoded.success;
+    if (source.entries.some((entry) => FixtureEntry.match(entry, {
+        directory: () => false,
+        file: ({ bytes }) => !isAttachedBytes(bytes),
+        symlink: () => false,
+        hardLink: () => false
+    }))) {
+        return yield* new ImageError({ code: "InvalidEncoding", field: "bytes" });
+    }
+    const metadata = (kind, overrides) => ({
+        uid: overrides?.uid ?? 0,
+        gid: overrides?.gid ?? 0,
+        mode: overrides?.mode ?? DEFAULT_MODE[kind],
+        atimeNs: overrides?.atimeNs ?? EPOCH_NS,
+        mtimeNs: overrides?.mtimeNs ?? EPOCH_NS,
+        ctimeNs: overrides?.ctimeNs ?? EPOCH_NS,
+        birthtimeNs: overrides?.birthtimeNs ?? EPOCH_NS
+    });
+    const declarations = new Map();
+    const aliases = new Map();
+    const paths = new Map();
+    const root = Image.Record.cases.directory.make({
+        id: "root",
+        metadata: metadata("directory", source.rootMetadata),
+        entries: []
+    });
+    declarations.set("", root);
+    const fixturePath = (input) => preparePath(input, "fixture", config.success.maxPathBytes).pipe(Result.flatMap((path) => !path.absolute || path.components.length === 0 ||
+        path.components.some(isDotComponent)
+        ? Result.fail(new FsError({ code: "InvalidArgument", operation: "fixture", path: input })) :
+        Result.succeed(path.components)));
+    // Encode caller-owned byte buffers now: nothing below yields until Image.capture, so a caller
+    // cannot mutate them first.
+    for (const entry of source.entries) {
+        const parsed = fixturePath(entry.path);
+        if (Result.isFailure(parsed)) {
+            return yield* new ImageError({ code: "InvalidStructure", field: "path" });
+        }
+        const components = parsed.success;
+        const key = components.join("/");
+        if (paths.has(key))
+            return yield* new ImageError({ code: "InvalidStructure", field: "duplicate" });
+        paths.set(key, components);
+        const error = FixtureEntry.match(entry, {
+            hardLink: ({ target }) => {
+                const parsedTarget = fixturePath(target);
+                if (Result.isFailure(parsedTarget))
+                    return new ImageError({ code: "InvalidStructure", field: "target" });
+                aliases.set(key, parsedTarget.success.join("/"));
+            },
+            directory: (entry) => {
+                declarations.set(key, Image.Record.cases.directory.make({
+                    id: String(paths.size),
+                    metadata: metadata("directory", entry.metadata),
+                    entries: []
+                }));
+            },
+            file: (entry) => {
+                declarations.set(key, Image.Record.cases.file.make({
+                    id: String(paths.size),
+                    metadata: metadata("file", entry.metadata),
+                    data: CanonicalBase64.encode(entry.bytes)
+                }));
+            },
+            symlink: ({ metadata: overrides, target: input }) => {
+                const target = inputBytes(input);
+                if (Result.isFailure(target)) {
+                    return new ImageError({
+                        code: target.failure === "InvalidPathEncoding" ? "InvalidEncoding" : "InvalidStructure",
+                        field: "target"
+                    });
+                }
+                if (target.success.includes(0))
+                    return new ImageError({ code: "InvalidStructure", field: "target" });
+                declarations.set(key, Image.Record.cases.symlink.make({
+                    id: String(paths.size),
+                    metadata: metadata("symlink", overrides),
+                    target: CanonicalBase64.encode(target.success)
+                }));
+            }
+        });
+        if (error instanceof ImageError)
+            return yield* error;
+    }
+    for (const [key] of aliases) {
+        let target = key;
+        const seen = new Set();
+        while (!declarations.has(target)) {
+            if (seen.has(target))
+                return yield* new ImageError({ code: "InvalidStructure", field: "hardLink" });
+            seen.add(target);
+            const next = aliases.get(target);
+            if (next === undefined)
+                return yield* new ImageError({ code: "InvalidStructure", field: "hardLink" });
+            target = next;
+        }
+        const node = declarations.get(target);
+        if (node === undefined || Image.Record.guards.directory(node)) {
+            return yield* new ImageError({ code: "InvalidStructure", field: "hardLink" });
+        }
+        for (const alias of seen)
+            declarations.set(alias, node);
+    }
+    const children = new Map();
+    for (const [key, components] of paths) {
+        const parent = declarations.get(components.slice(0, -1).join("/"));
+        const child = declarations.get(key);
+        const name = components.at(-1);
+        if (parent?._tag !== "directory" || child === undefined || name === undefined) {
+            return yield* new ImageError({ code: "InvalidStructure", field: "parent" });
+        }
+        const entries = children.get(parent.id) ?? [];
+        entries.push({ name: CanonicalBase64.encode(nameBytes(name)), target: child.id });
+        children.set(parent.id, entries);
+    }
+    const records = [...new Set(declarations.values())].map((record) => Image.Record.match(record, {
+        directory: (record) => ({ ...record, entries: children.get(record.id) ?? [] }),
+        file: (record) => record,
+        symlink: (record) => record
+    }));
+    const snapshot = yield* Image.capture({ format: "effect-vfs", version: 1, root: "root", records }, undefined, true);
+    const image = yield* Image.inspect(snapshot);
+    return yield* makeVolume(VolumeSource.Snapshot({ image }), config.success);
+});

package/dist/internal/{content.d.ts → virtualFileSystem/overlayContent.d.ts}

@@ -1,10 +1,5 @@
-/**
- * Immutable regular-file payloads shared by overlay workspaces.
- *
- * @internal
- */
-import type { Snapshot } from "../Snapshot.js";
-import * as Image from "./image.js";
+import type { Snapshot } from "../../Snapshot.js";
+import * as Image from "../image.js";
 /** @internal */
 export interface Content {
     readonly bytes: Uint8Array;
@@ -15,11 +10,6 @@ export declare const hasOverlayContents: (snapshot: Snapshot) => boolean;
 export declare const make: (bytes: Uint8Array) => Content;
 /** @internal */
 export declare const empty: () => Content;
-/**
- * Returns the immutable file payloads associated with the identity of a base
- * snapshot. The cache is weak so it cannot extend the snapshot's lifetime.
- *
- * @internal
- */
+/** @internal */
 export declare const forOverlay: (snapshot: Snapshot, image: Image.Document) => ReadonlyMap<string, Content>;
-//# sourceMappingURL=content.d.ts.map
+//# sourceMappingURL=overlayContent.d.ts.map

package/dist/internal/virtualFileSystem/overlayContent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlayContent.d.ts","sourceRoot":"","sources":["../../../src/internal/virtualFileSystem/overlayContent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AAEpC,gBAAgB;AAChB,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAC3B;AAID,gBAAgB;AAChB,eAAO,MAAM,kBAAkB,aAAc,QAAQ,KAAG,OAAwC,CAAA;AAEhG,gBAAgB;AAChB,eAAO,MAAM,IAAI,UAAW,UAAU,KAAG,OAAsB,CAAA;AAE/D,gBAAgB;AAChB,eAAO,MAAM,KAAK,QAAO,OAAkC,CAAA;AAG3D,gBAAgB;AAChB,eAAO,MAAM,UAAU,aAAc,QAAQ,SAAS,KAAK,CAAC,QAAQ,KAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAiBjG,CAAA"}

package/dist/internal/virtualFileSystem/overlayContent.js

@@ -0,0 +1,29 @@
+// Immutable regular-file payloads shared by overlay workspaces.
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { CanonicalBase64 } from "../canonicalBase64.js";
+import * as Image from "../image.js";
+const overlayContents = new WeakMap();
+/** @internal */
+export const hasOverlayContents = (snapshot) => overlayContents.has(snapshot);
+/** @internal */
+export const make = (bytes) => ({ bytes });
+/** @internal */
+export const empty = () => make(new Uint8Array(0));
+// The weak cache shares immutable payloads without extending the snapshot's lifetime.
+/** @internal */
+export const forOverlay = (snapshot, image) => {
+    const cached = overlayContents.get(snapshot);
+    if (cached !== undefined)
+        return cached;
+    const decoded = new Map();
+    for (const record of image.records) {
+        if (Image.Record.guards.file(record)) {
+            const bytes = Schema.decodeResult(CanonicalBase64.Bytes)(record.data);
+            if (Result.isSuccess(bytes))
+                decoded.set(record.id, make(bytes.success));
+        }
+    }
+    overlayContents.set(snapshot, decoded);
+    return decoded;
+};

package/dist/internal/{overlayChanges.d.ts → virtualFileSystem/overlayDiff.d.ts}

@@ -1,20 +1,11 @@
-/** @internal */
-export interface ObservationMetadata {
-    readonly uid: number;
-    readonly gid: number;
-    readonly mode: number;
-    readonly atimeNs: string;
-    readonly mtimeNs: string;
-    readonly ctimeNs: string;
-    readonly birthtimeNs: string;
-}
+import type { StoredMetadata } from "../metadata.js";
 /** @internal */
 export interface ObservationEntry {
     readonly path: Uint8Array;
     readonly lineage: string | undefined;
     readonly kind: "directory" | "file" | "symlink";
     readonly content: Uint8Array | undefined;
-    readonly metadata: ObservationMetadata;
+    readonly metadata: StoredMetadata;
 }
 /** @internal */
 export type OverlayDifference = "content" | "mode" | "uid" | "gid" | "atimeNs" | "mtimeNs" | "ctimeNs" | "birthtimeNs";
@@ -47,4 +38,4 @@ export type RawOverlayChange = {
 };
 /** @internal */
 export declare const compareOverlay: (base: ReadonlyArray<ObservationEntry>, current: ReadonlyArray<ObservationEntry>, includeTimestamps?: boolean) => ReadonlyArray<RawOverlayChange>;
-//# sourceMappingURL=overlayChanges.d.ts.map
+//# sourceMappingURL=overlayDiff.d.ts.map

package/dist/internal/virtualFileSystem/overlayDiff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlayDiff.d.ts","sourceRoot":"","sources":["../../../src/internal/virtualFileSystem/overlayDiff.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,gBAAgB;AAChB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;CAClC;AAED,gBAAgB;AAChB,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;AAEtH,gBAAgB;AAChB,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAA;CAAE,GAC9F;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAA;CAAE,GAChG;IACA,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAA;IAC7C,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAA;IAC5C,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAA;CACvD,GACC;IACA,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAA;IACvC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAA;CACvD,GACC;IACA,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAA;IACvC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAA;CACvD,CAAA;AA4DH,gBAAgB;AAChB,eAAO,MAAM,cAAc,SACnB,aAAa,CAAC,gBAAgB,CAAC,WAC5B,aAAa,CAAC,gBAAgB,CAAC,kCAEvC,aAAa,CAAC,gBAAgB,CAgFhC,CAAA"}

package/dist/internal/virtualFileSystem/overlayDiff.js

@@ -0,0 +1,120 @@
+import * as Data from "effect/Data";
+import * as Encoding from "effect/Encoding";
+import * as Order from "effect/Order";
+import * as Predicate from "effect/Predicate";
+import { bytesOrder, sameBytes } from "../bytes.js";
+const RawOverlayChange = Data.taggedEnum();
+const timestampFields = new Set(["atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]);
+const differenceOrder = [
+    "content",
+    "mode",
+    "uid",
+    "gid",
+    "atimeNs",
+    "mtimeNs",
+    "ctimeNs",
+    "birthtimeNs"
+];
+const tagOrder = {
+    Added: 0,
+    Removed: 1,
+    Replaced: 2,
+    Renamed: 3,
+    Updated: 4
+};
+const key = Encoding.encodeHex;
+// Output order: source path bytewise (a rename sorts by its `from`), then Added, Removed, Replaced, Renamed, Updated.
+const sourcePath = (change) => Predicate.isTagged("Renamed")(change) ? change.from : change.path;
+const changeOrder = Order.combine(Order.mapInput(bytesOrder, sourcePath), Order.mapInput(Order.Number, (change) => tagOrder[change._tag]));
+const differences = (before, after, includeTimestamps) => Object.freeze(differenceOrder.filter((field) => {
+    if (!includeTimestamps && timestampFields.has(field))
+        return false;
+    // A kind change always counts as a content change, even when the bytes happen to match.
+    if (field === "content")
+        return before.kind !== after.kind || !sameBytes(before.content, after.content);
+    return before.metadata[field] !== after.metadata[field];
+}));
+const byLineage = (entries) => {
+    const result = new Map();
+    for (const entry of entries) {
+        if (entry.lineage === undefined)
+            continue;
+        const group = result.get(entry.lineage);
+        if (group === undefined)
+            result.set(entry.lineage, new Map([[key(entry.path), entry]]));
+        else
+            group.set(key(entry.path), entry);
+    }
+    return result;
+};
+/** @internal */
+export const compareOverlay = (base, current, includeTimestamps = false) => {
+    const basePaths = new Map(base.map((entry) => [key(entry.path), entry]));
+    const currentPaths = new Map(current.map((entry) => [key(entry.path), entry]));
+    const baseLineages = byLineage(base);
+    const currentLineages = byLineage(current);
+    const renameSources = new Set();
+    const renameTargets = new Set();
+    const changes = [];
+    for (const [lineage, beforeEntries] of baseLineages) {
+        const afterEntries = currentLineages.get(lineage);
+        if (afterEntries === undefined)
+            continue;
+        const removed = [];
+        for (const [pathKey, entry] of beforeEntries) {
+            if (!afterEntries.has(pathKey))
+                removed.push(entry);
+        }
+        const added = [];
+        for (const [pathKey, entry] of afterEntries) {
+            if (!beforeEntries.has(pathKey))
+                added.push(entry);
+        }
+        if (removed.length !== 1 || added.length !== 1)
+            continue;
+        const before = removed[0];
+        const after = added[0];
+        renameSources.add(key(before.path));
+        renameTargets.add(key(after.path));
+        changes.push(RawOverlayChange.Renamed({
+            from: before.path.slice(),
+            to: after.path.slice(),
+            kind: after.kind,
+            differences: differences(before, after, includeTimestamps)
+        }));
+    }
+    for (const before of base) {
+        const pathKey = key(before.path);
+        if (renameSources.has(pathKey))
+            continue;
+        const after = currentPaths.get(pathKey);
+        // Gone, or the path's current occupant arrived by rename: the base entry was removed either way.
+        if (after === undefined || renameTargets.has(pathKey)) {
+            changes.push(RawOverlayChange.Removed({ path: before.path.slice(), kind: before.kind }));
+            continue;
+        }
+        if (before.lineage === undefined || before.lineage !== after.lineage) {
+            changes.push(RawOverlayChange.Replaced({
+                path: before.path.slice(),
+                beforeKind: before.kind,
+                afterKind: after.kind,
+                differences: differences(before, after, includeTimestamps)
+            }));
+            continue;
+        }
+        const changed = differences(before, after, includeTimestamps);
+        if (changed.length > 0) {
+            changes.push(RawOverlayChange.Updated({ path: before.path.slice(), kind: after.kind, differences: changed }));
+        }
+    }
+    for (const after of current) {
+        const pathKey = key(after.path);
+        // A new path, or one whose base occupant was renamed away; rename targets were already reported.
+        if (!renameTargets.has(pathKey) && (!basePaths.has(pathKey) || renameSources.has(pathKey))) {
+            changes.push(RawOverlayChange.Added({ path: after.path.slice(), kind: after.kind }));
+        }
+    }
+    changes.sort(changeOrder);
+    // Every record owns its byte buffers and is frozen, so callers may wrap paths without copying.
+    return Object.freeze(changes.map((change) => Object.freeze(change)));
+};

package/dist/internal/virtualFileSystem/path.d.ts

@@ -0,0 +1,44 @@
+import * as ByteSize from "effect/ByteSize";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import type { BytePath } from "../../BytePath.js";
+import type { PathInput } from "../../VirtualFileSystem.js";
+import { FsError } from "./errors.js";
+/** @internal */
+export declare const SLASH_HEX = "2f";
+/** @internal */
+export declare const DOT_HEX = "2e";
+/** @internal */
+export declare const DOT_DOT_HEX = "2e2e";
+/** @internal */
+export declare const SLASH_BYTE = 47;
+/** @internal */
+export declare const MAX_NAME_BYTES = 255;
+/** @internal */
+export declare const isDotComponent: (name: string | undefined) => name is undefined | typeof DOT_HEX | typeof DOT_DOT_HEX;
+/** @internal */
+export declare const ownedPath: (bytes: Uint8Array) => BytePath;
+/** @internal */
+export declare const strictString: (bytes: Uint8Array, operation: string) => Effect.Effect<string, FsError, never>;
+/** @internal */
+export declare const nameBytes: (name: string) => Uint8Array;
+/** @internal */
+export declare const isAttachedBytes: (bytes: Uint8Array) => boolean;
+/** @internal */
+export declare const pathFromBytes: (bytes: Uint8Array<ArrayBufferLike>) => Effect.Effect<BytePath, FsError, never>;
+/** @internal */
+export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array<ArrayBuffer>, FsError, never>;
+/** @internal */
+export interface PreparedPath {
+    readonly input: PathInput;
+    readonly absolute: boolean;
+    readonly trailingSlash: boolean;
+    readonly bytes: Uint8Array;
+    readonly suffixes: ReadonlyArray<Uint8Array>;
+    readonly components: ReadonlyArray<string>;
+}
+/** @internal */
+export declare const inputBytes: (input: PathInput) => Result.Result<Uint8Array, "InvalidPathEncoding" | "InvalidArgument">;
+/** @internal */
+export declare const preparePath: (input: PathInput, operation: string, maxPathBytes: ByteSize.ByteSize | undefined) => Result.Result<PreparedPath, FsError>;
+//# sourceMappingURL=path.d.ts.map

package/dist/internal/virtualFileSystem/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/internal/virtualFileSystem/path.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAE3D,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAGrC,gBAAgB;AAChB,eAAO,MAAM,SAAS,OAAO,CAAA;AAE7B,gBAAgB;AAChB,eAAO,MAAM,OAAO,OAAO,CAAA;AAE3B,gBAAgB;AAChB,eAAO,MAAM,WAAW,SAAS,CAAA;AAEjC,gBAAgB;AAChB,eAAO,MAAM,UAAU,KAAK,CAAA;AAG5B,gBAAgB;AAChB,eAAO,MAAM,cAAc,MAAM,CAAA;AAKjC,gBAAgB;AAChB,eAAO,MAAM,cAAc,SAAU,MAAM,GAAG,SAAS,KAAG,IAAI,IAAI,SAAS,GAAG,OAAO,OAAO,GAAG,OAAO,WACtC,CAAA;AAEhE,gBAAgB;AAChB,eAAO,MAAM,SAAS,UAAW,UAAU,KAAG,QAA+B,CAAA;AAE7E,gBAAgB;AAChB,eAAO,MAAM,YAAY,UAAW,UAAU,aAAa,MAAM,0CAI7D,CAAA;AAEJ,gBAAgB;AAChB,eAAO,MAAM,SAAS,SAAU,MAAM,KAAG,UAAyD,CAAA;AAgBlG,gBAAgB;AAChB,eAAO,MAAM,eAAe,UAAW,UAAU,KAAG,OAC2C,CAAA;AAE/F,gBAAgB;AAChB,eAAO,MAAM,aAAa,iFASxB,CAAA;AAEF,gBAAgB;AAChB,eAAO,MAAM,WAAW,4EAMtB,CAAA;AAEF,gBAAgB;AAChB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;IAC5C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAC3C;AAoBD,gBAAgB;AAChB,eAAO,MAAM,UAAU,UAAW,SAAS,KAAG,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,qBAAqB,GAAG,iBAAiB,CAG5B,CAAA;AAErF,gBAAgB;AAChB,eAAO,MAAM,WAAW,UACf,SAAS,aACL,MAAM,gBACH,QAAQ,CAAC,QAAQ,GAAG,SAAS,KAC1C,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAgDrC,CAAA"}