@granular-software/sdk 0.4.29 → 0.4.31

package/dist/cli/index.js

@@ -6597,9 +6597,9 @@ async function main() {
   });
 
   // Connect as one app user so the SDK can create an environment for the seed run.
-  const env = await granular.connect({
+  const env = await granular.openEnvironment({
     ontology: SANDBOX_ID,
-    environment: 'dev',
+    tag: 'dev',
     userId: '${template.seedUser.userId}',
     name: '${template.seedUser.name}',
     email: '${template.seedUser.email}',
@@ -6621,7 +6621,7 @@ async function main() {
     const updatedCount = results.length - createdCount;
     console.log(\`[Seed] Created \${createdCount} records, updated \${updatedCount} records.\`);
   } finally {
-    await env.disconnect();
+    await session.disconnect();
   }
 
   console.log(\`Seeded \${records.length} records into \${SANDBOX_ID}\`);
@@ -6670,7 +6670,7 @@ async function main() {
     apiUrl: process.env.GRANULAR_API_URL ?? API_URL,
   });
 
-  await granular.registerEffects(SANDBOX_ID, [
+  await granular.ontology(SANDBOX_ID).effects.registerMany([
 ${registrations}
   ]);
 
@@ -6688,7 +6688,7 @@ ${registrations}
       shuttingDown = true;
       clearInterval(keepAliveTimer);
       console.log(\`Shutting down after \${signal}...\`);
-      await granular.disconnectEffects(SANDBOX_ID);
+      await granular.ontology(SANDBOX_ID).effects.disconnect();
       resolve();
       process.exit(0);
     };
@@ -6738,9 +6738,9 @@ test('granular connect + submitJob smoke test', {
     apiUrl: process.env.GRANULAR_API_URL ?? rc.apiUrl ?? DEFAULT_API_URL,
   });
 
-  const environment = await granular.connect({
+  const environment = await granular.openEnvironment({
     ontology: rc.sandboxId,
-    environment: 'dev',
+    tag: 'dev',
     userId: '${template.seedUser.userId}',
     name: '${template.seedUser.name}',
     email: '${template.seedUser.email}',
@@ -6751,7 +6751,8 @@ test('granular connect + submitJob smoke test', {
     assert.ok(environment.environmentId);
     assert.ok(environment.sessionId);
 
-    const job = await environment.submitJob(\`
+    const session = await environment.sessions.create();
+const job = await session.submitJob(\`
 return {
   ok: true,
   template: '${template.id}',
@@ -6762,7 +6763,7 @@ return {
     assert.equal(result.ok, true);
     assert.equal(result.template, '${template.id}');
   } finally {
-    await environment.disconnect();
+    await session.disconnect();
   }
 });
 `;
@@ -8960,7 +8961,7 @@ function manifestGuideGranularProductSection() {
 2. **Build** that declaration from \`granular.json\` so the service compiles types and tooling for a **sandbox** (a workspace identified by \`sbx_\u2026\`).
 3. **Store** **records** (instances of your classes) and **run jobs** (code executed in Granular\u2019s **sandbox runtime**) that call generated helpers and effects.
 
-**Split of responsibility:** Data and domain rules live in Granular; **secrets, payment providers, email, and arbitrary HTTP** stay in **your** server via **effect handlers** you register with \`registerEffects\`.
+**Split of responsibility:** Data and domain rules live in Granular; **secrets, payment providers, email, and arbitrary HTTP** stay in **your** server via **effect handlers** you register with \`granular.ontology(sandboxId).effects.registerMany\`.
 
 ---
 
@@ -8985,10 +8986,10 @@ The rest of this guide assumes these terms.
 | **Manifest** | \`granular.json\` (definition under \`manifest\`). **Source** in the repo until you create a new ontology **version** from it. |
 | **Version** | Immutable ontology state derived from one manifest revision. Tags like \`dev\` and \`prod\` point to versions. |
 | **Build run** | The CI-style compilation process. \`granular build\` creates or reuses the ontology version, then runs a build for it. |
-| **Environment** | Return value of \`granular.connect({ ontology, environment, \u2026 })\`. It is your **server-side** handle for \`recordObject\`, \`submitJob\`, \`graphql\`, etc., bound to one ontology environment slot. |
-| **Session** | SDK base type; \`Environment\` **extends** \`Session\`. Job/prompt APIs live on \`Session\`; you still use the **\`Environment\`** instance from \`connect()\` in normal apps. |
-| **Job** | Code string passed to \`environment.submitJob(code)\`. Runs in Granular\u2019s **sandbox runtime** with access to \`./sandbox-tools\` (generated classes + effect entrypoints). |
-| **Effect** | Declared with \`withEffect\`; **handler** registered with \`registerEffects\` in **your** process. Jobs invoke effects; handlers do IO outside Granular. |
+| **Environment** | Return value of \`granular.openEnvironment({ ontology, tag, userId, \u2026 })\`. It is your **server-side** handle for \`recordObject\`, \`recordObjects\`, \`graphql\`, and \`sessions.create()\`. |
+| **Session** | Live runtime connection opened from an environment with \`environment.sessions.create()\` or \`environment.sessions.connect()\`. Job, prompt, and streaming APIs live here. |
+| **Job** | Code string passed to \`session.submitJob(code)\`. Runs in Granular\u2019s **sandbox runtime** with access to \`./sandbox-tools\` (generated classes + effect entrypoints). |
+| **Effect** | Declared with \`withEffect\`; **handler** registered in **your** process with \`granular.ontology(sandboxId).effects.registerMany(...)\`. Jobs invoke effects; handlers do IO outside Granular. |
 | **Class** | Entity **kind** in the domain (e.g. \`book\`) with \`has\` fields in the manifest. |
 | **Record / object** | One **instance**: \`className\`, \`id\`, \`fields\`, \`relationships\`. Use \`recordObject\` for one upsert, \`recordObjects\` for several immediate upserts, and record-import APIs for async bulk loads. |
 | **Relationship** | Declared link between two classes; defines **property names** and cardinality. Keys appear in \`recordObject({ relationships })\`. |
@@ -9007,10 +9008,10 @@ function manifestGuideEndToEndSection() {
 |------|--------|---------|
 | 1 | Edit \`granular.json\` (\`manifest\` \u2192 \`volumes\` \u2192 \`operations\`) | Domain **source** in the repo |
 | 2 | \`granular build\` | Manifest **uploaded**; ontology version created or reused; build run compiles it; errors surface here |
-| 3 | (Optional) Run your **effects host** \u2014 e.g. \`npx tsx granular-effects.ts\` \u2014 calling \`registerEffects(sandboxId, \u2026)\` | Effect **handlers** attached in **your** process |
-| 4 | \`new Granular({ apiKey })\` then \`connect({ ontology, environment, userId, permissions })\` | **\`Environment\`** for that ontology environment slot |
+| 3 | (Optional) Run your **effects host** \u2014 e.g. \`npx tsx granular-effects.ts\` \u2014 calling \`granular.ontology(sandboxId).effects.registerMany(...)\` | Effect **handlers** attached in **your** process |
+| 4 | \`new Granular({ apiKey })\` then \`openEnvironment({ ontology, tag, userId, permissions })\` | **\`Environment\`** handle for that ontology/user pair |
 | 5 | \`recordObject\` / \`recordObjects\` | **Records** stored with correct fields and relationship keys. Use \`recordObject\` for one targeted write. Use \`recordObjects\` for one synchronous multi-record write with chunking (default 100 rows/request), retries, and optional \`onChunkComplete\` / \`concurrency\` progress. For async bulk loads use \`enqueueRecordImport\` + import status APIs. |
-| 6 | \`submitJob(\`\u2026\`)\` with imports from \`./sandbox-tools\` | **Jobs** run; may call **effects** \u2192 your handlers execute and return results |
+| 6 | \`const session = await environment.sessions.create();\` then \`session.submitJob(\`\u2026\`)\` | **Jobs** run; may call **effects** \u2192 your handlers execute and return results |
 
 **Accuracy tip:** After changing the manifest, always **re-build** before assuming generated types, \`./sandbox-tools\` names, or effect signatures match the file on disk.`;
 }
@@ -9024,9 +9025,9 @@ function sandboxDocMainConceptsSection() {
 | **Manifest** | \`granular.json\` \u2014 **source**; edit here, then \`granular build\`. |
 | **Version** | Immutable ontology state created from one manifest revision. |
 | **Build run** | Compilation run that validates and materializes a version. |
-| **Environment** | \`connect()\` result \u2014 **record**, **submitJob**, **graphql** for this sandbox. |
-| **Session** | Base type; \`Environment\` extends it (job APIs). |
-| **Job** | \`submitJob\` code using \`./sandbox-tools\`. |
+| **Environment** | \`openEnvironment()\` result \u2014 **record**, **recordObjects**, **graphql**, and **session lifecycle** for this sandbox. |
+| **Session** | Live runtime connection created from an environment; job and prompt APIs live here. |
+| **Job** | \`session.submitJob(...)\` code using \`./sandbox-tools\`. |
 | **Effect** | Declared in manifest; **handler** in your process. |
 
 **Full product + manifest how-to:** [docs/granular-manifest.md](docs/granular-manifest.md).`;
@@ -14230,17 +14231,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;
     }
   }
 });
@@ -14869,7 +14861,7 @@ function generateManifestAgentGuide(options) {
   );
   return `# Granular manifest guide (for coding agents)
 
-This guide is for **coding agents** who may have **no prior context on Granular**. It explains the product, core terms, how to **author** \`granular.json\`, **build** the domain, and use the SDK (\`connect\` \u2192 **environment**, \`recordObject\`, \`submitJob\`, **effects**). For **this repository\u2019s** exact class names, relationship keys, and effect payloads only, see [GRANULAR_SANDBOX.md](../GRANULAR_SANDBOX.md).
+This guide is for **coding agents** who may have **no prior context on Granular**. It explains the product, core terms, how to **author** \`granular.json\`, **build** the domain, and use the SDK (\`openEnvironment\` \u2192 **environment**, \`environment.sessions.create()\` \u2192 **session**, \`recordObject\`, **effects**). For **this repository\u2019s** exact class names, relationship keys, and effect payloads only, see [GRANULAR_SANDBOX.md](../GRANULAR_SANDBOX.md).
 
 **Precedence:** User instructions in chat override this file. When in doubt, read \`granular.json\` and [AGENTS.md](../AGENTS.md).
 
@@ -15127,14 +15119,14 @@ Example:
 
 | Field | Meaning |
 |-------|---------|
-| \`name\` | Must match the \`name\` in \`registerEffects\`. |
+| \`name\` | Must match the handler name you register from your effect host. |
 | \`attachedClass\` | Omit for **global** effects. Set for class-bound effects. |
 | \`isStatic\` | \`true\` \u2192 static method; \`false\` or omit \u2192 **instance** method (handler receives the object **id** first). |
 | \`inputSchema\` / \`outputSchema\` | JSON Schema; used for codegen and validation. |
 
-**Lifecycle:** declare in manifest \u2192 \`granular build\` creates or reuses a version and runs the build \u2192 implement handlers \u2192 \`granular.registerEffects(sandboxId, [...])\` \u2192 jobs call generated methods \u2192 your handler runs and returns the result to the job.
+**Lifecycle:** declare in manifest \u2192 \`granular build\` creates or reuses a version and runs the build \u2192 implement handlers \u2192 \`granular.ontology(sandboxId).effects.registerMany([...])\` \u2192 jobs call generated methods \u2192 your handler runs and returns the result to the job.
 
-**Permissions:** \`connect({ permissions: [...] })\` assigns profiles (e.g. \`default\`) that can allow or deny which effects a user may call.
+**Permissions:** \`openEnvironment({ permissions: [...] })\` assigns profiles (e.g. \`default\`) that can allow or deny which effects a user may call.
 
 ### Effect metamodels
 
@@ -15200,30 +15192,38 @@ ${effectMetamodelTable}
 | API | Purpose |
 |-----|---------|
 | \`new Granular({ apiKey, apiUrl?, endpointMode?, token?, tokenProvider?, \u2026 })\` | Auth. Env: \`GRANULAR_API_KEY\`, \`GRANULAR_API_URL\`, \`GRANULAR_ENDPOINT_MODE\`. |
-| \`recordUser({ userId, name?, email?, permissions? })\` | Upsert user for later \`connect\`. |
-| \`connect({ ontology, environment, tagName?, userId?, granularId?, user?, permissions?, clientId?, initialHeap? })\` | Opens a session \u2192 **\`Environment\`**. \`tagName\` is an advanced override. |
-| \`registerEffects(sandboxId, effects)\` / \`registerEffect\` | Register handlers for manifest \`withEffect\` declarations. |
-| \`unregisterEffect\` / \`unregisterAllEffects\` / \`disconnectEffects\` | Stop effect handlers for a sandbox. |
+| \`recordUser({ userId, name?, email?, permissions? })\` | Upsert user for later \`openEnvironment\`. |
+| \`openEnvironment({ ontology, tag?, userId?, granularId?, user?, permissions, createFreshIfOutdated?, ... })\` | Resolves or creates an **\`Environment\`** handle. |
+| \`granular.ontology(sandboxId).effects.registerMany(effects)\` / \`.register(effect)\` | Register handlers for manifest \`withEffect\` declarations. |
+| \`granular.ontology(sandboxId).effects.unregister(name)\` / \`.clear()\` / \`.disconnect()\` | Stop effect handlers for a sandbox. |
 | \`granular.sandboxes\` | \`.list()\`, \`.get\`, \`.create\`, \`.update\`, \`.delete\` |
 | \`granular.permissionProfiles\` | Permission profiles per sandbox. |
-| \`granular.environments\` | List/create/delete environments (usually use \`connect()\`). |
+| \`granular.environments\` | List/create/delete environments (advanced control-plane API). |
 | \`granular.subjects\` | Subjects / assignments (see typings). |
 
-### \`Environment\` (connected session)
+### \`Environment\` (sessionless environment handle)
 
 | API | Purpose |
 |-----|---------|
-| \`environmentId\`, \`sandboxId\`, \`apiEndpoint\`, \u2026 | Session context. |
+| \`environmentId\`, \`sandboxId\`, \`apiEndpoint\`, \u2026 | Environment context. |
 | \`applyManifest(manifest)\` | Apply manifest operations at runtime (alternative to CLI build for dynamic ontologies). |
 | \`recordObject\` / \`recordObjects\` | Upsert instances and relationships. Use \`recordObject\` for one object or a targeted patch. Use \`recordObjects\` for synchronous multi-record ingestion with chunked HTTP writes (default 100 rows/chunk), retries, and optional \`onChunkComplete\`, \`batchSize\`, \`concurrency\`. |
 | \`enqueueRecordImport\`, \`listRecordImports\`, \`getRecordImport\`, \`getRecordImportSummary\`, \u2026 | **Async** bulk import (worker queue + aggregate progress). Prefer when loads are huge, returning an \`importId\` is enough up front, and background processing is acceptable. |
 | \`graphql(query, variables?)\` | **GraphQL** \u2014 see dedicated subsection below. |
 | \`defineRelationship\`, \`getRelationships\`, \`attach\`, \`detach\`, \`listRelated\` | Imperative relationship operations (same ideas as manifest \`defineRelationship\`). |
+| \`sessions.list()\`, \`sessions.create()\`, \`sessions.connect()\`, \`sessions.reopen()\`, \`sessions.close()\` | Session lifecycle for this environment. |
+
+### \`Session\` (live runtime connection)
+
+| API | Purpose |
+|-----|---------|
 | \`submitJob(code)\` | Run code in the sandbox; import from \`./sandbox-tools\`. |
+| \`answerPrompt(...)\`, \`appendMessage(...)\` | Human-in-the-loop and conversation APIs. |
 | \`getDomain()\`, \`getDomainTypes()\`, \`getDomainDocs()\`, \`getDomainDocumentation()\` | Domain summary and generated TypeScript / docs. |
-| \`getEffects()\` / \`getTools()\`, \`onEffectsChanged()\` | Effect catalog and updates. |
-| \`checkReadiness()\`, \`on('readiness', \u2026)\` | Environment readiness. |
+| \`getEffects()\` / \`getTools()\`, \`session.on("effects:changed", ...)\` | Effect catalog and live updates. |
+| \`checkReadiness()\`, \`on('readiness', ...)\` | Runtime readiness. |
 | \`getHeap()\` | Session state snapshot (advanced). |
+| \`disconnect()\` | Close the live runtime session. |
 | \`rpc(method, params)\` | Low-level session RPC (advanced). |
 | \`disconnect()\` | End the session. |
 
@@ -15423,9 +15423,9 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push(`  // apiUrl: process.env.GRANULAR_API_URL, // optional`);
   lines.push(`});`);
   lines.push("");
-  lines.push(`const env = await granular.connect({`);
+  lines.push(`const env = await granular.openEnvironment({`);
   lines.push(`  ontology: '${meta.sandboxId}',`);
-  lines.push(`  environment: 'dev',`);
+  lines.push(`  tag: 'dev',`);
   lines.push(`  userId: 'your_app_user_id',`);
   lines.push(`  permissions: ['default'],`);
   lines.push(`});`);
@@ -15544,7 +15544,7 @@ function generateSandboxAgentDoc(manifest, meta) {
     "1. **Build** the manifest so the domain package includes the effect (`granular build`)."
   );
   lines.push(
-    "2. **Register** a handler whose `name` (and `className` / `static` when applicable) matches \u2014 use `granular.registerEffects('" + meta.sandboxId + "', [...])` in your host process (see `granular-effects.ts` in starter projects)."
+    "2. **Register** a handler whose `name` (and `className` / `static` when applicable) matches \u2014 use `granular.ontology('" + meta.sandboxId + "').effects.registerMany([...])` in your host process (see `granular-effects.ts` in starter projects)."
   );
   lines.push(
     "3. **Invoke** from sandbox code via `./sandbox-tools` inside `submitJob`; the handler you registered runs in your process and the result returns to the job."
@@ -15612,7 +15612,8 @@ function generateSandboxAgentDoc(manifest, meta) {
   const globalEffects = effects2.filter((e) => !e.attachedClass);
   const firstGlobal = globalEffects[0]?.name;
   lines.push("```typescript");
-  lines.push(`const job = await env.submitJob(\``);
+  lines.push(`const session = await env.sessions.create();
+const job = await session.submitJob(\``);
   const importList = [...pascalImports, ...effectNames].filter(
     (v, i, a) => a.indexOf(v) === i
   );
@@ -15691,7 +15692,7 @@ function generateSandboxAgentDoc(manifest, meta) {
     "| Domain | `getDomain`, `getDomainTypes`, `getDomainDocumentation` |"
   );
   lines.push(
-    "| Effects | `registerEffects`, `getEffects`, `onEffectsChanged` |"
+    '| Effects | `granular.ontology(...).effects.registerMany`, `session.getEffects()`, `session.on("effects:changed", ...)` |'
   );
   lines.push("| Ops | `checkReadiness`, `getHeap`, `rpc` |");
   lines.push("");
@@ -18442,27 +18443,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(effects2) {
     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()."
     );
   }
   /**
@@ -19520,17 +19521,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;
@@ -19565,7 +19589,9 @@ function isRetryableLocalWorkerRestart(status, body, url) {
 }
 function isRetryableRecordObjectsError(error2) {
   const message = error2 instanceof Error ? error2.message : String(error2);
-  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();
@@ -19618,6 +19644,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;
@@ -19642,7 +19684,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,
@@ -19654,12 +19699,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;
@@ -19700,35 +19746,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, session2) => this.closeSession(sessionId, session2)
+    };
+  }
+  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 session2 = await this.granular["connectSession"]({
+      sessionId,
+      clientId: options?.clientId
+    });
+    if (session2.environmentId !== this.environmentId) {
+      await session2.disconnect().catch(() => {
+        session2.disconnectTransport();
+      });
+      throw new Error(
+        `Session ${sessionId} belongs to environment ${session2.environmentId}, not ${this.environmentId}.`
+      );
+    }
+    return session2;
+  }
+  async reopenSession(sessionId, options) {
+    const session2 = await this.granular.reopenSession(sessionId, {
+      clientId: options?.clientId
+    });
+    if (session2.environmentId !== this.environmentId) {
+      await session2.disconnect().catch(() => {
+        session2.disconnectTransport();
+      });
+      throw new Error(
+        `Session ${sessionId} belongs to environment ${session2.environmentId}, not ${this.environmentId}.`
+      );
     }
+    return session2;
+  }
+  async closeSession(sessionId, session2) {
+    await this.granular.closeSession(sessionId, session2);
+  }
+  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(path6, options = {}) {
     const runtimeBase = this.getRuntimeBaseUrl();
@@ -19736,94 +19873,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.
@@ -19852,14 +19914,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
@@ -19867,7 +19929,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 } } } }`
@@ -19879,7 +19941,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,
@@ -19896,10 +19958,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
@@ -19959,10 +20021,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');
@@ -19995,18 +20057,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)
@@ -20033,18 +20095,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');
    * ```
@@ -20068,11 +20130,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');
@@ -20096,14 +20158,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({
@@ -20141,12 +20203,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)`
+            );
           }
         }
       }
@@ -20230,7 +20296,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);
     }
   }
@@ -20279,7 +20348,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",
@@ -20562,7 +20633,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}`
@@ -20592,13 +20665,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 (error2) {
@@ -20661,7 +20731,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.
@@ -20674,36 +20746,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(effects2) {
-    return super.publishEffects(effects2);
+  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 (effects2) => this.granular.registerEffects(this.ontologyNameOrId, effects2),
+      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 {
@@ -20728,7 +20950,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);
@@ -20738,12 +20962,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({
@@ -20754,14 +20984,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,
@@ -20772,7 +21004,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 {
@@ -20808,76 +21056,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 tag2 = options.tag?.trim() || options.tagName?.trim() || options.environment?.trim();
+    if (!tag2) {
+      throw new Error(`${methodName}() requires \`tag\`.`);
+    }
+    return tag2;
+  }
+  buildManagedEnvironmentName(tag2, versionId) {
+    return `__sdk__${tag2}__${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 tag2 = (tags.items || []).find(
+      (candidate) => Boolean(candidate?.name === tagName)
+    );
+    if (!tag2) {
+      throw new Error(
+        `Tag "${tagName}" was not found for ontology ${sandbox.sandboxId}.`
+      );
+    }
+    const targetVersionId = tag2.targetVersionId || tag2.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, tag2.tagId) && environment.versionId === targetVersionId
+      )
+    );
+    if (currentMatches.length > 0) {
+      return currentMatches[0];
     }
-    const envData = await this.environments.create(sandbox.sandboxId, {
+    const outdatedMatches = this.sortEnvironmentsByRecency(
+      userEnvironments.filter(
+        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag2.tagId)
+      )
+    );
+    if (outdatedMatches.length > 0 && options.createFreshIfOutdated !== true) {
+      return outdatedMatches[0];
+    }
+    return this.environments.create(sandbox.sandboxId, {
       subjectId: user.granularId,
-      environment: environmentName,
-      tagName,
+      environment: this.buildManagedEnvironmentName(tagName, targetVersionId),
+      tagId: tag2.tagId,
       permissionProfileId: null
     });
-    await this.activateEnvironment(envData.environmentId);
-    const session2 = await this.request("/ws/sessions", {
-      method: "POST",
-      body: JSON.stringify({
-        environmentId: envData.environmentId,
-        clientId,
-        initialHeap: options.initialHeap
-      })
-    });
-    return this.bindWebSocketEnvironment(envData, clientId, session2);
   }
   /**
    * List active (open) sessions for an environment — each session is one agent conversation thread.
@@ -20912,7 +21225,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
@@ -20938,6 +21253,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 session2 = await this.request("/ws/sessions", {
       method: "POST",
       body: JSON.stringify({
@@ -20946,7 +21262,7 @@ var Granular = class _Granular {
         initialHeap: options.initialHeap
       })
     });
-    return this.bindWebSocketEnvironment(envData, clientId, session2);
+    return this.bindWebSocketEnvironmentSession(environment, clientId, session2);
   }
   /**
    * Connect to an existing open session (same conversation thread) using a freshly minted WebSocket token.
@@ -20958,7 +21274,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
@@ -20990,7 +21307,11 @@ var Granular = class _Granular {
     });
     return this.connectSession({ sessionId, clientId: options?.clientId });
   }
-  async bindWebSocketEnvironment(envData, clientId, session2) {
+  bindEnvironmentHandle(envData) {
+    const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
+    return new Environment(this, envData, this.apiKey, graphqlEndpoint);
+  }
+  async bindWebSocketEnvironmentSession(environment, clientId, session2) {
     const client = new WSClient({
       url: session2.wsUrl,
       sessionId: session2.sessionId,
@@ -21001,10 +21322,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`, {
@@ -21036,14 +21360,18 @@ var Granular = class _Granular {
     };
   }
   async publishSandboxEffectCatalog(host) {
-    const effects2 = Array.from(this.getSandboxEffectMap(host.sandboxId).values()).map(
-      (effect) => this.serializeEffect(effect)
-    );
-    const result = await host.wsClient.call("effects.publishCatalog", { effects: effects2 });
+    const effects2 = Array.from(
+      this.getSandboxEffectMap(host.sandboxId).values()
+    ).map((effect) => this.serializeEffect(effect));
+    const result = await host.wsClient.call("effects.publishCatalog", {
+      effects: effects2
+    });
     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}`
       );
@@ -21077,13 +21405,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:", error2);
-    });
+    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:", error2);
+      }
+    );
   }
   startEffectHostHeartbeat(host) {
     if (host.heartbeatTimer) {
@@ -21104,9 +21434,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) {
@@ -21138,7 +21474,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,
@@ -21157,7 +21498,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((error2) => {
@@ -21205,7 +21549,7 @@ var Granular = class _Granular {
   }
   /**
    * Register multiple effects (tools) for a specific sandbox.
-   * 
+   *
    * batch version of `registerEffect`.
    */
   async registerEffects(sandboxNameOrId, effects2) {
@@ -21219,7 +21563,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.
    */
@@ -21318,27 +21662,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
@@ -21418,23 +21766,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"
+          }
+        );
       }
     };
   }
@@ -21454,10 +21812,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,
@@ -21488,7 +21849,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;
@@ -21501,15 +21864,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((resolve2) => setTimeout(resolve2, interval));
           }
         };
         poll();
-        return { unsubscribe: () => {
-          running = false;
-        } };
+        return {
+          unsubscribe: () => {
+            running = false;
+          }
+        };
       },
       ack: async (eventId) => {
         await this.request("/control/stream-events/ack", {
@@ -21527,7 +21894,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,
@@ -21545,10 +21914,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`
+        );
       }
     };
   }
@@ -21558,24 +21931,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;
   }
   /**
@@ -21590,9 +21970,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
         }
       });
@@ -21603,7 +21983,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(
@@ -21662,7 +22046,7 @@ async function resolveEnvironmentData(granular, options) {
   const ontologyId = await resolveOntologyId(granular, options.ontology);
   const environmentName = options.environment ?? "dev";
   const environments = await granular.environments.list(ontologyId);
-  const existing = environments.find((environment) => matchesEnvironmentName(environment, environmentName));
+  const existing = environments.find((environment2) => matchesEnvironmentName(environment2, environmentName));
   if (existing) {
     return existing;
   }
@@ -21671,21 +22055,13 @@ async function resolveEnvironmentData(granular, options) {
       `No environment named \`${environmentName}\` found for ontology \`${ontologyId}\`. Run \`granular connect test\` or \`granular session create\` first, or pass \`--environment-id\`.`
     );
   }
-  const connection = await granular.connect({
+  const environment = await granular.openEnvironment({
     ontology: ontologyId,
-    environment: environmentName,
+    tag: environmentName,
     userId: options.userId ?? "granular-cli",
     permissions: options.permissions ?? ["default"]
   });
-  try {
-    return await granular.environments.get(connection.environmentId);
-  } finally {
-    try {
-      await connection.disconnect();
-    } catch {
-      connection?.client?.disconnect?.();
-    }
-  }
+  return await granular.environments.get(environment.environmentId);
 }
 async function listSessionsForEnvironment(granular, environmentId, status) {
   if (status === "all") {
@@ -21702,11 +22078,12 @@ async function listSessionsForEnvironment(granular, environmentId, status) {
 async function connectRuntime(options) {
   if (options.sessionId) {
     const { granular: granular2 } = createGranularClient();
-    const environment2 = await granular2.connectSession({ sessionId: options.sessionId });
+    const session3 = await granular2["connectSession"]({ sessionId: options.sessionId });
     return {
       granular: granular2,
-      environment: environment2,
-      ontologyId: environment2.ontologyId || environment2.sandboxId
+      environment: session3.environment,
+      session: session3,
+      ontologyId: session3.ontologyId || session3.sandboxId
     };
   }
   const { granular, config } = createGranularClient();
@@ -21714,15 +22091,17 @@ async function connectRuntime(options) {
   if (!ontologyId) {
     throw new Error("No ontology configured. Run `granular init` first or pass `--ontology`.");
   }
-  const environment = await granular.connect({
+  const environment = await granular.openEnvironment({
     ontology: ontologyId,
-    environment: options.environment ?? "dev",
+    tag: options.environment ?? "dev",
     userId: options.userId ?? "granular-cli",
     permissions: options.permissions ?? ["default"]
   });
+  const session2 = await environment.sessions.create();
   return {
     granular,
     environment,
+    session: session2,
     ontologyId
   };
 }
@@ -21732,9 +22111,9 @@ async function withRuntimeConnection(options, callback) {
     return await callback(connection);
   } finally {
     try {
-      await connection.environment.disconnect();
+      await connection.session.disconnect();
     } catch {
-      connection.environment?.client?.disconnect?.();
+      connection.session.disconnectTransport();
     }
   }
 }
@@ -21771,14 +22150,14 @@ async function connectTestCommand(options) {
       userId: options.user,
       permissions: normalizePermissions(options.permissions)
     },
-    async ({ environment, ontologyId }) => {
+    async ({ environment, session: session2, ontologyId }) => {
       const payload = {
         ok: true,
         ontologyId,
         sandboxId: environment.sandboxId,
         environmentId: environment.environmentId,
         environment: environment.environment,
-        sessionId: environment.sessionId,
+        sessionId: session2.sessionId,
         subjectId: environment.subjectId,
         versionId: environment.versionId
       };
@@ -21824,12 +22203,12 @@ async function sessionHeapCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, ontologyId }) => {
+    async ({ environment, session: session2, ontologyId }) => {
       const payload = {
         ontologyId,
-        sessionId: environment.sessionId,
+        sessionId: session2.sessionId,
         environmentId: environment.environmentId,
-        heap: environment.getHeap()
+        heap: session2.getHeap()
       };
       if (!emitJson) {
         step("Session heap");
@@ -21852,12 +22231,12 @@ async function sessionDocCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, ontologyId }) => {
+    async ({ environment, session: session2, ontologyId }) => {
       const payload = {
         ontologyId,
-        sessionId: environment.sessionId,
+        sessionId: session2.sessionId,
         environmentId: environment.environmentId,
-        document: documentToJson(environment.document)
+        document: documentToJson(session2.document)
       };
       if (!emitJson) {
         step("Session document");
@@ -21882,18 +22261,18 @@ async function sessionCreateCommand(options) {
     permissions,
     createIfMissing: true
   });
-  const environment = await granular.createSession({
+  const session2 = await granular.createSession({
     environmentId: envData.environmentId
   });
   try {
     const payload = {
       ok: true,
       ontologyId: envData.sandboxId,
-      environmentId: environment.environmentId,
-      environment: environment.environment,
-      sessionId: environment.sessionId,
-      subjectId: environment.subjectId,
-      versionId: environment.versionId
+      environmentId: session2.environmentId,
+      environment: session2.environment.environment,
+      sessionId: session2.sessionId,
+      subjectId: session2.subjectId,
+      versionId: session2.versionId
     };
     if (emitJson) {
       console.log(JSON.stringify(payload, null, 2));
@@ -21912,9 +22291,9 @@ async function sessionCreateCommand(options) {
     console.log();
   } finally {
     try {
-      await environment.disconnect();
+      await session2.disconnect();
     } catch {
-      environment?.client?.disconnect?.();
+      session2.disconnectTransport();
     }
   }
 }
@@ -21992,13 +22371,13 @@ async function graphqlCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, ontologyId }) => {
+    async ({ environment, session: session2, ontologyId }) => {
       const result = await environment.graphql(options.query, variables);
       const payload = {
         ok: !result.errors || result.errors.length === 0,
         ontologyId,
         environmentId: environment.environmentId,
-        sessionId: environment.sessionId,
+        sessionId: session2.sessionId,
         query: options.query,
         variables: variables ?? null,
         result
@@ -22039,12 +22418,12 @@ async function effectsListCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, ontologyId }) => {
-      const effects2 = sortEffects(environment.getEffects());
+    async ({ environment, session: session2, ontologyId }) => {
+      const effects2 = sortEffects(session2.getEffects());
       const payload = {
         ontologyId,
         environmentId: environment.environmentId,
-        sessionId: environment.sessionId,
+        sessionId: session2.sessionId,
         items: effects2
       };
       if (emitJson) {
@@ -22084,8 +22463,8 @@ async function effectsDiffCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, ontologyId }) => {
-      const effects2 = sortEffects(environment.getEffects());
+    async ({ environment, session: session2, ontologyId }) => {
+      const effects2 = sortEffects(session2.getEffects());
       const declared = effects2.map((effect) => effect.name);
       const liveReady = effects2.filter((effect) => effect.ready).map((effect) => effect.name);
       const declaredOnly = effects2.filter((effect) => !effect.ready).map((effect) => effect.name);
@@ -22093,7 +22472,7 @@ async function effectsDiffCommand(options) {
       const payload = {
         ontologyId,
         environmentId: environment.environmentId,
-        sessionId: environment.sessionId,
+        sessionId: session2.sessionId,
         summary: {
           declaredCount: declared.length,
           liveReadyCount: liveReady.length,
@@ -22147,8 +22526,8 @@ async function jobRunCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, ontologyId }) => {
-      const job2 = await environment.submitJob(code);
+    async ({ environment, session: session2, ontologyId }) => {
+      const job2 = await session2.submitJob(code);
       const stdout = [];
       const stderr = [];
       job2.on("stdout", (line) => {
@@ -22172,7 +22551,7 @@ async function jobRunCommand(options) {
         ok: true,
         ontologyId,
         environmentId: environment.environmentId,
-        sessionId: environment.sessionId,
+        sessionId: session2.sessionId,
         jobId: job2.id,
         status: job2.status,
         stdout,