@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/materialized-tree.js

@@ -0,0 +1,90 @@
+import * as crypto from "node:crypto";
+import * as Data from "effect/Data";
+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 Schema from "effect/Schema";
+const TREE_INTEGRITY_PREFIX = "sha256-tree-v1:";
+export const TreeIntegritySchema = Schema.String.pipe(Schema.check(Schema.makeFilter((value) => /^sha256-tree-v1:[0-9a-f]{64}$/u.test(value)
+    ? undefined
+    : "Expected a sha256-tree-v1 materialized-tree digest")), Schema.brand("TreeIntegrity")).annotate({
+    identifier: "TreeIntegrity",
+    description: "Strict SHA-256 integrity of regular-file paths and bytes using AXM materialized-tree framing v1.",
+});
+const decodeTreeIntegrity = Schema.decodeUnknownSync(TreeIntegritySchema);
+/**
+ * A materialized package tree failed strict integrity walking: unreadable,
+ * unsafe, colliding, or unsupported entries. `reason` carries the walk's fact
+ * sentence.
+ */
+export class MaterializedTreeInvalid extends Data.TaggedError("MaterializedTreeInvalid") {
+}
+const treeError = (root, reason, cause) => new MaterializedTreeInvalid({ root, reason, ...(cause === undefined ? {} : { cause }) });
+const frame = (hash, bytes) => {
+    const length = Buffer.alloc(8);
+    length.writeBigUInt64BE(BigInt(bytes.byteLength));
+    hash.update(length);
+    hash.update(bytes);
+};
+export const computeMaterializedTreeIntegrity = (root) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const files = [];
+    const caseFoldedPaths = new Map();
+    const walk = (directory, relativeDirectory) => Effect.gen(function* () {
+        const entries = yield* fs
+            .readDirectory(directory)
+            .pipe(Effect.mapError((cause) => treeError(root, `cannot read ${relativeDirectory || "."}`, cause)));
+        const ordered = [...entries].sort((left, right) => left.localeCompare(right, "en"));
+        for (const entry of ordered) {
+            if (entry.length === 0 ||
+                entry === "." ||
+                entry === ".." ||
+                entry.includes("/") ||
+                entry.includes("\\")) {
+                return yield* treeError(root, `unsafe path segment ${JSON.stringify(entry)}`);
+            }
+            const relativePath = relativeDirectory.length === 0 ? entry : `${relativeDirectory}/${entry}`;
+            if (relativePath.startsWith("/") || relativePath.split("/").includes("..")) {
+                return yield* treeError(root, `unsafe relative path ${JSON.stringify(relativePath)}`);
+            }
+            const folded = relativePath.normalize("NFC").toLocaleLowerCase("en-US");
+            const colliding = caseFoldedPaths.get(folded);
+            if (colliding !== undefined && colliding !== relativePath) {
+                return yield* treeError(root, `case-fold collision between ${JSON.stringify(colliding)} and ${JSON.stringify(relativePath)}`);
+            }
+            caseFoldedPaths.set(folded, relativePath);
+            const absolutePath = path.join(directory, entry);
+            const link = yield* fs.readLink(absolutePath).pipe(Effect.option);
+            if (Option.isSome(link)) {
+                return yield* treeError(root, `symlink is not allowed: ${relativePath}`);
+            }
+            const info = yield* fs
+                .stat(absolutePath)
+                .pipe(Effect.mapError((cause) => treeError(root, `cannot inspect ${relativePath}`, cause)));
+            if (info.type === "Directory") {
+                yield* walk(absolutePath, relativePath);
+            }
+            else if (info.type === "File") {
+                files.push({ relativePath, absolutePath });
+            }
+            else {
+                return yield* treeError(root, `unsupported filesystem entry: ${relativePath}`);
+            }
+        }
+    });
+    yield* walk(root, "");
+    files.sort((left, right) => left.relativePath.localeCompare(right.relativePath, "en"));
+    const hash = crypto.createHash("sha256");
+    frame(hash, Buffer.from("agentxm-materialized-tree"));
+    frame(hash, Buffer.from("1"));
+    for (const file of files) {
+        frame(hash, Buffer.from(file.relativePath, "utf8"));
+        frame(hash, yield* fs
+            .readFile(file.absolutePath)
+            .pipe(Effect.mapError((cause) => treeError(root, `cannot read ${file.relativePath}`, cause))));
+    }
+    return decodeTreeIntegrity(`${TREE_INTEGRITY_PREFIX}${hash.digest("hex")}`);
+});
+//# sourceMappingURL=materialized-tree.js.map

package/dist/src/workspace/mcp-entry-semantics.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Settings-semantics predicates for MCP server entries.
+ *
+ * Pure derivations over workspace-owned MCP entry shapes: per-agent targeting
+ * of a configured settings entry, and AXM ownership/provenance metadata
+ * embedded in agent-native MCP config entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import type { McpServerEntry } from "../settings/schema.js";
+export declare const isMcpServerApplicableToAgent: (entry: McpServerEntry, agentId: string) => boolean;
+export declare const AXM_MCP_METADATA_KEY = "x-axm";
+export declare const AxmMcpMetadataSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly v: Schema.Literal<1>;
+    readonly managed: Schema.Literal<true>;
+    readonly ext: Schema.NonEmptyString;
+    readonly source: Schema.Literal<"inline">;
+}>, Schema.Struct<{
+    readonly v: Schema.Literal<1>;
+    readonly managed: Schema.Literal<true>;
+    readonly ext: Schema.NonEmptyString;
+    readonly source: Schema.Literals<readonly ["github", "gitlab", "bitbucket", "azurerepos", "git", "registry", "local", "workspace"]>;
+    readonly ref: Schema.NonEmptyString;
+}>]>;
+export type AxmMcpMetadata = typeof AxmMcpMetadataSchema.Type;
+export declare const readAxmMcpMetadata: (entry: Readonly<Record<string, unknown>>) => Option.Option<AxmMcpMetadata>;
+export declare const isAxmManagedMcpEntry: (entry: Readonly<Record<string, unknown>>) => boolean;
+//# sourceMappingURL=mcp-entry-semantics.d.ts.map

package/dist/src/workspace/mcp-entry-semantics.js

@@ -0,0 +1,60 @@
+/**
+ * Settings-semantics predicates for MCP server entries.
+ *
+ * Pure derivations over workspace-owned MCP entry shapes: per-agent targeting
+ * of a configured settings entry, and AXM ownership/provenance metadata
+ * embedded in agent-native MCP config entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+export const isMcpServerApplicableToAgent = (entry, agentId) => entry.agents === undefined || entry.agents.some((candidate) => candidate === agentId);
+export const AXM_MCP_METADATA_KEY = "x-axm";
+const ResolvableSourceTypeSchema = Schema.Literals([
+    "github",
+    "gitlab",
+    "bitbucket",
+    "azurerepos",
+    "git",
+    "registry",
+    "local",
+    "workspace",
+]);
+export const AxmMcpMetadataSchema = Schema.Union([
+    Schema.Struct({
+        v: Schema.Literal(1),
+        managed: Schema.Literal(true),
+        ext: Schema.NonEmptyString,
+        source: Schema.Literal("inline"),
+    }),
+    Schema.Struct({
+        v: Schema.Literal(1),
+        managed: Schema.Literal(true),
+        ext: Schema.NonEmptyString,
+        source: ResolvableSourceTypeSchema,
+        ref: Schema.NonEmptyString,
+    }),
+]).annotate({
+    identifier: "AxmMcpMetadata",
+    title: "AXM MCP Metadata",
+    description: "AXM ownership and provenance metadata for an agent MCP config entry.",
+});
+const decodeMetadataOption = Schema.decodeUnknownOption(AxmMcpMetadataSchema);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasValidRefShape = (metadata) => {
+    const source = metadata["source"];
+    const ref = metadata["ref"];
+    if (source === "inline")
+        return ref === undefined;
+    return typeof ref === "string" && ref.length > 0;
+};
+export const readAxmMcpMetadata = (entry) => {
+    const metadata = entry[AXM_MCP_METADATA_KEY];
+    if (!isRecord(metadata) || !hasValidRefShape(metadata))
+        return Option.none();
+    return decodeMetadataOption(metadata);
+};
+export const isAxmManagedMcpEntry = (entry) => Option.isSome(readAxmMcpMetadata(entry));
+//# sourceMappingURL=mcp-entry-semantics.js.map

package/dist/src/workspace/observed-installed.d.ts

@@ -0,0 +1,9 @@
+import * as Effect from "effect/Effect";
+import type { InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import type { WorkspaceMutationsService, WorkspaceStateReadFailure } from "./service-interface.js";
+/**
+ * Determine installation from the observable workspace inventory. Lock
+ * presence is intentionally irrelevant.
+ */
+export declare const isObservedInstalled: (workspace: WorkspaceMutationsService, type: InstallableExtensionType, name: string) => Effect.Effect<boolean, WorkspaceStateReadFailure>;
+//# sourceMappingURL=observed-installed.d.ts.map

package/dist/src/workspace/observed-installed.js

@@ -0,0 +1,9 @@
+import * as Effect from "effect/Effect";
+/**
+ * Determine installation from the observable workspace inventory. Lock
+ * presence is intentionally irrelevant.
+ */
+export const isObservedInstalled = (workspace, type, name) => workspace.records
+    .getExtensionInventory(type, {})
+    .pipe(Effect.map((inventory) => inventory.items.some((item) => item.name === name && item.installed)));
+//# sourceMappingURL=observed-installed.js.map

package/dist/src/workspace/pack-manifest-content-identity.d.ts

@@ -0,0 +1,12 @@
+import { type SourceHash } from "@agentxm/extension-model/unstable/sources/source-hash";
+interface PackManifestIdentityInput {
+    readonly owner: string;
+    readonly type: "pack";
+    readonly name: string;
+    readonly version: string;
+    readonly dependencies: Readonly<Record<string, string>>;
+}
+/** Identity of the decoded Pack manifest semantics used to authorize reachability. */
+export declare const computePackManifestContentIdentity: (manifest: PackManifestIdentityInput) => SourceHash;
+export {};
+//# sourceMappingURL=pack-manifest-content-identity.d.ts.map

package/dist/src/workspace/pack-manifest-content-identity.js

@@ -0,0 +1,20 @@
+import { computeSourceHash } from "./rendered-files.js";
+import {} from "@agentxm/extension-model/unstable/sources/source-hash";
+const normalize = (value) => {
+    if (Array.isArray(value))
+        return value.map(normalize);
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, normalize(entry)]));
+};
+/** Identity of the decoded Pack manifest semantics used to authorize reachability. */
+export const computePackManifestContentIdentity = (manifest) => computeSourceHash(JSON.stringify(normalize({
+    owner: manifest.owner,
+    type: manifest.type,
+    name: manifest.name,
+    version: manifest.version,
+    dependencies: manifest.dependencies,
+})));
+//# sourceMappingURL=pack-manifest-content-identity.js.map

package/dist/src/workspace/pack-paths.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Centralized pack path computation.
+ *
+ * Provides types and a pure function for computing pack directory paths.
+ * Packs are either workspace-authored or Registry-sourced. Acquired packs
+ * retain the exact Registry source name in their canonical path.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { type AbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import type { WorkspaceLayout } from "./layout.js";
+/**
+ * Computed path for an installed pack directory.
+ *
+ * `canonicalPath` = `<base>/agent_extensions/<source-name>/<owner>/packs/<name>/`
+ *
+ * No `src/` subdirectory for packs.
+ */
+export interface PackDirPath {
+    readonly canonicalPath: AbsolutePath;
+}
+export declare const computePackPathsForLayout: (join: (...paths: string[]) => string, layout: WorkspaceLayout, sourceName: "workspace" | string, owner: Handle, name: string) => PackDirPath;
+//# sourceMappingURL=pack-paths.d.ts.map

package/dist/src/workspace/pack-paths.js

@@ -0,0 +1,16 @@
+/**
+ * Centralized pack path computation.
+ *
+ * Provides types and a pure function for computing pack directory paths.
+ * Packs are either workspace-authored or Registry-sourced. Acquired packs
+ * retain the exact Registry source name in their canonical path.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { decodeAbsolutePathSync, } from "@agentxm/extension-model/unstable/path-types";
+export const computePackPathsForLayout = (join, layout, sourceName, owner, name) => ({
+    canonicalPath: layout.scope === "project" && sourceName === "workspace"
+        ? decodeAbsolutePathSync(join(layout.authoredRoot("pack"), name))
+        : decodeAbsolutePathSync(join(layout.acquiredRoot, sourceName, owner, "packs", name)),
+});
+//# sourceMappingURL=pack-paths.js.map

package/dist/src/workspace/package-hash.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Content hashing for installed extension packages.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { PackageContentHashFailed } from "./errors.js";
+import type { SourceHash } from "@agentxm/extension-model/unstable/sources/source-hash";
+/**
+ * Compute an advisory SHA-256 change marker over package content recursively.
+ *
+ * File order is normalized by sorting on relative path, and each entry
+ * contributes its path and bytes separated by NUL so that a rename cannot
+ * collide with a content change.
+ *
+ * The result is a change-detection marker for created/updated/unchanged
+ * reporting, never a tamper seal — installed content is workspace-owned and
+ * may be rewritten by content-preserving tools after install.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const computePackageContentHash: (packageDir: string) => Effect.Effect<SourceHash, PackageContentHashFailed, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=package-hash.d.ts.map

package/dist/src/workspace/package-hash.js

@@ -0,0 +1,45 @@
+/**
+ * Content hashing for installed extension packages.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as crypto from "node:crypto";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { PackageContentHashFailed } from "./errors.js";
+import { computeSourceHash } from "./rendered-files.js";
+/**
+ * Compute an advisory SHA-256 change marker over package content recursively.
+ *
+ * File order is normalized by sorting on relative path, and each entry
+ * contributes its path and bytes separated by NUL so that a rename cannot
+ * collide with a content change.
+ *
+ * The result is a change-detection marker for created/updated/unchanged
+ * reporting, never a tamper seal — installed content is workspace-owned and
+ * may be rewritten by content-preserving tools after install.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const computePackageContentHash = (packageDir) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const rawEntries = yield* fs.readDirectory(packageDir, { recursive: true });
+    const candidates = yield* Effect.forEach(rawEntries, (relativePath) => Effect.gen(function* () {
+        const absolutePath = path.join(packageDir, relativePath);
+        const info = yield* fs.stat(absolutePath);
+        return { relativePath, absolutePath, isFile: info.type === "File" };
+    }), { concurrency: 16 });
+    const files = candidates.filter((candidate) => candidate.isFile);
+    files.sort((left, right) => left.relativePath < right.relativePath ? -1 : left.relativePath > right.relativePath ? 1 : 0);
+    const hash = crypto.createHash("sha256");
+    for (const file of files) {
+        hash.update(file.relativePath);
+        hash.update("\0");
+        hash.update(yield* fs.readFile(file.absolutePath));
+        hash.update("\0");
+    }
+    return computeSourceHash(hash.digest("hex"));
+}).pipe(Effect.mapError((cause) => new PackageContentHashFailed({ packageDir, cause })));
+//# sourceMappingURL=package-hash.js.map

package/dist/src/workspace/paths.d.ts

@@ -0,0 +1,24 @@
+/** AXM application-home and workspace path resolution. */
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { type AbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+export { AXM_DIR_NAME, USER_WORKSPACE_DIRECTORY } from "./constants.js";
+export interface WorkspaceLocation {
+    readonly scope: WorkspaceScope;
+    readonly path: AbsolutePath;
+    readonly baseDir: AbsolutePath;
+    readonly workspaceRoot: AbsolutePath;
+    readonly settingsPath: AbsolutePath;
+    readonly lockPath: AbsolutePath;
+    readonly acquiredRoot: AbsolutePath;
+}
+export declare const resolveUserHomePure: (configuredHome: string | undefined) => string;
+export declare const resolveUserAxmHomePure: (pathJoin: (...segments: ReadonlyArray<string>) => string, homeDir: string) => string;
+export declare const resolveUserWorkspaceRootPure: (pathJoin: (...segments: ReadonlyArray<string>) => string, homeDir: string) => string;
+export declare const resolveUserHome: () => Effect.Effect<AbsolutePath, never, Path.Path>;
+export declare const resolveUserAxmHome: () => Effect.Effect<AbsolutePath, never, Path.Path>;
+export declare const resolveUserWorkspaceRoot: () => Effect.Effect<AbsolutePath, never, Path.Path>;
+export declare const getProjectRuntimeDir: (projectRoot: AbsolutePath) => Effect.Effect<AbsolutePath, never, Path.Path>;
+export declare const locateWorkspace: (scope: WorkspaceScope, projectRoot: AbsolutePath) => Effect.Effect<WorkspaceLocation, never, Path.Path>;
+//# sourceMappingURL=paths.d.ts.map

package/dist/src/workspace/paths.js

@@ -0,0 +1,52 @@
+/** AXM application-home and workspace path resolution. */
+import * as os from "node:os";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { ACQUIRED_EXTENSIONS_DIR, AXM_DIR_NAME, LOCK_FILENAME, USER_WORKSPACE_DIRECTORY, } from "./constants.js";
+import { makeAbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import { SETTINGS_FILENAME } from "@agentxm/extension-model/unstable/workspace-files";
+export { AXM_DIR_NAME, USER_WORKSPACE_DIRECTORY } from "./constants.js";
+const axmUserHomeConfig = Config.option(Config.string("AXM_USER_HOME"));
+export const resolveUserHomePure = (configuredHome) => configuredHome ?? os.homedir();
+export const resolveUserAxmHomePure = (pathJoin, homeDir) => pathJoin(homeDir, AXM_DIR_NAME);
+export const resolveUserWorkspaceRootPure = (pathJoin, homeDir) => pathJoin(resolveUserAxmHomePure(pathJoin, homeDir), USER_WORKSPACE_DIRECTORY);
+export const resolveUserHome = () => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    // eslint-disable-next-line no-restricted-syntax -- Optional string decoding is total, so failure means the Config provider violated its contract.
+    const configuredHome = yield* Effect.orDie(axmUserHomeConfig);
+    return makeAbsolutePath(path, resolveUserHomePure(Option.getOrUndefined(configuredHome)));
+});
+export const resolveUserAxmHome = () => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const home = yield* resolveUserHome();
+    return makeAbsolutePath(path, resolveUserAxmHomePure(path.join, home));
+});
+export const resolveUserWorkspaceRoot = () => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const home = yield* resolveUserHome();
+    return makeAbsolutePath(path, resolveUserWorkspaceRootPure(path.join, home));
+});
+export const getProjectRuntimeDir = (projectRoot) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    return makeAbsolutePath(path, path.join(projectRoot, AXM_DIR_NAME));
+});
+export const locateWorkspace = (scope, projectRoot) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const baseDir = scope === "user" ? yield* resolveUserHome() : projectRoot;
+    const workspaceRoot = scope === "user"
+        ? makeAbsolutePath(path, resolveUserWorkspaceRootPure(path.join, baseDir))
+        : projectRoot;
+    const runtimeDir = makeAbsolutePath(path, path.join(workspaceRoot, AXM_DIR_NAME));
+    return {
+        scope,
+        path: runtimeDir,
+        baseDir,
+        workspaceRoot,
+        settingsPath: makeAbsolutePath(path, path.join(workspaceRoot, SETTINGS_FILENAME)),
+        lockPath: makeAbsolutePath(path, path.join(workspaceRoot, LOCK_FILENAME)),
+        acquiredRoot: makeAbsolutePath(path, path.join(workspaceRoot, ACQUIRED_EXTENSIONS_DIR)),
+    };
+});
+//# sourceMappingURL=paths.js.map

package/dist/src/workspace/read-model/__fixtures__/builder.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Fixture builder: synthesizes minimal workspace trees from declarative specs
+ * against an in-memory `FileSystem` for tests.
+ *
+ * Phase 5 of the workspace read-model change. Downstream phases (scanners,
+ * per-extension subject modules, the live `WorkspaceReadModel` service, and
+ * golden-fixture scenario tests) call `buildFixture(spec)` to materialize a
+ * minimal directory tree; named scenario constructors below provide the
+ * canonical specs for the spec scenarios listed in `proposal.md`.
+ *
+ * Key design choices:
+ *
+ * - The builder operates on a self-contained in-memory `Map<string, string>`
+ *   filesystem, exposed through `FileSystem.makeNoop`. No `node:fs` is used.
+ *   Tests get deterministic, ordered file sets without touching disk.
+ * - Path-escape attempts (entries containing `..` segments or absolute paths)
+ *   fail the builder with `PathEscapeError`. This makes the upcoming
+ *   Phase 9 `WorkspaceRootEscape` test a separate, deliberate scenario and
+ *   eliminates the chance of a leaky test fixture corrupting the host fs.
+ * - Settings and lockfile files are serialized through `JSON.stringify` and
+ *   `YAML.stringify` respectively when their `_tag === "valid"`. For
+ *   `byteCorrupt`, the literal bytes are written verbatim. For
+ *   `schemaInvalid`, the JSON/YAML serialization of the spec object is
+ *   written so the parser accepts it but the schema decoder rejects it.
+ * - The builder NEVER constructs the live `WorkspaceReadModel` itself. The
+ *   sibling `test-layer.ts` exposes a `WorkspaceReadModelTest` layer that
+ *   composes the builder output with the real (Phase 9) Live layer; in
+ *   Phase 5 it falls back to a `Layer.fail` placeholder.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { Settings } from "../../../settings/schema.js";
+/**
+ * A file-spec describes one workspace file. The four tags express the four
+ * source-cell states that WorkspaceReadModel source loaders distinguish:
+ * absent, valid (parses + decodes), byte-corrupt (parser rejects), and
+ * schema-invalid (parser accepts but decoder rejects).
+ */
+export type FileSpec = {
+    readonly _tag: "absent";
+} | {
+    readonly _tag: "valid";
+    /**
+     * Object content for files with a known structure (axm.json,
+     * lockfile, .mcp.json). The builder serializes through `JSON.stringify`
+     * for JSON files and `YAML.stringify` for YAML files. Pass a string
+     * literal to bypass serialization.
+     */
+    readonly contents: object | string;
+} | {
+    readonly _tag: "byteCorrupt";
+    readonly bytes: string;
+} | {
+    readonly _tag: "schemaInvalid";
+    /**
+     * Object content that serializes cleanly as JSON/YAML but fails the
+     * relevant Schema decoder. The builder writes the serialized form so
+     * `JSON.parse` / `YAML.parse` succeed.
+     */
+    readonly contents: object;
+};
+/**
+ * A tree of files. Keys are workspace-relative paths (no leading slash, no
+ * `..` segments). Values are either the file's contents as a string (for
+ * inline content) or a `FileSpec` discriminator (for absent/byte-corrupt/
+ * schema-invalid).
+ */
+export type TreeFiles = Readonly<Record<string, string | FileSpec>>;
+/**
+ * Per-scope file specs. `settings` and `lockfile` are scoped settings/lockfile
+ * files. `axmExtensions` synthesizes contents under the scope's
+ * `agent_extensions/` directory.
+ * `agentDirs` synthesizes per-agent rendered directories. `mcpJson` writes
+ * `.mcp.json` at the workspace/user root. `agentSettings` writes per-agent
+ * native settings files (e.g. `.claude/settings.json`).
+ */
+export interface ScopeFiles {
+    readonly settings?: FileSpec;
+    readonly lockfile?: FileSpec;
+    readonly axmExtensions?: TreeFiles;
+    readonly agentDirs?: Readonly<Record<string, TreeFiles>>;
+    readonly mcpJson?: FileSpec;
+    readonly agentSettings?: Readonly<Record<string, FileSpec>>;
+}
+/**
+ * Top-level fixture spec. `workspaceRoot` is the project root; `userHome` is
+ * the user-scope home directory (workspace state lives at
+ * `${userHome}/.axm/workspace/`).
+ */
+export interface FixtureSpec {
+    readonly workspaceRoot: string;
+    readonly userHome: string;
+    readonly project?: ScopeFiles;
+    readonly user?: ScopeFiles;
+}
+/**
+ * Test deps returned from `buildFixture(spec)`. Downstream layers consume
+ * `fs` and `path` to satisfy the `FileSystem` and `Path` services. `files`
+ * exposes the raw map for diagnostic snapshots (test-only).
+ */
+export interface FixtureTestDeps {
+    readonly fs: FileSystem.FileSystem;
+    readonly path: Path.Path;
+    readonly files: ReadonlyMap<string, string>;
+    readonly workspaceRoot: string;
+    readonly userHome: string;
+}
+export declare const resolveFixtureProjectLayout: (deps: FixtureTestDeps, settings?: Settings) => Effect.Effect<import("../../layout.js").ProjectWorkspaceLayout, import("../../errors.ts").WorkspaceLayoutError, never>;
+export declare const resolveFixtureUserLayout: (deps: FixtureTestDeps, settings?: Settings) => Effect.Effect<import("../../layout.js").UserWorkspaceLayout, never, never>;
+declare const PathEscapeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PathEscapeError";
+} & Readonly<A>;
+/**
+ * Builder rejected an entry because the spec asked to write outside the
+ * workspace/user-home root. Phase 9's `WorkspaceRootEscape` is a different
+ * (Layer-level) error; this one is purely a fixture sanity check so tests
+ * cannot accidentally clobber files outside the intended tree.
+ */
+export declare class PathEscapeError extends PathEscapeError_base<{
+    readonly path: string;
+    readonly reason: string;
+}> {
+}
+/**
+ * Build a fixture against an in-memory FileSystem.
+ *
+ * The returned `FixtureTestDeps` value is a stable, dependency-closed value:
+ * it carries the synthesized `FileSystem`, a `Path.Path` value, and the
+ * raw file map. Downstream test layers compose these with the real Live
+ * implementations.
+ *
+ * Failures: the builder fails with `PathEscapeError` when any tree entry
+ * contains a `..` segment or an absolute path. Phase 9's
+ * `WorkspaceRootEscape` is a different (Layer-construction) failure.
+ */
+export declare const buildFixture: (spec: FixtureSpec) => Effect.Effect<FixtureTestDeps, PathEscapeError>;
+/**
+ * No source files materialize. Both scopes return absent for every cell.
+ */
+export declare const absentAll: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Both project sources present and decodable; user scope settings present.
+ */
+export declare const validAll: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Settings is valid; the lockfile is byte-corrupt.
+ */
+export declare const lockfileInvalidOnly: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Lockfile is valid; settings is byte-corrupt.
+ */
+export declare const settingsInvalidOnly: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Both project sources are byte-corrupt.
+ */
+export declare const bothInvalid: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Project state present; user scope absent.
+ */
+export declare const projectOnly: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * User scope settings present; project state absent.
+ */
+export declare const userOnly: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Both scopes declare a source-host with the same name. Phase 9 verifies that
+ * the WorkspaceReadModel exposes both scope reads independently and does not
+ * implicitly merge them.
+ */
+export declare const projectUserShadowing: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Agent dir exists on disk but settings does not declare the agent. Phase 9
+ * verifies the `agents.detected` projection surfaces a mismatch.
+ */
+export declare const agentPresentNoDeclaration: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Settings declares an agent whose directory does not exist.
+ */
+export declare const agentDeclaredNotInstalled: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Settings disagrees with `.mcp.json`: the keys differ between the two
+ * surfaces. Phase 9 verifies the MCP-server projection exposes both views
+ * without silently reconciling them.
+ */
+export declare const mcpConfigDrift: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Same skill name across agent skill dirs (`.claude/skills/`, `.agents/skills/`)
+ * and canonical AXM storage.
+ */
+export declare const sameNameAcrossOrigins: (workspaceRoot: string, userHome: string) => FixtureSpec;
+/**
+ * Spec containing a `..` segment so callers can verify the builder rejects it.
+ * The fixture intentionally returns an unbuildable spec; consumers invoke
+ * `buildFixture` to assert the rejection path.
+ */
+export declare const pathEscapeAttempt: (workspaceRoot: string, userHome: string) => FixtureSpec;
+export {};
+//# sourceMappingURL=builder.d.ts.map