@agentxm/extension-lifecycle 0.28.12 → 0.28.13

package/dist/src/packs/artifact.js

@@ -0,0 +1,32 @@
+/**
+ * Where a pack member's acquired package sits, and what an install changed
+ * about it. Both the member step and the pack planner report the same
+ * artifact for the same ref, so a preview and its apply name one path.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { toExtensionTypePlural, } from "@agentxm/extension-model/unstable/extensions";
+import { ACQUIRED_EXTENSIONS_DIR, acquiredExtensionDisplayPath } from "@agentxm/workspace-state";
+const USER_SCOPE_ACQUIRED_ROOT = ".axm/workspace/agent_extensions";
+/** The registry directory segment a type's acquired packages live under. */
+export const registryPluralSegment = (type) => toExtensionTypePlural(type);
+/** Workspace-relative path of a ref's acquired (or authored) package. */
+export const registrySourcePath = (ref, scope) => ref.refType === "workspace"
+    ? ref.location
+    : acquiredExtensionDisplayPath(scope === "project" ? ACQUIRED_EXTENSIONS_DIR : USER_SCOPE_ACQUIRED_ROOT, ref, registryPluralSegment(ref.type), ref.name);
+/** The artifact one acquired pack member reports. */
+export const registrySourceArtifact = (args) => {
+    const change = args.ref.refType === "workspace" ? "unchanged" : args.installedBefore ? "updated" : "created";
+    const sourcePath = registrySourcePath(args.ref, args.scope);
+    return {
+        path: sourcePath,
+        scope: args.scope,
+        ...(args.ref.refType === "registry" || args.ref.refType === "workspace"
+            ? { version: args.ref.version }
+            : {}),
+        change,
+        fileCount: 1,
+        targets: [{ path: sourcePath, change }],
+    };
+};
+//# sourceMappingURL=artifact.js.map

package/dist/src/packs/constraint-gate.d.ts

@@ -0,0 +1,30 @@
+import * as Effect from "effect/Effect";
+import { type PackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
+import { type DesiredStateGraph, type DesiredStateProblem, type WorkspaceMutationsService } from "@agentxm/workspace-state";
+import { type Plan } from "@agentxm/workspace-operations";
+import type { InstallStepRequirements } from "../install/vocabulary.js";
+export declare const relevantPackConstraintProblems: (args: {
+    readonly graph: DesiredStateGraph;
+    readonly prospectivePacks: ReadonlyArray<PackRef>;
+    readonly selectedNames?: ReadonlySet<string>;
+}) => ReadonlyArray<Extract<DesiredStateProblem, {
+    readonly type: "constraint-conflict";
+}>>;
+export declare const prospectivePackConstraintProblems: (args: {
+    readonly workspace: WorkspaceMutationsService;
+    readonly prospectivePacks: ReadonlyArray<PackRef>;
+    readonly selectedNames?: ReadonlySet<string>;
+}) => Effect.Effect<readonly {
+    readonly type: "constraint-conflict";
+    readonly extensionType: import("@agentxm/extension-model/unstable/extensions").ExtensionType;
+    readonly name: string;
+    readonly constraints: ReadonlyArray<string>;
+    readonly contributors: ReadonlyArray<import("@agentxm/workspace-state").DesiredConstraintContributor>;
+}[], import("@agentxm/workspace-state").WorkspaceStateReadFailure, never>;
+export declare const configuredPackConstraintBlockPlan: (args: {
+    readonly operation: "install" | "update";
+    readonly problems: ReadonlyArray<Extract<DesiredStateProblem, {
+        readonly type: "constraint-conflict";
+    }>>;
+}) => Plan<InstallStepRequirements>;
+//# sourceMappingURL=constraint-gate.d.ts.map

package/dist/src/packs/constraint-gate.js

@@ -0,0 +1,76 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import {} from "@agentxm/extension-model/unstable/extensions/refs/pack";
+import { desiredStateProblemsText, } from "@agentxm/workspace-state";
+import { operationPresentation } from "@agentxm/workspace-operations";
+const normalizedPackIdentity = (identity) => identity.replace(/^workspace:/u, "");
+const packOrigins = (origins) => origins.flatMap((origin) => origin.type === "pack" ? [normalizedPackIdentity(origin.pack)] : []);
+const selectedPackClosure = (graph, prospectivePacks, selectedNames) => {
+    const selected = new Set(prospectivePacks.map((pack) => `${pack.owner}/packs/${pack.pack.name}`));
+    for (const node of graph.nodes) {
+        if (node.type === "pack" && (selectedNames === undefined || selectedNames.has(node.name))) {
+            selected.add(normalizedPackIdentity(node.identity));
+        }
+    }
+    const adjacent = new Map();
+    for (const node of graph.nodes) {
+        const packs = packOrigins(node.origins);
+        for (const pack of packs) {
+            const neighbors = adjacent.get(pack) ?? new Set();
+            for (const peer of packs) {
+                if (peer !== pack)
+                    neighbors.add(peer);
+            }
+            adjacent.set(pack, neighbors);
+        }
+    }
+    const closure = new Set(selected);
+    const pending = [...selected];
+    for (let index = 0; index < pending.length; index += 1) {
+        const pack = pending[index];
+        if (pack === undefined)
+            continue;
+        for (const neighbor of adjacent.get(pack) ?? []) {
+            if (closure.has(neighbor))
+                continue;
+            closure.add(neighbor);
+            pending.push(neighbor);
+        }
+    }
+    return closure;
+};
+export const relevantPackConstraintProblems = (args) => {
+    const closure = selectedPackClosure(args.graph, args.prospectivePacks, args.selectedNames);
+    return args.graph.problems.filter((problem) => problem.type === "constraint-conflict" &&
+        problem.contributors.some((contributor) => contributor.dependingPack !== undefined &&
+            closure.has(normalizedPackIdentity(contributor.dependingPack))));
+};
+export const prospectivePackConstraintProblems = (args) => args.workspace.getDesiredStateGraph({ prospectivePacks: args.prospectivePacks }).pipe(Effect.map((graph) => relevantPackConstraintProblems({
+    graph,
+    prospectivePacks: args.prospectivePacks,
+    ...(args.selectedNames === undefined ? {} : { selectedNames: args.selectedNames }),
+})));
+export const configuredPackConstraintBlockPlan = (args) => ({
+    _tag: "Plan",
+    name: `Block configured Pack ${args.operation}`,
+    description: Option.some("Configured Pack constraints cannot be satisfied together"),
+    presentation: operationPresentation({
+        imperative: args.operation,
+        past: args.operation === "install" ? "Installed" : "Updated",
+        gerund: args.operation === "install" ? "Installing" : "Updating",
+    }, "pack"),
+    jobs: [
+        {
+            concurrency: 1,
+            steps: [
+                {
+                    key: "pack:constraint-gate",
+                    readiness: "error",
+                    label: "configured Pack constraint gate",
+                    errorMessage: `Configured Pack constraints are unsatisfiable: ${desiredStateProblemsText(args.problems)}`,
+                },
+            ],
+        },
+    ],
+});
+//# sourceMappingURL=constraint-gate.js.map

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

@@ -6,17 +6,16 @@
  * @experimental This API is unstable and may change without notice.
  */
 import * as Effect from "effect/Effect";
+import type * as Duration from "effect/Duration";
 import type * as Option from "effect/Option";
-import type { SourceAuthorityBlocked, PackManagerError } from "@agentxm/extension-workspace";
-/** Failures pack expansion can surface. */
-type PackExpansionError = SourceResolutionFailure | PackManagerError | SourceAuthorityBlocked;
 import { type ExtensionType } from "@agentxm/extension-model/unstable/extensions";
 import type { ExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/extension-ref";
 import type { PackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
-import type { SourceHostProvidersService, SourceResolutionFailure } from "@agentxm/extension-sources";
-import type * as Duration from "effect/Duration";
-import { type PackDependencyRefResolver, type ReleaseAgeAwarePackDependencyResolution, type WorkspacePackDependencyResolver } from "./dependency-resolution.js";
 import type { ReleaseAgeEvaluation } from "@agentxm/extension-model/unstable/extensions/release-age";
+import type { SourceHostProvidersService, SourceResolutionFailure } from "@agentxm/extension-sources";
+import { type PackDependencyRefResolver, type PackDependencyResolutionFailure, type ReleaseAgeAwarePackDependencyResolution, type SourceAuthorityBlocked, type WorkspacePackDependencyResolver } from "@agentxm/extension-resolution";
+/** Failures pack expansion can surface. */
+type PackExpansionError = SourceResolutionFailure | PackDependencyResolutionFailure | SourceAuthorityBlocked;
 /**
  * Expand a pack ref into its cross-type dependency refs.
  *
@@ -27,14 +26,14 @@ import type { ReleaseAgeEvaluation } from "@agentxm/extension-model/unstable/ext
  * Dependency refs use the pack's registry source and empty integrity
  * (integrity is resolved during materialization, not at expansion time).
  */
-export declare const expandPackInstallRefs: <E = never>(args: {
+export declare const expandPackInstallRefs: <E = never, R = never>(args: {
     readonly pack: PackRef;
     readonly supportedDependencyTypes: ReadonlyArray<ExtensionType>;
     readonly sources: SourceHostProvidersService;
     readonly minimumReleaseAge?: Option.Option<Duration.Duration>;
-    readonly workspaceResolver?: WorkspacePackDependencyResolver<E>;
-    readonly dependencyResolver?: PackDependencyRefResolver<E>;
-}) => Effect.Effect<ReadonlyArray<ExtensionRef>, PackExpansionError | E>;
+    readonly workspaceResolver?: WorkspacePackDependencyResolver<E, R>;
+    readonly dependencyResolver?: PackDependencyRefResolver<E, R>;
+}) => Effect.Effect<ReadonlyArray<ExtensionRef>, PackExpansionError | E, R>;
 export type ReleaseAgeAwarePackExpansion = {
     readonly kind: "selected";
     readonly refs: ReadonlyArray<ExtensionRef>;
@@ -47,13 +46,13 @@ export type ReleaseAgeAwarePackExpansion = {
 } | Extract<ReleaseAgeAwarePackDependencyResolution, {
     kind: "policy_held";
 }>;
-export declare const expandPackInstallRefsWithReleaseAge: <E = never>(args: {
+export declare const expandPackInstallRefsWithReleaseAge: <E = never, R = never>(args: {
     readonly pack: PackRef;
     readonly supportedDependencyTypes: ReadonlyArray<ExtensionType>;
     readonly sources: SourceHostProvidersService;
     readonly releaseAgeEvaluation: ReleaseAgeEvaluation;
-    readonly workspaceResolver?: WorkspacePackDependencyResolver<E>;
-    readonly dependencyResolver?: PackDependencyRefResolver<E>;
-}) => Effect.Effect<ReleaseAgeAwarePackExpansion, PackExpansionError | E>;
+    readonly workspaceResolver?: WorkspacePackDependencyResolver<E, R>;
+    readonly dependencyResolver?: PackDependencyRefResolver<E, R>;
+}) => Effect.Effect<ReleaseAgeAwarePackExpansion, PackExpansionError | E, R>;
 export {};
 //# sourceMappingURL=expansion.d.ts.map

package/dist/src/packs/expansion.js

@@ -7,8 +7,7 @@
  */
 import * as Effect from "effect/Effect";
 import {} from "@agentxm/extension-model/unstable/extensions";
-import { resolvePackDependencies } from "./dependency-resolution.js";
-import { resolvePackDependenciesWithReleaseAge, } from "./dependency-resolution.js";
+import { resolvePackDependencies, resolvePackDependenciesWithReleaseAge, } from "@agentxm/extension-resolution";
 // -----------------------------------------------------------------------------
 // expandPackInstallRefs
 // -----------------------------------------------------------------------------

package/dist/src/packs/graph-transition.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The atomic pack graph transition.
+ *
+ * Installing or removing a pack changes the desired graph and every member's
+ * canonical content together. Either the whole transition holds or none of it
+ * does, so its children run inside one workspace transaction, a stale
+ * candidate is caught before the first write, and the resulting graph is
+ * checked against the predicate the planner declared.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { WorkspaceMutations, type DesiredExtensionNode } from "@agentxm/workspace-state";
+import { type JobStepArtifact, type PlannedJobStep } from "@agentxm/workspace-operations";
+import type { ExtensionLifecycleFailed } from "../errors.js";
+import { type LifecycleStepFailure } from "../step-failure.js";
+import { type InstallStepRequirements } from "../install/vocabulary.js";
+export interface AtomicPackGraphChild {
+    readonly step: PlannedJobStep<InstallStepRequirements>;
+    readonly coverage: "eligible" | "ineligible";
+}
+/**
+ * What a pack transition checks before it writes and after it commits. The
+ * checks are the planner's, so their failure family and their requirements
+ * travel with them rather than being fixed here.
+ */
+export interface AtomicPackGraphStepArgs<E extends LifecycleStepFailure, R> {
+    readonly label: string;
+    readonly message: string;
+    readonly artifact: JobStepArtifact;
+    readonly children: ReadonlyArray<AtomicPackGraphChild>;
+    readonly reportUnchangedWhenChildrenUnchanged?: boolean;
+    /** A stale-candidate check that runs under the transition, before any write. */
+    readonly preTransition?: Effect.Effect<void, E, R>;
+    /** The desired-graph predicate the committed transition must satisfy. */
+    readonly validate: Effect.Effect<void, E, R>;
+}
+/** Wrap a pack transition's children in one workspace transaction. */
+export declare const buildAtomicPackGraphStep: <E extends LifecycleStepFailure, R>(args: AtomicPackGraphStepArgs<E, R>) => Effect.Effect<PlannedJobStep<InstallStepRequirements | R>>;
+interface RequiredPack {
+    readonly name: string;
+    readonly identity: string;
+    readonly enabled?: boolean;
+}
+interface RequiredMember {
+    readonly type: Exclude<DesiredExtensionNode["type"], "pack">;
+    readonly name: string;
+    readonly packIdentity?: string;
+    readonly direct?: boolean;
+    readonly enabled?: boolean;
+}
+interface AbsentNode {
+    readonly type: DesiredExtensionNode["type"];
+    readonly name: string;
+}
+/** The desired-graph predicate a completed pack transition must satisfy. */
+export declare const validatePackGraphPostcondition: (args: {
+    readonly requiredPacks?: ReadonlyArray<RequiredPack>;
+    readonly requiredMembers?: ReadonlyArray<RequiredMember>;
+    readonly absent?: ReadonlyArray<AbsentNode>;
+    readonly inactive?: ReadonlyArray<AbsentNode>;
+}) => Effect.Effect<void, ExtensionLifecycleFailed, WorkspaceMutations>;
+export {};
+//# sourceMappingURL=graph-transition.d.ts.map

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

@@ -0,0 +1,219 @@
+/**
+ * The atomic pack graph transition.
+ *
+ * Installing or removing a pack changes the desired graph and every member's
+ * canonical content together. Either the whole transition holds or none of it
+ * does, so its children run inside one workspace transaction, a stale
+ * candidate is caught before the first write, and the resulting graph is
+ * checked against the predicate the planner declared.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+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;
+    const graph = yield* ws.getDesiredStateGraph().pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Desired state could not be read after the pack transition",
+        cause,
+    })));
+    const requiredPackIdentities = new Set((args.requiredPacks ?? []).map((pack) => normalizedIdentity(pack.identity)));
+    const requiredMemberKeys = new Set((args.requiredMembers ?? []).map((member) => `${member.type}:${member.name}`));
+    const relevantProblems = graph.problems.filter((problem) => {
+        switch (problem.type) {
+            case "pack-manifest-unavailable":
+            case "pack-manifest-invalid":
+            case "pack-identity-mismatch":
+            case "pack-resolution-unavailable":
+            case "pack-manifest-content-mismatch":
+                return requiredPackIdentities.has(normalizedIdentity(problem.pack));
+            case "projection-collision":
+            case "constraint-conflict":
+            case "workspace-owner-missing":
+                return requiredMemberKeys.has(`${problem.extensionType}:${problem.name}`);
+        }
+    });
+    if (relevantProblems.length > 0) {
+        return yield* installRefused({
+            category: "conflict",
+            detail: `Pack transition left its desired member graph incomplete: ${desiredStateProblemsText(relevantProblems)}`,
+        });
+    }
+    for (const expected of args.requiredPacks ?? []) {
+        const node = graph.nodes.find((candidate) => candidate.type === "pack" && candidate.name === expected.name);
+        if (node === undefined ||
+            normalizedIdentity(node.identity) !== normalizedIdentity(expected.identity) ||
+            (expected.enabled !== undefined && node.enabled !== expected.enabled)) {
+            const expectedPredicate = [
+                `identity ${normalizedIdentity(expected.identity)}`,
+                ...(expected.enabled === undefined
+                    ? []
+                    : [`activation ${expected.enabled ? "enabled" : "disabled"}`]),
+            ].join(", ");
+            const observedPredicate = node === undefined
+                ? "absent"
+                : `identity ${normalizedIdentity(node.identity)}, activation ${node.enabled ? "enabled" : "disabled"}`;
+            return yield* installRefused({
+                category: "internal",
+                detail: `Pack graph closure ${expected.identity} failed its desired-state predicate: expected ${expectedPredicate}; observed ${observedPredicate}`,
+            });
+        }
+    }
+    for (const expected of args.requiredMembers ?? []) {
+        const node = graph.nodes.find((candidate) => candidate.type === expected.type && candidate.name === expected.name);
+        const packIdentity = expected.packIdentity;
+        const hasPackOrigin = packIdentity === undefined ||
+            node?.origins.some((origin) => origin.type === "pack" &&
+                normalizedIdentity(origin.pack) === normalizedIdentity(packIdentity)) === true;
+        const hasDirectOrigin = expected.direct !== true ||
+            node?.origins.some((origin) => origin.type === "settings") === true;
+        if (node === undefined ||
+            !hasPackOrigin ||
+            !hasDirectOrigin ||
+            (expected.enabled !== undefined && node.enabled !== expected.enabled)) {
+            const expectedPredicate = [
+                ...(packIdentity === undefined
+                    ? []
+                    : [`Pack ownership ${normalizedIdentity(packIdentity)}`]),
+                ...(expected.direct === true ? ["direct ownership"] : []),
+                ...(expected.enabled === undefined
+                    ? []
+                    : [`activation ${expected.enabled ? "enabled" : "disabled"}`]),
+            ].join(", ");
+            const observedPredicate = node === undefined
+                ? "absent"
+                : `origins ${node.origins
+                    .map((origin) => origin.type === "pack"
+                    ? `Pack ${normalizedIdentity(origin.pack)}`
+                    : "direct settings")
+                    .join(", ") || "none"}, activation ${node.enabled ? "enabled" : "disabled"}`;
+            return yield* installRefused({
+                category: "internal",
+                detail: `Pack graph closure ${packIdentity ?? "unknown"} failed the ${expected.type} "${expected.name}" desired-state predicate: expected ${expectedPredicate || "reachable"}; observed ${observedPredicate}`,
+            });
+        }
+    }
+    for (const expected of args.absent ?? []) {
+        if (graph.nodes.some((candidate) => candidate.type === expected.type && candidate.name === expected.name)) {
+            return yield* installRefused({
+                category: "internal",
+                detail: `${expected.type} "${expected.name}" remained in the desired graph after the pack transition`,
+            });
+        }
+    }
+    for (const expected of args.inactive ?? []) {
+        const node = graph.nodes.find((candidate) => candidate.type === expected.type && candidate.name === expected.name);
+        if (node === undefined || node.enabled) {
+            return yield* installRefused({
+                category: "internal",
+                detail: `${expected.type} "${expected.name}" did not remain reachable and inactive after the Pack transition`,
+            });
+        }
+    }
+});
+//# sourceMappingURL=graph-transition.js.map

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

@@ -0,0 +1,95 @@
+/**
+ * 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";
+import { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager } from "@agentxm/extension-materialization";
+import type { PackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
+import { type ExtensionName, type Handle } from "@agentxm/extension-model/unstable/extensions";
+import type { ReleaseAgeEvaluation } from "@agentxm/extension-model/unstable/extensions/release-age";
+import type { RegistrySource } from "@agentxm/extension-model/unstable/sources/types";
+import { type VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
+import { type SourceAuthorityBlockedFact, type WorkspacePackDependencyResolver } from "@agentxm/extension-resolution";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { type Plan } from "@agentxm/workspace-operations";
+import { type DesiredStateGraph } from "@agentxm/workspace-state";
+import type { ExtensionLifecycleFailed } from "../../errors.js";
+import { type RegistryLookupProbe } from "../../install/registry-source-resolution.js";
+import { type InstallStepRequirements, type PackInstallIntent, type ResolveInstallRequirements } from "../../install/vocabulary.js";
+/** A pack install request after grammar parsing, before anything is discovered. */
+export interface ParsedPackInstallRequest {
+    readonly owner: Handle;
+    readonly packName: ExtensionName;
+    readonly versionRange: Option.Option<VersionRange>;
+    readonly resolvedInput: string;
+    readonly inputKind: "name-input" | "name-input-with-version" | "registry-pattern-input";
+    readonly sourceResolution?: string;
+    readonly unattended: boolean;
+    readonly nonInteractive: boolean;
+    readonly releaseAgeEvaluation?: ReleaseAgeEvaluation;
+    readonly releaseAgeHoldbackBehavior?: "continue" | "preserve-or-block";
+}
+/** One pack registry lookup. */
+export interface PackSourceRequest {
+    readonly source: RegistrySource;
+    readonly owner: Handle;
+    readonly packName: ExtensionName;
+    readonly versionRange: Option.Option<VersionRange>;
+    readonly sourceResolution?: string;
+}
+/** A discovered pack ref and the registry hosts that were consulted for it. */
+export interface PackDiscovery {
+    readonly ref: PackRef;
+    readonly probes: ReadonlyArray<RegistryLookupProbe>;
+    readonly registrySourceLabel: string;
+}
+/**
+ * Which declared members a locally-authored workspace package may satisfy,
+ * and which configured sources refuse to be replaced by the registry. The
+ * fingerprint identifies the exact authority this plan was built against, so
+ * the transition can refuse a candidate that went stale.
+ */
+export interface WorkspaceAuthorityScan {
+    readonly graph: DesiredStateGraph;
+    readonly blockers: ReadonlyArray<SourceAuthorityBlockedFact>;
+    readonly workspaceResolver: WorkspacePackDependencyResolver;
+    readonly fingerprint: string;
+}
+/** What a pack install command supplies before anything is parsed. */
+export interface PackInstallArgs {
+    readonly source: string;
+    readonly unattended?: boolean;
+    readonly nonInteractive: boolean;
+    readonly releaseAgeEvaluation?: ReleaseAgeEvaluation;
+    readonly releaseAgeHoldbackBehavior?: "continue" | "preserve-or-block";
+}
+/** Read the pack source grammar: which owner, which pack, which range. */
+export declare const parsePackInstallRequest: (args: PackInstallArgs) => Effect.Effect<ParsedPackInstallRequest, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/** Resolve the registry the parsed pack request names. */
+export declare const resolvePackSourceRequest: (request: ParsedPackInstallRequest) => Effect.Effect<PackSourceRequest, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/**
+ * Find the pack. When the first host cannot answer because remote reads are
+ * unsupported, every configured `file://` registry is consulted in turn, and
+ * every probe is recorded so the operator can see what was tried.
+ */
+export declare const discoverPackRef: (request: PackSourceRequest) => Effect.Effect<PackDiscovery, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/** Render the probe evidence a discovery collected. */
+export declare const packDiscoveryDiagnostics: (request: PackSourceRequest, discovery: PackDiscovery) => ReadonlyArray<string>;
+/** Settle the pack this request installs. */
+export declare const finalizePackInstallIntent: (request: ParsedPackInstallRequest, discovery: PackDiscovery) => PackInstallIntent;
+/** Everything the pack graph transition reads and writes through. */
+export type PackInstallRequirements = InstallStepRequirements | ResolveInstallRequirements | SourceHostProviders | Path.Path | HookManager | KnowledgeManager | McpServerManager | PackManager | RuleManager | SkillManager | SubagentManager;
+/** The single atomic closure a settled pack intent becomes. */
+export declare const planPackInstall: (intent: PackInstallIntent) => Effect.Effect<Plan<InstallStepRequirements>, ExtensionLifecycleFailed, PackInstallRequirements>;
+//# sourceMappingURL=plan.d.ts.map