refactor(core): consolidate references (anomalyco#31539)

shoootyou · Jun 10, 2026 · Jun 7, 2026 · Jun 7, 2026 · Jun 7, 2026 · Jun 7, 2026
commit 6566ede935069d9771e051ddbf60e087092d4395
diff --git a/packages/core/src/config/plugin/reference.ts b/packages/core/src/config/plugin/reference.ts
@@ -0,0 +1,63 @@
+export * as ConfigReferencePlugin from "./reference"
+
+import path from "path"
+import { Effect } from "effect"
+import { Config } from "../../config"
+import { ConfigReference } from "../reference"
+import { Global } from "../../global"
+import { Location } from "../../location"
+import { PluginV2 } from "../../plugin"
+import { Reference } from "../../reference"
+import { AbsolutePath } from "../../schema"
+
+export const Plugin = {
+  id: PluginV2.ID.make("core/config-reference"),
+  effect: Effect.gen(function* () {
+    const config = yield* Config.Service
+    const global = yield* Global.Service
+    const location = yield* Location.Service
+    const references = yield* Reference.Service
+    const update = yield* references.transform()
+    const entries = new Map<string, Reference.Source>()
+    for (const doc of (yield* config.entries()).filter(
+      (entry): entry is Config.Document => entry.type === "document",
+    )) {
+      const directory = doc.path ? path.dirname(doc.path) : location.directory
+      for (const [name, entry] of Object.entries(doc.info.references ?? {})) {
+        if (!validAlias(name)) continue
+        entries.set(
+          name,
+          local(entry)
+            ? new Reference.LocalSource({
+                type: "local",
+                path: AbsolutePath.make(localPath(directory, global.home, typeof entry === "string" ? entry : entry.path)),
+              })
+            : new Reference.GitSource({
+                type: "git",
+                repository: typeof entry === "string" ? entry : entry.repository,
+                branch: typeof entry === "string" ? undefined : entry.branch,
+              }),
+        )
+      }
+    }
+
+    yield* update((editor) => {
+      for (const [name, source] of entries) editor.add(name, source)
+    })
+  }),
+}
+
+function validAlias(name: string) {
+  return name.length > 0 && !/[\/\s`,]/.test(name)
+}
+
+function local(entry: ConfigReference.Entry): entry is string | ConfigReference.Local {
+  return typeof entry === "string"
+    ? entry.startsWith(".") || entry.startsWith("/") || entry.startsWith("~")
+    : "path" in entry
+}
+
+function localPath(directory: string, home: string, value: string) {
+  if (value.startsWith("~/")) return path.join(home, value.slice(2))
+  return path.isAbsolute(value) ? value : path.resolve(directory, value)
+}
diff --git a/packages/core/src/config/reference.ts b/packages/core/src/config/reference.ts
@@ -16,33 +16,3 @@ export type Entry = typeof Entry.Type
 
 export const Info = Schema.Record(Schema.String, Entry)
 export type Info = typeof Info.Type
-
-export type NormalizedEntry =
-  | { readonly kind: "local"; readonly path: string }
-  | { readonly kind: "git"; readonly repository: string; readonly branch?: string }
-  | { readonly kind: "invalid"; readonly message: string }
-
-export type NormalizedInfo = Record<string, NormalizedEntry>
-
-export function validateAlias(name: string) {
-  if (name.length === 0) return "Reference alias must not be empty"
-  if (/[\/\s`,]/.test(name)) return "Reference alias must not contain /, whitespace, comma, or backtick"
-}
-
-export function normalizeEntry(entry: Entry): NormalizedEntry {
-  if (typeof entry === "string") {
-    if (entry.startsWith(".") || entry.startsWith("/") || entry.startsWith("~")) return { kind: "local", path: entry }
-    return { kind: "git", repository: entry }
-  }
-  if ("path" in entry) return { kind: "local", path: entry.path }
-  return { kind: "git", repository: entry.repository, branch: entry.branch }
-}
-
-export function normalize(info: Info): NormalizedInfo {
-  return Object.fromEntries(
-    Object.entries(info).map(([name, entry]) => {
-      const message = validateAlias(name)
-      return [name, message ? { kind: "invalid" as const, message } : normalizeEntry(entry)]
-    }),
-  )
-}
diff --git a/packages/core/src/filesystem.ts b/packages/core/src/filesystem.ts
@@ -9,15 +9,13 @@ import { EventV2 } from "./event"
 import { FSUtil } from "./fs-util"
 import { Global } from "./global"
 import { Location } from "./location"
-import { ProjectReference } from "./project-reference"
 import { NonNegativeInt, PositiveInt, RelativePath } from "./schema"
 import { Protected } from "./filesystem/protected"
 import { Ripgrep } from "./filesystem/ripgrep"
 import { ToolOutputStore } from "./tool-output-store"
 
 export const ReadInput = Schema.Struct({
   path: Schema.String,
-  reference: Schema.NonEmptyString.pipe(Schema.optional),
 })
 export type ReadInput = typeof ReadInput.Type
 
@@ -134,7 +132,6 @@ export class ReadPath extends Schema.Class<ReadPath>("FileSystem.ReadPath")({
 
 export const ListInput = Schema.Struct({
   path: Schema.String.pipe(Schema.optional),
-  reference: Schema.NonEmptyString.pipe(Schema.optional),
 })
 export type ListInput = typeof ListInput.Type
 
@@ -158,7 +155,6 @@ export class RootTarget extends Schema.Class<RootTarget>("FileSystem.RootTarget"
   real: Schema.String,
   root: Schema.String,
   resource: Schema.String,
-  reference: Schema.NonEmptyString.pipe(Schema.optional),
   type: Schema.Literals(["file", "directory"]),
 }) {}
 
@@ -239,7 +235,6 @@ export const layer = Layer.effect(
     const fs = yield* FSUtil.Service
     const location = yield* Location.Service
     const global = yield* Effect.serviceOption(Global.Service)
-    const references = yield* ProjectReference.Service
     const ripgrep = yield* Ripgrep.Service
     const root = yield* fs.realPath(location.directory).pipe(Effect.orDie)
     const ignored = ignore()
@@ -251,21 +246,12 @@ export const layer = Layer.effect(
       .readFileString(path.join(location.project.directory, ".ignore"))
       .pipe(Effect.catch(() => Effect.succeed("")))
     if (ignorefile) ignored.add(ignorefile)
-    const select = Effect.fnUntraced(function* (reference?: string) {
-      if (!reference) return { directory: location.directory, root }
-      const resolved = yield* references.get(reference)
-      if (!resolved) return yield* Effect.die(new Error(`Unknown project reference: ${reference}`))
-      if (resolved.kind === "invalid") return yield* Effect.die(new Error(resolved.message))
-      if (resolved.kind === "git") yield* references.ensurePath(resolved.path).pipe(Effect.orDie)
-      return { directory: resolved.path, root: yield* fs.realPath(resolved.path).pipe(Effect.orDie) }
-    })
-    const resolve = Effect.fnUntraced(function* (input?: string, reference?: string) {
+    const resolve = Effect.fnUntraced(function* (input?: string) {
       const managed = path.join(
         Option.match(global, { onNone: () => Global.Path.data, onSome: (value) => value.data }),
         ToolOutputStore.MANAGED_DIRECTORY,
       )
       if (input && path.isAbsolute(input)) {
-        if (reference) return yield* Effect.die(new Error("Absolute paths cannot use a project reference"))
         if (path.dirname(input) !== managed || !path.basename(input).startsWith("tool_"))
           return yield* Effect.die(new Error("Absolute path is not managed tool output"))
         const real = yield* fs.realPath(input).pipe(Effect.orDie)
@@ -274,9 +260,9 @@ export const layer = Layer.effect(
           return yield* Effect.die(new Error("Path escapes managed tool output"))
         return { absolute: input, real, directory: managed, root: managedRoot }
       }
-      const selected = yield* select(reference)
-      const absolute = path.resolve(selected.directory, input ?? ".")
-      if (!FSUtil.contains(selected.directory, absolute))
+      const selected = { directory: location.directory, root }
+      const absolute = path.resolve(location.directory, input ?? ".")
+      if (!FSUtil.contains(location.directory, absolute))
         return yield* Effect.die(new Error("Path escapes the location"))
       const real = yield* fs.realPath(absolute).pipe(Effect.orDie)
       if (!FSUtil.contains(selected.root, real)) return yield* Effect.die(new Error("Path escapes the location"))
@@ -335,24 +321,24 @@ export const layer = Layer.effect(
     })
 
     const resolveReadPath = Effect.fn("FileSystem.resolveReadPath")(function* (input: ReadInput) {
-      const target = yield* resolve(input.path, input.reference)
+      const target = yield* resolve(input.path)
       const info = yield* fs.stat(target.real).pipe(Effect.orDie)
       const type = info.type === "File" ? "file" : info.type === "Directory" ? "directory" : undefined
       if (!type) return yield* Effect.die(new Error("Path is not a file or directory"))
       const relative = path.relative(target.root, target.real).replaceAll("\\", "/") || "."
       return new ReadPath({
         type,
-        resource: input.reference === undefined ? relative : `${input.reference}:${relative}`,
+        resource: relative,
       })
     })
     const resolveFile = Effect.fnUntraced(function* (input: ReadInput) {
-      const target = yield* resolve(input.path, input.reference)
+      const target = yield* resolve(input.path)
       const info = yield* fs.stat(target.real).pipe(Effect.orDie)
       if (info.type !== "File") return yield* Effect.die(new Error("Path is not a file"))
       const relative = path.relative(target.root, target.real).replaceAll("\\", "/") || "."
       return {
         real: target.real,
-        resource: input.reference === undefined ? relative : `${input.reference}:${relative}`,
+        resource: relative,
       }
     })
     const content = (target: { readonly real: string }, bytes: Uint8Array) =>
@@ -510,25 +496,24 @@ export const layer = Layer.effect(
       )
     })
     const resolveList = Effect.fn("FileSystem.resolveList")(function* (input: ListInput = {}) {
-      const directory = yield* resolve(input.path, input.reference)
+      const directory = yield* resolve(input.path)
       const info = yield* fs.stat(directory.real).pipe(Effect.orDie)
       if (info.type !== "Directory") return yield* Effect.die(new Error("Path is not a directory"))
       const relative = path.relative(directory.root, directory.real).replaceAll("\\", "/") || "."
       return new ListTarget({
         ...directory,
-        resource: input.reference === undefined ? relative : `${input.reference}:${relative}`,
+        resource: relative,
       })
     })
     const resolveRoot = Effect.fn("FileSystem.resolveRoot")(function* (input: ListInput = {}) {
-      const target = yield* resolve(input.path, input.reference)
+      const target = yield* resolve(input.path)
       const info = yield* fs.stat(target.real).pipe(Effect.orDie)
       const type = info.type === "File" ? "file" : info.type === "Directory" ? "directory" : undefined
       if (!type) return yield* Effect.die(new Error("Path is not a file or directory"))
       const relative = path.relative(target.root, target.real).replaceAll("\\", "/") || "."
       return new RootTarget({
         ...target,
-        resource: input.reference === undefined ? relative : `${input.reference}:${relative}`,
-        reference: input.reference,
+        resource: relative,
         type,
       })
     })
@@ -644,5 +629,4 @@ export const layer = Layer.effect(
 
 export const locationLayer = layer.pipe(
   Layer.provide(Ripgrep.defaultLayer),
-  Layer.provideMerge(ProjectReference.locationLayer),
 )
diff --git a/packages/core/src/location-layer.ts b/packages/core/src/location-layer.ts
@@ -22,7 +22,7 @@ import { Watcher } from "./filesystem/watcher"
 import { LocationMutation } from "./location-mutation"
 import { LocationSearch } from "./location-search"
 import { FileMutation } from "./file-mutation"
-import { ProjectReference } from "./project-reference"
+import { Reference } from "./reference"
 import { RepositoryCache } from "./repository-cache"
 import { Pty } from "./pty"
 import { SkillV2 } from "./skill"
@@ -52,7 +52,7 @@ export class LocationServiceMap extends LayerMap.Service<LocationServiceMap>()("
       location,
       Policy.locationLayer,
       Config.locationLayer,
-      ProjectReference.locationLayer,
+      Reference.locationLayer,
       PluginV2.locationLayer,
       Catalog.locationLayer,
       CommandV2.locationLayer,

diff --git a/packages/core/src/location-search.ts b/packages/core/src/location-search.ts
@@ -9,8 +9,7 @@ import { NonNegativeInt, PositiveInt, RelativePath } from "./schema"
 
 /**
  * Location-scoped raw search substrate. Search authority is selected only by
- * FileSystem, preserving Location-relative paths and named read
- * references. Model formatting, leaf-tool permissions, and HTTP transport stay
+ * FileSystem, preserving Location-relative paths. Model formatting, leaf-tool permissions, and HTTP transport stay
  * outside this service so future GlobTool, GrepTool, and HTTP consumers can
  * share the same bounded filesystem behavior.
  *
@@ -106,7 +105,7 @@ export const layer = Layer.effect(
       return {
         path: RelativePath.make(relative),
         canonical,
-        resource: root.reference === undefined ? relative : `${root.reference}:${relative}`,
+        resource: relative,
         mtime: info.mtime.pipe(
           Option.map((date) => date.getTime()),
           Option.getOrElse(() => 0),

diff --git a/packages/core/src/plugin/boot.ts b/packages/core/src/plugin/boot.ts
@@ -9,6 +9,7 @@ import { Config } from "../config"
 import { ConfigAgentPlugin } from "../config/plugin/agent"
 import { ConfigCommandPlugin } from "../config/plugin/command"
 import { ConfigSkillPlugin } from "../config/plugin/skill"
+import { ConfigReferencePlugin } from "../config/plugin/reference"
 import { EventV2 } from "../event"
 import { FSUtil } from "../fs-util"
 import { Global } from "../global"
@@ -25,6 +26,7 @@ import { EnvPlugin } from "./env"
 import { ModelsDevPlugin } from "./models-dev"
 import { ProviderPlugins } from "./provider"
 import { SkillV2 } from "../skill"
+import { Reference } from "../reference"
 
 type Plugin = {
   id: PluginV2.ID
@@ -42,6 +44,7 @@ type Plugin = {
     | Config.Service
     | ModelsDev.Service
     | SkillV2.Service
+    | Reference.Service
   >
 }
 
@@ -67,6 +70,7 @@ export const layer = Layer.effect(
     const fs = yield* FSUtil.Service
     const global = yield* Global.Service
     const skill = yield* SkillV2.Service
+    const references = yield* Reference.Service
     const done = yield* Deferred.make<void>()
 
     const add = Effect.fn("PluginBoot.add")(function* (input: Plugin) {
@@ -85,6 +89,7 @@ export const layer = Layer.effect(
           Effect.provideService(FSUtil.Service, fs),
           Effect.provideService(Global.Service, global),
           Effect.provideService(SkillV2.Service, skill),
+          Effect.provideService(Reference.Service, references),
           Effect.provideService(PluginV2.Service, plugin),
         ),
       })
@@ -104,6 +109,7 @@ export const layer = Layer.effect(
       yield* add(ConfigAgentPlugin.Plugin)
       yield* add(ConfigCommandPlugin.Plugin)
       yield* add(ConfigSkillPlugin.Plugin)
+      yield* add(ConfigReferencePlugin.Plugin)
     }).pipe(Effect.withSpan("PluginBoot.boot"))
 
     yield* boot.pipe(
@@ -124,4 +130,5 @@ export const locationLayer = layer.pipe(
   Layer.provideMerge(Config.locationLayer),
   Layer.provideMerge(AgentV2.locationLayer),
   Layer.provideMerge(SkillV2.locationLayer),
+  Layer.provideMerge(Reference.locationLayer),
 )