feat(runner): Ensure frame.space is always set and add inHandler flag

Audit and fix frame creation to ensure space is always available from
the result cell context:

1. Modified pushFrameFromCause() to:
   - Extract space from unsafe_binding and set on frame.space
   - Accept inHandler boolean parameter (replaces event field)
   - This makes frame.space available as fallback in cell.ts

2. Renamed Frame.event to Frame.inHandler:
   - More accurate semantic: indicates handler context, not event data
   - Used for per-frame counter-based ID generation fallback
   - Simpler boolean check vs checking event truthiness

3. Updated CauseContainer to store space:
   - Container now holds id, space, and cause for sharing across siblings
   - ensureLink() checks if container has both id and space before deriving
   - Space from container takes precedence over frame space

4. Updated event handler in runner.ts:
   - Pass inHandler: true to pushFrameFromCause()
   - Frame now has both space (from processCell.space) and inHandler flag

Benefits:
- frame.space fallback in cell.ts now works correctly
- clearer semantics with inHandler vs event
- space always available from result cell in runner contexts
- CauseContainer properly shares space across siblings

Author: seefeldb

docs/specs/recipe-construction/rollout-plan.md

@@ -42,7 +42,7 @@
     isn't there, e.g. because we need to create a link to the cell (when passed
     into `anotherCell.set()` for example). We want to encourage .for use in
     ambiguous cases.
-- [ ] Add space and event to Frame
+- [x] Add space and event to Frame
 - [ ] First merge of OpaqueRef and RegularCell
   - [ ] Add methods that allow linking to node invocations
     - [ ] `setPreExisting` can be deprecated (used in toOpaqueRef which itself

packages/runner/src/builder/recipe.ts

@@ -399,13 +399,17 @@ export function pushFrame(frame?: Frame): Frame {
 export function pushFrameFromCause(
   cause: any,
   unsafe_binding?: UnsafeBinding,
+  inHandler: boolean = false,
 ): Frame {
   const frame = {
     parent: getTopFrame(),
     cause,
     generatedIdCounter: 0,
     opaqueRefs: new Set(),
+    // Extract space from unsafe_binding if available and set it on frame
+    ...(unsafe_binding?.space && { space: unsafe_binding.space }),
     ...(unsafe_binding ? { unsafe_binding } : {}),
+    ...(inHandler && { inHandler }),
   };
   frames.push(frame);
   return frame;

packages/runner/src/builder/types.ts

@@ -260,7 +260,7 @@ export type Frame = {
   cause?: unknown;
   generatedIdCounter: number;
   space?: MemorySpace;
-  event?: unknown;
+  inHandler?: boolean;
   opaqueRefs: Set<OpaqueRef<any>>;
   unsafe_binding?: UnsafeBinding;
 };

packages/runner/src/cell.ts

@@ -278,7 +278,7 @@ export class CellImpl<T> implements ICell<T>, IStreamable<T> {
       } else {
         // Fail by default
         throw new Error(
-          "Cannot set cause: cell already has a cause or link. Pass true as second parameter to allow this as a suggestion.",
+          "Cannot set cause: cell already has a cause or link.",
         );
       }
     }
@@ -301,14 +301,22 @@ export class CellImpl<T> implements ICell<T>, IStreamable<T> {
    * @throws Error if not in a handler context and no cause was provided
    */
   private ensureLink(): void {
-    // If we already have a full link (id and space), nothing to do
-    if (this._causeContainer.id && this._link.space) {
+    // If we already have a full link (id and space) in the container, just copy
+    // it over to our link.
+    if (this._causeContainer.id && this._causeContainer.space) {
+      this._link = {
+        ...this._link,
+        id: this._causeContainer.id,
+        space: this._causeContainer.space,
+      };
       return;
     }
 
-    // Check if we're in a handler context
+    // Otherwise, let's attempt to derive the id:
+
     const frame = getTopFrame();
 
+    // We must be in a frame context to derive the id.
     if (!frame) {
       throw new Error(
         "Cannot create cell link: no frame context.\n" +
@@ -329,9 +337,11 @@ export class CellImpl<T> implements ICell<T>, IStreamable<T> {
       );
     }
 
+    // Used passed in cause (via .for()), for events fall back to per-frame
+    // counter.
     const cause = this._causeContainer.cause ??
-      (frame.event ? { count: frame.generatedIdCounter++ } : undefined);
-    // TODO(seefeld): Implement no-cause-but-in-handler case
+      (frame.inHandler ? { count: frame.generatedIdCounter++ } : undefined);
+
     if (!cause) {
       throw new Error(
         "Cannot create cell link: not in a handler context and no cause was provided.\n" +
@@ -342,19 +352,16 @@ export class CellImpl<T> implements ICell<T>, IStreamable<T> {
       );
     }
 
-    // Create an entity ID from the cause
-    // Include frame.cause in the source for determinism
+    // Create an entity ID from the cause, including the frame's
     const id = toURI(createRef({ frame: cause }, cause));
 
     // Populate the id in the shared causeContainer
     // All siblings will see this update
     this._causeContainer.id = id;
     this._causeContainer.space = space;
 
-    // Update this cell's link with the space if it doesn't have one
-    if (!this._link.space) {
-      this._link = { ...this._link, id, space };
-    }
+    // Update this cell's link
+    this._link = { ...this._link, id, space };
   }
 
   get space(): MemorySpace {

packages/runner/src/runner.ts

@@ -969,13 +969,17 @@ export class Runner implements IRunner {
           tx,
         );
 
-        const frame = pushFrameFromCause(cause, {
-          recipe,
-          materialize: (path: readonly PropertyKey[]) =>
-            processCell.getAsQueryResult(path),
-          space: processCell.space,
-          tx,
-        });
+        const frame = pushFrameFromCause(
+          cause,
+          {
+            recipe,
+            materialize: (path: readonly PropertyKey[]) =>
+              processCell.getAsQueryResult(path),
+            space: processCell.space,
+            tx,
+          },
+          true, // Set the event on the frame
+        );
 
         const argument = module.argumentSchema
           ? inputsCell.asSchema(module.argumentSchema).get()

packages/runner/test/cell-optional-link.test.ts

@@ -209,7 +209,7 @@ describe("Cell with Optional Link", () => {
       pushFrame({
         cause: { type: "handler-cause" },
         space,
-        event: "test-event",
+        inHandler: true,
         generatedIdCounter: 0,
         opaqueRefs: new Set(),
       });