edge cases and various todo items

Author: jbolda

packages/server/README.md

@@ -15,7 +15,11 @@ Key points:
 
 - `useServiceGraph(services: ServicesMap, options?: { sequential?: boolean }): ServiceRunner<ServicesMap>` — returns a _runner function_ which you call to start the graph: `const run = useServiceGraph(services, options); yield* run(subset?: string[] | string);`. By default services in the same topological layer run concurrently; pass `options.sequential = true` to run services in each layer serially.
 - `ServiceDefinition.operation` (required) — an `Operation<void>` which indicates the service has started. This operation may be long-lived (e.g. `useService`) or may return once the service is ready while a background child keeps the service running. See the example below.
-- `deps` — an optional list of service names this service depends on; services without dependencies in the same layer are started concurrently by default, or serially when `options.sequential` is true.
+- `dependsOn` — an optional object `{ startup: string[]; restart?: string[] }` listing service names this service depends on. Use `startup` to list services that must start before this service; use `restart` to list services that should trigger a restart of this service when they are restarted (for example, due to a watched file change). Services without dependencies in the same layer are started concurrently by default, or serially when `options.sequential` is true.
+
+- `subset` (runner argument) — when calling the runner returned by `useServiceGraph` you may pass a subset (e.g. `yield* run(['serviceA'])` or `yield* run('serviceA')`) to start only a subset of services; any startup dependencies required by that subset are automatically included.
+
+- Watching & restart propagation — pass `{ watch: true }` to `useServiceGraph` and define `watch` paths in each `ServiceDefinition` to enable file watching. The watcher will precompute transitive dependents (based on `dependsOn.restart`) and automatically emit restart updates for dependents when a watched path changes, so restarts propagate efficiently and deterministically.
 - Lifecycle hooks: `beforeStart`, `afterStart`, `beforeStop`, `afterStop` — each is an `Operation<void>` that runs at the appropriate time.
 
 Example:
@@ -42,7 +46,7 @@ main(function* () {
           "B",
           "node --import tsx ./test/services/service-b.ts"
         ),
-        deps: ["A"],
+        dependsOn: { startup: ["A"] },
       },
     });
   });
@@ -61,29 +65,28 @@ Each `ServiceDefinition` supports lifecycle hook operations. These hooks run in
 ```ts
 const services = {
   A: {
-    operation: useService(
-      "A",
-      "node --import tsx ./test/services/service-a.ts"
-    ),
-    afterStart: () =>
-      (function* () {
-        // runs after the operation returns
-        console.log("A has started");
-      })(),
-    beforeStop: () =>
-      (function* () {
-        // runs during shutdown in reverse order
+    operation: (function* () {
+      // start the service via useService or useChildSimulation
+      yield* useService("A", "node --import tsx ./test/services/service-a.ts");
+      // signal that the service is ready
+      console.log("A has started");
+      try {
+        // keep running until cancelled
+        yield* suspend();
+      } finally {
+        // cleanup runs automatically on scope cancellation
         console.log("A is stopping");
-      })(),
+      }
+    })(),
   },
 };
 ```
 
 Notes:
 
-- `afterStart` runs after `operation` returns (service is ready)
-- `beforeStop` runs during cleanup in reverse-order of startup
-- Hooks are optional and can be used together with a passed `operation` or a custom operation
+- Use a try/finally in your `operation` to run cleanup logic when the service is stopped
+- This approach leverages Effection scopes and ensures cleanup runs in reverse dependency order when the graph is shut down
+- Use `useService` or `useChildSimulation` inside your operation as needed to start underlying processes
 
 Try it
 
@@ -132,5 +135,5 @@ node --import tsx ./example/basic-graph.ts
 
 Previously services could expose their return value via a public `exportsOperation` that consumers could await. That mechanism has been removed in this branch as we move to a child-process-focused runner model. Provider-returned values are still delivered to dependent service factories internally, but no longer exposed as an operation on the public `services` map.
 
-For convenience tests may use the `servicePorts` map exposed by the running graph to discover HTTP ports that services registered when they start.
+For convenience tests may use the `servicePorts` map exposed by the running graph to discover HTTP ports that services registered when they start. The `servicePorts` map is available on the object returned by the runner and contains service name => port when a service's `operation` returns an object with a `{ port: number }` property.
 ````

packages/server/bin/run-simulation-child.ts

@@ -10,7 +10,7 @@ main(function* () {
   const args = process.argv.slice(2);
   console.dir({ args });
   if (args.length < 1) {
-    throw new Error("usage: run-simulation-child.js <modulePath> [jsonArgs]");
+    throw new Error("usage: run-simulation-child.js <modulePath>");
   }
 
   const modulePath = args[0];

packages/server/example/README.md

@@ -4,7 +4,7 @@ This folder contains runnable examples demonstrating `useServiceGraph` and `useS
 
 There are two sets of examples:
 
-- **use-service** (top-level files like `basic-graph.ts`, `lifecycle-hooks.ts`, `concurrency-layers.ts`) — these spawn separate processes using `useService` (e.g. `node --import tsx ./example/services/*.ts`). Use these to exercise the process-based behavior.
+- **use-service** (top-level files like `basic-graph.ts`, `concurrency-layers.ts`) — these spawn separate processes using `useService` (e.g. `node --import tsx ./example/services/*.ts`). Use these to exercise the process-based behavior.
 
 - **operation** (under `operation/`) — these demonstrate `useChildSimulation()` which runs each service in a child process using a simulation factory. They show how to isolate simulations and start them as independent processes.
 
@@ -25,3 +25,5 @@ node --import tsx ./example/operation/basic-graph.ts
 ```
 
 These examples make use of the small service implementations in `./example/services`.
+
+Notes: the examples now use `dependsOn` with a `{ startup, restart? }` shape. To experiment with restart propagation, add a `watch` entry to a service and include dependents via `dependsOn.restart` — when a watched file changes the watcher will restart the affected service and its transitive dependents.

packages/server/example/concurrency-layers.ts

@@ -14,7 +14,7 @@ const servicesMap = {
     watch: ["./example/services/basic-sim-2.ts"],
   },
   dependent: {
-    // deps: ["fast", "slow"] as const,
+    dependsOn: { startup: ["fast", "slow"] as const },
     operation: resource<void>(function* (provide) {
       try {
         console.log("all deps started; running dependent service");

packages/server/example/lifecycle-hooks.ts

@@ -28,7 +28,7 @@ const servicesMap = {
     ),
   },
   B: {
-    deps: ["A"] as const,
+    dependsOn: { startup: ["A"] as const },
     operation: useService(
       "B",
       "node --import tsx ./example/services/basic-sim.ts",

packages/server/example/process-graph.ts

@@ -1,19 +1,3 @@
-import {
-  createFoundationSimulationServer,
-  type FoundationSimulator,
-} from "@simulacrum/foundation-simulator";
+import { simulation as genSimulation } from "./gen-sim-factory.ts";
 
-export function simulation(
-  port: number = 3301,
-  startDelay: number = 10
-): FoundationSimulator<any> {
-  const factory = createFoundationSimulationServer({
-    port,
-    extendRouter(router) {
-      router.get("/status", (_req, res) => {
-        res.status(200).send("ok");
-      });
-    },
-  })();
-  return factory;
-}
+export const simulation = genSimulation(3301, 10);

packages/server/example/services/basic-sim-1.ts

@@ -1,19 +1,3 @@
-import {
-  createFoundationSimulationServer,
-  type FoundationSimulator,
-} from "@simulacrum/foundation-simulator";
+import { simulation as genSimulation } from "./gen-sim-factory.ts";
 
-export function simulation(
-  port: number = 3302,
-  startDelay: number = 10
-): FoundationSimulator<any> {
-  const factory = createFoundationSimulationServer({
-    port,
-    extendRouter(router) {
-      router.get("/status", (_req, res) => {
-        res.status(200).send("ok");
-      });
-    },
-  })();
-  return factory;
-}
+export const simulation = genSimulation(3302, 15);

packages/server/example/services/basic-sim-2.ts

@@ -0,0 +1,35 @@
+import {
+  createFoundationSimulationServer,
+  type FoundationSimulator,
+} from "@simulacrum/foundation-simulator";
+
+/*
+  Helper to create a basic foundation simulation server with a configurable
+  start delay to simulate slow startups. You would export your simulator
+  more directly instead of wrapping it like this in a real project.
+*/
+export function simulation(
+  port: number = 3301,
+  startDelay: number = 10
+): FoundationSimulator<any> {
+  const factory = createFoundationSimulationServer({
+    port,
+    extendRouter(router) {
+      router.get("/status", (_req, res) => {
+        res.status(200).send("ok");
+      });
+    },
+  })();
+
+  return {
+    async listen(
+      ...args: Parameters<FoundationSimulator<any>["listen"]>
+    ): Promise<any> {
+      if (startDelay > 0) {
+        await new Promise((resolve) => setTimeout(resolve, startDelay));
+      }
+      // delegate to underlying factory listen
+      return factory.listen(...args);
+    },
+  };
+}

packages/server/example/services/gen-sim-factory.ts

@@ -6,19 +6,11 @@ import { simulationCLI } from "../src/cli.ts";
 
 const servicesMap = {
   A: {
-    operation: useChildSimulation(
-      "A",
-      "./example/services/basic-sim.ts",
-      [0, 10]
-    ),
+    operation: useChildSimulation("A", "./example/services/basic-sim-1.ts"),
   },
   B: {
-    deps: ["A"] as const,
-    operation: useChildSimulation(
-      "B",
-      "./example/services/basic-sim.ts",
-      [0, 20]
-    ),
+    dependsOn: { startup: ["A"] as const },
+    operation: useChildSimulation("B", "./example/services/basic-sim-2.ts"),
   },
 };