@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/read-model/service.js

@@ -0,0 +1,391 @@
+/** Per-scope read-only workspace model factory and configuration. */
+import * as Brand from "effect/Brand";
+import * as ServiceMap from "effect/Context";
+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 Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { AgentPresenceProbe } from "./agent-presence.js";
+import { AGENTS } from "@agentxm/extension-model/unstable/agents/registry";
+import { parseExtensionFqnParts, } from "@agentxm/extension-model/unstable/extensions/common";
+import {} from "@agentxm/extension-model/unstable/extensions/handle";
+import { PACK_MANIFEST_FILENAME, PackManifestSchema, } from "@agentxm/extension-model/unstable/packs/manifest-schema";
+import { makeAbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import { resolveProjectWorkspaceLayout, resolveProjectWorkspaceStatePaths, resolveUserWorkspaceLayout, } from "../layout.js";
+import { AgentRootResolver } from "./agent-root-resolver.js";
+import { makeScopedAgentsApi } from "./agents/index.js";
+import {} from "./agents/types.js";
+import { makeDiagnostics } from "./diagnostics.js";
+import { WorkspaceRootEscape, } from "./errors.js";
+import { makeHookExtensionsApi, makeKnowledgeExtensionsApi, makeMcpServerExtensionsApi, makePackExtensionsApi, makeRuleExtensionsApi, makeSkillExtensionsApi, makeSubagentExtensionsApi, } from "./extensions/index.js";
+import { makeAgentDirScanner, makeAgentSettingsScanner, makeCanonicalExtensionsScanner, makeMcpConfigScanner, } from "./scanners/index.js";
+import { makeScopedStateApi } from "./state.js";
+/**
+ * The read-model family that carries each catalog extension type, or `null`
+ * where no family exists yet.
+ *
+ * Total by construction: a new extension type fails compile here until its
+ * read-model coverage is decided. The parity conformance suite reads this map
+ * to check the read-model obligation, and every `null` must be matched by a
+ * ledger row.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const READ_MODEL_EXTENSION_FAMILY_BY_TYPE = {
+    skill: "skills",
+    "mcp-server": "mcpServers",
+    subagent: "subagents",
+    rule: "rules",
+    hook: "hooks",
+    knowledge: "knowledge",
+};
+/** Service tag for the {@link WorkspaceReadModelConfigService} the factory requires. */
+export class WorkspaceReadModelConfig extends ServiceMap.Service()("@agentxm/workspace-state/workspace/read-model/service/WorkspaceReadModelConfig") {
+}
+const ResolvedWorkspaceRoot = Brand.nominal();
+/** Resolve and validate a workspace root resides within `allowedRoot`. */
+const validateRoot = (pathSvc, candidate, allowedRoot) => Effect.gen(function* () {
+    const resolved = pathSvc.resolve(candidate);
+    const resolvedAllowed = pathSvc.resolve(allowedRoot);
+    if (resolved === resolvedAllowed)
+        return ResolvedWorkspaceRoot(resolved);
+    const relative = pathSvc.relative(resolvedAllowed, resolved);
+    if (relative !== "" && (relative.startsWith("..") || pathSvc.isAbsolute(relative))) {
+        return yield* new WorkspaceRootEscape({
+            workspaceRoot: candidate,
+            allowedRoot,
+        });
+    }
+    return ResolvedWorkspaceRoot(resolved);
+});
+const buildScope = Effect.fn("workspace.read-model.build-scope")(function* (deps) {
+    const { scope, fs, path, workspaceRoot, settingsPath, lockfilePath, rootResolverState, diagnosticsRef, } = deps;
+    // Diagnostics buffer (Ref provided by the factory so collision warnings
+    // detected by the resolver layer can be pre-seeded for the project scope).
+    const diagnostics = makeDiagnostics(diagnosticsRef);
+    // Cached state-source cells: settings/settingsRaw + lockfile/lockfileRaw.
+    const loaders = yield* makeScopedStateApi(scope, {
+        fs,
+        path,
+        settingsPath,
+        lockfilePath,
+    });
+    const settingsResult = yield* Effect.result(loaders.settings);
+    const layoutSettings = Result.isSuccess(settingsResult)
+        ? Option.getOrElse(settingsResult.success, () => ({}))
+        : {};
+    const resolveLayout = () => scope === "project"
+        ? resolveProjectWorkspaceLayout(makeAbsolutePath(path, workspaceRoot), layoutSettings).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path))
+        : resolveUserWorkspaceLayout(makeAbsolutePath(path, workspaceRoot), layoutSettings).pipe(Effect.provideService(Path.Path, path));
+    const layoutResult = yield* Effect.result(resolveLayout());
+    if (Result.isFailure(layoutResult)) {
+        yield* diagnostics.append({
+            source: "scanner",
+            message: `workspace-layout: ${layoutResult.failure.message}`,
+            code: "scanner-io",
+        });
+    }
+    // Scanner cells — eagerly enumerate the closed scanner key set.
+    const canonicalScanner = yield* Effect.cached(Result.isFailure(layoutResult)
+        ? Effect.succeed([])
+        : makeCanonicalExtensionsScanner({
+            fs,
+            path,
+            workspaceRoot,
+            diagnostics,
+            layout: layoutResult.success,
+        }));
+    const agentDirScanner = yield* Effect.cached(makeAgentDirScanner({
+        fs,
+        path,
+        workspaceRoot,
+        scope,
+        diagnostics,
+        agentRegistry: AGENTS,
+    }));
+    const mcpConfigScanner = yield* Effect.cached(makeMcpConfigScanner({
+        fs,
+        path,
+        workspaceRoot,
+        scope,
+        diagnostics,
+        agentRegistry: AGENTS,
+    }));
+    const agentSettingsScanner = yield* Effect.cached(makeAgentSettingsScanner({
+        fs,
+        path,
+        workspaceRoot,
+        scope,
+        diagnostics,
+        agentRegistry: AGENTS,
+        rootResolverState,
+    }));
+    // Build the pack subject first; per-subject pack-member input derives from it.
+    const packsApi = yield* makePackExtensionsApi({
+        scope,
+        loaders,
+        scanners: { canonical: canonicalScanner },
+        diagnostics,
+    });
+    // Cache the authored-manifest membership rollup once per scope; shared
+    // across subjects. Lock rows authorize external Pack resolution but never
+    // provide membership.
+    const installedPackMembers = yield* Effect.cached(Effect.gen(function* () {
+        const active = yield* packsApi.active;
+        return yield* Effect.forEach(active, (row) => {
+            const packageRoot = row.actual.flatMap((actual) => actual.packageRoot === null ? [] : [actual.packageRoot])[0];
+            const empty = {
+                key: row.key,
+                skills: [],
+                mcpServers: [],
+                subagents: [],
+                rules: [],
+                hooks: [],
+                knowledge: [],
+            };
+            if (packageRoot === undefined)
+                return Effect.succeed(empty);
+            const manifestPath = path.join(packageRoot, PACK_MANIFEST_FILENAME);
+            return Effect.gen(function* () {
+                const contents = yield* fs.readFileString(manifestPath);
+                const parsedResult = Result.try({
+                    try: () => JSON.parse(contents),
+                    catch: () => "invalid-pack-manifest-json",
+                });
+                if (Result.isFailure(parsedResult)) {
+                    return yield* Effect.fail(parsedResult.failure);
+                }
+                const manifest = yield* Schema.decodeUnknownEffect(PackManifestSchema)(parsedResult.success);
+                const members = {
+                    skill: [],
+                    "mcp-server": [],
+                    subagent: [],
+                    rule: [],
+                    hook: [],
+                    knowledge: [],
+                };
+                for (const fqn of Object.keys(manifest.dependencies)) {
+                    const member = parseExtensionFqnParts(fqn);
+                    if (member !== undefined && member.type !== "pack") {
+                        members[member.type].push(member.name);
+                    }
+                }
+                return {
+                    key: row.key,
+                    skills: members.skill,
+                    mcpServers: members["mcp-server"],
+                    subagents: members.subagent,
+                    rules: members.rule,
+                    hooks: members.hook,
+                    knowledge: members.knowledge,
+                };
+            }).pipe(Effect.result, Effect.flatMap((result) => Result.isSuccess(result)
+                ? Effect.succeed(result.success)
+                : diagnostics
+                    .append({
+                    source: "scanner",
+                    path: manifestPath,
+                    code: "pack-manifest-invalid",
+                    message: `pack: unable to read authored membership from ${manifestPath}`,
+                })
+                    .pipe(Effect.as(empty))));
+        });
+    }));
+    const skillsInstalledPacks = installedPackMembers.pipe(Effect.map((packs) => packs.map((p) => ({
+        ref: { key: p.key },
+        skills: p.skills.map((name) => ({
+            name,
+            providingPack: { key: p.key },
+        })),
+    }))));
+    const mcpServersInstalledPacks = installedPackMembers.pipe(Effect.map((packs) => packs.map((p) => ({
+        ref: { key: p.key },
+        mcpServers: p.mcpServers.map((name) => ({
+            name,
+            providingPack: { key: p.key },
+        })),
+    }))));
+    const subagentsInstalledPacks = installedPackMembers.pipe(Effect.map((packs) => packs.map((p) => ({
+        ref: { key: p.key },
+        subagents: p.subagents.map((name) => ({
+            name,
+            providingPack: { key: p.key },
+        })),
+    }))));
+    const rulesInstalledPacks = installedPackMembers.pipe(Effect.map((packs) => packs.map((p) => ({
+        ref: { key: p.key },
+        rules: p.rules.map((name) => ({
+            name,
+            providingPack: { key: p.key },
+        })),
+    }))));
+    const hooksInstalledPacks = installedPackMembers.pipe(Effect.map((packs) => packs.map((p) => ({
+        ref: { key: p.key },
+        hooks: p.hooks.map((name) => ({
+            name,
+            providingPack: { key: p.key },
+        })),
+    }))));
+    const knowledgeInstalledPacks = installedPackMembers.pipe(Effect.map((packs) => packs.map((p) => ({
+        ref: { key: p.key },
+        knowledge: p.knowledge.map((name) => ({
+            name,
+            providingPack: { key: p.key },
+        })),
+    }))));
+    const skills = yield* makeSkillExtensionsApi({
+        scope,
+        loaders,
+        scanners: { canonical: canonicalScanner, agentDir: agentDirScanner },
+        installedPacks: skillsInstalledPacks,
+        diagnostics,
+    });
+    const mcpServers = yield* makeMcpServerExtensionsApi({
+        scope,
+        loaders,
+        scanners: { canonical: canonicalScanner, mcpConfig: mcpConfigScanner },
+        installedPacks: mcpServersInstalledPacks,
+        diagnostics,
+    });
+    const subagents = yield* makeSubagentExtensionsApi({
+        scope,
+        loaders,
+        scanners: { canonical: canonicalScanner, agentDir: agentDirScanner },
+        installedPacks: subagentsInstalledPacks,
+        diagnostics,
+    });
+    const rules = yield* makeRuleExtensionsApi({
+        scope,
+        loaders,
+        scanners: { canonical: canonicalScanner },
+        installedPacks: rulesInstalledPacks,
+        diagnostics,
+    });
+    const hooks = yield* makeHookExtensionsApi({
+        scope,
+        loaders,
+        scanners: { canonical: canonicalScanner },
+        installedPacks: hooksInstalledPacks,
+        diagnostics,
+    });
+    const knowledge = yield* makeKnowledgeExtensionsApi({
+        scope,
+        loaders,
+        scanners: { canonical: canonicalScanner },
+        installedPacks: knowledgeInstalledPacks,
+        diagnostics,
+    });
+    // Cached fold of the three scanner cells into the shape agents expects.
+    const observations = yield* Effect.cached(Effect.gen(function* () {
+        const agentDir = yield* agentDirScanner;
+        const agentSettings = yield* agentSettingsScanner;
+        const mcpConfig = yield* mcpConfigScanner;
+        return { agentDir, agentSettings, mcpConfig };
+    }));
+    // Project settings into the narrowed `DeclaredSettingsShape` agents needs.
+    const agentsSettings = loaders.settings.pipe(Effect.map((opt) => Option.map(opt, (settings) => ({
+        agents: settings.agents ?? [],
+    }))));
+    const presenceProbe = yield* Effect.serviceOption(AgentPresenceProbe);
+    const presence = yield* Effect.cached(Option.match(presenceProbe, {
+        onNone: () => Effect.succeed(new Set()),
+        onSome: (probe) => probe.detect(workspaceRoot, scope).pipe(Effect.map((detected) => new Set(detected)), Effect.catch((error) => diagnostics
+            .append({
+            source: "scanner",
+            message: `agent-presence: structured detection failed: ${error.message}`,
+            code: "scanner-io",
+        })
+            .pipe(Effect.map(() => new Set())))),
+    }));
+    const agents = makeScopedAgentsApi({
+        scope,
+        settings: agentsSettings,
+        presence,
+        observations,
+    });
+    // Source-host views over the cached settings loader.
+    const emptySources = [];
+    const declaredSourceHosts = loaders.settings.pipe(Effect.map((opt) => Option.match(opt, {
+        onNone: () => emptySources,
+        onSome: (settings) => settings.sources ?? emptySources,
+    })));
+    const sourceHosts = {
+        declared: declaredSourceHosts,
+        effective: declaredSourceHosts,
+        registryHosts: declaredSourceHosts.pipe(Effect.map((all) => all.filter((s) => s.type === "registry"))),
+        byName: (name) => declaredSourceHosts.pipe(Effect.map((all) => Option.fromUndefinedOr(all.find((s) => s.name === name)))),
+    };
+    // Owner view over the cached settings loader.
+    const owner = loaders.settings.pipe(Effect.map((opt) => Option.flatMap(opt, (settings) => Option.fromUndefinedOr(settings.owner))));
+    // Raw-bytes accessor reads from the cached raw cell; absent (`Option.none`)
+    // is distinct from unreadable (IO error in the channel).
+    const raw = (source) => source === "settings" ? loaders.settingsRaw : loaders.lockfileRaw;
+    const state = {
+        settings: loaders.settings,
+        lockfile: loaders.lockfile,
+        raw,
+    };
+    return {
+        scope,
+        skills,
+        mcpServers,
+        subagents,
+        rules,
+        hooks,
+        knowledge,
+        packs: packsApi,
+        agents,
+        state,
+        sourceHosts,
+        owner,
+        diagnostics: diagnostics.snapshot,
+        canonicalExtensions: canonicalScanner,
+    };
+});
+// ---------------------------------------------------------------------------
+// Per-scope factory
+// ---------------------------------------------------------------------------
+/**
+ * Build a {@link WorkspaceReadModel} for the requested scope.
+ *
+ * Each invocation produces a fresh instance with its own cached cells; call
+ * once at the command boundary and pass the value inward. Callers that need
+ * both scopes invoke the factory twice.
+ *
+ * Cross-scope state (the agent-root resolver and its collision warnings) is
+ * supplied by {@link AgentRootResolver}, which must be provided in the
+ * environment so the same warnings flow into every scope built against the
+ * same layer.
+ */
+export const makeWorkspaceReadModel = (scope) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const pathSvc = yield* Path.Path;
+    const config = yield* WorkspaceReadModelConfig;
+    const resolver = yield* AgentRootResolver;
+    // Validate roots eagerly — the only path that surfaces `WorkspaceRootEscape`.
+    const projectRootResolved = yield* validateRoot(pathSvc, config.projectRoot, config.allowedRoot);
+    const userHomeResolved = yield* validateRoot(pathSvc, config.userHome, config.allowedRoot);
+    // Workspace path layout per scope.
+    const workspaceRoot = scope === "project" ? projectRootResolved : userHomeResolved;
+    const projectPaths = resolveProjectWorkspaceStatePaths(pathSvc, config.projectRoot);
+    const userLayout = yield* resolveUserWorkspaceLayout(makeAbsolutePath(pathSvc, userHomeResolved)).pipe(Effect.provideService(Path.Path, pathSvc));
+    const settingsPath = scope === "project" ? projectPaths.settingsPath : userLayout.settingsPath;
+    const lockfilePath = scope === "project" ? projectPaths.lockPath : userLayout.lockPath;
+    // Pre-seed agent-root collision warnings into the project scope only;
+    // the user scope receives a clean buffer.
+    const diagnosticsRef = yield* Ref.make(scope === "project" ? resolver.collisionWarnings : []);
+    return yield* buildScope({
+        scope,
+        fs,
+        path: pathSvc,
+        workspaceRoot,
+        settingsPath,
+        lockfilePath,
+        rootResolverState: resolver.state,
+        diagnosticsRef,
+    });
+}).pipe(Effect.withSpan("workspace.read-model.make"));
+//# sourceMappingURL=service.js.map

package/dist/src/workspace/read-model/state.d.ts

@@ -0,0 +1,35 @@
+/** Cached scoped state-source loaders for `axm.json` and `axm-lock.yaml`. */
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import type * as Path from "effect/Path";
+import { type Lockfile } from "../../lockfile/schema.js";
+import { type Settings } from "../../settings/schema.js";
+import { LockfileIoError, type LockfileReadError, SettingsIoError, type SettingsReadError } from "./errors.js";
+import type { Scope } from "./types.js";
+/** Decoded `axm.json` payload exposed by the settings cell. */
+export type DecodedSettings = Settings;
+/** Decoded `axm-lock.yaml` payload exposed by the lockfile cell. */
+export type DecodedLockfile = Lockfile;
+/** Raw bytes of a workspace source file (path + literal content). */
+export interface RawSourceBytes {
+    readonly path: string;
+    readonly bytes: string;
+}
+/** Cached decoded settings/lockfile cells plus their raw-bytes siblings. */
+export interface ScopedStateLoaders {
+    readonly settings: Effect.Effect<Option.Option<DecodedSettings>, SettingsReadError>;
+    readonly lockfile: Effect.Effect<Option.Option<DecodedLockfile>, LockfileReadError>;
+    readonly settingsRaw: Effect.Effect<Option.Option<RawSourceBytes>, SettingsIoError>;
+    readonly lockfileRaw: Effect.Effect<Option.Option<RawSourceBytes>, LockfileIoError>;
+}
+/** Construction inputs captured and threaded into every cached loader. */
+export interface ScopedStateDeps {
+    readonly fs: FileSystem.FileSystem;
+    readonly path: Path.Path;
+    readonly settingsPath: string;
+    readonly lockfilePath: string | null;
+}
+/** Build the cached, requirement-free `ScopedStateLoaders` for one scope. */
+export declare const makeScopedStateApi: (_scope: Scope, deps: ScopedStateDeps) => Effect.Effect<ScopedStateLoaders>;
+//# sourceMappingURL=state.d.ts.map

package/dist/src/workspace/read-model/state.js

@@ -0,0 +1,97 @@
+/** Cached scoped state-source loaders for `axm.json` and `axm-lock.yaml`. */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import YAML from "yaml";
+import { LockfileSchema } from "../../lockfile/schema.js";
+import { formatSchemaIssuesToLines } from "@agentxm/extension-model/unstable/schema-issues";
+import { SettingsSchema } from "../../settings/schema.js";
+import { LockfileDecodeError, LockfileIoError, LockfileParseError, SettingsDecodeError, SettingsIoError, SettingsParseError, } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Raw bytes loaders (shared by the decoded loaders and the public raw cells)
+// ---------------------------------------------------------------------------
+const loadRawSettingsBytes = Effect.fn("workspace.read-model.state.settings.raw")(function* (deps) {
+    const { fs, settingsPath } = deps;
+    const exists = yield* fs
+        .exists(settingsPath)
+        .pipe(Effect.mapError((cause) => new SettingsIoError({ path: settingsPath, cause })));
+    if (!exists)
+        return Option.none();
+    const bytes = yield* fs
+        .readFileString(settingsPath)
+        .pipe(Effect.mapError((cause) => new SettingsIoError({ path: settingsPath, cause })));
+    return Option.some({ path: settingsPath, bytes });
+});
+const loadRawLockfileBytes = Effect.fn("workspace.read-model.state.lockfile.raw")(function* (deps) {
+    const { fs, lockfilePath } = deps;
+    const exists = yield* fs
+        .exists(lockfilePath)
+        .pipe(Effect.mapError((cause) => new LockfileIoError({ path: lockfilePath, cause })));
+    if (!exists)
+        return Option.none();
+    const bytes = yield* fs
+        .readFileString(lockfilePath)
+        .pipe(Effect.mapError((cause) => new LockfileIoError({ path: lockfilePath, cause })));
+    return Option.some({ path: lockfilePath, bytes });
+});
+// ---------------------------------------------------------------------------
+// Settings loader (decode pipeline) — sources bytes from the cached raw cell
+// ---------------------------------------------------------------------------
+/** Decode settings from cached raw bytes. Source-independent (Decision 2). */
+const loadSettings = (rawCell) => Effect.gen(function* () {
+    const rawOpt = yield* rawCell;
+    if (Option.isNone(rawOpt))
+        return Option.none();
+    const { path, bytes } = rawOpt.value;
+    const parsed = yield* Effect.try({
+        try: () => JSON.parse(bytes),
+        catch: (cause) => new SettingsParseError({ path, raw: bytes, cause }),
+    });
+    const decoded = yield* Schema.decodeUnknownEffect(SettingsSchema)(parsed, {
+        onExcessProperty: "error",
+    }).pipe(Effect.mapError((error) => {
+        return new SettingsDecodeError({
+            path,
+            issues: formatSchemaIssuesToLines(error.issue),
+            raw: parsed,
+        });
+    }));
+    return Option.some(decoded);
+}).pipe(Effect.withSpan("workspace.read-model.state.settings"));
+// ---------------------------------------------------------------------------
+// Lockfile loader (decode pipeline) — sources bytes from the cached raw cell
+// ---------------------------------------------------------------------------
+/** Decode lockfile from cached raw bytes. Source-independent (Decision 2). */
+const loadLockfile = (rawCell) => Effect.gen(function* () {
+    const rawOpt = yield* rawCell;
+    if (Option.isNone(rawOpt))
+        return Option.none();
+    const { path, bytes } = rawOpt.value;
+    const parsed = yield* Effect.try({
+        try: () => YAML.parse(bytes),
+        catch: (cause) => new LockfileParseError({ path, raw: bytes, cause }),
+    });
+    const decoded = yield* Schema.decodeUnknownEffect(LockfileSchema)(parsed).pipe(Effect.mapError((error) => new LockfileDecodeError({
+        path,
+        issues: formatSchemaIssuesToLines(error.issue),
+        raw: parsed,
+    })));
+    return Option.some(decoded);
+}).pipe(Effect.withSpan("workspace.read-model.state.lockfile"));
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Build the cached, requirement-free `ScopedStateLoaders` for one scope. */
+export const makeScopedStateApi = (_scope, deps) => Effect.gen(function* () {
+    const { fs, settingsPath, lockfilePath } = deps;
+    const settingsRaw = yield* Effect.cached(loadRawSettingsBytes({ fs, settingsPath }));
+    const settings = yield* Effect.cached(loadSettings(settingsRaw));
+    const lockfileRaw = lockfilePath === null
+        ? Effect.succeed(Option.none())
+        : yield* Effect.cached(loadRawLockfileBytes({ fs, lockfilePath }));
+    const lockfile = lockfilePath === null
+        ? Effect.succeed(Option.none())
+        : yield* Effect.cached(loadLockfile(lockfileRaw));
+    return { settings, lockfile, settingsRaw, lockfileRaw };
+});
+//# sourceMappingURL=state.js.map

package/dist/src/workspace/read-model/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared, non-circular type declarations for the WorkspaceReadModel capability.
+ *
+ * Subject modules under `extensions/` and `agents/` own their payload types;
+ * this file holds only subject-agnostic declarations referenced from multiple
+ * places (Scope, ExtensionKey, ActivationState, InstallationOrigin, the
+ * empty-shape ExtensionStateReader contract, and the public surface contracts
+ * for WorkspaceReadModel / ScopedStateApi / ScopedSourceHostsApi /
+ * ScopedOwnerApi / ScopedAgentsApi).
+ *
+ * Source-backed cell failure channels carry per-source tagged error unions
+ * imported from `errors.ts`: `SettingsReadError` for `declared` and
+ * `LockfileReadError` for `resolved`.
+ */
+import type * as Effect from "effect/Effect";
+import type * as Option from "effect/Option";
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { LockfileReadError, SettingsReadError } from "./errors.js";
+/**
+ * Workspace scope discriminator. Project state is read from the project root;
+ * user state is read from `.axm/workspace/` under the resolved user home.
+ */
+export type Scope = "project" | "user";
+/**
+ * Stable identity for an extension row across declared, resolved, actual, and
+ * projection cells. Subject modules reuse this shape for their projection rows.
+ */
+export interface ExtensionKey<TType extends ExtensionType = ExtensionType> {
+    readonly scope: Scope;
+    readonly type: TType;
+    readonly name: string;
+}
+/**
+ * Activation state on installed rows for subjects that support it.
+ *
+ * Subjects without a configurable activation flag use `enabled` by policy.
+ */
+export type ActivationState = "enabled" | "disabled";
+/**
+ * Why an installed row exists. Direct rows carry the declared entry; pack
+ * member rows carry the installed pack reference and the resolved member.
+ */
+export type InstallationOrigin<TDeclared, TPackMember> = {
+    readonly _tag: "direct";
+    readonly declared: TDeclared;
+} | {
+    readonly _tag: "pack-member";
+    readonly member: TPackMember;
+    readonly pack: InstalledPackRef;
+};
+/**
+ * Reference to an installed pack carried on pack-member installation origins.
+ *
+ * Subject modules that need pack-member rows narrow this further; phase 7
+ * defines the concrete shape on the pack subject module.
+ */
+export interface InstalledPackRef {
+    readonly key: ExtensionKey<"pack">;
+}
+/**
+ * Empty-shape contract for the three independent layers per subject. Each
+ * subject module instantiates this with its own payload types.
+ *
+ * The failure channels are intentionally narrow: `declared` only fails with
+ * `SettingsReadError` (3 tags), `resolved` only fails with
+ * `LockfileReadError` (3 tags), and `actual` never fails — workspace-root
+ * path-escape is validated once at provider construction (Layer-level), not
+ * per cell.
+ */
+export interface ExtensionStateReader<TDeclared, TResolved, TActual> {
+    readonly declared: Effect.Effect<Option.Option<TDeclared>, SettingsReadError>;
+    readonly resolved: Effect.Effect<Option.Option<TResolved>, LockfileReadError>;
+    readonly actual: Effect.Effect<TActual>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/workspace/read-model/types.js

@@ -0,0 +1,26 @@
+/**
+ * Shared, non-circular type declarations for the WorkspaceReadModel capability.
+ *
+ * Subject modules under `extensions/` and `agents/` own their payload types;
+ * this file holds only subject-agnostic declarations referenced from multiple
+ * places (Scope, ExtensionKey, ActivationState, InstallationOrigin, the
+ * empty-shape ExtensionStateReader contract, and the public surface contracts
+ * for WorkspaceReadModel / ScopedStateApi / ScopedSourceHostsApi /
+ * ScopedOwnerApi / ScopedAgentsApi).
+ *
+ * Source-backed cell failure channels carry per-source tagged error unions
+ * imported from `errors.ts`: `SettingsReadError` for `declared` and
+ * `LockfileReadError` for `resolved`.
+ */
+export {};
+// -----------------------------------------------------------------------------
+// Public scoped surfaces — concrete shapes live in `context.ts`
+// -----------------------------------------------------------------------------
+//
+// `service.ts` (Phase 9) defines the real `ScopedStateApi`,
+// `ScopedSourceHostsApi`, `ScopedOwnerApi`, and `WorkspaceReadModel`
+// surfaces. They attach payload types from per-subject modules under
+// `extensions/` and per-agent modules under `agents/`, which would create
+// import cycles if defined here. `ScopedAgentsApi` is owned by
+// `agents/index.ts` for the same reason.
+//# sourceMappingURL=types.js.map

package/dist/src/workspace/read-model-record-readers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Read-model record readers.
+ *
+ * Centralizes read-model record projection over `WorkspaceReadModel` subject
+ * rows.
+ */
+import * as Effect from "effect/Effect";
+import type * as Path from "effect/Path";
+import { type InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import type { WorkspaceStateReadFailure } from "./service-interface.js";
+import type { DesiredStateGraph } from "./desired-state-graph.js";
+import type { LockfileReadError, SettingsReadError } from "./read-model/errors.js";
+import { type ExtensionInventory } from "./read-model/extensions/inventory.js";
+import type { WorkspaceReadModel } from "./read-model/service.js";
+import type { ReadModelRecordRow } from "./read-model-record-types.js";
+type WorkspaceManagedExtensionType = InstallableExtensionType;
+type ReadScopedContext = <A>(f: (scoped: WorkspaceReadModel) => Effect.Effect<A, SettingsReadError | LockfileReadError>) => Effect.Effect<A, WorkspaceStateReadFailure>;
+export interface ReadModelRecordReaders {
+    readonly getInventory: (options: {
+        readonly type?: InstallableExtensionType;
+    }) => Effect.Effect<ExtensionInventory, WorkspaceStateReadFailure>;
+    readonly getReadModelRecordRows: (type: WorkspaceManagedExtensionType) => Effect.Effect<ReadonlyArray<ReadModelRecordRow>, WorkspaceStateReadFailure>;
+    readonly getExtensionInventory: (type: WorkspaceManagedExtensionType, options: {
+        readonly agents?: ReadonlyArray<string>;
+    }) => Effect.Effect<ExtensionInventory, WorkspaceStateReadFailure>;
+}
+export declare const makeReadModelRecordReaders: (args: {
+    readonly baseDir: string;
+    readonly path: Path.Path;
+    readonly readScopedContext: ReadScopedContext;
+    readonly getDesiredStateGraph: () => Effect.Effect<DesiredStateGraph, WorkspaceStateReadFailure>;
+}) => ReadModelRecordReaders;
+export {};
+//# sourceMappingURL=read-model-record-readers.d.ts.map