@agentxm/extension-lifecycle 0.28.11 → 0.28.13

package/dist/src/packs/member-install-step.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One member of a pack graph transition.
+ *
+ * A member is acquired without writing its own settings entry — the pack's
+ * dependency map already declares it — and without validating its observable
+ * projection on its own, because the enclosing transition renders every
+ * shared aggregate once at the end.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { HookManager, KnowledgeManager, RuleManager, SkillManager, SubagentManager } from "@agentxm/extension-materialization";
+import type { HookExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/hook";
+import type { KnowledgeExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/knowledge";
+import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import type { RuleExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/rule";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+import type { PlannedJobStep } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import type { InstallStepRequirements } from "../install/vocabulary.js";
+export type PackMemberRef = SkillExtensionRef | McpServerExtensionRef | SubagentExtensionRef | RuleExtensionRef | HookExtensionRef | KnowledgeExtensionRef;
+/** Build the install closure for one pack member. */
+export declare const buildPackMemberInstallStep: (args: {
+    readonly ref: PackMemberRef;
+    readonly graphComplete: boolean;
+    readonly nonInteractive: boolean;
+}) => Effect.Effect<PlannedJobStep<InstallStepRequirements>, never, HookManager | KnowledgeManager | RuleManager | SkillManager | SubagentManager | WorkspaceMutations>;
+//# sourceMappingURL=member-install-step.d.ts.map

package/dist/src/packs/member-install-step.js

@@ -0,0 +1,156 @@
+/**
+ * One member of a pack graph transition.
+ *
+ * A member is acquired without writing its own settings entry — the pack's
+ * dependency map already declares it — and without validating its observable
+ * projection on its own, because the enclosing transition renders every
+ * shared aggregate once at the end.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { HookManager, KnowledgeManager, NO_MATERIALIZATION_OBSERVATION, RuleManager, SkillManager, SubagentManager, buildInstallOperation, extensionRefLifecycleWarnings, extensionRefRegistryLifecycle, installMcpServer, toLabelWithCompanions, } from "@agentxm/extension-materialization";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { lifecycleStepFailure } from "../step-failure.js";
+import { registrySourceArtifact } from "./artifact.js";
+const registrySourceArtifactWithCoverage = (args) => Effect.gen(function* () {
+    const artifact = registrySourceArtifact(args);
+    const materialization = yield* args.materialization;
+    return { ...artifact, agents: materialization.agents };
+});
+/** Build the install closure for one pack member. */
+export const buildPackMemberInstallStep = Effect.fn("InstallExtensions.buildPackMemberInstallStep")(function* (args) {
+    const ws = yield* WorkspaceMutations;
+    const ref = args.ref;
+    if (ref.type === "skill") {
+        const skillManager = yield* SkillManager;
+        return buildInstallOperation(skillManager, {
+            toStepFailure: lifecycleStepFailure,
+            ref,
+            versionRange: Option.none(),
+            skipSettings: true,
+            deferObservableValidation: true,
+            installedBefore: args.graphComplete
+                ? skillManager.isInstalled({ target: { type: "skill", name: ref.skill.name } })
+                : Effect.succeed(false),
+            buildArtifact: ({ installedBefore, materialization }) => registrySourceArtifactWithCoverage({
+                ref,
+                scope: ws.scope,
+                installedBefore,
+                materialization: Effect.succeed(Option.match(materialization, {
+                    onNone: () => NO_MATERIALIZATION_OBSERVATION,
+                    onSome: (facts) => facts.observation,
+                })),
+            }),
+        });
+    }
+    if (ref.type === "mcp-server") {
+        const base = {
+            key: `mcp-server:${ref.server.name}`,
+            label: toLabelWithCompanions({ type: "mcp-server", name: ref.server.name }, ref.refType === "registry" ? ref.packages : []),
+            run: installMcpServer({
+                name: "install-mcp-server",
+                args: {
+                    ref,
+                    nonInteractive: args.nonInteractive,
+                    force: false,
+                    versionRange: Option.none(),
+                    skipSettings: Option.some(true),
+                    strictAgentSync: Option.some(true),
+                    env: Option.none(),
+                },
+            }).pipe(Effect.mapError(lifecycleStepFailure)),
+        };
+        const warnings = extensionRefLifecycleWarnings(ref);
+        const registryLifecycle = extensionRefRegistryLifecycle(ref);
+        return warnings.length === 0
+            ? {
+                ...base,
+                readiness: "ready",
+                ...(registryLifecycle === undefined ? {} : { registryLifecycle }),
+            }
+            : {
+                ...base,
+                readiness: "warn",
+                warnMessage: warnings.join("; "),
+                ...(registryLifecycle === undefined ? {} : { registryLifecycle }),
+            };
+    }
+    if (ref.type === "subagent") {
+        const subagentManager = yield* SubagentManager;
+        return buildInstallOperation(subagentManager, {
+            toStepFailure: lifecycleStepFailure,
+            ref,
+            versionRange: Option.none(),
+            skipSettings: true,
+            deferObservableValidation: true,
+            installedBefore: args.graphComplete
+                ? subagentManager.isInstalled({ target: { type: "subagent", name: ref.subagent.name } })
+                : Effect.succeed(false),
+            buildArtifact: ({ installedBefore, materialization }) => registrySourceArtifactWithCoverage({
+                ref,
+                scope: ws.scope,
+                installedBefore,
+                materialization: Effect.succeed(Option.match(materialization, {
+                    onNone: () => NO_MATERIALIZATION_OBSERVATION,
+                    onSome: (facts) => facts.observation,
+                })),
+            }),
+        });
+    }
+    if (ref.type === "rule") {
+        const ruleManager = yield* RuleManager;
+        return buildInstallOperation(ruleManager, {
+            toStepFailure: lifecycleStepFailure,
+            ref,
+            versionRange: Option.none(),
+            skipSettings: true,
+            skipProjections: true,
+            deferObservableValidation: true,
+            installedBefore: args.graphComplete
+                ? ruleManager.isInstalled({ target: { type: "rule", name: ref.rule.name } })
+                : Effect.succeed(false),
+            buildArtifact: ({ installedBefore }) => registrySourceArtifactWithCoverage({
+                ref,
+                scope: ws.scope,
+                installedBefore,
+                materialization: ruleManager.aggregateProjectionObservation,
+            }),
+        });
+    }
+    if (ref.type === "hook") {
+        const hookManager = yield* HookManager;
+        return buildInstallOperation(hookManager, {
+            toStepFailure: lifecycleStepFailure,
+            ref,
+            versionRange: Option.none(),
+            skipSettings: true,
+            skipProjections: true,
+            deferObservableValidation: true,
+            installedBefore: args.graphComplete
+                ? hookManager.isInstalled({ target: { type: "hook", name: ref.hook.name } })
+                : Effect.succeed(false),
+            buildArtifact: ({ installedBefore }) => registrySourceArtifactWithCoverage({
+                ref,
+                scope: ws.scope,
+                installedBefore,
+                materialization: hookManager.aggregateProjectionObservation,
+            }),
+        });
+    }
+    const knowledgeManager = yield* KnowledgeManager;
+    return buildInstallOperation(knowledgeManager, {
+        toStepFailure: lifecycleStepFailure,
+        ref,
+        versionRange: Option.none(),
+        skipSettings: true,
+        skipProjections: true,
+        deferObservableValidation: true,
+        installedBefore: args.graphComplete
+            ? knowledgeManager.isInstalled({ target: { type: "knowledge", name: ref.knowledge.name } })
+            : Effect.succeed(false),
+        buildArtifact: ({ installedBefore }) => Effect.succeed(registrySourceArtifact({ ref, scope: ws.scope, installedBefore })),
+    });
+});
+//# sourceMappingURL=member-install-step.js.map

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

@@ -13,11 +13,11 @@ 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 { StepFailureConversion } from "../../step-failure-conversion.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";
+import type { ResolvedPackDependencyMap } from "@agentxm/extension-resolution";
 /**
  * Args for the install pack operation.
  */
@@ -63,5 +63,5 @@ export type InstallPackOperation = Operation<"install-pack", InstallPackOperatio
  * 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>;
+export declare const installPack: OperationHandler<InstallPackOperation, WorkspaceMutations | SourceHostProviders | FileSystem.FileSystem | Path.Path | StepFailureConversion>;
 //# sourceMappingURL=install.d.ts.map

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

@@ -11,16 +11,16 @@ 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 { recoverCanonicalDirectory, replaceCanonicalDirectory, } from "@agentxm/extension-materialization";
 import { validateExactResolvedVersion } from "@agentxm/workspace-state";
 import { SourceHostProviders } from "@agentxm/extension-sources";
 import { ExtensionLifecycleFailed } from "../../errors.js";
-import { LifecycleFailureAdapter, } from "../../failure-adapter.js";
+import { StepFailureConversion, } from "../../step-failure-conversion.js";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
-import { copyExtensionDirectory } from "@agentxm/extension-workspace";
+import { copyExtensionDirectory } from "@agentxm/extension-materialization";
 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 { validateExactPackDependencyVersions } from "../resolved-dependency.js";
 import { computePackManifestContentIdentity } from "@agentxm/workspace-state";
 import { computeMaterializedTreeIntegrity } from "@agentxm/workspace-state";
 const collectMissingResolvedDependencies = (manifest, op) => {
@@ -45,7 +45,7 @@ const collectMissingResolvedDependencies = (manifest, op) => {
  * the pack in settings and lockfile.
  */
 export const installPack = (op) => Effect.gen(function* () {
-    const adapter = yield* LifecycleFailureAdapter;
+    const adapter = yield* StepFailureConversion;
     return yield* runInstallPack(op, adapter);
 });
 const runInstallPack = (op, adapter) => Effect.gen(function* () {

package/dist/src/packs/promote-authored-pack.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Unpacking a Pack: promoting its members to direct declarations.
+ *
+ * A Pack owns the declarations of everything it brings in. Unpacking hands
+ * that ownership to the workspace: every member the Pack contributed becomes
+ * a direct settings declaration carrying the member's own accepted source and
+ * activation, and the Pack declaration itself goes away. Nothing is
+ * re-resolved and nothing is re-acquired — the accepted resolutions the Pack
+ * already established are exactly what the direct declarations inherit.
+ *
+ * Membership has to be provable before any of it happens: an incomplete Pack
+ * graph, a Pack that is not configured, or a member whose accepted identity
+ * cannot be read stops the operation rather than leaving the workspace half
+ * promoted. The promotion and the Pack's removal are one atomic graph
+ * transition validated against the desired state it must leave behind.
+ *
+ * A member that is already declared directly keeps the declaration it has:
+ * unpacking grants ownership, it does not overwrite intent a person expressed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { PackManager } from "@agentxm/extension-materialization";
+import { type ExecutionCandidate, type PlanExecution } from "@agentxm/workspace-operations";
+import { WorkspaceMutations, type DesiredExtensionNode } from "@agentxm/workspace-state";
+import { ExtensionLifecycleFailed } from "../errors.js";
+import type { InstallStepRequirements } from "../install/vocabulary.js";
+/** Which configured Pack is being unpacked. */
+export interface PromoteAuthoredPackRequest {
+    /** The configured Pack's installed name. */
+    readonly name: string;
+}
+/** What every step in this transition may require when it runs. */
+export type PromoteAuthoredPackRequirements = InstallStepRequirements;
+/** One member the transition promotes, and how it was declared before. */
+export interface PromotedPackMember {
+    readonly type: DesiredExtensionNode["type"];
+    readonly name: string;
+    /** True when the workspace already declared this member directly. */
+    readonly alreadyDirect: boolean;
+}
+/**
+ * A settled unpack: membership is proven, every member's accepted identity is
+ * readable, and nothing is written.
+ */
+export interface PromoteAuthoredPackCandidate {
+    /** The Pack's desired-state identity, as the transition reports it. */
+    readonly packIdentity: string;
+    readonly packName: string;
+    readonly members: ReadonlyArray<PromotedPackMember>;
+    readonly execution: ExecutionCandidate<PromoteAuthoredPackRequirements>;
+}
+/**
+ * Every failure settling an unpack can surface before anything is written:
+ * the feature's own refusals plus whatever reading the desired graph, the
+ * accepted identities, and the transition it composes surfaced.
+ */
+export type PromoteAuthoredPackFailure = Effect.Error<ReturnType<typeof settleUnpack>>;
+/** Everything settling an unpack reads before it freezes a candidate. */
+export type PreparePromoteAuthoredPackRequirements = Effect.Services<ReturnType<typeof settleUnpack>>;
+/**
+ * Settle an unpack: prove the graph is complete and the Pack is configured,
+ * read every member's accepted identity, and freeze the atomic transition
+ * that promotes the members and removes the Pack.
+ */
+declare const settleUnpack: (request: PromoteAuthoredPackRequest) => Effect.Effect<{
+    packIdentity: string;
+    packName: string;
+    members: {
+        type: "mcp-server" | "skill" | "subagent" | "rule" | "hook" | "knowledge" | "pack";
+        name: string;
+        alreadyDirect: boolean;
+    }[];
+    execution: ExecutionCandidate<InstallStepRequirements, never>;
+}, ExtensionLifecycleFailed | import("@agentxm/workspace-state").PathTraversalDetected | import("@agentxm/workspace-state").SettingsIoError | import("@agentxm/workspace-state").SettingsParseError | import("@agentxm/workspace-state").SettingsDecodeError | import("@agentxm/workspace-state").LockfileIoError | import("@agentxm/workspace-state").LockfileParseError | import("@agentxm/workspace-state").LockfileDecodeError | import("@agentxm/workspace-state").LockfileVersionUnsupported | import("@agentxm/workspace-state").WorkspaceRootEscape | import("@agentxm/workspace-state").LockfileValidationError | import("@agentxm/workspace-state").LockEntrySourceMissing | import("@agentxm/workspace-state").LockEntryUrlInvalid | import("@agentxm/workspace-state").LockEntryNameInvalid | import("@agentxm/workspace-state").LockEntryEndpointConflict | import("@agentxm/workspace-state").LockEntrySourceTypeConflict | import("@agentxm/workspace-state").AcceptedResolutionMissing | import("@agentxm/workspace-state").InlineExtensionSourceMissing | import("@agentxm/workspace-state").PackageContentHashFailed | import("@agentxm/workspace-state").WorkspaceSourceInvalid | import("@agentxm/workspace-operations").CandidateFingerprintFailed, import("effect/FileSystem").FileSystem | Path.Path | WorkspaceMutations | import("@agentxm/workspace-state").ConfiguredAgentOutcomesProvider | PackManager>;
+export declare const preparePromoteAuthoredPack: (request: PromoteAuthoredPackRequest) => Effect.Effect<PromoteAuthoredPackCandidate, PromoteAuthoredPackFailure, PreparePromoteAuthoredPackRequirements>;
+/** Preview or apply a settled unpack, resolving to one operation outcome. */
+export declare const previewOrApplyPromoteAuthoredPack: (candidate: PromoteAuthoredPackCandidate, execution: PlanExecution) => Effect.Effect<import("@agentxm/workspace-operations").OperationResolution<never>, import("@agentxm/workspace-state").WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, import("@agentxm/workspace-state").ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-transactions").FootprintRecorder | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | InstallStepRequirements>;
+/** The unpack use case: settle a request, then preview or apply it. */
+export declare const PromoteAuthoredPack: {
+    readonly prepare: (request: PromoteAuthoredPackRequest) => Effect.Effect<PromoteAuthoredPackCandidate, PromoteAuthoredPackFailure, PreparePromoteAuthoredPackRequirements>;
+    readonly previewOrApply: (candidate: PromoteAuthoredPackCandidate, execution: PlanExecution) => Effect.Effect<import("@agentxm/workspace-operations").OperationResolution<never>, import("@agentxm/workspace-state").WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, import("@agentxm/workspace-state").ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-transactions").FootprintRecorder | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | InstallStepRequirements>;
+};
+export {};
+//# sourceMappingURL=promote-authored-pack.d.ts.map

package/dist/src/packs/promote-authored-pack.js

@@ -0,0 +1,239 @@
+/**
+ * Unpacking a Pack: promoting its members to direct declarations.
+ *
+ * A Pack owns the declarations of everything it brings in. Unpacking hands
+ * that ownership to the workspace: every member the Pack contributed becomes
+ * a direct settings declaration carrying the member's own accepted source and
+ * activation, and the Pack declaration itself goes away. Nothing is
+ * re-resolved and nothing is re-acquired — the accepted resolutions the Pack
+ * already established are exactly what the direct declarations inherit.
+ *
+ * Membership has to be provable before any of it happens: an incomplete Pack
+ * graph, a Pack that is not configured, or a member whose accepted identity
+ * cannot be read stops the operation rather than leaving the workspace half
+ * promoted. The promotion and the Pack's removal are one atomic graph
+ * transition validated against the desired state it must leave behind.
+ *
+ * A member that is already declared directly keeps the declaration it has:
+ * unpacking grants ownership, it does not overwrite intent a person expressed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { PackManager, buildUninstallOperation, } from "@agentxm/extension-materialization";
+import { operationPresentation, prepareExecutionCandidate, resolveExecutionCandidate, } from "@agentxm/workspace-operations";
+import { WorkspaceMutations, usableAcceptedCanonical, } from "@agentxm/workspace-state";
+import { ExtensionLifecycleFailed } from "../errors.js";
+import { lifecycleStepFailure } from "../step-failure.js";
+import { buildAtomicPackGraphStep, validatePackGraphPostcondition } from "./graph-transition.js";
+// -----------------------------------------------------------------------------
+// Promotion
+// -----------------------------------------------------------------------------
+/**
+ * The Pack is leaving, so nothing it owned is retained on its account. The
+ * members it contributed are retained by their own direct declarations, which
+ * this same transition writes.
+ */
+const neverRetain = {
+    isRequiredByInstalledPack: () => Effect.succeed(false),
+};
+const reconcileSuggestion = (packIdentity) => ({
+    description: "Preview workspace reconciliation before unpacking.",
+    cmd: `axm sync ${packIdentity} --preview`,
+});
+/**
+ * Write the member's own declaration: the source and activation it already
+ * has under the Pack become the direct declaration it keeps without it.
+ */
+const promoteToDirectSettings = (ws, node) => {
+    const entry = { source: node.source, enabled: node.enabled };
+    const run = (() => {
+        switch (node.type) {
+            case "skill":
+                return ws.setSkillEntry(node.name, entry);
+            case "mcp-server":
+                return ws.setMcpServerEntry(node.name, { ...entry, env: {} });
+            case "subagent":
+                return ws.setSubagentEntry(node.name, entry);
+            case "rule":
+                return ws.setRuleEntry(node.name, entry);
+            case "hook":
+                return ws.setHookEntry(node.name, entry);
+            case "knowledge":
+                return ws.setKnowledgeEntry(node.name, entry);
+            case "pack":
+                return Effect.fail(new ExtensionLifecycleFailed({
+                    category: "validation",
+                    detail: `Nested pack member "${node.name}" cannot be unpacked`,
+                }));
+        }
+    })();
+    return {
+        readiness: "ready",
+        label: node.name,
+        run: run.pipe(Effect.mapError(lifecycleStepFailure), Effect.as({
+            result: "success",
+            message: `Promoted ${node.type} ${node.name}`,
+        })),
+    };
+};
+/** The workspace-relative settings file the promoted declarations land in. */
+const settingsDisplayPath = (path, ws) => path.relative(ws.baseDir, ws.layout.settingsPath);
+/** The workspace-relative canonical location the removed Pack occupied. */
+const packDisplayPath = (path, ws, node) => node.identity.startsWith("workspace:") && ws.layout.scope === "project"
+    ? path.join(path.relative(ws.baseDir, ws.layout.authoredRoot("pack")), node.name)
+    : path.join(path.relative(ws.baseDir, ws.layout.acquiredRoot), node.identity.startsWith("workspace:")
+        ? node.identity.slice("workspace:".length)
+        : node.identity);
+// -----------------------------------------------------------------------------
+// prepare
+// -----------------------------------------------------------------------------
+/**
+ * Settle an unpack: prove the graph is complete and the Pack is configured,
+ * read every member's accepted identity, and freeze the atomic transition
+ * that promotes the members and removes the Pack.
+ */
+const settleUnpack = Effect.fn("PromoteAuthoredPack.prepare")(function* (request) {
+    const ws = yield* WorkspaceMutations;
+    const packManager = yield* PackManager;
+    const path = yield* Path.Path;
+    const graph = yield* ws.getDesiredStateGraph();
+    if (!graph.complete) {
+        return yield* new ExtensionLifecycleFailed({
+            category: "validation",
+            detail: `Cannot unpack "${request.name}" while the desired pack graph is incomplete`,
+            suggestions: graph.problems.map((problem) => ({
+                description: `Resolve ${problem.type} before unpacking.`,
+            })),
+        });
+    }
+    const packNode = graph.nodes.find((node) => node.type === "pack" && node.name === request.name);
+    if (packNode === undefined || packNode.type !== "pack") {
+        return yield* new ExtensionLifecycleFailed({
+            category: "not_found",
+            detail: `Pack "${request.name}" is not configured`,
+            suggestions: [{ description: "Install the pack first.", cmd: "axm packs install <source>" }],
+        });
+    }
+    const acceptedRefFor = Effect.fn("PromoteAuthoredPack.acceptedRef")(function* (node) {
+        const canonical = yield* usableAcceptedCanonical({
+            workspace: ws,
+            type: node.type,
+            name: node.name,
+        });
+        if (Option.isNone(canonical)) {
+            return yield* new ExtensionLifecycleFailed({
+                category: "not_found",
+                detail: `Accepted ${node.type} identity for "${node.name}" is unavailable`,
+                suggestions: [reconcileSuggestion(packNode.identity)],
+            });
+        }
+        return canonical.value.ref;
+    });
+    const packRef = yield* acceptedRefFor(packNode);
+    if (packRef.type !== "pack") {
+        return yield* new ExtensionLifecycleFailed({
+            category: "not_found",
+            detail: `Accepted pack identity for "${request.name}" is invalid`,
+            suggestions: [reconcileSuggestion(packNode.identity)],
+        });
+    }
+    const memberNodes = graph.nodes.filter((node) => node.type !== "pack" &&
+        node.origins.some((origin) => origin.type === "pack" && origin.pack === packNode.identity));
+    const promotions = yield* Effect.forEach(memberNodes, Effect.fn("PromoteAuthoredPack.member")(function* (node) {
+        const ref = yield* acceptedRefFor(node);
+        if (ref.type === "pack") {
+            return yield* new ExtensionLifecycleFailed({
+                category: "not_found",
+                detail: `Accepted ${node.type} identity for "${node.name}" is invalid`,
+                suggestions: [reconcileSuggestion(packNode.identity)],
+            });
+        }
+        return node;
+    }), { concurrency: "unbounded" });
+    const promotionSteps = promotions.map((node) => {
+        // A declaration a person already wrote outranks the promotion: the
+        // member is theirs to own, on the terms they chose.
+        if (node.origins.some((origin) => origin.type === "settings")) {
+            return {
+                readiness: "ready",
+                label: node.name,
+                run: Effect.succeed({
+                    result: "success",
+                    message: "already directly configured",
+                }),
+            };
+        }
+        if (node.source === undefined) {
+            return {
+                readiness: "error",
+                errorMessage: "Inline MCP configuration has no Pack source.",
+                label: node.name,
+            };
+        }
+        return promoteToDirectSettings(ws, node);
+    });
+    const uninstallPackStep = buildUninstallOperation(packManager, neverRetain, {
+        toStepFailure: lifecycleStepFailure,
+        target: { type: "pack", owner: packRef.owner, name: packRef.pack.name },
+    });
+    const artifactTargets = [
+        ...promotions.map((node) => ({
+            path: `${settingsDisplayPath(path, ws)}#${node.type}.${node.name}`,
+            change: "updated",
+        })),
+        { path: packDisplayPath(path, ws, packNode), change: "removed" },
+    ];
+    const graphStep = yield* buildAtomicPackGraphStep({
+        label: packNode.identity,
+        message: `Unpacked ${packNode.identity} into ${promotions.length} direct declaration${promotions.length === 1 ? "" : "s"}`,
+        artifact: {
+            path: "pack provenance",
+            scope: ws.scope,
+            change: "updated",
+            fileCount: promotions.length + 1,
+            targets: artifactTargets,
+        },
+        children: [...promotionSteps, uninstallPackStep].map((step) => ({
+            step,
+            coverage: "ineligible",
+        })),
+        validate: validatePackGraphPostcondition({
+            requiredMembers: promotions.flatMap((node) => node.type === "pack"
+                ? []
+                : [{ type: node.type, name: node.name, direct: true, enabled: node.enabled }]),
+            absent: [{ type: "pack", name: packNode.name }],
+        }),
+    });
+    const plan = {
+        _tag: "Plan",
+        name: "Unpack pack",
+        description: Option.some(`Unpack ${request.name} into direct settings entries`),
+        presentation: operationPresentation({ imperative: "unpack", past: "Unpacked", gerund: "Unpacking" }, "pack"),
+        jobs: [{ concurrency: 1, steps: [graphStep] }],
+    };
+    return {
+        packIdentity: packNode.identity,
+        packName: packNode.name,
+        members: promotions.map((node) => ({
+            type: node.type,
+            name: node.name,
+            alreadyDirect: node.origins.some((origin) => origin.type === "settings"),
+        })),
+        execution: yield* prepareExecutionCandidate(plan),
+    };
+});
+export const preparePromoteAuthoredPack = settleUnpack;
+// -----------------------------------------------------------------------------
+// previewOrApply
+// -----------------------------------------------------------------------------
+/** Preview or apply a settled unpack, resolving to one operation outcome. */
+export const previewOrApplyPromoteAuthoredPack = (candidate, execution) => resolveExecutionCandidate(candidate.execution, execution);
+/** The unpack use case: settle a request, then preview or apply it. */
+export const PromoteAuthoredPack = {
+    prepare: preparePromoteAuthoredPack,
+    previewOrApply: previewOrApplyPromoteAuthoredPack,
+};
+//# sourceMappingURL=promote-authored-pack.js.map

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

@@ -1,29 +1,12 @@
+/**
+ * Pack lock-entry validation over the resolved dependency map: the map's
+ * shape belongs to `@agentxm/extension-resolution`; refusing an inexact
+ * version before a lock entry is written is the pack manager's obligation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
 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;
+import { PackDefinitionInvalid } from "@agentxm/extension-materialization";
+import type { ResolvedPackDependencyMap } from "@agentxm/extension-resolution";
 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

@@ -1,26 +1,14 @@
+/**
+ * Pack lock-entry validation over the resolved dependency map: the map's
+ * shape belongs to `@agentxm/extension-resolution`; refusing an inexact
+ * version before a lock entry is written is the pack manager's obligation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
 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 { PackDefinitionInvalid } from "@agentxm/extension-materialization";
 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,