@agentxm/workspace-state 0.28.11 → 0.28.13

package/dist/src/workspace/accepted-resolution-writer.js

@@ -0,0 +1,67 @@
+/**
+ * Accepted-resolution writer: lockfile-only mutations of the selected scope.
+ * Each commit merges the lockfile snapshot per entry, keeps an accepted
+ * resolution that is semantically unchanged byte-identical, and is
+ * serialized by the workspace's mutation mutex.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { commitLockfileSnapshotUpdateAtPath } from "../lockfile/index.js";
+import { lockEntries } from "./entry-accessors.js";
+import { WorkspaceLocation } from "./location.js";
+import { WorkspaceStateShared } from "./shared.js";
+import { readLockfileCell } from "./state-cells.js";
+export class AcceptedResolutionWriter extends ServiceMap.Service()("@agentxm/workspace-state/AcceptedResolutionWriter") {
+}
+const normalizeForStableCompare = (value) => {
+    if (DateTime.isDateTime(value))
+        return DateTime.formatIso(value);
+    if (Array.isArray(value))
+        return value.map(normalizeForStableCompare);
+    if (typeof value === "object" && value !== null) {
+        const normalized = {};
+        for (const [key, entryValue] of Object.entries(value).sort(([left], [right]) => left.localeCompare(right))) {
+            normalized[key] = normalizeForStableCompare(entryValue);
+        }
+        return normalized;
+    }
+    return value;
+};
+/** Structural equality that treats date-times by their ISO rendering. */
+export const stableCompare = (left, right) => JSON.stringify(normalizeForStableCompare(left)) ===
+    JSON.stringify(normalizeForStableCompare(right));
+export const lockEntrySemanticallyEqual = (current, next) => current !== undefined && stableCompare(current, next);
+/** Keep the recorded object when the replacement carries the same facts. */
+export const preserveAcceptedResolutionOnNoop = (current, next) => (lockEntrySemanticallyEqual(current, next) && current !== undefined ? current : next);
+/** Types whose semantically unchanged resolution skips the commit entirely. */
+const skipsUnchangedCommit = (type) => type === "skill" || type === "subagent";
+export const makeAcceptedResolutionWriter = (location, mutex) => {
+    const current = readLockfileCell(location, location.runtimeDir);
+    const commit = (base, next) => commitLockfileSnapshotUpdateAtPath(location.lockPath, base, next);
+    const serialized = mutex.withPermits(1);
+    return {
+        setAccepted: (type, key, entry) => serialized(Effect.gen(function* () {
+            const lockfile = yield* current;
+            const accessor = lockEntries[type];
+            const previous = accessor.entries(lockfile)[key];
+            if (skipsUnchangedCommit(type) && lockEntrySemanticallyEqual(previous, entry))
+                return;
+            yield* commit(lockfile, accessor.set(lockfile, key, preserveAcceptedResolutionOnNoop(previous, entry)));
+        })).pipe(Effect.withSpan("AcceptedResolutionWriter.setAccepted")),
+        removeAccepted: (type, key) => serialized(Effect.gen(function* () {
+            const lockfile = yield* current;
+            const accessor = lockEntries[type];
+            if (accessor.entries(lockfile)[key] === undefined)
+                return;
+            yield* commit(lockfile, accessor.remove(lockfile, key));
+        })).pipe(Effect.withSpan("AcceptedResolutionWriter.removeAccepted")),
+    };
+};
+export const AcceptedResolutionWriterLive = Layer.effect(AcceptedResolutionWriter, Effect.gen(function* () {
+    return makeAcceptedResolutionWriter(yield* WorkspaceLocation, (yield* WorkspaceStateShared).mutex);
+}));
+//# sourceMappingURL=accepted-resolution-writer.js.map

package/dist/src/workspace/canonical-observation.js

@@ -12,7 +12,7 @@ import { KnowledgeManifestSchema } from "@agentxm/extension-model/unstable/knowl
 import { McpServerManifestSchema } from "@agentxm/extension-model/unstable/mcps/manifest-schema";
 import { PackManifestSchema } from "@agentxm/extension-model/unstable/packs/manifest-schema";
 import { RuleManifestSchema } from "@agentxm/extension-model/unstable/rules/manifest-schema";
-import { parseSkillMd } from "@agentxm/registry-protocol/unstable/content";
+import { parseSkillMd } from "@agentxm/extension-content";
 import { SkillManifestSchema } from "@agentxm/extension-model/unstable/skills/manifest-schema";
 import { SubagentManifestSchema } from "@agentxm/extension-model/unstable/subagents/manifest-schema";
 import { printSourceParams } from "@agentxm/extension-model/unstable/sources/printer";

package/dist/src/workspace/configured-entry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared helpers for configured extension entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface ConfiguredEntryEnabledState {
+    readonly enabled: boolean;
+}
+export declare const isConfiguredEntryEnabled: (entry: ConfiguredEntryEnabledState) => boolean;
+export declare const enabledConfiguredEntries: <TEntry extends ConfiguredEntryEnabledState>(entries: Readonly<Record<string, TEntry>>) => ReadonlyArray<readonly [string, TEntry]>;
+//# sourceMappingURL=configured-entry.d.ts.map

package/dist/src/workspace/configured-entry.js

@@ -0,0 +1,8 @@
+/**
+ * Shared helpers for configured extension entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const isConfiguredEntryEnabled = (entry) => entry.enabled;
+export const enabledConfiguredEntries = (entries) => Object.entries(entries).filter(([, entry]) => isConfiguredEntryEnabled(entry));
+//# sourceMappingURL=configured-entry.js.map

package/dist/src/workspace/create-symlink.d.ts

@@ -22,5 +22,5 @@ export type SymlinkResult = "created" | "replaced" | "no-op" | "skipped";
 export declare const createSymlink: (opts: {
     readonly target: string;
     readonly link: string;
-}) => Effect.Effect<"skipped" | "created" | "replaced" | "no-op", import("./transaction.js").WorkspaceSnapshotError | SymlinkCreationError, FileSystem.FileSystem | Path.Path>;
+}) => Effect.Effect<"skipped" | "created" | "replaced" | "no-op", import("@agentxm/workspace-transactions").WorkspaceSnapshotError | SymlinkCreationError, FileSystem.FileSystem | Path.Path>;
 //# sourceMappingURL=create-symlink.d.ts.map

package/dist/src/workspace/create-symlink.js

@@ -3,8 +3,7 @@ import * as Path from "effect/Path";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import { SymlinkCreationError } from "./errors.js";
-import { protectCreatedAncestors, protectWorkspacePath } from "./transaction.js";
-import { recordFootprint } from "./footprint-recorder.js";
+import { protectCreatedAncestors, protectWorkspacePath, recordFootprint, } from "@agentxm/workspace-transactions";
 import { resolveParentSymlinks } from "../utils/resolve-parent-symlinks.js";
 /**
  * Creates a relative symlink from `link` to `target`, handling the full

package/dist/src/workspace/desired-identity.d.ts

@@ -0,0 +1,19 @@
+import { type ExtensionName, type ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+export type DesiredPackageAuthority = "registry" | "workspace";
+export interface DecodedDesiredExtensionIdentity {
+    readonly authority: DesiredPackageAuthority;
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly fqn: string;
+}
+/**
+ * Decode the source-qualified identity stored in the desired-state graph.
+ *
+ * This is deliberately narrower than source-locator parsing: desired graph
+ * identities are either validated Registry FQNs or `workspace:` followed by a
+ * validated FQN. Unknown authorities fail closed.
+ */
+export declare const decodeDesiredExtensionIdentity: (identity: string) => DecodedDesiredExtensionIdentity | undefined;
+//# sourceMappingURL=desired-identity.d.ts.map

package/dist/src/workspace/desired-identity.js

@@ -0,0 +1,26 @@
+import { parseExtensionFqnParts, } from "@agentxm/extension-model/unstable/extensions/common";
+const workspacePrefix = "workspace:";
+/**
+ * Decode the source-qualified identity stored in the desired-state graph.
+ *
+ * This is deliberately narrower than source-locator parsing: desired graph
+ * identities are either validated Registry FQNs or `workspace:` followed by a
+ * validated FQN. Unknown authorities fail closed.
+ */
+export const decodeDesiredExtensionIdentity = (identity) => {
+    const authority = identity.startsWith(workspacePrefix)
+        ? "workspace"
+        : "registry";
+    const fqn = authority === "workspace" ? identity.slice(workspacePrefix.length) : identity;
+    const parsed = parseExtensionFqnParts(fqn);
+    if (parsed === undefined)
+        return undefined;
+    return {
+        authority,
+        owner: parsed.owner,
+        type: parsed.type,
+        name: parsed.name,
+        fqn,
+    };
+};
+//# sourceMappingURL=desired-identity.js.map

package/dist/src/workspace/desired-state-reader.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Desired-state reader: the graph derived from settings and installed or
+ * prospective Pack manifests, validated against the accepted lock state, and
+ * the Pack-membership query commands ask before removing an extension.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import type * as Path from "effect/Path";
+import { type DesiredStateGraph, type ProspectivePackRef } from "./desired-state-graph.js";
+import { DesiredPackGraphIncomplete } from "./errors.js";
+import { WorkspaceLocation, type WorkspaceLocationService } from "./location.js";
+import type { ExtensionTarget, WorkspaceStateReadFailure } from "./service-interface.js";
+import { SettingsReader, type SettingsReaderService } from "./settings-reader.js";
+export interface DesiredStateReaderService {
+    /** Build desired extension state from settings and installed or prospective Pack manifests. */
+    readonly graph: (options?: {
+        readonly prospectivePacks?: ReadonlyArray<ProspectivePackRef>;
+    }) => Effect.Effect<DesiredStateGraph, WorkspaceStateReadFailure, FileSystem.FileSystem | Path.Path>;
+    /** Whether an installed Pack's dependency maps reference the target. */
+    readonly isRequiredByInstalledPack: (target: ExtensionTarget) => Effect.Effect<boolean, WorkspaceStateReadFailure | DesiredPackGraphIncomplete, FileSystem.FileSystem | Path.Path>;
+}
+declare const DesiredStateReader_base: ServiceMap.ServiceClass<DesiredStateReader, "@agentxm/workspace-state/DesiredStateReader", DesiredStateReaderService>;
+export declare class DesiredStateReader extends DesiredStateReader_base {
+}
+export declare const makeDesiredStateReader: (location: WorkspaceLocationService, settings: SettingsReaderService) => DesiredStateReaderService;
+export declare const DesiredStateReaderLive: Layer.Layer<DesiredStateReader, never, WorkspaceLocation | SettingsReader>;
+export {};
+//# sourceMappingURL=desired-state-reader.d.ts.map

package/dist/src/workspace/desired-state-reader.js

@@ -0,0 +1,56 @@
+/**
+ * Desired-state reader: the graph derived from settings and installed or
+ * prospective Pack manifests, validated against the accepted lock state, and
+ * the Pack-membership query commands ask before removing an extension.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+import { buildDesiredStateGraph, } from "./desired-state-graph.js";
+import { validateDesiredPackLock } from "./desired-pack-lock.js";
+import { DesiredPackGraphIncomplete } from "./errors.js";
+import { WorkspaceLocation } from "./location.js";
+import { SettingsReader } from "./settings-reader.js";
+import { readLockfileCell } from "./state-cells.js";
+export class DesiredStateReader extends ServiceMap.Service()("@agentxm/workspace-state/DesiredStateReader") {
+}
+export const makeDesiredStateReader = (location, settings) => {
+    const graph = (options) => Effect.gen(function* () {
+        const current = yield* settings.settings;
+        const configuredSources = yield* settings.configuredSources;
+        const layout = yield* Ref.get(location.layout);
+        const registryAuthorities = Object.fromEntries(configuredSources.flatMap((source) => source.type === "registry" ? [[source.name, source.location]] : []));
+        const built = yield* buildDesiredStateGraph({
+            baseDir: location.baseDir,
+            settings: current,
+            layout,
+            registryAuthorities,
+            ...(options?.prospectivePacks === undefined
+                ? {}
+                : { prospectivePacks: options.prospectivePacks }),
+        });
+        const lockfile = yield* readLockfileCell(location, location.runtimeDir);
+        return yield* validateDesiredPackLock({ graph: built, lockfile, layout });
+    }).pipe(Effect.withSpan("DesiredStateReader.graph"));
+    return {
+        graph,
+        isRequiredByInstalledPack: (target) => Effect.gen(function* () {
+            if (target.type === "pack")
+                return false;
+            const current = yield* graph();
+            if (!current.complete) {
+                return yield* new DesiredPackGraphIncomplete();
+            }
+            return current.nodes.some((node) => node.type === target.type &&
+                node.name === target.name &&
+                node.origins.some((origin) => origin.type === "pack"));
+        }),
+    };
+};
+export const DesiredStateReaderLive = Layer.effect(DesiredStateReader, Effect.gen(function* () {
+    return makeDesiredStateReader(yield* WorkspaceLocation, yield* SettingsReader);
+}));
+//# sourceMappingURL=desired-state-reader.js.map

package/dist/src/workspace/desired-state-writer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Desired-state writer: the coupled settings-and-lockfile mutations that
+ * declare or undeclare one extension in the selected scope. Declaring writes
+ * the desired entry and records its accepted resolution together;
+ * undeclaring removes both. The per-type shapes differ where the schemas
+ * do — Packs keep their enabled flag, MCP servers keep env and enabled and
+ * are keyed by resolution identity, Knowledge keeps its instruction entry —
+ * and each family's semantics are preserved here exactly.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import type * as Path from "effect/Path";
+import type * as Semaphore from "effect/Semaphore";
+import type { InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import { DesiredStateReader, type DesiredStateReaderService } from "./desired-state-reader.js";
+import { WorkspaceLocation, type WorkspaceLocationService } from "./location.js";
+import type { SetHookArgs, SetKnowledgeArgs, SetMcpServerArgs, SetPackArgs, SetRuleArgs, SetSkillArgs, SetSubagentArgs, WorkspaceStateMutationFailure } from "./service-interface.js";
+import { WorkspaceStateShared } from "./shared.js";
+/** The declaration each installable extension type accepts. */
+export interface DeclareArgsByType {
+    readonly skill: SetSkillArgs;
+    readonly pack: SetPackArgs;
+    readonly "mcp-server": SetMcpServerArgs;
+    readonly subagent: SetSubagentArgs;
+    readonly rule: SetRuleArgs;
+    readonly hook: SetHookArgs;
+    readonly knowledge: SetKnowledgeArgs;
+}
+type Write = Effect.Effect<void, WorkspaceStateMutationFailure, FileSystem.FileSystem | Path.Path>;
+export interface DesiredStateWriterService {
+    /** Declare the extension in settings and record its accepted resolution. */
+    readonly declare: <T extends InstallableExtensionType>(type: T, args: DeclareArgsByType[T]) => Write;
+    /** Remove the extension from settings and its accepted resolution. No-op when absent. */
+    readonly undeclare: (type: InstallableExtensionType, name: string) => Write;
+}
+declare const DesiredStateWriter_base: ServiceMap.ServiceClass<DesiredStateWriter, "@agentxm/workspace-state/DesiredStateWriter", DesiredStateWriterService>;
+export declare class DesiredStateWriter extends DesiredStateWriter_base {
+}
+export declare const makeDesiredStateWriter: (location: WorkspaceLocationService, desiredState: DesiredStateReaderService, mutex: Semaphore.Semaphore) => DesiredStateWriterService;
+export declare const DesiredStateWriterLive: Layer.Layer<DesiredStateWriter, never, WorkspaceLocation | DesiredStateReader | WorkspaceStateShared>;
+export {};
+//# sourceMappingURL=desired-state-writer.d.ts.map

package/dist/src/workspace/desired-state-writer.js

@@ -0,0 +1,214 @@
+/**
+ * Desired-state writer: the coupled settings-and-lockfile mutations that
+ * declare or undeclare one extension in the selected scope. Declaring writes
+ * the desired entry and records its accepted resolution together;
+ * undeclaring removes both. The per-type shapes differ where the schemas
+ * do — Packs keep their enabled flag, MCP servers keep env and enabled and
+ * are keyed by resolution identity, Knowledge keeps its instruction entry —
+ * and each family's semantics are preserved here exactly.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { decodeExtensionNameSync, formatFqn } from "@agentxm/extension-model/unstable/extensions";
+import { printSourceParams } from "@agentxm/extension-model/unstable/sources/printer";
+import { commitLockfileSnapshotUpdateAtPath } from "../lockfile/index.js";
+import { writeSettingsAtPath, } from "../settings/index.js";
+import { lockEntrySemanticallyEqual, preserveAcceptedResolutionOnNoop, stableCompare, } from "./accepted-resolution-writer.js";
+import { DesiredStateReader } from "./desired-state-reader.js";
+import { lockEntries, settingsEntries } from "./entry-accessors.js";
+import { lockEntryToSourceParams } from "./lock-entry-to-source-params.js";
+import { WorkspaceLocation } from "./location.js";
+import { WorkspaceStateShared } from "./shared.js";
+import { readLockfileCell, readSettingsOrDefault } from "./state-cells.js";
+export class DesiredStateWriter extends ServiceMap.Service()("@agentxm/workspace-state/DesiredStateWriter") {
+}
+/** The settings source locator a Registry resolution is declared under. */
+const registryLocator = (sourceName, fqn, versionRange) => `${sourceName}:${Option.isSome(versionRange) ? `${fqn}@${versionRange.value}` : fqn}`;
+export const makeDesiredStateWriter = (location, desiredState, mutex) => {
+    const settings = readSettingsOrDefault(location, location.runtimeDir);
+    const lockfile = readLockfileCell(location, location.runtimeDir);
+    const writeSettings = (next) => writeSettingsAtPath(location.settingsPath, next);
+    const commit = (base, next) => commitLockfileSnapshotUpdateAtPath(location.lockPath, base, next);
+    const serialized = mutex.withPermits(1);
+    /** Declare a sourced entry then record the resolution, always writing both. */
+    const declareSourced = (type, configured, accepted, makeEntry, name, lockEntry, versionRange) => Effect.gen(function* () {
+        const source = lockEntry.type === "registry"
+            ? registryLocator(lockEntry.sourceName, formatFqn({ owner: lockEntry.owner, type, name: decodeExtensionNameSync(name) }), versionRange)
+            : printSourceParams(lockEntryToSourceParams(lockEntry));
+        yield* writeSettings(configured.set(yield* settings, name, makeEntry(source)));
+        const current = yield* lockfile;
+        const previous = accepted.entries(current)[name];
+        yield* commit(current, accepted.set(current, name, preserveAcceptedResolutionOnNoop(previous, lockEntry)));
+    });
+    const declareSkill = ({ name, lockEntry, versionRange }) => Effect.gen(function* () {
+        const source = lockEntry.type === "registry"
+            ? registryLocator(lockEntry.sourceName, formatFqn({
+                owner: lockEntry.owner,
+                type: "skill",
+                name: decodeExtensionNameSync(name),
+            }), versionRange)
+            : printSourceParams(lockEntryToSourceParams(lockEntry));
+        const current = yield* settings;
+        const nextEntry = { source, enabled: true };
+        const currentLockfile = yield* lockfile;
+        const currentLockEntry = currentLockfile.skills[name];
+        if (!stableCompare(settingsEntries.skill.entries(current)[name], nextEntry)) {
+            yield* writeSettings(settingsEntries.skill.set(current, name, nextEntry));
+        }
+        if (lockEntrySemanticallyEqual(currentLockEntry, lockEntry))
+            return;
+        yield* commit(currentLockfile, lockEntries.skill.set(currentLockfile, name, preserveAcceptedResolutionOnNoop(currentLockEntry, lockEntry)));
+    });
+    const declareSubagent = ({ name, lockEntry, versionRange }) => Effect.gen(function* () {
+        const source = lockEntry.type === "registry"
+            ? registryLocator(lockEntry.sourceName, formatFqn({
+                owner: lockEntry.owner,
+                type: "subagent",
+                name: decodeExtensionNameSync(name),
+            }), versionRange)
+            : printSourceParams(lockEntryToSourceParams(lockEntry));
+        const current = yield* settings;
+        const nextEntry = { source, enabled: true };
+        const currentLockfile = yield* lockfile;
+        const currentLockEntry = lockEntries.subagent.entries(currentLockfile)[name];
+        if (!stableCompare(settingsEntries.subagent.entries(current)[name], nextEntry)) {
+            yield* writeSettings(settingsEntries.subagent.set(current, name, nextEntry));
+        }
+        if (lockEntrySemanticallyEqual(currentLockEntry, lockEntry))
+            return;
+        yield* commit(currentLockfile, lockEntries.subagent.set(currentLockfile, name, preserveAcceptedResolutionOnNoop(currentLockEntry, lockEntry)));
+    });
+    const declareKnowledge = ({ name, lockEntry, versionRange }) => Effect.gen(function* () {
+        const source = lockEntry.type === "registry"
+            ? registryLocator(lockEntry.sourceName, formatFqn({
+                owner: lockEntry.owner,
+                type: "knowledge",
+                name: decodeExtensionNameSync(name),
+            }), versionRange)
+            : printSourceParams(lockEntryToSourceParams(lockEntry));
+        const current = yield* settings;
+        const currentEntry = settingsEntries.knowledge.entries(current)[name];
+        yield* writeSettings(settingsEntries.knowledge.set(current, name, {
+            source,
+            enabled: true,
+            ...(currentEntry?.instructionEntry === undefined
+                ? {}
+                : { instructionEntry: currentEntry.instructionEntry }),
+        }));
+        const currentLockfile = yield* lockfile;
+        const previous = lockEntries.knowledge.entries(currentLockfile)[name];
+        yield* commit(currentLockfile, lockEntries.knowledge.set(currentLockfile, name, preserveAcceptedResolutionOnNoop(previous, lockEntry)));
+    });
+    const declarePack = (args) => Effect.gen(function* () {
+        const { versionRange, ...lockEntry } = args;
+        const name = lockEntry.name;
+        const source = registryLocator(lockEntry.sourceName, formatFqn({ owner: args.owner, type: "pack", name: decodeExtensionNameSync(name) }), versionRange);
+        const current = yield* settings;
+        const enabled = settingsEntries.pack.entries(current)[name]?.enabled ?? true;
+        yield* writeSettings(settingsEntries.pack.set(current, name, { source, enabled }));
+        const currentLockfile = yield* lockfile;
+        const previous = lockEntries.pack.entries(currentLockfile)[name];
+        yield* commit(currentLockfile, lockEntries.pack.set(currentLockfile, name, preserveAcceptedResolutionOnNoop(previous, lockEntry)));
+    });
+    const declareMcpServer = ({ name, resolutionKey, lockEntry, versionRange, env, enabled, }) => Effect.gen(function* () {
+        const current = yield* settings;
+        const existing = settingsEntries["mcp-server"].entries(current)[name];
+        yield* writeSettings(settingsEntries["mcp-server"].set(current, name, {
+            kind: "sourced",
+            source: lockEntry.type === "registry"
+                ? registryLocator(lockEntry.sourceName, formatFqn({ owner: lockEntry.owner, type: "mcp-server", name: lockEntry.name }), versionRange)
+                : printSourceParams(lockEntryToSourceParams(lockEntry)),
+            enabled: enabled ?? existing?.enabled ?? true,
+            env: env ?? existing?.env ?? {},
+        }));
+        const currentLockfile = yield* lockfile;
+        const previous = lockEntries["mcp-server"].entries(currentLockfile)[resolutionKey];
+        yield* commit(currentLockfile, lockEntries["mcp-server"].set(currentLockfile, resolutionKey, preserveAcceptedResolutionOnNoop(previous, lockEntry)));
+    });
+    const declareByType = {
+        skill: declareSkill,
+        pack: declarePack,
+        "mcp-server": declareMcpServer,
+        subagent: declareSubagent,
+        rule: ({ name, lockEntry, versionRange }) => declareSourced("rule", settingsEntries.rule, lockEntries.rule, (source) => ({ source, enabled: true }), name, lockEntry, versionRange),
+        hook: ({ name, lockEntry, versionRange }) => declareSourced("hook", settingsEntries.hook, lockEntries.hook, (source) => ({ source, enabled: true }), name, lockEntry, versionRange),
+        knowledge: declareKnowledge,
+    };
+    /** Remove both documents' entries, writing each document unconditionally. */
+    const undeclareBoth = (type, name) => Effect.gen(function* () {
+        const current = yield* settings;
+        const currentLockfile = yield* lockfile;
+        yield* writeSettings(settingsEntries[type].remove(current, name));
+        yield* commit(currentLockfile, lockEntries[type].remove(currentLockfile, name));
+    });
+    /** Remove each document's entry only when present. */
+    const undeclarePresent = (type, name) => Effect.gen(function* () {
+        const current = yield* settings;
+        const configured = settingsEntries[type];
+        if (configured.entries(current)[name] !== undefined) {
+            yield* writeSettings(configured.remove(current, name));
+        }
+        const currentLockfile = yield* lockfile;
+        const accepted = lockEntries[type];
+        if (accepted.entries(currentLockfile)[name] !== undefined) {
+            yield* commit(currentLockfile, accepted.remove(currentLockfile, name));
+        }
+    });
+    /** A Pack not declared in settings is left alone entirely. */
+    const undeclarePack = (name) => Effect.gen(function* () {
+        const current = yield* settings;
+        if (Option.isNone(settingsEntries.pack.entry(current, name)))
+            return;
+        yield* writeSettings(settingsEntries.pack.remove(current, name));
+        const currentLockfile = yield* lockfile;
+        if (Option.isSome(lockEntries.pack.entry(currentLockfile, name))) {
+            yield* commit(currentLockfile, lockEntries.pack.remove(currentLockfile, name));
+        }
+    });
+    /**
+     * An MCP server's accepted resolution is shared by every connection and
+     * Pack member that resolves to the same identity; it is removed only when
+     * this connection was its last user.
+     */
+    const undeclareMcpServer = (name) => Effect.gen(function* () {
+        const graph = yield* desiredState.graph();
+        const desiredNode = graph.nodes.find((node) => node.type === "mcp-server" && node.name === name);
+        const closure = desiredNode === undefined || desiredNode.authority === "inline"
+            ? undefined
+            : graph.mcpSourceClosures.find((candidate) => candidate.identity === desiredNode.identity);
+        const current = yield* settings;
+        if (Option.isSome(settingsEntries["mcp-server"].entry(current, name))) {
+            yield* writeSettings(settingsEntries["mcp-server"].remove(current, name));
+        }
+        const currentLockfile = yield* lockfile;
+        const resolutionKey = desiredNode?.identity;
+        const keepSharedResolution = closure !== undefined &&
+            (closure.localNames.length > 1 || closure.origins.some((origin) => origin.type === "pack"));
+        if (resolutionKey !== undefined &&
+            !keepSharedResolution &&
+            Option.isSome(lockEntries["mcp-server"].entry(currentLockfile, resolutionKey))) {
+            yield* commit(currentLockfile, lockEntries["mcp-server"].remove(currentLockfile, resolutionKey));
+        }
+    });
+    const undeclareByType = {
+        skill: (name) => undeclarePresent("skill", name),
+        pack: undeclarePack,
+        "mcp-server": undeclareMcpServer,
+        subagent: (name) => undeclarePresent("subagent", name),
+        rule: (name) => undeclareBoth("rule", name),
+        hook: (name) => undeclareBoth("hook", name),
+        knowledge: (name) => undeclareBoth("knowledge", name),
+    };
+    return {
+        declare: (type, args) => serialized(declareByType[type](args)).pipe(Effect.withSpan("DesiredStateWriter.declare")),
+        undeclare: (type, name) => serialized(undeclareByType[type](name)).pipe(Effect.withSpan("DesiredStateWriter.undeclare")),
+    };
+};
+export const DesiredStateWriterLive = Layer.effect(DesiredStateWriter, Effect.gen(function* () {
+    return makeDesiredStateWriter(yield* WorkspaceLocation, yield* DesiredStateReader, (yield* WorkspaceStateShared).mutex);
+}));
+//# sourceMappingURL=desired-state-writer.js.map

package/dist/src/workspace/entry-accessors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Type-indexed access to the per-type settings and lockfile entry maps.
+ *
+ * Settings and the lockfile keep one map per installable extension type under
+ * type-specific keys. The accessors here let the narrow state services read
+ * and write those maps generically — `entries(type)`, `setEntry(type, …)` —
+ * while every map keeps its exact schema type, so a caller that names the
+ * type statically gets the matching entry type back.
+ */
+import * as Option from "effect/Option";
+import type { InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import type { HookLockEntry, KnowledgeLockEntry, Lockfile, McpServerLockEntry, PackLockEntry, RuleLockEntry, SkillLockEntry, SubagentLockEntry } from "../lockfile/schema.js";
+import type { HookEntry, KnowledgeEntry, McpServerEntry, PackEntry, RuleEntry, Settings, SkillEntry, SubagentEntry } from "../settings/schema.js";
+/** The settings entry type declared for each installable extension type. */
+export interface SettingsEntryByType {
+    readonly skill: SkillEntry;
+    readonly pack: PackEntry;
+    readonly "mcp-server": McpServerEntry;
+    readonly subagent: SubagentEntry;
+    readonly rule: RuleEntry;
+    readonly hook: HookEntry;
+    readonly knowledge: KnowledgeEntry;
+}
+/** The accepted-resolution entry type recorded for each installable extension type. */
+export interface LockEntryByType {
+    readonly skill: SkillLockEntry;
+    readonly pack: PackLockEntry;
+    readonly "mcp-server": McpServerLockEntry;
+    readonly subagent: SubagentLockEntry;
+    readonly rule: RuleLockEntry;
+    readonly hook: HookLockEntry;
+    readonly knowledge: KnowledgeLockEntry;
+}
+export type SettingsEntriesOf<T extends InstallableExtensionType> = Readonly<Record<string, SettingsEntryByType[T]>>;
+export type LockEntriesOf<T extends InstallableExtensionType> = Readonly<Record<string, LockEntryByType[T]>>;
+export interface EntriesAccessor<Document, Entry> {
+    readonly entries: (document: Document) => Readonly<Record<string, Entry>>;
+    readonly entry: (document: Document, name: string) => Option.Option<Entry>;
+    readonly set: (document: Document, name: string, entry: Entry) => Document;
+    readonly remove: (document: Document, name: string) => Document;
+}
+/** Settings entry maps by type; absent maps read as empty. */
+export declare const settingsEntries: {
+    readonly [T in InstallableExtensionType]: EntriesAccessor<Settings, SettingsEntryByType[T]>;
+};
+/** Lockfile entry maps by type; absent maps read as empty. */
+export declare const lockEntries: {
+    readonly [T in InstallableExtensionType]: EntriesAccessor<Lockfile, LockEntryByType[T]>;
+};
+//# sourceMappingURL=entry-accessors.d.ts.map

package/dist/src/workspace/entry-accessors.js

@@ -0,0 +1,41 @@
+/**
+ * Type-indexed access to the per-type settings and lockfile entry maps.
+ *
+ * Settings and the lockfile keep one map per installable extension type under
+ * type-specific keys. The accessors here let the narrow state services read
+ * and write those maps generically — `entries(type)`, `setEntry(type, …)` —
+ * while every map keeps its exact schema type, so a caller that names the
+ * type statically gets the matching entry type back.
+ */
+import * as Option from "effect/Option";
+const accessor = (read, write) => ({
+    entries: read,
+    entry: (document, name) => Option.fromUndefinedOr(read(document)[name]),
+    set: (document, name, entry) => write(document, { ...read(document), [name]: entry }),
+    remove: (document, name) => {
+        const { [name]: removed, ...remaining } = read(document);
+        void removed;
+        return write(document, remaining);
+    },
+});
+/** Settings entry maps by type; absent maps read as empty. */
+export const settingsEntries = {
+    skill: accessor((settings) => settings.skills ?? {}, (settings, skills) => ({ ...settings, skills })),
+    pack: accessor((settings) => settings.packs ?? {}, (settings, packs) => ({ ...settings, packs })),
+    "mcp-server": accessor((settings) => settings.mcpServers ?? {}, (settings, mcpServers) => ({ ...settings, mcpServers })),
+    subagent: accessor((settings) => settings.subagents ?? {}, (settings, subagents) => ({ ...settings, subagents })),
+    rule: accessor((settings) => settings.rules ?? {}, (settings, rules) => ({ ...settings, rules })),
+    hook: accessor((settings) => settings.hooks ?? {}, (settings, hooks) => ({ ...settings, hooks })),
+    knowledge: accessor((settings) => settings.knowledge ?? {}, (settings, knowledge) => ({ ...settings, knowledge })),
+};
+/** Lockfile entry maps by type; absent maps read as empty. */
+export const lockEntries = {
+    skill: accessor((lockfile) => lockfile.skills, (lockfile, skills) => ({ ...lockfile, skills })),
+    pack: accessor((lockfile) => lockfile.packs ?? {}, (lockfile, packs) => ({ ...lockfile, packs })),
+    "mcp-server": accessor((lockfile) => lockfile.mcpServers ?? {}, (lockfile, mcpServers) => ({ ...lockfile, mcpServers })),
+    subagent: accessor((lockfile) => lockfile.subagents ?? {}, (lockfile, subagents) => ({ ...lockfile, subagents })),
+    rule: accessor((lockfile) => lockfile.rules ?? {}, (lockfile, rules) => ({ ...lockfile, rules })),
+    hook: accessor((lockfile) => lockfile.hooks ?? {}, (lockfile, hooks) => ({ ...lockfile, hooks })),
+    knowledge: accessor((lockfile) => lockfile.knowledge ?? {}, (lockfile, knowledge) => ({ ...lockfile, knowledge })),
+};
+//# sourceMappingURL=entry-accessors.js.map