@granular-software/sdk 0.4.30 → 0.4.32

package/dist/{client-BVvOMfln.d.mts → client-C2Gk641P.d.mts}

@@ -9,7 +9,7 @@ import { Doc } from '@automerge/automerge/slim';
  * Configuration for the Granular client
  */
 type AccessTokenProvider = () => Promise<string | null | undefined> | string | null | undefined;
-type EndpointMode = "auto" | "local" | "production";
+type EndpointMode = 'auto' | 'local' | 'production';
 interface GranularOptions {
     /** Your Granular API key (for service/CLI auth; use with GRANULAR_API_KEY) */
     apiKey?: string;
@@ -86,35 +86,72 @@ interface Subject {
     updatedAt: number;
 }
 /**
- * Options for connecting to an ontology environment
+ * Options for opening an ontology environment for one delegated subject.
+ *
+ * This does not open a live runtime session. Use
+ * `environment.sessions.create()` or `granular.createSession({ environmentId })`
+ * when you need a conversation/session with jobs, prompts, heap, and effects.
  */
-interface ConnectOptions {
-    /** The ontology name or ID to connect to */
+interface OpenEnvironmentOptions {
+    /** The ontology name or ID to open. */
     ontology: string;
-    /** Named environment slot such as `dev` or `prod` */
-    environment: string;
-    /** Advanced override for the version tag/channel to follow. In the common case, omit this. */
-    tagName?: string;
+    /** Version channel to follow, typically `dev` or `prod`. */
+    tag?: string;
     /**
-     * External user identifier from your app. This is the primary input for
-     * connecting to a sandbox and the only required user field in the common case.
+     * External user identifier from your app.
+     *
+     * Exactly one of `userId`, `granularId`, or `user` should be provided.
      */
     userId?: string;
     /**
-     * Internal Granular user identifier. Optional fallback when you only know
-     * the Granular-side ID for an existing subject.
+     * Internal Granular user identifier.
+     *
+     * Exactly one of `userId`, `granularId`, or `user` should be provided.
      */
     granularId?: string;
-    /** Optional display name used when upserting the user */
+    /** Optional display name used when upserting the user. */
     name?: string;
-    /** Optional email used when upserting the user */
+    /** Optional email used when upserting the user. */
     email?: string;
-    /** Permission profile IDs or names to ensure before connecting */
-    permissions?: string[];
-    /** Backwards-compatible user object returned from recordUser() */
+    /**
+     * Permission profile names or IDs to ensure before opening the environment.
+     * This should be provided even for existing users so the SDK can guarantee
+     * assignments for first-time environment creation.
+     */
+    permissions: string[];
+    /**
+     * When true, if the latest environment for this ontology/user/tag is marked
+     * outdated relative to the current tag target, create a fresh environment on
+     * the newest tag target instead of reusing the outdated one.
+     */
+    createFreshIfOutdated?: boolean;
+    /** Backwards-compatible user object returned from `recordUser()`. */
     user?: User;
-    /** Optional stable client ID. Defaults to `client_${Date.now()}`. Use a fixed
-     *  value for long-lived effect hosts so tool catalogs don't accumulate. */
+}
+/**
+ * Deprecated compatibility alias for the legacy `connect()` entry point.
+ *
+ * `connect()` now resolves an environment handle and no longer opens a runtime
+ * session automatically. Prefer `openEnvironment()` for new code.
+ */
+interface ConnectOptions extends OpenEnvironmentOptions {
+    /** @deprecated Legacy explicit environment slot name. Prefer `tag`. */
+    environment?: string;
+    /** @deprecated Legacy tag field. Prefer `tag`. */
+    tagName?: string;
+    /** @deprecated Ignored by `connect()` now that it no longer opens sessions. */
+    clientId?: string;
+    /** @deprecated Ignored by `connect()` now that it no longer opens sessions. */
+    initialHeap?: Array<{
+        className: string;
+        id: string;
+    }>;
+}
+/**
+ * Options for creating a live runtime session from an opened environment.
+ */
+interface CreateSessionOptions {
+    /** Optional stable client ID. Defaults to `client_${Date.now()}`. */
     clientId?: string;
     /** Optional session heap seed. Each item is eagerly hydrated into the session heap on connect. */
     initialHeap?: Array<{
@@ -131,7 +168,7 @@ interface ConversationSessionInfo {
     environmentId: string;
     versionId?: string | null;
     docId: string;
-    status: "active" | "closed" | "expired";
+    status: 'active' | 'closed' | 'expired';
     createdAt: string;
     lastSeenAt: string;
     summary?: string | null;
@@ -239,7 +276,7 @@ interface AssignmentListResponse {
  * pin themselves to one immutable ontology version.
  */
 interface BuildPolicy {
-    mode: "tag" | "current" | "pinned";
+    mode: 'tag' | 'current' | 'pinned';
     buildId?: string;
     versionId?: string;
     tagId?: string;
@@ -250,7 +287,7 @@ interface VersionTag {
     tagId: string;
     sandboxId: string;
     name: string;
-    kind: "channel" | "release" | "system";
+    kind: 'channel' | 'release' | 'system';
     targetBuildId?: string | null;
     targetVersionId?: string | null;
     description?: string | null;
@@ -275,7 +312,7 @@ interface EnvironmentData {
     tag?: VersionTag | null;
     tracking?: BuildPolicy;
     buildPolicy: BuildPolicy;
-    updateState?: "up_to_date" | "update_available" | "upgrading" | "failed";
+    updateState?: 'up_to_date' | 'update_available' | 'upgrading' | 'failed';
     createdAt: number;
     updatedAt: number;
 }
@@ -324,7 +361,7 @@ interface Manifest {
 interface ManifestListResponse {
     items: Manifest[];
 }
-type BuildStatus = "queued" | "building" | "completed" | "failed" | "canceled";
+type BuildStatus = 'queued' | 'building' | 'completed' | 'failed' | 'canceled';
 /**
  * An immutable ontology version derived from a specific manifest revision.
  *
@@ -359,8 +396,8 @@ interface BuildListResponse {
 }
 interface SemanticVersionDiffEntry {
     operationId: string;
-    kind: "create" | "update" | "relationship" | "effect" | "eventStream" | "unknown";
-    changeType: "added" | "removed" | "changed";
+    kind: 'create' | 'update' | 'relationship' | 'effect' | 'eventStream' | 'unknown';
+    changeType: 'added' | 'removed' | 'changed';
     label: string;
     additive: boolean;
     breaking: boolean;
@@ -422,7 +459,7 @@ interface ResolvedEffectBehaviors {
     reverse?: ResolvedEffectReverse;
     approvalRequired?: ResolvedEffectApprovalRequired;
 }
-type EffectInvocationMode = "execute" | "dryRun" | "reverse";
+type EffectInvocationMode = 'execute' | 'dryRun' | 'reverse';
 interface EffectInvocationMetadata {
     mode?: EffectInvocationMode;
     reverseHandler?: string;
@@ -479,9 +516,9 @@ interface ToolSchema {
      * ```
      */
     outputSchema?: Record<string, unknown>;
-    stability?: "stable" | "experimental" | "deprecated";
+    stability?: 'stable' | 'experimental' | 'deprecated';
     provenance?: {
-        source: "mcp" | "custom";
+        source: 'mcp' | 'custom';
     };
     tags?: string[];
     /**
@@ -588,8 +625,8 @@ interface EffectsChangedEvent extends ToolsChangedEvent {
 }
 type EffectHandler = ToolHandler;
 type InstanceEffectHandler = InstanceToolHandler;
-type JobStatus = "queued" | "running" | "awaitingTool" | "awaitingHuman" | "succeeded" | "failed" | "timeout" | "canceled";
-type JobFeedbackSentiment = "good" | "bad";
+type JobStatus = 'queued' | 'running' | 'awaitingTool' | 'awaitingHuman' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
+type JobFeedbackSentiment = 'good' | 'bad';
 interface JobFeedbackToolCall {
     callId?: string;
     toolName?: string;
@@ -601,7 +638,7 @@ interface JobFeedbackToolCall {
     durationMs?: number | null;
 }
 interface JobFeedbackMetadata {
-    source: "sdk";
+    source: 'sdk';
     status: JobStatus;
     code: string;
     domainRevision?: string;
@@ -634,6 +671,18 @@ interface JobFeedbackRecord {
     createdAt: number;
     updatedAt: number;
 }
+/**
+ * Persisted feedback row listed at the environment level.
+ */
+interface EnvironmentFeedbackRecord {
+    feedbackId: string;
+    sessionId: string;
+    jobId: string;
+    sentiment: JobFeedbackSentiment;
+    comment?: string | null;
+    metadata?: Record<string, unknown> | null;
+    createdAt: string | null;
+}
 /**
  * Result from submitting a job
  */
@@ -653,11 +702,11 @@ interface Job {
     /** Attach user feedback to this job and persist it with job/session metadata */
     leaveFeedback(input: JobFeedbackInput): Promise<JobFeedbackRecord>;
     /** Subscribe to job events */
-    on(event: string, handler: (data: unknown) => void): void;
+    on(event: string, handler: (data: unknown) => void): () => void;
 }
 interface Prompt {
     id: string;
-    type: "confirm" | "choice" | "input";
+    type: 'confirm' | 'choice' | 'input';
     title: string;
     message: string;
     options?: Array<string | {
@@ -676,7 +725,7 @@ interface ConversationMessageShowRefs {
     variableNames?: string[];
 }
 interface ConversationMessageInput {
-    role: "user" | "assistant";
+    role: 'user' | 'assistant';
     content?: string;
     show?: ConversationMessageShowRefs;
     jobId?: string;
@@ -692,7 +741,7 @@ interface ConversationAppendResult {
 }
 interface SessionTranscriptEntry {
     id: string;
-    role: "user" | "assistant";
+    role: 'user' | 'assistant';
     content: string;
     timestamp: number;
     jobId?: string;
@@ -703,9 +752,9 @@ interface SessionTranscriptEntry {
     error?: string;
     show?: ConversationMessageShowRefs;
     historyContent?: string;
-    source: "conversation" | "job_code" | "job_result" | "job_prompt" | "job_agent_message";
+    source: 'conversation' | 'job_code' | 'job_result' | 'job_prompt' | 'job_agent_message';
 }
-type SessionHeapFieldType = "string" | "number" | "boolean" | "null" | "unknown";
+type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
 interface SessionHeapFieldValue {
     name: string;
     type: SessionHeapFieldType;
@@ -733,7 +782,7 @@ interface SessionHeapList {
 }
 interface SessionHeapVariable {
     name: string;
-    kind: "entry" | "list" | "scalar";
+    kind: 'entry' | 'list' | 'scalar';
     entryPath?: string;
     listName?: string;
     value?: string | number | boolean | null;
@@ -770,13 +819,13 @@ interface WSClientOptions {
     onReconnectError?: (info: WSReconnectErrorInfo) => void;
 }
 interface RPCRequest {
-    type: "rpc";
+    type: 'rpc';
     method: string;
     params: unknown;
     id: string;
 }
 interface RPCResponse {
-    type: "rpc_result" | "rpc_error";
+    type: 'rpc_result' | 'rpc_error';
     id: string;
     result?: unknown;
     error?: {
@@ -786,12 +835,12 @@ interface RPCResponse {
     };
 }
 interface SyncMessage {
-    type: "sync";
+    type: 'sync';
     message?: string | number[] | Uint8Array;
     data?: number[];
 }
 interface RPCRequestFromServer {
-    type: "rpc";
+    type: 'rpc';
     method: string;
     params: unknown;
     id: string;
@@ -835,7 +884,7 @@ interface RelationshipInfo {
     /** The foreign model type */
     foreign_model: ModelRef;
     /** Computed relationship kind: "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" */
-    relationship_kind: "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many";
+    relationship_kind: 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many';
 }
 /**
  * Options for defining a relationship between two model types
@@ -934,8 +983,8 @@ interface RecordObjectsOptions {
      */
     onChunkComplete?: (info: RecordObjectsChunkInfo) => void | Promise<void>;
 }
-type RecordImportStatus = "queued" | "processing" | "completed" | "failed" | "canceled";
-type RecordImportItemStatus = "queued" | "processing" | "completed" | "failed" | "canceled";
+type RecordImportStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
+type RecordImportItemStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
 interface RecordImportStats {
     totalRecords: number;
     queuedRecords: number;
@@ -1000,14 +1049,10 @@ interface ManifestPropertySpec {
     required?: boolean;
     note?: string | string[];
     enum?: string[] | ManifestEnumRuleSpec;
-    searchable?: boolean | {
-        enabled?: boolean;
-        phonetic?: boolean;
-    };
     filterBy?: boolean | string[] | ManifestFilterBySpec;
     validate?: ManifestValidationRuleSpec[];
 }
-type ManifestValidationOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "true" | "false" | "regex" | "contains" | "not_contains" | "starts_with" | "ends_with";
+type ManifestValidationOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'true' | 'false' | 'regex' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with';
 interface ManifestEnumRuleSpec {
     values: string[];
     message?: string;
@@ -1096,7 +1141,7 @@ interface ManifestEffectDeclaration {
     isStatic?: boolean;
     inputSchema: ManifestEffectSchema;
     outputSchema?: ManifestEffectSchema;
-    stability?: "stable" | "experimental" | "deprecated";
+    stability?: 'stable' | 'experimental' | 'deprecated';
     tags?: string[];
     metamodels?: ManifestEffectMetamodelSpec;
 }
@@ -1157,7 +1202,7 @@ interface ManifestImport {
 }
 interface ManifestVolume {
     name: string;
-    scope: "sandbox" | "build" | "user";
+    scope: 'sandbox' | 'build' | 'user';
     imports?: ManifestImport[];
     operations: ManifestOperation[];
 }
@@ -1200,7 +1245,7 @@ interface StreamEvent {
     environmentId: string;
     sessionId?: string;
     subjectId?: string;
-    source: "sandbox" | "api";
+    source: 'sandbox' | 'api';
     isAcked: boolean;
     createdAt: number;
 }
@@ -1432,7 +1477,7 @@ declare class Session {
     /**
      * Subscribe to session events
      */
-    on(event: string, handler: (data: unknown) => void): void;
+    on(event: string, handler: (data: unknown) => void): () => void;
     /**
      * Unsubscribe from session events
      */
@@ -1447,27 +1492,18 @@ declare class Session {
 }
 
 /**
- * Environment represents a connected session to a sandbox for a specific user.
- *
- * After connecting, you can:
- * 1. Define your domain ontology via `applyManifest()` (classes, properties, relationships)
- * 2. Record object instances via `recordObject()` (with fields and relationship attachments)
- * 3. Register sandbox-scoped effects via `granular.registerEffect()` / `granular.registerEffects()`
- * 4. Submit jobs via `submitJob()` that import auto-generated typed classes from `./sandbox-tools`
- * 5. Execute GraphQL queries via `graphql()` (authenticated automatically)
- * 6. List available effects via `getEffects()` and listen for updates via `onEffectsChanged()`
+ * Environment is the sessionless handle for one resolved ontology environment.
  *
- * Tool calls from the sandbox automatically invoke your handlers via reverse-RPC.
- *
- * Object IDs are unique per class. Internally, the graph path is `{className}_{id}`
- * (e.g., `author_tolkien`). Use `Environment.toGraphPath()` and
- * `Environment.extractIdFromGraphPath()` for conversions.
+ * Use it to query or mutate environment data directly, or to open live runtime
+ * sessions through `environment.sessions.*` when you need jobs, prompts, or a
+ * synced Automerge document.
  */
-declare class Environment extends Session {
+declare class Environment {
+    private granular;
     private envData;
     private _apiKey;
     private _apiEndpoint;
-    constructor(client: WSClient, envData: EnvironmentData, clientId: string, apiKey: string, apiEndpoint: string);
+    constructor(granular: Granular, envData: EnvironmentData, apiKey: string, apiEndpoint: string);
     /** The environment ID */
     get environmentId(): string;
     /** The sandbox ID */
@@ -1486,65 +1522,68 @@ declare class Environment extends Session {
     get granularId(): string;
     /** The permission profile ID */
     get permissionProfileId(): string;
+    /** The current build policy backing this environment */
+    get buildPolicy(): BuildPolicy;
+    /** The current update state relative to the followed tag */
+    get updateState(): EnvironmentData["updateState"];
+    /** Convenience flag for whether this environment trails the current tag target */
+    get isOutdated(): boolean;
+    /** The followed tag name when this environment is tag-tracked */
+    get tag(): string | null;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    /** Internal auth token used for control-plane and runtime fallback requests */
+    get authToken(): string;
+    /** Base runtime URL derived from the GraphQL endpoint */
+    get runtimeBaseUrl(): string;
+    get sessions(): {
+        list: (options?: {
+            status?: "active" | "closed" | "all";
+        }) => Promise<ConversationSessionInfo[]>;
+        create: (options?: CreateSessionOptions) => Promise<EnvironmentSession>;
+        connect: (sessionId: string, options?: {
+            clientId?: string;
+        }) => Promise<EnvironmentSession>;
+        reopen: (sessionId: string, options?: {
+            clientId?: string;
+        }) => Promise<EnvironmentSession>;
+        close: (sessionId: string, session?: EnvironmentSession | null) => Promise<void>;
+    };
+    get data(): {
+        record: (record: RecordObjectOptions) => Promise<RecordObjectResult>;
+        recordMany: (records: RecordObjectOptions[], options?: RecordObjectsOptions) => Promise<RecordObjectResult[]>;
+        import: (records: RecordObjectOptions[], options?: {
+            batchSize?: number;
+        }) => Promise<RecordImport>;
+        listImports: (status?: RecordImportStatus) => Promise<RecordImport[]>;
+        getImport: (importId: string) => Promise<RecordImport>;
+        getImportSummary: () => Promise<EnvironmentRecordImportSummary>;
+        cancelImport: (importId: string) => Promise<RecordImport>;
+        getAwaitingCount: () => Promise<number>;
+    };
+    get feedback(): {
+        list: () => Promise<EnvironmentFeedbackRecord[]>;
+    };
     /**
-     * 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(): SessionHeapSnapshot;
+    disconnect(): Promise<void>;
+    listSessions(status?: "active" | "closed" | "all"): Promise<ConversationSessionInfo[]>;
+    createSession(options?: CreateSessionOptions): Promise<EnvironmentSession>;
+    connectSession(sessionId: string, options?: {
+        clientId?: string;
+    }): Promise<EnvironmentSession>;
+    reopenSession(sessionId: string, options?: {
+        clientId?: string;
+    }): Promise<EnvironmentSession>;
+    closeSession(sessionId: string, session?: EnvironmentSession | null): Promise<void>;
+    listFeedback(): Promise<EnvironmentFeedbackRecord[]>;
     private getRuntimeBaseUrl;
     private controlPlaneRequest;
-    /**
-     * 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.
-     */
-    disconnect(): Promise<void>;
-    /**
-     * Close only the socket transport without sending `client.goodbye`.
-     *
-     * Use this when the caller intends to immediately reattach to the same
-     * session after an unexpected disconnect.
-     */
-    disconnectTransport(): void;
-    /** The last known graph container status, updated by checkReadiness() or on heartbeat */
-    graphContainerStatus: {
-        lastKeepAliveAt: number;
-        status: "warming" | "hot" | "unknown";
-    } | 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);
-     * });
-     * ```
-     */
-    checkReadiness(): Promise<{
-        lastKeepAliveAt: number;
-        status: "warming" | "hot" | "unknown";
-    }>;
     /**
      * Convert a class name + real-world ID into a unique graph path.
      *
@@ -1822,26 +1861,107 @@ declare class Environment extends Session {
      * Cancel a queued/background record import.
      */
     cancelRecordImport(importId: string): Promise<RecordImport>;
+}
+/**
+ * Live runtime session attached to one opened environment.
+ *
+ * This is the object returned by `environment.sessions.create()` and friends.
+ * It owns websocket state, prompts, job execution, and the synced Automerge
+ * document while delegating environment-level data APIs back to
+ * `session.environment`.
+ */
+declare class EnvironmentSession extends Session {
+    readonly environment: Environment;
+    /** The last known graph container status, updated by checkReadiness() or on heartbeat */
+    graphContainerStatus: {
+        lastKeepAliveAt: number;
+        status: "warming" | "hot" | "unknown";
+    } | null;
+    constructor(client: WSClient, environment: Environment, clientId: string);
+    get environmentId(): string;
+    get sandboxId(): string;
+    get ontologyId(): string;
+    get subjectId(): string;
+    get envName(): string;
+    get versionId(): string;
+    get granularId(): string;
+    get permissionProfileId(): string;
+    get apiEndpoint(): string;
+    get data(): {
+        record: (record: RecordObjectOptions) => Promise<RecordObjectResult>;
+        recordMany: (records: RecordObjectOptions[], options?: RecordObjectsOptions) => Promise<RecordObjectResult[]>;
+        import: (records: RecordObjectOptions[], options?: {
+            batchSize?: number;
+        } | undefined) => Promise<RecordImport>;
+        listImports: (status?: RecordImportStatus) => Promise<RecordImport[]>;
+        getImport: (importId: string) => Promise<RecordImport>;
+        getImportSummary: () => Promise<EnvironmentRecordImportSummary>;
+        cancelImport: (importId: string) => Promise<RecordImport>;
+        getAwaitingCount: () => Promise<number>;
+    };
+    get feedback(): {
+        list: () => Promise<EnvironmentFeedbackRecord[]>;
+    };
     /**
-     * Removed: environment-scoped effect publication is no longer supported.
+     * Return a plain JS snapshot of the synced session heap.
      */
-    publishTools(tools: ToolWithHandler[], revision?: string): Promise<PublishToolsResult>;
+    getHeap(): SessionHeapSnapshot;
+    graphql<T = any>(query: string, variables?: Record<string, any>): Promise<GraphQLResult<T>>;
+    defineRelationship(options: DefineRelationshipOptions): Promise<RelationshipInfo>;
+    getRelationships(modelPath: string): Promise<RelationshipInfo[]>;
+    attach(modelPath: string, submodelPath: string, targetPath: string): Promise<void>;
+    detach(modelPath: string, submodelPath: string, targetPath?: string): Promise<void>;
+    listRelated(modelPath: string, submodelPath: string): Promise<ModelRef[]>;
+    applyManifest(manifest: ManifestContent): Promise<{
+        applied: number;
+        errors: string[];
+    }>;
+    recordObject(options: RecordObjectOptions): Promise<RecordObjectResult>;
+    recordObjects(records: RecordObjectOptions[], options?: RecordObjectsOptions): Promise<RecordObjectResult[]>;
+    enqueueRecordImport(records: RecordObjectOptions[], options?: {
+        batchSize?: number;
+    }): Promise<RecordImport>;
+    listRecordImports(status?: RecordImportStatus): Promise<RecordImport[]>;
+    getRecordImportSummary(): Promise<EnvironmentRecordImportSummary>;
+    getAwaitingRecordCount(): Promise<number>;
+    getRecordImport(importId: string): Promise<RecordImport>;
+    cancelRecordImport(importId: string): Promise<RecordImport>;
+    listFeedback(): Promise<EnvironmentFeedbackRecord[]>;
     /**
-     * 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.
      */
-    publishEffect(effect: ToolWithHandler): Promise<PublishToolsResult>;
+    disconnect(): Promise<void>;
     /**
-     * Removed: environment-scoped effect publication is no longer supported.
+     * Close only the socket transport without sending `client.goodbye`.
      */
-    publishEffects(effects: ToolWithHandler[]): Promise<PublishToolsResult>;
+    disconnectTransport(): void;
     /**
-     * Removed: environment-scoped effect publication is no longer supported.
+     * Backwards-compatible alias for `disconnect()`.
      */
-    unpublishEffect(name: string): Promise<PublishToolsResult>;
+    close(): Promise<void>;
     /**
-     * Removed: environment-scoped effect publication is no longer supported.
+     * Check if the graph container is ready and warm.
      */
-    unpublishAllEffects(): Promise<PublishToolsResult>;
+    checkReadiness(): Promise<{
+        lastKeepAliveAt: number;
+        status: "warming" | "hot" | "unknown";
+    }>;
+}
+declare class OntologyHandle {
+    private granular;
+    private ontologyNameOrId;
+    constructor(granular: Granular, ontologyNameOrId: string);
+    get effects(): {
+        register: (effect: ToolWithHandler) => Promise<void>;
+        registerMany: (effects: ToolWithHandler[]) => Promise<void>;
+        unregister: (name: string) => Promise<void>;
+        clear: () => Promise<void>;
+        disconnect: () => Promise<void>;
+    };
 }
 declare class Granular {
     private apiKey;
@@ -1863,6 +1983,10 @@ declare class Granular {
      * @param options - Client configuration
      */
     constructor(options: GranularOptions);
+    /**
+     * Return an ontology-scoped handle for effects and other ontology-level APIs.
+     */
+    ontology(ontologyNameOrId: string): OntologyHandle;
     /**
      * Records/upserts a user and prepares them for sandbox connections
      *
@@ -1879,43 +2003,46 @@ declare class Granular {
      * ```
      */
     recordUser(options: RecordUserOptions): Promise<User>;
+    /**
+     * Alias for `recordUser()` with user-facing naming that matches upsert semantics.
+     */
+    upsertUser(options: RecordUserOptions): Promise<User>;
     private resolveConnectUser;
     /**
-     * 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);
      * ```
      */
+    openEnvironment(options: OpenEnvironmentOptions): Promise<Environment>;
+    /**
+     * Deprecated compatibility alias for `openEnvironment()`.
+     *
+     * `connect()` no longer opens a runtime session automatically.
+     */
     connect(options: ConnectOptions): Promise<Environment>;
+    private resolveRequestedTag;
+    private buildManagedEnvironmentName;
+    private matchesTagTrackedEnvironment;
+    private sortEnvironmentsByRecency;
+    private resolveOpenEnvironmentData;
     /**
      * List active (open) sessions for an environment — each session is one agent conversation thread.
      */
@@ -1938,27 +2065,28 @@ declare class Granular {
     createSession(options: {
         environmentId: string;
         clientId?: string;
-        initialHeap?: ConnectOptions["initialHeap"];
-    }): Promise<Environment>;
+        initialHeap?: CreateSessionOptions["initialHeap"];
+    }): Promise<EnvironmentSession>;
     /**
      * Connect to an existing open session (same conversation thread) using a freshly minted WebSocket token.
      */
     connectSession(options: {
         sessionId: string;
         clientId?: string;
-    }): Promise<Environment>;
+    }): Promise<EnvironmentSession>;
     /**
      * Mark a session closed in the control plane. If `environment` is the connected handle for that
      * `sessionId`, disconnects the WebSocket so the runtime tears down cleanly.
      */
-    closeSession(sessionId: string, environment?: Environment | null): Promise<void>;
+    closeSession(sessionId: string, environment?: EnvironmentSession | null): Promise<void>;
     /**
      * Re-open a closed session in the index and connect to its existing runtime document.
      */
     reopenSession(sessionId: string, options?: {
         clientId?: string;
-    }): Promise<Environment>;
-    private bindWebSocketEnvironment;
+    }): Promise<EnvironmentSession>;
+    private bindEnvironmentHandle;
+    private bindWebSocketEnvironmentSession;
     private activateEnvironment;
     private getSandboxEffectMap;
     private serializeEffect;
@@ -2102,4 +2230,4 @@ declare class Granular {
     private request;
 }
 
-export { type ResolvedEffectApprovalRequired as $, type AccessTokenProvider as A, type BuildPolicy as B, type ConnectOptions as C, type DomainState as D, type EndpointMode as E, type EnvironmentListResponse as F, Granular as G, type Manifest as H, type InstanceToolHandler as I, type ManifestListResponse as J, type BuildStatus as K, type Build as L, type ManifestEffectMetamodelSpec as M, type Version as N, type BuildListResponse as O, type Prompt as P, type SemanticVersionDiffEntry as Q, type ResolvedEffectBehaviors as R, type SessionHeapEntry as S, type ToolWithHandler as T, type User as U, type VersionTracking as V, WSClient as W, type SemanticVersionDiff as X, type ResolvedEffectPostCondition as Y, type ResolvedEffectDryRun as Z, type ResolvedEffectReverse as _, type EffectHandlerContext as a, type ManifestEventStreamDef as a$, type EffectInvocationMode as a0, type EffectInvocationMetadata as a1, type EffectSchema as a2, type EffectWithHandler as a3, type PublishEffectsResult as a4, type ToolInfo as a5, type EffectInfo as a6, type ToolsChangedEvent as a7, type EffectsChangedEvent as a8, type EffectHandler as a9, type DefineRelationshipOptions as aA, type RecordObjectOptions as aB, type RecordObjectResult as aC, type RecordObjectsChunkInfo as aD, type RecordObjectsOptions as aE, type RecordImportStatus as aF, type RecordImportItemStatus as aG, type RecordImportStats as aH, type RecordImportItem as aI, type RecordImport as aJ, type EnvironmentRecordImportSummary as aK, type ManifestPropertySpec as aL, type ManifestValidationOperator as aM, type ManifestEnumRuleSpec as aN, type ManifestFilterBySpec as aO, type ManifestValidationRuleSpec as aP, type ManifestStateMachineStateSpec as aQ, type ManifestStateMachineTransitionSpec as aR, type ManifestStateMachineSpec as aS, type ManifestPostConditionSpec as aT, type ManifestDryRunSpec as aU, type ManifestReverseSpec as aV, type ManifestApprovalRequiredSpec as aW, type ManifestRelationshipDef as aX, type ManifestEffectSchema as aY, type ManifestEffectDeclaration as aZ, type ManifestEventTypeDef as a_, type InstanceEffectHandler as aa, type JobStatus as ab, type JobFeedbackSentiment as ac, type JobFeedbackToolCall as ad, type JobFeedbackMetadata as ae, type JobFeedbackInput as af, type JobFeedbackRecord as ag, type JobSubmitResult as ah, type Job as ai, type ConversationMessageShowRefs as aj, type ConversationMessageInput as ak, type ConversationAppendResult as al, type SessionHeapFieldType as am, type SessionHeapFieldValue as an, type SessionHeapVariable as ao, type WSDisconnectInfo as ap, type WSReconnectErrorInfo as aq, type WSClientOptions as ar, type RPCRequest as as, type RPCResponse as at, type SyncMessage as au, type RPCRequestFromServer as av, type ToolInvokeParams as aw, type ToolResultParams as ax, type ModelRef as ay, type RelationshipInfo as az, type SessionHeapList as b, type ManifestOperation as b0, type ManifestImport as b1, type ManifestVolume as b2, type ManifestContent as b3, type GraphQLResult as b4, type APIError as b5, type DeleteResponse as b6, type StreamEvent as b7, type StreamSubscription as b8, type StreamStats as b9, type SessionHeapSnapshot as c, type SessionTranscriptEntry as d, Environment as e, Session as f, type ToolSchema as g, type PublishToolsResult as h, type ToolHandler as i, type GranularOptions as j, type GranularAuth as k, type RecordUserOptions as l, type Subject as m, type ConversationSessionInfo as n, type Sandbox as o, type CreateSandboxData as p, type SandboxListResponse as q, type PermissionRules as r, type PermissionProfile as s, type CreatePermissionProfileData as t, type PermissionProfileListResponse as u, type Assignment as v, type AssignmentListResponse as w, type VersionTag as x, type EnvironmentData as y, type CreateEnvironmentData as z };
+export { type SemanticVersionDiff as $, type AccessTokenProvider as A, type BuildPolicy as B, type ConnectOptions as C, type DomainState as D, type EndpointMode as E, type VersionTag as F, Granular as G, type EnvironmentData as H, type InstanceToolHandler as I, type CreateEnvironmentData as J, type EnvironmentListResponse as K, type Manifest as L, type ManifestEffectMetamodelSpec as M, type ManifestListResponse as N, OntologyHandle as O, type Prompt as P, type BuildStatus as Q, type ResolvedEffectBehaviors as R, type SessionHeapEntry as S, type ToolWithHandler as T, type User as U, type VersionTracking as V, WSClient as W, type Build as X, type Version as Y, type BuildListResponse as Z, type SemanticVersionDiffEntry as _, type EffectHandlerContext as a, type ManifestApprovalRequiredSpec as a$, type ResolvedEffectPostCondition as a0, type ResolvedEffectDryRun as a1, type ResolvedEffectReverse as a2, type ResolvedEffectApprovalRequired as a3, type EffectInvocationMode as a4, type EffectInvocationMetadata as a5, type EffectSchema as a6, type EffectWithHandler as a7, type PublishEffectsResult as a8, type ToolInfo as a9, type RPCRequestFromServer as aA, type ToolInvokeParams as aB, type ToolResultParams as aC, type ModelRef as aD, type RelationshipInfo as aE, type DefineRelationshipOptions as aF, type RecordObjectOptions as aG, type RecordObjectResult as aH, type RecordObjectsChunkInfo as aI, type RecordObjectsOptions as aJ, type RecordImportStatus as aK, type RecordImportItemStatus as aL, type RecordImportStats as aM, type RecordImportItem as aN, type RecordImport as aO, type EnvironmentRecordImportSummary as aP, type ManifestPropertySpec as aQ, type ManifestValidationOperator as aR, type ManifestEnumRuleSpec as aS, type ManifestFilterBySpec as aT, type ManifestValidationRuleSpec as aU, type ManifestStateMachineStateSpec as aV, type ManifestStateMachineTransitionSpec as aW, type ManifestStateMachineSpec as aX, type ManifestPostConditionSpec as aY, type ManifestDryRunSpec as aZ, type ManifestReverseSpec as a_, type EffectInfo as aa, type ToolsChangedEvent as ab, type EffectsChangedEvent as ac, type EffectHandler as ad, type InstanceEffectHandler as ae, type JobStatus as af, type JobFeedbackSentiment as ag, type JobFeedbackToolCall as ah, type JobFeedbackMetadata as ai, type JobFeedbackInput as aj, type JobFeedbackRecord as ak, type EnvironmentFeedbackRecord as al, type JobSubmitResult as am, type Job as an, type ConversationMessageShowRefs as ao, type ConversationMessageInput as ap, type ConversationAppendResult as aq, type SessionHeapFieldType as ar, type SessionHeapFieldValue as as, type SessionHeapVariable as at, type WSDisconnectInfo as au, type WSReconnectErrorInfo as av, type WSClientOptions as aw, type RPCRequest as ax, type RPCResponse as ay, type SyncMessage as az, type SessionHeapList as b, type ManifestRelationshipDef as b0, type ManifestEffectSchema as b1, type ManifestEffectDeclaration as b2, type ManifestEventTypeDef as b3, type ManifestEventStreamDef as b4, type ManifestOperation as b5, type ManifestImport as b6, type ManifestVolume as b7, type ManifestContent as b8, type GraphQLResult as b9, type APIError as ba, type DeleteResponse as bb, type StreamEvent as bc, type StreamSubscription as bd, type StreamStats as be, type SessionHeapSnapshot as c, type SessionTranscriptEntry as d, Environment as e, EnvironmentSession as f, Session as g, type ToolSchema as h, type PublishToolsResult as i, type ToolHandler as j, type GranularOptions as k, type GranularAuth as l, type RecordUserOptions as m, type Subject as n, type OpenEnvironmentOptions as o, type CreateSessionOptions as p, type ConversationSessionInfo as q, type Sandbox as r, type CreateSandboxData as s, type SandboxListResponse as t, type PermissionRules as u, type PermissionProfile as v, type CreatePermissionProfileData as w, type PermissionProfileListResponse as x, type Assignment as y, type AssignmentListResponse as z };