@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/read-model/__fixtures__/builder.js

@@ -0,0 +1,588 @@
+/**
+ * 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 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 PlatformError from "effect/PlatformError";
+import YAML from "yaml";
+import { AGENTS } from "@agentxm/extension-model/unstable/agents/registry";
+import { makeAbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import { resolveProjectWorkspaceLayout, resolveUserWorkspaceLayout } from "../../layout.js";
+export const resolveFixtureProjectLayout = (deps, settings = {}) => resolveProjectWorkspaceLayout(makeAbsolutePath(deps.path, deps.workspaceRoot), settings).pipe(Effect.provideService(FileSystem.FileSystem, deps.fs), Effect.provideService(Path.Path, deps.path));
+export const resolveFixtureUserLayout = (deps, settings = {}) => resolveUserWorkspaceLayout(makeAbsolutePath(deps.path, deps.userHome), settings).pipe(Effect.provideService(Path.Path, deps.path));
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+/**
+ * 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 class PathEscapeError extends Data.TaggedError("PathEscapeError") {
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const isObject = (value) => typeof value === "object" && value !== null;
+const stringifyJson = (value) => typeof value === "string" ? value : JSON.stringify(value);
+const stringifyYaml = (value) => typeof value === "string" ? value : YAML.stringify(value);
+const validateRelativePath = (relative, owner) => Effect.suspend(() => {
+    if (relative.length === 0) {
+        return Effect.fail(new PathEscapeError({
+            path: relative,
+            reason: `${owner} entry path is empty`,
+        }));
+    }
+    if (relative.startsWith("/")) {
+        return Effect.fail(new PathEscapeError({
+            path: relative,
+            reason: `${owner} entry must be a workspace-relative path; absolute paths are rejected`,
+        }));
+    }
+    const segments = relative.split("/");
+    for (const segment of segments) {
+        if (segment === "..") {
+            return Effect.fail(new PathEscapeError({
+                path: relative,
+                reason: `${owner} entry contains a ".." segment, which would escape the synthesized root`,
+            }));
+        }
+    }
+    return Effect.void;
+});
+/**
+ * Resolve an agent's content root directory (e.g., `.claude` for `claude-code`).
+ *
+ * The agent registry exposes per-subject directories like `.claude/skills`;
+ * the builder writes the entire `agentDirs[agentId]` tree under the agent's
+ * root, which is the first segment of any of those paths. If the agent is
+ * not registered, the builder falls back to `.<agentId>` so callers can
+ * still synthesize directories for hypothetical agents.
+ */
+const resolveAgentContentRoot = (agentId) => {
+    const isKnown = (id) => Object.hasOwn(AGENTS, id);
+    if (!isKnown(agentId))
+        return `.${agentId}`;
+    const descriptor = AGENTS[agentId];
+    const skillsDir = descriptor.skills?.dir;
+    if (skillsDir === undefined)
+        return descriptor.rootDir ?? `.${agentId}`;
+    const firstSegment = skillsDir.split("/")[0];
+    return firstSegment !== undefined && firstSegment.length > 0 ? firstSegment : `.${agentId}`;
+};
+const resolveAgentSettingsRoot = (agentId) => {
+    const isKnown = (id) => Object.hasOwn(AGENTS, id);
+    if (!isKnown(agentId))
+        return `.${agentId}`;
+    const descriptor = AGENTS[agentId];
+    if (typeof descriptor.rootDir === "string")
+        return descriptor.rootDir;
+    return resolveAgentContentRoot(agentId);
+};
+const join = (...parts) => {
+    const normalized = [];
+    for (const p of parts) {
+        if (p.length === 0)
+            continue;
+        if (p === "/") {
+            normalized.push("");
+            continue;
+        }
+        normalized.push(p.endsWith("/") ? p.slice(0, -1) : p);
+    }
+    return normalized.join("/");
+};
+// ---------------------------------------------------------------------------
+// In-memory FileSystem
+// ---------------------------------------------------------------------------
+const notFound = (method, path) => PlatformError.systemError({
+    _tag: "NotFound",
+    module: "FileSystem",
+    method,
+    description: "No such file or directory",
+    pathOrDescriptor: path,
+});
+const makeInMemoryFs = (files) => {
+    const directorySet = new Set();
+    const encoder = new TextEncoder();
+    for (const filePath of files.keys()) {
+        const segments = filePath.split("/");
+        for (let i = 1; i < segments.length; i += 1) {
+            const dir = segments.slice(0, i).join("/");
+            if (dir.length > 0)
+                directorySet.add(dir);
+        }
+    }
+    return FileSystem.makeNoop({
+        exists: (path) => Effect.sync(() => {
+            if (files.has(path))
+                return true;
+            if (directorySet.has(path))
+                return true;
+            return false;
+        }),
+        readFileString: (path) => {
+            const value = files.get(path);
+            if (value === undefined) {
+                return Effect.fail(notFound("readFileString", path));
+            }
+            return Effect.succeed(value);
+        },
+        readFile: (path) => {
+            const value = files.get(path);
+            if (value === undefined) {
+                return Effect.fail(notFound("readFile", path));
+            }
+            return Effect.succeed(encoder.encode(value));
+        },
+        readDirectory: (path) => {
+            if (!directorySet.has(path)) {
+                return Effect.fail(notFound("readDirectory", path));
+            }
+            const prefix = path.endsWith("/") ? path : `${path}/`;
+            const entries = new Set();
+            for (const filePath of files.keys()) {
+                if (!filePath.startsWith(prefix))
+                    continue;
+                const remainder = filePath.slice(prefix.length);
+                const head = remainder.split("/")[0];
+                if (head !== undefined && head.length > 0)
+                    entries.add(head);
+            }
+            for (const dir of directorySet) {
+                if (!dir.startsWith(prefix))
+                    continue;
+                const remainder = dir.slice(prefix.length);
+                const head = remainder.split("/")[0];
+                if (head !== undefined && head.length > 0)
+                    entries.add(head);
+            }
+            return Effect.succeed(Array.from(entries).sort());
+        },
+        // Minimal `stat` for callers that probe entry kind. Returns `File` for a
+        // path tracked in the files map, `Directory` for a synthesized directory,
+        // and fails with NotFound otherwise. Only `type` is meaningful — the
+        // remaining fields keep the `FileSystem.File.Info` shape happy.
+        stat: (path) => {
+            if (files.has(path)) {
+                return Effect.succeed({
+                    type: "File",
+                    mtime: Option.none(),
+                    atime: Option.none(),
+                    birthtime: Option.none(),
+                    dev: 0,
+                    ino: Option.none(),
+                    mode: 0,
+                    nlink: Option.none(),
+                    uid: Option.none(),
+                    gid: Option.none(),
+                    rdev: Option.none(),
+                    size: FileSystem.Size(0),
+                    blksize: Option.none(),
+                    blocks: Option.none(),
+                });
+            }
+            if (directorySet.has(path)) {
+                return Effect.succeed({
+                    type: "Directory",
+                    mtime: Option.none(),
+                    atime: Option.none(),
+                    birthtime: Option.none(),
+                    dev: 0,
+                    ino: Option.none(),
+                    mode: 0,
+                    nlink: Option.none(),
+                    uid: Option.none(),
+                    gid: Option.none(),
+                    rdev: Option.none(),
+                    size: FileSystem.Size(0),
+                    blksize: Option.none(),
+                    blocks: Option.none(),
+                });
+            }
+            return Effect.fail(notFound("stat", path));
+        },
+    });
+};
+// ---------------------------------------------------------------------------
+// Spec → file map
+// ---------------------------------------------------------------------------
+const writeFileSpec = (files, absolutePath, spec, format) => {
+    switch (spec._tag) {
+        case "absent": {
+            // No-op: the file is intentionally absent.
+            return;
+        }
+        case "valid": {
+            const serialized = format === "json" ? stringifyJson(spec.contents) : stringifyYaml(spec.contents);
+            files.set(absolutePath, serialized);
+            return;
+        }
+        case "byteCorrupt": {
+            files.set(absolutePath, spec.bytes);
+            return;
+        }
+        case "schemaInvalid": {
+            // Use the format's serializer so the parser succeeds but the decoder
+            // rejects.
+            const serialized = format === "json" ? stringifyJson(spec.contents) : stringifyYaml(spec.contents);
+            files.set(absolutePath, serialized);
+            return;
+        }
+    }
+};
+const writeTree = (files, baseAbsolute, tree, ownerLabel) => Effect.gen(function* () {
+    for (const [relative, value] of Object.entries(tree)) {
+        yield* validateRelativePath(relative, ownerLabel);
+        const absolute = join(baseAbsolute, relative);
+        if (typeof value === "string") {
+            files.set(absolute, value);
+            continue;
+        }
+        // Determine format heuristically from the file extension; default to
+        // JSON because tree files we've seen so far are markdown / JSON / plain
+        // text.
+        const lower = relative.toLowerCase();
+        const format = lower.endsWith(".yaml") || lower.endsWith(".yml") ? "yaml" : "json";
+        // For tree-level FileSpecs, "valid" with a string maps to literal
+        // bytes; with an object we fall back to JSON serialization.
+        writeFileSpec(files, absolute, value, format);
+    }
+});
+const writeScope = (files, scope, scopeRoot, options) => Effect.gen(function* () {
+    if (scope === undefined)
+        return;
+    const stateRoot = options.scope === "project" ? scopeRoot : join(scopeRoot, ".axm", "workspace");
+    const settingsPath = options.scope === "project" ? join(scopeRoot, "axm.json") : join(stateRoot, "axm.json");
+    const lockfilePath = options.includeLockfile
+        ? options.scope === "project"
+            ? join(scopeRoot, "axm-lock.yaml")
+            : join(stateRoot, "axm-lock.yaml")
+        : null;
+    const mcpJsonPath = join(scopeRoot, ".mcp.json");
+    if (scope.settings !== undefined) {
+        writeFileSpec(files, settingsPath, scope.settings, "json");
+    }
+    if (scope.lockfile !== undefined && lockfilePath !== null) {
+        writeFileSpec(files, lockfilePath, scope.lockfile, "yaml");
+    }
+    if (scope.axmExtensions !== undefined) {
+        yield* writeTree(files, options.scope === "project"
+            ? join(scopeRoot, "agent_extensions")
+            : join(scopeRoot, ".axm", "workspace", "agent_extensions"), scope.axmExtensions, "axmExtensions");
+    }
+    if (scope.agentDirs !== undefined) {
+        for (const [agentId, tree] of Object.entries(scope.agentDirs)) {
+            const agentRoot = resolveAgentContentRoot(agentId);
+            yield* writeTree(files, join(scopeRoot, agentRoot), tree, `agentDirs[${agentId}]`);
+        }
+    }
+    if (scope.mcpJson !== undefined) {
+        writeFileSpec(files, mcpJsonPath, scope.mcpJson, "json");
+    }
+    if (scope.agentSettings !== undefined) {
+        for (const [agentId, fileSpec] of Object.entries(scope.agentSettings)) {
+            const agentRoot = resolveAgentSettingsRoot(agentId);
+            const agentSettingsPath = join(scopeRoot, agentRoot, "settings.json");
+            writeFileSpec(files, agentSettingsPath, fileSpec, "json");
+        }
+    }
+});
+// ---------------------------------------------------------------------------
+// Public builder
+// ---------------------------------------------------------------------------
+/**
+ * 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 const buildFixture = (spec) => Effect.gen(function* () {
+    const files = new Map();
+    yield* writeScope(files, spec.project, spec.workspaceRoot, {
+        scope: "project",
+        includeLockfile: true,
+    });
+    yield* writeScope(files, spec.user, join(spec.userHome), {
+        scope: "user",
+        includeLockfile: true,
+    });
+    const fs = makeInMemoryFs(files);
+    const path = yield* Path.Path;
+    return {
+        fs,
+        path,
+        files,
+        workspaceRoot: spec.workspaceRoot,
+        userHome: spec.userHome,
+    };
+}).pipe(Effect.provide(Path.layer));
+// ---------------------------------------------------------------------------
+// Named scenario constructors
+// ---------------------------------------------------------------------------
+const validSettingsContents = {
+    owner: "@team",
+    agents: ["claude-code"],
+    skills: { "managed-tool": { source: "github:owner/repo", enabled: true } },
+};
+const validLockfileContents = {
+    lockfileVersion: 6,
+    skills: {
+        "managed-tool": {
+            type: "github",
+            sourceType: "github",
+            sourceName: "github",
+            endpoint: "https://github.com",
+            extensionType: "skill",
+            workspaceName: "managed-tool",
+            packageFormat: "agentxm",
+            packageOwner: "@owner",
+            packageName: "managed-tool",
+            owner: "owner",
+            repo: "repo",
+            ref: "main",
+            resolvedCommit: "commit-1",
+            resolvedTree: "tree-1",
+            contentIdentity: "content-1",
+            treeIntegrity: `sha256-tree-v1:${"0".repeat(64)}`,
+        },
+    },
+};
+/**
+ * No source files materialize. Both scopes return absent for every cell.
+ */
+export const absentAll = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: { settings: { _tag: "absent" }, lockfile: { _tag: "absent" } },
+    user: { settings: { _tag: "absent" } },
+});
+/**
+ * Both project sources present and decodable; user scope settings present.
+ */
+export const validAll = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        settings: { _tag: "valid", contents: validSettingsContents },
+        lockfile: { _tag: "valid", contents: validLockfileContents },
+    },
+    user: {
+        settings: { _tag: "valid", contents: { owner: "@user" } },
+    },
+});
+/**
+ * Settings is valid; the lockfile is byte-corrupt.
+ */
+export const lockfileInvalidOnly = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        settings: { _tag: "valid", contents: validSettingsContents },
+        lockfile: {
+            _tag: "byteCorrupt",
+            bytes: "skills:\n  - bad\n - mismatched: indent\n   bad: !!!@@@",
+        },
+    },
+});
+/**
+ * Lockfile is valid; settings is byte-corrupt.
+ */
+export const settingsInvalidOnly = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        settings: { _tag: "byteCorrupt", bytes: "{ this is not json" },
+        lockfile: { _tag: "valid", contents: validLockfileContents },
+    },
+});
+/**
+ * Both project sources are byte-corrupt.
+ */
+export const bothInvalid = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        settings: { _tag: "byteCorrupt", bytes: "{ this is not json" },
+        lockfile: { _tag: "byteCorrupt", bytes: "lockfile: [bogus" },
+    },
+});
+/**
+ * Project state present; user scope absent.
+ */
+export const projectOnly = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        settings: { _tag: "valid", contents: validSettingsContents },
+        lockfile: { _tag: "valid", contents: validLockfileContents },
+    },
+    user: { settings: { _tag: "absent" } },
+});
+/**
+ * User scope settings present; project state absent.
+ */
+export const userOnly = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: { settings: { _tag: "absent" }, lockfile: { _tag: "absent" } },
+    user: { settings: { _tag: "valid", contents: { owner: "@user" } } },
+});
+/**
+ * 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 const projectUserShadowing = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        settings: {
+            _tag: "valid",
+            contents: {
+                owner: "@team",
+                sources: [{ name: "shared", type: "github", url: "https://github.com/team" }],
+            },
+        },
+    },
+    user: {
+        settings: {
+            _tag: "valid",
+            contents: {
+                owner: "@user",
+                sources: [{ name: "shared", type: "github", url: "https://github.com/user" }],
+            },
+        },
+    },
+});
+/**
+ * Agent dir exists on disk but settings does not declare the agent. Phase 9
+ * verifies the `agents.detected` projection surfaces a mismatch.
+ */
+export const agentPresentNoDeclaration = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        settings: { _tag: "valid", contents: { owner: "@team" } },
+        agentDirs: {
+            "claude-code": {
+                "skills/some-skill/SKILL.md": "# some-skill\n",
+            },
+        },
+    },
+});
+/**
+ * Settings declares an agent whose directory does not exist.
+ */
+export const agentDeclaredNotInstalled = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        settings: {
+            _tag: "valid",
+            contents: { owner: "@team", agents: ["claude-code"] },
+        },
+    },
+});
+/**
+ * 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 const mcpConfigDrift = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        settings: {
+            _tag: "valid",
+            contents: {
+                owner: "@team",
+                mcpServers: { declared: { source: "github:owner/repo" } },
+            },
+        },
+        mcpJson: {
+            _tag: "valid",
+            contents: { mcpServers: { drifted: { command: "echo" } } },
+        },
+    },
+});
+/**
+ * Same skill name across agent skill dirs (`.claude/skills/`, `.agents/skills/`)
+ * and canonical AXM storage.
+ */
+export const sameNameAcrossOrigins = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        agentDirs: {
+            "claude-code": {
+                "skills/some-skill/SKILL.md": "# claude-code\n",
+            },
+            codex: {
+                "skills/some-skill/SKILL.md": "# codex\n",
+            },
+        },
+        axmExtensions: {
+            "agentxm/@owner/skills/some-skill/skill.json": JSON.stringify({
+                owner: "@owner",
+                type: "skill",
+                name: "some-skill",
+                version: "1.0.0",
+            }),
+            "agentxm/@owner/skills/some-skill/src/SKILL.md": "---\nname: some-skill\ndescription: Canonical\n---\n# canonical\n",
+        },
+    },
+});
+/**
+ * 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 const pathEscapeAttempt = (workspaceRoot, userHome) => ({
+    workspaceRoot,
+    userHome,
+    project: {
+        axmExtensions: {
+            "../../etc/passwd": "evil\n",
+        },
+    },
+});
+// Keep `isObject` available for downstream phases that need the same guard.
+void isObject;
+//# sourceMappingURL=builder.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * Schema-decoded fixture builders for tests.
+ *
+ * Tests that need a real `Settings` or `Lockfile` value should run the input
+ * through the actual decoder rather than casting an arbitrary object via
+ * `as unknown as Settings`. These helpers wrap the canonical schema decoders
+ * so call sites yield the decoded value with `yield* decodedSettings({ ... })`.
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { type Lockfile } from "../../../lockfile/schema.js";
+import { type Settings } from "../../../settings/schema.js";
+export declare const decodedSettings: (input: unknown) => Effect.Effect<Settings, Schema.SchemaError>;
+export declare const decodedLockfile: (input: unknown) => Effect.Effect<Lockfile, Schema.SchemaError>;
+//# sourceMappingURL=decoders.d.ts.map

package/dist/src/workspace/read-model/__fixtures__/decoders.js

@@ -0,0 +1,15 @@
+/**
+ * Schema-decoded fixture builders for tests.
+ *
+ * Tests that need a real `Settings` or `Lockfile` value should run the input
+ * through the actual decoder rather than casting an arbitrary object via
+ * `as unknown as Settings`. These helpers wrap the canonical schema decoders
+ * so call sites yield the decoded value with `yield* decodedSettings({ ... })`.
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { LockfileSchema } from "../../../lockfile/schema.js";
+import { SettingsSchema } from "../../../settings/schema.js";
+export const decodedSettings = (input) => Schema.decodeUnknownEffect(SettingsSchema)(input);
+export const decodedLockfile = (input) => Schema.decodeUnknownEffect(LockfileSchema)(input);
+//# sourceMappingURL=decoders.js.map

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

@@ -0,0 +1,72 @@
+import { type ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { AgentId } from "@agentxm/extension-model/unstable/agents/types";
+import type { AgentDirOccurrence, AgentDirSubjectType, AgentSettingsOccurrence, CanonicalExtensionOccurrence, CanonicalExtensionOriginKind, McpConfigOccurrence } from "../scanners/types.js";
+import type { Scope } from "../types.js";
+export interface MakeCanonicalOccurrenceInput {
+    readonly scope: Scope;
+    readonly type: ExtensionType;
+    readonly origin: CanonicalExtensionOriginKind;
+    readonly name: string;
+    readonly owner: string | null;
+    readonly contentLocation: string;
+    /**
+     * Override `subjectFileExists`. Defaults to `true` when the subject type has
+     * a canonical primary file; `false` otherwise.
+     */
+    readonly subjectFileExists?: boolean;
+}
+/**
+ * Build a `CanonicalExtensionOccurrence` with the new structural fields
+ * populated. `pathSegments` is computed from `contentLocation` (POSIX split).
+ * `subjectFile` is `Some(<dir>/<name>.md)` for skill/subagent; `None` for
+ * mcp-server/rule/hook/knowledge/pack. `subjectFileExists` defaults to `true` when
+ * the subject has a canonical primary file; pass `false` to model absence.
+ */
+export declare const makeCanonicalOccurrence: (input: MakeCanonicalOccurrenceInput) => CanonicalExtensionOccurrence;
+export interface MakeAgentDirOccurrenceInput {
+    readonly scope: Scope;
+    readonly type: AgentDirSubjectType;
+    readonly agentId: AgentId;
+    readonly name: string;
+    readonly contentLocation: string;
+    /**
+     * Set to `true` for single-file subagent surfaces (e.g., `.roomodes`) so
+     * `subjectFile` is the `contentLocation` itself.
+     */
+    readonly singleFile?: boolean;
+    /**
+     * Override `subjectFileExists`. Defaults to `true` (the occurrence exists
+     * because the file exists).
+     */
+    readonly subjectFileExists?: boolean;
+}
+/**
+ * Build an `AgentDirOccurrence` with the new structural fields populated.
+ * `pathSegments` is computed from `contentLocation` (POSIX split).
+ * `subjectFile` is `<contentLocation>/<canonical-file>` for directory
+ * occurrences and the `contentLocation` itself for single-file subagent
+ * surfaces. `subjectFileExists` defaults to `true`.
+ */
+export declare const makeAgentDirOccurrence: (input: MakeAgentDirOccurrenceInput) => AgentDirOccurrence;
+export interface MakeWorkspaceMcpConfigOccurrenceInput {
+    readonly scope: Scope;
+    readonly name: string;
+    readonly contentLocation: string;
+    readonly config?: Readonly<Record<string, unknown>>;
+}
+export interface MakeAgentMcpConfigOccurrenceInput {
+    readonly scope: Scope;
+    readonly agentId: AgentId;
+    readonly name: string;
+    readonly contentLocation: string;
+    readonly config?: Readonly<Record<string, unknown>>;
+}
+export declare const makeWorkspaceMcpConfigOccurrence: (input: MakeWorkspaceMcpConfigOccurrenceInput) => McpConfigOccurrence;
+export declare const makeAgentMcpConfigOccurrence: (input: MakeAgentMcpConfigOccurrenceInput) => McpConfigOccurrence;
+export interface MakeAgentSettingsOccurrenceInput {
+    readonly scope: Scope;
+    readonly agentId: AgentId;
+    readonly contentLocation: string;
+}
+export declare const makeAgentSettingsOccurrence: (input: MakeAgentSettingsOccurrenceInput) => AgentSettingsOccurrence;
+//# sourceMappingURL=occurrences.d.ts.map