@agentxm/extension-lifecycle 0.28.11 → 0.28.13

package/dist/src/knowledge/manager.js

@@ -1,711 +0,0 @@
-// @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 * as FileSystem from "effect/FileSystem";
-import * as HttpClient from "effect/unstable/http/HttpClient";
-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, applyProjectionPlans, formatProjectionExclusions, planAggregateProjection, requireCompleteGraph, KNOWLEDGE_REGION_OWNER, reconcileKnowledgeDiscovery, resolveInstructionsConfig, } from "@agentxm/extension-workspace";
-import { canReuseInstalledPackage, materializeExternalPackage } from "@agentxm/extension-workspace";
-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 { stripFileProtocol } from "../internal/fs-helpers.js";
-import { makeWorkspaceRelativeSourcePath } from "@agentxm/extension-model/unstable/path-types";
-import { recordFootprint } from "@agentxm/workspace-state";
-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 { KnowledgeManager, } from "@agentxm/extension-workspace";
-import { WorkspaceMutations } from "@agentxm/workspace-state";
-import { isObservedInstalled } from "@agentxm/workspace-state";
-import { acceptedCanonicalObservation, prepareAcceptedCanonicalTransition, removableAcceptedCanonicalPath, } from "@agentxm/workspace-state";
-import { protectWorkspacePath } from "@agentxm/workspace-state";
-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/registry-protocol/unstable/knowledge/okf";
-import { resolveKnowledgeInstructionEntry } from "@agentxm/extension-workspace";
-import { coupleLifecycleDependencyFailure } from "../errors.js";
-import { LifecycleFailureAdapter } from "../failure-adapter.js";
-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,
-});
-export const KnowledgeManagerLive = Layer.effect(KnowledgeManager, Effect.gen(function* () {
-    const ws = yield* WorkspaceMutations;
-    const fs = yield* FileSystem.FileSystem;
-    const httpClient = yield* HttpClient.HttpClient;
-    const path = yield* Path.Path;
-    const sources = yield* SourceHostProviders;
-    const catalog = yield* WorkspaceCatalog;
-    const adapter = yield* LifecycleFailureAdapter;
-    const baseDir = ws.baseDir;
-    const env = Layer.mergeAll(Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(HttpClient.HttpClient, httpClient), Layer.succeed(Path.Path, path), Layer.succeed(WorkspaceMutations, ws), Layer.succeed(SourceHostProviders, sources), Layer.succeed(WorkspaceCatalog, catalog), Layer.succeed(LifecycleFailureAdapter, adapter));
-    const provide = (effect) => Effect.provide(effect, env);
-    const lastInstallState = new Map();
-    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
-                : adapter.describeFailure(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) => Effect.gen(function* () {
-        const state = lastInstallState.get(ref.knowledge.name);
-        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(),
-        })
-            .pipe(Effect.mapError(coupleLifecycleDependencyFailure));
-        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}. ${adapter.describeFailure(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) => ws
-        .runTransaction({
-        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* () {
-                lastInstallState.set(name, {
-                    relativeLocalSource,
-                    sourceHash: prepared.sourceHash,
-                    ...(prepared.treeIntegrity === undefined
-                        ? {}
-                        : { treeIntegrity: prepared.treeIntegrity }),
-                });
-                if (args.ref.refType !== "workspace" && prepared.treeIntegrity === undefined) {
-                    return yield* new KnowledgeInstallStateMissing({
-                        name,
-                        kind: "staged-tree-integrity",
-                    });
-                }
-                const lockEntry = yield* buildLockEntry(args.ref);
-                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.tapError(() => Effect.sync(() => {
-        lastInstallState.delete(args.ref.knowledge.name);
-    })), 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,
-            })));
-        }
-    }, Effect.asVoid);
-    // 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);
-    return {
-        type: "knowledge",
-        projectionPlans,
-        runTransaction: ws.runTransaction,
-        refreshCatalog: () => ws.runTransaction({
-            transition: applyKnowledgeProjection,
-            validate: () => Effect.void,
-        }),
-        sync: ({ dryRun }) => dryRun
-            ? Effect.scoped(syncLocked(true))
-            : Effect.scoped(ws.runTransaction({
-                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;
-            lastInstallState.set(ref.knowledge.name, {
-                relativeLocalSource,
-                sourceHash: prepared.sourceHash,
-                ...(prepared.treeIntegrity === undefined
-                    ? {}
-                    : { treeIntegrity: prepared.treeIntegrity }),
-            });
-        }, Effect.asVoid, 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 }) => buildLockEntry(ref).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 }) => buildLockEntry(ref).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