chore(core): add reference precedence changeset

.changeset/reference-precedence.md

@@ -0,0 +1,5 @@
+---
+"@opencode-ai/core": patch
+---
+
+Preserve reference insertion order when later config documents override an existing reference.

packages/core/src/config/plugin/reference.ts

@@ -20,14 +20,13 @@ export const Plugin = define({
     const global = yield* Global.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, ctx.reference.reload())
     yield* ctx.reference.transform((draft) => {
-      const entries = new Map<string, Reference.Source>()
       for (const doc of loaded.entries.filter((entry): entry is 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
           const description = typeof entry === "string" ? undefined : entry.description
           const hidden = typeof entry === "string" ? undefined : entry.hidden
-          entries.set(
+          draft.add(
             name,
             local(entry)
               ? Reference.LocalSource.make({
@@ -48,7 +47,6 @@ export const Plugin = define({
           )
         }
       }
-      for (const [name, source] of entries) draft.add(name, source)
     })
   }),
 })

packages/core/src/location-mutation.ts

@@ -120,6 +120,6 @@ const layer = Layer.effect(
 
 export const node = makeLocationNode({
   service: Service,
-  layer,
+  layer: layer.pipe(Layer.orDie),
   deps: [FSUtil.node, Location.node, ProjectMarkers.node],
 })

packages/core/src/session.ts

@@ -1209,7 +1209,7 @@ const SHELL_MAX_CAPTURE_BYTES = 1024 * 1024
 
 export const node = makeGlobalNode({
   service: Service,
-  layer,
+  layer: layer.pipe(Layer.orDie),
   deps: [
     Job.node,
     SessionEnvironment.node,

packages/core/test/config/reload.test.ts

@@ -34,6 +34,41 @@ const decode = Schema.decodeUnknownSync(Info)
 const document = path.join(import.meta.dir, "opencode.json")
 
 describe("config plugin reloads", () => {
+  it.effect("preserves reference precedence and insertion order across documents", () =>
+    Effect.gen(function* () {
+      const plugins = yield* Plugin.Service
+      const references = yield* Reference.Service
+      const host = yield* PluginHost.make(plugins)
+      yield* references.transform((draft) =>
+        draft.add(
+          "external",
+          Reference.LocalSource.make({ type: "local", path: AbsolutePath.make("/references/external") }),
+        ),
+      )
+      yield* ConfigReferencePlugin.Plugin.effect(host)
+
+      const result = yield* references.list()
+      expect(result.map((reference) => reference.name)).toEqual(["external", "shared", "first", "second"])
+      expect(result.find((reference) => reference.name === "shared")?.path).toBe(
+        AbsolutePath.make(path.resolve("/config/second/shared")),
+      )
+    }).pipe(
+      Effect.provide(
+        Config.testLayer([
+          referenceConfig("/config/first/opencode.json", {
+            shared: "./shared",
+            first: "./first",
+          }),
+          referenceConfig("/config/second/opencode.json", {
+            shared: "./shared",
+            second: "./second",
+          }),
+        ]),
+      ),
+      Effect.provideService(Global.Service, Global.Service.of(Global.make())),
+    ),
+  )
+
   it.live("reloads config-backed domains without reloading external plugins", () =>
     Effect.gen(function* () {
       const agents = yield* Agent.Service
@@ -102,6 +137,14 @@ function config(name: string) {
   })
 }
 
+function referenceConfig(file: string, references: Record<string, string>) {
+  return new Document({
+    type: "document",
+    path: AbsolutePath.make(file),
+    info: decode({ references }),
+  })
+}
+
 function title(value: string) {
   return value.charAt(0).toUpperCase() + value.slice(1)
 }