@agentxm/extension-lifecycle 0.29.2 → 0.30.1

package/dist/src/packs/graph-transition.js

@@ -11,109 +11,8 @@
  */
 import * as Effect from "effect/Effect";
 import { WorkspaceMutations, desiredStateProblemsText, } from "@agentxm/workspace-state";
-import { runWorkspaceTransaction } from "@agentxm/workspace-transactions";
-import { StepFailure, } from "@agentxm/workspace-operations";
-import { lifecycleStepFailure } from "../step-failure.js";
 import { installRefused } from "../install/vocabulary.js";
 const normalizedIdentity = (identity) => identity.startsWith("workspace:") ? identity.slice("workspace:".length) : identity;
-const failedStep = (label, result) => result.result === "error"
-    ? Effect.fail(result.error ??
-        lifecycleStepFailure(installRefused({
-            category: "internal",
-            detail: `${label} failed: ${result.message}`,
-        })))
-    : Effect.succeed(result);
-const aggregatePackCoverage = (results, scope) => Effect.gen(function* () {
-    const applicableArtifacts = results.flatMap(({ result, coverage }) => coverage === "eligible" &&
-        result.result === "success" &&
-        result.artifact?.agents !== undefined
-        ? [result.artifact]
-        : []);
-    const agents = [];
-    for (const artifact of applicableArtifacts) {
-        if (artifact.scope !== scope) {
-            return yield* installRefused({
-                category: "internal",
-                detail: `Pack coverage spans ${scope} and ${artifact.scope} scopes`,
-            });
-        }
-        const artifactAgents = new Set(artifact.agents);
-        for (const target of artifact.targets ?? []) {
-            for (const agent of target.agentIds ?? []) {
-                if (!artifactAgents.has(agent)) {
-                    return yield* installRefused({
-                        category: "internal",
-                        detail: `Pack child target agent ${agent} is absent from its artifact agents`,
-                    });
-                }
-            }
-        }
-        for (const agent of artifact.agents ?? []) {
-            if (agent !== "universal" && !agents.includes(agent))
-                agents.push(agent);
-        }
-    }
-    return { applicable: applicableArtifacts.length > 0, agents };
-});
-/** Wrap a pack transition's children in one workspace transaction. */
-export const buildAtomicPackGraphStep = (args) => Effect.sync(() => {
-    const readinessErrors = args.children.flatMap(({ step }) => step.readiness === "error" ? [step.errorMessage] : []);
-    if (readinessErrors.length > 0) {
-        const blockingConditionIds = args.children.flatMap(({ step }) => step.readiness === "error" ? (step.blockingConditionIds ?? []) : []);
-        return {
-            readiness: "error",
-            label: args.label,
-            errorMessage: readinessErrors.join("; "),
-            artifact: args.artifact,
-            ...(blockingConditionIds.length === 0 ? {} : { blockingConditionIds }),
-        };
-    }
-    const readinessWarnings = args.children.flatMap(({ step }) => step.readiness === "warn" ? [step.warnMessage] : []);
-    const runnableChildren = args.children.filter((child) => child.step.readiness !== "error");
-    let validatedCoverage = { applicable: false, agents: [] };
-    const run = runWorkspaceTransaction({
-        transition: Effect.gen(function* () {
-            if (args.preTransition !== undefined) {
-                yield* args.preTransition.pipe(Effect.mapError(lifecycleStepFailure));
-            }
-            return yield* Effect.forEach(runnableChildren, ({ step, coverage }) => step.run.pipe(Effect.flatMap((result) => failedStep(step.label, result)), Effect.map((result) => ({ result, coverage }))), { concurrency: 1 });
-        }),
-        validate: (results) => Effect.gen(function* () {
-            yield* args.validate;
-            validatedCoverage = yield* aggregatePackCoverage(results, args.artifact.scope);
-        }).pipe(Effect.mapError(lifecycleStepFailure)),
-    }).pipe(Effect.mapError(lifecycleStepFailure), Effect.map((results) => {
-        const warnings = results.flatMap(({ result }) => result.result === "success" ? (result.warnings ?? []) : []);
-        const allChildrenUnchanged = args.reportUnchangedWhenChildrenUnchanged === true &&
-            results.length > 0 &&
-            results.every(({ result }) => result.result === "success" && result.artifact?.change === "unchanged");
-        const artifact = allChildrenUnchanged
-            ? { ...args.artifact, change: "unchanged" }
-            : args.artifact;
-        return {
-            result: "success",
-            message: args.message,
-            artifact: !validatedCoverage.applicable
-                ? artifact
-                : { ...artifact, agents: validatedCoverage.agents },
-            ...(warnings.length === 0 ? {} : { warnings }),
-        };
-    }));
-    return readinessWarnings.length === 0
-        ? {
-            readiness: "ready",
-            label: args.label,
-            artifact: args.artifact,
-            run,
-        }
-        : {
-            readiness: "warn",
-            label: args.label,
-            warnMessage: readinessWarnings.join("; "),
-            artifact: args.artifact,
-            run,
-        };
-});
 /** The desired-graph predicate a completed pack transition must satisfy. */
 export const validatePackGraphPostcondition = (args) => Effect.gen(function* () {
     const ws = yield* WorkspaceMutations;

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

@@ -1,16 +1,3 @@
-/**
- * Installing a pack.
- *
- * A pack install is a graph transition, not a package copy: the pack's own
- * package, every member its manifest resolves to, and every member the
- * previous graph owned and this one drops all change together. Workspace
- * source authority decides whether a locally-authored package may stand in
- * for a declared member, the minimum-release-age policy decides whether a
- * held-back release preserves the current graph or blocks, and the transition
- * is refused if the authority it was planned against changed underneath it.
- *
- * @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";

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

@@ -1,3 +1,4 @@
+import { buildReconciliationClosure } from "@agentxm/workspace-reconciliation";
 /**
  * Installing a pack.
  *
@@ -16,7 +17,8 @@ import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import * as Result from "effect/Result";
-import { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager, buildInstallOperation, buildUninstallOperation, targetFromRef, toLabel, } from "@agentxm/extension-materialization";
+import { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager, } from "@agentxm/extension-materialization";
+import { buildInstallOperation, buildUninstallOperation, targetFromRef, toLabel, } from "@agentxm/workspace-reconciliation";
 import { parseExtensionFqnParts, toExtensionTypePlural, } from "@agentxm/extension-model/unstable/extensions";
 import { isWorkspaceSourceLocator } from "@agentxm/extension-model/unstable/sources/workspace";
 import { versionSatisfiesRange, } from "@agentxm/extension-model/unstable/version-constraints";
@@ -31,10 +33,10 @@ import { registryLoginSuggestions } from "../../install/registry-login-suggestio
 import { formatRegistryProbe, sourceFailureDetail, } from "../../install/registry-source-resolution.js";
 import { installRefused, } from "../../install/vocabulary.js";
 import { expandPackInstallRefs, expandPackInstallRefsWithReleaseAge } from "../expansion.js";
-import { buildAtomicPackGraphStep, validatePackGraphPostcondition } from "../graph-transition.js";
+import { validatePackGraphPostcondition } from "../graph-transition.js";
 import { buildPackMemberInstallStep } from "../member-install-step.js";
 import { registrySourceArtifact, registrySourcePath } from "../artifact.js";
-import { makeWorkspaceRetentionPolicy } from "../../uninstall/retention-policy.js";
+import { makeWorkspaceRetentionPolicy } from "@agentxm/workspace-reconciliation";
 const isRemoteReadNotImplemented = (error) => {
     const detail = sourceFailureDetail(error);
     return detail.includes("not implemented") || detail.includes("not yet supported");
@@ -661,12 +663,12 @@ export const planPackInstall = Effect.fn("InstallExtensions.planPack")(function*
     // cleanup by suppressing dropped-member removal until the pre-install graph
     // is complete.
     const existingPack = graph.complete ? currentPackNode : undefined;
-    const retentionPolicy = makeWorkspaceRetentionPolicy(ws);
+    const retentionPolicy = makeWorkspaceRetentionPolicy(ws, lifecycleStepFailure);
     const installSteps = yield* Effect.forEach(refs, (ref) => ref.type === "pack"
         ? Effect.succeed(buildInstallOperation(packManager, {
             toStepFailure: lifecycleStepFailure,
             ref,
-            versionRange: intent.versionRange,
+            declaration: { name: ref.pack.name, versionRange: intent.versionRange },
             ...(intent.forceCanonical === true ? { force: true } : {}),
             installedBefore: graph.complete
                 ? packManager.isInstalled({
@@ -724,19 +726,19 @@ export const planPackInstall = Effect.fn("InstallExtensions.planPack")(function*
                 return buildUninstallOperation(ruleManager, retentionPolicy, {
                     toStepFailure: lifecycleStepFailure,
                     target,
-                    skipProjections: true,
+                    enclosingClosure: { projections: [target.type] },
                 });
             case "hook":
                 return buildUninstallOperation(hookManager, retentionPolicy, {
                     toStepFailure: lifecycleStepFailure,
                     target,
-                    skipProjections: true,
+                    enclosingClosure: { projections: [target.type] },
                 });
             case "knowledge":
                 return buildUninstallOperation(knowledgeManager, retentionPolicy, {
                     toStepFailure: lifecycleStepFailure,
                     target,
-                    skipProjections: true,
+                    enclosingClosure: { projections: [target.type] },
                 });
         }
     });
@@ -777,7 +779,8 @@ export const planPackInstall = Effect.fn("InstallExtensions.planPack")(function*
                 ...droppedTargets.map(({ target }) => target.type),
             ]),
         });
-    const graphStep = yield* buildAtomicPackGraphStep({
+    const graphStep = yield* buildReconciliationClosure({
+        toStepFailure: lifecycleStepFailure,
         label: packIdentity,
         message: `Installed ${packIdentity} and ${refs.length - 1} pack member${refs.length === 2 ? "" : "s"}`,
         artifact: {

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

@@ -10,7 +10,9 @@
  */
 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 { HookManager, KnowledgeManager, NO_MATERIALIZATION_OBSERVATION, RuleManager, SkillManager, SubagentManager, } from "@agentxm/extension-materialization";
+import { installMcpServer } from "@agentxm/workspace-reconciliation";
+import { buildInstallOperation, extensionRefLifecycleWarnings, extensionRefRegistryLifecycle, toLabelWithCompanions, } from "@agentxm/workspace-reconciliation";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
 import { lifecycleStepFailure } from "../step-failure.js";
 import { registrySourceArtifact } from "./artifact.js";
@@ -28,9 +30,7 @@ export const buildPackMemberInstallStep = Effect.fn("InstallExtensions.buildPack
         return buildInstallOperation(skillManager, {
             toStepFailure: lifecycleStepFailure,
             ref,
-            versionRange: Option.none(),
-            skipSettings: true,
-            deferObservableValidation: true,
+            enclosingClosure: { projections: [], postconditions: [ref.type] },
             installedBefore: args.graphComplete
                 ? skillManager.isInstalled({ target: { type: "skill", name: ref.skill.name } })
                 : Effect.succeed(false),
@@ -55,8 +55,6 @@ export const buildPackMemberInstallStep = Effect.fn("InstallExtensions.buildPack
                     ref,
                     nonInteractive: args.nonInteractive,
                     force: false,
-                    versionRange: Option.none(),
-                    skipSettings: Option.some(true),
                     strictAgentSync: Option.some(true),
                     env: Option.none(),
                 },
@@ -82,9 +80,7 @@ export const buildPackMemberInstallStep = Effect.fn("InstallExtensions.buildPack
         return buildInstallOperation(subagentManager, {
             toStepFailure: lifecycleStepFailure,
             ref,
-            versionRange: Option.none(),
-            skipSettings: true,
-            deferObservableValidation: true,
+            enclosingClosure: { projections: [], postconditions: [ref.type] },
             installedBefore: args.graphComplete
                 ? subagentManager.isInstalled({ target: { type: "subagent", name: ref.subagent.name } })
                 : Effect.succeed(false),
@@ -104,10 +100,7 @@ export const buildPackMemberInstallStep = Effect.fn("InstallExtensions.buildPack
         return buildInstallOperation(ruleManager, {
             toStepFailure: lifecycleStepFailure,
             ref,
-            versionRange: Option.none(),
-            skipSettings: true,
-            skipProjections: true,
-            deferObservableValidation: true,
+            enclosingClosure: { projections: [ref.type], postconditions: [ref.type] },
             installedBefore: args.graphComplete
                 ? ruleManager.isInstalled({ target: { type: "rule", name: ref.rule.name } })
                 : Effect.succeed(false),
@@ -124,10 +117,7 @@ export const buildPackMemberInstallStep = Effect.fn("InstallExtensions.buildPack
         return buildInstallOperation(hookManager, {
             toStepFailure: lifecycleStepFailure,
             ref,
-            versionRange: Option.none(),
-            skipSettings: true,
-            skipProjections: true,
-            deferObservableValidation: true,
+            enclosingClosure: { projections: [ref.type], postconditions: [ref.type] },
             installedBefore: args.graphComplete
                 ? hookManager.isInstalled({ target: { type: "hook", name: ref.hook.name } })
                 : Effect.succeed(false),
@@ -143,10 +133,7 @@ export const buildPackMemberInstallStep = Effect.fn("InstallExtensions.buildPack
     return buildInstallOperation(knowledgeManager, {
         toStepFailure: lifecycleStepFailure,
         ref,
-        versionRange: Option.none(),
-        skipSettings: true,
-        skipProjections: true,
-        deferObservableValidation: true,
+        enclosingClosure: { projections: [ref.type], postconditions: [ref.type] },
         installedBefore: args.graphComplete
             ? knowledgeManager.isInstalled({ target: { type: "knowledge", name: ref.knowledge.name } })
             : Effect.succeed(false),

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

@@ -1,3 +1,4 @@
+import { buildReconciliationClosure } from "@agentxm/workspace-reconciliation";
 /**
  * Unpacking a Pack: promoting its members to direct declarations.
  *
@@ -22,12 +23,13 @@
 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 { PackManager } from "@agentxm/extension-materialization";
+import { buildUninstallOperation, } from "@agentxm/workspace-reconciliation";
 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";
+import { validatePackGraphPostcondition } from "./graph-transition.js";
 // -----------------------------------------------------------------------------
 // Promotion
 // -----------------------------------------------------------------------------
@@ -186,7 +188,8 @@ const settleUnpack = Effect.fn("PromoteAuthoredPack.prepare")(function* (request
         })),
         { path: packDisplayPath(path, ws, packNode), change: "removed" },
     ];
-    const graphStep = yield* buildAtomicPackGraphStep({
+    const graphStep = yield* buildReconciliationClosure({
+        toStepFailure: lifecycleStepFailure,
         label: packNode.identity,
         message: `Unpacked ${packNode.identity} into ${promotions.length} direct declaration${promotions.length === 1 ? "" : "s"}`,
         artifact: {

package/dist/src/packs/uninstall/plan.js

@@ -1,3 +1,4 @@
+import { buildReconciliationClosure } from "@agentxm/workspace-reconciliation";
 /**
  * Uninstalling packs.
  *
@@ -13,7 +14,8 @@ 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 { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager, buildUninstallOperation, toLabel, } from "@agentxm/extension-materialization";
+import { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager, } from "@agentxm/extension-materialization";
+import { buildUninstallOperation, prepareUninstallArtifact, collectCleanupStep, proposeDesiredState, } from "@agentxm/workspace-reconciliation";
 import { parseExtensionFqnParts, } from "@agentxm/extension-model/unstable/extensions";
 import { operationPresentation, } from "@agentxm/workspace-operations";
 import { WorkspaceMutations, decodeDesiredExtensionIdentity, } from "@agentxm/workspace-state";
@@ -21,9 +23,8 @@ import { expandGlob } from "../../glob.js";
 import { lifecycleStepFailure } from "../../step-failure.js";
 import { buildAggregateProjectionStep } from "../../install/aggregate-projection-step.js";
 import { installRefused } from "../../install/vocabulary.js";
-import { exclusiveMemberRetentionPolicy, makeWorkspaceRetentionPolicy, } from "../../uninstall/retention-policy.js";
-import { workspaceCanonicalNodePath } from "../../workspace-paths.js";
-import { buildAtomicPackGraphStep, validatePackGraphPostcondition } from "../graph-transition.js";
+import { exclusiveMemberRetentionPolicy, makeWorkspaceRetentionPolicy, } from "@agentxm/workspace-reconciliation";
+import { validatePackGraphPostcondition } from "../graph-transition.js";
 import { PACK_UNINSTALL_GRAPH_BLOCKER_ID, planPackUninstallGraphReadiness, } from "./readiness.js";
 const normalizedPackIdentity = (identity) => identity.startsWith("workspace:") ? identity.slice("workspace:".length) : identity;
 const identityValidationError = (identity) => installRefused({
@@ -211,7 +212,7 @@ export const planPackUninstall = Effect.fn("UninstallExtensions.planPacks")(func
         const retirement = retirementByIdentity.get(normalizedPackIdentity(pack.desiredIdentity));
         return retirement === undefined ? [] : [[pack.name, retirement]];
     }));
-    const retentionPolicy = makeWorkspaceRetentionPolicy(ws);
+    const retentionPolicy = makeWorkspaceRetentionPolicy(ws, lifecycleStepFailure);
     const allTargets = new Map();
     for (const pack of intent.packsToUninstall) {
         allTargets.set(`pack:${pack.name}`, pack);
@@ -234,10 +235,19 @@ export const planPackUninstall = Effect.fn("UninstallExtensions.planPacks")(func
     const packTargets = [...allTargets.values()].filter((target) => target.type === "pack");
     const depTargets = [...allTargets.values()].filter((target) => target.type !== "pack");
     const orderedTargets = [...depTargets, ...packTargets];
-    const sourcePathByTarget = new Map(graph.nodes.map((node) => [
-        `${node.type}:${node.name}`,
-        workspaceCanonicalNodePath(path, ws, node),
-    ]));
+    const proposal = yield* proposeDesiredState(intent.packsToUninstall.map((pack) => ({ kind: "remove", type: "pack", name: pack.name }))).pipe(Effect.mapError((cause) => installRefused({
+        category: "conflict",
+        detail: "Pack retirement intent could not be evaluated",
+        cause,
+    })));
+    const artifacts = yield* Effect.forEach(orderedTargets, (target) => prepareUninstallArtifact(target, proposal)).pipe(Effect.mapError((cause) => installRefused({
+        category: "conflict",
+        detail: "Pack retirement effects could not be established",
+        cause,
+    })));
+    const artifactTargets = artifacts
+        .flatMap((artifact) => artifact.targets ?? [])
+        .filter((target, index, all) => all.findIndex((candidate) => candidate.path === target.path && candidate.change === target.change) === index);
     const steps = orderedTargets.map((target) => {
         switch (target.type) {
             case "pack": {
@@ -276,44 +286,66 @@ export const planPackUninstall = Effect.fn("UninstallExtensions.planPacks")(func
                 return buildUninstallOperation(ruleManager, exclusiveMemberRetentionPolicy, {
                     toStepFailure: lifecycleStepFailure,
                     target,
-                    skipProjections: true,
+                    enclosingClosure: { projections: [target.type] },
                 });
             case "hook":
                 return buildUninstallOperation(hookManager, exclusiveMemberRetentionPolicy, {
                     toStepFailure: lifecycleStepFailure,
                     target,
-                    skipProjections: true,
+                    enclosingClosure: { projections: [target.type] },
                 });
             case "knowledge":
                 return buildUninstallOperation(knowledgeManager, exclusiveMemberRetentionPolicy, {
                     toStepFailure: lifecycleStepFailure,
                     target,
-                    skipProjections: true,
+                    enclosingClosure: { projections: [target.type] },
                 });
         }
     });
+    const activeNames = (type) => new Set(proposal.after.nodes
+        .filter((node) => node.type === type && node.enabled)
+        .map((node) => node.name));
+    const cleanup = plannedRetirements.length > 0
+        ? Option.none()
+        : yield* collectCleanupStep({
+            expectedSkillNames: activeNames("skill"),
+            expectedSubagentNames: activeNames("subagent"),
+            expectedMcpServerNames: activeNames("mcp-server"),
+            expectedHookNames: activeNames("hook"),
+            subjects: orderedTargets,
+            adapter: {
+                toStepFailure: (cause) => lifecycleStepFailure(installRefused({
+                    category: "conflict",
+                    detail: ("detail" in cause ? cause.detail : undefined) ?? cause._tag,
+                    cause,
+                })),
+            },
+        }).pipe(Effect.mapError((cause) => installRefused({
+            category: "conflict",
+            detail: "Cannot establish owned Pack uninstall outputs",
+            cause,
+        })));
     const projectionStep = yield* buildAggregateProjectionStep({
         types: new Set(orderedTargets.map((target) => target.type)),
     });
     const registrationOnly = plannedRetirements.length === 0
         ? ""
         : ` (${plannedRetirements.length} pack${plannedRetirements.length === 1 ? "" : "s"} unregistered without removing package content)`;
-    const graphStep = yield* buildAtomicPackGraphStep({
+    const graphStep = yield* buildReconciliationClosure({
+        toStepFailure: lifecycleStepFailure,
         label: `${intent.packsToUninstall.length} pack${intent.packsToUninstall.length === 1 ? "" : "s"}`,
         message: `Uninstalled ${intent.packsToUninstall.length} pack${intent.packsToUninstall.length === 1 ? "" : "s"} and ${depTargets.length} exclusive member${depTargets.length === 1 ? "" : "s"}${registrationOnly}`,
         artifact: {
-            path: "pack graph",
+            path: artifacts[0]?.path ?? path.relative(ws.baseDir, ws.layout.settingsPath),
             scope: ws.scope,
             change: "removed",
             fileCount: orderedTargets.length,
-            targets: orderedTargets.map((target) => ({
-                path: sourcePathByTarget.get(`${target.type}:${target.name}`) ?? toLabel(target),
-                // Content AXM could not verify is preserved, so its canonical path is
-                // never reported as removed.
-                change: target.type === "pack" && retirementByPackName.has(target.name) ? "unchanged" : "removed",
-            })),
+            targets: artifactTargets,
+            references: artifacts.flatMap((artifact) => artifact.references ?? []),
+            managedRegions: artifacts.flatMap((artifact) => artifact.managedRegions ?? []),
         },
         children: [
+            ...Option.toArray(cleanup).map((step) => ({ step, coverage: "ineligible" })),
             ...steps.map((step) => ({ step, coverage: "ineligible" })),
             ...Option.toArray(projectionStep).map((step) => ({
                 step,

package/dist/src/rules/install/plan.js

@@ -9,7 +9,8 @@
  */
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import { RuleManager, buildInstallOperation } from "@agentxm/extension-materialization";
+import { RuleManager } from "@agentxm/extension-materialization";
+import { buildInstallOperation } from "@agentxm/workspace-reconciliation";
 import { parseSourceQualifiedRegistrySourcePatternParts, } from "@agentxm/extension-model/unstable/extensions";
 import { SourceHostProviders, resolveSource } from "@agentxm/extension-sources";
 import { operationPresentation, } from "@agentxm/workspace-operations";
@@ -86,8 +87,10 @@ export const planRuleInstall = Effect.fn("InstallExtensions.planRules")(function
     const memberSteps = intent.refs.map(({ ref, versionRange }) => buildInstallOperation(ruleManager, {
         toStepFailure: lifecycleStepFailure,
         ref,
-        versionRange,
-        skipProjections: deferProjections,
+        declaration: { name: ref.rule.name, versionRange },
+        ...(deferProjections
+            ? { enclosingClosure: { projections: [ref.type], postconditions: [] } }
+            : {}),
         installedBefore: ruleManager.isInstalled({
             target: { type: "rule", name: ref.rule.name },
         }),

package/dist/src/rules/uninstall/plan.js

@@ -8,11 +8,12 @@
  */
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import { RuleManager, buildUninstallOperation } from "@agentxm/extension-materialization";
+import { RuleManager } from "@agentxm/extension-materialization";
+import { buildUninstallOperation } from "@agentxm/workspace-reconciliation";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
 import { lifecycleStepFailure } from "../../step-failure.js";
 import { installRefused } from "../../install/vocabulary.js";
-import { makeWorkspaceRetentionPolicy } from "../../uninstall/retention-policy.js";
+import { makeWorkspaceRetentionPolicy } from "@agentxm/workspace-reconciliation";
 /** Settle whether this rule has anything to remove. */
 export const parseRuleUninstallRequest = Effect.fn("UninstallExtensions.parseRuleRequest")(function* (selector) {
     const ruleManager = yield* RuleManager;
@@ -35,7 +36,7 @@ export const parseRuleUninstallRequest = Effect.fn("UninstallExtensions.parseRul
 export const planRuleUninstall = Effect.fn("UninstallExtensions.planRules")(function* (intent) {
     const ws = yield* WorkspaceMutations;
     const ruleManager = yield* RuleManager;
-    const retentionPolicy = makeWorkspaceRetentionPolicy(ws);
+    const retentionPolicy = makeWorkspaceRetentionPolicy(ws, lifecycleStepFailure);
     return {
         _tag: "Plan",
         name: "Uninstall rule",

package/dist/src/skills/install/bundled.js

@@ -1,3 +1,4 @@
+import { renderAxmSkillRecovery } from "@agentxm/cli-maintenance/official-skill/adapters/cli";
 /**
  * Installing the official AXM skill that ships inside the CLI.
  *
@@ -16,7 +17,7 @@ import * as FileSystem from "effect/FileSystem";
 import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import { ensureSkillAgentArtifact, replaceCanonicalDirectory, } from "@agentxm/extension-materialization";
-import { AXM_SKILL_CLI_VERSION_METADATA_KEY, AXM_SKILL_CLI_VERSION_RANGE_METADATA_KEY, AXM_SKILL_FQN, evaluateAxmSkillCompatibility, } from "@agentxm/extension-resolution";
+import { AXM_SKILL_CLI_VERSION_METADATA_KEY, AXM_SKILL_CLI_VERSION_RANGE_METADATA_KEY, AXM_SKILL_FQN, evaluateAxmSkillCompatibility, } from "@agentxm/cli-maintenance/official-skill/domain";
 import { operationPresentation, } from "@agentxm/workspace-operations";
 import { CodingAgentRepository } from "@agentxm/workspace-projection";
 import { WorkspaceMutations, sanitizeName } from "@agentxm/workspace-state";
@@ -173,13 +174,12 @@ export const installBundledAxmSkill = Effect.gen(function* () {
                 },
             });
             if (compatibility.status === "incompatible") {
+                const recovery = renderAxmSkillRecovery(compatibility.recovery);
                 return yield* installRefused({
                     category: "internal",
                     detail: compatibility.detail ??
                         "Bundled AXM skill remained incompatible after workspace installation",
-                    ...(compatibility.recovery.nextAction === null
-                        ? {}
-                        : { cmd: compatibility.recovery.nextAction }),
+                    ...(recovery.nextAction === null ? {} : { cmd: recovery.nextAction }),
                 });
             }
         }),

package/dist/src/skills/install/plan.js

@@ -17,7 +17,8 @@ import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
-import { SkillManager, artifactAgentIdsFromTargets, artifactTargetAgentIds, buildInstallOperation, computeSkillSourceHash, groupInstallTargetsByDirectory, } from "@agentxm/extension-materialization";
+import { SkillManager, artifactAgentIdsFromTargets, artifactTargetAgentIds, computeSkillSourceHash, groupInstallTargetsByDirectory, } from "@agentxm/extension-materialization";
+import { buildInstallOperation } from "@agentxm/workspace-reconciliation";
 import { matchesReleaseAgeExcludePattern, } from "@agentxm/extension-model/unstable/extensions";
 import { PackageUrlPartsSchema, formatPackageDisplay, } from "@agentxm/extension-model/unstable/packaging";
 import { parseInputPattern, } from "@agentxm/extension-model/unstable/sources/parser";
@@ -379,7 +380,7 @@ export const planSkillInstall = Effect.fn("InstallExtensions.planSkills")(functi
         return withPlanWarning(buildInstallOperation(skillManager, {
             toStepFailure: lifecycleStepFailure,
             ref,
-            versionRange: entry.versionRange,
+            declaration: { name: ref.skill.name, versionRange: entry.versionRange },
             force: intent.force === true,
             installedBefore: Effect.succeed(installedBefore),
             buildArtifact: ({ installedBefore }) => Effect.gen(function* () {

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

@@ -30,7 +30,6 @@ export type InstallSkillOperationArgs = {
     /** Version constraint from the original input when available. */
     readonly versionRange: Option.Option<string>;
     /** When true, write to lockfile only (skip settings). Used for pack dependencies. */
-    readonly skipSettings: Option.Option<boolean>;
     /** When true, fail on unknown configured agents instead of warning+skip. */
     readonly strictUnknownAgents: Option.Option<boolean>;
     /** Named registry source that provided the ref (written to lockfile for registry skills). */

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

@@ -529,25 +529,16 @@ export const installSkill = (op) => Effect.gen(function* () {
             }),
         };
     }
-    const skipSettings = Option.getOrElse(op.args.skipSettings, () => false);
     const writeEffect = baseLockEntry === undefined
-        ? skipSettings
-            ? Effect.void
-            : ws.setSkillEntry(ref.skill.name, {
-                source: ref.refType === "workspace" ? "workspace" : printSourceParams(ref.source),
-                enabled: true,
-            })
-        : skipSettings
-            ? ws.setSkillLock({
-                name: ref.skill.name,
-                lockEntry: baseLockEntry,
-                versionRange: materialized.versionRange,
-            })
-            : ws.setSkill({
-                name: ref.skill.name,
-                lockEntry: baseLockEntry,
-                versionRange: materialized.versionRange,
-            });
+        ? ws.setSkillEntry(ref.skill.name, {
+            source: ref.refType === "workspace" ? "workspace" : printSourceParams(ref.source),
+            enabled: true,
+        })
+        : ws.setSkill({
+            name: ref.skill.name,
+            lockEntry: baseLockEntry,
+            versionRange: materialized.versionRange,
+        });
     const writeFailure = yield* writeEffect.pipe(Effect.result);
     if (writeFailure._tag === "Failure") {
         const failure = writeFailure.failure;

package/dist/src/skills/uninstall/plan.js

@@ -12,14 +12,15 @@ 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 { SkillManager, buildUninstallOperation, skillArtifactFromTargets, } from "@agentxm/extension-materialization";
+import { SkillManager, skillArtifactFromTargets, } from "@agentxm/extension-materialization";
+import { buildUninstallOperation } from "@agentxm/workspace-reconciliation";
 import { resolveInstalledIdentifierNameOrInput } from "@agentxm/extension-sources";
 import { CodingAgentRepository } from "@agentxm/workspace-projection";
 import { WorkspaceMutations, acquiredExtensionDisplayPathFromLockEntry, installedRowsByName, sanitizeName, } from "@agentxm/workspace-state";
 import { expandGlob } from "../../glob.js";
 import { lifecycleStepFailure } from "../../step-failure.js";
 import { installRefused, } from "../../install/vocabulary.js";
-import { makeWorkspaceRetentionPolicy } from "../../uninstall/retention-policy.js";
+import { makeWorkspaceRetentionPolicy } from "@agentxm/workspace-reconciliation";
 import { workspaceAuthoredPath, workspaceCanonicalPath, workspaceCanonicalRoot, workspaceLockfilePath, workspaceSettingsPath, } from "../../workspace-paths.js";
 const skillSourceTarget = (ws, path, configuredSource, lockEntry, sanitizedName) => {
     if (Option.isSome(configuredSource) && configuredSource.value === "workspace") {
@@ -69,7 +70,7 @@ export const planSkillUninstall = Effect.fn("UninstallExtensions.planSkills")(fu
     const skillManager = yield* SkillManager;
     const agentRepo = yield* CodingAgentRepository;
     const path = yield* Path.Path;
-    const retentionPolicy = makeWorkspaceRetentionPolicy(ws);
+    const retentionPolicy = makeWorkspaceRetentionPolicy(ws, lifecycleStepFailure);
     const configuredAgents = yield* agentRepo.getMaterializationAgents().pipe(Effect.mapError((cause) => installRefused({
         category: "internal",
         detail: "Configured agents could not be read",

package/dist/src/subagents/install/plan.js

@@ -10,7 +10,8 @@
 import * as Array from "effect/Array";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import { NO_MATERIALIZATION_OBSERVATION, SubagentManager, buildInstallOperation, } from "@agentxm/extension-materialization";
+import { NO_MATERIALIZATION_OBSERVATION, SubagentManager, } from "@agentxm/extension-materialization";
+import { buildInstallOperation } from "@agentxm/workspace-reconciliation";
 import { parseInputPattern, } from "@agentxm/extension-model/unstable/sources/parser";
 import { SourceHostProviders, sourceResolutionFailureCategory, } from "@agentxm/extension-sources";
 import { operationPresentation, } from "@agentxm/workspace-operations";
@@ -216,7 +217,7 @@ export const planSubagentInstall = Effect.fn("InstallExtensions.planSubagents")(
         return buildInstallOperation(subagentManager, {
             toStepFailure: lifecycleStepFailure,
             ref,
-            versionRange: entry.versionRange,
+            declaration: { name: ref.subagent.name, versionRange: entry.versionRange },
             installedBefore: subagentManager
                 .isInstalled({ target: { type: "subagent", name: ref.subagent.name } })
                 .pipe(Effect.catch(() => Effect.succeed(false))),