refactor(core): simplify system context into a belief model (#34917)

packages/core/src/reference/guidance.ts

@@ -11,20 +11,48 @@ const Summary = Schema.Struct({
   description: Schema.String.pipe(Schema.optional),
 })
 
+const entries = (references: ReadonlyArray<typeof Summary.Type>) =>
+  references.flatMap((reference) => [
+    "  <reference>",
+    `    <name>${reference.name}</name>`,
+    `    <path>${reference.path}</path>`,
+    ...(reference.description === undefined ? [] : [`    <description>${reference.description}</description>`]),
+    "  </reference>",
+  ])
+
 const render = (references: ReadonlyArray<typeof Summary.Type>) =>
   [
     "Project references provide additional directories that can be accessed when relevant.",
     "<available_references>",
-    ...references.flatMap((reference) => [
-      "  <reference>",
-      `    <name>${reference.name}</name>`,
-      `    <path>${reference.path}</path>`,
-      ...(reference.description === undefined ? [] : [`    <description>${reference.description}</description>`]),
-      "  </reference>",
-    ]),
+    ...entries(references),
     "</available_references>",
   ].join("\n")
 
+const update = (previous: ReadonlyArray<typeof Summary.Type>, current: ReadonlyArray<typeof Summary.Type>) => {
+  const diff = SystemContext.diffByKey(
+    previous,
+    current,
+    (reference) => reference.name,
+    (before, after) => before.path !== after.path || before.description !== after.description,
+  )
+  // Additions and removals render as small deltas; anything else restates the full list.
+  if (diff.changed.length > 0 || (diff.added.length === 0 && diff.removed.length === 0))
+    return [
+      "The available project references have changed. This list supersedes the previous reference list.",
+      render(current),
+    ].join("\n")
+  return [
+    ...(diff.added.length === 0
+      ? []
+      : ["New project references are available in addition to those previously listed:", ...entries(diff.added)]),
+    ...(diff.removed.length === 0
+      ? []
+      : [
+          `The following project references are no longer available and must not be used: ${diff.removed.map((reference) => reference.name).join(", ")}.`,
+        ]),
+  ].join("\n")
+}
+
 export interface Interface {
   readonly load: () => Effect.Effect<SystemContext.SystemContext>
 }
@@ -52,11 +80,7 @@ const layer = Layer.effect(
           codec: Schema.toCodecJson(Schema.Array(Summary)),
           load: Effect.succeed(available),
           baseline: render,
-          update: (_previous, current) =>
-            [
-              "The available project references have changed. This list supersedes the previous reference list.",
-              render(current),
-            ].join("\n"),
+          update,
           removed: () => "Project reference guidance is no longer available. Do not use previously listed references.",
         })
       }),