@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/accepted-canonical-ref.js

@@ -0,0 +1,229 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { decodeExtensionNameSync } from "@agentxm/extension-model/unstable/extensions/common";
+import { decodeHandleSync } from "@agentxm/extension-model/unstable/extensions/handle";
+import { AcceptedResolutionMissing, InlineExtensionSourceMissing, SupersededCanonicalRemovalFailed, } from "./errors.js";
+import { hookLockEntryToRef, knowledgeLockEntryToRef, mcpServerLockEntryToRef, packLockEntryToRef, ruleLockEntryToRef, skillLockEntryToRef, subagentLockEntryToRef, } from "./lock-entry-to-ref.js";
+import { observeCanonicalExtension, } from "./canonical-observation.js";
+import { computeExtensionPathsForLayout, extensionPathSourceFromLockEntry, } from "./extension-paths.js";
+import { toExtensionTypePlural } from "@agentxm/extension-model/unstable/extensions/common";
+import { protectWorkspacePath } from "./transaction.js";
+import { resolveWorkspaceExtensionRef } from "./configured-entry-resolution/workspace-ref.js";
+/** Canonical package AXM may delete when removing desired state. Authored source is durable. */
+export const removableAcceptedCanonicalPath = (canonical) => Option.flatMap(canonical, (state) => state.desired.identity.startsWith("workspace:")
+    ? Option.none()
+    : Option.fromUndefinedOr(state.observation.path));
+const getAcceptedResolution = (workspace, type, name) => {
+    const read = () => {
+        switch (type) {
+            case "skill":
+                return workspace.getLockedSkill(name);
+            case "mcp-server":
+                return workspace.getLockedMcpServer(name);
+            case "subagent":
+                return workspace.getLockedSubagent(name);
+            case "rule":
+                return workspace.getLockedRuleEntry(name);
+            case "hook":
+                return workspace.getLockedHookEntry(name);
+            case "knowledge":
+                return workspace.getLockedKnowledgeEntry(name);
+            case "pack":
+                return workspace.getLockedPack(name);
+        }
+    };
+    return read();
+};
+/** Exact acquired canonical path reconstructed directly from accepted lock authority. */
+export const acceptedLockedCanonicalPath = (args) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const accepted = yield* getAcceptedResolution(args.workspace, args.type, args.name);
+    return Option.map(accepted, (entry) => computeExtensionPathsForLayout(path.join, args.workspace.layout, extensionPathSourceFromLockEntry(entry), toExtensionTypePlural(args.type), entry.workspaceName).canonicalPath);
+});
+const workspaceNameFromRef = (ref) => {
+    switch (ref.type) {
+        case "skill":
+            return ref.skill.name;
+        case "mcp-server":
+            return ref.server.name;
+        case "subagent":
+            return ref.subagent.name;
+        case "rule":
+            return ref.rule.name;
+        case "hook":
+            return ref.hook.name;
+        case "knowledge":
+            return ref.knowledge.name;
+        case "pack":
+            return ref.pack.name;
+    }
+};
+/**
+ * Capture exact cleanup for a superseded accepted package. The old path is
+ * read before the lock transition; the returned effect runs afterward and
+ * removes only that path when the replacement canonical path differs.
+ */
+export const prepareAcceptedCanonicalTransition = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const previous = yield* acceptedLockedCanonicalPath(args);
+    if (Option.isNone(previous))
+        return yield* Effect.succeed(Effect.void);
+    const next = computeExtensionPathsForLayout(path.join, args.workspace.layout, args.ref, toExtensionTypePlural(args.ref.type), workspaceNameFromRef(args.ref)).canonicalPath;
+    if (path.resolve(previous.value) === path.resolve(next)) {
+        return yield* Effect.succeed(Effect.void);
+    }
+    return yield* Effect.succeed(Effect.gen(function* () {
+        yield* protectWorkspacePath(previous.value);
+        yield* fs
+            .remove(previous.value, { recursive: true, force: true })
+            .pipe(Effect.mapError((cause) => new SupersededCanonicalRemovalFailed({ path: previous.value, cause })));
+    }));
+});
+const lockRefDeps = (workspace, path) => ({
+    baseDir: workspace.baseDir,
+    path,
+    scope: workspace.scope,
+    getConfiguredSourceByName: (name) => workspace.getConfiguredSourceByName(name),
+});
+const missingAccepted = (label, name) => new AcceptedResolutionMissing({ label, name });
+const refFromAcceptedResolution = (workspace, type, name) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const deps = lockRefDeps(workspace, path);
+    switch (type) {
+        case "skill": {
+            const entry = yield* workspace.getLockedSkill(name);
+            return yield* Option.match(entry, {
+                onNone: () => Effect.fail(missingAccepted("Skill", name)),
+                onSome: (value) => skillLockEntryToRef(name, value, deps),
+            });
+        }
+        case "mcp-server": {
+            const entry = yield* workspace.getLockedMcpServer(name);
+            return yield* Option.match(entry, {
+                onNone: () => Effect.fail(missingAccepted("MCP", name)),
+                onSome: (value) => mcpServerLockEntryToRef(name, value, deps),
+            });
+        }
+        case "subagent": {
+            const entry = yield* workspace.getLockedSubagent(name);
+            return yield* Option.match(entry, {
+                onNone: () => Effect.fail(missingAccepted("Subagent", name)),
+                onSome: (value) => subagentLockEntryToRef(name, value, deps),
+            });
+        }
+        case "rule": {
+            const entry = yield* workspace.getLockedRuleEntry(name);
+            return yield* Option.match(entry, {
+                onNone: () => Effect.fail(missingAccepted("Rule", name)),
+                onSome: (value) => ruleLockEntryToRef(name, value, deps),
+            });
+        }
+        case "hook": {
+            const entry = yield* workspace.getLockedHookEntry(name);
+            return yield* Option.match(entry, {
+                onNone: () => Effect.fail(missingAccepted("Hook", name)),
+                onSome: (value) => hookLockEntryToRef(name, value, deps),
+            });
+        }
+        case "knowledge": {
+            const entry = yield* workspace.getLockedKnowledgeEntry(name);
+            return yield* Option.match(entry, {
+                onNone: () => Effect.fail(missingAccepted("Knowledge", name)),
+                onSome: (value) => knowledgeLockEntryToRef(name, value, deps),
+            });
+        }
+        case "pack": {
+            const entry = yield* workspace.getLockedPack(name);
+            return yield* Option.match(entry, {
+                onNone: () => Effect.fail(missingAccepted("Pack", name)),
+                onSome: (value) => packLockEntryToRef(name, value, deps),
+            });
+        }
+    }
+});
+/** Reconstruct a ref directly from accepted lock authority without desired reachability. */
+export const acceptedLockedResolutionRef = (args) => Effect.gen(function* () {
+    const accepted = yield* getAcceptedResolution(args.workspace, args.type, args.name);
+    if (Option.isNone(accepted))
+        return Option.none();
+    return Option.some(yield* refFromAcceptedResolution(args.workspace, args.type, args.name));
+});
+const refForDesired = (workspace, desired) => Effect.gen(function* () {
+    if (desired.source === undefined) {
+        return yield* new InlineExtensionSourceMissing({ name: desired.name });
+    }
+    if (desired.identity.startsWith("bundled:")) {
+        const path = yield* Path.Path;
+        return yield* resolveWorkspaceExtensionRef({
+            settingsName: desired.name,
+            source: "workspace",
+            expectedType: desired.type,
+            layout: workspace.layout,
+            scope: workspace.scope,
+            staticPackage: {
+                owner: decodeHandleSync("@agentxm"),
+                name: decodeExtensionNameSync(desired.name),
+                root: workspace.layout.scope === "project"
+                    ? path.join(workspace.layout.acquiredRoot, "agentxm", "@agentxm", "skills", desired.name)
+                    : path.join(workspace.layout.acquiredRoot, "agentxm", "@agentxm", "skills", desired.name),
+            },
+        });
+    }
+    if (desired.identity.startsWith("workspace:")) {
+        return yield* resolveWorkspaceExtensionRef({
+            settingsName: desired.name,
+            source: desired.source,
+            expectedType: desired.type,
+            layout: workspace.layout,
+            scope: workspace.scope,
+        });
+    }
+    return yield* refFromAcceptedResolution(workspace, desired.type, desired.name);
+});
+/**
+ * Reconstruct the immutable source reference recorded for a desired extension,
+ * even when its canonical materialization is absent or divergent.
+ */
+export const acceptedResolutionRef = (args) => Effect.gen(function* () {
+    const graph = yield* args.workspace.getDesiredStateGraph();
+    const desired = graph.nodes.find((node) => node.type === args.type && node.name === args.name);
+    if (desired === undefined || desired.identity.startsWith("workspace:")) {
+        return Option.none();
+    }
+    return yield* acceptedLockedResolutionRef(args);
+});
+export const acceptedCanonicalObservation = ({ workspace, type, name, }) => Effect.gen(function* () {
+    const graph = yield* workspace.getDesiredStateGraph();
+    const desired = graph.nodes.find((node) => node.type === type && node.name === name);
+    if (desired === undefined)
+        return Option.none();
+    const accepted = yield* getAcceptedResolution(workspace, type, name);
+    const observation = yield* observeCanonicalExtension({
+        layout: workspace.layout,
+        desired,
+        accepted: Option.getOrUndefined(accepted),
+    });
+    return Option.some({
+        desired,
+        ...(Option.isSome(accepted) ? { accepted: accepted.value } : {}),
+        observation,
+    });
+});
+export const usableAcceptedCanonicalObservation = (args) => acceptedCanonicalObservation(args).pipe(Effect.map(Option.flatMap((value) => value.observation.status === "usable" && value.observation.path !== undefined
+    ? Option.some({
+        ...value,
+        observation: { ...value.observation, status: "usable", path: value.observation.path },
+    })
+    : Option.none())));
+export const usableAcceptedCanonical = (args) => Effect.gen(function* () {
+    const canonical = yield* usableAcceptedCanonicalObservation(args);
+    if (Option.isNone(canonical))
+        return Option.none();
+    const ref = yield* refForDesired(args.workspace, canonical.value.desired);
+    return Option.some({ ...canonical.value, ref });
+});
+export const usableAcceptedCanonicalRef = (args) => usableAcceptedCanonical(args).pipe(Effect.map(Option.map((canonical) => canonical.ref)));
+//# sourceMappingURL=accepted-canonical-ref.js.map

package/dist/src/workspace/artifact-change.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Change classification for a workspace-managed artifact.
+ *
+ * Names how one on-disk artifact fared during an operation. Owned by the
+ * workspace state vocabulary so plan presentation, agent projection, and
+ * read-model consumers share one definition.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Schema from "effect/Schema";
+export declare const ArtifactChangeSchema: Schema.Literals<readonly ["created", "updated", "unchanged", "removed"]>;
+export type ArtifactChange = typeof ArtifactChangeSchema.Type;
+//# sourceMappingURL=artifact-change.d.ts.map

package/dist/src/workspace/artifact-change.js

@@ -0,0 +1,18 @@
+/**
+ * Change classification for a workspace-managed artifact.
+ *
+ * Names how one on-disk artifact fared during an operation. Owned by the
+ * workspace state vocabulary so plan presentation, agent projection, and
+ * read-model consumers share one definition.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Schema from "effect/Schema";
+export const ArtifactChangeSchema = Schema.Literals([
+    "created",
+    "updated",
+    "unchanged",
+    "removed",
+]);
+//# sourceMappingURL=artifact-change.js.map

package/dist/src/workspace/canonical-observation.d.ts

@@ -0,0 +1,39 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { type ExtensionType } from "@agentxm/extension-model/unstable/extensions";
+import type { HookLockEntry, KnowledgeLockEntry, McpServerLockEntry, PackLockEntry, RuleLockEntry, SkillLockEntry, SubagentLockEntry } from "../lockfile/index.js";
+import { type DesiredConstraintContributor, type DesiredExtensionNode } from "./desired-state-graph.js";
+import type { WorkspaceLayout } from "./layout.js";
+export type CanonicalObservationStatus = "not-applicable" | "missing" | "missing-resolution" | "constraint-mismatch" | "wrong-origin" | "corrupt" | "incomplete" | "locally-modified" | "materialization-mismatch" | "usable";
+export type CanonicalConstraintContributor = DesiredConstraintContributor;
+interface CanonicalObservationBase {
+    readonly type: ExtensionType;
+    readonly name: string;
+    readonly path?: string;
+    readonly contentIdentity?: string;
+}
+export interface CanonicalConstraintMismatchObservation extends CanonicalObservationBase {
+    readonly status: "constraint-mismatch";
+    readonly authority: {
+        readonly source: "desired-state-graph";
+        readonly identity: string;
+        readonly locator: string;
+        readonly constraints: ReadonlyArray<CanonicalConstraintContributor>;
+    };
+    readonly acceptedVersion?: string;
+    readonly observedVersion?: string;
+}
+export type CanonicalObservation = CanonicalConstraintMismatchObservation | (CanonicalObservationBase & {
+    readonly status: Exclude<CanonicalObservationStatus, "constraint-mismatch">;
+});
+interface ObserveCanonicalArgs {
+    readonly layout: WorkspaceLayout;
+    readonly desired: DesiredExtensionNode;
+    readonly accepted: AcceptedExtensionResolution | undefined;
+}
+export type AcceptedExtensionResolution = SkillLockEntry | McpServerLockEntry | SubagentLockEntry | RuleLockEntry | HookLockEntry | KnowledgeLockEntry | PackLockEntry;
+export declare const canonicalPathForAcceptedExtension: (path: Path.Path, layout: WorkspaceLayout, desired: DesiredExtensionNode, accepted: AcceptedExtensionResolution | undefined) => string | undefined;
+export declare const observeCanonicalExtension: ({ layout, desired, accepted, }: ObserveCanonicalArgs) => Effect.Effect<CanonicalObservation, never, FileSystem.FileSystem | Path.Path>;
+export {};
+//# sourceMappingURL=canonical-observation.d.ts.map

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

@@ -0,0 +1,307 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as semver from "semver";
+import { computeMaterializedTreeIntegrity } from "./materialized-tree.js";
+import { toExtensionTypePlural, } from "@agentxm/extension-model/unstable/extensions";
+import { HookManifestSchema } from "@agentxm/extension-model/unstable/hooks/manifest-schema";
+import { KnowledgeManifestSchema } from "@agentxm/extension-model/unstable/knowledge";
+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 { 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";
+import { lockEntryToSourceParams } from "./lock-entry-to-source-params.js";
+import { collectDesiredConstraintContributors, } from "./desired-state-graph.js";
+import { computeExtensionPathsForLayout, extensionPathSourceFromLockEntry, } from "./extension-paths.js";
+const MANIFEST_CONTRACTS = {
+    skill: { filename: "skill.json", schema: SkillManifestSchema },
+    "mcp-server": { filename: "mcp.json", schema: McpServerManifestSchema },
+    subagent: { filename: "subagent.json", schema: SubagentManifestSchema },
+    rule: { filename: "rule.json", schema: RuleManifestSchema },
+    hook: { filename: "hook.json", schema: HookManifestSchema },
+    knowledge: { filename: "knowledge.json", schema: KnowledgeManifestSchema },
+    pack: { filename: "pack.json", schema: PackManifestSchema },
+};
+export const canonicalPathForAcceptedExtension = (path, layout, desired, accepted) => {
+    if (desired.source === undefined)
+        return undefined;
+    if (desired.identity.startsWith("bundled:")) {
+        return path.join(layout.acquiredRoot, "agentxm", "@agentxm", "skills", desired.name);
+    }
+    if (desired.identity.startsWith("workspace:")) {
+        if (layout.scope === "project")
+            return path.join(layout.authoredRoot(desired.type), desired.name);
+        return undefined;
+    }
+    if (accepted === undefined)
+        return undefined;
+    const source = extensionPathSourceFromLockEntry(accepted);
+    return computeExtensionPathsForLayout(path.join, layout, source, toExtensionTypePlural(desired.type), accepted.workspaceName).canonicalPath;
+};
+const hasRequiredPayload = (fs, path, root, type, name) => {
+    switch (type) {
+        case "skill":
+            return Effect.map(Effect.all([fs.exists(path.join(root, "src", "SKILL.md"))]), (exists) => exists.some(Boolean));
+        case "subagent":
+            return fs.exists(path.join(root, "src", `${name}.md`));
+        case "rule":
+        case "hook":
+        case "knowledge":
+            return fs.exists(path.join(root, "src"));
+        case "mcp-server":
+        case "pack":
+            return Effect.succeed(true);
+    }
+};
+const parseJson = (raw) => {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+};
+const constraintMismatchObservation = (args) => ({
+    type: args.desired.type,
+    name: args.desired.name,
+    status: "constraint-mismatch",
+    ...(args.canonicalPath === undefined ? {} : { path: args.canonicalPath }),
+    authority: {
+        source: "desired-state-graph",
+        identity: args.desired.identity,
+        locator: args.desired.source,
+        constraints: collectDesiredConstraintContributors(args.path, args.desired.origins),
+    },
+    ...(args.acceptedVersion === undefined ? {} : { acceptedVersion: args.acceptedVersion }),
+    ...(args.observedVersion === undefined ? {} : { observedVersion: args.observedVersion }),
+});
+export const observeCanonicalExtension = ({ layout, desired, accepted, }) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    if (desired.source === undefined) {
+        return {
+            type: desired.type,
+            name: desired.name,
+            status: "not-applicable",
+        };
+    }
+    const workspaceAuthored = desired.identity.startsWith("workspace:");
+    const bundled = desired.identity.startsWith("bundled:");
+    if (!workspaceAuthored && !bundled && accepted === undefined) {
+        return {
+            type: desired.type,
+            name: desired.name,
+            status: "missing-resolution",
+        };
+    }
+    const acceptedIdentity = accepted?.type === "registry"
+        ? `${accepted.owner}/${toExtensionTypePlural(desired.type)}/${accepted.name}`
+        : accepted === undefined
+            ? undefined
+            : printSourceParams(lockEntryToSourceParams(accepted));
+    if (!workspaceAuthored &&
+        !bundled &&
+        acceptedIdentity !== desired.identity &&
+        acceptedIdentity !== desired.source) {
+        return {
+            type: desired.type,
+            name: desired.name,
+            status: "wrong-origin",
+        };
+    }
+    const acceptedConstraintMismatch = !workspaceAuthored &&
+        desired.constraints.length > 0 &&
+        (accepted?.type !== "registry" ||
+            desired.constraints.some((constraint) => !semver.satisfies(accepted.resolvedVersion, constraint)));
+    const acceptedVersion = accepted?.type === "registry" ? accepted.resolvedVersion : undefined;
+    const root = canonicalPathForAcceptedExtension(path, layout, desired, accepted);
+    if (root === undefined) {
+        if (acceptedConstraintMismatch) {
+            return constraintMismatchObservation({
+                path,
+                desired,
+                ...(acceptedVersion === undefined ? {} : { acceptedVersion }),
+            });
+        }
+        return {
+            type: desired.type,
+            name: desired.name,
+            status: "wrong-origin",
+        };
+    }
+    const exists = yield* fs.exists(root).pipe(Effect.orElseSucceed(() => false));
+    if (!exists) {
+        if (acceptedConstraintMismatch) {
+            return constraintMismatchObservation({
+                path,
+                desired,
+                canonicalPath: root,
+                ...(acceptedVersion === undefined ? {} : { acceptedVersion }),
+            });
+        }
+        return { type: desired.type, name: desired.name, status: "missing", path: root };
+    }
+    if (accepted?.packageFormat === "agent-skill") {
+        if (acceptedConstraintMismatch) {
+            return constraintMismatchObservation({
+                path,
+                desired,
+                canonicalPath: root,
+                ...(acceptedVersion === undefined ? {} : { acceptedVersion }),
+            });
+        }
+        const skillMdPath = path.join(root, "SKILL.md");
+        const skillMdExists = yield* fs.exists(skillMdPath).pipe(Effect.orElseSucceed(() => false));
+        if (!skillMdExists) {
+            return { type: desired.type, name: desired.name, status: "incomplete", path: root };
+        }
+        const raw = yield* fs.readFileString(skillMdPath).pipe(Effect.result);
+        if (Result.isFailure(raw)) {
+            return { type: desired.type, name: desired.name, status: "corrupt", path: root };
+        }
+        if (Option.isNone(parseSkillMd(raw.success, accepted.packageName))) {
+            return { type: desired.type, name: desired.name, status: "corrupt", path: root };
+        }
+        const observedIntegrity = yield* Effect.result(computeMaterializedTreeIntegrity(root));
+        if (Result.isFailure(observedIntegrity) ||
+            observedIntegrity.success !== accepted.treeIntegrity) {
+            return {
+                type: desired.type,
+                name: desired.name,
+                status: "materialization-mismatch",
+                path: root,
+            };
+        }
+        return {
+            type: desired.type,
+            name: desired.name,
+            status: "usable",
+            path: root,
+        };
+    }
+    const contract = MANIFEST_CONTRACTS[desired.type];
+    const manifestPath = path.join(root, contract.filename);
+    const manifestExists = yield* fs.exists(manifestPath).pipe(Effect.orElseSucceed(() => false));
+    let manifestVersion;
+    {
+        if (!manifestExists) {
+            if (acceptedConstraintMismatch) {
+                return constraintMismatchObservation({
+                    path,
+                    desired,
+                    canonicalPath: root,
+                    ...(acceptedVersion === undefined ? {} : { acceptedVersion }),
+                });
+            }
+            return { type: desired.type, name: desired.name, status: "incomplete", path: root };
+        }
+        const raw = yield* fs.readFileString(manifestPath).pipe(Effect.result);
+        if (Result.isFailure(raw)) {
+            if (acceptedConstraintMismatch) {
+                return constraintMismatchObservation({
+                    path,
+                    desired,
+                    canonicalPath: root,
+                    ...(acceptedVersion === undefined ? {} : { acceptedVersion }),
+                });
+            }
+            return { type: desired.type, name: desired.name, status: "corrupt", path: root };
+        }
+        const parsed = parseJson(raw.success);
+        if (parsed === undefined) {
+            if (acceptedConstraintMismatch) {
+                return constraintMismatchObservation({
+                    path,
+                    desired,
+                    canonicalPath: root,
+                    ...(acceptedVersion === undefined ? {} : { acceptedVersion }),
+                });
+            }
+            return { type: desired.type, name: desired.name, status: "corrupt", path: root };
+        }
+        const decoded = Schema.decodeUnknownResult(contract.schema)(parsed);
+        if (Result.isFailure(decoded)) {
+            if (acceptedConstraintMismatch) {
+                return constraintMismatchObservation({
+                    path,
+                    desired,
+                    canonicalPath: root,
+                    ...(acceptedVersion === undefined ? {} : { acceptedVersion }),
+                });
+            }
+            return { type: desired.type, name: desired.name, status: "corrupt", path: root };
+        }
+        const expectedOwner = bundled
+            ? "@agentxm"
+            : workspaceAuthored
+                ? layout.owner
+                : accepted?.type === "registry"
+                    ? accepted.owner
+                    : accepted?.packageOwner;
+        const expectedName = bundled
+            ? desired.name
+            : workspaceAuthored
+                ? desired.name
+                : accepted?.type === "registry"
+                    ? accepted.name
+                    : accepted?.packageName;
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            !("owner" in parsed) ||
+            parsed.owner !== expectedOwner ||
+            !("name" in parsed) ||
+            parsed.name !== expectedName ||
+            !("type" in parsed) ||
+            parsed.type !== desired.type) {
+            return { type: desired.type, name: desired.name, status: "wrong-origin", path: root };
+        }
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            "version" in parsed &&
+            typeof parsed.version === "string") {
+            manifestVersion = parsed.version;
+        }
+    }
+    if (desired.constraints.length > 0 &&
+        (acceptedConstraintMismatch ||
+            (workspaceAuthored &&
+                (manifestVersion === undefined ||
+                    desired.constraints.some((constraint) => !semver.satisfies(manifestVersion, constraint)))))) {
+        return constraintMismatchObservation({
+            path,
+            desired,
+            canonicalPath: root,
+            ...(acceptedVersion === undefined ? {} : { acceptedVersion }),
+            ...(manifestVersion === undefined ? {} : { observedVersion: manifestVersion }),
+        });
+    }
+    const payloadComplete = yield* hasRequiredPayload(fs, path, root, desired.type, desired.name).pipe(Effect.orElseSucceed(() => false));
+    if (!payloadComplete) {
+        return { type: desired.type, name: desired.name, status: "incomplete", path: root };
+    }
+    if (!workspaceAuthored && accepted !== undefined) {
+        const observedIntegrity = yield* Effect.result(computeMaterializedTreeIntegrity(root));
+        if (Result.isFailure(observedIntegrity) ||
+            observedIntegrity.success !== accepted.treeIntegrity) {
+            return {
+                type: desired.type,
+                name: desired.name,
+                status: "materialization-mismatch",
+                path: root,
+            };
+        }
+    }
+    return {
+        type: desired.type,
+        name: desired.name,
+        status: "usable",
+        path: root,
+    };
+});
+//# sourceMappingURL=canonical-observation.js.map

package/dist/src/workspace/configured-agent-outcome.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Effective per-agent lifecycle outcome for a configured extension.
+ *
+ * Workspace-state vocabulary: the plan pipeline, agent projection, and the
+ * read-model inventory all report against this one shape.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Schema from "effect/Schema";
+export declare const ConfiguredAgentOutcomeSchema: Schema.Struct<{
+    readonly extensionType: Schema.Literals<readonly ("skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack")[]>;
+    readonly name: Schema.String;
+    readonly agentId: Schema.String;
+    readonly outcome: Schema.Literals<readonly ["projected", "current", "not-applicable", "unsupported", "blocked", "failed"]>;
+    readonly reasonCode: Schema.String;
+    readonly reason: Schema.String;
+    readonly mechanism: Schema.optional<Schema.String>;
+    readonly path: Schema.optional<Schema.String>;
+}>;
+export type ConfiguredAgentOutcome = typeof ConfiguredAgentOutcomeSchema.Type;
+//# sourceMappingURL=configured-agent-outcome.d.ts.map

package/dist/src/workspace/configured-agent-outcome.js

@@ -0,0 +1,33 @@
+/**
+ * Effective per-agent lifecycle outcome for a configured extension.
+ *
+ * Workspace-state vocabulary: the plan pipeline, agent projection, and the
+ * read-model inventory all report against this one shape.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Schema from "effect/Schema";
+import { ExtensionTypeSchema } from "@agentxm/extension-model/unstable/extensions/common";
+export const ConfiguredAgentOutcomeSchema = Schema.Struct({
+    extensionType: ExtensionTypeSchema,
+    name: Schema.String,
+    agentId: Schema.String,
+    outcome: Schema.Literals([
+        "projected",
+        "current",
+        "not-applicable",
+        "unsupported",
+        "blocked",
+        "failed",
+    ]),
+    reasonCode: Schema.String,
+    reason: Schema.String,
+    mechanism: Schema.optional(Schema.String),
+    path: Schema.optional(Schema.String),
+}).annotate({
+    identifier: "ConfiguredAgentOutcome",
+    title: "Configured Agent Outcome",
+    description: "Effective lifecycle result for one configured agent and extension.",
+});
+//# sourceMappingURL=configured-agent-outcome.js.map