Rename builders to routes (plain object) and use $ as the argument convention

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/a80bbc52-f68f-419e-971b-d993e4e18383

Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

Author: Copilot

.github/issue-proposals/apply-approach-1-function-injection.md

@@ -27,15 +27,12 @@ An apply script is a TypeScript file with a default export:
 // repl/sold-pets.ts
 import type { ApplyContext } from "counterfact";
 
-export default ({ context, builders, route }: ApplyContext) => {
-  context.petService.reset();
-  context.petService.addPet({ id: 1, status: "sold" });
-  context.petService.addPet({ id: 2, status: "available" });
-
-  builders.set(
-    "getSoldPets",
-    route("/pet/findByStatus").method("get").query({ status: "sold" }),
-  );
+export default ($: ApplyContext) => {
+  $.context.petService.reset();
+  $.context.petService.addPet({ id: 1, status: "sold" });
+  $.context.petService.addPet({ id: 2, status: "available" });
+
+  $.routes.getSoldPets = $.route("/pet/findByStatus").method("get").query({ status: "sold" });
 };
 ```
 
@@ -47,8 +44,8 @@ export interface ApplyContext {
   context: Record<string, unknown>;
   /** Load a context object for a specific path */
   loadContext: (path: string) => Record<string, unknown>;
-  /** Named route builders injected into the REPL */
-  builders: Map<string, RouteBuilder>;
+  /** Named route builders available in the REPL execution context */
+  routes: Record<string, RouteBuilder>;
   /** Create a new RouteBuilder for a given path */
   route: (path: string) => RouteBuilder;
 }
@@ -74,7 +71,7 @@ After execution, Counterfact compares the environment state before and after the
 ```
 Applied sold-pets
 
-Builders added:
+Routes added:
   getSoldPets
 ```
 
@@ -88,7 +85,7 @@ Context diffs are not automatically tracked in this approach — the script auth
 2. Resolve the file path using the ordered lookup above.
 3. Dynamically import the resolved module (using `tsx` or the existing transpiler if the file is TypeScript).
 4. Call the exported function with the live environment objects.
-5. Snapshot `builders` before/after and print the diff.
+5. Snapshot `routes` before/after and print the diff.
 
 ---
 
@@ -108,8 +105,8 @@ Context diffs are not automatically tracked in this approach — the script auth
 
 - [ ] `.apply <name>` resolves and executes a TypeScript file from the configured `repl/` directory
 - [ ] `.apply <path>` resolves and executes a TypeScript file at the given relative path
-- [ ] The script receives `{ context, loadContext, builders, route }` as arguments
-- [ ] Builders injected by the script are available in the REPL after the command runs
-- [ ] The REPL prints a summary of builders added and removed after each apply
+- [ ] The script receives `$` with `{ context, loadContext, routes, route }` as properties
+- [ ] Routes injected by the script are available in the REPL after the command runs
+- [ ] The REPL prints a summary of routes added and removed after each apply
 - [ ] A meaningful error is shown when the file cannot be found or the export is not a function
 - [ ] Existing REPL commands and behavior are unaffected

.github/issue-proposals/apply-approach-2-scenario-class-lifecycle.md

@@ -28,20 +28,17 @@ import type { Scenario, ApplyContext } from "counterfact";
 export default class SoldPetsScenario implements Scenario {
   static dependencies = ["base"];
 
-  setup({ context, builders, route }: ApplyContext): void {
-    context.petService.addPet({ id: 1, status: "sold" });
-    context.petService.addPet({ id: 2, status: "available" });
-
-    builders.set(
-      "getSoldPets",
-      route("/pet/findByStatus").method("get").query({ status: "sold" }),
-    );
+  setup($: ApplyContext): void {
+    $.context.petService.addPet({ id: 1, status: "sold" });
+    $.context.petService.addPet({ id: 2, status: "available" });
+
+    $.routes.getSoldPets = $.route("/pet/findByStatus").method("get").query({ status: "sold" });
   }
 
-  teardown({ context, builders }: ApplyContext): void {
-    context.petService.removePet(1);
-    context.petService.removePet(2);
-    builders.delete("getSoldPets");
+  teardown($: ApplyContext): void {
+    $.context.petService.removePet(1);
+    $.context.petService.removePet(2);
+    delete $.routes.getSoldPets;
   }
 }
 ```
@@ -61,6 +58,8 @@ export interface Scenario {
 }
 ```
 
+> `ApplyContext` provides `{ context, loadContext, routes, route }` where `routes` is a plain object in the REPL execution context.
+
 ### Invocation
 
 ```
@@ -78,7 +77,7 @@ When a scenario declares `static dependencies`, Counterfact automatically applie
 # Counterfact first applies "base" (dependency), then "sold-pets"
 Applied base → sold-pets
 
-Builders added:
+Routes added:
   getSoldPets
 ```
 

.github/issue-proposals/apply-approach-3-proxy-based-tracking.md

@@ -25,29 +25,27 @@ A script is a plain TypeScript module with a default export function. The script
 
 ```ts
 // repl/sold-pets.ts
-export default ({ context, builders, route }) => {
-  context.petService.reset();
+export default ($) => {
+  $.context.petService.reset();
 
-  context.petService.addPet({ id: 1, status: "sold" });
-  context.petService.addPet({ id: 2, status: "available" });
+  $.context.petService.addPet({ id: 1, status: "sold" });
+  $.context.petService.addPet({ id: 2, status: "available" });
 
-  builders.set(
-    "getSoldPets",
-    route("/pet/findByStatus").method("get").query({ status: "sold" }),
-  );
+  $.routes.getSoldPets = $.route("/pet/findByStatus").method("get").query({ status: "sold" });
 };
 ```
 
-This is identical in surface syntax to Approach 1. The difference is internal: `context` and `builders` passed to the script are **transparent reactive proxies** of the live objects.
+This is identical in surface syntax to Approach 1. The difference is internal: `$.context` and `$.routes` passed to the script are **transparent reactive proxies** of the live objects.
 
 ### Proxy-based change tracking
 
-Before calling the script, Counterfact wraps each environment object in a `Proxy` that intercepts `set`, `deleteProperty`, and `Map` mutations:
+Before calling the script, Counterfact wraps each environment object in a `Proxy` that intercepts `set`, `deleteProperty`, and property mutations on the `routes` plain object:
 
 ```ts
 const tracked = trackChanges(liveContext);
-await script({ context: tracked.proxy, builders: trackBuilders(liveBuilders) });
-const report = tracked.changes(); // returns structured diff
+const trackedRoutes = trackChanges(liveRoutes);
+await script({ context: tracked.proxy, routes: trackedRoutes.proxy, route: createRouteFunction(...) });
+const report = { context: tracked.changes(), routes: trackedRoutes.changes() };
 ```
 
 The proxy forwards all reads and writes to the underlying live object, so mutations take effect immediately. It also accumulates a change log:
@@ -71,7 +69,7 @@ Applied sold-pets
 Context changes:
   petService.pets: [] → [{id:1,status:"sold"},{id:2,status:"available"}]
 
-Builders added:
+Routes added:
   getSoldPets
 ```
 
@@ -96,7 +94,7 @@ Resolution order is the same as Approach 1:
 
 1. Add `.apply` as a dot-command in `src/repl/repl.ts`.
 2. Resolve the file path.
-3. Create proxy wrappers around `context` and `builders`.
+3. Create proxy wrappers around `context` and `routes`.
 4. Dynamically import and call the script with the proxy-wrapped arguments.
 5. Collect the accumulated change records from the proxies.
 6. Print the formatted diff.
@@ -144,7 +142,7 @@ Deep (nested) change tracking can be implemented by returning a recursive proxy
 - [ ] `.apply <name>` resolves and executes a TypeScript file, passing proxy-wrapped environment objects
 - [ ] All top-level property assignments to `context` are captured in the change log
 - [ ] Nested property mutations (e.g. `context.petService.reset()`) are captured where feasible
-- [ ] `builders.set()` and `builders.delete()` calls are captured and reported
+- [ ] `$.routes.name = builder` assignments and `delete $.routes.name` are captured and reported
 - [ ] After the script runs, the REPL prints a structured diff of all recorded changes
 - [ ] The underlying live objects are mutated correctly (proxy is transparent for reads and writes)
 - [ ] Scripts that throw an error do not leave the change-tracking proxy in an inconsistent state