@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/read-model/extensions/hook.js

@@ -0,0 +1,119 @@
+/**
+ * Hook subject module: declared/resolved/actual payloads, scanner composition,
+ * and projections via the shared helper.
+ *
+ * Declared hooks come from `settings.hooks`; resolved hooks come from
+ * `axm-lock.yaml` `hooks`. Actual occurrences come exclusively from the
+ * canonical-extensions scanner (`type === "hook"`), which enumerates
+ * project-authored `hooks/<name>/src`, project-acquired
+ * `agent_extensions/<source>/<source-full-name>`, and user-scope packages.
+ *
+ * The hook installer also writes agent-side derived artifacts — managed hook
+ * groups inside agent settings files and the advisory-rule fallback region.
+ * Those are renderings of an installed hook, not separate materializations, so
+ * they are deliberately NOT occurrences: the family derives `actual` from the
+ * canonical scanner alone and an agent-side rendering never produces an
+ * unmanaged row.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { decodeExtensionNameSync, } from "@agentxm/extension-model/unstable/extensions/common";
+import { filterMapOccurrences } from "./actual-helpers.js";
+import { canonicalAxmPackageRoot } from "./package-root.js";
+import { makeProjectedSubjectCells, projectInstalledExtensions, } from "./projection.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const canonicalToActual = (occ, scope) => {
+    const isExternal = occ.origin === "external-axm";
+    const packageRoot = canonicalAxmPackageRoot(occ);
+    return {
+        key: { scope, type: "hook", name: occ.name },
+        origin: isExternal ? { _tag: "external-axm-hook" } : { _tag: "canonical-axm-hook" },
+        contentRoot: occ.contentLocation,
+        packageRoot,
+    };
+};
+const declaredFromSettings = (settings) => {
+    if (settings.hooks === undefined)
+        return [];
+    return Object.entries(settings.hooks).map(([name, entry]) => ({
+        name: decodeExtensionNameSync(name),
+        entry,
+    }));
+};
+const resolvedFromLockfile = (lockfile) => {
+    if (lockfile.hooks === undefined)
+        return [];
+    return Object.entries(lockfile.hooks).map(([name, lockEntry]) => ({
+        name: decodeExtensionNameSync(name),
+        lockEntry,
+    }));
+};
+const orphanResolvedWarning = (name) => ({
+    source: "lockfile",
+    message: `hook: lockfile entry "${name}" has no matching declared or pack-member home`,
+    code: "orphan-resolved",
+});
+const hookPolicy = (scope) => ({
+    declaredEntries: (d) => d,
+    declaredName: (entry) => entry.name,
+    declaredActivation: (entry) => (entry.entry.enabled === false ? "disabled" : "enabled"),
+    resolvedEntries: (r) => r,
+    resolvedName: (entry) => entry.name,
+    actualEntries: (a) => a,
+    actualName: (e) => e.key.name,
+    packMemberName: (m) => m.name,
+    packMemberActivation: () => "enabled",
+    attachActualToInstalled: (name, actual) => actual.filter((a) => a.key.name === name),
+    notClaimedBySubjectPolicy: () => true,
+    buildInstalledRow: (input) => ({
+        key: { scope, type: "hook", name: input.name },
+        installationOrigin: input.installationOrigin,
+        activation: input.activation,
+        resolved: input.resolved,
+        actual: input.actual,
+        providingPacks: input.providingPacks,
+    }),
+    buildUnmanagedRow: (entry) => ({
+        key: { scope, type: "hook", name: entry.key.name },
+        actual: entry,
+    }),
+    resolvedOrphanWarning: orphanResolvedWarning,
+});
+/**
+ * Build the hook subject API. Returns an `Effect` because the projection
+ * cell is wrapped in `Effect.cached` so the four derived cells share one
+ * in-flight execution per scope, mirroring `state.ts`.
+ */
+export const makeHookExtensionsApi = (deps) => Effect.gen(function* () {
+    const { scope, scanners, diagnostics } = deps;
+    const declared = deps.loaders.settings.pipe(Effect.map((opt) => Option.map(opt, declaredFromSettings)));
+    const resolved = deps.loaders.lockfile.pipe(Effect.map((opt) => Option.map(opt, resolvedFromLockfile)));
+    const actual = Effect.gen(function* () {
+        const canonical = yield* scanners.canonical;
+        return filterMapOccurrences(canonical, "hook", (occ) => canonicalToActual(occ, scope));
+    });
+    const project = yield* Effect.cached(projectInstalledExtensions({
+        declared,
+        resolved,
+        actual,
+        installedPacks: deps.installedPacks,
+        packMembers: (pack) => pack.hooks,
+        packRef: (pack) => pack.ref,
+        policy: hookPolicy(scope),
+        diagnostics,
+    }));
+    return {
+        ...makeProjectedSubjectCells({
+            declared,
+            resolved,
+            actual,
+            project,
+        }),
+        declared,
+        resolved,
+        actual,
+    };
+});
+//# sourceMappingURL=hook.js.map

package/dist/src/workspace/read-model/extensions/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Subject-module barrel: re-exports every per-subject API factory and its
+ * public payload types from one entry point so `context.ts` and downstream
+ * consumers can import a single module per concern instead of seven.
+ *
+ * Each subject module owns its own row shapes, scanner-composition signature,
+ * and projection wiring; this barrel only re-exports — no logic.
+ */
+export { makeSkillExtensionsApi, type ActualSkill, type ActualSkills, type DeclaredSkill, type DeclaredSkills, type InstalledPackForSkills, type InstalledSkill, type ResolvedSkill, type ResolvedSkills, type SkillDetectionOrigin, type SkillExtensionsApi, type SkillExtensionsApiDeps, type SkillPackMember, type SkillScanners, type SkillScopedLoaders, type UnmanagedSkill, } from "./skill.js";
+export { makeMcpServerExtensionsApi, type ActualMcpServer, type ActualMcpServers, type DeclaredMcpServer, type DeclaredMcpServers, type InstalledMcpServer, type InstalledPackForMcpServers, type McpServerDetectionOrigin, type McpServerExtensionsApi, type McpServerExtensionsApiDeps, type McpServerPackMember, type McpServerScanners, type McpServerScopedLoaders, type ResolvedMcpServer, type ResolvedMcpServers, type UnmanagedMcpServer, } from "./mcp-server.js";
+export { makeSubagentExtensionsApi, type ActualSubagent, type ActualSubagents, type DeclaredSubagent, type DeclaredSubagents, type InstalledPackForSubagents, type InstalledSubagent, type ResolvedSubagent, type ResolvedSubagents, type SubagentDetectionOrigin, type SubagentExtensionsApi, type SubagentExtensionsApiDeps, type SubagentPackMember, type SubagentScanners, type SubagentScopedLoaders, type UnmanagedSubagent, } from "./subagent.js";
+export { makeHookExtensionsApi, type ActualHook, type ActualHooks, type DeclaredHook, type DeclaredHooks, type HookDetectionOrigin, type HookExtensionsApi, type HookExtensionsApiDeps, type HookPackMember, type HookScanners, type HookScopedLoaders, type InstalledHook, type InstalledPackForHooks, type ResolvedHook, type ResolvedHooks, type UnmanagedHook, } from "./hook.js";
+export { makeKnowledgeExtensionsApi, type ActualKnowledge, type ActualKnowledgeBundle, type DeclaredKnowledge, type DeclaredKnowledgeBundle, type InstalledKnowledgeBundle, type InstalledPackForKnowledge, type KnowledgeDetectionOrigin, type KnowledgeExtensionsApi, type KnowledgeExtensionsApiDeps, type KnowledgePackMember, type KnowledgeScanners, type KnowledgeScopedLoaders, type ResolvedKnowledge, type ResolvedKnowledgeBundle, type UnmanagedKnowledgeBundle, } from "./knowledge.js";
+export { makeRuleExtensionsApi, type ActualRule, type ActualRules, type DeclaredRule, type DeclaredRules, type InstalledPackForRules, type InstalledRule, type ResolvedRule, type ResolvedRules, type RuleDetectionOrigin, type RuleExtensionsApi, type RuleExtensionsApiDeps, type RulePackMember, type RuleScanners, type RuleScopedLoaders, type UnmanagedRule, } from "./rule.js";
+export { makePackExtensionsApi, type ActualPack, type ActualPacks, type DeclaredPack, type DeclaredPacks, type InstalledPack, type PackDetectionOrigin, type PackExtensionsApi, type PackExtensionsApiDeps, type PackPackMember, type PackScanners, type PackScopedLoaders, type ResolvedPack, type ResolvedPacks, type UnmanagedPack, } from "./pack.js";
+export { projectInstalledExtensions, type BuildInstalledRowInput, type ProjectInstalledExtensionsInput, type ProjectInstalledExtensionsOutput, type SubjectPolicy, type TActualEntry, type TDeclaredEntry, type TResolvedEntry, } from "./projection.js";
+export { findByName, indexByName, type RowWithKey } from "./indexByName.js";
+export { ExtensionInventoryClassificationSchema, ExtensionInventoryLifecycleSchema, ExtensionInventoryRowSchema, ExtensionInventorySchema, projectExtensionInventory, type ExtensionInventory, type ExtensionInventoryClassification, type ExtensionInventoryLifecycle, type ExtensionInventoryObservation, type ExtensionInventoryRow, type LifecycleInventoryCandidate, type ProjectExtensionInventoryInput, } from "./inventory.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/workspace/read-model/extensions/index.js

@@ -0,0 +1,43 @@
+/**
+ * Subject-module barrel: re-exports every per-subject API factory and its
+ * public payload types from one entry point so `context.ts` and downstream
+ * consumers can import a single module per concern instead of seven.
+ *
+ * Each subject module owns its own row shapes, scanner-composition signature,
+ * and projection wiring; this barrel only re-exports — no logic.
+ */
+// ---------------------------------------------------------------------------
+// Skill subject
+// ---------------------------------------------------------------------------
+export { makeSkillExtensionsApi, } from "./skill.js";
+// ---------------------------------------------------------------------------
+// MCP server subject
+// ---------------------------------------------------------------------------
+export { makeMcpServerExtensionsApi, } from "./mcp-server.js";
+// ---------------------------------------------------------------------------
+// Subagent subject
+// ---------------------------------------------------------------------------
+export { makeSubagentExtensionsApi, } from "./subagent.js";
+// ---------------------------------------------------------------------------
+// Hook subject
+// ---------------------------------------------------------------------------
+export { makeHookExtensionsApi, } from "./hook.js";
+// ---------------------------------------------------------------------------
+// Knowledge subject
+// ---------------------------------------------------------------------------
+export { makeKnowledgeExtensionsApi, } from "./knowledge.js";
+// ---------------------------------------------------------------------------
+// Rule subject
+// ---------------------------------------------------------------------------
+export { makeRuleExtensionsApi, } from "./rule.js";
+// ---------------------------------------------------------------------------
+// Pack subject
+// ---------------------------------------------------------------------------
+export { makePackExtensionsApi, } from "./pack.js";
+// ---------------------------------------------------------------------------
+// Shared projection helper + name-index helpers
+// ---------------------------------------------------------------------------
+export { projectInstalledExtensions, } from "./projection.js";
+export { findByName, indexByName } from "./indexByName.js";
+export { ExtensionInventoryClassificationSchema, ExtensionInventoryLifecycleSchema, ExtensionInventoryRowSchema, ExtensionInventorySchema, projectExtensionInventory, } from "./inventory.js";
+//# sourceMappingURL=index.js.map

package/dist/src/workspace/read-model/extensions/indexByName.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure `indexByName` / `findByName` helpers for projection rows carrying an
+ * `ExtensionKey`. Exported once from this shared utility; per-subject modules
+ * re-use the same shape so command handlers can lookup a row by name without
+ * each subject re-implementing the operation.
+ *
+ * Rows are read-only inputs; the helpers do not mutate or copy beyond what is
+ * needed to build a `Map`. First-seen wins on duplicate names — duplicates are
+ * rare in projection output (the projection helper deduplicates by name) but
+ * the contract is explicit.
+ */
+import * as Option from "effect/Option";
+import type { ExtensionKey } from "../types.js";
+/**
+ * Minimal row shape the helpers operate on. Subjects whose row carries
+ * `key: ExtensionKey<TType>` for any `TType` satisfies this constraint.
+ */
+export interface RowWithKey {
+    readonly key: ExtensionKey;
+}
+/**
+ * Build a name-indexed read-only map from a row array. First row with a given
+ * `key.name` wins; subsequent rows with the same name are dropped.
+ */
+export declare const indexByName: <Row extends RowWithKey>(rows: ReadonlyArray<Row>) => ReadonlyMap<string, Row>;
+/**
+ * Look up one row by name. Returns `Option.none()` when the name is not
+ * indexed.
+ */
+export declare const findByName: <Row extends RowWithKey>(rows: ReadonlyArray<Row>, name: string) => Option.Option<Row>;
+//# sourceMappingURL=indexByName.d.ts.map

package/dist/src/workspace/read-model/extensions/indexByName.js

@@ -0,0 +1,30 @@
+/**
+ * Pure `indexByName` / `findByName` helpers for projection rows carrying an
+ * `ExtensionKey`. Exported once from this shared utility; per-subject modules
+ * re-use the same shape so command handlers can lookup a row by name without
+ * each subject re-implementing the operation.
+ *
+ * Rows are read-only inputs; the helpers do not mutate or copy beyond what is
+ * needed to build a `Map`. First-seen wins on duplicate names — duplicates are
+ * rare in projection output (the projection helper deduplicates by name) but
+ * the contract is explicit.
+ */
+import * as Option from "effect/Option";
+/**
+ * Build a name-indexed read-only map from a row array. First row with a given
+ * `key.name` wins; subsequent rows with the same name are dropped.
+ */
+export const indexByName = (rows) => {
+    const map = new Map();
+    for (const row of rows) {
+        if (!map.has(row.key.name))
+            map.set(row.key.name, row);
+    }
+    return map;
+};
+/**
+ * Look up one row by name. Returns `Option.none()` when the name is not
+ * indexed.
+ */
+export const findByName = (rows, name) => Option.fromUndefinedOr(indexByName(rows).get(name));
+//# sourceMappingURL=indexByName.js.map

package/dist/src/workspace/read-model/extensions/inventory.d.ts

@@ -0,0 +1,99 @@
+import * as Schema from "effect/Schema";
+import { type ConfiguredAgentOutcome } from "../../configured-agent-outcome.js";
+import type { ExtensionKey } from "../types.js";
+export declare const ExtensionInventoryLifecycleSchema: Schema.Literals<readonly ["configured", "implicit", "unmanaged"]>;
+export type ExtensionInventoryLifecycle = typeof ExtensionInventoryLifecycleSchema.Type;
+export declare const ExtensionInventoryClassificationSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"lifecycle">;
+    readonly lifecycle: Schema.Literals<readonly ["configured", "implicit", "unmanaged"]>;
+}>;
+export type ExtensionInventoryClassification = typeof ExtensionInventoryClassificationSchema.Type;
+export declare const ExtensionInventoryRowSchema: Schema.Struct<{
+    readonly scope: Schema.Literals<readonly ["project", "user"]>;
+    readonly type: Schema.Literals<readonly ("skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack")[]>;
+    readonly name: Schema.String;
+    readonly classification: Schema.Struct<{
+        readonly kind: Schema.Literal<"lifecycle">;
+        readonly lifecycle: Schema.Literals<readonly ["configured", "implicit", "unmanaged"]>;
+    }>;
+    readonly enabled: Schema.NullOr<Schema.Boolean>;
+    readonly installed: Schema.Boolean;
+    readonly agents: Schema.$Array<Schema.String>;
+    readonly agentOutcomes: Schema.$Array<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>;
+    }>>;
+    readonly origins: Schema.$Array<Schema.String>;
+    readonly paths: Schema.$Array<Schema.String>;
+    readonly source: Schema.optionalKey<Schema.String>;
+    readonly version: Schema.optionalKey<Schema.String>;
+    readonly owner: Schema.optionalKey<Schema.String>;
+    readonly transport: Schema.optionalKey<Schema.String>;
+    readonly status: Schema.optionalKey<Schema.String>;
+    readonly locked: Schema.optionalKey<Schema.Boolean>;
+    readonly sourceType: Schema.optionalKey<Schema.String>;
+}>;
+export type ExtensionInventoryRow = typeof ExtensionInventoryRowSchema.Type;
+export declare const ExtensionInventorySchema: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly scope: Schema.Literals<readonly ["project", "user"]>;
+        readonly type: Schema.Literals<readonly ("skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack")[]>;
+        readonly name: Schema.String;
+        readonly classification: Schema.Struct<{
+            readonly kind: Schema.Literal<"lifecycle">;
+            readonly lifecycle: Schema.Literals<readonly ["configured", "implicit", "unmanaged"]>;
+        }>;
+        readonly enabled: Schema.NullOr<Schema.Boolean>;
+        readonly installed: Schema.Boolean;
+        readonly agents: Schema.$Array<Schema.String>;
+        readonly agentOutcomes: Schema.$Array<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>;
+        }>>;
+        readonly origins: Schema.$Array<Schema.String>;
+        readonly paths: Schema.$Array<Schema.String>;
+        readonly source: Schema.optionalKey<Schema.String>;
+        readonly version: Schema.optionalKey<Schema.String>;
+        readonly owner: Schema.optionalKey<Schema.String>;
+        readonly transport: Schema.optionalKey<Schema.String>;
+        readonly status: Schema.optionalKey<Schema.String>;
+        readonly locked: Schema.optionalKey<Schema.Boolean>;
+        readonly sourceType: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly count: Schema.Number;
+    readonly configuredCount: Schema.Number;
+    readonly implicitCount: Schema.Number;
+    readonly installedCount: Schema.Number;
+    readonly unmanagedCount: Schema.Number;
+}>;
+export type ExtensionInventory = typeof ExtensionInventorySchema.Type;
+export interface ExtensionInventoryObservation {
+    readonly agents?: ReadonlyArray<string>;
+    readonly origins?: ReadonlyArray<string>;
+    readonly paths?: ReadonlyArray<string>;
+}
+export interface LifecycleInventoryCandidate extends ExtensionInventoryObservation {
+    readonly key: ExtensionKey;
+    readonly lifecycle: ExtensionInventoryLifecycle;
+    readonly enabled: boolean | null;
+    readonly installed: boolean;
+    readonly agentOutcomes?: ReadonlyArray<ConfiguredAgentOutcome>;
+}
+export interface ProjectExtensionInventoryInput {
+    readonly lifecycle: ReadonlyArray<LifecycleInventoryCandidate>;
+    readonly agents?: ReadonlyArray<string>;
+}
+export declare const projectExtensionInventory: (input: ProjectExtensionInventoryInput) => ExtensionInventory;
+//# sourceMappingURL=inventory.d.ts.map

package/dist/src/workspace/read-model/extensions/inventory.js

@@ -0,0 +1,111 @@
+import * as Schema from "effect/Schema";
+import { ExtensionTypeSchema } from "@agentxm/extension-model/unstable/extensions/common";
+import { ConfiguredAgentOutcomeSchema, } from "../../configured-agent-outcome.js";
+export const ExtensionInventoryLifecycleSchema = Schema.Literals([
+    "configured",
+    "implicit",
+    "unmanaged",
+]);
+export const ExtensionInventoryClassificationSchema = Schema.Struct({
+    kind: Schema.Literal("lifecycle"),
+    lifecycle: ExtensionInventoryLifecycleSchema,
+});
+export const ExtensionInventoryRowSchema = Schema.Struct({
+    scope: Schema.Literals(["project", "user"]),
+    type: ExtensionTypeSchema,
+    name: Schema.String,
+    classification: ExtensionInventoryClassificationSchema,
+    enabled: Schema.NullOr(Schema.Boolean),
+    installed: Schema.Boolean,
+    agents: Schema.Array(Schema.String),
+    agentOutcomes: Schema.Array(ConfiguredAgentOutcomeSchema),
+    origins: Schema.Array(Schema.String),
+    paths: Schema.Array(Schema.String),
+    source: Schema.optionalKey(Schema.String),
+    version: Schema.optionalKey(Schema.String),
+    owner: Schema.optionalKey(Schema.String),
+    transport: Schema.optionalKey(Schema.String),
+    status: Schema.optionalKey(Schema.String),
+    locked: Schema.optionalKey(Schema.Boolean),
+    sourceType: Schema.optionalKey(Schema.String),
+});
+export const ExtensionInventorySchema = Schema.Struct({
+    items: Schema.Array(ExtensionInventoryRowSchema),
+    count: Schema.Number,
+    configuredCount: Schema.Number,
+    implicitCount: Schema.Number,
+    installedCount: Schema.Number,
+    unmanagedCount: Schema.Number,
+});
+const lifecyclePriority = {
+    configured: 0,
+    implicit: 1,
+    unmanaged: 2,
+};
+const keyString = (key) => `${key.scope}:${key.type}:${key.name}`;
+const addAll = (target, values) => {
+    for (const value of values ?? [])
+        target.add(value);
+};
+const sorted = (values) => Array.from(values).sort((left, right) => left.localeCompare(right));
+const matchesAgentFilter = (agents, filter) => filter.length === 0 || filter.some((agent) => agents.includes(agent));
+export const projectExtensionInventory = (input) => {
+    const lifecycleByKey = new Map();
+    for (const candidate of input.lifecycle) {
+        const candidateKey = keyString(candidate.key);
+        const existing = lifecycleByKey.get(candidateKey);
+        if (existing === undefined) {
+            const aggregate = {
+                key: candidate.key,
+                lifecycle: candidate.lifecycle,
+                enabled: candidate.enabled,
+                installed: candidate.installed,
+                agents: new Set(candidate.agents ?? []),
+                agentOutcomes: new Map((candidate.agentOutcomes ?? []).map((outcome) => [outcome.agentId, outcome])),
+                origins: new Set(candidate.origins ?? []),
+                paths: new Set(candidate.paths ?? []),
+            };
+            lifecycleByKey.set(candidateKey, aggregate);
+            continue;
+        }
+        if (lifecyclePriority[candidate.lifecycle] < lifecyclePriority[existing.lifecycle]) {
+            existing.lifecycle = candidate.lifecycle;
+            existing.enabled = candidate.enabled;
+        }
+        existing.installed = existing.installed || candidate.installed;
+        addAll(existing.agents, candidate.agents);
+        for (const outcome of candidate.agentOutcomes ?? []) {
+            existing.agentOutcomes.set(outcome.agentId, outcome);
+        }
+        addAll(existing.origins, candidate.origins);
+        addAll(existing.paths, candidate.paths);
+    }
+    const agentFilter = input.agents ?? [];
+    const lifecycleRows = Array.from(lifecycleByKey.entries())
+        .filter(([, aggregate]) => matchesAgentFilter(sorted(aggregate.agents), agentFilter))
+        .map(([, aggregate]) => ({
+        scope: aggregate.key.scope,
+        type: aggregate.key.type,
+        name: aggregate.key.name,
+        classification: { kind: "lifecycle", lifecycle: aggregate.lifecycle },
+        enabled: aggregate.enabled,
+        installed: aggregate.installed,
+        agents: sorted(aggregate.agents),
+        agentOutcomes: Array.from(aggregate.agentOutcomes.values()).sort((left, right) => left.agentId.localeCompare(right.agentId)),
+        origins: sorted(aggregate.origins),
+        paths: sorted(aggregate.paths),
+    }));
+    const items = lifecycleRows.sort((left, right) => left.name.localeCompare(right.name));
+    const configuredCount = items.filter((item) => item.classification.lifecycle === "configured").length;
+    const implicitCount = items.filter((item) => item.classification.lifecycle === "implicit").length;
+    const unmanagedCount = items.filter((item) => item.classification.lifecycle === "unmanaged").length;
+    return {
+        items,
+        count: items.length,
+        configuredCount,
+        implicitCount,
+        installedCount: items.filter((item) => item.installed).length,
+        unmanagedCount,
+    };
+};
+//# sourceMappingURL=inventory.js.map

package/dist/src/workspace/read-model/extensions/knowledge.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Knowledge subject module: declared/resolved/actual payloads, scanner
+ * composition, and projections via the shared helper.
+ *
+ * Declared bundles come from `settings.knowledge`; resolved bundles come from
+ * `axm-lock.yaml` `knowledge`. Actual occurrences come exclusively from the
+ * canonical-extensions scanner (`type === "knowledge"`), which enumerates
+ * project-authored `knowledge/<name>/src`, project-acquired
+ * `agent_extensions/<source>/<source-full-name>`, and user-scope packages.
+ *
+ * Knowledge installs also write two derived artifacts — the `.axm/knowledge/index.md`
+ * catalog and the discovery region inside the agent instructions file. Both live
+ * outside canonical package roots, so the canonical scanner never sees them and they
+ * cannot become occurrences; `actual` is therefore scoped to the materialized
+ * bundle package directory by construction.
+ *
+ * Pack-resolved Knowledge members participate in the same direct-over-pack
+ * projection as every other extension type.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { type ExtensionName } from "@agentxm/extension-model/unstable/extensions/common";
+import type { KnowledgeLockEntry, Lockfile } from "../../../lockfile/schema.js";
+import type { KnowledgeEntry, Settings } from "../../../settings/schema.js";
+import type { Diagnostics } from "../diagnostics.js";
+import type { LockfileReadError, SettingsReadError } from "../errors.js";
+import type { CanonicalExtensionOccurrence } from "../scanners/types.js";
+import type { ActivationState, ExtensionKey, InstallationOrigin, InstalledPackRef, Scope } from "../types.js";
+export type KnowledgeDetectionOrigin = {
+    readonly _tag: "canonical-axm-knowledge";
+} | {
+    readonly _tag: "external-axm-knowledge";
+};
+export interface DeclaredKnowledgeBundle {
+    readonly name: ExtensionName;
+    readonly entry: KnowledgeEntry;
+}
+export type DeclaredKnowledge = ReadonlyArray<DeclaredKnowledgeBundle>;
+export interface ResolvedKnowledgeBundle {
+    readonly name: ExtensionName;
+    readonly lockEntry: KnowledgeLockEntry;
+}
+export type ResolvedKnowledge = ReadonlyArray<ResolvedKnowledgeBundle>;
+export interface ActualKnowledgeBundle {
+    readonly key: ExtensionKey<"knowledge">;
+    readonly origin: KnowledgeDetectionOrigin;
+    readonly contentRoot: string;
+    readonly packageRoot: string | null;
+}
+export type ActualKnowledge = ReadonlyArray<ActualKnowledgeBundle>;
+export interface KnowledgePackMember {
+    readonly name: ExtensionName;
+    readonly providingPack: InstalledPackRef;
+}
+export interface InstalledKnowledgeBundle {
+    readonly key: ExtensionKey<"knowledge">;
+    readonly installationOrigin: InstallationOrigin<DeclaredKnowledgeBundle, KnowledgePackMember>;
+    readonly activation: ActivationState;
+    readonly resolved: Option.Option<ResolvedKnowledgeBundle>;
+    readonly actual: ReadonlyArray<ActualKnowledgeBundle>;
+    readonly providingPacks: ReadonlyArray<InstalledPackRef>;
+}
+export interface UnmanagedKnowledgeBundle {
+    readonly key: ExtensionKey<"knowledge">;
+    readonly actual: ActualKnowledgeBundle;
+}
+export interface KnowledgeScanners {
+    readonly canonical: Effect.Effect<ReadonlyArray<CanonicalExtensionOccurrence>>;
+}
+export interface KnowledgeScopedLoaders {
+    readonly settings: Effect.Effect<Option.Option<Settings>, SettingsReadError>;
+    readonly lockfile: Effect.Effect<Option.Option<Lockfile>, LockfileReadError>;
+}
+export interface KnowledgeExtensionsApiDeps {
+    readonly scope: Scope;
+    readonly loaders: KnowledgeScopedLoaders;
+    readonly scanners: KnowledgeScanners;
+    readonly installedPacks: Effect.Effect<ReadonlyArray<InstalledPackForKnowledge>, SettingsReadError | LockfileReadError>;
+    readonly diagnostics: Diagnostics;
+}
+export interface InstalledPackForKnowledge {
+    readonly ref: InstalledPackRef;
+    readonly knowledge: ReadonlyArray<KnowledgePackMember>;
+}
+export interface KnowledgeExtensionsApi {
+    readonly declared: Effect.Effect<Option.Option<DeclaredKnowledge>, SettingsReadError>;
+    readonly resolved: Effect.Effect<Option.Option<ResolvedKnowledge>, LockfileReadError>;
+    readonly actual: Effect.Effect<ActualKnowledge>;
+    readonly installed: Effect.Effect<ReadonlyArray<InstalledKnowledgeBundle>, SettingsReadError | LockfileReadError>;
+    readonly byName: (name: string) => Effect.Effect<Option.Option<InstalledKnowledgeBundle>, SettingsReadError | LockfileReadError>;
+    readonly declaredByName: (name: string) => Effect.Effect<Option.Option<DeclaredKnowledgeBundle>, SettingsReadError>;
+    readonly active: Effect.Effect<ReadonlyArray<InstalledKnowledgeBundle>, SettingsReadError | LockfileReadError>;
+    readonly unmanaged: Effect.Effect<ReadonlyArray<UnmanagedKnowledgeBundle>, SettingsReadError | LockfileReadError>;
+}
+/**
+ * Build the knowledge subject API. Returns an `Effect` because the projection
+ * cell is wrapped in `Effect.cached` so the four derived cells share one
+ * in-flight execution per scope, mirroring `state.ts`.
+ */
+export declare const makeKnowledgeExtensionsApi: (deps: KnowledgeExtensionsApiDeps) => Effect.Effect<KnowledgeExtensionsApi>;
+//# sourceMappingURL=knowledge.d.ts.map