@granular-software/sdk 0.4.29 → 0.4.31

package/dist/index.js

@@ -4669,27 +4669,27 @@ var Session = class {
   }
   async publishTools(tools, revision = "1.0.0") {
     throw new Error(
-      "Environment-scoped effect publication was removed. Declare effects in the manifest and register live handlers with granular.registerEffects(environment.sandboxId, effects)."
+      "Environment-scoped effect publication was removed. Declare effects in the manifest and register live handlers with granular.ontology(environment.sandboxId).effects.registerMany(effects)."
     );
   }
   async publishEffect(effect) {
     throw new Error(
-      "Environment-scoped effect publication was removed. Use granular.registerEffect(environment.sandboxId, effect)."
+      "Environment-scoped effect publication was removed. Use granular.ontology(environment.sandboxId).effects.register(effect)."
     );
   }
   async publishEffects(effects) {
     throw new Error(
-      "Environment-scoped effect publication was removed. Use granular.registerEffects(environment.sandboxId, effects)."
+      "Environment-scoped effect publication was removed. Use granular.ontology(environment.sandboxId).effects.registerMany(effects)."
     );
   }
   async unpublishEffect(name) {
     throw new Error(
-      "Environment-scoped effect publication was removed. Use granular.unregisterEffect(environment.sandboxId, effectName)."
+      "Environment-scoped effect publication was removed. Use granular.ontology(environment.sandboxId).effects.unregister(effectName)."
     );
   }
   async unpublishAllEffects() {
     throw new Error(
-      "Environment-scoped effect publication was removed. Use granular.unregisterAllEffects(environment.sandboxId)."
+      "Environment-scoped effect publication was removed. Use granular.ontology(environment.sandboxId).effects.clear()."
     );
   }
   /**
@@ -10975,17 +10975,8 @@ var searchableMetamodelPackage = defineMetamodelPackage({
     }
   },
   domain: {
-    applyToPropertyIR(propertyIR, propertySummary) {
-      if (String(propertySummary.type || "").toLowerCase() !== "string" || propertySummary.searchable === false) {
-        return propertyIR;
-      }
-      return {
-        ...propertyIR,
-        docs: [
-          ...propertyIR.docs,
-          propertySummary.searchablePhonetic ? "Searchable via `search` using FalkorDB full-text query syntax with phonetic matching enabled." : "Searchable via `search` using FalkorDB full-text query syntax."
-        ]
-      };
+    applyToPropertyIR(propertyIR, _propertySummary) {
+      return propertyIR;
     }
   }
 });
@@ -11599,17 +11590,40 @@ function buildEffectMetamodelMutations(toolPath, spec) {
 
 // src/client.ts
 var STANDARD_MODULES_OPERATIONS = [
-  { create: "entity", has: { id: { value: "auto-generated" }, createdAt: { value: void 0 } } },
+  {
+    create: "entity",
+    has: { id: { value: "auto-generated" }, createdAt: { value: void 0 } }
+  },
   { create: "class", extends: "entity", has: {} },
-  { create: "user", extends: "entity", has: { email: { value: void 0 }, firstName: { value: void 0 }, lastName: { value: void 0 } } },
-  { create: "company", extends: "entity", has: { name: { value: void 0 }, website: { value: void 0 } } },
+  {
+    create: "user",
+    extends: "entity",
+    has: {
+      email: { value: void 0 },
+      firstName: { value: void 0 },
+      lastName: { value: void 0 }
+    }
+  },
+  {
+    create: "company",
+    extends: "entity",
+    has: { name: { value: void 0 }, website: { value: void 0 } }
+  },
   { create: "string", has: {} },
   { create: "number", has: {} },
   { create: "boolean", has: {} },
-  { create: "tool_parameter", has: { name: { value: void 0 }, type: { value: "string" }, description: { value: void 0 }, required: { value: false } } }
+  {
+    create: "tool_parameter",
+    has: {
+      name: { value: void 0 },
+      type: { value: "string" },
+      description: { value: void 0 },
+      required: { value: false }
+    }
+  }
 ];
 var BUILTIN_MODULES = {
-  "standard_modules": STANDARD_MODULES_OPERATIONS
+  standard_modules: STANDARD_MODULES_OPERATIONS
 };
 var DEFAULT_DIRECT_RECORD_OBJECTS_REQUEST_BATCH_SIZE = 100;
 var MAX_RECORD_OBJECTS_CONCURRENCY = 16;
@@ -11644,7 +11658,9 @@ function isRetryableLocalWorkerRestart(status, body, url) {
 }
 function isRetryableRecordObjectsError(error) {
   const message = error instanceof Error ? error.message : String(error);
-  return /worker restarted mid-request|econnreset|network|socket connection was closed unexpectedly|timed out/i.test(message);
+  return /worker restarted mid-request|econnreset|network|socket connection was closed unexpectedly|timed out/i.test(
+    message
+  );
 }
 function computeEffectKey2(effect) {
   const attachedClass = effect.className?.trim();
@@ -11697,6 +11713,22 @@ function normalizeHeapSnapshot(raw) {
     updatedAt: typeof heap.updatedAt === "number" ? heap.updatedAt : Date.now()
   };
 }
+function deriveRuntimeBaseUrl(apiEndpoint) {
+  try {
+    const endpoint = new URL(apiEndpoint);
+    const graphqlSuffix = "/orchestrator/graphql";
+    if (endpoint.pathname.endsWith(graphqlSuffix)) {
+      endpoint.pathname = endpoint.pathname.slice(0, -graphqlSuffix.length);
+    } else if (endpoint.pathname.endsWith("/graphql")) {
+      endpoint.pathname = endpoint.pathname.slice(0, -"/graphql".length);
+    }
+    endpoint.search = "";
+    endpoint.hash = "";
+    return endpoint.toString().replace(/\/$/, "");
+  } catch {
+    return apiEndpoint.replace(/\/orchestrator\/graphql$/, "").replace(/\/$/, "");
+  }
+}
 function normalizeSubject(subject) {
   const granularId = subject.granularId || subject.subjectId;
   const userId = subject.userId || subject.identityId || granularId;
@@ -11721,7 +11753,10 @@ function normalizeUser(user) {
   };
 }
 function normalizeEnvironmentData(environment) {
-  const buildPolicy = environment.buildPolicy || environment.tracking || (environment.tagId ? { mode: "tag", tagId: environment.tagId } : { mode: "pinned", versionId: environment.versionId || environment.buildId });
+  const buildPolicy = environment.buildPolicy || environment.tracking || (environment.tagId ? { mode: "tag", tagId: environment.tagId } : {
+    mode: "pinned",
+    versionId: environment.versionId || environment.buildId
+  });
   const environmentName = environment.environment || environment.envName || "prod";
   return {
     ...environment,
@@ -11733,12 +11768,13 @@ function normalizeEnvironmentData(environment) {
     tracking: environment.tracking || buildPolicy
   };
 }
-var Environment = class extends Session {
+var Environment = class {
+  granular;
   envData;
   _apiKey;
   _apiEndpoint;
-  constructor(client, envData, clientId, apiKey, apiEndpoint) {
-    super(client, clientId);
+  constructor(granular, envData, apiKey, apiEndpoint) {
+    this.granular = granular;
     this.envData = envData;
     this._apiKey = apiKey;
     this._apiEndpoint = apiEndpoint;
@@ -11779,35 +11815,126 @@ var Environment = class extends Session {
   get permissionProfileId() {
     return this.envData.permissionProfileId;
   }
+  /** The current build policy backing this environment */
+  get buildPolicy() {
+    return this.envData.buildPolicy;
+  }
+  /** The current update state relative to the followed tag */
+  get updateState() {
+    return this.envData.updateState;
+  }
+  /** Convenience flag for whether this environment trails the current tag target */
+  get isOutdated() {
+    return this.envData.updateState === "update_available";
+  }
+  /** The followed tag name when this environment is tag-tracked */
+  get tag() {
+    return this.envData.tag?.name || this.envData.buildPolicy.tagName || null;
+  }
   /** The GraphQL API endpoint URL */
   get apiEndpoint() {
     return this._apiEndpoint;
   }
+  /** Internal auth token used for control-plane and runtime fallback requests */
+  get authToken() {
+    return this._apiKey;
+  }
+  /** Base runtime URL derived from the GraphQL endpoint */
+  get runtimeBaseUrl() {
+    return this.getRuntimeBaseUrl();
+  }
+  get sessions() {
+    return {
+      list: async (options) => this.listSessions(options?.status || "active"),
+      create: async (options) => this.createSession(options),
+      connect: async (sessionId, options) => this.connectSession(sessionId, options),
+      reopen: async (sessionId, options) => this.reopenSession(sessionId, options),
+      close: async (sessionId, session) => this.closeSession(sessionId, session)
+    };
+  }
+  get data() {
+    return {
+      record: async (record) => this.recordObject(record),
+      recordMany: async (records, options) => this.recordObjects(records, options),
+      import: async (records, options) => this.enqueueRecordImport(records, options),
+      listImports: async (status) => this.listRecordImports(status),
+      getImport: async (importId) => this.getRecordImport(importId),
+      getImportSummary: async () => this.getRecordImportSummary(),
+      cancelImport: async (importId) => this.cancelRecordImport(importId),
+      getAwaitingCount: async () => this.getAwaitingRecordCount()
+    };
+  }
+  get feedback() {
+    return {
+      list: async () => this.listFeedback()
+    };
+  }
   /**
-   * Return a plain JS snapshot of the synced session heap.
-   *
-   * The heap lives in the Automerge document, so this method does not perform
-   * any extra network roundtrip.
+   * Sessionless environments do not own a live transport, so disconnecting the
+   * environment handle itself is a no-op. This keeps the public surface
+   * symmetric with `EnvironmentSession.disconnect()` and lets callers always
+   * clean up safely without tracking whether they currently hold an environment
+   * or a session.
    */
-  getHeap() {
-    const doc = this.document;
-    return normalizeHeapSnapshot(doc?.heap);
+  async disconnect() {
   }
-  getRuntimeBaseUrl() {
-    try {
-      const endpoint = new URL(this._apiEndpoint);
-      const graphqlSuffix = "/orchestrator/graphql";
-      if (endpoint.pathname.endsWith(graphqlSuffix)) {
-        endpoint.pathname = endpoint.pathname.slice(0, -graphqlSuffix.length);
-      } else if (endpoint.pathname.endsWith("/graphql")) {
-        endpoint.pathname = endpoint.pathname.slice(0, -"/graphql".length);
-      }
-      endpoint.search = "";
-      endpoint.hash = "";
-      return endpoint.toString().replace(/\/$/, "");
-    } catch {
-      return this._apiEndpoint.replace(/\/orchestrator\/graphql$/, "").replace(/\/$/, "");
+  async listSessions(status = "active") {
+    if (status === "all") {
+      const [active, closed] = await Promise.all([
+        this.granular.listOpenSessions({ environmentId: this.environmentId }),
+        this.granular.listClosedSessions({ environmentId: this.environmentId })
+      ]);
+      return [...active, ...closed].sort(
+        (left, right) => Date.parse(right.lastSeenAt) - Date.parse(left.lastSeenAt)
+      );
+    }
+    return status === "closed" ? this.granular.listClosedSessions({ environmentId: this.environmentId }) : this.granular.listOpenSessions({ environmentId: this.environmentId });
+  }
+  async createSession(options) {
+    return this.granular.createSession({
+      environmentId: this.environmentId,
+      clientId: options?.clientId,
+      initialHeap: options?.initialHeap
+    });
+  }
+  async connectSession(sessionId, options) {
+    const session = await this.granular["connectSession"]({
+      sessionId,
+      clientId: options?.clientId
+    });
+    if (session.environmentId !== this.environmentId) {
+      await session.disconnect().catch(() => {
+        session.disconnectTransport();
+      });
+      throw new Error(
+        `Session ${sessionId} belongs to environment ${session.environmentId}, not ${this.environmentId}.`
+      );
+    }
+    return session;
+  }
+  async reopenSession(sessionId, options) {
+    const session = await this.granular.reopenSession(sessionId, {
+      clientId: options?.clientId
+    });
+    if (session.environmentId !== this.environmentId) {
+      await session.disconnect().catch(() => {
+        session.disconnectTransport();
+      });
+      throw new Error(
+        `Session ${sessionId} belongs to environment ${session.environmentId}, not ${this.environmentId}.`
+      );
     }
+    return session;
+  }
+  async closeSession(sessionId, session) {
+    await this.granular.closeSession(sessionId, session);
+  }
+  async listFeedback() {
+    const response = await this.controlPlaneRequest(`/control/environments/${this.environmentId}/feedback`);
+    return Array.isArray(response.items) ? response.items : [];
+  }
+  getRuntimeBaseUrl() {
+    return deriveRuntimeBaseUrl(this._apiEndpoint);
   }
   async controlPlaneRequest(path, options = {}) {
     const runtimeBase = this.getRuntimeBaseUrl();
@@ -11815,94 +11942,19 @@ var Environment = class extends Session {
     const response = await fetch(url, {
       ...options,
       headers: {
-        "Authorization": `Bearer ${this._apiKey}`,
+        Authorization: `Bearer ${this._apiKey}`,
         "Content-Type": "application/json",
-        "Connection": "close",
+        Connection: "close",
         ...options.headers
       }
     });
     if (!response.ok) {
-      throw new Error(`Control Plane API Error (${response.status}): ${await response.text()}`);
+      throw new Error(
+        `Control Plane API Error (${response.status}): ${await response.text()}`
+      );
     }
     return response.json();
   }
-  /**
-   * Close the session and disconnect from the sandbox.
-   *
-   * Sends `client.goodbye` over WebSocket first, then issues an HTTP fallback
-   * to the runtime goodbye endpoint if no definitive WS-side runtime notify
-   * acknowledgement was observed.
-   */
-  async disconnect() {
-    let wsNotifiedRuntime = false;
-    try {
-      const goodbye = await this.rpc("client.goodbye", {
-        timestamp: Date.now()
-      });
-      wsNotifiedRuntime = Boolean(goodbye?.ok && goodbye?.via);
-    } catch {
-      wsNotifiedRuntime = false;
-    }
-    if (!wsNotifiedRuntime) {
-      try {
-        const runtimeBase = this.getRuntimeBaseUrl();
-        await fetch(
-          `${runtimeBase}/orchestrator/runtime/environments/${this.environmentId}/session-goodbye`,
-          {
-            method: "POST",
-            headers: {
-              "Content-Type": "application/json",
-              "Authorization": `Bearer ${this._apiKey}`,
-              "Connection": "close"
-            },
-            body: JSON.stringify({
-              reason: "sdk_disconnect_http_fallback",
-              sessionId: this.client.currentSessionId
-            })
-          }
-        );
-      } catch {
-      }
-    }
-    this.client.disconnect();
-  }
-  // ==================== GRAPH CONTAINER READINESS ====================
-  /** The last known graph container status, updated by checkReadiness() or on heartbeat */
-  graphContainerStatus = null;
-  /**
-   * Check if the graph container is ready and warm.
-   *
-   * Sends a lightweight heartbeat RPC to the Session DO which internally
-   * pings the FalkorDB container. The response includes `graphContainerStatus`,
-   * which is stored locally and emitted as a `readiness` event.
-   *
-   * Use this method to proactively warm the graph container before any
-   * GraphQL query that requires it, or to poll the container's state in
-   * the background.
-   *
-   * @returns The current graph container status object
-   *
-   * @example
-   * ```typescript
-   * const status = await env.checkReadiness();
-   * console.log(status.status); // 'hot' | 'warming' | 'unknown'
-   *
-   * // Or listen for live updates
-   * env.on('readiness', (status) => {
-   *   console.log('Graph is now:', status.status);
-   * });
-   * ```
-   */
-  async checkReadiness() {
-    const result = await this.client.call("client.heartbeat", {});
-    const containerStatus = result?.graphContainerStatus ?? {
-      lastKeepAliveAt: Date.now(),
-      status: "unknown"
-    };
-    this.graphContainerStatus = containerStatus;
-    this.emit("readiness", containerStatus);
-    return containerStatus;
-  }
   // ==================== ID ↔ GRAPH PATH MAPPING ====================
   /**
    * Convert a class name + real-world ID into a unique graph path.
@@ -11931,14 +11983,14 @@ var Environment = class extends Session {
   }
   /**
    * Execute a GraphQL query against the environment's graph.
-   * 
+   *
    * The query uses the Granular graph query language (based on Cypher/GraphQL).
    * Authentication is handled automatically using the SDK's API key.
-   * 
+   *
    * @param query - The GraphQL query string
    * @param variables - Optional variables for the query
    * @returns The query result data
-   * 
+   *
    * @example
    * ```typescript
    * // Read the workspace
@@ -11946,7 +11998,7 @@ var Environment = class extends Session {
    *   `query { model(path: "workspace") { path label submodels { path label } } }`
    * );
    * console.log(result.data);
-   * 
+   *
    * // Create a model
    * const created = await env.graphql(
    *   `mutation { at(path: "workspace") { create_submodel(subpath: "my_node", label: "My Node", prototype: "Model") { model { path label } } } }`
@@ -11958,7 +12010,7 @@ var Environment = class extends Session {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "Authorization": `Bearer ${this._apiKey}`
+        Authorization: `Bearer ${this._apiKey}`
       },
       body: JSON.stringify({
         environmentId: this.environmentId,
@@ -11975,10 +12027,10 @@ var Environment = class extends Session {
   // ==================== RELATIONSHIP METHODS ====================
   /**
    * Define a relationship between two model types.
-   * 
+   *
    * Creates both submodels (if they don't exist) and links them with
    * a RelationshipDef node that encodes cardinality.
-   * 
+   *
    * @example
    * ```typescript
    * // Author has many Books, Book has one Author
@@ -12038,10 +12090,10 @@ var Environment = class extends Session {
   }
   /**
    * Get all relationships for a model type.
-   * 
+   *
    * @param modelPath - The model type path (e.g., "author")
    * @returns Array of relationships from this model's perspective
-   * 
+   *
    * @example
    * ```typescript
    * const rels = await env.getRelationships('author');
@@ -12074,18 +12126,18 @@ var Environment = class extends Session {
   }
   /**
    * Attach a target model to a relationship submodel.
-   * 
+   *
    * Handles cardinality automatically:
    * - "One" side: sets/replaces the reference
    * - "Many" side: adds the target to the collection
-   * 
+   *
    * If the target model doesn't exist, it's created as an instance of the foreign type.
    * Bidirectional sync is automatic.
-   * 
+   *
    * @param modelPath - The model instance path (e.g., "tolkien")
    * @param submodelPath - The relationship submodel (e.g., "books")
    * @param targetPath - The target model to attach (e.g., "lord_of_the_rings")
-   * 
+   *
    * @example
    * ```typescript
    * // Attach a book to an author (many side)
@@ -12112,18 +12164,18 @@ var Environment = class extends Session {
   }
   /**
    * Detach a target model from a relationship submodel.
-   * 
+   *
    * Handles bidirectional cleanup automatically.
-   * 
+   *
    * @param modelPath - The model instance path
    * @param submodelPath - The relationship submodel
    * @param targetPath - The target to detach (optional for "one" side; omit on "many" side to detach all)
-   * 
+   *
    * @example
    * ```typescript
    * // Detach a specific book
    * await env.detach('tolkien', 'books', 'lord_of_the_rings');
-   * 
+   *
    * // Detach all books
    * await env.detach('tolkien', 'books');
    * ```
@@ -12147,11 +12199,11 @@ var Environment = class extends Session {
   }
   /**
    * List all related models through a relationship submodel.
-   * 
+   *
    * @param modelPath - The model instance path
    * @param submodelPath - The relationship submodel
    * @returns Array of related model references
-   * 
+   *
    * @example
    * ```typescript
    * const books = await env.listRelated('tolkien', 'books');
@@ -12175,14 +12227,14 @@ var Environment = class extends Session {
   }
   /**
    * Apply a manifest to the current environment's graph.
-   * 
+   *
    * Translates each manifest operation into GraphQL mutations and executes them
    * in order. This is the core mechanism for creating classes, fields, and
    * relationships from a declarative manifest.
-   * 
+   *
    * @param manifest - The manifest content to apply
    * @returns Summary of applied operations
-   * 
+   *
    * @example
    * ```typescript
    * await environment.applyManifest({
@@ -12220,12 +12272,16 @@ var Environment = class extends Session {
                 applied++;
               } catch (err) {
                 if (!err.message?.includes("already exists")) {
-                  errors.push(`Import ${imp.name} operation failed: ${err.message}`);
+                  errors.push(
+                    `Import ${imp.name} operation failed: ${err.message}`
+                  );
                 }
               }
             }
           } else {
-            errors.push(`Unknown module: "${imp.name}" (only built-in modules are supported)`);
+            errors.push(
+              `Unknown module: "${imp.name}" (only built-in modules are supported)`
+            );
           }
         }
       }
@@ -12309,7 +12365,10 @@ var Environment = class extends Session {
     }
   }
   async _applyEffectMetamodels(toolPath, metamodels) {
-    for (const mutation of buildEffectMetamodelMutations(toolPath, metamodels)) {
+    for (const mutation of buildEffectMetamodelMutations(
+      toolPath,
+      metamodels
+    )) {
       await this._runGraphql(mutation.query, mutation.label);
     }
   }
@@ -12358,7 +12417,9 @@ var Environment = class extends Session {
       }
       if (eventType.payloadSchema?.properties) {
         const fieldSpecs = {};
-        for (const [propName, propSchema] of Object.entries(eventType.payloadSchema.properties)) {
+        for (const [propName, propSchema] of Object.entries(
+          eventType.payloadSchema.properties
+        )) {
           const schema = propSchema;
           fieldSpecs[propName] = {
             type: schema.type ?? "string",
@@ -12641,7 +12702,9 @@ var Environment = class extends Session {
       const wave = plans.slice(waveStart, waveStart + concurrency);
       await Promise.all(
         wave.map(async (plan) => {
-          const { items, durationMs } = await this.executeRecordObjectsChunk(plan.slice);
+          const { items, durationMs } = await this.executeRecordObjectsChunk(
+            plan.slice
+          );
           if (items.length !== plan.slice.length) {
             throw new Error(
               `recordObjects: chunk ${plan.chunkIndex + 1} returned ${items.length} results, expected ${plan.slice.length}`
@@ -12671,13 +12734,10 @@ var Environment = class extends Session {
     let lastError;
     for (let attempt = 1; attempt <= DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT; attempt += 1) {
       try {
-        const response = await this.controlPlaneRequest(
-          `/control/environments/${this.environmentId}/records/batch`,
-          {
-            method: "POST",
-            body: JSON.stringify({ records: chunk })
-          }
-        );
+        const response = await this.controlPlaneRequest(`/control/environments/${this.environmentId}/records/batch`, {
+          method: "POST",
+          body: JSON.stringify({ records: chunk })
+        });
         const items = Array.isArray(response.items) ? response.items : [];
         return { items, durationMs: Date.now() - wallStart };
       } catch (error) {
@@ -12740,7 +12800,9 @@ var Environment = class extends Session {
    * Fetch a single record import by id.
    */
   async getRecordImport(importId) {
-    return this.controlPlaneRequest(`/control/record-imports/${importId}`);
+    return this.controlPlaneRequest(
+      `/control/record-imports/${importId}`
+    );
   }
   /**
    * Cancel a queued/background record import.
@@ -12753,36 +12815,186 @@ var Environment = class extends Session {
       }
     );
   }
-  // ==================== PUBLISH TOOLS ====================
+};
+var EnvironmentSession = class extends Session {
+  environment;
+  /** The last known graph container status, updated by checkReadiness() or on heartbeat */
+  graphContainerStatus = null;
+  constructor(client, environment, clientId) {
+    super(client, clientId);
+    this.environment = environment;
+  }
+  get environmentId() {
+    return this.environment.environmentId;
+  }
+  get sandboxId() {
+    return this.environment.sandboxId;
+  }
+  get ontologyId() {
+    return this.environment.ontologyId;
+  }
+  get subjectId() {
+    return this.environment.subjectId;
+  }
+  get envName() {
+    return this.environment.envName;
+  }
+  get versionId() {
+    return this.environment.versionId;
+  }
+  get granularId() {
+    return this.environment.granularId;
+  }
+  get permissionProfileId() {
+    return this.environment.permissionProfileId;
+  }
+  get apiEndpoint() {
+    return this.environment.apiEndpoint;
+  }
+  get data() {
+    return this.environment.data;
+  }
+  get feedback() {
+    return this.environment.feedback;
+  }
   /**
-   * Removed: environment-scoped effect publication is no longer supported.
+   * Return a plain JS snapshot of the synced session heap.
    */
-  async publishTools(tools, revision = "1.0.0") {
-    return super.publishTools(tools, revision);
+  getHeap() {
+    const doc = this.document;
+    return normalizeHeapSnapshot(doc?.heap);
+  }
+  async graphql(query, variables) {
+    return this.environment.graphql(query, variables);
+  }
+  async defineRelationship(options) {
+    return this.environment.defineRelationship(options);
+  }
+  async getRelationships(modelPath) {
+    return this.environment.getRelationships(modelPath);
+  }
+  async attach(modelPath, submodelPath, targetPath) {
+    return this.environment.attach(modelPath, submodelPath, targetPath);
+  }
+  async detach(modelPath, submodelPath, targetPath) {
+    return this.environment.detach(modelPath, submodelPath, targetPath);
+  }
+  async listRelated(modelPath, submodelPath) {
+    return this.environment.listRelated(modelPath, submodelPath);
+  }
+  async applyManifest(manifest) {
+    return this.environment.applyManifest(manifest);
+  }
+  async recordObject(options) {
+    return this.environment.recordObject(options);
+  }
+  async recordObjects(records, options) {
+    return this.environment.recordObjects(records, options);
+  }
+  async enqueueRecordImport(records, options = {}) {
+    return this.environment.enqueueRecordImport(records, options);
+  }
+  async listRecordImports(status) {
+    return this.environment.listRecordImports(status);
+  }
+  async getRecordImportSummary() {
+    return this.environment.getRecordImportSummary();
+  }
+  async getAwaitingRecordCount() {
+    return this.environment.getAwaitingRecordCount();
+  }
+  async getRecordImport(importId) {
+    return this.environment.getRecordImport(importId);
+  }
+  async cancelRecordImport(importId) {
+    return this.environment.cancelRecordImport(importId);
+  }
+  async listFeedback() {
+    return this.environment.listFeedback();
   }
   /**
-   * Removed: environment-scoped effect publication is no longer supported.
+   * Close the session and disconnect from the sandbox.
+   *
+   * Sends `client.goodbye` over WebSocket first, then issues an HTTP fallback
+   * to the runtime goodbye endpoint if no definitive WS-side runtime notify
+   * acknowledgement was observed.
    */
-  async publishEffect(effect) {
-    return super.publishEffect(effect);
+  async disconnect() {
+    let wsNotifiedRuntime = false;
+    try {
+      const goodbye = await this.rpc(
+        "client.goodbye",
+        {
+          timestamp: Date.now()
+        }
+      );
+      wsNotifiedRuntime = Boolean(goodbye?.ok && goodbye?.via);
+    } catch {
+      wsNotifiedRuntime = false;
+    }
+    if (!wsNotifiedRuntime) {
+      try {
+        await fetch(
+          `${this.environment.runtimeBaseUrl}/orchestrator/runtime/environments/${this.environmentId}/session-goodbye`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${this.environment.authToken}`,
+              Connection: "close"
+            },
+            body: JSON.stringify({
+              reason: "sdk_disconnect_http_fallback",
+              sessionId: this.client.currentSessionId
+            })
+          }
+        );
+      } catch {
+      }
+    }
+    this.client.disconnect();
   }
   /**
-   * Removed: environment-scoped effect publication is no longer supported.
+   * Close only the socket transport without sending `client.goodbye`.
    */
-  async publishEffects(effects) {
-    return super.publishEffects(effects);
+  disconnectTransport() {
+    this.client.disconnect();
   }
   /**
-   * Removed: environment-scoped effect publication is no longer supported.
+   * Backwards-compatible alias for `disconnect()`.
    */
-  async unpublishEffect(name) {
-    return super.unpublishEffect(name);
+  async close() {
+    await this.disconnect();
   }
   /**
-   * Removed: environment-scoped effect publication is no longer supported.
+   * Check if the graph container is ready and warm.
    */
-  async unpublishAllEffects() {
-    return super.unpublishAllEffects();
+  async checkReadiness() {
+    const result = await this.client.call("client.heartbeat", {});
+    const containerStatus = result?.graphContainerStatus ?? {
+      lastKeepAliveAt: Date.now(),
+      status: "unknown"
+    };
+    this.graphContainerStatus = containerStatus;
+    this.emit("readiness", containerStatus);
+    return containerStatus;
+  }
+};
+var OntologyHandle = class {
+  granular;
+  ontologyNameOrId;
+  constructor(granular, ontologyNameOrId) {
+    this.granular = granular;
+    this.ontologyNameOrId = ontologyNameOrId;
+  }
+  get effects() {
+    return {
+      register: async (effect) => this.granular.registerEffect(this.ontologyNameOrId, effect),
+      registerMany: async (effects) => this.granular.registerEffects(this.ontologyNameOrId, effects),
+      unregister: async (name) => this.granular.unregisterEffect(this.ontologyNameOrId, name),
+      clear: async () => this.granular.unregisterAllEffects(this.ontologyNameOrId),
+      disconnect: async () => this.granular.disconnectEffects(this.ontologyNameOrId)
+    };
   }
 };
 var Granular = class _Granular {
@@ -12807,7 +13019,9 @@ var Granular = class _Granular {
   constructor(options) {
     const auth = options.token ?? options.apiKey;
     if (!auth) {
-      throw new Error("Granular client requires either apiKey or token. Set GRANULAR_API_KEY or GRANULAR_TOKEN, or pass one in options.");
+      throw new Error(
+        "Granular client requires either apiKey or token. Set GRANULAR_API_KEY or GRANULAR_TOKEN, or pass one in options."
+      );
     }
     this.apiUrl = resolveApiUrl(options.apiUrl, options.endpointMode);
     this.apiKey = resolveAuthTokenForApiUrl(auth, this.apiUrl);
@@ -12817,12 +13031,18 @@ var Granular = class _Granular {
     this.onReconnectError = options.onReconnectError;
     this.httpUrl = this.apiUrl.replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://").replace(/\/ws$/, "");
   }
+  /**
+   * Return an ontology-scoped handle for effects and other ontology-level APIs.
+   */
+  ontology(ontologyNameOrId) {
+    return new OntologyHandle(this, ontologyNameOrId);
+  }
   /**
    * Records/upserts a user and prepares them for sandbox connections
-   * 
+   *
    * @param options - User options
    * @returns The recorded user with both `userId` and `granularId`
-   * 
+   *
    * @example
    * ```typescript
    * const user = await granular.recordUser({
@@ -12833,14 +13053,16 @@ var Granular = class _Granular {
    * ```
    */
   async recordUser(options) {
-    const subject = normalizeSubject(await this.request("/control/subjects", {
-      method: "POST",
-      body: JSON.stringify({
-        identityId: options.userId,
-        name: options.name,
-        email: options.email
+    const subject = normalizeSubject(
+      await this.request("/control/subjects", {
+        method: "POST",
+        body: JSON.stringify({
+          identityId: options.userId,
+          name: options.name,
+          email: options.email
+        })
       })
-    }));
+    );
     return normalizeUser({
       granularId: subject.granularId,
       userId: options.userId,
@@ -12851,7 +13073,23 @@ var Granular = class _Granular {
       permissions: options.permissions || []
     });
   }
+  /**
+   * Alias for `recordUser()` with user-facing naming that matches upsert semantics.
+   */
+  async upsertUser(options) {
+    return this.recordUser(options);
+  }
   async resolveConnectUser(options) {
+    const providedIdentityCount = [
+      Boolean(options.user),
+      Boolean(options.userId),
+      Boolean(options.granularId)
+    ].filter(Boolean).length;
+    if (providedIdentityCount !== 1) {
+      throw new Error(
+        "openEnvironment() requires exactly one of userId, granularId, or a user object returned by recordUser()."
+      );
+    }
     if (options.user) {
       const user = normalizeUser(options.user);
       return {
@@ -12887,76 +13125,141 @@ var Granular = class _Granular {
         permissions: options.permissions || []
       };
     }
-    throw new Error("connect() requires either userId, granularId, or a user object returned by recordUser().");
+    throw new Error(
+      "openEnvironment() requires either userId, granularId, or a user object returned by recordUser()."
+    );
   }
   /**
-   * Connect to an ontology environment and establish a real-time session.
-   * 
-   * Effects are registered at the sandbox level via `granular.registerEffect()`
-   * or `granular.registerEffects()`. Sessions pick up live availability from
-   * the sandbox registry automatically.
-   * 
-   * @param options - Connection options
-   * @returns An active environment session
-   * 
+   * Open or resolve an ontology environment for one user without opening a session.
+   *
    * @example
    * ```typescript
-   * const environment = await granular.connect({
+   * const environment = await granular.openEnvironment({
    *   ontology: 'my-ontology',
-   *   environment: 'dev',
+   *   tag: 'dev',
    *   userId: 'user_123',
    *   permissions: ['agent'],
    * });
-   * 
-   * await granular.registerEffect('my-sandbox', {
-   *   name: 'greet',
-   *   description: 'Say hello',
-   *   inputSchema: { type: 'object', properties: {} },
-   *   handler: async () => 'Hello!',
+   *
+   * await environment.data.record({
+   *   className: 'customer',
+   *   id: 'acme',
+   *   fields: { name: 'Acme' },
    * });
-   * 
-   * // Submit job
-   * const job = await environment.submitJob(`
-   *   import { tools } from './sandbox-tools';
-   *   return await tools.greet({});
-   * `);
-   * 
-   * console.log(await job.result); // 'Hello!'
+   *
+   * const session = await environment.sessions.create();
+   * const job = await session.submitJob(`return "hello";`);
+   * console.log(await job.result);
    * ```
-  */
+   */
+  async openEnvironment(options) {
+    const envData = await this.resolveOpenEnvironmentData(
+      options,
+      "openEnvironment"
+    );
+    return this.bindEnvironmentHandle(envData);
+  }
+  /**
+   * Deprecated compatibility alias for `openEnvironment()`.
+   *
+   * `connect()` no longer opens a runtime session automatically.
+   */
   async connect(options) {
-    const clientId = options.clientId || `client_${Date.now()}`;
+    return this.openEnvironment({
+      ...options,
+      tag: this.resolveRequestedTag(options, "connect"),
+      permissions: options.permissions || options.user?.permissions || []
+    });
+  }
+  resolveRequestedTag(options, methodName) {
+    const tag = options.tag?.trim() || options.tagName?.trim() || options.environment?.trim();
+    if (!tag) {
+      throw new Error(`${methodName}() requires \`tag\`.`);
+    }
+    return tag;
+  }
+  buildManagedEnvironmentName(tag, versionId) {
+    return `__sdk__${tag}__${versionId}`;
+  }
+  matchesTagTrackedEnvironment(environment, tagName, tagId) {
+    const environmentTagName = environment.tag?.name || environment.buildPolicy.tagName || null;
+    return environment.tagId === tagId || environmentTagName === tagName || environment.environment === tagName || environment.envName === tagName || environment.environment === this.buildManagedEnvironmentName(tagName, environment.versionId) || environment.envName === this.buildManagedEnvironmentName(tagName, environment.versionId);
+  }
+  sortEnvironmentsByRecency(environments) {
+    return [...environments].sort(
+      (left, right) => right.updatedAt - left.updatedAt
+    );
+  }
+  async resolveOpenEnvironmentData(options, methodName) {
     const ontology = options.ontology;
     if (!ontology) {
-      throw new Error("connect() requires `ontology`.");
+      throw new Error(`${methodName}() requires \`ontology\`.`);
     }
-    const environmentName = options.environment;
-    if (!environmentName) {
-      throw new Error("connect() requires `environment`.");
+    const tagName = options.tag?.trim();
+    if (!tagName) {
+      throw new Error(`${methodName}() requires \`tag\`.`);
     }
-    const tagName = options.tagName?.trim() || void 0;
     const user = await this.resolveConnectUser(options);
+    if (!Array.isArray(user.permissions) || user.permissions.length === 0) {
+      throw new Error(
+        `${methodName}() requires at least one permission so the SDK can ensure assignments for new users.`
+      );
+    }
     const sandbox = await this.findOrCreateSandbox(ontology);
     for (const profileName of user.permissions) {
-      const profileId = await this.ensurePermissionProfile(sandbox.sandboxId, profileName);
-      await this.ensureAssignment(user.granularId, sandbox.sandboxId, profileId);
+      const profileId = await this.ensurePermissionProfile(
+        sandbox.sandboxId,
+        profileName
+      );
+      await this.ensureAssignment(
+        user.granularId,
+        sandbox.sandboxId,
+        profileId
+      );
+    }
+    const tags = await this.request(
+      `/control/sandboxes/${sandbox.sandboxId}/tags`
+    );
+    const tag = (tags.items || []).find(
+      (candidate) => Boolean(candidate?.name === tagName)
+    );
+    if (!tag) {
+      throw new Error(
+        `Tag "${tagName}" was not found for ontology ${sandbox.sandboxId}.`
+      );
+    }
+    const targetVersionId = tag.targetVersionId || tag.targetBuildId;
+    if (!targetVersionId) {
+      throw new Error(
+        `Tag "${tagName}" does not currently point to a build/version.`
+      );
+    }
+    const allEnvironments = await this.environments.list(sandbox.sandboxId);
+    const userEnvironments = allEnvironments.filter(
+      (environment) => environment.subjectId === user.granularId
+    );
+    const currentMatches = this.sortEnvironmentsByRecency(
+      userEnvironments.filter(
+        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag.tagId) && environment.versionId === targetVersionId
+      )
+    );
+    if (currentMatches.length > 0) {
+      return currentMatches[0];
+    }
+    const outdatedMatches = this.sortEnvironmentsByRecency(
+      userEnvironments.filter(
+        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag.tagId)
+      )
+    );
+    if (outdatedMatches.length > 0 && options.createFreshIfOutdated !== true) {
+      return outdatedMatches[0];
     }
-    const envData = await this.environments.create(sandbox.sandboxId, {
+    return this.environments.create(sandbox.sandboxId, {
       subjectId: user.granularId,
-      environment: environmentName,
-      tagName,
+      environment: this.buildManagedEnvironmentName(tagName, targetVersionId),
+      tagId: tag.tagId,
       permissionProfileId: null
     });
-    await this.activateEnvironment(envData.environmentId);
-    const session = await this.request("/ws/sessions", {
-      method: "POST",
-      body: JSON.stringify({
-        environmentId: envData.environmentId,
-        clientId,
-        initialHeap: options.initialHeap
-      })
-    });
-    return this.bindWebSocketEnvironment(envData, clientId, session);
   }
   /**
    * List active (open) sessions for an environment — each session is one agent conversation thread.
@@ -12991,7 +13294,9 @@ var Granular = class _Granular {
       createdAt: _Granular.coerceIsoDate(row.createdAt ?? row.created_at),
       lastSeenAt: _Granular.coerceIsoDate(row.lastSeenAt ?? row.last_seen_at),
       summary: row.summary != null ? String(row.summary) : null,
-      summaryUpdatedAt: row.summaryUpdatedAt != null || row.summary_updated_at != null ? _Granular.coerceIsoDate(row.summaryUpdatedAt ?? row.summary_updated_at) : null,
+      summaryUpdatedAt: row.summaryUpdatedAt != null || row.summary_updated_at != null ? _Granular.coerceIsoDate(
+        row.summaryUpdatedAt ?? row.summary_updated_at
+      ) : null,
       subjectId: row.subjectId != null ? String(row.subjectId) : null,
       jobCount: typeof row.jobCount === "number" ? row.jobCount : void 0,
       toolCallCount: typeof row.toolCallCount === "number" ? row.toolCallCount : void 0
@@ -13017,6 +13322,7 @@ var Granular = class _Granular {
     const clientId = options.clientId || `client_${Date.now()}`;
     await this.activateEnvironment(options.environmentId);
     const envData = await this.environments.get(options.environmentId);
+    const environment = this.bindEnvironmentHandle(envData);
     const session = await this.request("/ws/sessions", {
       method: "POST",
       body: JSON.stringify({
@@ -13025,7 +13331,7 @@ var Granular = class _Granular {
         initialHeap: options.initialHeap
       })
     });
-    return this.bindWebSocketEnvironment(envData, clientId, session);
+    return this.bindWebSocketEnvironmentSession(environment, clientId, session);
   }
   /**
    * Connect to an existing open session (same conversation thread) using a freshly minted WebSocket token.
@@ -13037,7 +13343,8 @@ var Granular = class _Granular {
       body: JSON.stringify({})
     });
     const envData = await this.environments.get(minted.environmentId);
-    return this.bindWebSocketEnvironment(envData, clientId, minted);
+    const environment = this.bindEnvironmentHandle(envData);
+    return this.bindWebSocketEnvironmentSession(environment, clientId, minted);
   }
   /**
    * Mark a session closed in the control plane. If `environment` is the connected handle for that
@@ -13069,7 +13376,11 @@ var Granular = class _Granular {
     });
     return this.connectSession({ sessionId, clientId: options?.clientId });
   }
-  async bindWebSocketEnvironment(envData, clientId, session) {
+  bindEnvironmentHandle(envData) {
+    const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
+    return new Environment(this, envData, this.apiKey, graphqlEndpoint);
+  }
+  async bindWebSocketEnvironmentSession(environment, clientId, session) {
     const client = new WSClient({
       url: session.wsUrl,
       sessionId: session.sessionId,
@@ -13080,10 +13391,13 @@ var Granular = class _Granular {
       onReconnectError: this.onReconnectError
     });
     await client.connect();
-    const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
-    const environment = new Environment(client, envData, clientId, this.apiKey, graphqlEndpoint);
-    await environment.hello();
-    return environment;
+    const environmentSession = new EnvironmentSession(
+      client,
+      environment,
+      clientId
+    );
+    await environmentSession.hello();
+    return environmentSession;
   }
   async activateEnvironment(environmentId) {
     await this.request(`/orchestrator/runtime/environments/${environmentId}/activate`, {
@@ -13115,14 +13429,18 @@ var Granular = class _Granular {
     };
   }
   async publishSandboxEffectCatalog(host) {
-    const effects = Array.from(this.getSandboxEffectMap(host.sandboxId).values()).map(
-      (effect) => this.serializeEffect(effect)
-    );
-    const result = await host.wsClient.call("effects.publishCatalog", { effects });
+    const effects = Array.from(
+      this.getSandboxEffectMap(host.sandboxId).values()
+    ).map((effect) => this.serializeEffect(effect));
+    const result = await host.wsClient.call("effects.publishCatalog", {
+      effects
+    });
     const acceptedCount = typeof result?.acceptedCount === "number" ? result.acceptedCount : 0;
     const rejected = Array.isArray(result?.rejected) ? result.rejected : [];
     if (acceptedCount === 0 && rejected.length > 0) {
-      const detail = rejected.map((entry) => `${entry.name || "unknown"}: ${entry.reason || "rejected"}`).join("; ");
+      const detail = rejected.map(
+        (entry) => `${entry.name || "unknown"}: ${entry.reason || "rejected"}`
+      ).join("; ");
       throw new Error(
         `Failed to publish live effects for sandbox ${host.sandboxId}: ${detail}`
       );
@@ -13156,13 +13474,15 @@ var Granular = class _Granular {
         disconnectError
       );
     }
-    void this.ensureSandboxEffectHost(host.sandboxId).catch((reconnectError) => {
-      console.error(
-        `[Granular] Failed to recover effect host for sandbox ${host.sandboxId} after heartbeat failure:`,
-        reconnectError
-      );
-      console.error("[Granular] Original heartbeat failure:", error);
-    });
+    void this.ensureSandboxEffectHost(host.sandboxId).catch(
+      (reconnectError) => {
+        console.error(
+          `[Granular] Failed to recover effect host for sandbox ${host.sandboxId} after heartbeat failure:`,
+          reconnectError
+        );
+        console.error("[Granular] Original heartbeat failure:", error);
+      }
+    );
   }
   startEffectHostHeartbeat(host) {
     if (host.heartbeatTimer) {
@@ -13183,9 +13503,15 @@ var Granular = class _Granular {
         host.heartbeatInFlight = false;
       });
     };
-    sendHeartbeat("[Granular] Initial effect host heartbeat failed for sandbox", false);
+    sendHeartbeat(
+      "[Granular] Initial effect host heartbeat failed for sandbox",
+      false
+    );
     host.heartbeatTimer = setInterval(() => {
-      sendHeartbeat("[Granular] Effect host heartbeat failed for sandbox", true);
+      sendHeartbeat(
+        "[Granular] Effect host heartbeat failed for sandbox",
+        true
+      );
     }, 1e4);
   }
   stopEffectHostHeartbeat(host) {
@@ -13217,7 +13543,12 @@ var Granular = class _Granular {
       const effectClientId = crypto.randomUUID();
       const clientId = `effect-host:${sandboxId}:${effectClientId}`;
       const wsClient = new WSClient({
-        url: buildEffectHostUrl(this.apiUrl, sandboxId, effectClientId, clientId),
+        url: buildEffectHostUrl(
+          this.apiUrl,
+          sandboxId,
+          effectClientId,
+          clientId
+        ),
         sessionId: `effect-host:${effectClientId}`,
         token: this.apiKey,
         tokenProvider: this.tokenProvider,
@@ -13236,7 +13567,10 @@ var Granular = class _Granular {
       };
       wsClient.registerRpcHandler("effect.invoke", async (params) => {
         const request = params;
-        return invokeRegisteredEffect(this.getSandboxEffectMap(sandboxId), request);
+        return invokeRegisteredEffect(
+          this.getSandboxEffectMap(sandboxId),
+          request
+        );
       });
       wsClient.on("open", () => {
         void this.synchronizeEffectHost(host).catch((error) => {
@@ -13284,7 +13618,7 @@ var Granular = class _Granular {
   }
   /**
    * Register multiple effects (tools) for a specific sandbox.
-   * 
+   *
    * batch version of `registerEffect`.
    */
   async registerEffects(sandboxNameOrId, effects) {
@@ -13298,7 +13632,7 @@ var Granular = class _Granular {
   }
   /**
    * Unregister an effect from a sandbox.
-   * 
+   *
    * Removes it from the local sandbox registry and updates the
    * sandbox-scoped live catalog.
    */
@@ -13397,27 +13731,31 @@ var Granular = class _Granular {
       const assignments = await this.request(
         `/control/subjects/${subjectId}/assignments`
       );
-      const existing = assignments.items.find(
-        (a) => a.sandboxId === sandboxId
-      );
+      const existing = assignments.items.find((a) => a.sandboxId === sandboxId);
       if (existing) {
         if (existing.permissionProfileId === permissionProfileId) {
           return;
         }
-        await this.request(`/control/assignments/${existing.assignmentId}`, {
-          method: "DELETE"
-        });
+        await this.request(
+          `/control/assignments/${existing.assignmentId}`,
+          {
+            method: "DELETE"
+          }
+        );
       }
     } catch {
     }
-    await this.request(`/control/subjects/${subjectId}/assignments`, {
-      method: "POST",
-      body: JSON.stringify({
-        sandboxId,
-        subjectId,
-        permissionProfileId
-      })
-    });
+    await this.request(
+      `/control/subjects/${subjectId}/assignments`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          sandboxId,
+          subjectId,
+          permissionProfileId
+        })
+      }
+    );
   }
   /**
    * Sandbox management API
@@ -13497,23 +13835,33 @@ var Granular = class _Granular {
       },
       get: async (environmentId) => {
         return normalizeEnvironmentData(
-          await this.request(`/control/environments/${environmentId}`)
+          await this.request(
+            `/control/environments/${environmentId}`
+          )
         );
       },
       create: async (sandboxId, data) => {
         const environmentName = data.environment || data.envName;
-        return normalizeEnvironmentData(await this.request(`/control/sandboxes/${sandboxId}/environments`, {
-          method: "POST",
-          body: JSON.stringify({
-            ...data,
-            envName: environmentName
-          })
-        }));
+        return normalizeEnvironmentData(
+          await this.request(
+            `/control/sandboxes/${sandboxId}/environments`,
+            {
+              method: "POST",
+              body: JSON.stringify({
+                ...data,
+                envName: environmentName
+              })
+            }
+          )
+        );
       },
       delete: async (environmentId) => {
-        return this.request(`/control/environments/${environmentId}`, {
-          method: "DELETE"
-        });
+        return this.request(
+          `/control/environments/${environmentId}`,
+          {
+            method: "DELETE"
+          }
+        );
       }
     };
   }
@@ -13533,10 +13881,13 @@ var Granular = class _Granular {
         }
         if (params.since) query.set("since", params.since.toISOString());
         if (params.until) query.set("until", params.until.toISOString());
-        if (params.isAcked !== void 0) query.set("isAcked", params.isAcked ? "1" : "0");
+        if (params.isAcked !== void 0)
+          query.set("isAcked", params.isAcked ? "1" : "0");
         if (params.limit) query.set("limit", String(params.limit));
         if (params.offset) query.set("offset", String(params.offset));
-        const result = await this.request(`/control/stream-events?${query.toString()}`);
+        const result = await this.request(
+          `/control/stream-events?${query.toString()}`
+        );
         return (result.items || []).map((row) => ({
           eventId: row.event_id,
           streamName: row.stream_name,
@@ -13567,7 +13918,9 @@ var Granular = class _Granular {
                 since: cursor,
                 limit: 100
               });
-              const orderedEvents = [...events].sort((a, b) => a.createdAt - b.createdAt);
+              const orderedEvents = [...events].sort(
+                (a, b) => a.createdAt - b.createdAt
+              );
               for (const event of orderedEvents) {
                 if (seenEventIds.has(event.eventId)) {
                   continue;
@@ -13580,15 +13933,19 @@ var Granular = class _Granular {
                 params.onEvent(event);
               }
             } catch (err) {
-              params.onError?.(err instanceof Error ? err : new Error(String(err)));
+              params.onError?.(
+                err instanceof Error ? err : new Error(String(err))
+              );
             }
             await new Promise((resolve) => setTimeout(resolve, interval));
           }
         };
         poll();
-        return { unsubscribe: () => {
-          running = false;
-        } };
+        return {
+          unsubscribe: () => {
+            running = false;
+          }
+        };
       },
       ack: async (eventId) => {
         await this.request("/control/stream-events/ack", {
@@ -13606,7 +13963,9 @@ var Granular = class _Granular {
         const sandbox = await this._resolveSandboxId(params.ontology);
         const query = new URLSearchParams({ sandboxId: sandbox });
         if (params.environment) query.set("environmentId", params.environment);
-        const result = await this.request(`/control/stream-events/stats?${query.toString()}`);
+        const result = await this.request(
+          `/control/stream-events/stats?${query.toString()}`
+        );
         return (result.items || []).map((row) => ({
           streamName: row.stream_name,
           eventType: row.event_type,
@@ -13624,10 +13983,14 @@ var Granular = class _Granular {
   get subjects() {
     return {
       get: async (subjectId) => {
-        return normalizeSubject(await this.request(`/control/subjects/${subjectId}`));
+        return normalizeSubject(
+          await this.request(`/control/subjects/${subjectId}`)
+        );
       },
       listAssignments: async (subjectId) => {
-        return this.request(`/control/subjects/${subjectId}/assignments`);
+        return this.request(
+          `/control/subjects/${subjectId}/assignments`
+        );
       }
     };
   }
@@ -13637,24 +14000,31 @@ var Granular = class _Granular {
   get users() {
     return {
       create: async (data) => {
-        return normalizeSubject(await this.request("/control/subjects", {
-          method: "POST",
-          body: JSON.stringify({
-            identityId: data.id,
-            name: data.name,
-            email: data.email
+        return normalizeSubject(
+          await this.request("/control/subjects", {
+            method: "POST",
+            body: JSON.stringify({
+              identityId: data.id,
+              name: data.name,
+              email: data.email
+            })
           })
-        }));
+        );
       },
       get: async (id) => {
-        return normalizeSubject(await this.request(`/control/subjects/${id}`));
+        return normalizeSubject(
+          await this.request(`/control/subjects/${id}`)
+        );
       }
     };
   }
   async _resolveSandboxId(ontologyNameOrId) {
     if (ontologyNameOrId.startsWith("sbx_")) return ontologyNameOrId;
-    const result = await this.request(`/control/sandboxes?name=${encodeURIComponent(ontologyNameOrId)}`);
-    if (result.items.length === 0) throw new Error(`Ontology not found: ${ontologyNameOrId}`);
+    const result = await this.request(
+      `/control/sandboxes?name=${encodeURIComponent(ontologyNameOrId)}`
+    );
+    if (result.items.length === 0)
+      throw new Error(`Ontology not found: ${ontologyNameOrId}`);
     return result.items[0].sandboxId;
   }
   /**
@@ -13669,9 +14039,9 @@ var Granular = class _Granular {
       const response = await fetch(url, {
         ...options,
         headers: {
-          "Authorization": `Bearer ${this.apiKey}`,
+          Authorization: `Bearer ${this.apiKey}`,
           "Content-Type": "application/json",
-          "Connection": "close",
+          Connection: "close",
           ...options.headers
         }
       });
@@ -13682,7 +14052,11 @@ var Granular = class _Granular {
         return response.json();
       }
       const errorText = await response.text();
-      const retryable = isRetryableLocalWorkerRestart(response.status, errorText, url);
+      const retryable = isRetryableLocalWorkerRestart(
+        response.status,
+        errorText,
+        url
+      );
       if (retryable && attempt < LOCAL_CONTROL_REQUEST_RETRY_COUNT) {
         if (this.debugHttp) {
           console.warn(
@@ -13821,21 +14195,6 @@ function reviewGeneratedJobCode(code) {
         message: "After await loop.ask_user(...) returns a usable answer, continue the workflow in the same resumed run instead of stopping with placeholder text about doing the work later."
       });
     }
-    const askUserCalls = normalized.match(/await\s+loop\.ask_user\s*\(\s*\{[\s\S]*?\}\s*\)/g) || [];
-    for (const call of askUserCalls) {
-      const usesChoiceType = /type\s*:\s*['"]choice['"]/.test(call);
-      const usesInputType = /type\s*:\s*['"]input['"]/.test(call);
-      const hasDisambiguationLanguage = /(which|choose|pick|select)/i.test(call) && /(invoice|order|shipment|request|case|work[\s_-]?order)/i.test(call);
-      const includesShortlistOptions = /options\s*:\s*\[/.test(call);
-      if (!usesChoiceType && (usesInputType || hasDisambiguationLanguage || includesShortlistOptions)) {
-        issues.push({
-          code: "disambiguation_requires_choice",
-          severity: "error",
-          message: "When asking the user to choose between known concrete records such as invoices, orders, shipments, requests, cases, or work orders, use loop.ask_user({ type: 'choice', options: [...] }) with a short explicit shortlist instead of a free-text input."
-        });
-        break;
-      }
-    }
   }
   const hasConversationalReturn = /return\s+[`'"]/.test(normalized) || /\breply\s*:/.test(normalized) || /\bagent_message\s*\(/.test(normalized) || /\bagent_text_message\s*\(/.test(normalized);
   const returnsObjectLiteral = /return\s+\{[\s\S]*?\}/.test(normalized);
@@ -13881,6 +14240,184 @@ function extractFocusHintsFromActionSummary(actionSummaryLines) {
     entryPaths: uniqueStrings(entryPaths, 8)
   };
 }
+function normalizeActionSummaryForPrompt(line) {
+  return line.replace(/\blimit=/g, "perPage=").replace(/\blimit:/g, "perPage:");
+}
+function collectConversationReferents(liveDoc) {
+  const conversation = asRecord2(liveDoc?.conversation);
+  const persistedReferents = asArray(conversation?.referents).map((value) => asRecord2(value)).filter((value) => Boolean(value));
+  if (persistedReferents.length > 0) {
+    return persistedReferents.slice().sort((left, right) => (right.ts || 0) - (left.ts || 0));
+  }
+  const heap = asRecord2(liveDoc?.heap);
+  const entriesByPath = asRecord2(heap?.entriesByPath) || {};
+  const listsByName = asRecord2(heap?.listsByName) || {};
+  const variablesByName = asRecord2(heap?.variablesByName) || {};
+  const messages = asArray(conversation?.messages).map((value) => asRecord2(value)).filter((value) => Boolean(value)).slice().sort((left, right) => (Number(right.ts) || 0) - (Number(left.ts) || 0));
+  const referents = [];
+  const seen = /* @__PURE__ */ new Set();
+  const pushReferent = (referent) => {
+    if (!referent?.kind || !referent.ref) return;
+    const key = `${referent.kind}:${referent.ref}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    referents.push(referent);
+  };
+  for (const message of messages) {
+    if (message.role !== "assistant") continue;
+    const show = asRecord2(message.show);
+    if (!show) continue;
+    const ts = Number(message.ts) || 0;
+    const messageId = typeof message.id === "string" ? message.id : void 0;
+    const jobId = typeof message.jobId === "string" ? message.jobId : void 0;
+    for (const entryPath of uniqueStrings(asArray(show.entryPaths))) {
+      const entry = asRecord2(entriesByPath[entryPath]);
+      pushReferent({
+        id: `entry:${entryPath}`,
+        kind: "entry",
+        ref: entryPath,
+        entryPath,
+        className: typeof entry?.className === "string" ? entry.className : void 0,
+        label: typeof entry?.label === "string" && entry.label.trim() ? entry.label.trim() : typeof entry?.id === "string" && entry.id.trim() ? entry.id.trim() : entryPath,
+        messageId,
+        jobId,
+        ts
+      });
+    }
+    for (const listName of uniqueStrings(asArray(show.listNames))) {
+      const list = asRecord2(listsByName[listName]);
+      pushReferent({
+        id: `list:${listName}`,
+        kind: "list",
+        ref: listName,
+        listName,
+        className: typeof list?.className === "string" ? list.className : void 0,
+        count: Array.isArray(list?.paths) ? list.paths.length : null,
+        messageId,
+        jobId,
+        ts
+      });
+    }
+    for (const variableName of uniqueStrings(
+      asArray(show.variableNames)
+    )) {
+      const variable = asRecord2(variablesByName[variableName]);
+      const entryPath = typeof variable?.entryPath === "string" ? variable.entryPath : void 0;
+      const listName = typeof variable?.listName === "string" ? variable.listName : void 0;
+      const entry = entryPath ? asRecord2(entriesByPath[entryPath]) : null;
+      const list = listName ? asRecord2(listsByName[listName]) : null;
+      pushReferent({
+        id: `variable:${variableName}`,
+        kind: "variable",
+        ref: variableName,
+        variableName,
+        variableKind: typeof variable?.kind === "string" ? variable.kind : void 0,
+        entryPath,
+        listName,
+        className: typeof variable?.className === "string" ? variable.className : typeof entry?.className === "string" ? entry.className : typeof list?.className === "string" ? list.className : void 0,
+        label: typeof entry?.label === "string" && entry.label.trim() ? entry.label.trim() : typeof entry?.id === "string" && entry.id.trim() ? entry.id.trim() : null,
+        count: variable?.kind === "list" && Array.isArray(list?.paths) ? list.paths.length : null,
+        scalarValue: variable?.kind === "scalar" && (typeof variable.value === "string" || typeof variable.value === "number" || typeof variable.value === "boolean" || variable.value === null) ? variable.value : void 0,
+        messageId,
+        jobId,
+        ts
+      });
+    }
+  }
+  return referents;
+}
+function projectConversationReferentFocus(liveDoc) {
+  const heap = asRecord2(liveDoc?.heap);
+  const listsByName = asRecord2(heap?.listsByName) || {};
+  const referents = collectConversationReferents(liveDoc);
+  const entryPaths = [];
+  const listNames = [];
+  const variableNames = [];
+  for (const referent of referents.slice(0, 8)) {
+    if (referent.kind === "entry" && typeof referent.entryPath === "string") {
+      entryPaths.push(referent.entryPath);
+      continue;
+    }
+    if (referent.kind === "list" && typeof referent.listName === "string") {
+      listNames.push(referent.listName);
+      const list = asRecord2(listsByName[referent.listName]);
+      entryPaths.push(...asArray(list?.paths).slice(0, 4));
+      continue;
+    }
+    if (referent.kind === "variable" && typeof referent.variableName === "string") {
+      variableNames.push(referent.variableName);
+      if (typeof referent.entryPath === "string") {
+        entryPaths.push(referent.entryPath);
+      }
+      if (typeof referent.listName === "string") {
+        listNames.push(referent.listName);
+        const list = asRecord2(listsByName[referent.listName]);
+        entryPaths.push(...asArray(list?.paths).slice(0, 4));
+      }
+    }
+  }
+  return {
+    entryPaths: uniqueStrings(entryPaths, 8),
+    listNames: uniqueStrings(listNames, 4),
+    variableNames: uniqueStrings(variableNames, 4)
+  };
+}
+function projectConversationReferentSummary(liveDoc) {
+  const referents = collectConversationReferents(liveDoc).slice(0, 8);
+  if (referents.length === 0) {
+    return "No recent referents recorded from prior assistant replies.";
+  }
+  const entryLines = [];
+  const listLines = [];
+  const variableLines = [];
+  for (const referent of referents) {
+    if (referent.kind === "entry" && referent.entryPath) {
+      const label = referent.label || referent.entryPath;
+      const classLabel = referent.className || "unknown";
+      entryLines.push(`- ${label} <${referent.entryPath}> [${classLabel}]`);
+      continue;
+    }
+    if (referent.kind === "list" && referent.listName) {
+      const classLabel = referent.className || "unknown";
+      const countLabel = typeof referent.count === "number" ? referent.count : "?";
+      listLines.push(
+        `- ${referent.listName}: list<${classLabel}> -> ${countLabel} item(s)`
+      );
+      continue;
+    }
+    if (referent.kind === "variable" && referent.variableName) {
+      if (referent.variableKind === "entry" && referent.entryPath && referent.className) {
+        const label = referent.label || referent.entryPath;
+        variableLines.push(
+          `- ${referent.variableName}: entry<${referent.className}> -> ${label} <${referent.entryPath}>`
+        );
+        continue;
+      }
+      if (referent.variableKind === "list" && referent.listName && referent.className) {
+        const countLabel = typeof referent.count === "number" ? referent.count : "?";
+        variableLines.push(
+          `- ${referent.variableName}: list<${referent.className}> -> ${countLabel} item(s) via ${referent.listName}`
+        );
+        continue;
+      }
+      if (referent.variableKind === "scalar") {
+        variableLines.push(
+          `- ${referent.variableName}: scalar = ${formatScalar(referent.scalarValue)}`
+        );
+        continue;
+      }
+      variableLines.push(`- ${referent.variableName}`);
+    }
+  }
+  const lines = [];
+  lines.push("Entries:");
+  lines.push(...entryLines.length > 0 ? entryLines : ["- none"]);
+  lines.push("", "Lists:");
+  lines.push(...listLines.length > 0 ? listLines : ["- none"]);
+  lines.push("", "Variables:");
+  lines.push(...variableLines.length > 0 ? variableLines : ["- none"]);
+  return lines.join("\n");
+}
 function getCurrentClosureId(liveDoc) {
   const loop = asRecord2(liveDoc?.loop);
   return typeof loop?.currentClosureId === "string" ? loop.currentClosureId : null;
@@ -14093,7 +14630,9 @@ function projectWorkflowFocus(liveDoc, pendingPrompts = [], options) {
     variableNames: uniqueStrings(variableNames, 4),
     listNames: uniqueStrings(listNames, 4),
     entryPaths: uniqueStrings(entryPaths, 6),
-    recentActionSummary: uniqueStrings(actionSummaryLines, 8)
+    recentActionSummary: uniqueStrings(actionSummaryLines, 8).map(
+      normalizeActionSummaryForPrompt
+    )
   };
 }
 function projectWorkflowSummary(liveDoc, pendingPrompts = [], options) {
@@ -14490,17 +15029,14 @@ ${resultPreview}` : null
   ].filter(Boolean).join("\n\n");
 }
 function buildGranularAgentDomainBlock(domainDocumentation) {
-  return domainDocumentation?.trim() || "No domain types available. The graph may not be ready yet.";
+  return domainDocumentation?.trim() || "No domain reference available. The graph may not be ready yet.";
 }
 function buildGranularAgentSessionBlock(sessionContext) {
   if (!sessionContext) return "No session metadata available.";
   const rows = [
     ["sandboxId", sessionContext.sandboxId],
     ["environmentId", sessionContext.environmentId],
-    ["userId", sessionContext.userId],
-    ["granularId", sessionContext.granularId],
-    ["userName", sessionContext.userName],
-    ["domainRevision", sessionContext.domainRevision]
+    ["userName", sessionContext.userName]
   ];
   const activeRows = rows.filter(([, value]) => Boolean(value));
   if (activeRows.length === 0) return "No session metadata available.";
@@ -14509,6 +15045,9 @@ function buildGranularAgentSessionBlock(sessionContext) {
 function buildGranularAgentHeapBlock(heapSummary) {
   return heapSummary?.trim() || "Heap is empty for this session.";
 }
+function buildGranularAgentReferentBlock(referentSummary) {
+  return referentSummary?.trim() || "No recent referents recorded from prior assistant replies.";
+}
 function buildGranularAgentLoopBlock(loopSummary) {
   return loopSummary?.trim() || "No active loop state recorded for this session.";
 }
@@ -14532,7 +15071,7 @@ function buildGranularAgentToolBlock(tools) {
     (tool) => Boolean(tool.className && !tool.static)
   );
   const lines = [
-    "Treat this block as the planning map. Use DOMAIN TYPES below for exact signatures."
+    "Treat this block as the planning map. Use DOMAIN REFERENCE below for exact signatures and query examples."
   ];
   const appendGroup = (title, group) => {
     lines.push(`- ${title}:`);
@@ -14580,7 +15119,10 @@ function buildGranularAgentCheckpointBlock(checkpoint) {
   if (Array.isArray(checkpoint.latestActionSummary) && checkpoint.latestActionSummary.length > 0) {
     lines.push("latestActionSummary:");
     for (const line of checkpoint.latestActionSummary.slice(0, 8)) {
-      lines.push(line.startsWith("- ") ? line : `- ${line}`);
+      const normalizedLine = normalizeActionSummaryForPrompt(line);
+      lines.push(
+        normalizedLine.startsWith("- ") ? normalizedLine : `- ${normalizedLine}`
+      );
     }
   }
   if (checkpoint.latestJobResult?.trim()) {
@@ -14596,9 +15138,10 @@ function buildGranularAgentSystemPrompt(input) {
   const workflowBlock = buildGranularAgentWorkflowBlock(input.workflowSummary);
   const checkpointBlock = buildGranularAgentCheckpointBlock(input.checkpoint);
   const heapBlock = buildGranularAgentHeapBlock(input.heapSummary);
+  const referentBlock = buildGranularAgentReferentBlock(input.referentSummary);
   const loopBlock = buildGranularAgentLoopBlock(input.loopSummary);
   return `You are an AI assistant for a live Granular session.
-You can help the user understand the domain, answer questions, or generate and execute TypeScript code.
+You can help the user understand the domain, answer questions, or generate and execute code against the live session.
 Your tone must be natural and human-like.
 
 Call the \`execute_code\` effect ONLY when the user's intent matches the domain's capabilities and requires executing code against the live session. If the user is just asking a general question or if their request doesn't match the available effects or domain types, respond with text to explain.
@@ -14607,6 +15150,8 @@ When you call \`execute_code\`, additional assistant text must be either:
 - a brief summary of the actions the generated code will perform.
 Do not include any other kind of commentary when calling \`execute_code\`.
 - If the next step needs to create or update workflow state in the live session, you must call \`execute_code\`. This includes \`loop.ask_user(...)\`, \`loop.confirm(...)\`, \`loop.open_decision(...)\`, \`loop.close_decision(...)\`, \`loop.create_task(...)\`, \`loop.update_task(...)\`, \`loop.complete_task(...)\`, and \`loop.close_loop(...)\`.
+- If the next step is an interactive clarification that should be resumable in the live workflow, you must call \`execute_code\`. A missing preference, rule, metric, target, or option selection is not a plain-text reply when the answer should drive the next live step.
+- If you can offer a short grounded shortlist, that clarification should usually be \`loop.ask_user({ type: 'choice', ... })\` instead of a plain-text question with bullet options.
 - Never simulate a live prompt, confirmation, decision, task change, or loop closure in plain text. Plain-text replies are only for conversational answers that do not need to mutate session state.
 
 \u2500\u2500\u2500 STREAMING COMMENT RULES \u2500\u2500\u2500
@@ -14626,6 +15171,7 @@ Do not include any other kind of commentary when calling \`execute_code\`.
 - Do not say "sandbox" in user-facing text unless the user is explicitly asking about the runtime environment itself.
 - If you need clarification, ask in everyday language.
 - If the missing information should pause the live workflow for later continuation, ask through \`loop.ask_user(...)\` in generated code rather than with a plain-text question.
+- If you are asking the user to pick from explicit options, prefer a live \`loop.ask_user({ type: 'choice', ... })\` prompt over a direct reply that lists those options in text.
 - Keep replies concise and clear.
 - This is a conversation UI, not an API console. Favor human answers over machine-shaped payloads.
 
@@ -14635,9 +15181,9 @@ ${sessionBlock}
 \u2500\u2500\u2500 CAPABILITY SNAPSHOT \u2500\u2500\u2500
 ${toolBlock}
 
-\u2500\u2500\u2500 DOMAIN TYPES (TypeScript declarations from ./sandbox-tools) \u2500\u2500\u2500
+\u2500\u2500\u2500 DOMAIN REFERENCE (from ./sandbox-tools) \u2500\u2500\u2500
 Import classes and effect functions from \`./sandbox-tools\` in generated code.
-Published effects appear as instance or static methods on the classes below, or as top-level \`export declare function\` entries for global effects.
+Use the TypeScript declarations for exact signatures. When present, the generated usage notes below them show query patterns and examples.
 
 ${domainBlock}
 
@@ -14647,6 +15193,9 @@ ${checkpointBlock}
 \u2500\u2500\u2500 WORKFLOW SNAPSHOT \u2500\u2500\u2500
 ${workflowBlock}
 
+\u2500\u2500\u2500 RECENT REFERENTS \u2500\u2500\u2500
+${referentBlock}
+
 \u2500\u2500\u2500 SESSION HEAP \u2500\u2500\u2500
 ${heapBlock}
 
@@ -14654,109 +15203,54 @@ ${heapBlock}
 ${loopBlock}
 
 \u2500\u2500\u2500 LOOP PLAYBOOK \u2500\u2500\u2500
-- A single user request may span several assistant turns and several jobs. Continue from the latest structured session state instead of restarting.
-- Treat WORKFLOW SNAPSHOT, EXECUTION CHECKPOINT, SESSION HEAP, and AGENT LOOP STATE as the authoritative working memory for the current request.
-- Use CAPABILITY SNAPSHOT to choose the next step quickly, then use DOMAIN TYPES to write exact valid code.
-- Use WORKFLOW SNAPSHOT to understand the current boundary, recent actions, and working set before fetching more data.
-- If the user names a concrete customer, case, order, shipment, or other record that is not already in the heap, fetch it from the graph. "Not in the current context" is not a sufficient reason to stop.
-- Treat user-provided names as human references, not exact database keys. If the user says "Northwind", "the Alpine compressor case", or another shorthand, prefer sensible case-insensitive partial matching across likely records before concluding that nothing matches.
-- If exactly one strong partial-name match exists, use it. If several plausible partial matches exist, ask the user to choose instead of failing on an exact-equality lookup.
-- Take the minimum next step that directly advances the user's request. Do not do speculative cleanup, enrichment, or bookkeeping.
-- Reuse exact \`taskId\`, \`decisionId\`, and \`closureId\` values from the AGENT LOOP STATE block. Never guess or slugify IDs.
-- If the request is ambiguous or clearly multi-step, start by creating 2-4 meaningful user-visible tasks. Do not create a detailed internal checklist.
-- Keep tasks updated as the workflow advances. Complete tasks as soon as they are actually done.
-- Write the smallest straightforward code that fits the current step. Avoid defensive branches for hypothetical states that are not currently true.
-- Before asking a new question, check whether the answer is already present in the current heap, open decisions, or checkpoint.
-- If the previous step made no progress, prefer a different concrete action, a narrower fetch, or a user question instead of repeating equivalent code.
-- Use \`loop.open_decision(...)\` in one job to store grounded candidates, then \`loop.close_decision(...)\` in a later job to pick one stored candidate with \`selectedId\`.
-- Use \`loop.ask_user({ type: 'input', ... })\` only for open-ended preferences or missing free-form text that cannot be represented as a short explicit shortlist.
-- If you already have a short concrete shortlist, usually 2-7 candidates, generate code and call \`loop.ask_user({ type: 'choice', ... })\`. Do not downgrade that to a text input.
-- If multiple concrete records match a singular user reference such as "the invoice", "the order", "the shipment", or "the request", do not silently choose one by heuristic. Ask the user to choose unless the request already uniquely identifies the record.
-- For disambiguation between concrete known records, prefer \`type: 'choice'\` over \`type: 'input'\`. This is especially important for invoices, orders, shipments, requests, work orders, and cases.
-- For \`type: 'choice'\` prompts, make the options directly pickable by a human: use a stable value and a readable label that includes the identifier or title they are likely to recognize.
-- If a shortlist already exists, do not ask the user to type an exact database key or identifier manually. Present the shortlist as clickable choices instead.
-- When reasoning about free-form status strings, do not use brittle substring checks such as \`status.includes("paid")\` because values like \`"unpaid"\` would be misclassified. Prefer explicit positive matches such as \`unpaid\`, \`open\`, or \`overdue\`, or exact normalized comparisons.
-- When multiple concrete records match and \`loop.ask_user(...)\` is available, do not stop with a plain-text question like "Which invoice do you mean?". Persist the live workflow and ask through \`await loop.ask_user(...)\` instead.
-- If the user could reasonably answer with a partial identifier such as \`abcd\` for \`INV-abcd\`, that is another sign the question should be a \`type: 'choice'\` prompt with visible options rather than a free-text input.
-- Never ask for approval in plain text when \`loop.confirm(...)\` is available. Use \`loop.confirm(...)\` for consequential approval.
-- When the correct next step is a loop helper action, generate code and call that helper. Do not replace it with a conversational reply.
-- If you ask the user a new question in the current job, do not also call \`loop.close_loop(...)\` in that same job.
-- When you need user input or approval, await \`loop.ask_user(...)\` or \`loop.confirm(...)\`. The job will pause until the user answers, then resume from that awaited call.
-- It is valid to branch on the value returned by \`await loop.ask_user(...)\` or \`await loop.confirm(...)\` after the job resumes.
-- After \`await loop.ask_user(...)\` returns a concrete choice, continue the workflow in the same resumed job whenever that answer is enough to act. Do not stop with placeholder text such as "I can do that next" or "I'm ready to continue".
-- After \`await loop.confirm(...)\` returns \`true\`, execute the approved mutation in that same resumed job before returning. Do not end with placeholder text like "Approved, ready to make the change next."
-- Only stop immediately after a resumed prompt when the user declined, the workflow is now blocked, or you truly still need another missing piece of information.
-- If the user says stop, enough, or no further action, close the loop and end cleanly without asking another question.
-- If one clear item is already selected and the next step matters, prefer \`loop.confirm(...)\` over another exploratory question.
-- If one clear item is already selected and the only missing input is approval to proceed, use \`loop.confirm(...)\` rather than \`loop.ask_user(...)\`.
-- If the user already gave a usable scheduling window such as "Tuesday morning", treat that as enough to choose a reasonable concrete slot. Do not open another menu just to choose between nearby sub-slots unless a real conflict or hard business rule forces that follow-up.
-- For schedule changes, prefer one grounded recommendation plus one approval prompt. Avoid a second prompt for optional time-window micro-choices when you can pick a sensible default that still satisfies the user request.
-- If the user explicitly instructs you to perform a consequential action now, that instruction counts as approval. Do not add an extra confirmation step unless the user expressed hesitation, ambiguity, or asked you not to execute yet.
-- Direct imperatives such as "cancel this order", "send the reminder now", "approve this refund", or "charge it now" already authorize that exact step. Execute them directly instead of inserting \`loop.confirm(...)\`.
-- If the user says not to do anything irreversible yet, stop at recommendation, review, or approval. Do not collect checkout-only details like quantity, delivery notes, gift message, or optional preferences unless the user explicitly asks to move closer to purchase.
-- Once you have one solid recommendation, prefer summarizing it and asking for approval over gathering more optional preferences.
-- Prefer asking the user for the next missing input over fetching extra related data they did not ask for yet.
-- Avoid serial menus. After one clarifying choice, prefer acting on it, asking one short text question, or confirming rather than opening another menu.
-- When the user asks for a summary "including" concrete records such as unpaid invoices, open cases, orders, or shipments, include the actual identifiers or titles of those records in the reply, not just aggregate counts.
-- Call \`loop.close_loop(...)\` before stopping whenever the current workflow is completed, canceled, or clearly blocked.
+- Continue from the latest structured state. Treat WORKFLOW SNAPSHOT, EXECUTION CHECKPOINT, RECENT REFERENTS, SESSION HEAP, and AGENT LOOP STATE as the working memory for this request.
+- Use CAPABILITY SNAPSHOT to choose the next step, then use DOMAIN REFERENCE for exact signatures and query shapes.
+- Take the minimum next step that directly helps the user. Avoid duplicate work, speculative cleanup, or extra fetching that is not needed yet.
+- If the user names a record that is not already in the heap, fetch it from the graph instead of saying it is not in context.
+- Treat user-provided names as human references, not exact keys. If one strong partial match exists, use it. If several plausible matches exist, ask the user to choose.
+- Use RECENT REFERENTS to resolve follow-up references across turns, such as "that invoice", "that customer", "those products", or "the other one".
+- If the request has more than one reasonable interpretation, ask the user to clarify instead of guessing.
+- For comparisons, rankings, selections, or summaries, first identify the rule you are using. If that rule is not clear from the user request and DOMAIN REFERENCE, ask the user before choosing anything.
+- When the ranking, comparison, or selection rule is unclear, the minimum next step is the clarification itself. Do not run a placeholder query for a provisional winner before asking.
+- Reuse exact \`taskId\`, \`decisionId\`, and \`closureId\` values from AGENT LOOP STATE. Never invent or rewrite them.
+- If the request is ambiguous or clearly multi-step, create 2-4 short user-visible tasks and keep them updated as the workflow advances.
+- Use \`loop.ask_user({ type: 'choice', options: [...] })\` when you have a short, grounded shortlist the user can choose from. Otherwise use \`type: 'input'\`.
+- For an unclear ranking, comparison, or selection rule, prefer \`type: 'choice'\` when you can offer a short grounded list of plausible interpretations from the domain or nearby context.
+- When \`type: 'choice'\` fits, do not ask the same question as plain text with bullets such as "Common options:" or "Choose one of these:".
+- Use \`loop.confirm(...)\` for consequential approval unless the user already clearly instructed you to perform that exact action now.
+- Await \`loop.ask_user(...)\` and \`loop.confirm(...)\`. After the job resumes, continue in the same job whenever the answer is enough to act.
+- Use \`loop.open_decision(...)\` to persist grounded candidates, \`loop.close_decision(...)\` to resolve one, and \`loop.close_loop(...)\` when the workflow is completed, canceled, or blocked.
+- If you ask a new question in the current job, do not also close the loop in that same job.
 
 \u2500\u2500\u2500 CODE RULES \u2500\u2500\u2500
 - Import from \`./sandbox-tools\`.
-- If you use \`heap\`, \`loop\`, \`agent_text_message\`, \`agent_heap_objects\`, or legacy \`agent_message\`, import them explicitly from \`./sandbox-tools\`.
+- If you use \`heap\`, \`loop\`, \`agent_text_message\`, or \`agent_heap_objects\`, import them explicitly from \`./sandbox-tools\`.
 - Write top-level executable code with \`await\` at top level.
-- The generated job body must be plain runnable JavaScript. The DOMAIN TYPES block is only a reference for shapes and available methods.
-- Do not write TypeScript-only syntax in executable code: no type annotations, no interfaces, no enums, no \`as Type\` casts, no \`satisfies\`, and no generic type parameters in code.
-- Generated code must be valid against the DOMAIN TYPES block above.
-- Only use classes, methods, and parameter shapes that are explicitly declared in those typedefs.
-- Never invent helper methods such as \`find(...)\` or unsupported parameters such as \`id\` when the typedefs require \`path\`.
-- Use \`ClassName.get({ path })\` only when you already know an object's graph path.
-- Use \`ClassName.count()\` when you only need a total.
-- Use \`ClassName.page({ page, perPage, saveAs })\` when you need both records and pagination metadata like \`totalCount\` or \`hasMore\`. \`perPage\` defaults to \`100\` and larger values are clamped to \`100\`.
-- Use \`ClassName.list({ page, perPage, saveAs })\` to load one typed page of records. \`limit\` is only a legacy alias for \`perPage\`, \`perPage\` defaults to \`100\`, and larger values are clamped to \`100\`.
-- Use \`for await (const item of ClassName.iterate({ perPage, maxItems }))\` for large batch jobs so you do not materialize the whole result set at once. \`perPage\` defaults to \`100\` and larger values are clamped to \`100\`.
-- Instance methods: \`await instance.method_name(params)\`.
-- Static methods: \`await ClassName.static_method(params)\`.
-- Global effects: \`await effect_name(params)\`.
-- When a child record has sparse fields, identify it through nearby graph context instead of only string-matching that child\u2019s local fields. Prefer traversing linked customer, case, work order, part request, and shipment records over broad guesswork.
-- For blocker, delay, ETA, or "what is holding this up?" questions, do not stop at a parent status like \`in_progress\` or \`scheduled\` if linked dependencies exist. Trace into the likely dependency chain first: approval -> work order -> part request -> shipment -> carrier update.
-- A generic parent status is not a sufficient blocker explanation when a linked part request, approval, shipment, customs hold, or vendor delay may be the real cause.
-- If a case summary or latest customer message mentions a part, shipment, ETA, customs, vendor, approval, regulator, kit, or delay, treat that as a strong hint to inspect the linked dependency records before answering.
-- When you already found the correct parent case, inspect its linked child records even if the child summaries use different wording. Do not require a work order, part request, or shipment description to repeat the exact phrase that identified the parent case.
-- Status fields are free-form operational strings, not strict enums. Normalize spelling mentally and do not rely on brittle hard-coded sets that miss variants like \`in-progress\`, \`in_progress\`, \`awaiting-part\`, or \`approval-submitted\`.
-- Do not discard a case, work order, part request, or shipment only because its status string does not match your preferred "open" spelling. If the record is otherwise the clear match, inspect it.
-- Reuse \`heap.getVar(name)\`, \`heap.setVar(name, value)\`, and \`heap.deleteVar(name)\` only when it clearly helps the next step. Do not mirror data into the heap just for completeness.
-- Prefer \`heap.setVar(name, value)\` for scalars or one selected instance. Prefer \`ClassName.list({ page, perPage, saveAs })\` for reusable list pages instead of \`heap.setVar(name, array)\`.
-- Never write an empty array into the heap. If a filtered list is empty, keep it local or clear the previous heap value with \`heap.deleteVar(name)\`.
-- Prefer heap-backed state that represents the current choice or recommendation. Avoid storing extra scalar bookkeeping unless it is needed for the next concrete step.
-- Only store true sandbox instances, typed lists of sandbox instances, or scalars in the heap. Results returned by static effects like availability/search helpers are often plain JSON, not sandbox instances.
-- If a helper returns plain JSON candidates, keep them local, store only a scalar like the chosen id, or resolve the matching sandbox instance before writing it into the heap.
-- When reading heap values, prefer generated generic typings such as \`await heap.getVar<Book[]>("my_books")\` or \`await heap.getVar<Book>("selected_book")\`.
-- If a focused heap variable already points to a known class, read it with that exact generic type and act on it directly. Do not use \`heap.getVar<any>(...)\` or cast through \`any\` when the class is already clear from the prompt. For example, prefer \`await heap.getVar<Order>("selected_order")\` over \`await heap.getVar<any>("selected_order")\`.
-- Use the injected \`loop\` helpers when you need to manage the workflow itself:
-  \`loop.ask_user(...)\`, \`loop.confirm(...)\`, \`loop.open_decision(...)\`, \`loop.close_decision(...)\`,
-  \`loop.create_task(...)\`, \`loop.update_task(...)\`, \`loop.complete_task(...)\`, and \`loop.close_loop(...)\`.
-- Loop helper semantics:
-  - \`loop.open_decision(...)\`: store explicit candidates from the current job so a later job can revisit the same decision. Keep and reuse the returned \`decisionId\`.
-  - \`loop.close_decision(...)\`: resolve an open decision by choosing one stored candidate with \`selectedId\` and recording why. Candidates may be any JSON objects, but each one must have an \`id\`.
-  - \`loop.ask_user(...)\`: pause the job and ask the user for missing input. Default to \`type: 'input'\`; use \`type: 'choice'\` only for a short explicit shortlist. Write \`const answer = await loop.ask_user(...)\`, then continue the same job once the user answers.
-  - \`loop.confirm(...)\`: pause the job for approval before a consequential action. Do not simulate confirmation in plain text. Write \`const approved = await loop.confirm(...)\`, then branch on that approval once the job resumes.
-  - \`loop.create_task(...)\`, \`loop.update_task(...)\`, \`loop.complete_task(...)\`: keep a short task list that later jobs can continue and finish.
-  - \`loop.close_loop(...)\`: record the current workflow outcome with a short summary before stopping. Do not call it in the same job that opens a new user prompt unless the workflow is explicitly blocked. This does not end the session forever.
-- Avoid \`as any\` and other broad casts when the DOMAIN TYPES block already tells you the correct class or list type.
-- Prefer manipulating heap-backed instances and typed lists instead of returning raw JSON blobs or object IDs unless the user explicitly asks for them.
-- Every job that intends to answer the user must emit at least one explicit UI message with \`agent_text_message(...)\` and/or \`agent_heap_objects(...)\`.
-- Use \`agent_text_message("...")\` for all user-visible text shown in the UI.
-- Use \`agent_heap_objects(...)\` only when you want the UI to render heap-backed records or lists.
-- If you want to show both text and records, call \`agent_text_message(...)\` and \`agent_heap_objects(...)\` separately in whatever order fits the interaction.
-- \`agent_text_message(...)\` should be used with a plain text string in normal generated code.
-- \`agent_heap_objects(...)\` should point at heap-backed values: explicit \`entryPaths\` / \`listNames\` / \`variableNames\`, a named list saved with \`saveAs\`, or values read back from \`heap.getVar(...)\`.
-- If you just fetched records and want to show them in the UI, save or reference them through the heap first, then call \`agent_heap_objects(...)\`. Do not try to hand-build UI payloads in job code.
-- Do not assume heap changes will be displayed automatically. If records should appear in the UI, you must call \`agent_heap_objects(...)\`.
-- Never write \`return { reply, show }\` or \`return { show: ... }\` for UI. If you want the UI to render records or lists, call \`agent_heap_objects(...)\` instead.
-- Do not rely on the final return value for user-visible output. A plain return value is not considered a displayed UI answer.
-- \`agent_message(...)\` remains available as a legacy compatibility alias, but prefer \`agent_text_message(...)\` and \`agent_heap_objects(...)\` in new code.
-- Do not return bare structured JSON, low-level diagnostics, or database-shaped payloads as the final answer unless the user explicitly asks for them.
-- Prefer simple executable JavaScript over clever interpolation. Avoid nested template literals or unusually dense inline expressions when a small temporary variable or string concatenation would be clearer and safer.
+- The generated job body must be plain runnable JavaScript. Do not use TypeScript-only syntax.
+- Follow the exact classes, methods, and parameter shapes in DOMAIN REFERENCE. Do not invent helpers or unsupported arguments.
+- Use \`ClassName.get({ path })\` only for known graph paths when you want a direct graph fetch.
+- Use \`ClassName.count()\` for totals, \`ClassName.page({ page, perPage, saveAs })\` when you need \`items\` plus \`totalCount\` or \`hasMore\`, \`ClassName.list({ page, perPage, saveAs })\` for one page of records, and \`ClassName.iterate({ perPage, maxItems })\` for large scans.
+- \`perPage\` defaults to \`100\` and is capped at \`100\`.
+- Push \`filter\`, \`search\`, and \`sort\` into graph queries instead of fetching a page and processing it locally.
+- A property appearing on a record does not make it valid in \`filter\` or \`sort\`; only use fields and operators that are explicitly exposed in DOMAIN REFERENCE.
+- Choose \`sort.field\` verbatim from the sortable fields listed in DOMAIN REFERENCE. Do not sort by relationship names, related-record collections, counts, totals, or other derived metrics unless they are explicitly listed as sortable.
+- If ordering alone answers the request, use \`sort\` without inventing a \`filter\`.
+- Do not invent proxy metrics, fallback heuristics, or made-up tie-breakers to resolve ambiguity. If the rule is unclear, ask the user with \`loop.ask_user(...)\`.
+- Do not fetch, sort, or show a provisional record just to have something to display while the real ranking or selection rule is still ambiguous.
+- Call instance methods on instances, static methods on classes, and global effects by name.
+- Use \`heap.getEntry(path)\` for remembered heap entries, \`heap.getList(name)\` for remembered lists, and \`heap.getVar(name)\` only for named variables.
+- Use \`heap.setVar(...)\` and \`heap.deleteVar(...)\` only when they help the next step.
+- Prefer \`heap.setVar(...)\` for scalars or one selected instance. Prefer \`ClassName.list({ saveAs })\` for reusable typed lists. Empty arrays are allowed.
+- Only store sandbox instances, typed lists, or scalars in the heap. If a helper returns plain JSON, keep it local or store only the chosen scalar.
+- Use the \`loop\` helpers to manage workflow state: \`ask_user\`, \`confirm\`, \`open_decision\`, \`close_decision\`, \`create_task\`, \`update_task\`, \`complete_task\`, and \`close_loop\`.
+- Use \`type: 'choice'\` only for short grounded options. Use \`type: 'input'\` when the answer should stay open-ended.
+- \`loop.confirm(...)\` is for consequential approval. Do not ask for approval in plain text.
+- After \`await loop.ask_user(...)\` or \`await loop.confirm(...)\`, continue in the same resumed job when the answer is enough to act.
+- Every job that answers the user must emit \`agent_text_message(...)\` and/or \`agent_heap_objects(...)\`.
+- Use \`agent_text_message(...)\` for user-visible text.
+- Use \`agent_heap_objects(...)\` for user-visible records. You may pass sandbox instances directly, or heap-backed \`entryPaths\`, \`listNames\`, and \`variableNames\` when you already have them. Use \`saveAs\` or \`heap.setVar(...)\` when you need a reusable named selection.
+- Do not rely on the final return value for UI output. Do not return ad-hoc \`reply\` / \`show\` payloads instead of explicit agent message calls.
+- Keep the code small and direct. Avoid speculative branches, broad casts, and raw JSON dumps unless the user asked for them.
 - Use \`console.log()\` only for intermediate diagnostics, not for the final user-facing answer.`;
 }
 
@@ -14915,6 +15409,10 @@ function fallbackResponseText(entries, lists) {
     return entries.length === 1 ? "I found one relevant record." : `I found ${entries.length} relevant records.`;
   }
   if (lists.length > 0) {
+    const emptyOnly = lists.every((list) => (list.paths || []).length === 0);
+    if (emptyOnly) {
+      return lists.length === 1 ? "I saved one empty result set." : `I saved ${lists.length} empty result sets.`;
+    }
     return lists.length === 1 ? "I saved one result set." : `I saved ${lists.length} result sets.`;
   }
   return null;
@@ -15291,7 +15789,9 @@ function buildSessionTranscript(input) {
 }
 
 exports.Environment = Environment;
+exports.EnvironmentSession = EnvironmentSession;
 exports.Granular = Granular;
+exports.OntologyHandle = OntologyHandle;
 exports.Session = Session;
 exports.WSClient = WSClient;
 exports.buildContinuationInstruction = buildContinuationInstruction;
@@ -15299,6 +15799,7 @@ exports.buildGranularAgentCheckpointBlock = buildGranularAgentCheckpointBlock;
 exports.buildGranularAgentDomainBlock = buildGranularAgentDomainBlock;
 exports.buildGranularAgentHeapBlock = buildGranularAgentHeapBlock;
 exports.buildGranularAgentLoopBlock = buildGranularAgentLoopBlock;
+exports.buildGranularAgentReferentBlock = buildGranularAgentReferentBlock;
 exports.buildGranularAgentSessionBlock = buildGranularAgentSessionBlock;
 exports.buildGranularAgentSystemPrompt = buildGranularAgentSystemPrompt;
 exports.buildGranularAgentToolBlock = buildGranularAgentToolBlock;
@@ -15316,6 +15817,8 @@ exports.normalizeEffectBehaviors = normalizeEffectBehaviors;
 exports.normalizePrompt = normalizePrompt;
 exports.normalizePromptText = normalizePromptText;
 exports.normalizePromptType = normalizePromptType;
+exports.projectConversationReferentFocus = projectConversationReferentFocus;
+exports.projectConversationReferentSummary = projectConversationReferentSummary;
 exports.projectHeapSummary = projectHeapSummary;
 exports.projectLoopSummary = projectLoopSummary;
 exports.projectWorkflowFocus = projectWorkflowFocus;