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

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2025-2026 AgentXM, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @agentxm/extension-materialization
+
+The AXM extension materialization capability: the per-extension-type manager
+contract and its seven implementations, canonical package staging with
+interrupted-swap recovery, registry-backed package materialization, and the
+install, uninstall, materialize, and authored-package closure recipes that
+compose them into plan steps.
+
+Managers keep their requirements explicit in `R`; a manager's materialization
+facts travel forward as return values rather than through captured state.
+`./live` composes the environment-backed manager layers and registers them as
+`workspace-projection` participants; `./testing` carries in-memory managers for
+feature tests. The surface is unsupported and may change in any release.
+Ordinary users should use the [`axm` CLI](https://axm.sh) instead.
+
+Part of the [AgentXM](https://agentxm.ai) toolchain.

package/dist/src/desired-state/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Failures deciding a retained re-materialization.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+declare const RetainedContentUnusable_base: Schema.Class<RetainedContentUnusable, Schema.TaggedStruct<"RetainedContentUnusable", {
+    readonly extensionType: Schema.String;
+    readonly name: Schema.String;
+    /** The canonical observation status that made restoration impossible. */
+    readonly status: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A retained transition asked to restore content the workspace accepted, and
+ * that content is not usable. The transition refuses rather than re-resolving
+ * the source, because re-acquiring is a different decision than restoring.
+ */
+export declare class RetainedContentUnusable extends RetainedContentUnusable_base {
+    get detail(): string;
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/desired-state/errors.js

@@ -0,0 +1,22 @@
+/**
+ * Failures deciding a retained re-materialization.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+/**
+ * A retained transition asked to restore content the workspace accepted, and
+ * that content is not usable. The transition refuses rather than re-resolving
+ * the source, because re-acquiring is a different decision than restoring.
+ */
+export class RetainedContentUnusable extends Schema.TaggedError()("RetainedContentUnusable", {
+    extensionType: Schema.String,
+    name: Schema.String,
+    /** The canonical observation status that made restoration impossible. */
+    status: Schema.String,
+}) {
+    get detail() {
+        return `Cannot rematerialize retained ${this.extensionType} ${this.name}: canonical content is ${this.status}`;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/desired-state/retained-materialization.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Re-materializing what desired state already accepted.
+ *
+ * A retained transition — re-enabling a Pack whose members were left on disk
+ * — must never re-resolve a source. The accepted resolution and the canonical
+ * content it names are the only inputs: if that content is not usable the
+ * transition refuses rather than silently reaching for the network, because
+ * "enable what you already have" and "acquire something new" are different
+ * decisions with different risk.
+ *
+ * This lives in the materialization capability, not in a feature, because
+ * both the workspace sync sweep and Pack activation re-materialize accepted
+ * content, and a feature may not import a peer feature.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { ExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/extension-ref";
+import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import { CodingAgentRepository, type ProjectionParticipantRequirements } from "@agentxm/workspace-projection";
+import { WorkspaceMutations, type DesiredExtensionNode } from "@agentxm/workspace-state";
+import type { JobStepResult, PlannedJobStep, StepFailure } from "@agentxm/workspace-operations";
+import { RetainedContentUnusable } from "./errors.js";
+import type { ExtensionManagerFailure } from "../errors.js";
+import { ExtensionManagers } from "../manager-registry.js";
+import type { ManagerRequirements } from "../manager-contract.js";
+import { type RecipeRequirements, type StepFailureAdapter } from "../extensions/operations.js";
+import { SubagentManager } from "../managers.js";
+/** Services a retained materialize step needs when it runs. */
+export type RetainedMaterializeRequirements = CodingAgentRepository | ExtensionManagers | ManagerRequirements | RecipeRequirements | SubagentManager | WorkspaceMutations;
+/**
+ * How an MCP server member is re-projected. MCP servers are realized into
+ * each agent's native configuration rather than into a canonical tree, so the
+ * caller hands in the install operation it already owns.
+ */
+export type RunRetainedMcpServerInstall<R> = (args: {
+    readonly ref: McpServerExtensionRef;
+}) => Effect.Effect<JobStepResult, StepFailure, R>;
+export interface RetainedMaterializeSteps<R> {
+    /** Every accepted ref the selection covers, whether or not it needs work. */
+    readonly refs: ReadonlyArray<ExtensionRef>;
+    readonly steps: ReadonlyArray<PlannedJobStep<R | RetainedMaterializeRequirements>>;
+}
+/** Every failure deciding retained re-materialization can surface. */
+export type RetainedMaterializeFailure = RetainedContentUnusable | ExtensionManagerFailure;
+/**
+ * Build the steps that bring the given desired nodes back to their accepted
+ * materialization. Nodes whose projections are already current contribute no
+ * step, so a retained transition that changes nothing plans nothing.
+ */
+export declare const collectRetainedMaterializeSteps: <R = never>(args: {
+    readonly nodes: ReadonlyArray<DesiredExtensionNode>;
+    readonly runMcpServerInstall: RunRetainedMcpServerInstall<R>;
+    readonly adapter: StepFailureAdapter;
+}) => Effect.Effect<RetainedMaterializeSteps<R>, RetainedMaterializeFailure, CodingAgentRepository | ExtensionManagers | FileSystem.FileSystem | Path.Path | ProjectionParticipantRequirements | SubagentManager | WorkspaceMutations>;
+//# sourceMappingURL=retained-materialization.d.ts.map

package/dist/src/desired-state/retained-materialization.js

@@ -0,0 +1,119 @@
+/**
+ * Re-materializing what desired state already accepted.
+ *
+ * A retained transition — re-enabling a Pack whose members were left on disk
+ * — must never re-resolve a source. The accepted resolution and the canonical
+ * content it names are the only inputs: if that content is not usable the
+ * transition refuses rather than silently reaching for the network, because
+ * "enable what you already have" and "acquire something new" are different
+ * decisions with different risk.
+ *
+ * This lives in the materialization capability, not in a feature, because
+ * both the workspace sync sweep and Pack activation re-materialize accepted
+ * content, and a feature may not import a peer feature.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+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 { CodingAgentRepository, isObservedMaterializationCurrent, } from "@agentxm/workspace-projection";
+import { acceptedCanonicalObservation, acceptedResolutionRef, isSourcedDesiredExtension, usableAcceptedCanonical, WorkspaceMutations, } from "@agentxm/workspace-state";
+import { RetainedContentUnusable } from "./errors.js";
+import { ExtensionManagers } from "../manager-registry.js";
+import { buildMaterializeOperation, targetFromRef, toStepKey, } from "../extensions/operations.js";
+import { SubagentManager } from "../managers.js";
+/**
+ * Build the steps that bring the given desired nodes back to their accepted
+ * materialization. Nodes whose projections are already current contribute no
+ * step, so a retained transition that changes nothing plans nothing.
+ */
+export const collectRetainedMaterializeSteps = (args) => Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const agentRepo = yield* CodingAgentRepository;
+    const managers = yield* ExtensionManagers;
+    const subagentManager = yield* SubagentManager;
+    const configuredAgentIds = yield* ws.getConfiguredAgents();
+    const selected = args.nodes
+        .filter(isSourcedDesiredExtension)
+        .filter((node) => node.enabled && node.type !== "pack");
+    const reconciled = yield* Effect.forEach(selected, (node) => Effect.gen(function* () {
+        const canonical = yield* acceptedCanonicalObservation({
+            workspace: ws,
+            type: node.type,
+            name: node.name,
+        });
+        const status = Option.isSome(canonical)
+            ? canonical.value.observation.status
+            : "missing-resolution";
+        const usable = status === "usable"
+            ? yield* usableAcceptedCanonical({
+                workspace: ws,
+                type: node.type,
+                name: node.name,
+            })
+            : Option.none();
+        const ref = Option.isSome(usable)
+            ? Option.some(usable.value.ref)
+            : yield* acceptedResolutionRef({
+                workspace: ws,
+                type: node.type,
+                name: node.name,
+            });
+        if (Option.isNone(ref)) {
+            return yield* new RetainedContentUnusable({
+                extensionType: node.type,
+                name: node.name,
+                status,
+            });
+        }
+        const current = yield* isObservedMaterializationCurrent({
+            workspace: ws,
+            node,
+            configuredAgentIds,
+            agents: agentRepo,
+            subagents: subagentManager,
+            resolvedRef: ref.value,
+            fs,
+            path,
+        });
+        return { node, ref: ref.value, materialize: status !== "usable" || !current };
+    }), { concurrency: "unbounded" });
+    const steps = reconciled
+        .filter(({ materialize }) => materialize)
+        .map(({ node, ref }) => {
+        if (ref.type === "mcp-server") {
+            const target = targetFromRef(ref);
+            return {
+                key: toStepKey(target),
+                label: `${node.type} ${node.name}`,
+                readiness: "ready",
+                run: args.runMcpServerInstall({ ref }),
+            };
+        }
+        const common = {
+            toStepFailure: args.adapter.toStepFailure,
+            label: `${node.type} ${node.name}`,
+            message: `Restored ${node.type} ${node.name}`,
+        };
+        switch (ref.type) {
+            case "skill":
+                return buildMaterializeOperation(managers.skill, { ...common, ref });
+            case "subagent":
+                return buildMaterializeOperation(managers.subagent, { ...common, ref });
+            case "rule":
+                return buildMaterializeOperation(managers.rule, { ...common, ref });
+            case "hook":
+                return buildMaterializeOperation(managers.hook, { ...common, ref });
+            case "knowledge":
+                return buildMaterializeOperation(managers.knowledge, { ...common, ref });
+            case "pack":
+                return buildMaterializeOperation(managers.pack, { ...common, ref });
+        }
+    });
+    return { refs: reconciled.map(({ ref }) => ref), steps };
+});
+//# sourceMappingURL=retained-materialization.js.map

package/dist/src/errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Failure vocabulary for extension materialization: the union of the per-type
+ * manager families, the canonical-materialization family, and the failures the
+ * managers surface from the capabilities underneath them — workspace state,
+ * transactions, projection, source resolution, and the registry client.
+ *
+ * Every member is typed. Nothing travels opaquely: a manager that calls a
+ * source host or the registry client keeps that integration's own failure in
+ * its channel, and the application boundary converts it once.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { FqnInvalidError } from "@agentxm/extension-model/unstable/extensions/fqn";
+import type { FrontmatterParseFailure, SubagentContentError } from "@agentxm/extension-content";
+import type { MaterializationError } from "./extensions/errors.js";
+import type { SourceAuthorityBlocked } from "@agentxm/extension-resolution";
+import type { SourceResolutionFailure } from "@agentxm/extension-sources";
+import type { RegistryClientFailure } from "@agentxm/registry-client";
+import type { InstructionMaintenanceFailed, ProjectionError } from "@agentxm/workspace-projection";
+import type { MaterializedTreeInvalid } from "@agentxm/workspace-state";
+import type { WorkspaceTransactionFailure, WorkspaceRestorationIncomplete } from "@agentxm/workspace-transactions";
+import type { WorkspaceStateMutationFailure, WorkspaceStateReadFailure } from "@agentxm/workspace-state";
+import type { CodingAgentFailure } from "@agentxm/agent-integration";
+import type { RuleManagerError } from "./rules/errors.js";
+import type { HookManagerError } from "./hooks/errors.js";
+import type { SubagentManagerError } from "./subagents/errors.js";
+import type { McpManagerError } from "./mcps/errors.js";
+import type { SkillManagerError } from "./skills/errors.js";
+import type { PackManagerError } from "./packs/errors.js";
+import type { KnowledgeManagerError } from "./knowledge/errors.js";
+import type { AcceptedResolutionMissing, CanonicalPathRemovalError, DesiredPackGraphIncomplete, InlineExtensionSourceMissing, InvalidAgentId, LockedSkillMissing, LockEntryEndpointConflict, LockEntryNameInvalid, LockEntrySourceMissing, LockEntrySourceTypeConflict, LockEntryUrlInvalid, PackageContentHashFailed, SettingsEntryMissing, SupersededCanonicalRemovalFailed, SymlinkCreationError, WorkspaceLayoutError, WorkspaceNotInitialized, WorkspaceSourceInvalid } from "@agentxm/workspace-state";
+import type { SkillDiscoveryRootInvalid, SubagentScanFailed } from "@agentxm/workspace-state";
+import type { LockfileResolvedVersionInvalid } from "@agentxm/workspace-state";
+/** Every typed failure the materialization modules construct themselves. */
+export type ExtensionMaterializationError = MaterializationError | SourceAuthorityBlocked | ProjectionError | InstructionMaintenanceFailed | RuleManagerError | HookManagerError | SubagentManagerError | McpManagerError | SkillManagerError | PackManagerError | KnowledgeManagerError | MaterializedTreeInvalid;
+/**
+ * Every failure an extension-type manager method may surface: the
+ * materialization families, the capability families underneath them, and the
+ * integration families their acquisition steps carry through.
+ */
+export type ExtensionManagerFailure = CodingAgentFailure | ExtensionMaterializationError | SourceResolutionFailure | RegistryClientFailure | WorkspaceStateReadFailure | WorkspaceStateMutationFailure | WorkspaceTransactionFailure | WorkspaceRestorationIncomplete | WorkspaceLayoutError | WorkspaceNotInitialized | LockedSkillMissing | SettingsEntryMissing | InvalidAgentId | DesiredPackGraphIncomplete | CanonicalPathRemovalError | SymlinkCreationError | LockEntrySourceMissing | LockEntryUrlInvalid | LockEntryNameInvalid | LockEntryEndpointConflict | LockEntrySourceTypeConflict | AcceptedResolutionMissing | InlineExtensionSourceMissing | SupersededCanonicalRemovalFailed | PackageContentHashFailed | WorkspaceSourceInvalid | SkillDiscoveryRootInvalid | SubagentScanFailed | LockfileResolvedVersionInvalid | FqnInvalidError | FrontmatterParseFailure | SubagentContentError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.js

@@ -0,0 +1,14 @@
+/**
+ * Failure vocabulary for extension materialization: the union of the per-type
+ * manager families, the canonical-materialization family, and the failures the
+ * managers surface from the capabilities underneath them — workspace state,
+ * transactions, projection, source resolution, and the registry client.
+ *
+ * Every member is typed. Nothing travels opaquely: a manager that calls a
+ * source host or the registry client keeps that integration's own failure in
+ * its channel, and the application boundary converts it once.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export {};
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1,106 @@
+/**
+ * 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 * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { type WorkspaceSnapshotError } from "@agentxm/workspace-transactions";
+import { CanonicalPackageProbeFailed, CreateDestinationExists, PackageCopyFailed, PackageMaterializationFailed, StagedPackageInvalid } from "./errors.js";
+import { PathTraversalDetected } from "@agentxm/workspace-state";
+import { type MaterializedTreeInvalid, type TreeIntegrity } from "@agentxm/workspace-state";
+export declare const canonicalMaterializationPaths: (canonicalPath: string) => {
+    stagingPath: string;
+    backupPath: string;
+};
+/** Failures the sibling staging/swap machinery itself can produce. */
+export type CanonicalDirectoryReplacementError = PackageMaterializationFailed | PathTraversalDetected | WorkspaceSnapshotError;
+export interface RecoverCanonicalDirectoryArgs {
+    readonly baseDir: string;
+    readonly canonicalPath: string;
+}
+/** Recover or clean sibling replacement state before any fallible source work. */
+export declare const recoverCanonicalDirectory: (args: RecoverCanonicalDirectoryArgs) => Effect.Effect<void, PackageMaterializationFailed | PathTraversalDetected, FileSystem.FileSystem | Path.Path>;
+export interface ReplaceCanonicalDirectoryArgs<E, R> {
+    readonly baseDir: string;
+    readonly canonicalPath: string;
+    readonly populate: (stagingPath: string) => Effect.Effect<void, E, R>;
+    readonly validate?: (stagingPath: string) => Effect.Effect<void, E, R>;
+}
+export interface ReplaceCanonicalDirectoryWithInspectionArgs<A, E, R> extends ReplaceCanonicalDirectoryArgs<E, R> {
+    readonly inspect: (stagingPath: string) => Effect.Effect<A, E, R>;
+}
+export interface CanonicalDirectoryInspection<A> {
+    readonly canonicalPath: string;
+    readonly inspection: A;
+}
+export interface CreateCanonicalDirectoryArgs<E, R> extends ReplaceCanonicalDirectoryArgs<E, R> {
+    /** Human-readable create-only subject used in collision diagnostics. */
+    readonly subject: string;
+    /** Type-defined files that must exist in the complete staged package. */
+    readonly requiredFiles?: ReadonlyArray<string>;
+}
+/**
+ * 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 declare const replaceCanonicalDirectoryWithInspection: <A, E, R>(args: ReplaceCanonicalDirectoryWithInspectionArgs<A, E, R>) => Effect.Effect<CanonicalDirectoryInspection<A>, E | CanonicalDirectoryReplacementError, FileSystem.FileSystem | Path.Path | R>;
+export declare const replaceCanonicalDirectory: <E, R>(args: ReplaceCanonicalDirectoryArgs<E, R>) => Effect.Effect<string, E | CanonicalDirectoryReplacementError, FileSystem.FileSystem | Path.Path | R>;
+/**
+ * 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 declare const createCanonicalDirectory: <E, R>(args: CreateCanonicalDirectoryArgs<E, R>) => Effect.Effect<string, E | CanonicalDirectoryReplacementError | CreateDestinationExists | StagedPackageInvalid, FileSystem.FileSystem | Path.Path | R>;
+export interface CanReuseInstalledPackageArgs {
+    /**
+     * Canonical installed tree for this extension. Always the workspace location
+     * the extension is installed to — never a staging destination, whose absence
+     * would make every install look like a first install.
+     */
+    readonly installedPath: string;
+    /** Caller demanded an unconditional re-materialization. */
+    readonly force: boolean;
+    /** Exact version requested by the ref being installed. */
+    readonly refVersion: string;
+    /** The ref carries a pinned archive integrity (registry-resolved). */
+    readonly hasIntegrity: boolean;
+    /** Resolved version recorded in the current lockfile entry, when any. */
+    readonly lockedVersion?: string;
+    readonly existsFailureDetail: (installedPath: string) => string;
+}
+export interface CanReuseExternalPackageArgs {
+    readonly installedPath: string;
+    readonly force: boolean;
+    readonly existsFailureDetail: (installedPath: string) => string;
+}
+/** Preserve an existing external canonical tree unless refresh was explicitly requested. */
+export declare const canReuseExternalPackage: (args: CanReuseExternalPackageArgs) => Effect.Effect<boolean, PackageMaterializationFailed | CanonicalPackageProbeFailed, FileSystem.FileSystem>;
+/**
+ * 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 declare const canReuseInstalledPackage: (args: CanReuseInstalledPackageArgs) => Effect.Effect<boolean, PackageMaterializationFailed | CanonicalPackageProbeFailed, FileSystem.FileSystem>;
+export interface MaterializedPackage {
+    readonly canonicalPath: string;
+    readonly treeIntegrity: TreeIntegrity;
+}
+export interface MaterializeExternalPackageArgs<E = never> {
+    readonly baseDir: string;
+    readonly canonicalPath: string;
+    readonly sourceLocation: string;
+    readonly copyFailureCode: "internal" | "validation";
+    readonly copyFailureDetail: (canonicalPath: string) => string;
+    readonly validate?: (stagingPath: string) => Effect.Effect<void, E, FileSystem.FileSystem | Path.Path>;
+}
+export declare const materializeExternalPackageWithTreeIntegrity: <E = never>(args: MaterializeExternalPackageArgs<E>) => Effect.Effect<MaterializedPackage, E | PackageCopyFailed | CanonicalDirectoryReplacementError | MaterializedTreeInvalid, FileSystem.FileSystem | Path.Path>;
+export declare const materializeExternalPackage: <E = never>(args: MaterializeExternalPackageArgs<E>) => Effect.Effect<string, PackageCopyFailed | MaterializedTreeInvalid | CanonicalDirectoryReplacementError | E, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=canonical-directory.d.ts.map