@agentxm/extension-lifecycle 0.28.4-bootstrap.0

package/dist/src/packs/expansion.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pack expansion helpers for cross-type dependency expansion.
+ *
+ * - expandPackInstallRefs: Expands a pack ref into install refs (pack + dependencies)
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type * as Option from "effect/Option";
+import type { SourceAuthorityBlocked, PackManagerError } from "@agentxm/extension-workspace";
+/** Failures pack expansion can surface. */
+type PackExpansionError = SourceResolutionFailure | PackManagerError | SourceAuthorityBlocked;
+import { type ExtensionType } from "@agentxm/extension-model/unstable/extensions";
+import type { ExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/extension-ref";
+import type { PackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
+import type { SourceHostProvidersService, SourceResolutionFailure } from "@agentxm/extension-sources";
+import type * as Duration from "effect/Duration";
+import { type PackDependencyRefResolver, type ReleaseAgeAwarePackDependencyResolution, type WorkspacePackDependencyResolver } from "./dependency-resolution.js";
+import type { ReleaseAgeEvaluation } from "@agentxm/extension-model/unstable/extensions/release-age";
+/**
+ * Expand a pack ref into its cross-type dependency refs.
+ *
+ * Returns the pack ref first, followed by dependency refs in declaration
+ * order. Only dependency types listed in `supportedDependencyTypes` are
+ * included.
+ *
+ * Dependency refs use the pack's registry source and empty integrity
+ * (integrity is resolved during materialization, not at expansion time).
+ */
+export declare const expandPackInstallRefs: <E = never>(args: {
+    readonly pack: PackRef;
+    readonly supportedDependencyTypes: ReadonlyArray<ExtensionType>;
+    readonly sources: SourceHostProvidersService;
+    readonly minimumReleaseAge?: Option.Option<Duration.Duration>;
+    readonly workspaceResolver?: WorkspacePackDependencyResolver<E>;
+    readonly dependencyResolver?: PackDependencyRefResolver<E>;
+}) => Effect.Effect<ReadonlyArray<ExtensionRef>, PackExpansionError | E>;
+export type ReleaseAgeAwarePackExpansion = {
+    readonly kind: "selected";
+    readonly refs: ReadonlyArray<ExtensionRef>;
+    readonly holdbacks: Extract<ReleaseAgeAwarePackDependencyResolution, {
+        kind: "selected";
+    }>["holdbacks"];
+    readonly bypasses: Extract<ReleaseAgeAwarePackDependencyResolution, {
+        kind: "selected";
+    }>["bypasses"];
+} | Extract<ReleaseAgeAwarePackDependencyResolution, {
+    kind: "policy_held";
+}>;
+export declare const expandPackInstallRefsWithReleaseAge: <E = never>(args: {
+    readonly pack: PackRef;
+    readonly supportedDependencyTypes: ReadonlyArray<ExtensionType>;
+    readonly sources: SourceHostProvidersService;
+    readonly releaseAgeEvaluation: ReleaseAgeEvaluation;
+    readonly workspaceResolver?: WorkspacePackDependencyResolver<E>;
+    readonly dependencyResolver?: PackDependencyRefResolver<E>;
+}) => Effect.Effect<ReleaseAgeAwarePackExpansion, PackExpansionError | E>;
+export {};
+//# sourceMappingURL=expansion.d.ts.map

package/dist/src/packs/expansion.js

@@ -0,0 +1,44 @@
+/**
+ * Pack expansion helpers for cross-type dependency expansion.
+ *
+ * - expandPackInstallRefs: Expands a pack ref into install refs (pack + dependencies)
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import {} from "@agentxm/extension-model/unstable/extensions";
+import { resolvePackDependencies } from "./dependency-resolution.js";
+import { resolvePackDependenciesWithReleaseAge, } from "./dependency-resolution.js";
+// -----------------------------------------------------------------------------
+// expandPackInstallRefs
+// -----------------------------------------------------------------------------
+/**
+ * Expand a pack ref into its cross-type dependency refs.
+ *
+ * Returns the pack ref first, followed by dependency refs in declaration
+ * order. Only dependency types listed in `supportedDependencyTypes` are
+ * included.
+ *
+ * Dependency refs use the pack's registry source and empty integrity
+ * (integrity is resolved during materialization, not at expansion time).
+ */
+export const expandPackInstallRefs = (args) => Effect.gen(function* () {
+    const { pack, supportedDependencyTypes, sources, minimumReleaseAge, workspaceResolver, dependencyResolver, } = args;
+    const resolved = yield* resolvePackDependencies(pack, sources, minimumReleaseAge, undefined, workspaceResolver, dependencyResolver);
+    const deps = resolved.dependencyRefs.filter((ref) => supportedDependencyTypes.includes(ref.type));
+    const packRef = pack;
+    return [packRef, ...deps];
+});
+export const expandPackInstallRefsWithReleaseAge = (args) => Effect.gen(function* () {
+    const resolved = yield* resolvePackDependenciesWithReleaseAge(args.pack, args.sources, args.releaseAgeEvaluation, undefined, args.workspaceResolver, args.dependencyResolver);
+    if (resolved.kind === "policy_held")
+        return resolved;
+    const dependencies = resolved.dependencies.dependencyRefs.filter((ref) => args.supportedDependencyTypes.includes(ref.type));
+    return {
+        kind: "selected",
+        refs: [args.pack, ...dependencies],
+        holdbacks: resolved.holdbacks,
+        bypasses: resolved.bypasses,
+    };
+});
+//# sourceMappingURL=expansion.js.map

package/dist/src/packs/manager.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pack manager service.
+ *
+ * Implements ExtensionManager<PackRef>. Delegates to existing
+ * pack materialization functions and workspace service methods.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Layer from "effect/Layer";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { PackManager } from "@agentxm/extension-workspace";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+export declare const PackManagerLive: Layer.Layer<PackManager, never, SourceHostProviders | WorkspaceMutations | FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=manager.d.ts.map

package/dist/src/packs/manager.js

@@ -0,0 +1,181 @@
+/**
+ * Pack manager service.
+ *
+ * Implements ExtensionManager<PackRef>. Delegates to existing
+ * pack materialization functions and workspace service methods.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { PackArchiveFetchFailed, PackDefinitionInvalid, PackInstallStateMissing, PackStagingFailed, } from "@agentxm/extension-workspace";
+import { canReuseInstalledPackage, replaceCanonicalDirectoryWithInspection, } from "@agentxm/extension-workspace";
+import { configuredPacksToDiskRefs } from "@agentxm/extension-workspace";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { PackManager } from "@agentxm/extension-workspace";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { copyExtensionDirectory } from "@agentxm/extension-workspace";
+import { computePackPathsForLayout } from "@agentxm/workspace-state";
+import { removeIfExists } from "@agentxm/workspace-state";
+import { acceptedRegistryVersionForRef, validateExactResolvedVersion, } from "@agentxm/workspace-state";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { configuredRowsByName } from "@agentxm/workspace-state";
+import { isObservedInstalled } from "@agentxm/workspace-state";
+import { acceptedCanonicalObservation, prepareAcceptedCanonicalTransition, removableAcceptedCanonicalPath, } from "@agentxm/workspace-state";
+import { computePackManifestContentIdentity } from "@agentxm/workspace-state";
+import { computeMaterializedTreeIntegrity, } from "@agentxm/workspace-state";
+// Build pack SetPackArgs from a registry ref
+const buildSetPackArgs = (ref, versionRange, treeIntegrity) => ({
+    type: "registry",
+    sourceType: "registry",
+    packageFormat: "agentxm",
+    endpoint: ref.source.location,
+    extensionType: "pack",
+    workspaceName: ref.pack.name,
+    owner: ref.owner,
+    name: ref.pack.name,
+    resolvedVersion: decodeVersionSync(ref.version),
+    integrity: Option.getOrElse(ref.integrity, () => ""),
+    sourceName: ref.source.name,
+    publisherBindingId: ref.publisherBindingId,
+    treeIntegrity,
+    manifestContentIdentity: computePackManifestContentIdentity({
+        owner: ref.owner,
+        type: "pack",
+        name: ref.pack.name,
+        version: ref.version,
+        dependencies: ref.pack.dependencies,
+    }),
+    versionRange,
+});
+// -----------------------------------------------------------------------------
+// Live Layer
+// -----------------------------------------------------------------------------
+export const PackManagerLive = Layer.effect(PackManager, Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const sources = yield* SourceHostProviders;
+    const baseDir = ws.baseDir;
+    // Build a layer to provide FileSystem + Path to inner effects
+    const fsPathLayer = Layer.merge(Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(Path.Path, path));
+    const provide = (effect) => Effect.provide(effect, fsPathLayer);
+    const lastTreeIntegrities = new Map();
+    const materializeInstall = Effect.fn("PackManager.materializeInstall")(function* ({ ref, force }) {
+        if (ref.refType === "registry") {
+            yield* validateExactResolvedVersion(`packs.${ref.pack.name}.resolvedVersion`, ref.version);
+        }
+        const packDir = computePackPathsForLayout(path.join, ws.layout, ref.refType === "workspace" ? "workspace" : ref.source.name, ref.owner, ref.pack.name).canonicalPath;
+        const canonicalExists = yield* fs.exists(packDir).pipe(Effect.orElseSucceed(() => false));
+        if (ref.refType === "workspace") {
+            if (ref.scope !== ws.scope || path.resolve(ref.location) !== path.resolve(packDir)) {
+                return yield* new PackDefinitionInvalid({
+                    detail: `Invalid workspace pack source location: ${ref.location}`,
+                });
+            }
+            if (!canonicalExists) {
+                return yield* new PackDefinitionInvalid({
+                    detail: `Workspace pack package is missing: ${packDir}`,
+                });
+            }
+            return;
+        }
+        const lockedEntry = yield* ws.getLockedPack(ref.pack.name);
+        const lockedVersion = acceptedRegistryVersionForRef(lockedEntry, ref);
+        if (yield* provide(canReuseInstalledPackage({
+            installedPath: packDir,
+            force: force === true,
+            refVersion: ref.version,
+            hasIntegrity: Option.isSome(ref.integrity),
+            ...(lockedVersion === undefined ? {} : { lockedVersion }),
+            existsFailureDetail: (target) => `Failed to check if canonical pack path exists: ${target}`,
+        }))) {
+            if (Option.isSome(lockedEntry)) {
+                const observedTree = yield* provide(computeMaterializedTreeIntegrity(packDir));
+                if (observedTree === lockedEntry.value.treeIntegrity) {
+                    lastTreeIntegrities.set(ref.pack.name, lockedEntry.value.treeIntegrity);
+                    return;
+                }
+            }
+        }
+        yield* Effect.scoped(Effect.gen(function* () {
+            const fetched = yield* sources
+                .fetch(ref)
+                .pipe(Effect.mapError((e) => new PackArchiveFetchFailed({ message: e.message, cause: e })));
+            const materialized = yield* provide(replaceCanonicalDirectoryWithInspection({
+                baseDir,
+                canonicalPath: packDir,
+                populate: (stagingPath) => copyExtensionDirectory(fetched.directory, stagingPath).pipe(Effect.mapError((cause) => new PackStagingFailed({ packDir, cause }))),
+                inspect: computeMaterializedTreeIntegrity,
+            }));
+            lastTreeIntegrities.set(ref.pack.name, materialized.inspection);
+        }));
+    });
+    const materializeUninstall = Effect.fn("PackManager.materializeUninstall")(function* ({ target }) {
+        const canonical = yield* provide(acceptedCanonicalObservation({ workspace: ws, type: "pack", name: target.name }));
+        const packDir = removableAcceptedCanonicalPath(canonical);
+        if (Option.isSome(packDir))
+            yield* removeIfExists(fs, packDir.value);
+    });
+    const materializeDeactivate = () => Effect.void;
+    const buildCurrentPackArgs = (ref, versionRange) => Effect.gen(function* () {
+        if (ref.refType !== "registry")
+            return Option.none();
+        const treeIntegrity = lastTreeIntegrities.get(ref.pack.name);
+        if (treeIntegrity === undefined) {
+            return yield* new PackInstallStateMissing({ name: ref.pack.name });
+        }
+        return Option.some(buildSetPackArgs(ref, versionRange, treeIntegrity));
+    });
+    return {
+        type: "pack",
+        runTransaction: ws.runTransaction,
+        isInstalled: Effect.fn("PackManager.isInstalled")(function* ({ target, }) {
+            return yield* isObservedInstalled(ws, "pack", target.name);
+        }),
+        materializeInstall,
+        prepareSourceTransition: ({ ref }) => provide(prepareAcceptedCanonicalTransition({
+            workspace: ws,
+            type: "pack",
+            name: ref.pack.name,
+            ref,
+        })),
+        getConfiguredSource: Effect.fn("PackManager.getConfiguredSource")(function* ({ target }) {
+            const configured = yield* ws.getConfiguredPackEntries();
+            return Option.fromUndefinedOr(configured[target.name]?.source);
+        }),
+        listMaterializable: Effect.fn("PackManager.listMaterializable")(function* () {
+            const configured = yield* ws.records.rows("pack").pipe(Effect.map(configuredRowsByName));
+            return yield* configuredPacksToDiskRefs({ fs, path, baseDir, scope: ws.scope, layout: ws.layout }, configured);
+        }),
+        materializeUninstall,
+        materializeDeactivate,
+        upsertSettingsEntry: Effect.fn("PackManager.upsertSettingsEntry")(function* ({ ref, versionRange, }) {
+            const args = yield* buildCurrentPackArgs(ref, versionRange);
+            if (Option.isSome(args)) {
+                yield* ws.setPack(args.value);
+            }
+            else {
+                yield* ws.setPackEntry(ref.pack.name, {
+                    source: "workspace",
+                    enabled: true,
+                });
+            }
+        }),
+        removeSettingsEntry: ({ target }) => ws.removePackSettings(target.name).pipe(Effect.withSpan("PackManager.removeSettingsEntry")),
+        upsertLockfileEntry: Effect.fn("PackManager.upsertLockfileEntry")(function* ({ ref }) {
+            const args = yield* buildCurrentPackArgs(ref, Option.none());
+            if (Option.isSome(args)) {
+                yield* ws.setPackLock(args.value);
+            }
+            else {
+                yield* ws.removePackLock(ref.pack.name);
+            }
+        }),
+        removeLockfileEntry: ({ target }) => ws.removePackLock(target.name).pipe(Effect.withSpan("PackManager.removeLockfileEntry")),
+    };
+}));
+//# sourceMappingURL=manager.js.map

package/dist/src/packs/operations/install.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Install pack operation handler.
+ *
+ * Fetches the pack archive, extracts to the managed location, and
+ * writes pack metadata to settings and lockfile.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { Option } from "effect/Option";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import type { Version } from "@agentxm/extension-model/unstable/version-constraints";
+import type { PackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { LifecycleFailureAdapter } from "../../failure-adapter.js";
+import type { OperationHandler } from "@agentxm/workspace-operations";
+import type { Operation } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { type ResolvedPackDependencyMap } from "../resolved-dependency.js";
+/**
+ * Args for the install pack operation.
+ */
+export interface InstallPackOperationArgs {
+    /** Pack name (e.g., "my-pack") */
+    readonly packName: string;
+    /** Pack owner (e.g., "@acme") */
+    readonly owner: Handle;
+    /** Exact resolved version */
+    readonly resolvedVersion: Version;
+    /** SRI integrity string */
+    readonly integrity: string;
+    /** Registry source name */
+    readonly sourceName: string;
+    readonly publisherBindingId: string;
+    /** Resolved skill FQNs to exact versions */
+    readonly resolvedSkills: ResolvedPackDependencyMap;
+    /** Resolved MCP server FQNs to exact versions */
+    readonly resolvedMcpServers: ResolvedPackDependencyMap;
+    /** Resolved subagent FQNs to exact versions */
+    readonly resolvedSubagents: ResolvedPackDependencyMap;
+    /** Resolved rule FQNs to exact versions */
+    readonly resolvedRules: ResolvedPackDependencyMap;
+    /** Resolved hook FQNs to exact versions */
+    readonly resolvedHooks: ResolvedPackDependencyMap;
+    /** Resolved knowledge FQNs to exact versions */
+    readonly resolvedKnowledge: ResolvedPackDependencyMap;
+    /** Version constraint from the original source (e.g. "^2.0.0"). Preserved in settings. */
+    readonly versionRange: Option<string>;
+    /** Pack extension ref for fetching the archive. */
+    readonly ref: PackRef;
+}
+/**
+ * Add a pack to the workspace.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type InstallPackOperation = Operation<"install-pack", InstallPackOperationArgs>;
+/**
+ * Install pack operation handler.
+ *
+ * Fetches the pack archive via sources.fetch(), extracts to the managed
+ * source-qualified acquired pack location, then records
+ * the pack in settings and lockfile.
+ */
+export declare const installPack: OperationHandler<InstallPackOperation, WorkspaceMutations | SourceHostProviders | FileSystem.FileSystem | Path.Path | LifecycleFailureAdapter>;
+//# sourceMappingURL=install.d.ts.map

package/dist/src/packs/operations/install.js

@@ -0,0 +1,156 @@
+/**
+ * Install pack operation handler.
+ *
+ * Fetches the pack archive, extracts to the managed location, and
+ * writes pack metadata to settings and lockfile.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { decodeExtensionNameSync } from "@agentxm/extension-model/unstable/extensions";
+import { recoverCanonicalDirectory, replaceCanonicalDirectory } from "@agentxm/extension-workspace";
+import { validateExactResolvedVersion } from "@agentxm/workspace-state";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { ExtensionLifecycleFailed } from "../../errors.js";
+import { LifecycleFailureAdapter, } from "../../failure-adapter.js";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { copyExtensionDirectory } from "@agentxm/extension-workspace";
+import { computePackPathsForLayout } from "@agentxm/workspace-state";
+import { PACK_MANIFEST_FILENAME, PackManifestSchema, } from "@agentxm/extension-model/unstable/packs/manifest-schema";
+import { validateExactPackDependencyVersions, } from "../resolved-dependency.js";
+import { computePackManifestContentIdentity } from "@agentxm/workspace-state";
+import { computeMaterializedTreeIntegrity } from "@agentxm/workspace-state";
+const collectMissingResolvedDependencies = (manifest, op) => {
+    const missing = [];
+    for (const fqn of Object.keys(manifest.dependencies)) {
+        if (!Object.hasOwn(op.args.resolvedSkills, fqn) &&
+            !Object.hasOwn(op.args.resolvedMcpServers, fqn) &&
+            !Object.hasOwn(op.args.resolvedSubagents, fqn) &&
+            !Object.hasOwn(op.args.resolvedRules, fqn) &&
+            !Object.hasOwn(op.args.resolvedHooks, fqn) &&
+            !Object.hasOwn(op.args.resolvedKnowledge, fqn)) {
+            missing.push(fqn);
+        }
+    }
+    return missing;
+};
+/**
+ * Install pack operation handler.
+ *
+ * Fetches the pack archive via sources.fetch(), extracts to the managed
+ * source-qualified acquired pack location, then records
+ * the pack in settings and lockfile.
+ */
+export const installPack = (op) => Effect.gen(function* () {
+    const adapter = yield* LifecycleFailureAdapter;
+    return yield* runInstallPack(op, adapter);
+});
+const runInstallPack = (op, adapter) => Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const sources = yield* SourceHostProviders;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    yield* validateExactResolvedVersion(`packs.${op.args.packName}.resolvedVersion`, op.args.resolvedVersion);
+    yield* validateExactPackDependencyVersions(`packs.${op.args.packName}.resolvedSkills`, op.args.resolvedSkills);
+    yield* validateExactPackDependencyVersions(`packs.${op.args.packName}.resolvedMcpServers`, op.args.resolvedMcpServers);
+    yield* validateExactPackDependencyVersions(`packs.${op.args.packName}.resolvedSubagents`, op.args.resolvedSubagents);
+    yield* validateExactPackDependencyVersions(`packs.${op.args.packName}.resolvedRules`, op.args.resolvedRules);
+    yield* validateExactPackDependencyVersions(`packs.${op.args.packName}.resolvedHooks`, op.args.resolvedHooks);
+    yield* validateExactPackDependencyVersions(`packs.${op.args.packName}.resolvedKnowledge`, op.args.resolvedKnowledge);
+    // Extract to managed location
+    const packDir = computePackPathsForLayout(path.join, ws.layout, op.args.sourceName, op.args.owner, op.args.packName).canonicalPath;
+    yield* recoverCanonicalDirectory({ baseDir: ws.baseDir, canonicalPath: packDir });
+    // Keep fetch scope alive through copy; fetched directories are released on scope close.
+    const manifestContentIdentity = yield* Effect.scoped(Effect.gen(function* () {
+        const fetched = yield* sources.fetch(op.args.ref).pipe(Effect.mapError((error) => new ExtensionLifecycleFailed({
+            category: "network",
+            detail: `Failed to fetch pack archive: ${error.message}`,
+            cause: error,
+        })));
+        const manifestPath = path.join(fetched.directory, PACK_MANIFEST_FILENAME);
+        const manifestContent = yield* fs.readFileString(manifestPath).pipe(Effect.mapError((error) => new ExtensionLifecycleFailed({
+            category: "internal",
+            detail: `Failed to read fetched pack manifest: ${manifestPath}`,
+            cause: error,
+        })));
+        const manifestJson = yield* Effect.try({
+            try: () => {
+                const parsed = JSON.parse(manifestContent);
+                return parsed;
+            },
+            catch: (error) => new ExtensionLifecycleFailed({
+                category: "validation",
+                detail: `Invalid JSON in fetched pack manifest: ${manifestPath}`,
+                cause: error,
+            }),
+        });
+        const manifest = yield* Schema.decodeUnknownEffect(PackManifestSchema)(manifestJson).pipe(Effect.mapError((error) => new ExtensionLifecycleFailed({
+            category: "validation",
+            detail: `Invalid fetched pack manifest: ${manifestPath}`,
+            cause: error,
+        })));
+        const missingDependencies = collectMissingResolvedDependencies(manifest, op);
+        if (missingDependencies.length > 0) {
+            return yield* new ExtensionLifecycleFailed({
+                category: "internal",
+                detail: `Pack ${op.args.packName} declares dependencies that were not resolved from registry metadata`,
+                suggestions: [
+                    {
+                        description: "Republish the pack or repair the registry metadata before installing this pack.",
+                    },
+                ],
+            });
+        }
+        yield* replaceCanonicalDirectory({
+            baseDir: ws.baseDir,
+            canonicalPath: packDir,
+            populate: (stagingPath) => copyExtensionDirectory(fetched.directory, stagingPath).pipe(Effect.mapError((cause) => new ExtensionLifecycleFailed({
+                category: "internal",
+                detail: `Failed to stage pack at ${packDir}`,
+                cause,
+            }))),
+        });
+        return computePackManifestContentIdentity(manifest);
+    }));
+    const treeIntegrity = yield* computeMaterializedTreeIntegrity(packDir);
+    if (op.args.ref.source.type !== "registry") {
+        return yield* new ExtensionLifecycleFailed({
+            category: "validation",
+            detail: `Pack ${op.args.packName} does not resolve to a Registry source`,
+        });
+    }
+    // Write lockfile + settings
+    const metadataWarning = yield* ws
+        .setPack({
+        type: "registry",
+        sourceType: "registry",
+        packageFormat: "agentxm",
+        endpoint: op.args.ref.source.location,
+        extensionType: "pack",
+        workspaceName: decodeExtensionNameSync(op.args.packName),
+        owner: op.args.owner,
+        name: decodeExtensionNameSync(op.args.packName),
+        resolvedVersion: op.args.resolvedVersion,
+        integrity: op.args.integrity,
+        sourceName: op.args.sourceName,
+        publisherBindingId: op.args.publisherBindingId,
+        manifestContentIdentity,
+        treeIntegrity,
+        versionRange: op.args.versionRange,
+    })
+        .pipe(Effect.as(undefined), Effect.catch((e) => Effect.succeed(`Pack metadata update failed: ${String(e)}`)));
+    return {
+        result: "success",
+        message: metadataWarning === undefined
+            ? `Installed pack ${op.args.packName}`
+            : `Installed pack ${op.args.packName}; ${metadataWarning}`,
+    };
+}).pipe(Effect.catch((error) => Effect.succeed({
+    result: "error",
+    message: `Failed to install pack: ${adapter.describeFailureMessage(error)}`,
+    error: adapter.toStepFailure(error),
+})));
+//# sourceMappingURL=install.js.map

package/dist/src/packs/resolved-dependency.d.ts

@@ -0,0 +1,29 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { PackDefinitionInvalid } from "@agentxm/extension-workspace";
+export declare const ResolvedPackDependencySchema: Schema.Union<readonly [Schema.Struct<{
+    readonly source: Schema.Literal<"registry">;
+    readonly version: Schema.brand<Schema.String, "Version">;
+    readonly publisherBindingId: Schema.NonEmptyString;
+    readonly integrity: Schema.String;
+}>, Schema.Struct<{
+    readonly source: Schema.Literal<"workspace">;
+    readonly version: Schema.brand<Schema.String, "Version">;
+    readonly sourceIdentity: Schema.String;
+    readonly contentIdentity: Schema.brand<Schema.String, "SourceHash">;
+}>]>;
+export type ResolvedPackDependency = typeof ResolvedPackDependencySchema.Type;
+export declare const ResolvedPackDependencyMapSchema: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Struct<{
+    readonly source: Schema.Literal<"registry">;
+    readonly version: Schema.brand<Schema.String, "Version">;
+    readonly publisherBindingId: Schema.NonEmptyString;
+    readonly integrity: Schema.String;
+}>, Schema.Struct<{
+    readonly source: Schema.Literal<"workspace">;
+    readonly version: Schema.brand<Schema.String, "Version">;
+    readonly sourceIdentity: Schema.String;
+    readonly contentIdentity: Schema.brand<Schema.String, "SourceHash">;
+}>]>>;
+export type ResolvedPackDependencyMap = typeof ResolvedPackDependencyMapSchema.Type;
+export declare const validateExactPackDependencyVersions: (field: string, resolved: ResolvedPackDependencyMap) => Effect.Effect<void, PackDefinitionInvalid, never>;
+//# sourceMappingURL=resolved-dependency.d.ts.map

package/dist/src/packs/resolved-dependency.js

@@ -0,0 +1,28 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { PackDefinitionInvalid } from "@agentxm/extension-workspace";
+import { ExtensionFqnSchema } from "@agentxm/extension-model/unstable/extensions";
+import { SourceHashSchema } from "@agentxm/extension-model/unstable/sources/source-hash";
+import { VersionSchema } from "@agentxm/extension-model/unstable/version-constraints";
+const ResolvedRegistryDependencySchema = Schema.Struct({
+    source: Schema.Literal("registry"),
+    version: VersionSchema,
+    publisherBindingId: Schema.NonEmptyString,
+    integrity: Schema.String,
+});
+const ResolvedWorkspaceDependencySchema = Schema.Struct({
+    source: Schema.Literal("workspace"),
+    version: VersionSchema,
+    sourceIdentity: Schema.String,
+    contentIdentity: SourceHashSchema,
+});
+export const ResolvedPackDependencySchema = Schema.Union([
+    ResolvedRegistryDependencySchema,
+    ResolvedWorkspaceDependencySchema,
+]);
+export const ResolvedPackDependencyMapSchema = Schema.Record(ExtensionFqnSchema, ResolvedPackDependencySchema);
+export const validateExactPackDependencyVersions = (field, resolved) => Effect.forEach(Object.entries(resolved), ([fqn, value]) => Schema.decodeUnknownEffect(VersionSchema)(value.version).pipe(Effect.mapError((cause) => new PackDefinitionInvalid({
+    detail: `Pack dependency ${field}.${fqn}.version must be an exact semver value`,
+    cause,
+}))), { concurrency: "unbounded", discard: true });
+//# sourceMappingURL=resolved-dependency.js.map

package/dist/src/registry-materialization.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Registry-backed canonical package materialization.
+ *
+ * The canonical-directory staging/swap machinery lives in
+ * `@agentxm/extension-workspace`; this module owns only the registry
+ * fetch/verify/extract path.
+ *
+ * @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 * as HttpClient from "effect/unstable/http/HttpClient";
+import type { Version, VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
+import type { ExtensionName, ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { ArchiveIntegrityMismatch, type CanonicalDirectoryReplacementError, type MaterializedPackage } from "@agentxm/extension-workspace";
+import { CoupledDependencyFailure } from "@agentxm/extension-workspace";
+import { type MaterializedTreeInvalid } from "@agentxm/workspace-state";
+export interface RegistryPackageMaterializationMessages {
+    readonly integrityMismatchDetail: string;
+}
+export interface MaterializeRegistryPackageArgs<E = never> {
+    readonly baseDir: string;
+    /**
+     * Canonical installed path for this extension. Bytes always land in a sibling
+     * staging directory first and are swapped in after validation.
+     */
+    readonly destinationPath: string;
+    readonly sourceLocation: URL;
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly version: Version | VersionRange;
+    readonly integrity: Option.Option<string>;
+    readonly messages: RegistryPackageMaterializationMessages;
+    readonly validate?: (stagingPath: string) => Effect.Effect<void, E, FileSystem.FileSystem | Path.Path>;
+}
+/**
+ * Fetch, verify, and extract a registry package into `destinationPath`.
+ *
+ * Always writes. Whether new bytes are needed at all is
+ * `canReuseInstalledPackage`'s decision, which the caller makes against the
+ * canonical installed path before choosing a destination.
+ *
+ * Registry client and archive-extraction failures travel opaquely as coupled
+ * dependency failures; the application boundary restores and converts them.
+ */
+export declare const materializeRegistryPackageWithTreeIntegrity: <E = never>(args: MaterializeRegistryPackageArgs<E>) => Effect.Effect<MaterializedPackage, E | CoupledDependencyFailure | ArchiveIntegrityMismatch | CanonicalDirectoryReplacementError | MaterializedTreeInvalid, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
+export declare const materializeRegistryPackage: <E = never>(args: MaterializeRegistryPackageArgs<E>) => Effect.Effect<string, CoupledDependencyFailure | ArchiveIntegrityMismatch | CanonicalDirectoryReplacementError | MaterializedTreeInvalid | E, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
+//# sourceMappingURL=registry-materialization.d.ts.map