@agentxm/extension-materialization 0.28.14-preview.1789139351.5cd4595aa

package/dist/src/extensions/canonical-directory.js

@@ -0,0 +1,210 @@
+/**
+ * Canonical package directory machinery: sibling staging/swap replacement,
+ * interrupted-swap recovery, create-only publication, reuse decisions, and
+ * external (non-registry) package materialization.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { stripFileProtocol } from "@agentxm/registry-client";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { protectCreatedAncestors, protectWorkspacePath, } from "@agentxm/workspace-transactions";
+import { recordFootprint } from "@agentxm/workspace-transactions";
+import { shouldReuseCanonicalInstall } from "./canonical-reuse.js";
+import { copyExtensionDirectory } from "./copy-directory.js";
+import { validatePathSafety } from "@agentxm/workspace-state";
+import { CanonicalPackageProbeFailed, CreateDestinationExists, PackageCopyFailed, PackageMaterializationFailed, StagedPackageInvalid, } from "./errors.js";
+import { PathTraversalDetected } from "@agentxm/workspace-state";
+import { computeMaterializedTreeIntegrity, } from "@agentxm/workspace-state";
+export const canonicalMaterializationPaths = (canonicalPath) => ({
+    stagingPath: `${canonicalPath}.axm-staging`,
+    backupPath: `${canonicalPath}.axm-backup`,
+});
+/**
+ * Resolve the sibling replacement state left by an interrupted swap.
+ *
+ * `replaceCanonicalDirectory` never populates the canonical path in place: it
+ * fills a sibling staging directory, then commits with two same-parent renames.
+ * So the canonical path only ever holds a whole tree, and the pair of
+ * (canonical present, backup present) names the interruption point exactly:
+ *
+ * - backup, no canonical — died between the two renames; restore the backup.
+ * - backup and canonical — the second rename landed; the backup is superseded.
+ * - no backup — nothing was swapped; only staging needs discarding.
+ */
+const recoverInterruptedReplacement = (canonicalPath, fs) => Effect.gen(function* () {
+    const { stagingPath, backupPath } = canonicalMaterializationPaths(canonicalPath);
+    const canonicalExists = yield* fs.exists(canonicalPath);
+    const backupExists = yield* fs.exists(backupPath);
+    if (backupExists && !canonicalExists) {
+        yield* fs.rename(backupPath, canonicalPath);
+    }
+    else if (backupExists) {
+        yield* fs.remove(backupPath, { recursive: true, force: true });
+    }
+    yield* fs.remove(stagingPath, { recursive: true, force: true });
+}).pipe(Effect.mapError((cause) => new PackageMaterializationFailed({ path: canonicalPath, step: "recover", cause })));
+/** Recover or clean sibling replacement state before any fallible source work. */
+export const recoverCanonicalDirectory = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const { stagingPath, backupPath } = canonicalMaterializationPaths(args.canonicalPath);
+    yield* validatePathSafety(path, args.baseDir, args.canonicalPath);
+    yield* validatePathSafety(path, args.baseDir, stagingPath);
+    yield* validatePathSafety(path, args.baseDir, backupPath);
+    yield* recoverInterruptedReplacement(args.canonicalPath, fs);
+});
+const validateRequiredPackageFiles = (stagingPath, requiredFiles) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    yield* Effect.forEach(requiredFiles, (relativePath) => Effect.gen(function* () {
+        const filePath = path.join(stagingPath, relativePath);
+        yield* validatePathSafety(path, stagingPath, filePath);
+        const info = yield* fs
+            .stat(filePath)
+            .pipe(Effect.mapError((cause) => new StagedPackageInvalid({ file: relativePath, kind: "missing", cause })));
+        if (info.type !== "File") {
+            return yield* new StagedPackageInvalid({ file: relativePath, kind: "not-file" });
+        }
+    }), { discard: true });
+});
+/**
+ * Publish a complete canonical tree from a sibling staging directory. Recovery
+ * restores a prior tree left in the sibling backup by abrupt process death;
+ * incomplete staging is never made eligible for reuse.
+ */
+export const replaceCanonicalDirectoryWithInspection = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const { stagingPath, backupPath } = canonicalMaterializationPaths(args.canonicalPath);
+    yield* recoverCanonicalDirectory(args);
+    yield* protectCreatedAncestors(fs, path, path.dirname(args.canonicalPath));
+    yield* fs.makeDirectory(path.dirname(args.canonicalPath), { recursive: true }).pipe(Effect.mapError((cause) => new PackageMaterializationFailed({
+        path: args.canonicalPath,
+        step: "prepare-parent",
+        cause,
+    })));
+    const inspection = yield* Effect.gen(function* () {
+        yield* fs.makeDirectory(stagingPath, { recursive: true }).pipe(Effect.mapError((cause) => new PackageMaterializationFailed({
+            path: stagingPath,
+            step: "prepare-staging",
+            cause,
+        })));
+        yield* args.populate(stagingPath);
+        if (args.validate !== undefined)
+            yield* args.validate(stagingPath);
+        return yield* args.inspect(stagingPath);
+    }).pipe(Effect.tapError(() => fs.remove(stagingPath, { recursive: true, force: true }).pipe(Effect.ignore)));
+    yield* protectWorkspacePath(args.canonicalPath);
+    const hadCanonical = yield* fs
+        .exists(args.canonicalPath)
+        .pipe(Effect.mapError((cause) => new PackageMaterializationFailed({ path: args.canonicalPath, step: "inspect", cause })));
+    yield* Effect.uninterruptible(Effect.gen(function* () {
+        if (hadCanonical)
+            yield* fs.rename(args.canonicalPath, backupPath);
+        yield* fs
+            .rename(stagingPath, args.canonicalPath)
+            .pipe(Effect.tapError(() => hadCanonical
+            ? fs.rename(backupPath, args.canonicalPath).pipe(Effect.ignore)
+            : Effect.void));
+        yield* fs.remove(backupPath, { recursive: true, force: true });
+    })).pipe(Effect.mapError((cause) => new PackageMaterializationFailed({ path: args.canonicalPath, step: "replace", cause })));
+    yield* recordFootprint({
+        path: args.canonicalPath,
+        change: hadCanonical ? "modified" : "created",
+    });
+    return { canonicalPath: args.canonicalPath, inspection };
+});
+export const replaceCanonicalDirectory = (args) => replaceCanonicalDirectoryWithInspection({
+    ...args,
+    inspect: () => Effect.void,
+}).pipe(Effect.map(({ canonicalPath }) => canonicalPath));
+/**
+ * Publish one create-only authored package without ever populating its
+ * canonical directory in place. Interrupted sibling state is resolved before
+ * the collision check while the caller holds the workspace mutation lock.
+ */
+export const createCanonicalDirectory = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* recoverCanonicalDirectory(args);
+    const exists = yield* fs.exists(args.canonicalPath).pipe(Effect.mapError((cause) => new PackageMaterializationFailed({
+        path: args.canonicalPath,
+        step: "inspect-create-destination",
+        cause,
+    })));
+    if (exists) {
+        return yield* new CreateDestinationExists({
+            subject: args.subject,
+            path: args.canonicalPath,
+        });
+    }
+    return yield* replaceCanonicalDirectory({
+        baseDir: args.baseDir,
+        canonicalPath: args.canonicalPath,
+        populate: args.populate,
+        validate: (stagingPath) => validateRequiredPackageFiles(stagingPath, args.requiredFiles ?? []).pipe(Effect.andThen(args.validate === undefined ? Effect.void : args.validate(stagingPath))),
+    });
+});
+/** Preserve an existing external canonical tree unless refresh was explicitly requested. */
+export const canReuseExternalPackage = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* recoverInterruptedReplacement(args.installedPath, fs);
+    const canonicalExists = yield* fs.exists(args.installedPath).pipe(Effect.mapError((cause) => new CanonicalPackageProbeFailed({
+        detail: args.existsFailureDetail(args.installedPath),
+        cause,
+    })));
+    return canonicalExists && !args.force;
+});
+/**
+ * Decide whether the installed tree already satisfies the requested ref, so no
+ * archive needs to be fetched or written.
+ *
+ * Callers that stage into a temporary directory must call this against the
+ * canonical installed path before staging: the decision is about the installed
+ * tree, while the registry materialization only answers where bytes go.
+ */
+export const canReuseInstalledPackage = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* recoverInterruptedReplacement(args.installedPath, fs);
+    const canonicalExists = yield* fs.exists(args.installedPath).pipe(Effect.mapError((cause) => new CanonicalPackageProbeFailed({
+        detail: args.existsFailureDetail(args.installedPath),
+        cause,
+    })));
+    return shouldReuseCanonicalInstall({
+        canonicalExists,
+        force: args.force,
+        hasIntegrity: args.hasIntegrity,
+        refVersion: args.refVersion,
+        lockedVersion: args.lockedVersion,
+    });
+});
+export const materializeExternalPackageWithTreeIntegrity = (args) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    yield* validatePathSafety(path, args.baseDir, args.canonicalPath);
+    const sourcePath = stripFileProtocol(args.sourceLocation);
+    const isSelfCopy = path.resolve(sourcePath) === path.resolve(args.canonicalPath);
+    if (isSelfCopy) {
+        return {
+            canonicalPath: args.canonicalPath,
+            treeIntegrity: yield* computeMaterializedTreeIntegrity(args.canonicalPath),
+        };
+    }
+    const result = yield* replaceCanonicalDirectoryWithInspection({
+        baseDir: args.baseDir,
+        canonicalPath: args.canonicalPath,
+        populate: (stagingPath) => copyExtensionDirectory(sourcePath, stagingPath).pipe(Effect.mapError((cause) => new PackageCopyFailed({
+            severity: args.copyFailureCode,
+            detail: args.copyFailureDetail(args.canonicalPath),
+            cause,
+        }))),
+        ...(args.validate === undefined ? {} : { validate: args.validate }),
+        inspect: computeMaterializedTreeIntegrity,
+    });
+    return {
+        canonicalPath: result.canonicalPath,
+        treeIntegrity: result.inspection,
+    };
+});
+export const materializeExternalPackage = (args) => materializeExternalPackageWithTreeIntegrity(args).pipe(Effect.map(({ canonicalPath }) => canonicalPath));
+//# sourceMappingURL=canonical-directory.js.map

package/dist/src/extensions/canonical-reuse.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Reuse decision for registry canonical trees.
+ *
+ * Archive integrity is a download-time supply-chain guarantee: the SRI hash
+ * in the lockfile is verified against fetched archive bytes before
+ * extraction. After install, canonical content is workspace-owned —
+ * content-preserving workspace tools (formatters, line-ending
+ * normalization) may rewrite installed files, and a no-op install must not
+ * revert them by re-extracting the archive.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+/**
+ * Decide whether a registry install may reuse the existing canonical tree
+ * instead of re-downloading and re-extracting the archive.
+ *
+ * `canonicalExists` must describe the canonical installed tree. Probing a
+ * staging destination instead makes it permanently false, which silently
+ * defeats the reuse contract above; prefer `canReuseInstalledPackage`, which
+ * takes the installed path by name.
+ *
+ * - `force` always re-materializes (the internal repair path for `--reinstall` installs
+ *   and lint autofix reinstalls).
+ * - Refs without integrity (synthetic refs from publish) reuse an existing
+ *   tree, preserving the historical publish behavior.
+ * - Refs with integrity reuse the tree only when the lockfile already pins
+ *   the requested version, so version changes still re-materialize.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const shouldReuseCanonicalInstall: (args: {
+    /** The canonical extension directory already exists on disk. */
+    readonly canonicalExists: boolean;
+    /** Caller demanded an unconditional re-materialization. */
+    readonly force: boolean;
+    /** The ref carries a pinned archive integrity (registry-resolved). */
+    readonly hasIntegrity: boolean;
+    /** Exact version requested by the ref being installed. */
+    readonly refVersion: string | undefined;
+    /** Resolved version recorded in the current lockfile entry, when any. */
+    readonly lockedVersion: string | undefined;
+}) => boolean;
+//# sourceMappingURL=canonical-reuse.d.ts.map

package/dist/src/extensions/canonical-reuse.js

@@ -0,0 +1,38 @@
+/**
+ * Reuse decision for registry canonical trees.
+ *
+ * Archive integrity is a download-time supply-chain guarantee: the SRI hash
+ * in the lockfile is verified against fetched archive bytes before
+ * extraction. After install, canonical content is workspace-owned —
+ * content-preserving workspace tools (formatters, line-ending
+ * normalization) may rewrite installed files, and a no-op install must not
+ * revert them by re-extracting the archive.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+/**
+ * Decide whether a registry install may reuse the existing canonical tree
+ * instead of re-downloading and re-extracting the archive.
+ *
+ * `canonicalExists` must describe the canonical installed tree. Probing a
+ * staging destination instead makes it permanently false, which silently
+ * defeats the reuse contract above; prefer `canReuseInstalledPackage`, which
+ * takes the installed path by name.
+ *
+ * - `force` always re-materializes (the internal repair path for `--reinstall` installs
+ *   and lint autofix reinstalls).
+ * - Refs without integrity (synthetic refs from publish) reuse an existing
+ *   tree, preserving the historical publish behavior.
+ * - Refs with integrity reuse the tree only when the lockfile already pins
+ *   the requested version, so version changes still re-materialize.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const shouldReuseCanonicalInstall = (args) => {
+    if (!args.canonicalExists || args.force)
+        return false;
+    if (!args.hasIntegrity)
+        return true;
+    return args.refVersion !== undefined && args.refVersion === args.lockedVersion;
+};
+//# sourceMappingURL=canonical-reuse.js.map

package/dist/src/extensions/copy-directory.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared extension utilities.
+ *
+ * Cross-cutting utilities used by multiple extension types.
+ * Promoted from skills-specific modules to avoid cross-feature dependencies.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { PlatformError } from "effect/PlatformError";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+/**
+ * Options for {@link copyExtensionDirectory}.
+ */
+export type CopyExtensionDirectoryOptions = {
+    /**
+     * When true, omit entries that should not appear in a fanned-out agent
+     * artifact: `README.md`, `metadata.json`, and `_`-prefixed names (`.git` is
+     * always omitted).
+     *
+     * Defaults to `false` — a faithful copy of the source, matching what
+     * `publish` packages into the archive. Canonical materialization must use
+     * the faithful copy so realigning a lockfile does not strip authored files
+     * (e.g. `README.md`) that the published package contains.
+     */
+    readonly forAgentArtifact?: boolean;
+};
+export type CopyExtensionDirectoryFailureDetails = {
+    readonly sourcePath: string;
+    readonly targetPath: string;
+    readonly subject?: string;
+    readonly sourceExists?: boolean;
+};
+export declare const formatCopyExtensionDirectoryFailure: ({ sourcePath, targetPath, subject, sourceExists, }: CopyExtensionDirectoryFailureDetails) => string;
+/**
+ * Recursively copies an extension directory from `src` to `dest`.
+ *
+ * By default this is a faithful copy of every entry except `.git`, used to
+ * materialize the canonical extension store from a package archive or local
+ * source. Pass `{ forAgentArtifact: true }` to also omit non-artifact entries
+ * when fanning the canonical copy out to an agent directory (see
+ * {@link CopyExtensionDirectoryOptions}).
+ *
+ * Symlinks are dereferenced (file content is copied, not the link).
+ * Directory entries are copied concurrently.
+ */
+export declare const copyExtensionDirectory: (src: string, dest: string, options?: CopyExtensionDirectoryOptions) => Effect.Effect<void, PlatformError, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=copy-directory.d.ts.map

package/dist/src/extensions/copy-directory.js

@@ -0,0 +1,78 @@
+/**
+ * Shared extension utilities.
+ *
+ * Cross-cutting utilities used by multiple extension types.
+ * Promoted from skills-specific modules to avoid cross-feature dependencies.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+// -----------------------------------------------------------------------------
+// Path Safety Validation
+// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Extension Directory Copy
+// -----------------------------------------------------------------------------
+/**
+ * VCS state is never copied in any copy mode. It does not belong to authored
+ * package content, and copying a `.git` directory from a git-hosted or local
+ * source would only bloat the canonical copy.
+ */
+const ALWAYS_EXCLUDED_NAMES = new Set([".git"]);
+/**
+ * Entries additionally omitted from an agent-facing artifact: human files,
+ * AXM-managed install metadata, and authoring-private (`_`-prefixed) files.
+ * These belong in the canonical copy (they are part of the published package)
+ * but are trimmed when fanning out to an agent directory.
+ */
+const AGENT_ARTIFACT_EXCLUDED_NAMES = new Set(["README.md", "metadata.json"]);
+const isExcluded = (name, forAgentArtifact) => {
+    if (ALWAYS_EXCLUDED_NAMES.has(name))
+        return true;
+    if (!forAgentArtifact)
+        return false;
+    return AGENT_ARTIFACT_EXCLUDED_NAMES.has(name) || name.startsWith("_");
+};
+const copyEntry = (src, dest, fs, path, forAgentArtifact) => Effect.gen(function* () {
+    // Read through symlinks (stat follows symlinks by default)
+    const info = yield* fs.stat(src);
+    if (info.type === "Directory") {
+        yield* copyDir(src, dest, fs, path, forAgentArtifact);
+    }
+    else {
+        // Copy file content — readFile follows symlinks, giving us dereferenced content
+        const content = yield* fs.readFile(src);
+        yield* fs.makeDirectory(path.dirname(dest), { recursive: true });
+        yield* fs.writeFile(dest, content);
+    }
+});
+const copyDir = (src, dest, fs, path, forAgentArtifact) => Effect.gen(function* () {
+    yield* fs.makeDirectory(dest, { recursive: true });
+    const entries = yield* fs.readDirectory(src);
+    yield* Effect.forEach(entries.filter((name) => !isExcluded(name, forAgentArtifact)), (name) => copyEntry(path.join(src, name), path.join(dest, name), fs, path, forAgentArtifact), { concurrency: "unbounded" });
+});
+export const formatCopyExtensionDirectoryFailure = ({ sourcePath, targetPath, subject = "extension files", sourceExists, }) => {
+    const missingSource = sourceExists === false ? "; source does not exist" : "";
+    return `Failed to copy ${subject} from ${sourcePath} to ${targetPath}${missingSource}`;
+};
+/**
+ * Recursively copies an extension directory from `src` to `dest`.
+ *
+ * By default this is a faithful copy of every entry except `.git`, used to
+ * materialize the canonical extension store from a package archive or local
+ * source. Pass `{ forAgentArtifact: true }` to also omit non-artifact entries
+ * when fanning the canonical copy out to an agent directory (see
+ * {@link CopyExtensionDirectoryOptions}).
+ *
+ * Symlinks are dereferenced (file content is copied, not the link).
+ * Directory entries are copied concurrently.
+ */
+export const copyExtensionDirectory = (src, dest, options) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    yield* copyDir(src, dest, fs, path, options?.forAgentArtifact ?? false);
+});
+//# sourceMappingURL=copy-directory.js.map

package/dist/src/extensions/errors.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Typed failure family for canonical package materialization: staging, swap,
+ * copy, integrity, and the shared lifecycle closure postconditions. Fields are
+ * domain facts; the application error boundary owns rendering, codes, and
+ * suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { PathTraversalDetected } from "@agentxm/workspace-state";
+declare const PackageMaterializationFailed_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: "PackageMaterializationFailed";
+} & Readonly<A>;
+/** Canonical package staging/swap machinery failed at a filesystem step. */
+export declare class PackageMaterializationFailed extends PackageMaterializationFailed_base<{
+    /** The canonical path for most steps; the staging path for `prepare-staging`. */
+    readonly path: string;
+    readonly step: "recover" | "prepare-parent" | "prepare-staging" | "inspect" | "replace" | "inspect-create-destination";
+    readonly cause: unknown;
+}> {
+}
+declare const StagedPackageInvalid_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: "StagedPackageInvalid";
+} & Readonly<A>;
+/** A staged package tree is missing or misshapes a type-required file. */
+export declare class StagedPackageInvalid extends StagedPackageInvalid_base<{
+    readonly file: string;
+    readonly kind: "missing" | "not-file";
+    readonly cause?: unknown;
+}> {
+}
+declare const CanonicalPackageProbeFailed_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: "CanonicalPackageProbeFailed";
+} & Readonly<A>;
+/**
+ * Probing installed canonical state failed. `detail` carries the caller's
+ * fact sentence verbatim; each call site owns its subject wording.
+ */
+export declare class CanonicalPackageProbeFailed extends CanonicalPackageProbeFailed_base<{
+    readonly detail: string;
+    readonly cause: unknown;
+}> {
+}
+declare const PackageCopyFailed_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: "PackageCopyFailed";
+} & Readonly<A>;
+/**
+ * Copying package content into staging failed. `severity` records the caller's
+ * decision about whether the failure indicts the source content (`validation`)
+ * or the machinery (`internal`).
+ */
+export declare class PackageCopyFailed extends PackageCopyFailed_base<{
+    readonly severity: "internal" | "validation";
+    readonly detail: string;
+    readonly cause: unknown;
+}> {
+}
+declare const ArchiveIntegrityMismatch_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: "ArchiveIntegrityMismatch";
+} & Readonly<A>;
+/** The fetched archive did not match the accepted integrity pin. */
+export declare class ArchiveIntegrityMismatch extends ArchiveIntegrityMismatch_base<{
+    /** The caller's subject sentence, e.g. `Integrity mismatch for name@1.0.0`. */
+    readonly subject: string;
+}> {
+}
+declare const LifecyclePostconditionViolated_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: "LifecyclePostconditionViolated";
+} & Readonly<A>;
+/** A lifecycle transition committed but its observable postcondition failed. */
+export declare class LifecyclePostconditionViolated extends LifecyclePostconditionViolated_base<{
+    readonly postcondition: "install-observable" | "install-declared" | "new-observable" | "new-declared" | "materialize-observable" | "uninstall-remains-declared" | "uninstall-observed-state";
+    readonly targetType: string;
+    readonly targetName: string;
+}> {
+}
+declare const ScaffoldedExtensionUnresolved_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: "ScaffoldedExtensionUnresolved";
+} & Readonly<A>;
+/** A newly scaffolded extension could not be resolved from its workspace source. */
+export declare class ScaffoldedExtensionUnresolved extends ScaffoldedExtensionUnresolved_base<{
+    readonly targetType: string;
+    readonly targetName: string;
+}> {
+}
+declare const CreateDestinationExists_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: "CreateDestinationExists";
+} & Readonly<A>;
+/** A create-only operation found existing state at its destination path. */
+export declare class CreateDestinationExists extends CreateDestinationExists_base<{
+    readonly subject: string;
+    readonly path: string;
+}> {
+}
+/** Every failure canonical materialization and the closure recipes construct. */
+export type MaterializationError = PackageMaterializationFailed | StagedPackageInvalid | CanonicalPackageProbeFailed | PackageCopyFailed | ArchiveIntegrityMismatch | CreateDestinationExists | PathTraversalDetected | LifecyclePostconditionViolated | ScaffoldedExtensionUnresolved;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/extensions/errors.js

@@ -0,0 +1,42 @@
+/**
+ * Typed failure family for canonical package materialization: staging, swap,
+ * copy, integrity, and the shared lifecycle closure postconditions. Fields are
+ * domain facts; the application error boundary owns rendering, codes, and
+ * suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { PathTraversalDetected } from "@agentxm/workspace-state";
+import * as Data from "effect/Data";
+/** Canonical package staging/swap machinery failed at a filesystem step. */
+export class PackageMaterializationFailed extends Data.TaggedError("PackageMaterializationFailed") {
+}
+/** A staged package tree is missing or misshapes a type-required file. */
+export class StagedPackageInvalid extends Data.TaggedError("StagedPackageInvalid") {
+}
+/**
+ * Probing installed canonical state failed. `detail` carries the caller's
+ * fact sentence verbatim; each call site owns its subject wording.
+ */
+export class CanonicalPackageProbeFailed extends Data.TaggedError("CanonicalPackageProbeFailed") {
+}
+/**
+ * Copying package content into staging failed. `severity` records the caller's
+ * decision about whether the failure indicts the source content (`validation`)
+ * or the machinery (`internal`).
+ */
+export class PackageCopyFailed extends Data.TaggedError("PackageCopyFailed") {
+}
+/** The fetched archive did not match the accepted integrity pin. */
+export class ArchiveIntegrityMismatch extends Data.TaggedError("ArchiveIntegrityMismatch") {
+}
+/** A lifecycle transition committed but its observable postcondition failed. */
+export class LifecyclePostconditionViolated extends Data.TaggedError("LifecyclePostconditionViolated") {
+}
+/** A newly scaffolded extension could not be resolved from its workspace source. */
+export class ScaffoldedExtensionUnresolved extends Data.TaggedError("ScaffoldedExtensionUnresolved") {
+}
+/** A create-only operation found existing state at its destination path. */
+export class CreateDestinationExists extends Data.TaggedError("CreateDestinationExists") {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/extensions/materializable-from-disk.d.ts

@@ -0,0 +1,37 @@
+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 { CanonicalPackageProbeFailed } from "./errors.js";
+import type { PathTraversalDetected } from "@agentxm/workspace-state";
+import type { PackageContentHashFailed, WorkspaceSourceInvalid } from "@agentxm/workspace-state";
+import type { LockEntryToRefError } from "@agentxm/workspace-state";
+import type { WorkspaceSettingsReadFailure } from "@agentxm/workspace-state";
+import type { SkillLockEntry } from "@agentxm/workspace-state";
+import type { ConfiguredRecordRow } from "@agentxm/workspace-state";
+import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import type { PackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
+import type { SourceHostConfig } from "@agentxm/workspace-state";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+import type { WorkspaceLayout } from "@agentxm/workspace-state";
+type DiskRefError = LockEntryToRefError | WorkspaceSourceInvalid | PathTraversalDetected | PackageContentHashFailed | CanonicalPackageProbeFailed;
+interface DiskRefEnv {
+    readonly fs: FileSystem.FileSystem;
+    readonly path: Path.Path;
+    readonly baseDir: string;
+    readonly scope: WorkspaceScope;
+    readonly layout: WorkspaceLayout;
+}
+interface SkillDiskAcceptedResolutionContext {
+    readonly lockEntries: Readonly<Record<string, SkillLockEntry>>;
+    readonly getConfiguredSources: () => Effect.Effect<ReadonlyArray<SourceHostConfig>, WorkspaceSettingsReadFailure>;
+    readonly getConfiguredSourceByName: (name: string) => Effect.Effect<Option.Option<SourceHostConfig>, WorkspaceSettingsReadFailure>;
+}
+export declare const configuredSkillsToDiskRefs: (env: DiskRefEnv, configured: Readonly<Record<string, ConfiguredRecordRow>>, accepted?: SkillDiskAcceptedResolutionContext) => Effect.Effect<ReadonlyArray<SkillExtensionRef>, DiskRefError>;
+export declare const configuredMcpServersToDiskRefs: (env: DiskRefEnv, configured: Readonly<Record<string, ConfiguredRecordRow>>) => Effect.Effect<ReadonlyArray<McpServerExtensionRef>, DiskRefError>;
+export declare const configuredSubagentsToDiskRefs: (env: DiskRefEnv, configured: Readonly<Record<string, ConfiguredRecordRow>>) => Effect.Effect<ReadonlyArray<SubagentExtensionRef>, DiskRefError>;
+export declare const configuredPacksToDiskRefs: (env: DiskRefEnv, configured: Readonly<Record<string, ConfiguredRecordRow>>) => Effect.Effect<ReadonlyArray<PackRef>, DiskRefError>;
+export {};
+//# sourceMappingURL=materializable-from-disk.d.ts.map