@agentxm/extension-materialization 0.29.4 → 0.30.1

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

@@ -1,8 +1,3 @@
-/**
- * Hook manager service.
- *
- * @experimental This API is unstable and may change without notice.
- */
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";

package/dist/src/hooks/manager.js

@@ -1,3 +1,5 @@
+import { usableAcceptedCanonical } from "@agentxm/workspace-state";
+import { LifecyclePostconditionViolated } from "../extensions/errors.js";
 /**
  * Hook manager service.
  *
@@ -511,13 +513,20 @@ export const HookManagerLive = Layer.effect(HookManager, Effect.gen(function* ()
                 .map(({ marker }) => marker),
         };
     });
-    const makeHookProjectionPlans = () => Effect.gen(function* () {
+    const makeHookProjectionPlans = (prospective = []) => Effect.gen(function* () {
         const configuredAgents = yield* ws.getConfiguredAgents();
         const targets = yield* configuredHookWriterTargets(configuredAgents, (configPath) => path.resolve(baseDir, configPath));
         const fallbackTarget = yield* hookFallbackTarget();
         const graph = yield* ws.getDesiredStateGraph();
         const locked = yield* ws.getLockedHooks();
-        const contributors = yield* selectHookContributors({ graph, locked });
+        const retained = yield* selectHookContributors({
+            graph: {
+                ...graph,
+                nodes: graph.nodes.filter((node) => node.type !== "hook" || !prospective.some(({ name }) => name === node.name)),
+            },
+            locked,
+        });
+        const contributors = [...retained, ...prospective].sort((a, b) => a.marker.localeCompare(b.marker));
         const outcomes = evaluateConfiguredOutcomes({
             configuredAgents,
             targets,
@@ -590,11 +599,11 @@ export const HookManagerLive = Layer.effect(HookManager, Effect.gen(function* ()
         });
         return [...nativePlans, fallbackPlan];
     });
-    const configuredAgentOutcomes = (state) => Effect.gen(function* () {
+    const configuredAgentOutcomes = (state, proposedGraph) => Effect.gen(function* () {
         const configuredAgents = yield* ws.getConfiguredAgents();
         const targets = yield* configuredHookWriterTargets(configuredAgents, (configPath) => path.resolve(baseDir, configPath));
         const fallbackTarget = yield* hookFallbackTarget();
-        const graph = yield* ws.getDesiredStateGraph();
+        const graph = proposedGraph ?? (yield* ws.getDesiredStateGraph());
         const locked = yield* ws.getLockedHooks();
         const contributors = yield* selectHookContributors({ graph, locked });
         return evaluateConfiguredOutcomes({
@@ -625,6 +634,45 @@ export const HookManagerLive = Layer.effect(HookManager, Effect.gen(function* ()
             state,
         });
     });
+    const prepareProjection = (refs) => Effect.gen(function* () {
+        const prepared = yield* Effect.forEach(refs, (ref) => Effect.scoped(Effect.gen(function* () {
+            const root = ref.refType === "registry"
+                ? (yield* sources.fetch(ref)).directory
+                : stripFileProtocol(ref.location);
+            const manifest = yield* readManifest(root);
+            const entrypoint = path.resolve(root, manifest.entrypoint);
+            yield* validatePathSafety(path, root, entrypoint);
+            if (!(yield* fs.exists(entrypoint)))
+                return yield* new HookDefinitionInvalid({
+                    detail: `Hook entrypoint does not exist: ${manifest.entrypoint}`,
+                });
+            const canonicalPath = computeExtensionPathsForLayout(path.join, ws.layout, ref, HOOK_EXTENSION_DIR, ref.hook.name).canonicalPath;
+            const commandPath = path.relative(baseDir, path.resolve(canonicalPath, manifest.entrypoint));
+            return {
+                name: ref.hook.name,
+                marker: formatFqn({ owner: manifest.owner, type: "hook", name: manifest.name }),
+                manifest,
+                command: `${interpreterForRuntime(manifest.runtime)} ${commandPath}`,
+                treeIntegrity: yield* computeMaterializedTreeIntegrity(root),
+            };
+        })), { concurrency: 1 });
+        const configuredAgents = yield* ws.getConfiguredAgents();
+        const targets = yield* configuredHookWriterTargets(configuredAgents, (configPath) => path.resolve(baseDir, configPath));
+        const fallbackTarget = yield* hookFallbackTarget();
+        return {
+            plans: yield* makeHookProjectionPlans(prepared),
+            agentOutcomes: evaluateConfiguredOutcomes({
+                configuredAgents,
+                targets,
+                fallbackPath: fallbackTarget.workspaceRelative,
+                contributors: prepared,
+                state: "projected",
+            }),
+            acquisitions: prepared.map(({ name, treeIntegrity }) => ({ name, treeIntegrity })),
+        };
+    }).pipe(Effect.mapError((cause) => cause._tag === "PlatformError"
+        ? new HookDefinitionInvalid({ detail: "Cannot inspect prepared hook content", cause })
+        : cause));
     const projectionPlans = () => makeHookProjectionPlans();
     const applyHookProjections = projectionPlans().pipe(Effect.flatMap(applyProjectionPlans));
     const materializeInstall = Effect.fn("HookManager.materializeInstall")(function* ({ ref }) {
@@ -705,11 +753,28 @@ export const HookManagerLive = Layer.effect(HookManager, Effect.gen(function* ()
     return {
         type: "hook",
         projectionPlans,
+        prepareProjection,
         aggregateProjectionObservation: Ref.get(lastProjection),
         configuredAgentOutcomes,
         configuredAgentOutcomesForRef,
         isInstalled: ({ target }) => isObservedInstalled(ws, "hook", target.name).pipe(Effect.withSpan("HookManager.isInstalled")),
         materializeInstall,
+        acquireCanonical: materializeInstall,
+        materializeRetained: ({ target }) => Effect.gen(function* () {
+            const canonical = yield* usableAcceptedCanonical({
+                workspace: ws,
+                type: "hook",
+                name: target.name,
+            });
+            if (Option.isNone(canonical) || canonical.value.ref.type !== "hook") {
+                return yield* new LifecyclePostconditionViolated({
+                    postcondition: "materialize-observable",
+                    targetType: "hook",
+                    targetName: target.name,
+                });
+            }
+            return yield* materializeInstall({ ref: canonical.value.ref });
+        }),
         prepareSourceTransition: ({ ref }) => provide(prepareAcceptedCanonicalTransition({
             workspace: ws,
             type: "hook",
@@ -734,45 +799,17 @@ export const HookManagerLive = Layer.effect(HookManager, Effect.gen(function* ()
         }),
         materializeUninstall,
         materializeDeactivate,
-        upsertSettingsEntry: Effect.fn("HookManager.upsertSettingsEntry")(function* ({ ref, versionRange, materialization, }) {
-            const lockEntry = yield* buildLockEntry(ref, materialization);
-            if (Option.isNone(lockEntry)) {
-                yield* ws.setHookEntry(ref.hook.name, {
-                    source: "workspace",
-                    enabled: true,
-                });
-                return;
-            }
-            if (lockEntry.value.type === "registry") {
-                yield* validateExactResolvedVersion(`hooks.${ref.hook.name}.resolvedVersion`, lockEntry.value.resolvedVersion);
-            }
-            yield* ws.setHook({
-                name: ref.hook.name,
-                lockEntry: lockEntry.value,
-                versionRange,
-            });
-        }),
-        removeSettingsEntry: Effect.fn("HookManager.removeSettingsEntry")(function* ({ target }) {
-            yield* ws.removeHookSettings(target.name);
-        }),
-        upsertLockfileEntry: Effect.fn("HookManager.upsertLockfileEntry")(function* ({ ref, materialization, }) {
+        acceptedResolution: Effect.fn("HookManager.acceptedResolution")(function* ({ ref, materialization, }) {
             const entry = yield* buildLockEntry(ref, materialization);
             if (Option.isNone(entry)) {
-                yield* ws.removeHookLock(ref.hook.name);
-                return;
+                return Option.none();
             }
             if (ref.refType === "registry") {
                 yield* validateExactResolvedVersion(`hooks.${ref.hook.name}.resolvedVersion`, ref.version);
             }
-            yield* ws.setHookLock({
-                name: ref.hook.name,
-                lockEntry: entry.value,
-                versionRange: Option.none(),
-            });
-        }),
-        removeLockfileEntry: Effect.fn("HookManager.removeLockfileEntry")(function* ({ target }) {
-            yield* ws.removeHookLock(target.name);
+            return Option.some({ key: ref.hook.name, entry: entry.value });
         }),
+        withdrawnResolutionKeys: ({ target }) => Effect.succeed([target.name]),
     };
 }));
 //# sourceMappingURL=manager.js.map

package/dist/src/index.d.ts

@@ -13,7 +13,7 @@
  */
 export { NO_MATERIALIZATION_OBSERVATION, type ExtensionManager, type ManagerRequirements, type MaterializationFacts, type MaterializationObservation, } from "./manager-contract.js";
 export { ExtensionManagers, type ExtensionManagersService } from "./manager-registry.js";
-export { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager, type AcquiredContentFacts, type HookManagerService, type HookMaterializationFacts, type KnowledgeManagerService, type KnowledgeMaterializationFacts, type KnowledgeSyncResult, type McpServerMaterializationFacts, type McpServerManagerService, type PackMaterializationFacts, type RuleManagerService, type RuleMaterializationFacts, type SkillMaterializationFacts, type SubagentManagerService, type SubagentMaterializationFacts, } from "./managers.js";
+export { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager, type AcquiredContentFacts, type HookManagerService, type PreparedHookProjection, type HookMaterializationFacts, type KnowledgeManagerService, type KnowledgeMaterializationFacts, type KnowledgeSyncResult, type McpServerMaterializationFacts, type McpServerManagerService, type PackMaterializationFacts, type RuleManagerService, type RuleMaterializationFacts, type SkillMaterializationFacts, type SubagentManagerService, type SubagentMaterializationFacts, } from "./managers.js";
 export type { ExtensionManagerFailure, ExtensionMaterializationError } from "./errors.js";
 export { ArchiveIntegrityMismatch, CanonicalPackageProbeFailed, CreateDestinationExists, LifecyclePostconditionViolated, PackageCopyFailed, PackageMaterializationFailed, ScaffoldedExtensionUnresolved, StagedPackageInvalid, type MaterializationError, } from "./extensions/errors.js";
 export { HookDefinitionInvalid, HookInstallStateMissing, type HookManagerError, } from "./hooks/errors.js";
@@ -23,8 +23,6 @@ export { SubagentContentUnreadable, SubagentDefinitionInvalid, SubagentInstallSt
 export { SkillDefinitionInvalid, SkillInstallStateMissing, SkillMaterializationFailed, type SkillManagerError, } from "./skills/errors.js";
 export { PackArchiveFetchFailed, PackDefinitionInvalid, PackInstallStateMissing, PackStagingFailed, type PackManagerError, } from "./packs/errors.js";
 export { KnowledgeDefinitionInvalid, KnowledgeDesiredStateUnreconcilable, KnowledgeInstallStateMissing, KnowledgeIoFailed, KnowledgeObservableContractViolated, KnowledgeResolutionMissing, KnowledgeUnavailable, type KnowledgeManagerError, } from "./knowledge/errors.js";
-export { collectSecretInputNames, deleteMcpSecrets, installMcpServer, readMcpServerManifest, type InstallMcpServerOperation, type InstallMcpServerOperationArgs, type McpSecretDeletionOutcome, type McpServerInstallRequirements, } from "./mcps/install-operation.js";
-export { materializeAuthoredMcpServer } from "./mcps/authored-materialization.js";
 export { NativeMcpEntryRetirementFailed, retireNativeMcpEntry, type NativeMcpEntryRef, } from "./mcps/native-entry.js";
 export { MCP_SECRET_SERVICE, McpSecretStore, mcpSecretAccount, type McpSecretEraseOutcome, type McpSecretIdentity, type McpSecretStoreService, type McpSecretWriteOutcome, } from "./mcps/secret-store.js";
 export { MCP_AGENT_CONFIG_SURFACE, agentConfigTarget, agentConfigTargets, mcpConfigSurface, mcpServerArtifact, mcpServerSourcePath, mcpServerVersion, mcpSettingsTarget, mcpSourceTarget, type AgentMcpConfigOutcome, } from "./mcps/artifact.js";
@@ -37,8 +35,5 @@ export { shouldReuseCanonicalInstall } from "./extensions/canonical-reuse.js";
 export { configuredMcpServersToDiskRefs, configuredPacksToDiskRefs, configuredSkillsToDiskRefs, configuredSubagentsToDiskRefs, } from "./extensions/materializable-from-disk.js";
 export { canReuseExternalPackage, canReuseInstalledPackage, canonicalMaterializationPaths, createCanonicalDirectory, materializeExternalPackage, materializeExternalPackageWithTreeIntegrity, recoverCanonicalDirectory, replaceCanonicalDirectory, replaceCanonicalDirectoryWithInspection, type CanReuseExternalPackageArgs, type CanReuseInstalledPackageArgs, type CanonicalDirectoryInspection, type CanonicalDirectoryReplacementError, type CreateCanonicalDirectoryArgs, type MaterializeExternalPackageArgs, type MaterializedPackage, type RecoverCanonicalDirectoryArgs, type ReplaceCanonicalDirectoryArgs, type ReplaceCanonicalDirectoryWithInspectionArgs, } from "./extensions/canonical-directory.js";
 export { materializeRegistryPackage, materializeRegistryPackageWithTreeIntegrity, type MaterializeRegistryPackageArgs, type RegistryPackageMaterializationMessages, } from "./registry-materialization.js";
-export { buildAuthoredExtensionStep, buildInstallOperation, buildMaterializeOperation, buildNewExtensionStep, buildUninstallOperation, extensionRefLifecycleWarnings, extensionRefRegistryLifecycle, formatPackageUrlParts, targetFromRef, toLabel, toLabelWithCompanions, toStepKey, type AuthoredExtensionOperationArgs, type CallerStepFailure, type InstallOperationArgs, type MaterializeOperationArgs, type NewExtensionOperationArgs, type RecipeRequirements, type StepFailureAdapter, type UninstallOperationArgs, type UninstallRetentionPolicy, type UninstallSettlement, type UnreadablePackageRetirement, } from "./extensions/operations.js";
-export { RetainedContentUnusable } from "./desired-state/errors.js";
-export { collectRetainedMaterializeSteps, type RetainedMaterializeFailure, type RetainedMaterializeRequirements, type RetainedMaterializeSteps, type RunRetainedMcpServerInstall, } from "./desired-state/retained-materialization.js";
 export { projectionErrorToStepFailure } from "./projection-step-failure.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -28,8 +28,6 @@ export { PackArchiveFetchFailed, PackDefinitionInvalid, PackInstallStateMissing,
 export { KnowledgeDefinitionInvalid, KnowledgeDesiredStateUnreconcilable, KnowledgeInstallStateMissing, KnowledgeIoFailed, KnowledgeObservableContractViolated, KnowledgeResolutionMissing, KnowledgeUnavailable, } from "./knowledge/errors.js";
 // MCP server installation: the operation four surfaces share, its credential
 // port, and the artifact/target vocabulary the plan step reports.
-export { collectSecretInputNames, deleteMcpSecrets, installMcpServer, readMcpServerManifest, } from "./mcps/install-operation.js";
-export { materializeAuthoredMcpServer } from "./mcps/authored-materialization.js";
 export { NativeMcpEntryRetirementFailed, retireNativeMcpEntry, } from "./mcps/native-entry.js";
 export { MCP_SECRET_SERVICE, McpSecretStore, mcpSecretAccount, } from "./mcps/secret-store.js";
 export { MCP_AGENT_CONFIG_SURFACE, agentConfigTarget, agentConfigTargets, mcpConfigSurface, mcpServerArtifact, mcpServerSourcePath, mcpServerVersion, mcpSettingsTarget, mcpSourceTarget, } from "./mcps/artifact.js";
@@ -45,12 +43,5 @@ export { configuredMcpServersToDiskRefs, configuredPacksToDiskRefs, configuredSk
 export { canReuseExternalPackage, canReuseInstalledPackage, canonicalMaterializationPaths, createCanonicalDirectory, materializeExternalPackage, materializeExternalPackageWithTreeIntegrity, recoverCanonicalDirectory, replaceCanonicalDirectory, replaceCanonicalDirectoryWithInspection, } from "./extensions/canonical-directory.js";
 // Registry-backed acquisition
 export { materializeRegistryPackage, materializeRegistryPackageWithTreeIntegrity, } from "./registry-materialization.js";
-// Closure recipes
-export { buildAuthoredExtensionStep, buildInstallOperation, buildMaterializeOperation, buildNewExtensionStep, buildUninstallOperation, extensionRefLifecycleWarnings, extensionRefRegistryLifecycle, formatPackageUrlParts, targetFromRef, toLabel, toLabelWithCompanions, toStepKey, } from "./extensions/operations.js";
-// Re-materializing content the workspace already accepted. Both the sync
-// sweep and Pack activation restore retained members, and neither feature may
-// import the other.
-export { RetainedContentUnusable } from "./desired-state/errors.js";
-export { collectRetainedMaterializeSteps, } from "./desired-state/retained-materialization.js";
 export { projectionErrorToStepFailure } from "./projection-step-failure.js";
 //# sourceMappingURL=index.js.map

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

@@ -1,4 +1,3 @@
-/** Lifecycle manager for isolated Open Knowledge Format bundles. */
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";

package/dist/src/knowledge/manager.js

@@ -1,3 +1,5 @@
+import { usableAcceptedCanonical } from "@agentxm/workspace-state";
+import { LifecyclePostconditionViolated } from "../extensions/errors.js";
 // @effect-diagnostics anyUnknownInErrorContext:off — schema and filesystem errors are swept into KnowledgeIoFailed inside this manager
 /** Lifecycle manager for isolated Open Knowledge Format bundles. */
 import * as Effect from "effect/Effect";
@@ -628,6 +630,19 @@ export const KnowledgeManagerLive = Layer.effect(KnowledgeManager, Effect.gen(fu
     // Deactivation retains canonical content; the caller updates settings
     // first, so re-rendering the whole region drops this bundle's routing.
     const materializeDeactivate = Effect.fn("KnowledgeManager.materializeDeactivate")(() => applyKnowledgeProjection.pipe(Effect.as(withdrawn)));
+    const acquireCanonical = Effect.fn("KnowledgeManager.materializeInstall")(function* ({ ref, force }) {
+        const relativeLocalSource = ref.refType === "local"
+            ? makeWorkspaceRelativeSourcePath(path, baseDir, ref.sourcePath ?? stripFileProtocol(ref.location))
+            : Option.none();
+        if (ref.refType === "local" && Option.isNone(relativeLocalSource)) {
+            return yield* new KnowledgeDefinitionInvalid({
+                detail: `Local knowledge source must stay within the workspace: ${ref.source.path}`,
+            });
+        }
+        const prepared = yield* preparePackage(ref, force === true);
+        yield* prepared.commit;
+        return acquiredFacts(prepared, relativeLocalSource);
+    }, Effect.scoped);
     return {
         type: "knowledge",
         projectionPlans,
@@ -643,19 +658,8 @@ export const KnowledgeManagerLive = Layer.effect(KnowledgeManager, Effect.gen(fu
             })),
         install: installAtomically,
         isInstalled: ({ target }) => isObservedInstalled(ws, "knowledge", target.name),
-        materializeInstall: Effect.fn("KnowledgeManager.materializeInstall")(function* ({ ref, force, }) {
-            const relativeLocalSource = ref.refType === "local"
-                ? makeWorkspaceRelativeSourcePath(path, baseDir, ref.sourcePath ?? stripFileProtocol(ref.location))
-                : Option.none();
-            if (ref.refType === "local" && Option.isNone(relativeLocalSource)) {
-                return yield* new KnowledgeDefinitionInvalid({
-                    detail: `Local knowledge source must stay within the workspace: ${ref.source.path}`,
-                });
-            }
-            const prepared = yield* preparePackage(ref, force === true);
-            yield* prepared.commit;
-            return acquiredFacts(prepared, relativeLocalSource);
-        }, Effect.scoped),
+        materializeInstall: acquireCanonical,
+        acquireCanonical,
         prepareSourceTransition: ({ ref }) => provide(prepareAcceptedCanonicalTransition({
             workspace: ws,
             type: "knowledge",
@@ -683,27 +687,30 @@ export const KnowledgeManagerLive = Layer.effect(KnowledgeManager, Effect.gen(fu
         }),
         materializeUninstall,
         materializeDeactivate,
-        upsertSettingsEntry: ({ ref, versionRange, materialization }) => buildLockEntry(ref, materialization).pipe(Effect.flatMap((lockEntry) => Option.isSome(lockEntry)
-            ? ws.setKnowledge({
-                name: ref.knowledge.name,
-                lockEntry: lockEntry.value,
-                versionRange,
-            })
-            : setKnowledgeSourceEntry(ref.knowledge.name, "workspace"))),
-        removeSettingsEntry: ({ target }) => ws.removeKnowledgeSettings(target.name),
-        upsertLockfileEntry: ({ ref, materialization }) => buildLockEntry(ref, materialization).pipe(Effect.flatMap((lockEntry) => {
+        materializeRetained: ({ target }) => Effect.gen(function* () {
+            const canonical = yield* usableAcceptedCanonical({
+                workspace: ws,
+                type: "knowledge",
+                name: target.name,
+            });
+            if (Option.isNone(canonical) || canonical.value.ref.type !== "knowledge") {
+                return yield* new LifecyclePostconditionViolated({
+                    postcondition: "materialize-observable",
+                    targetType: "knowledge",
+                    targetName: target.name,
+                });
+            }
+            return yield* materializeDeactivate({ target });
+        }),
+        acceptedResolution: ({ ref, materialization }) => buildLockEntry(ref, materialization).pipe(Effect.flatMap((lockEntry) => {
             if (Option.isNone(lockEntry))
-                return ws.removeKnowledgeLock(ref.knowledge.name);
+                return Effect.succeed(Option.none());
             const validate = lockEntry.value.type === "registry"
                 ? validateExactResolvedVersion(`knowledge.${ref.knowledge.name}.resolvedVersion`, lockEntry.value.resolvedVersion)
                 : Effect.void;
-            return validate.pipe(Effect.flatMap(() => ws.setKnowledgeLock({
-                name: ref.knowledge.name,
-                lockEntry: lockEntry.value,
-                versionRange: Option.none(),
-            })));
+            return validate.pipe(Effect.as(Option.some({ key: ref.knowledge.name, entry: lockEntry.value })));
         })),
-        removeLockfileEntry: ({ target }) => ws.removeKnowledgeLock(target.name),
+        withdrawnResolutionKeys: ({ target }) => Effect.succeed([target.name]),
     };
 }));
 //# sourceMappingURL=manager.js.map

package/dist/src/manager-contract.d.ts

@@ -20,7 +20,7 @@ import type { ExtensionManagerFailure } from "./errors.js";
 import type { NativeWriteAuthority } from "@agentxm/agent-integration";
 import type { ProjectionPlan } from "@agentxm/workspace-projection";
 import type { ExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/extension-ref";
-import type { ExtensionTarget, ExtensionTargetFor } from "@agentxm/workspace-state";
+import type { ExtensionTarget, ExtensionTargetFor, LockEntryByType } from "@agentxm/workspace-state";
 /**
  * The services every manager keeps in `R`: the platform it reads and writes
  * through, the registry transport its acquisition steps use, and the authority
@@ -107,30 +107,28 @@ export interface ExtensionManager<TRef extends ExtensionRef, TMaterialization ex
     readonly materializeUninstall: (args: {
         readonly target: ExtensionTargetFor<TRef>;
     }) => Effect.Effect<TMaterialization, ExtensionManagerFailure, R>;
+    /** Acquire canonical content without producing any native agent output. */
+    readonly acquireCanonical: ExtensionManager<TRef, TMaterialization, R>["materializeInstall"];
+    /** Restore projections from verified retained canonical content, without source resolution. */
+    readonly materializeRetained: (args: {
+        readonly target: ExtensionTargetFor<TRef>;
+    }) => Effect.Effect<TMaterialization, ExtensionManagerFailure, R>;
     /** Remove active projections while retaining canonical managed content. */
     readonly materializeDeactivate: (args: {
         readonly target: ExtensionTargetFor<TRef>;
     }) => Effect.Effect<TMaterialization, ExtensionManagerFailure, R>;
-    readonly upsertSettingsEntry: (args: {
-        readonly ref: TRef;
-        readonly versionRange: Option.Option<string>;
-        /** What `materializeInstall` observed in this closure, when it ran. */
-        readonly materialization: Option.Option<TMaterialization>;
-    }) => Effect.Effect<void, ExtensionManagerFailure, R>;
-    readonly removeSettingsEntry: (args: {
-        readonly target: ExtensionTargetFor<TRef>;
-        /** What the withdrawal in this closure observed, when one ran. */
-        readonly materialization: Option.Option<TMaterialization>;
-    }) => Effect.Effect<void, ExtensionManagerFailure, R>;
-    readonly upsertLockfileEntry: (args: {
+    /** Verified acquisition facts; recording the resolution belongs to reconciliation. */
+    readonly acceptedResolution: (args: {
         readonly ref: TRef;
-        /** What `materializeInstall` observed in this closure, when it ran. */
         readonly materialization: Option.Option<TMaterialization>;
-    }) => Effect.Effect<void, ExtensionManagerFailure, R>;
-    readonly removeLockfileEntry: (args: {
+    }) => Effect.Effect<Option.Option<{
+        readonly key: string;
+        readonly entry: LockEntryByType[TRef["type"]];
+    }>, ExtensionManagerFailure, R>;
+    /** Accepted keys associated with the withdrawal observed by this adapter. */
+    readonly withdrawnResolutionKeys: (args: {
         readonly target: ExtensionTargetFor<TRef>;
-        /** What the withdrawal in this closure observed, when one ran. */
         readonly materialization: Option.Option<TMaterialization>;
-    }) => Effect.Effect<void, ExtensionManagerFailure, R>;
+    }) => Effect.Effect<ReadonlyArray<string>, ExtensionManagerFailure, R>;
 }
 //# sourceMappingURL=manager-contract.d.ts.map

package/dist/src/managers.d.ts

@@ -1,3 +1,4 @@
+import type { DesiredStateGraph } from "@agentxm/workspace-state";
 /**
  * Per-extension-type manager service tags and the materialization facts each
  * manager reports.
@@ -110,10 +111,20 @@ export interface RuleManagerService extends ExtensionManager<RuleExtensionRef, R
 declare const RuleManager_base: ServiceMap.ServiceClass<RuleManager, "@agentxm/extension-materialization/managers/RuleManager", RuleManagerService>;
 export declare class RuleManager extends RuleManager_base {
 }
+/** Hook contributors verified during preparation, before they enter the lockfile. */
+export interface PreparedHookProjection {
+    readonly plans: ReadonlyArray<ProjectionPlan<void, ExtensionManagerFailure, ManagerRequirements>>;
+    readonly agentOutcomes: ReadonlyArray<ConfiguredAgentOutcome>;
+    readonly acquisitions: ReadonlyArray<{
+        readonly name: string;
+        readonly treeIntegrity: TreeIntegrity;
+    }>;
+}
 export interface HookManagerService extends ExtensionManager<HookExtensionRef, HookMaterializationFacts, ManagerRequirements> {
+    readonly prepareProjection: (refs: ReadonlyArray<HookExtensionRef>) => Effect.Effect<PreparedHookProjection, ExtensionManagerFailure, ManagerRequirements>;
     readonly aggregateProjectionObservation: Effect.Effect<MaterializationObservation, ExtensionManagerFailure, ManagerRequirements>;
     readonly projectionPlans: () => Effect.Effect<ReadonlyArray<ProjectionPlan<void, ExtensionManagerFailure, ManagerRequirements>>, ExtensionManagerFailure, ManagerRequirements>;
-    readonly configuredAgentOutcomes?: (state: "projected" | "current") => Effect.Effect<ReadonlyArray<ConfiguredAgentOutcome>, ExtensionManagerFailure, ManagerRequirements>;
+    readonly configuredAgentOutcomes?: (state: "projected" | "current", proposedGraph?: DesiredStateGraph) => Effect.Effect<ReadonlyArray<ConfiguredAgentOutcome>, ExtensionManagerFailure, ManagerRequirements>;
     readonly configuredAgentOutcomesForRef?: (ref: HookExtensionRef, state: "projected" | "current") => Effect.Effect<ReadonlyArray<ConfiguredAgentOutcome>, ExtensionManagerFailure, ManagerRequirements>;
 }
 declare const HookManager_base: ServiceMap.ServiceClass<HookManager, "@agentxm/extension-materialization/managers/HookManager", HookManagerService>;

package/dist/src/managers.js

@@ -1,16 +1,3 @@
-/**
- * Per-extension-type manager service tags and the materialization facts each
- * manager reports.
- *
- * Plan-building features require a manager through its tag without depending
- * on the module that implements it. Every tag pins the facts type its manager
- * carries from a materialization to the settings and lockfile writes that
- * follow it in the same closure, so nothing travels through state the layer
- * keeps alive between calls.
- *
- * @experimental This API is unstable and may change without notice.
- * @packageDocumentation
- */
 import * as ServiceMap from "effect/Context";
 // -----------------------------------------------------------------------------
 // Service tags

package/dist/src/mcps/manager.js

@@ -1,3 +1,5 @@
+import { usableAcceptedCanonical } from "@agentxm/workspace-state";
+import { LifecyclePostconditionViolated } from "../extensions/errors.js";
 /**
  * MCP server extension manager service.
  *
@@ -216,6 +218,22 @@ export const McpServerManagerLive = Layer.effect(McpServerManager, Effect.gen(fu
             return yield* isObservedInstalled(ws, "mcp-server", target.name);
         }),
         materializeInstall,
+        acquireCanonical: materializeInstall,
+        materializeRetained: ({ target }) => Effect.gen(function* () {
+            const canonical = yield* usableAcceptedCanonical({
+                workspace: ws,
+                type: "mcp-server",
+                name: target.name,
+            });
+            if (Option.isNone(canonical) || canonical.value.ref.type !== "mcp-server") {
+                return yield* new LifecyclePostconditionViolated({
+                    postcondition: "materialize-observable",
+                    targetType: "mcp-server",
+                    targetName: target.name,
+                });
+            }
+            return yield* materializeInstall({ ref: canonical.value.ref });
+        }),
         prepareSourceTransition: ({ ref }) => prepareAcceptedCanonicalTransition({
             workspace: ws,
             type: "mcp-server",
@@ -240,9 +258,9 @@ export const McpServerManagerLive = Layer.effect(McpServerManager, Effect.gen(fu
         materializeDeactivate,
         configuredAgentOutcomes,
         configuredAgentOutcomesForEntry,
-        upsertSettingsEntry: ({ ref, versionRange, materialization, }) => {
+        acceptedResolution: ({ ref, materialization, }) => {
             if (ref.refType !== "registry")
-                return Effect.void.pipe(Effect.withSpan("McpServerManager.upsertSettingsEntry"));
+                return Effect.succeed(Option.none());
             const registryRef = ref;
             return validateExactResolvedVersion(`mcpServers.${ref.server.name}.resolvedVersion`, registryRef.version).pipe(Effect.flatMap(() => {
                 const treeIntegrity = materialization.pipe(Option.flatMap((facts) => facts.treeIntegrity));
@@ -250,56 +268,25 @@ export const McpServerManagerLive = Layer.effect(McpServerManager, Effect.gen(fu
                     return Effect.fail(new McpInstallStateMissing({ name: registryRef.server.name }));
                 }
                 const lockEntry = buildMcpServerLockEntry(registryRef, treeIntegrity.value);
-                return ws.setMcpServer({
-                    name: ref.server.name,
-                    resolutionKey: mcpRegistryResolutionKey({
+                return Effect.succeed(Option.some({
+                    key: mcpRegistryResolutionKey({
                         authority: registryRef.source.location,
                         owner: registryRef.owner,
                         name: registryRef.server.name,
                     }),
-                    lockEntry,
-                    versionRange,
-                });
-            }), Effect.withSpan("McpServerManager.upsertSettingsEntry"));
-        },
-        removeSettingsEntry: ({ target }) => ws
-            .removeMcpServerSettings(target.name)
-            .pipe(Effect.withSpan("McpServerManager.removeSettingsEntry")),
-        upsertLockfileEntry: ({ ref, materialization, }) => {
-            if (ref.refType !== "registry")
-                return ws
-                    .removeMcpServerLock(ref.server.name)
-                    .pipe(Effect.withSpan("McpServerManager.upsertLockfileEntry"));
-            const registryRef = ref;
-            return validateExactResolvedVersion(`mcpServers.${ref.server.name}.resolvedVersion`, registryRef.version).pipe(Effect.flatMap(() => {
-                const treeIntegrity = materialization.pipe(Option.flatMap((facts) => facts.treeIntegrity));
-                if (Option.isNone(treeIntegrity)) {
-                    return Effect.fail(new McpInstallStateMissing({ name: registryRef.server.name }));
-                }
-                const lockEntry = buildMcpServerLockEntry(registryRef, treeIntegrity.value);
-                return ws.setMcpServerLock({
-                    name: ref.server.name,
-                    resolutionKey: mcpRegistryResolutionKey({
-                        authority: registryRef.source.location,
-                        owner: registryRef.owner,
-                        name: registryRef.server.name,
-                    }),
-                    lockEntry,
-                    versionRange: Option.none(),
-                });
-            }), Effect.withSpan("McpServerManager.upsertLockfileEntry"));
+                    entry: lockEntry,
+                }));
+            }), Effect.withSpan("McpServerManager.acceptedResolution"));
         },
-        removeLockfileEntry: ({ materialization, }) => {
+        withdrawnResolutionKeys: ({ materialization, }) => {
             const removal = materialization.pipe(Option.flatMap((facts) => facts.removal));
             if (Option.isNone(removal)) {
-                return Effect.void.pipe(Effect.withSpan("McpServerManager.removeLockfileEntry"));
+                return Effect.succeed([]);
             }
             if (removal.value.retainShared || Option.isNone(removal.value.resolutionKey)) {
-                return Effect.void.pipe(Effect.withSpan("McpServerManager.removeLockfileEntry"));
+                return Effect.succeed([]);
             }
-            return ws
-                .removeMcpServerLock(removal.value.resolutionKey.value)
-                .pipe(Effect.withSpan("McpServerManager.removeLockfileEntry"));
+            return Effect.succeed([removal.value.resolutionKey.value]);
         },
     };
 }));

package/dist/src/packs/manager.js

@@ -1,3 +1,5 @@
+import { usableAcceptedCanonical } from "@agentxm/workspace-state";
+import { LifecyclePostconditionViolated } from "../extensions/errors.js";
 /**
  * Pack manager service.
  *
@@ -145,6 +147,7 @@ export const PackManagerLive = Layer.effect(PackManager, Effect.gen(function* ()
             return yield* isObservedInstalled(ws, "pack", target.name);
         }),
         materializeInstall,
+        acquireCanonical: materializeInstall,
         prepareSourceTransition: ({ ref }) => prepareAcceptedCanonicalTransition({
             workspace: ws,
             type: "pack",
@@ -161,29 +164,29 @@ export const PackManagerLive = Layer.effect(PackManager, Effect.gen(function* ()
         }),
         materializeUninstall,
         materializeDeactivate,
-        upsertSettingsEntry: Effect.fn("PackManager.upsertSettingsEntry")(function* ({ ref, versionRange, materialization, }) {
-            const args = yield* buildCurrentPackArgs(ref, versionRange, materialization);
-            if (Option.isSome(args)) {
-                yield* ws.setPack(args.value);
-            }
-            else {
-                yield* ws.setPackEntry(ref.pack.name, {
-                    source: "workspace",
-                    enabled: true,
+        materializeRetained: ({ target }) => Effect.gen(function* () {
+            const canonical = yield* usableAcceptedCanonical({
+                workspace: ws,
+                type: "pack",
+                name: target.name,
+            });
+            if (Option.isNone(canonical) || canonical.value.ref.type !== "pack") {
+                return yield* new LifecyclePostconditionViolated({
+                    postcondition: "materialize-observable",
+                    targetType: "pack",
+                    targetName: target.name,
                 });
             }
+            return yield* materializeDeactivate({ target });
         }),
-        removeSettingsEntry: ({ target }) => ws.removePackSettings(target.name).pipe(Effect.withSpan("PackManager.removeSettingsEntry")),
-        upsertLockfileEntry: Effect.fn("PackManager.upsertLockfileEntry")(function* ({ ref, materialization, }) {
+        acceptedResolution: Effect.fn("PackManager.acceptedResolution")(function* ({ ref, materialization, }) {
             const args = yield* buildCurrentPackArgs(ref, Option.none(), materialization);
-            if (Option.isSome(args)) {
-                yield* ws.setPackLock(args.value);
-            }
-            else {
-                yield* ws.removePackLock(ref.pack.name);
-            }
+            return Option.map(args, ({ versionRange: _versionRange, ...entry }) => ({
+                key: ref.pack.name,
+                entry,
+            }));
         }),
-        removeLockfileEntry: ({ target }) => ws.removePackLock(target.name).pipe(Effect.withSpan("PackManager.removeLockfileEntry")),
+        withdrawnResolutionKeys: ({ target }) => Effect.succeed([target.name]),
     };
 }));
 //# sourceMappingURL=manager.js.map

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

@@ -1,8 +1,3 @@
-/**
- * Rule manager service.
- *
- * @experimental This API is unstable and may change without notice.
- */
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";