@agentxm/extension-lifecycle 0.28.12 → 0.28.13

package/dist/src/test-registry.js

@@ -0,0 +1,223 @@
+// @effect-diagnostics globalDate:off — ZIP's driver API requires one fixed Date value and never reads the ambient clock
+/**
+ * A file-backed Registry a specification can publish into.
+ *
+ * Writes the real Registry directory layout — a per-extension index plus
+ * version archives with genuine integrity hashes — that the production
+ * source-resolution layer reads over `file://`. Publication instants predate
+ * the deterministic test clock by more than the default minimum release age,
+ * so every written version is immediately eligible; rewriting an extension
+ * with a longer version list models a later publication.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as nodePath from "node:path";
+import { strToU8, zipSync } from "fflate";
+const PUBLISHED_AT = "1960-01-01T00:00:00Z";
+const OWNER = "@acme";
+// ZIP stores a local-time DOS timestamp and admits only 1980-2099. Building the
+// fixed instant from local components keeps the encoded fields identical in
+// every timezone; an instant fixed in UTC falls into 1979 west of Greenwich.
+// eslint-disable-next-line no-restricted-syntax -- ZIP's driver API requires Date; this fixed value never reads the ambient clock.
+const ARCHIVE_MTIME = new Date(1980, 0, 2, 0, 0, 0, 0);
+const versionParts = (version) => (version.split("-")[0] ?? version).split(".").map((part) => Number.parseInt(part, 10));
+/**
+ * The Registry index lists versions newest-first and the resolvers rely on
+ * that order; callers may pass versions in any order.
+ */
+const newestFirst = (entries) => [...entries].sort((left, right) => {
+    const a = versionParts(left.version);
+    const b = versionParts(right.version);
+    for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+        const difference = (b[index] ?? 0) - (a[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+});
+/** Publish into a throwaway `file://` Registry. */
+export const makeLifecycleRegistry = () => {
+    const root = fs.realpathSync(fs.mkdtempSync(nodePath.join(os.tmpdir(), "axm-lifecycle-registry-")));
+    const writeArchive = (directory, version, entries) => {
+        fs.mkdirSync(directory, { recursive: true });
+        const archive = zipSync(Object.fromEntries(Object.entries(entries).map(([relative, content]) => [relative, strToU8(content)])), { mtime: ARCHIVE_MTIME });
+        fs.writeFileSync(nodePath.join(directory, `${version}.zip`), archive);
+        return archive;
+    };
+    const writeIndex = (directory, index) => {
+        fs.mkdirSync(directory, { recursive: true });
+        fs.writeFileSync(nodePath.join(directory, "index.json"), `${JSON.stringify(index, null, 2)}\n`);
+    };
+    const integrity = (archive) => `sha512-${createHash("sha512").update(archive).digest("base64")}`;
+    const extensionDirectory = (plural, name) => nodePath.join(root, "extensions", OWNER, plural, name);
+    const publish = (args) => {
+        const directory = extensionDirectory(args.plural, args.name);
+        const entries = args.versions.map((entry) => ({
+            version: entry.version,
+            published: entry.published ?? PUBLISHED_AT,
+            integrity: integrity(writeArchive(directory, entry.version, args.archive(entry))),
+            ...(args.extra === undefined ? {} : args.extra(entry)),
+        }));
+        writeIndex(directory, {
+            owner: OWNER,
+            type: args.type,
+            name: args.name,
+            publisherBindingId: "hbnd_test",
+            deprecation: null,
+            versions: newestFirst(entries),
+        });
+    };
+    const manifest = (contents) => `${JSON.stringify(contents, null, 2)}\n`;
+    return {
+        root,
+        source: { name: "agentxm", type: "registry", location: `file://${root}` },
+        writeSkill: (name, versions) => publish({
+            plural: "skills",
+            type: "skill",
+            name,
+            versions,
+            archive: ({ version, body }) => ({
+                "skill.json": manifest({
+                    owner: OWNER,
+                    type: "skill",
+                    name,
+                    version,
+                    description: `The ${name} skill.`,
+                }),
+                "src/SKILL.md": `---\nname: "${name}"\ndescription: "The ${name} skill."\n---\n\n# ${name}\n\n${body}\n`,
+            }),
+        }),
+        writeSubagent: (name, versions) => publish({
+            plural: "subagents",
+            type: "subagent",
+            name,
+            versions,
+            archive: ({ version, body }) => ({
+                "subagent.json": manifest({
+                    owner: OWNER,
+                    type: "subagent",
+                    name,
+                    version,
+                    description: `The ${name} subagent.`,
+                }),
+                [`src/${name}.md`]: `---\nname: ${name}\ndescription: The ${name} subagent.\n---\n\n# ${name}\n\n${body}\n`,
+            }),
+        }),
+        writeRule: (name, versions) => publish({
+            plural: "rules",
+            type: "rule",
+            name,
+            versions,
+            archive: ({ version, body }) => ({
+                "rule.json": manifest({
+                    owner: OWNER,
+                    type: "rule",
+                    name,
+                    version,
+                    description: `The ${name} rule.`,
+                }),
+                "src/RULE.md": `Guidance for ${name}: ${body}\n`,
+            }),
+        }),
+        writeHook: (name, versions) => publish({
+            plural: "hooks",
+            type: "hook",
+            name,
+            versions,
+            archive: ({ version }) => ({
+                "hook.json": manifest({
+                    owner: OWNER,
+                    type: "hook",
+                    name,
+                    version,
+                    description: `The ${name} hook.`,
+                    runtime: "bash",
+                    entrypoint: "src/hook.sh",
+                    bindings: [{ on: "tool.pre", match: { tools: ["file.write"] } }],
+                }),
+                "src/hook.sh": `#!/usr/bin/env bash\necho "${name}"\n`,
+            }),
+        }),
+        writeMcp: (name, versions) => publish({
+            plural: "mcps",
+            type: "mcp-server",
+            name,
+            versions,
+            archive: ({ version, secretInput, files }) => ({
+                "mcp.json": manifest({
+                    owner: OWNER,
+                    type: "mcp-server",
+                    name,
+                    version,
+                    server: {
+                        name: `ai.agentxm.spec/${name}`,
+                        description: `The ${name} MCP server.`,
+                        version,
+                        packages: [
+                            {
+                                registryType: "npm",
+                                identifier: `@acme/${name}`,
+                                version,
+                                transport: { type: "stdio" },
+                                ...(secretInput === undefined
+                                    ? {}
+                                    : {
+                                        environmentVariables: [
+                                            { name: secretInput, isRequired: true, isSecret: true },
+                                        ],
+                                    }),
+                            },
+                        ],
+                    },
+                }),
+                ...files,
+            }),
+        }),
+        writePack: (name, versions) => publish({
+            plural: "packs",
+            type: "pack",
+            name,
+            versions,
+            archive: ({ version, dependencies, files }) => ({
+                "pack.json": manifest({
+                    owner: OWNER,
+                    type: "pack",
+                    name,
+                    version,
+                    description: `The ${name} pack.`,
+                    dependencies,
+                }),
+                ...files,
+            }),
+            // The index carries the member constraints the resolver reads; the
+            // archive manifest must agree with it for the accepted identity to
+            // match the realized package.
+            extra: ({ dependencies }) => ({ dependencies }),
+        }),
+        writeKnowledge: (name, versions) => publish({
+            plural: "knowledge",
+            type: "knowledge",
+            name,
+            versions,
+            archive: ({ version, body }) => ({
+                "knowledge.json": manifest({
+                    owner: OWNER,
+                    type: "knowledge",
+                    name,
+                    version,
+                    description: `The ${name} knowledge bundle.`,
+                    format: { name: "okf", version: "0.2" },
+                    bundleRoot: "src",
+                }),
+                "src/index.md": `---\nokf_version: "0.2"\ndescription: "The ${name} knowledge bundle."\n---\n\n# ${name}\n\n${body}\n`,
+            }),
+        }),
+        cleanup: () => {
+            fs.rmSync(root, { recursive: true, force: true });
+        },
+    };
+};
+//# sourceMappingURL=test-registry.js.map

package/dist/src/testing.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @agentxm/extension-lifecycle deterministic fixtures and ports.
+ *
+ * A throwaway workspace with settings, lockfile, and authored extension
+ * content written as the product writes them, plus every service a lifecycle
+ * use case reads or writes through: the workspace state and its transaction
+ * scope, the projection capability, all seven materialization managers, and
+ * the plan pipeline's per-invocation services with a recording interaction
+ * port. Production source never imports this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import { AgentExecutableResolver } from "@agentxm/agent-integration";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+import { ReleaseAgePosture } from "@agentxm/extension-resolution";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { type ResolvePlanInteractionTestState } from "@agentxm/workspace-operations/testing";
+import { ExtensionSelectionInteraction } from "./install/selection-interaction.js";
+import { BundledAxmSkillAsset } from "./skills/install/bundled.js";
+import { StepFailureConversion } from "./step-failure-conversion.js";
+/**
+ * The official skill as a running executable carries it. The generator that
+ * produces the real asset belongs to the application; a specification only
+ * needs a compatible one to observe what the lifecycle does with it.
+ */
+export declare const bundledAxmSkillAsset: (options?: {
+    readonly version?: string;
+    readonly runningCliVersion?: string;
+    readonly body?: string;
+    /**
+     * The compatibility range the asset declares. The default is the bounded,
+     * wildcard-free form the install validates against; an unbounded range is
+     * what an incompatible-asset example supplies deliberately.
+     */
+    readonly cliVersionRange?: string;
+}) => Layer.Layer<BundledAxmSkillAsset>;
+export interface LifecycleFixtureOptions {
+    readonly scope?: WorkspaceScope;
+    /** Settings document for the selected scope; written as authored. */
+    readonly settings?: Readonly<Record<string, unknown>>;
+    /** Lockfile document for the selected scope; `lockfileVersion` is supplied. */
+    readonly lockfile?: Readonly<Record<string, unknown>>;
+    /** Extra files written into the project root, keyed by relative path. */
+    readonly files?: Readonly<Record<string, string>>;
+    /** Agent executables the machine reports as present. */
+    readonly installedExecutables?: ReadonlyArray<string>;
+    /**
+     * How the fixture resolves sources. `none` (the default) refuses every
+     * lookup, which is what an activation fixture wants: turning something on
+     * never fetches. `live` composes the production source-resolution layer, so
+     * an install fixture acquires from a real local package or a `file://`
+     * Registry the specification published into.
+     */
+    readonly sources?: "none" | "live";
+    /** The CLI version the official-skill compatibility policy evaluates against. */
+    readonly cliVersion?: string;
+    /**
+     * How the fixture answers "which of these did you want?". The default takes
+     * every candidate and records the question, so a specification can show
+     * that a choice was — or was not — asked for.
+     */
+    readonly select?: "all" | "none";
+    /**
+     * Whether a confirmable risk condition can be approved at a prompt, and
+     * what happens when one opens. The default has no terminal, so a
+     * confirmable condition blocks naming interactive approval instead of
+     * prompting. `onConfirm` runs while the answer is still pending, which is
+     * where a specification observes that nothing was written before it.
+     */
+    readonly confirmation?: {
+        readonly available?: boolean;
+        readonly answer?: "approved" | "declined" | "cancelled";
+        readonly onConfirm?: () => void;
+    };
+}
+/**
+ * A throwaway workspace with every service a lifecycle use case needs over
+ * it, and a pinned user home so a project-scope run can be shown to leave the
+ * user scope alone.
+ */
+export declare const makeLifecycleFixture: (options?: LifecycleFixtureOptions) => {
+    root: string;
+    home: string;
+    workspaceRoot: string;
+    writeFile: (relativePath: string, contents: string) => void;
+    readFile: (relativePath: string) => string;
+    exists: (relativePath: string) => boolean;
+    /** Every file under the project root. */
+    snapshot: () => readonly (readonly [string, string])[];
+    /** Every file under the pinned user home. */
+    homeSnapshot: () => readonly (readonly [string, string])[];
+    /** What the plan interaction port was asked to present and confirm. */
+    interactionState: () => ResolvePlanInteractionTestState;
+    /** Every time the fixture was asked which extensions to install. */
+    selectionCalls: () => ReadonlyArray<{
+        readonly type: "skill" | "subagent";
+        readonly offered: ReadonlyArray<string>;
+    }>;
+    provide: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | import("@agentxm/workspace-state").WorkspaceMutationsError, import("effect/FileSystem").FileSystem | import("effect/Path").Path | Exclude<R, StepFailureConversion | import("@agentxm/workspace-state").WorkspaceMutations | import("@agentxm/workspace-transactions").WorkspaceTransactionScope | import("@agentxm/workspace-projection").CodingAgentRepository | import("@agentxm/agent-integration").NativeWriteAuthority | import("@agentxm/workspace-state").ConfiguredAgentOutcomesProvider | import("@agentxm/extension-materialization").ExtensionManagers | import("@agentxm/workspace-transactions").FootprintRecorder | HttpClient.HttpClient | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/extension-materialization").McpSecretStore | ReleaseAgePosture | import("@agentxm/workspace-operations").ResolvePlanInteraction | SourceHostProviders | import("@agentxm/extension-materialization").SubagentManager | import("@agentxm/extension-sources").WorkspaceCatalog | import("@agentxm/extension-materialization").HookManager | import("@agentxm/extension-materialization").KnowledgeManager | import("@agentxm/extension-materialization").RuleManager | import("@agentxm/extension-materialization").SkillManager | import("@agentxm/extension-materialization").McpServerManager | import("@agentxm/extension-materialization").PackManager | ExtensionSelectionInteraction | BundledAxmSkillAsset | AgentExecutableResolver | import("@agentxm/workspace-state/live").WorkspaceStateServices | import("@agentxm/workspace-projection").ProjectionParticipants | import("@agentxm/workspace-projection").WorkspaceInvariantFacts>>;
+    cleanup: () => void;
+};
+export type LifecycleFixture = ReturnType<typeof makeLifecycleFixture>;
+export { writeAgentSkillDirectory, writeLocalHookPackage, writeLocalKnowledgePackage, writeLocalRulePackage, writeLocalSkillPackage, writeLocalSubagentPackage, type LocalPackageFixture, } from "./test-packages.js";
+export { makeLifecycleRegistry, type LifecycleRegistry, type RegistryHookVersion, type RegistryKnowledgeVersion, type RegistryMcpVersion, type RegistryPackVersion, type RegistryRuleVersion, type RegistrySkillVersion, type RegistrySubagentVersion, } from "./test-registry.js";
+//# sourceMappingURL=testing.d.ts.map

package/dist/src/testing.js

@@ -0,0 +1,241 @@
+/**
+ * @agentxm/extension-lifecycle deterministic fixtures and ports.
+ *
+ * A throwaway workspace with settings, lockfile, and authored extension
+ * content written as the product writes them, plus every service a lifecycle
+ * use case reads or writes through: the workspace state and its transaction
+ * scope, the projection capability, all seven materialization managers, and
+ * the plan pipeline's per-invocation services with a recording interaction
+ * port. Production source never imports this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as nodePath from "node:path";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import { AgentExecutableResolver } from "@agentxm/agent-integration";
+import { decodeAbsolutePathSync } from "@agentxm/extension-model/unstable/path-types";
+import { ExtensionManagersLive, HookManagerLive, KnowledgeManagerLive, McpSecretStoreLive, McpServerManagerLive, PackManagerLive, ProjectionParticipantsLive, RuleManagerLive, SkillManagerLive, SubagentManagerLive, } from "@agentxm/extension-materialization/live";
+import { ReleaseAgePosture, decideNamedRegistryVersion, makeAxmSkillCompatibilityPolicyLayer, namedRegistryCandidates, resolveVersionEntryWithReleaseAge, } from "@agentxm/extension-resolution";
+import { AxmSkillCandidateGateLive } from "@agentxm/extension-resolution/live";
+import { RegistryResolutionPolicy, SourceHostProviders } from "@agentxm/extension-sources";
+import { SourceHostProvidersLive } from "@agentxm/extension-sources/live";
+import { StepFailure } from "@agentxm/workspace-operations";
+import { PlanInvocationTest, ResolvePlanInteractionTest, } from "@agentxm/workspace-operations/testing";
+import { CodingAgentRepositoryLive, NativeWriteAuthorityLive, WorkspaceCatalogLive, WorkspaceInvariantFactsLive, } from "@agentxm/workspace-projection/live";
+import { layer as WorkspaceLayerLive } from "@agentxm/workspace-state/live";
+import { ExtensionLifecycleFailed } from "./errors.js";
+import { ExtensionSelectionInteraction } from "./install/selection-interaction.js";
+import { BundledAxmSkillAsset } from "./skills/install/bundled.js";
+import { StepFailureConversion } from "./step-failure-conversion.js";
+/**
+ * The official skill as a running executable carries it. The generator that
+ * produces the real asset belongs to the application; a specification only
+ * needs a compatible one to observe what the lifecycle does with it.
+ */
+export const bundledAxmSkillAsset = (options = {}) => {
+    const version = options.version ?? "1.0.0";
+    const nextMajor = `${Number(version.split(".")[0] ?? "0") + 1}.0.0`;
+    const body = options.body ?? "---\nname: axm\ndescription: The official AXM skill.\n---\n\n# axm\n";
+    return Layer.succeed(BundledAxmSkillAsset, {
+        manifestJson: `${JSON.stringify({
+            owner: "@agentxm",
+            type: "skill",
+            name: "axm",
+            version,
+            description: "The official AXM skill.",
+        }, null, 2)}\n`,
+        version,
+        cliVersion: version,
+        cliVersionRange: options.cliVersionRange ?? `>=${version} <${nextMajor}`,
+        sourceFiles: [{ path: "SKILL.md", base64: Buffer.from(body).toString("base64") }],
+        runningCliVersion: options.runningCliVersion ?? version,
+    });
+};
+/**
+ * Render a failure as the sentence a structural fixture reports. Assertions in
+ * this package bind to this mapping, not to the application boundary's
+ * wording: a fixture that borrowed the application's renderer would be
+ * asserting the application's words from inside the feature.
+ */
+const describeFailure = (failure) => {
+    if (failure instanceof ExtensionLifecycleFailed)
+        return failure.detail ?? failure.category;
+    if (typeof failure === "object" && failure !== null) {
+        for (const key of ["detail", "subject", "message"]) {
+            if (key in failure) {
+                const candidate = Reflect.get(failure, key);
+                if (typeof candidate === "string" && candidate.length > 0)
+                    return candidate;
+            }
+        }
+        if ("cause" in failure && failure.cause !== undefined && failure.cause !== failure) {
+            return describeFailure(failure.cause);
+        }
+    }
+    return String(failure);
+};
+/**
+ * Structural stand-in for the application's failure adapter: the feature's own
+ * failure maps 1:1; anything else keeps its detail sentence under an
+ * `internal` category.
+ */
+const TestStepFailureConversion = Layer.succeed(StepFailureConversion, {
+    toStepFailure: (failure) => failure instanceof ExtensionLifecycleFailed
+        ? new StepFailure({
+            category: failure.category,
+            detail: failure.detail ?? failure.category,
+            ...(failure.suggestions === undefined ? {} : { suggestions: failure.suggestions }),
+            ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+        })
+        : new StepFailure({ category: "internal", detail: describeFailure(failure), cause: failure }),
+    describeFailure,
+    describeFailureMessage: describeFailure,
+});
+/**
+ * A throwaway workspace with every service a lifecycle use case needs over
+ * it, and a pinned user home so a project-scope run can be shown to leave the
+ * user scope alone.
+ */
+export const makeLifecycleFixture = (options = {}) => {
+    const scope = options.scope ?? "project";
+    const root = fs.realpathSync(fs.mkdtempSync(nodePath.join(os.tmpdir(), "axm-lifecycle-")));
+    const home = fs.realpathSync(fs.mkdtempSync(nodePath.join(os.tmpdir(), "axm-lifecycle-home-")));
+    const workspaceRoot = scope === "user" ? nodePath.join(home, ".axm", "workspace") : root;
+    fs.mkdirSync(nodePath.join(root, ".axm"), { recursive: true });
+    fs.mkdirSync(nodePath.join(home, ".axm", "workspace"), { recursive: true });
+    const writeFile = (relativePath, contents) => {
+        const file = nodePath.join(root, relativePath);
+        fs.mkdirSync(nodePath.dirname(file), { recursive: true });
+        fs.writeFileSync(file, contents);
+    };
+    const readFile = (relativePath) => fs.readFileSync(nodePath.join(root, relativePath), "utf8");
+    const exists = (relativePath) => fs.existsSync(nodePath.join(root, relativePath));
+    /** Every file, symlink, and directory under a root, so purity can be proven. */
+    const snapshotUnder = (base) => {
+        const entries = [];
+        const walk = (directory) => {
+            for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+                const absolute = nodePath.join(directory, entry.name);
+                const relative = nodePath.relative(base, absolute);
+                if (entry.isSymbolicLink()) {
+                    entries.push([relative, `symlink:${fs.readlinkSync(absolute)}`]);
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    entries.push([relative, "directory"]);
+                    walk(absolute);
+                    continue;
+                }
+                entries.push([relative, fs.readFileSync(absolute, "utf8")]);
+            }
+        };
+        walk(base);
+        return entries.sort((left, right) => left[0].localeCompare(right[0]));
+    };
+    if (options.settings !== undefined) {
+        fs.writeFileSync(nodePath.join(workspaceRoot, "axm.json"), JSON.stringify({ agents: [], ...options.settings }, null, 2));
+        // JSON is valid YAML, so the lockfile fixture needs no emitter.
+        fs.writeFileSync(nodePath.join(workspaceRoot, "axm-lock.yaml"), JSON.stringify({ lockfileVersion: 7, skills: {}, ...options.lockfile }));
+    }
+    for (const [relativePath, contents] of Object.entries(options.files ?? {})) {
+        writeFile(relativePath, contents);
+    }
+    const confirmation = options.confirmation;
+    const interaction = ResolvePlanInteractionTest({
+        isConfirmationAvailable: confirmation?.available ?? false,
+        confirmApplyChanges: () => Effect.sync(() => {
+            confirmation?.onConfirm?.();
+            return confirmation?.answer ?? "approved";
+        }),
+    });
+    const selectionCalls = [];
+    const selection = Layer.succeed(ExtensionSelectionInteraction, {
+        selectSkills: (candidates) => {
+            selectionCalls.push({ type: "skill", offered: candidates.map((ref) => ref.skill.name) });
+            return Effect.succeed(options.select === "none" ? [] : candidates);
+        },
+        selectSubagents: (candidates) => {
+            selectionCalls.push({
+                type: "subagent",
+                offered: candidates.map((ref) => ref.subagent.name),
+            });
+            return Effect.succeed(options.select === "none" ? [] : candidates);
+        },
+    });
+    const environment = ConfigProvider.layer(ConfigProvider.fromEnv({ env: { AXM_USER_HOME: home } }));
+    // Activation never fetches a source: it turns on what the workspace already
+    // acquired. A fixture that could fetch would be describing installation.
+    const refusingSourceProviders = Layer.succeed(SourceHostProviders, {
+        find: () => Effect.succeed([]),
+        resolveNamedRegistry: () => Effect.die("no named registry in this fixture"),
+        fetch: () => Effect.die("no source fetch in this fixture"),
+        cloneUrl: () => Option.none(),
+        origin: () => "fixture",
+    });
+    const transport = Layer.succeed(HttpClient.HttpClient, HttpClient.make(() => Effect.die("no HTTP request in this fixture")));
+    const installedExecutables = new Set(options.installedExecutables ?? []);
+    const executables = Layer.succeed(AgentExecutableResolver, {
+        exists: (name) => Effect.succeed(installedExecutables.has(name)),
+    });
+    // One environment, built outward: the workspace state and the ports over it,
+    // then the projection services that read them, then the managers that read
+    // both, then the registry that indexes the managers. `provideMerge` keeps
+    // every layer's output, so a service a manager keeps in `R` is still there.
+    const base = Layer.provideMerge(Layer.mergeAll(WorkspaceLayerLive({
+        scope,
+        projectRoot: decodeAbsolutePathSync(root),
+        allowUninitialized: options.settings === undefined,
+    }), CodingAgentRepositoryLive, NativeWriteAuthorityLive, transport, interaction.layer, selection, executables, TestStepFailureConversion, Layer.succeed(ReleaseAgePosture, "enforce"), PlanInvocationTest, 
+    // Every AXM executable carries the official skill, so the world a
+    // lifecycle specification runs in carries one too. Only a request whose
+    // subject is `bundled` ever reads it.
+    bundledAxmSkillAsset()), environment);
+    const withProjection = Layer.provideMerge(WorkspaceCatalogLive, base);
+    // Installing resolves real sources, so the install fixtures compose the
+    // production resolution layer over the same workspace catalog.
+    const liveSourceProviders = Layer.provide(SourceHostProvidersLive, Layer.mergeAll(withProjection, Layer.provide(AxmSkillCandidateGateLive, makeAxmSkillCompatibilityPolicyLayer(options.cliVersion ?? "0.0.0-fixture")), Layer.succeed(RegistryResolutionPolicy, {
+        selectVersion: resolveVersionEntryWithReleaseAge,
+        decideNamedVersion: decideNamedRegistryVersion,
+        namedCandidates: namedRegistryCandidates,
+    })));
+    const resolvedSources = (options.sources ?? "none") === "live" ? liveSourceProviders : refusingSourceProviders;
+    const withSources = Layer.provideMerge(resolvedSources, withProjection);
+    const leafManagers = Layer.provideMerge(Layer.mergeAll(RuleManagerLive, HookManagerLive, KnowledgeManagerLive, SkillManagerLive, SubagentManagerLive, McpSecretStoreLive), withSources);
+    const withMcp = Layer.provideMerge(McpServerManagerLive, leafManagers);
+    const withPack = Layer.provideMerge(PackManagerLive, withMcp);
+    // The participant registry indexes the managers, and the invariant facts
+    // read the registry, so both come after every manager is available.
+    const withParticipants = Layer.provideMerge(ProjectionParticipantsLive, withPack);
+    const services = Layer.provideMerge(Layer.mergeAll(ExtensionManagersLive, WorkspaceInvariantFactsLive), withParticipants);
+    return {
+        root,
+        home,
+        workspaceRoot,
+        writeFile,
+        readFile,
+        exists,
+        /** Every file under the project root. */
+        snapshot: () => snapshotUnder(root),
+        /** Every file under the pinned user home. */
+        homeSnapshot: () => snapshotUnder(home),
+        /** What the plan interaction port was asked to present and confirm. */
+        interactionState: () => interaction.state,
+        /** Every time the fixture was asked which extensions to install. */
+        selectionCalls: () => selectionCalls,
+        provide: (effect) => effect.pipe(Effect.provide(services)),
+        cleanup: () => {
+            fs.rmSync(root, { recursive: true, force: true });
+            fs.rmSync(home, { recursive: true, force: true });
+        },
+    };
+};
+// Local package and Registry fixtures an install specification publishes into.
+export { writeAgentSkillDirectory, writeLocalHookPackage, writeLocalKnowledgePackage, writeLocalRulePackage, writeLocalSkillPackage, writeLocalSubagentPackage, } from "./test-packages.js";
+export { makeLifecycleRegistry, } from "./test-registry.js";
+//# sourceMappingURL=testing.js.map

package/dist/src/uninstall/retention-policy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether a removal may delete the package it withdraws.
+ *
+ * An extension declared directly and also required by an installed pack keeps
+ * its package when the direct declaration goes: the pack still depends on it.
+ * The membership fact is workspace state's; deciding that it means "retain"
+ * is this feature's.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { UninstallRetentionPolicy } from "@agentxm/extension-materialization";
+import type { WorkspaceMutationsService } from "@agentxm/workspace-state";
+import type { ExtensionLifecycleFailed } from "../errors.js";
+/** Retain a package an installed pack still requires. */
+export declare const makeWorkspaceRetentionPolicy: (ws: WorkspaceMutationsService) => UninstallRetentionPolicy<ExtensionLifecycleFailed>;
+/**
+ * A pack's own exclusive members carry no separate retention question: the
+ * pack that required them is being removed in the same transition.
+ */
+export declare const exclusiveMemberRetentionPolicy: UninstallRetentionPolicy<ExtensionLifecycleFailed>;
+//# sourceMappingURL=retention-policy.d.ts.map

package/dist/src/uninstall/retention-policy.js

@@ -0,0 +1,28 @@
+/**
+ * Whether a removal may delete the package it withdraws.
+ *
+ * An extension declared directly and also required by an installed pack keeps
+ * its package when the direct declaration goes: the pack still depends on it.
+ * The membership fact is workspace state's; deciding that it means "retain"
+ * is this feature's.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { installRefused } from "../install/vocabulary.js";
+/** Retain a package an installed pack still requires. */
+export const makeWorkspaceRetentionPolicy = (ws) => ({
+    isRequiredByInstalledPack: (args) => ws.isExtensionRequiredByInstalledPack(args.target).pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: `Pack membership for ${args.target.type} "${args.target.name}" could not be read`,
+        cause,
+    }))),
+});
+/**
+ * A pack's own exclusive members carry no separate retention question: the
+ * pack that required them is being removed in the same transition.
+ */
+export const exclusiveMemberRetentionPolicy = {
+    isRequiredByInstalledPack: () => Effect.succeed(false),
+};
+//# sourceMappingURL=retention-policy.js.map

package/dist/src/uninstall/root-intent.d.ts

@@ -0,0 +1,17 @@
+import * as Effect from "effect/Effect";
+import type { ExtensionLifecycleFailed } from "../errors.js";
+import { type InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+export declare const rootUninstallableTypeSegments: readonly ("knowledge" | "rules" | "hooks" | "mcps" | "skills" | "subagents" | "packs")[];
+export type RootUninstallableType = InstallableExtensionType;
+export interface RootUninstallIntent {
+    readonly source: string;
+    readonly type: RootUninstallableType;
+    readonly name: string;
+}
+/**
+ * Root uninstall accepts only a registry FQN: it is the one form that names
+ * the extension type without guessing, and every other spelling has a
+ * per-type command that already knows the type.
+ */
+export declare const resolveRootUninstallIntent: (input: string) => Effect.Effect<RootUninstallIntent, ExtensionLifecycleFailed>;
+//# sourceMappingURL=root-intent.d.ts.map