@agentxm/extension-materialization 0.28.14-preview.1789139351.5cd4595aa

package/dist/src/knowledge/manager.js

@@ -0,0 +1,709 @@
+// @effect-diagnostics anyUnknownInErrorContext:off — schema and filesystem errors are swept into KnowledgeIoFailed inside this manager
+/** Lifecycle manager for isolated Open Knowledge Format bundles. */
+import * as Effect from "effect/Effect";
+import { stripFileProtocol } from "@agentxm/registry-client";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Result from "effect/Result";
+import { PlatformError } from "effect/PlatformError";
+import { KnowledgeDefinitionInvalid, KnowledgeDesiredStateUnreconcilable, KnowledgeInstallStateMissing, KnowledgeIoFailed, KnowledgeObservableContractViolated, KnowledgeResolutionMissing, KnowledgeUnavailable, } from "./errors.js";
+import { applyProjectionPlans, formatProjectionExclusions, planAggregateProjection, requireCompleteGraph, KNOWLEDGE_REGION_OWNER, reconcileKnowledgeDiscovery, resolveInstructionsConfig, } from "@agentxm/workspace-projection";
+import { canReuseInstalledPackage, materializeExternalPackage, } from "../extensions/canonical-directory.js";
+import { materializeRegistryPackage } from "../registry-materialization.js";
+import { computeExtensionPathsForLayout, extensionPathSourceFromLockEntry, } from "@agentxm/workspace-state";
+import { computePackageContentHash } from "@agentxm/workspace-state";
+import { computeMaterializedTreeIntegrity } from "@agentxm/workspace-state";
+import { acceptedRegistryVersionForRef, validateExactResolvedVersion, } from "@agentxm/workspace-state";
+import { gitSourceLockFields } from "@agentxm/workspace-state";
+import { SourceHostProviders, WorkspaceCatalog } from "@agentxm/extension-sources";
+import { knowledgeLockEntryToRef } from "@agentxm/workspace-state";
+import { makeWorkspaceRelativeSourcePath } from "@agentxm/extension-model/unstable/path-types";
+import { recordFootprint } from "@agentxm/workspace-transactions";
+import { makeWorkspaceRelativePath } from "@agentxm/extension-model/unstable/path-types";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { usableAcceptedCanonicalRef } from "@agentxm/workspace-state";
+import { getKnowledgeLockEntries } from "@agentxm/workspace-state";
+import { NO_MATERIALIZATION_OBSERVATION } from "../manager-contract.js";
+import { KnowledgeManager, } from "../managers.js";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { runWorkspaceTransaction } from "@agentxm/workspace-transactions";
+import { isObservedInstalled } from "@agentxm/workspace-state";
+import { acceptedCanonicalObservation, prepareAcceptedCanonicalTransition, removableAcceptedCanonicalPath, } from "@agentxm/workspace-state";
+import { protectWorkspacePath } from "@agentxm/workspace-transactions";
+import { isSourcedDesiredExtension } from "@agentxm/workspace-state";
+import { KNOWLEDGE_EXTENSION_DIR, KNOWLEDGE_MANIFEST_FILENAME, KNOWLEDGE_SOURCE_DIR, KnowledgeManifestSchema, } from "@agentxm/extension-model/unstable/knowledge/manifest-schema";
+import { inspectKnowledgeBundle, } from "@agentxm/extension-content/knowledge";
+import { resolveKnowledgeInstructionEntry } from "@agentxm/workspace-projection";
+const decodeManifest = Schema.decodeUnknownEffect(KnowledgeManifestSchema);
+const registryLockEntry = (ref, treeIntegrity) => ({
+    type: "registry",
+    sourceType: "registry",
+    packageFormat: "agentxm",
+    endpoint: ref.source.location,
+    extensionType: "knowledge",
+    workspaceName: ref.knowledge.name,
+    owner: ref.owner,
+    name: ref.name,
+    resolvedVersion: decodeVersionSync(ref.version),
+    integrity: Option.getOrElse(ref.integrity, () => ""),
+    sourceName: ref.source.name,
+    publisherBindingId: ref.publisherBindingId,
+    treeIntegrity,
+});
+const gitLockEntry = (ref, contentIdentity, treeIntegrity) => ({
+    ...gitSourceLockFields(ref.source, "knowledge", ref.knowledge.name, Option.fromUndefinedOr(ref.sourcePath), ref.gitCommitSha, ref.gitTreeSha, contentIdentity, ref.owner, ref.name, treeIntegrity),
+});
+const localLockEntry = (ref, relativePath, contentIdentity, treeIntegrity) => ({
+    type: "local",
+    sourceType: "local",
+    sourceName: "local",
+    extensionType: "knowledge",
+    workspaceName: ref.knowledge.name,
+    packageFormat: "agentxm",
+    packageOwner: ref.owner,
+    packageName: ref.name,
+    path: Option.getOrElse(relativePath, () => ref.source.path),
+    contentIdentity,
+    treeIntegrity,
+});
+/**
+ * Name the failure that stopped a restore in the operator's sentence: the
+ * producing family carries its own detail, so no application envelope is
+ * needed to describe it.
+ */
+const describeKnowledgeFailure = (failure) => "detail" in failure && typeof failure.detail === "string" ? failure.detail : failure._tag;
+export const KnowledgeManagerLive = Layer.effect(KnowledgeManager, Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const sources = yield* SourceHostProviders;
+    const catalog = yield* WorkspaceCatalog;
+    const baseDir = ws.baseDir;
+    // The workspace facade and the source integration are this layer's own
+    // dependencies; the platform stays in `R` for every member.
+    const provide = (effect) => effect.pipe(Effect.provideService(WorkspaceMutations, ws), Effect.provideService(SourceHostProviders, sources), Effect.provideService(WorkspaceCatalog, catalog));
+    const acquiredFacts = (prepared, relativeLocalSource) => ({
+        observation: NO_MATERIALIZATION_OBSERVATION,
+        acquired: Option.some({
+            relativeLocalSource,
+            sourceHash: prepared.sourceHash,
+            ...(prepared.treeIntegrity === undefined ? {} : { treeIntegrity: prepared.treeIntegrity }),
+        }),
+    });
+    const withdrawn = {
+        observation: NO_MATERIALIZATION_OBSERVATION,
+        acquired: Option.none(),
+    };
+    const canonicalPathForRef = (ref) => computeExtensionPathsForLayout(path.join, ws.layout, ref, KNOWLEDGE_EXTENSION_DIR, ref.name)
+        .canonicalPath;
+    const materializePackage = (ref, options) => {
+        const canonicalPath = options?.destinationPath ?? canonicalPathForRef(ref);
+        const materializationBaseDir = options?.baseDir ?? baseDir;
+        switch (ref.refType) {
+            case "registry":
+                return Effect.gen(function* () {
+                    return yield* provide(materializeRegistryPackage({
+                        baseDir: materializationBaseDir,
+                        destinationPath: canonicalPath,
+                        sourceLocation: ref.source.location,
+                        owner: ref.owner,
+                        type: "knowledge",
+                        name: ref.name,
+                        version: ref.version,
+                        integrity: ref.integrity,
+                        messages: {
+                            integrityMismatchDetail: `Integrity mismatch for knowledge:${ref.name}@${ref.version}`,
+                        },
+                    }));
+                });
+            case "git-hosted":
+            case "local":
+                return provide(materializeExternalPackage({
+                    baseDir: materializationBaseDir,
+                    canonicalPath,
+                    sourceLocation: ref.location,
+                    copyFailureCode: "validation",
+                    copyFailureDetail: (target) => `Failed to copy knowledge package to ${target}`,
+                }));
+            case "workspace":
+                if (ref.scope !== ws.scope ||
+                    path.resolve(ref.location) !== path.resolve(canonicalPath)) {
+                    return Effect.fail(new KnowledgeDefinitionInvalid({
+                        detail: `Invalid workspace knowledge source location: ${ref.location}`,
+                    }));
+                }
+                return Effect.succeed(ref.location);
+        }
+    };
+    const inspectPackage = (packageRoot) => Effect.gen(function* () {
+        const raw = yield* fs
+            .readFileString(path.join(packageRoot, KNOWLEDGE_MANIFEST_FILENAME))
+            .pipe(Effect.mapError((cause) => new KnowledgeDefinitionInvalid({
+            detail: `Failed to read ${KNOWLEDGE_MANIFEST_FILENAME}`,
+            cause,
+        })));
+        const manifest = yield* Effect.try({
+            try: () => JSON.parse(raw),
+            catch: (cause) => new KnowledgeDefinitionInvalid({
+                detail: `Failed to parse ${KNOWLEDGE_MANIFEST_FILENAME}`,
+                cause,
+            }),
+        }).pipe(Effect.flatMap(decodeManifest), Effect.mapError((cause) => new KnowledgeDefinitionInvalid({
+            detail: `Invalid ${KNOWLEDGE_MANIFEST_FILENAME}`,
+            cause,
+        })));
+        const inspection = yield* provide(inspectKnowledgeBundle(path.join(packageRoot, KNOWLEDGE_SOURCE_DIR))).pipe(Effect.mapError((cause) => new KnowledgeDefinitionInvalid({
+            detail: "Failed to inspect Open Knowledge Format bundle",
+            cause,
+        })));
+        const errors = inspection.diagnostics.filter((item) => item.severity === "error");
+        if (errors.length > 0) {
+            return yield* new KnowledgeDefinitionInvalid({
+                detail: errors
+                    .map((item) => item.details?.kind === "frontmatter-parse"
+                    ? `${item.relativePath}: ${item.message}`
+                    : item.message)
+                    .join(" "),
+            });
+        }
+        return { manifest, inspection };
+    });
+    const preparePackage = (ref, force = false) => Effect.gen(function* () {
+        const canonicalPath = canonicalPathForRef(ref);
+        if (ref.refType === "workspace") {
+            const root = yield* materializePackage(ref);
+            yield* inspectPackage(root);
+            return {
+                root,
+                sourceHash: ref.sourceHash,
+                commit: Effect.void,
+                rollback: Effect.void,
+            };
+        }
+        // Decide against the canonical tree before staging: the staged path
+        // never exists, so a decision made there would re-extract every time
+        // and revert workspace-owned content on a no-op install.
+        if (ref.refType === "registry") {
+            const lockedEntry = yield* ws.getLockedKnowledgeEntry(ref.knowledge.name);
+            const lockedVersion = acceptedRegistryVersionForRef(lockedEntry, ref);
+            const reuse = yield* provide(canReuseInstalledPackage({
+                installedPath: canonicalPath,
+                force,
+                refVersion: ref.version,
+                hasIntegrity: Option.isSome(ref.integrity),
+                ...(lockedVersion === undefined ? {} : { lockedVersion }),
+                existsFailureDetail: (target) => `Failed to inspect knowledge path: ${target}`,
+            }));
+            if (reuse && Option.isSome(lockedEntry)) {
+                const observedTree = yield* provide(computeMaterializedTreeIntegrity(canonicalPath));
+                if (observedTree !== lockedEntry.value.treeIntegrity) {
+                    yield* Effect.logWarning(`Knowledge package ${ref.knowledge.name} differs from its accepted tree; rematerializing`);
+                }
+                else {
+                    return {
+                        root: canonicalPath,
+                        sourceHash: yield* provide(computePackageContentHash(canonicalPath)),
+                        treeIntegrity: lockedEntry.value.treeIntegrity,
+                        commit: Effect.void,
+                        rollback: Effect.void,
+                    };
+                }
+            }
+        }
+        const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "axm-knowledge-package-" });
+        const stagedPath = path.join(tempDir, "staged");
+        const backupPath = path.join(tempDir, "previous");
+        const stageState = yield* Ref.make({ phase: "preparing" });
+        const restoreStagedPackage = Ref.get(stageState).pipe(Effect.flatMap((state) => {
+            if (state.phase !== "staged")
+                return Effect.void;
+            return fs.remove(canonicalPath, { recursive: true, force: true }).pipe(Effect.mapError((cause) => new KnowledgeIoFailed({
+                detail: `Failed to remove staged Knowledge package during rollback: ${canonicalPath}`,
+                cause,
+            })), Effect.andThen(state.hadCanonical
+                ? fs.rename(backupPath, canonicalPath).pipe(Effect.mapError((cause) => new KnowledgeIoFailed({
+                    detail: `Failed to restore Knowledge package during rollback: ${canonicalPath}`,
+                    cause,
+                })))
+                : Effect.void), Effect.andThen(Ref.set(stageState, { phase: "settled" })));
+        }));
+        yield* Effect.addFinalizer(() => restoreStagedPackage.pipe(Effect.catchCause((cause) => Effect.logError("Failed to restore staged Knowledge package during finalization", cause))));
+        const stagedRoot = yield* materializePackage(ref, {
+            baseDir: tempDir,
+            destinationPath: stagedPath,
+        });
+        yield* inspectPackage(stagedRoot);
+        const sourceHash = yield* provide(computePackageContentHash(stagedRoot));
+        const treeIntegrity = yield* provide(computeMaterializedTreeIntegrity(stagedRoot));
+        yield* protectWorkspacePath(canonicalPath);
+        const hadCanonical = yield* fs.exists(canonicalPath);
+        yield* Effect.uninterruptible(Effect.gen(function* () {
+            if (hadCanonical)
+                yield* fs.rename(canonicalPath, backupPath);
+            yield* fs.makeDirectory(path.dirname(canonicalPath), { recursive: true });
+            yield* fs.rename(stagedPath, canonicalPath).pipe(Effect.tapError(() => hadCanonical
+                ? fs.rename(backupPath, canonicalPath).pipe(Effect.mapError((cause) => new KnowledgeIoFailed({
+                    detail: `Failed to restore Knowledge package after staging failed: ${canonicalPath}`,
+                    cause,
+                })))
+                : Effect.void));
+            yield* Ref.set(stageState, { phase: "staged", hadCanonical });
+        }));
+        yield* recordFootprint({
+            path: canonicalPath,
+            change: hadCanonical ? "modified" : "created",
+        });
+        return {
+            root: canonicalPath,
+            sourceHash,
+            treeIntegrity,
+            commit: Ref.set(stageState, { phase: "settled" }),
+            rollback: restoreStagedPackage,
+        };
+    }).pipe(Effect.mapError((cause) => cause instanceof PlatformError
+        ? new KnowledgeIoFailed({
+            detail: `Failed to stage Knowledge bundle ${ref.knowledge.name}`,
+            cause,
+        })
+        : cause));
+    const getInstructionsTarget = () => Effect.gen(function* () {
+        const config = yield* ws.getInstructionsConfig();
+        const enabled = Option.isSome(config) && config.value !== false;
+        const resolved = resolveInstructionsConfig(enabled ? config.value : undefined);
+        const relative = makeWorkspaceRelativePath(path, baseDir, resolved.fileName);
+        if (Option.isNone(relative)) {
+            return yield* new KnowledgeDefinitionInvalid({
+                detail: `Knowledge discovery instruction target escapes workspace: ${resolved.fileName}`,
+            });
+        }
+        return {
+            path: path.resolve(baseDir, relative.value),
+            enabled,
+            preserveSource: enabled,
+        };
+    });
+    const canonicalRoot = (_name, locked) => computeExtensionPathsForLayout(path.join, ws.layout, extensionPathSourceFromLockEntry(locked), KNOWLEDGE_EXTENSION_DIR, locked.workspaceName).canonicalPath;
+    const desiredCanonicalRoot = (node, locked) => {
+        if (node.identity.startsWith("workspace:")) {
+            return ws.layout.scope === "project"
+                ? Effect.succeed(path.join(ws.layout.authoredRoot("knowledge"), node.name))
+                : Effect.fail(new KnowledgeDefinitionInvalid({
+                    detail: "User workspaces do not support workspace-authored Knowledge bundles",
+                }));
+        }
+        return locked === undefined
+            ? Effect.fail(new KnowledgeResolutionMissing({ name: node.name }))
+            : Effect.succeed(canonicalRoot(node.name, locked));
+    };
+    const toProjectionBundle = (root, inspected) => ({
+        owner: inspected.manifest.owner,
+        name: inspected.manifest.name,
+        sourceDir: path.join(root, KNOWLEDGE_SOURCE_DIR),
+        ...(inspected.manifest.description === undefined
+            ? {}
+            : { description: inspected.manifest.description }),
+    });
+    const activeKnowledgeNodes = () => ws
+        .getDesiredStateGraph()
+        .pipe(Effect.flatMap((graph) => graph.complete
+        ? Effect.succeed(graph.nodes
+            .filter(isSourcedDesiredExtension)
+            .filter((node) => node.type === "knowledge" && node.enabled))
+        : new KnowledgeDesiredStateUnreconcilable()));
+    /**
+     * Classify a bundle whose package could not be inspected. Only the
+     * bundle's own content is in question here: resolution facts have already
+     * succeeded, so the two truthful answers are that the package is gone or
+     * that its content is invalid.
+     */
+    const excludedContributor = (name, root, failure) => Effect.gen(function* () {
+        const probe = yield* Effect.result(fs.exists(path.join(root, KNOWLEDGE_MANIFEST_FILENAME)));
+        const manifestPresent = Result.isSuccess(probe) && probe.success;
+        if (!manifestPresent)
+            return { contributor: name, reason: "package-missing" };
+        return {
+            contributor: name,
+            reason: "package-invalid",
+            detail: failure._tag === "KnowledgeDefinitionInvalid"
+                ? failure.detail
+                : describeKnowledgeFailure(failure),
+        };
+    });
+    /**
+     * Resolve the contributor set for the discovery region. A bundle that
+     * fails inspection cannot supply a row, so it is excluded and reported
+     * rather than failing every other bundle's command with it. Resolution
+     * failures — a missing lock entry, an unsupported workspace-authored
+     * bundle — remain fail-closed: they are AXM state problems, not bundle
+     * content problems.
+     */
+    const selectKnowledgeBundles = (graph, locked, configured, config, instructionFilesEnabled) => Effect.forEach(graph.nodes.filter((node) => node.type === "knowledge" && node.enabled), (node) => Effect.gen(function* () {
+        const root = yield* desiredCanonicalRoot(node, locked[node.name]);
+        const workspaceInstructionEntry = configured[node.name]?.instructionEntry;
+        const resolveInclusion = (manifestInstructionEntry) => resolveKnowledgeInstructionEntry({
+            bundleEnabled: node.enabled,
+            instructionFilesEnabled,
+            knowledgeInstructionsEnabled: config.instructions,
+            ...(workspaceInstructionEntry === undefined ? {} : { workspaceInstructionEntry }),
+            ...(manifestInstructionEntry === undefined ? {} : { manifestInstructionEntry }),
+        });
+        const inspection = yield* Effect.result(inspectPackage(root));
+        if (Result.isFailure(inspection)) {
+            // A bundle the workspace would not publish anyway is simply
+            // absent from the region; reporting it would be noise.
+            return resolveInclusion().included
+                ? {
+                    contributors: [],
+                    exclusions: [yield* excludedContributor(node.name, root, inspection.failure)],
+                }
+                : { contributors: [], exclusions: [] };
+        }
+        const inspected = inspection.success;
+        const resolution = resolveInclusion(inspected.manifest.instructionEntry);
+        return {
+            contributors: resolution.included ? [toProjectionBundle(root, inspected)] : [],
+            exclusions: [],
+        };
+    })).pipe(Effect.map((selections) => ({
+        contributors: selections.flatMap(({ contributors }) => contributors),
+        exclusions: selections.flatMap(({ exclusions }) => exclusions),
+    })));
+    const resolveKnowledgeProjection = () => Effect.gen(function* () {
+        const graph = yield* ws.getDesiredStateGraph();
+        const locked = yield* getKnowledgeLockEntries(ws);
+        const configured = yield* ws.getConfiguredKnowledgeEntries();
+        const config = yield* ws.getKnowledgeDiscoveryConfig();
+        const instructionsTarget = yield* getInstructionsTarget();
+        return { graph, locked, configured, config, instructionsTarget };
+    });
+    const runKnowledgeProjectionAdapter = (args) => provide(reconcileKnowledgeDiscovery({
+        scopeRoot: baseDir,
+        config: args.config,
+        bundles: args.bundles,
+        instructionsPath: args.instructionsTarget.path,
+        instructionManagementEnabled: args.instructionsTarget.enabled,
+        preserveInstructionsSource: args.instructionsTarget.preserveSource,
+        ...(args.dryRun === undefined ? {} : { dryRun: args.dryRun }),
+    }));
+    const makeKnowledgeProjectionPlan = () => Effect.gen(function* () {
+        const { graph, locked, configured, config, instructionsTarget } = yield* resolveKnowledgeProjection();
+        return yield* planAggregateProjection({
+            unitId: "knowledge:discovery-region",
+            targetFile: instructionsTarget.path,
+            graph,
+            select: (completeGraph) => selectKnowledgeBundles(completeGraph, locked, configured, config, instructionsTarget.enabled),
+            adapter: {
+                observe: (input) => runKnowledgeProjectionAdapter({
+                    bundles: input.contributors,
+                    config,
+                    instructionsTarget,
+                    dryRun: true,
+                }).pipe(Effect.map((result) => ({
+                    unitId: "knowledge:discovery-region",
+                    path: `${instructionsTarget.path}#knowledge`,
+                    owner: KNOWLEDGE_REGION_OWNER,
+                    present: Option.isSome(result.observedRegion),
+                    current: !result.changed,
+                    expectedContributors: input.contributors.map(({ owner, name }) => `${owner}/knowledge/${name}`),
+                }))),
+                apply: (input) => runKnowledgeProjectionAdapter({
+                    bundles: input.contributors,
+                    config,
+                    instructionsTarget,
+                }).pipe(Effect.asVoid),
+            },
+        });
+    });
+    const projectionPlans = () => makeKnowledgeProjectionPlan().pipe(Effect.map((plan) => [plan]));
+    const applyKnowledgeProjection = projectionPlans().pipe(Effect.flatMap(applyProjectionPlans));
+    const reconcileDiscovery = (options) => resolveKnowledgeProjection().pipe(Effect.flatMap(({ graph, locked, configured, config, instructionsTarget }) => requireCompleteGraph(graph).pipe(Effect.flatMap((completeGraph) => selectKnowledgeBundles(completeGraph, locked, configured, config, instructionsTarget.enabled)), Effect.flatMap(({ contributors, exclusions }) => runKnowledgeProjectionAdapter({
+        bundles: contributors,
+        config,
+        instructionsTarget,
+        ...(options?.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+    }).pipe(Effect.map((result) => ({
+        ...result,
+        warnings: formatProjectionExclusions({
+            exclusions,
+            targetFile: instructionsTarget.path,
+        }),
+    })))))));
+    const buildLockEntry = (ref, materialization) => Effect.gen(function* () {
+        const state = Option.getOrUndefined(materialization.pipe(Option.flatMap((facts) => facts.acquired)));
+        switch (ref.refType) {
+            case "registry":
+                return state?.treeIntegrity === undefined
+                    ? yield* new KnowledgeInstallStateMissing({
+                        name: ref.knowledge.name,
+                        kind: "tree-integrity",
+                    })
+                    : Option.some(registryLockEntry(ref, state.treeIntegrity));
+            case "git-hosted":
+                return state?.treeIntegrity === undefined
+                    ? yield* new KnowledgeInstallStateMissing({
+                        name: ref.knowledge.name,
+                        kind: "content-identity",
+                    })
+                    : Option.some(gitLockEntry(ref, state.sourceHash, state.treeIntegrity));
+            case "local":
+                return state?.treeIntegrity === undefined
+                    ? yield* new KnowledgeInstallStateMissing({
+                        name: ref.knowledge.name,
+                        kind: "content-identity",
+                    })
+                    : Option.some(localLockEntry(ref, state.relativeLocalSource, state.sourceHash, state.treeIntegrity));
+            case "workspace":
+                return Option.none();
+        }
+    });
+    const setKnowledgeSourceEntry = (name, source) => Effect.gen(function* () {
+        const configured = yield* ws.getConfiguredKnowledgeEntries();
+        const current = configured[name];
+        yield* ws.setKnowledgeEntry(name, {
+            source,
+            enabled: true,
+            ...(current?.instructionEntry === undefined
+                ? {}
+                : { instructionEntry: current.instructionEntry }),
+        });
+    });
+    const restoreLockedPackage = (name, entry) => Effect.gen(function* () {
+        const ref = yield* knowledgeLockEntryToRef(name, entry, {
+            baseDir,
+            path,
+            scope: ws.scope,
+            getConfiguredSourceByName: (sourceName) => ws.getConfiguredSourceByName(sourceName),
+        });
+        if (ref.refType === "registry" && Option.isNone(ref.integrity)) {
+            return yield* new KnowledgeUnavailable({
+                detail: `Locked registry Knowledge bundle has no integrity and cannot be restored: ${name}`,
+            });
+        }
+        if (ref.refType !== "git-hosted") {
+            return yield* preparePackage(ref);
+        }
+        const discovered = yield* sources.find(ref.source, {
+            names: [name],
+            type: "knowledge",
+            owner: Option.none(),
+            versionRange: Option.none(),
+        });
+        const candidate = discovered.find((item) => item.type === "knowledge" && item.refType === "git-hosted");
+        if (candidate === undefined ||
+            candidate.gitTreeSha !== ref.gitTreeSha ||
+            candidate.gitCommitSha !== ref.gitCommitSha) {
+            return yield* new KnowledgeUnavailable({
+                detail: `Git Knowledge source no longer resolves to locked commit/tree ${ref.gitCommitSha}/${ref.gitTreeSha}: ${name}`,
+            });
+        }
+        return yield* preparePackage(candidate);
+    });
+    const syncLocked = (dryRun) => Effect.gen(function* () {
+        const desired = yield* activeKnowledgeNodes();
+        const locked = yield* getKnowledgeLockEntries(ws);
+        const prepared = [];
+        for (const node of desired) {
+            const { name } = node;
+            const entry = locked[name];
+            const root = yield* desiredCanonicalRoot(node, entry);
+            const inspection = yield* Effect.result(inspectPackage(root));
+            if (Result.isSuccess(inspection))
+                continue;
+            if (node.identity.startsWith("workspace:")) {
+                return yield* new KnowledgeDefinitionInvalid({
+                    detail: `Active workspace-authored Knowledge bundle is missing or invalid: ${name}`,
+                    cause: inspection.failure,
+                });
+            }
+            if (entry === undefined) {
+                return yield* new KnowledgeResolutionMissing({ name });
+            }
+            const restored = yield* Effect.result(restoreLockedPackage(name, entry));
+            if (Result.isFailure(restored)) {
+                yield* Effect.forEach([...prepared].reverse(), (item) => item.rollback, {
+                    discard: true,
+                });
+                const restoreFailure = restored.failure;
+                return yield* new KnowledgeUnavailable({
+                    detail: `Active Knowledge bundle could not be restored: ${name}. ${describeKnowledgeFailure(restoreFailure)}`,
+                    cause: restoreFailure,
+                });
+            }
+            else
+                prepared.push(restored.success);
+        }
+        const discovered = yield* Effect.result(reconcileDiscovery({ dryRun: true }));
+        if (Result.isFailure(discovered)) {
+            yield* Effect.forEach([...prepared].reverse(), (item) => item.rollback, {
+                discard: true,
+            });
+            return yield* discovered.failure;
+        }
+        if (!dryRun)
+            yield* applyKnowledgeProjection;
+        yield* Effect.forEach(dryRun ? [...prepared].reverse() : prepared, (item) => (dryRun ? item.rollback : item.commit), { discard: true });
+        const discovery = discovered.success;
+        return {
+            changed: prepared.length > 0 || discovery.changed,
+            warnings: discovery.warnings,
+            artifacts: discovery.artifacts,
+        };
+    });
+    const installAtomically = (args) => runWorkspaceTransaction({
+        transition: Effect.gen(function* () {
+            const name = args.ref.knowledge.name;
+            const relativeLocalSource = args.ref.refType === "local"
+                ? makeWorkspaceRelativeSourcePath(path, baseDir, args.ref.sourcePath ?? stripFileProtocol(args.ref.location))
+                : Option.none();
+            if (args.ref.refType === "local" && Option.isNone(relativeLocalSource)) {
+                return yield* new KnowledgeDefinitionInvalid({
+                    detail: `Local knowledge source must stay within the workspace: ${args.ref.source.path}`,
+                });
+            }
+            const cleanupSupersededCanonical = yield* provide(prepareAcceptedCanonicalTransition({
+                workspace: ws,
+                type: "knowledge",
+                name,
+                ref: args.ref,
+            }));
+            const prepared = yield* preparePackage(args.ref);
+            const committed = yield* Effect.gen(function* () {
+                const facts = acquiredFacts(prepared, relativeLocalSource);
+                if (args.ref.refType !== "workspace" && prepared.treeIntegrity === undefined) {
+                    return yield* new KnowledgeInstallStateMissing({
+                        name,
+                        kind: "staged-tree-integrity",
+                    });
+                }
+                const lockEntry = yield* buildLockEntry(args.ref, Option.some(facts));
+                if (Option.isSome(lockEntry)) {
+                    yield* ws.setKnowledge({
+                        name,
+                        lockEntry: lockEntry.value,
+                        versionRange: args.versionRange,
+                    });
+                }
+                else {
+                    yield* setKnowledgeSourceEntry(name, "workspace");
+                }
+                yield* cleanupSupersededCanonical;
+                return { name };
+            });
+            if (args.deferProjection !== true)
+                yield* applyKnowledgeProjection;
+            // The workspace transaction owns a nested scope. Settle the staged
+            // package before that scope closes; a later postcondition failure
+            // still restores the transaction snapshot.
+            yield* prepared.commit;
+            return committed;
+        }),
+        validate: ({ name }) => isObservedInstalled(ws, "knowledge", name).pipe(Effect.flatMap((installed) => installed ? Effect.void : new KnowledgeObservableContractViolated({ name }))),
+    }).pipe(Effect.scoped, Effect.asVoid);
+    // Canonical removal only. The shared operation flow re-renders the
+    // discovery region after settings and lock removal, once the target has
+    // left the graph.
+    const materializeUninstall = Effect.fn("KnowledgeManager.materializeUninstall")(function* ({ target, }) {
+        const canonical = yield* provide(acceptedCanonicalObservation({
+            workspace: ws,
+            type: "knowledge",
+            name: target.name,
+        }));
+        const root = removableAcceptedCanonicalPath(canonical);
+        const locked = yield* ws.getLockedKnowledgeEntry(target.name);
+        const ownedRoot = Option.orElse(root, () => Option.map(locked, (entry) => canonicalRoot(target.name, entry)));
+        if (Option.isSome(ownedRoot)) {
+            yield* protectWorkspacePath(ownedRoot.value);
+            yield* fs.remove(ownedRoot.value, { recursive: true, force: true }).pipe(Effect.mapError((cause) => new KnowledgeIoFailed({
+                detail: `Failed to remove Knowledge package source: ${ownedRoot.value}`,
+                cause,
+            })));
+        }
+        return withdrawn;
+    });
+    // Deactivation retains canonical content; the caller updates settings
+    // first, so re-rendering the whole region drops this bundle's routing.
+    const materializeDeactivate = Effect.fn("KnowledgeManager.materializeDeactivate")(() => applyKnowledgeProjection.pipe(Effect.as(withdrawn)));
+    return {
+        type: "knowledge",
+        projectionPlans,
+        refreshCatalog: () => runWorkspaceTransaction({
+            transition: applyKnowledgeProjection,
+            validate: () => Effect.void,
+        }),
+        sync: ({ dryRun }) => dryRun
+            ? Effect.scoped(syncLocked(true))
+            : Effect.scoped(runWorkspaceTransaction({
+                transition: syncLocked(false),
+                validate: () => Effect.void,
+            })),
+        install: installAtomically,
+        isInstalled: ({ target }) => isObservedInstalled(ws, "knowledge", target.name),
+        materializeInstall: Effect.fn("KnowledgeManager.materializeInstall")(function* ({ ref, force, }) {
+            const relativeLocalSource = ref.refType === "local"
+                ? makeWorkspaceRelativeSourcePath(path, baseDir, ref.sourcePath ?? stripFileProtocol(ref.location))
+                : Option.none();
+            if (ref.refType === "local" && Option.isNone(relativeLocalSource)) {
+                return yield* new KnowledgeDefinitionInvalid({
+                    detail: `Local knowledge source must stay within the workspace: ${ref.source.path}`,
+                });
+            }
+            const prepared = yield* preparePackage(ref, force === true);
+            yield* prepared.commit;
+            return acquiredFacts(prepared, relativeLocalSource);
+        }, Effect.scoped),
+        prepareSourceTransition: ({ ref }) => provide(prepareAcceptedCanonicalTransition({
+            workspace: ws,
+            type: "knowledge",
+            name: ref.knowledge.name,
+            ref,
+        })),
+        getConfiguredSource: ({ target }) => ws
+            .getConfiguredKnowledgeEntries()
+            .pipe(Effect.map((entries) => Option.fromUndefinedOr(entries[target.name]?.source))),
+        /**
+         * Every enabled entry's accepted canonical package, read from accepted
+         * resolution rather than re-resolved from source. Materialization
+         * realizes what the workspace already accepted; going back to the
+         * source would put an unrelated configured entry's release age between
+         * an operator and the extension they are authoring.
+         */
+        listMaterializable: () => Effect.gen(function* () {
+            const nodes = yield* activeKnowledgeNodes();
+            const refs = yield* Effect.forEach(nodes, (node) => provide(usableAcceptedCanonicalRef({
+                workspace: ws,
+                type: "knowledge",
+                name: node.name,
+            }).pipe(Effect.map(Option.filter((ref) => ref.type === "knowledge")))), { concurrency: "unbounded" });
+            return refs.flatMap((ref) => (Option.isSome(ref) ? [ref.value] : []));
+        }),
+        materializeUninstall,
+        materializeDeactivate,
+        upsertSettingsEntry: ({ ref, versionRange, materialization }) => buildLockEntry(ref, materialization).pipe(Effect.flatMap((lockEntry) => Option.isSome(lockEntry)
+            ? ws.setKnowledge({
+                name: ref.knowledge.name,
+                lockEntry: lockEntry.value,
+                versionRange,
+            })
+            : setKnowledgeSourceEntry(ref.knowledge.name, "workspace"))),
+        removeSettingsEntry: ({ target }) => ws.removeKnowledgeSettings(target.name),
+        upsertLockfileEntry: ({ ref, materialization }) => buildLockEntry(ref, materialization).pipe(Effect.flatMap((lockEntry) => {
+            if (Option.isNone(lockEntry))
+                return ws.removeKnowledgeLock(ref.knowledge.name);
+            const validate = lockEntry.value.type === "registry"
+                ? validateExactResolvedVersion(`knowledge.${ref.knowledge.name}.resolvedVersion`, lockEntry.value.resolvedVersion)
+                : Effect.void;
+            return validate.pipe(Effect.flatMap(() => ws.setKnowledgeLock({
+                name: ref.knowledge.name,
+                lockEntry: lockEntry.value,
+                versionRange: Option.none(),
+            })));
+        })),
+        removeLockfileEntry: ({ target }) => ws.removeKnowledgeLock(target.name),
+    };
+}));
+//# sourceMappingURL=manager.js.map