feat(api): Change .for() polarity to fail by default

Change the .for() method to throw an error by default if a cause is
already set, with an optional boolean parameter to allow treating it
as a suggestion.

Changes:
- Renamed parameter from `options: { force?: boolean }` to `allowIfSet?: boolean`
- Default behavior: throw error if cause/link already exists
- Pass `true` to silently ignore if cause already set (treat as suggestion)
- Moved .for() signature to IAnyCell interface for consistency
- Updated tests to verify new behavior

This makes the API safer by preventing accidental overwrites while still
allowing flexibility when needed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: seefeldb

packages/api/index.ts

@@ -56,8 +56,14 @@ type IsThisArray =
  * IAnyCell is an interface that is used by all calls and to which the runner
  * attaches the internal methods..
  */
-// deno-lint-ignore no-empty-interface
 export interface IAnyCell<T> {
+  /**
+   * Set a cause for this cell. Used to create a link when the cell doesn't have
+   * one yet.
+   * @param cause - The cause to associate with this cell
+   * @returns This cell for method chaining
+   */
+  for(cause: unknown): Cell<T>;
 }
 
 /**

packages/runner/src/cell.ts

@@ -86,13 +86,7 @@ declare module "@commontools/api" {
    * on Cell in the runner runtime.
    */
   interface IAnyCell<out T> {
-    /**
-     * Set a cause for this cell. Used to create a link when the cell doesn't have one yet.
-     * @param cause - The cause to associate with this cell
-     * @param options - Optional configuration
-     * @returns This cell for method chaining
-     */
-    for(cause: unknown, options?: { force?: boolean }): Cell<T>;
+    for(cause: unknown, allowIfSet?: boolean): Cell<T>;
     asSchema<S extends JSONSchema = JSONSchema>(
       schema: S,
     ): Cell<Schema<S>>;
@@ -272,23 +266,26 @@ export class CellImpl<T> implements ICell<T>, IStreamable<T> {
    * This affects all sibling cells (created via .key(), .asSchema(), .withTx()) since they
    * share the same container.
    * @param cause - The cause to associate with this cell
-   * @param options - Optional configuration
-   * @param options.force - If true, will create an extension if link already exists. If false (default), ignores the call if link already exists.
+   * @param allowIfSet - If true, treat as suggestion and silently ignore if cause already set. If false (default), throw error if cause already set.
    * @returns This cell for method chaining
    */
-  for(cause: unknown, options?: { force?: boolean }): Cell<T> {
-    const force = options?.force ?? false;
-
-    // If cause or id already exists and force is false, silently ignore
-    if ((this._causeContainer.id || this._causeContainer.cause) && !force) {
-      return this as unknown as Cell<T>;
+  for(cause: unknown, allowIfSet?: boolean): Cell<T> {
+    // If cause or id already exists, either fail or silently ignore based on allowIfSet
+    if (this._causeContainer.id || this._causeContainer.cause) {
+      if (allowIfSet) {
+        // Treat as suggestion - silently ignore
+        return this as unknown as Cell<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.",
+        );
+      }
     }
 
     // Store the cause in the shared container - all siblings will see this
     this._causeContainer.cause = cause;
 
-    // TODO(seefeld): Implement extension creation when force is true and link exists
-
     return this as unknown as Cell<T>;
   }
 

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

@@ -45,7 +45,7 @@ describe("Cell with Optional Link", () => {
       expect(result).toBe(cell);
     });
 
-    it("should ignore .for() if link already exists", () => {
+    it("should throw error if link already exists (default behavior)", () => {
       const existingCell = runtime.getCell<number>(
         space,
         "test-cell-with-link",
@@ -55,28 +55,32 @@ describe("Cell with Optional Link", () => {
       existingCell.set(42);
 
       const cause = { type: "test-cause" };
-      const result = existingCell.for(cause);
 
-      // Should return the cell for chaining
-      expect(result).toBe(existingCell);
+      // Should throw by default
+      expect(() => existingCell.for(cause)).toThrow(
+        "Cannot set cause: cell already has a cause or link",
+      );
+
       // Cell should still work normally
       expect(existingCell.get()).toBe(42);
     });
 
-    it("should allow force option to override existing link behavior", () => {
+    it("should allow allowIfSet option to treat as suggestion", () => {
       const existingCell = runtime.getCell<number>(
         space,
-        "test-cell-force",
+        "test-cell-allow",
         undefined,
         tx,
       );
       existingCell.set(42);
 
       const cause = { type: "test-cause" };
-      const result = existingCell.for(cause, { force: true });
+      const result = existingCell.for(cause, true); // allowIfSet = true
 
-      // Should return the cell for chaining
+      // Should return the cell for chaining without throwing
       expect(result).toBe(existingCell);
+      // Cell should still work normally
+      expect(existingCell.get()).toBe(42);
     });
 
     it("should support method chaining", () => {
@@ -248,7 +252,7 @@ describe("Cell with Optional Link", () => {
       cell.set(42);
 
       // Should not affect the cell
-      cell.for({ type: "ignored-cause" });
+      cell.for({ type: "ignored-cause" }, true);
 
       expect(cell.get()).toBe(42);
     });