@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/settings/settings.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Settings management for AXM workspace configuration.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { SettingsWriteError } from "./errors.js";
+import { type Settings } from "./schema.js";
+import { applyJsonPatchToText } from "./format-preserving-json.js";
+/**
+ * Create default settings object.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const createDefaultSettings: () => Settings;
+type ExistingSettingsRenderResult = {
+    readonly content: string;
+    readonly fallbackReason?: "edit_failed" | "edited_content_invalid";
+};
+/** @internal */
+export declare const renderExistingSettings: (priorText: string, prior: Schema.Json, target: Schema.Json, canonicalContent: string, applyPatch?: typeof applyJsonPatchToText) => ExistingSettingsRenderResult;
+/**
+ * Write settings to the selected scope's settings path.
+ *
+ * Creates the directory if it doesn't exist. Pretty-prints JSON with 2-space indent.
+ *
+ * @param settingsPath - Exact project or user settings path
+ * @param settings - Settings object to write
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const writeSettingsAtPath: (settingsPath: string, settings: Settings) => Effect.Effect<void, SettingsWriteError | import("../workspace/transaction.js").WorkspaceSnapshotError, FileSystem.FileSystem | Path.Path>;
+export {};
+//# sourceMappingURL=settings.d.ts.map

package/dist/src/settings/settings.js

@@ -0,0 +1,213 @@
+/**
+ * Settings management for AXM workspace configuration.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as JsonPatch from "effect/JsonPatch";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { sweepStaleAtomicWriteTemps, writeFileAtomic } from "../utils/atomic-write.js";
+import { SettingsWriteError } from "./errors.js";
+import { protectWorkspacePath } from "../workspace/transaction.js";
+import { recordFootprint } from "../workspace/footprint-recorder.js";
+import { SETTINGS_KEY_ORDER, SETTINGS_KNOWN_KEYS, SettingsSchema, } from "./schema.js";
+import { applyJsonPatchToText } from "./format-preserving-json.js";
+// -----------------------------------------------------------------------------
+// Default Settings
+// -----------------------------------------------------------------------------
+/**
+ * Create default settings object.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const createDefaultSettings = () => ({});
+// -----------------------------------------------------------------------------
+// Key Ordering
+// -----------------------------------------------------------------------------
+/**
+ * Reorder settings keys to match the canonical schema order.
+ *
+ * Creates a new object with keys in `SETTINGS_KEY_ORDER`, omitting keys
+ * not present in the input.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isEmptySettingsConfig = (key, value) => {
+    if (key !== "knowledgeConfig" || !isRecord(value))
+        return false;
+    return value["instructions"] !== false;
+};
+const orderSettingsRecord = (settings) => {
+    const ordered = SETTINGS_KEY_ORDER.reduce((accumulated, key) => {
+        const value = settings[key];
+        return value === undefined || isEmptySettingsConfig(key, value)
+            ? accumulated
+            : { ...accumulated, [key]: value };
+    }, {});
+    // Unknown top-level keys are preserved after the canonical keys, in their
+    // original relative order, so a write never discards data it did not create.
+    for (const [key, value] of Object.entries(settings)) {
+        if (!SETTINGS_KNOWN_KEYS.has(key) && value !== undefined) {
+            ordered[key] = value;
+        }
+    }
+    return ordered;
+};
+const isJsonArray = (value) => Array.isArray(value);
+const isJsonObject = (value) => typeof value === "object" && value !== null && !isJsonArray(value);
+const parseJson = (text) => {
+    try {
+        return Schema.decodeUnknownSync(Schema.Json)(JSON.parse(text));
+    }
+    catch {
+        return undefined;
+    }
+};
+const serializeCanonicalSettings = (settings) => JSON.stringify(settings, null, 2) + "\n";
+const ensureSingleTrailingNewline = (content) => content.replace(/[\r\n]+$/, "") + "\n";
+const hasCanonicalTopLevelOrder = (settings) => {
+    if (!isJsonObject(settings))
+        return false;
+    let previousIndex = -1;
+    let foundUnknownKey = false;
+    for (const key of Object.keys(settings)) {
+        const index = SETTINGS_KEY_ORDER.indexOf(key);
+        if (index === -1) {
+            foundUnknownKey = true;
+            continue;
+        }
+        if (foundUnknownKey || index <= previousIndex)
+            return false;
+        previousIndex = index;
+    }
+    return true;
+};
+const insertionIndexFor = (priorWasCanonical, path, properties) => {
+    const key = path.length === 1 ? path[0] : undefined;
+    if (!priorWasCanonical || typeof key !== "string")
+        return properties.length;
+    const keyIndex = SETTINGS_KEY_ORDER.indexOf(key);
+    if (keyIndex === -1)
+        return properties.length;
+    const nextIndex = properties.findIndex((property) => {
+        const propertyIndex = SETTINGS_KEY_ORDER.indexOf(property);
+        return propertyIndex === -1 || propertyIndex > keyIndex;
+    });
+    return nextIndex === -1 ? properties.length : nextIndex;
+};
+/** @internal */
+export const renderExistingSettings = (priorText, prior, target, canonicalContent, applyPatch = applyJsonPatchToText) => {
+    const patch = JsonPatch.get(prior, target);
+    if (patch.length === 0) {
+        return { content: ensureSingleTrailingNewline(priorText) };
+    }
+    const priorWasCanonical = hasCanonicalTopLevelOrder(prior);
+    const edited = applyPatch(priorText, prior, patch, {
+        getInsertionIndex: (path, properties) => insertionIndexFor(priorWasCanonical, path, properties),
+    });
+    if (edited._tag === "Failure") {
+        return { content: canonicalContent, fallbackReason: "edit_failed" };
+    }
+    const parsed = parseJson(edited.text);
+    if (parsed === undefined || JsonPatch.get(parsed, target).length !== 0) {
+        return { content: canonicalContent, fallbackReason: "edited_content_invalid" };
+    }
+    if (isJsonObject(target) && Object.keys(target).length === 0) {
+        return { content: canonicalContent };
+    }
+    return { content: ensureSingleTrailingNewline(edited.text) };
+};
+// -----------------------------------------------------------------------------
+// Core Functions
+// -----------------------------------------------------------------------------
+/**
+ * Write settings to the selected scope's settings path.
+ *
+ * Creates the directory if it doesn't exist. Pretty-prints JSON with 2-space indent.
+ *
+ * @param settingsPath - Exact project or user settings path
+ * @param settings - Settings object to write
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const writeSettingsAtPath = (settingsPath, settings) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const settingsDir = path.dirname(settingsPath);
+    // Ensure directory exists
+    yield* fs
+        .makeDirectory(settingsDir, { recursive: true })
+        .pipe(Effect.mapError((cause) => new SettingsWriteError({ path: settingsDir, step: "mkdir", cause })));
+    // Encode through schema (converts Option -> nullable, URL -> string, etc.)
+    const encoded = yield* Schema.encodeEffect(SettingsSchema)(settings).pipe(Effect.mapError((cause) => new SettingsWriteError({ path: settingsPath, step: "encode", cause })));
+    const ordered = orderSettingsRecord(encoded);
+    const canonicalContent = serializeCanonicalSettings(ordered);
+    const targetResult = yield* Effect.result(Schema.decodeUnknownEffect(Schema.Json)(ordered));
+    let content = canonicalContent;
+    if (targetResult._tag === "Failure") {
+        yield* Effect.logDebug("Falling back to canonical settings serialization", {
+            settingsPath,
+            reason: "target_not_json",
+        });
+    }
+    else {
+        const existsResult = yield* Effect.result(fs.exists(settingsPath));
+        if (existsResult._tag === "Failure") {
+            yield* Effect.logDebug("Falling back to canonical settings serialization", {
+                settingsPath,
+                reason: "existence_check_failed",
+            });
+        }
+        else if (existsResult.success) {
+            const readResult = yield* Effect.result(fs.readFileString(settingsPath));
+            if (readResult._tag === "Failure") {
+                yield* Effect.logDebug("Falling back to canonical settings serialization", {
+                    settingsPath,
+                    reason: "read_failed",
+                });
+            }
+            else if (readResult.success.trim() !== "") {
+                const prior = parseJson(readResult.success);
+                if (prior === undefined) {
+                    yield* Effect.logDebug("Falling back to canonical settings serialization", {
+                        settingsPath,
+                        reason: "parse_failed",
+                    });
+                }
+                else {
+                    const rendered = renderExistingSettings(readResult.success, prior, targetResult.success, canonicalContent);
+                    content = rendered.content;
+                    if (rendered.fallbackReason !== undefined) {
+                        yield* Effect.logDebug("Falling back to canonical settings serialization", {
+                            settingsPath,
+                            reason: rendered.fallbackReason,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    yield* protectWorkspacePath(settingsPath);
+    const existed = yield* fs.exists(settingsPath).pipe(Effect.orElseSucceed(() => true));
+    // Write to a temp file then atomically rename into place, so an interrupted
+    // write can never truncate or corrupt the user's existing settings file.
+    // The temp file is removed on any failure or interruption.
+    yield* sweepStaleAtomicWriteTemps(fs, settingsPath);
+    yield* writeFileAtomic(fs, {
+        targetPath: settingsPath,
+        content,
+        mapError: (failure) => failure.step === "rename"
+            ? new SettingsWriteError({ path: settingsPath, step: "rename", cause: failure.cause })
+            : new SettingsWriteError({
+                path: failure.tempPath,
+                step: "write-temp",
+                cause: failure.cause,
+            }),
+    });
+    yield* recordFootprint({ path: settingsPath, change: existed ? "modified" : "created" });
+});
+//# sourceMappingURL=settings.js.map

package/dist/src/testing.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @agentxm/workspace-state deterministic test layers and fixtures.
+ *
+ * In-memory and fixture-backed implementations of this package's own
+ * services for tests and executable specifications. Production source never
+ * imports this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export * from "./workspace/test-stubs.js";
+export { WorkspaceReadModelTest, type WorkspaceReadModelTestOptions, } from "./workspace/read-model/__fixtures__/test-layer.js";
+export * from "./workspace/read-model/__fixtures__/builder.js";
+export * from "./workspace/read-model/__fixtures__/decoders.js";
+export * from "./workspace/read-model/__fixtures__/occurrences.js";
+export * from "./workspace/read-model/__fixtures__/scenario-harness.js";
+//# sourceMappingURL=testing.d.ts.map

package/dist/src/testing.js

@@ -0,0 +1,17 @@
+/**
+ * @agentxm/workspace-state deterministic test layers and fixtures.
+ *
+ * In-memory and fixture-backed implementations of this package's own
+ * services for tests and executable specifications. Production source never
+ * imports this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export * from "./workspace/test-stubs.js";
+export { WorkspaceReadModelTest, } from "./workspace/read-model/__fixtures__/test-layer.js";
+export * from "./workspace/read-model/__fixtures__/builder.js";
+export * from "./workspace/read-model/__fixtures__/decoders.js";
+export * from "./workspace/read-model/__fixtures__/occurrences.js";
+export * from "./workspace/read-model/__fixtures__/scenario-harness.js";
+//# sourceMappingURL=testing.js.map

package/dist/src/utils/atomic-write.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared atomic single-file replacement: write a uniquely named temp file in
+ * the target's directory, then rename it over the target.
+ *
+ * The temp file lives next to the target so the rename stays on one
+ * filesystem (and therefore atomic), and is removed on any failure or
+ * interruption. Temp names follow `<target>.tmp.<unique>`; sweepers that
+ * clean stale temps (e.g. the lockfile writer) rely on that prefix.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { PlatformError } from "effect/PlatformError";
+/**
+ * Step at which an atomic write failed. `check-target` and `read-target` can
+ * only occur with `skipIfUnchanged: "fail-on-read-error"`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type AtomicWriteStep = "check-target" | "read-target" | "write-temp" | "rename";
+/**
+ * Failure passed to `mapError` so each call site keeps its own error shape.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface AtomicWriteFailure {
+    readonly step: AtomicWriteStep;
+    readonly targetPath: string;
+    readonly tempPath: string;
+    readonly cause: PlatformError;
+}
+/**
+ * Content-equality short-circuit mode: `fail-on-read-error` surfaces
+ * check/read failures via `mapError`; `ignore-read-errors` treats an
+ * unreadable target as changed and proceeds to write.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type SkipIfUnchanged = "fail-on-read-error" | "ignore-read-errors";
+/**
+ * Options for `writeFileAtomic`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface WriteFileAtomicOptions<E> {
+    readonly targetPath: string;
+    readonly content: string | Uint8Array;
+    /** When set, leave the target untouched if it already has this content. */
+    readonly skipIfUnchanged?: SkipIfUnchanged;
+    /** Best-effort remove of the target before rename (Windows cannot always rename over an existing file). */
+    readonly removeTargetBeforeRename?: boolean;
+    readonly mapError: (failure: AtomicWriteFailure) => E;
+}
+export declare const atomicWriteTempPrefix: (targetPath: string) => string;
+/** Remove only stale temp siblings belonging to one atomic-write target. */
+export declare const sweepStaleAtomicWriteTemps: (fs: FileSystem.FileSystem, targetPath: string) => Effect.Effect<void, never, Path.Path>;
+/**
+ * Atomically replace `targetPath` with `content` via a same-directory temp
+ * file and rename. Failures at each step are mapped by the caller, so error
+ * codes, details, and suggestions stay call-site specific.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const writeFileAtomic: <E>(fs: FileSystem.FileSystem, options: WriteFileAtomicOptions<E>) => Effect.Effect<"written" | "skipped", E>;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/src/utils/atomic-write.js

@@ -0,0 +1,71 @@
+/**
+ * Shared atomic single-file replacement: write a uniquely named temp file in
+ * the target's directory, then rename it over the target.
+ *
+ * The temp file lives next to the target so the rename stays on one
+ * filesystem (and therefore atomic), and is removed on any failure or
+ * interruption. Temp names follow `<target>.tmp.<unique>`; sweepers that
+ * clean stale temps (e.g. the lockfile writer) rely on that prefix.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+/** In-process sequence so concurrent fibers never share a temp path. */
+let tempSequence = 0;
+export const atomicWriteTempPrefix = (targetPath) => `${targetPath}.tmp.`;
+/** Remove only stale temp siblings belonging to one atomic-write target. */
+export const sweepStaleAtomicWriteTemps = (fs, targetPath) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const parent = path.dirname(targetPath);
+    const filenamePrefix = `${path.basename(targetPath)}.tmp.`;
+    const entries = yield* fs.readDirectory(parent).pipe(Effect.orElseSucceed(() => []));
+    yield* Effect.forEach(entries.filter((entry) => entry.startsWith(filenamePrefix)), (entry) => fs.remove(path.join(parent, entry), { force: true }).pipe(Effect.ignore), { discard: true });
+});
+const makeTempPath = (targetPath) => {
+    tempSequence += 1;
+    const pid = typeof process === "object" ? process.pid.toString(36) : "x";
+    const random = Math.random().toString(36).slice(2, 8);
+    return `${atomicWriteTempPrefix(targetPath)}${pid}.${tempSequence.toString(36)}.${random}`;
+};
+const bytesEqual = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
+const targetHasContent = (fs, targetPath, content) => typeof content === "string"
+    ? Effect.map(fs.readFileString(targetPath), (current) => current === content)
+    : Effect.map(fs.readFile(targetPath), (current) => bytesEqual(current, content));
+/**
+ * Atomically replace `targetPath` with `content` via a same-directory temp
+ * file and rename. Failures at each step are mapped by the caller, so error
+ * codes, details, and suggestions stay call-site specific.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const writeFileAtomic = (fs, options) => Effect.gen(function* () {
+    const { content, mapError, targetPath } = options;
+    const tempPath = makeTempPath(targetPath);
+    const fail = (step) => (cause) => mapError({ step, targetPath, tempPath, cause });
+    if (options.skipIfUnchanged === "fail-on-read-error") {
+        const exists = yield* fs.exists(targetPath).pipe(Effect.mapError(fail("check-target")));
+        if (exists) {
+            const unchanged = yield* targetHasContent(fs, targetPath, content).pipe(Effect.mapError(fail("read-target")));
+            if (unchanged)
+                return "skipped";
+        }
+    }
+    else if (options.skipIfUnchanged === "ignore-read-errors") {
+        const unchanged = yield* targetHasContent(fs, targetPath, content).pipe(Effect.option);
+        if (Option.isSome(unchanged) && unchanged.value)
+            return "skipped";
+    }
+    yield* Effect.gen(function* () {
+        yield* (typeof content === "string"
+            ? fs.writeFileString(tempPath, content)
+            : fs.writeFile(tempPath, content)).pipe(Effect.mapError(fail("write-temp")));
+        if (options.removeTargetBeforeRename === true) {
+            yield* fs.remove(targetPath).pipe(Effect.ignore);
+        }
+        yield* fs.rename(tempPath, targetPath).pipe(Effect.mapError(fail("rename")));
+    }).pipe(Effect.ensuring(fs.remove(tempPath, { force: true }).pipe(Effect.ignore)));
+    return "written";
+});
+//# sourceMappingURL=atomic-write.js.map

package/dist/src/utils/environment.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Private environment and home-directory helpers for workspace-state.
+ *
+ * Deliberately duplicated from the CLI-destined environment module: the
+ * kernel may not depend on application utilities, and these helpers are
+ * within the sanctioned duplication budget for small pure functions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+/** Read an optional env var. Centralized access point for process.env. */
+export declare const envOption: (name: string) => Effect.Effect<Option.Option<string>>;
+/** Resolve the user's home directory. */
+export declare const getHome: Effect.Effect<string, never, never>;
+//# sourceMappingURL=environment.d.ts.map

package/dist/src/utils/environment.js

@@ -0,0 +1,19 @@
+/**
+ * Private environment and home-directory helpers for workspace-state.
+ *
+ * Deliberately duplicated from the CLI-destined environment module: the
+ * kernel may not depend on application utilities, and these helpers are
+ * within the sanctioned duplication budget for small pure functions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as os from "node:os";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+// eslint-disable-next-line no-restricted-properties -- Centralized env var access point; all callers use these helpers
+const readEnv = (name) => process.env[name];
+/** Read an optional env var. Centralized access point for process.env. */
+export const envOption = (name) => Effect.sync(() => Option.fromUndefinedOr(readEnv(name)));
+/** Resolve the user's home directory. */
+export const getHome = Effect.sync(() => os.homedir());
+//# sourceMappingURL=environment.js.map

package/dist/src/utils/path-safety.d.ts

@@ -0,0 +1,25 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { type AbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+/**
+ * Validates that a resolved target path stays within a base directory.
+ * Uses path separator boundary check to prevent prefix false positives.
+ */
+export declare const isPathSafe: (path: Path.Path, base: string, target: string) => boolean;
+/**
+ * Resolve `target` and return it only when it stays inside `base`.
+ */
+export declare const safeChildPath: (base: AbsolutePath, target: string) => Effect.Effect<Option.Option<AbsolutePath>, never, Path.Path>;
+declare const PathTraversalDetected_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: "PathTraversalDetected";
+} & Readonly<A>;
+/** A resolved path escaped its workspace base directory. */
+export declare class PathTraversalDetected extends PathTraversalDetected_base<{
+    readonly path: string;
+}> {
+}
+/** Fail with `PathTraversalDetected` when `targetPath` escapes `baseDir`. */
+export declare const validatePathSafety: (path: Path.Path, baseDir: string, targetPath: string) => Effect.Effect<void, PathTraversalDetected>;
+export {};
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/src/utils/path-safety.js

@@ -0,0 +1,34 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { makeAbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+/**
+ * Validates that a resolved target path stays within a base directory.
+ * Uses path separator boundary check to prevent prefix false positives.
+ */
+export const isPathSafe = (path, base, target) => {
+    const resolvedBase = path.resolve(base);
+    const resolvedTarget = path.resolve(target);
+    return resolvedTarget === resolvedBase || resolvedTarget.startsWith(resolvedBase + path.sep);
+};
+/**
+ * Resolve `target` and return it only when it stays inside `base`.
+ */
+export const safeChildPath = (base, target) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const resolvedBase = path.resolve(base);
+    const resolvedTarget = path.isAbsolute(target)
+        ? path.resolve(target)
+        : path.resolve(resolvedBase, target);
+    const safe = resolvedTarget === resolvedBase || resolvedTarget.startsWith(resolvedBase + path.sep);
+    return safe ? Option.some(makeAbsolutePath(path, resolvedTarget)) : Option.none();
+});
+/** A resolved path escaped its workspace base directory. */
+export class PathTraversalDetected extends Data.TaggedError("PathTraversalDetected") {
+}
+/** Fail with `PathTraversalDetected` when `targetPath` escapes `baseDir`. */
+export const validatePathSafety = (path, baseDir, targetPath) => isPathSafe(path, baseDir, targetPath)
+    ? Effect.void
+    : new PathTraversalDetected({ path: targetPath });
+//# sourceMappingURL=path-safety.js.map

package/dist/src/utils/resolve-parent-symlinks.d.ts

@@ -0,0 +1,16 @@
+import type { PlatformError } from "effect/PlatformError";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+/**
+ * Resolves the parent directory of a path through symlinks while
+ * preserving the final path component (basename).
+ *
+ * Needed for computing correct relative symlink paths when parent
+ * directories may themselves be symlinks. Missing parent directories are
+ * preserved below the nearest existing ancestor, whose real path is used as
+ * the common base. This also handles platform aliases such as macOS `/tmp` →
+ * `/private/tmp` before the link parent has been created.
+ */
+export declare const resolveParentSymlinks: (filePath: string) => Effect.Effect<string, PlatformError, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=resolve-parent-symlinks.d.ts.map

package/dist/src/utils/resolve-parent-symlinks.js

@@ -0,0 +1,36 @@
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+/**
+ * Resolves the parent directory of a path through symlinks while
+ * preserving the final path component (basename).
+ *
+ * Needed for computing correct relative symlink paths when parent
+ * directories may themselves be symlinks. Missing parent directories are
+ * preserved below the nearest existing ancestor, whose real path is used as
+ * the common base. This also handles platform aliases such as macOS `/tmp` →
+ * `/private/tmp` before the link parent has been created.
+ */
+export const resolveParentSymlinks = (filePath) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const p = yield* Path.Path;
+    const basename = p.basename(filePath);
+    const missingParents = [];
+    let current = p.dirname(filePath);
+    while (true) {
+        const resolved = yield* fs.realPath(current).pipe(Effect.option);
+        if (Option.isSome(resolved)) {
+            return p.join(resolved.value, ...missingParents, basename);
+        }
+        const parent = p.dirname(current);
+        if (parent === current) {
+            return yield* fs
+                .realPath(current)
+                .pipe(Effect.map((resolvedRoot) => p.join(resolvedRoot, ...missingParents, basename)));
+        }
+        missingParents.unshift(p.basename(current));
+        current = parent;
+    }
+});
+//# sourceMappingURL=resolve-parent-symlinks.js.map

package/dist/src/workspace/accepted-canonical-ref.d.ts

@@ -0,0 +1,58 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import type { ExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/extension-ref";
+import { AcceptedResolutionMissing, InlineExtensionSourceMissing, SupersededCanonicalRemovalFailed, type PackageContentHashFailed, type WorkspaceSourceInvalid } from "./errors.js";
+import type { PathTraversalDetected } from "../utils/path-safety.js";
+import type { WorkspaceSnapshotError } from "./transaction.js";
+import { type LockEntryToRefError } from "./lock-entry-to-ref.js";
+import { type AcceptedExtensionResolution, type CanonicalObservation } from "./canonical-observation.js";
+import type { DesiredExtensionNode } from "./desired-state-graph.js";
+import type { WorkspaceLockfileReadFailure, WorkspaceMutationsService, WorkspaceStateReadFailure } from "./service-interface.js";
+interface AcceptedCanonicalRefArgs {
+    readonly workspace: WorkspaceMutationsService;
+    readonly type: DesiredExtensionNode["type"];
+    readonly name: string;
+}
+/** Every failure the accepted-canonical reconstruction functions can produce. */
+export type AcceptedCanonicalRefError = WorkspaceStateReadFailure | LockEntryToRefError | AcceptedResolutionMissing | InlineExtensionSourceMissing | WorkspaceSourceInvalid | PathTraversalDetected | PackageContentHashFailed;
+export interface AcceptedCanonicalObservation {
+    readonly desired: DesiredExtensionNode;
+    readonly accepted?: AcceptedExtensionResolution;
+    readonly observation: CanonicalObservation;
+}
+export interface UsableAcceptedCanonicalObservation extends AcceptedCanonicalObservation {
+    readonly observation: CanonicalObservation & {
+        readonly status: "usable";
+        readonly path: string;
+    };
+}
+export interface UsableAcceptedCanonical extends UsableAcceptedCanonicalObservation {
+    readonly ref: ExtensionRef;
+}
+/** Canonical package AXM may delete when removing desired state. Authored source is durable. */
+export declare const removableAcceptedCanonicalPath: (canonical: Option.Option<AcceptedCanonicalObservation>) => Option.Option<string>;
+/** Exact acquired canonical path reconstructed directly from accepted lock authority. */
+export declare const acceptedLockedCanonicalPath: (args: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<string>, WorkspaceLockfileReadFailure, Path.Path>;
+/**
+ * Capture exact cleanup for a superseded accepted package. The old path is
+ * read before the lock transition; the returned effect runs afterward and
+ * removes only that path when the replacement canonical path differs.
+ */
+export declare const prepareAcceptedCanonicalTransition: (args: AcceptedCanonicalRefArgs & {
+    readonly ref: ExtensionRef;
+}) => Effect.Effect<Effect.Effect<void, WorkspaceSnapshotError | SupersededCanonicalRemovalFailed>, WorkspaceLockfileReadFailure, FileSystem.FileSystem | Path.Path>;
+/** Reconstruct a ref directly from accepted lock authority without desired reachability. */
+export declare const acceptedLockedResolutionRef: (args: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<ExtensionRef>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
+/**
+ * Reconstruct the immutable source reference recorded for a desired extension,
+ * even when its canonical materialization is absent or divergent.
+ */
+export declare const acceptedResolutionRef: (args: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<ExtensionRef>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
+export declare const acceptedCanonicalObservation: ({ workspace, type, name, }: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<AcceptedCanonicalObservation>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
+export declare const usableAcceptedCanonicalObservation: (args: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<UsableAcceptedCanonicalObservation>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
+export declare const usableAcceptedCanonical: (args: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<UsableAcceptedCanonical>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
+export declare const usableAcceptedCanonicalRef: (args: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<ExtensionRef>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
+export {};
+//# sourceMappingURL=accepted-canonical-ref.d.ts.map