@granular-software/sdk 0.4.11 → 0.4.13

package/dist/cli/index.js

@@ -10,6 +10,7 @@ var crypto = require('crypto');
 var process6 = require('process');
 var os = require('os');
 var tty = require('tty');
+var metamodelPresetDefault = require('@granular-software/metamodel-preset-default');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -8833,10 +8834,29 @@ function sandboxDocScopeSection(projectName) {
 
 If **syntax** or **Granular behavior** is unclear, use the manifest guide; use **this** file for **ontology facts** for **${projectName}**.`;
 }
+function getFieldMetamodelDocRows() {
+  return metamodelPresetDefault.collectMetamodelDocRows("fieldRows");
+}
+function getModelMetamodelDocRows() {
+  return metamodelPresetDefault.collectMetamodelDocRows("modelRows");
+}
+function getEffectMetamodelDocRows() {
+  return metamodelPresetDefault.collectMetamodelDocRows("effectRows");
+}
+function renderMetamodelDocTable(rows) {
+  return [
+    "| Key | Meaning |",
+    "|-----|---------|",
+    ...rows.map((row) => `| \`${row.key}\` | ${row.description} |`)
+  ].join("\n");
+}
 
 // src/cli/agent-docs/manifest-guide.ts
 function generateManifestAgentGuide(options) {
   const { projectName } = options;
+  const fieldMetamodelTable = renderMetamodelDocTable(getFieldMetamodelDocRows());
+  const modelMetamodelTable = renderMetamodelDocTable(getModelMetamodelDocRows());
+  const effectMetamodelTable = renderMetamodelDocTable(getEffectMetamodelDocRows());
   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).
@@ -8942,6 +8962,66 @@ Each key under \`has\` is a **field name** on the class. Each value is a **field
 - Every scalar field should have \`"type": "..."\`.
 - Do **not** store links to other entities as opaque strings when you can use **relationships** (next section).
 
+### Field metamodels
+
+Scalar fields can carry lightweight metamodels directly in their field spec:
+
+\`\`\`json
+{
+  "create": "ticket",
+  "extends": "@std/class",
+  "note": "Ticket workflow object",
+  "stateMachines": [
+    {
+      "name": "lifecycle",
+      "entryState": "draft",
+      "states": ["draft", "active", { "name": "done", "isFinal": true }],
+      "finalStates": ["canceled"],
+      "transitions": [
+        { "name": "activate", "from": "draft", "to": "active" },
+        { "name": "complete", "from": "active", "to": "done" },
+        { "name": "cancel", "from": "draft", "to": "canceled" }
+      ]
+    }
+  ],
+  "has": {
+    "title": {
+      "type": "string",
+      "required": true,
+      "note": "Must use the canonical prefix",
+      "filterBy": true,
+      "validate": [
+        { "operator": "regex", "stringValue": "^TKT-[A-Z0-9-]+$" }
+      ]
+    },
+    "status": {
+      "type": "string",
+      "enum": {
+        "values": ["draft", "active", "done", "canceled"],
+        "message": "Invalid ticket status"
+      },
+      "filterBy": ["equal_to", "contains"]
+    },
+    "estimate": {
+      "type": "number",
+      "filterBy": true,
+      "validate": [
+        { "operator": "gt", "numberValue": 0 },
+        { "operator": "lt", "numberValue": 100 }
+      ]
+    }
+  }
+}
+\`\`\`
+
+Supported field metamodel keys:
+
+${fieldMetamodelTable}
+
+Supported model-level metamodel keys:
+
+${modelMetamodelTable}
+
 ---
 
 ## Operations: \`defineRelationship\` (model links precisely)
@@ -9027,6 +9107,50 @@ Example:
 
 **Permissions:** \`connect({ permissions: [...] })\` assigns profiles (e.g. \`default\`) that can allow or deny which effects a user may call.
 
+### Effect metamodels
+
+Effects can declare runtime behaviors under \`withEffect.metamodels\`:
+
+\`\`\`json
+{
+  "withEffect": {
+    "name": "publish_ticket",
+    "attachedClass": "ticket",
+    "inputSchema": {
+      "type": "object",
+      "properties": { "audience": { "type": "string" } }
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": { "ok": { "type": "boolean" } }
+    },
+    "metamodels": {
+      "postCondition": {
+        "condition": "result.ok == true",
+        "description": "Publishing must report success"
+      },
+      "dryRun": {
+        "enabled": true,
+        "description": "Preview publishing before sending"
+      },
+      "reverse": {
+        "handler": "unpublish_ticket",
+        "description": "Undo a publication"
+      },
+      "approvalRequired": {
+        "required": true,
+        "reason": "Publishing is user-visible",
+        "mode": "confirm"
+      }
+    }
+  }
+}
+\`\`\`
+
+Supported effect metamodel keys:
+
+${effectMetamodelTable}
+
 ---
 
 ## IDs and labels

package/dist/index.d.mts

@@ -304,6 +304,38 @@ interface EffectHandlerContext {
         identityId?: string;
         principalId?: string;
     };
+    behaviors?: ResolvedEffectBehaviors;
+    invocation?: EffectInvocationMetadata;
+}
+interface ResolvedEffectPostCondition {
+    condition: string;
+    description?: string;
+}
+interface ResolvedEffectDryRun {
+    enabled: boolean;
+    description?: string;
+}
+interface ResolvedEffectReverse {
+    handler?: string;
+    description?: string;
+}
+interface ResolvedEffectApprovalRequired {
+    required: boolean;
+    reason?: string;
+    mode?: string;
+}
+interface ResolvedEffectBehaviors {
+    postCondition?: ResolvedEffectPostCondition;
+    dryRun?: ResolvedEffectDryRun;
+    reverse?: ResolvedEffectReverse;
+    approvalRequired?: ResolvedEffectApprovalRequired;
+}
+type EffectInvocationMode = 'execute' | 'dryRun' | 'reverse';
+interface EffectInvocationMetadata {
+    mode?: EffectInvocationMode;
+    reverseHandler?: string;
+    sourceEffectKey?: string;
+    sourceEffectName?: string;
 }
 type ToolHandler = (input: any, context: EffectHandlerContext) => Promise<unknown>;
 /**
@@ -373,6 +405,8 @@ interface ToolSchema {
      * passed as the first argument to the handler).
      */
     static?: boolean;
+    /** Declarative runtime behaviors attached to the effect. */
+    metamodels?: ManifestEffectMetamodelSpec;
 }
 type EffectSchema = ToolSchema;
 /**
@@ -387,6 +421,8 @@ type EffectSchema = ToolSchema;
  */
 interface ToolWithHandler extends ToolSchema {
     handler: ToolHandler | InstanceToolHandler;
+    dryRunHandler?: ToolHandler | InstanceToolHandler;
+    reverseHandler?: ToolHandler | InstanceToolHandler;
 }
 type EffectWithHandler = ToolWithHandler;
 /**
@@ -411,6 +447,7 @@ interface DomainState {
         description?: string;
         inputSchema?: Record<string, unknown>;
         outputSchema?: Record<string, unknown>;
+        metamodels?: ManifestEffectMetamodelSpec;
     }>;
     [key: string]: unknown;
 }
@@ -437,6 +474,8 @@ interface ToolInfo {
     className?: string;
     /** Whether this is a static method */
     static?: boolean;
+    /** Declarative runtime behaviors attached to the effect. */
+    metamodels?: ManifestEffectMetamodelSpec;
 }
 interface EffectInfo extends ToolInfo {
 }
@@ -457,7 +496,7 @@ interface EffectsChangedEvent extends ToolsChangedEvent {
 }
 type EffectHandler = ToolHandler;
 type InstanceEffectHandler = InstanceToolHandler;
-type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
+type JobStatus = 'queued' | 'running' | 'awaitingTool' | 'awaitingHuman' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
 type JobFeedbackSentiment = 'good' | 'bad';
 interface JobFeedbackToolCall {
     callId?: string;
@@ -529,8 +568,15 @@ interface Prompt {
     type: 'confirm' | 'choice' | 'input';
     title: string;
     message: string;
-    options?: string[];
+    options?: Array<string | {
+        value: string;
+        label: string;
+        description?: string;
+    }>;
     defaultValue?: unknown;
+    placeholder?: string;
+    allowEmpty?: boolean;
+    metadata?: Record<string, unknown>;
 }
 type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
 interface SessionHeapFieldValue {
@@ -788,6 +834,65 @@ interface ManifestPropertySpec {
     type?: string;
     description?: string;
     required?: boolean;
+    note?: string | string[];
+    enum?: string[] | ManifestEnumRuleSpec;
+    filterBy?: boolean | string[] | ManifestFilterBySpec;
+    validate?: ManifestValidationRuleSpec[];
+}
+type ManifestValidationOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'true' | 'false' | 'regex' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with';
+interface ManifestEnumRuleSpec {
+    values: string[];
+    message?: string;
+}
+interface ManifestFilterBySpec {
+    operators: string[];
+    scalarType?: string;
+}
+interface ManifestValidationRuleSpec {
+    operator: ManifestValidationOperator;
+    stringValue?: string;
+    numberValue?: number;
+    booleanValue?: boolean;
+    message?: string;
+}
+interface ManifestStateMachineStateSpec {
+    name: string;
+    isFinal?: boolean;
+}
+interface ManifestStateMachineTransitionSpec {
+    name: string;
+    from: string;
+    to: string;
+}
+interface ManifestStateMachineSpec {
+    name: string;
+    entryState: string;
+    states: Array<string | ManifestStateMachineStateSpec>;
+    transitions: ManifestStateMachineTransitionSpec[];
+    finalStates?: string[];
+}
+interface ManifestPostConditionSpec {
+    condition: string;
+    description?: string;
+}
+interface ManifestDryRunSpec {
+    enabled?: boolean;
+    description?: string;
+}
+interface ManifestReverseSpec {
+    handler?: string;
+    description?: string;
+}
+interface ManifestApprovalRequiredSpec {
+    required?: boolean;
+    reason?: string;
+    mode?: string;
+}
+interface ManifestEffectMetamodelSpec {
+    postCondition?: string | ManifestPostConditionSpec;
+    dryRun?: boolean | ManifestDryRunSpec;
+    reverse?: string | ManifestReverseSpec;
+    approvalRequired?: boolean | ManifestApprovalRequiredSpec;
 }
 /**
  * Relationship definition between two classes
@@ -825,6 +930,7 @@ interface ManifestEffectDeclaration {
     outputSchema?: ManifestEffectSchema;
     stability?: 'stable' | 'experimental' | 'deprecated';
     tags?: string[];
+    metamodels?: ManifestEffectMetamodelSpec;
 }
 /**
  * A single operation in a manifest volume
@@ -840,6 +946,10 @@ interface ManifestOperation {
     instanceOf?: string;
     /** Define submodels/fields */
     has?: Record<string, ManifestPropertySpec>;
+    /** Advisory notes attached to the model/class itself */
+    note?: string | string[];
+    /** State machines attached to the created or targeted class */
+    stateMachines?: ManifestStateMachineSpec[];
     /** Define a relationship between two classes */
     defineRelationship?: ManifestRelationshipDef;
     /** Declare a build-owned effect */
@@ -1377,6 +1487,13 @@ declare class Environment extends Session {
      * Strips the alias prefix, returning the bare model path.
      */
     private _resolveAlias;
+    private _runGraphql;
+    private _applyFieldMetamodels;
+    private _applyModelMetamodels;
+    private _ensureWorkspaceToolsRoot;
+    private _storeEffectSchemas;
+    private _applyEffectMetamodels;
+    private _applyEffectDeclaration;
     /**
      * Apply a single manifest operation via GraphQL
      */
@@ -1547,6 +1664,7 @@ declare class Granular {
     private serializeEffect;
     private publishSandboxEffectCatalog;
     private syncSandboxEffectCatalog;
+    private recoverEffectHost;
     private startEffectHostHeartbeat;
     private stopEffectHostHeartbeat;
     private synchronizeEffectHost;
@@ -1649,4 +1767,13 @@ declare class Granular {
     private request;
 }
 
-export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };
+type EffectRuntimeRequest = {
+    effectKey: string;
+    effectName: string;
+    input: unknown;
+    context?: EffectHandlerContext;
+};
+declare function normalizeEffectBehaviors(value?: ManifestEffectMetamodelSpec | ResolvedEffectBehaviors | null): ResolvedEffectBehaviors;
+declare function invokeRegisteredEffect(effectMap: Map<string, ToolWithHandler>, request: EffectRuntimeRequest): Promise<unknown>;
+
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };

package/dist/index.d.ts

@@ -304,6 +304,38 @@ interface EffectHandlerContext {
         identityId?: string;
         principalId?: string;
     };
+    behaviors?: ResolvedEffectBehaviors;
+    invocation?: EffectInvocationMetadata;
+}
+interface ResolvedEffectPostCondition {
+    condition: string;
+    description?: string;
+}
+interface ResolvedEffectDryRun {
+    enabled: boolean;
+    description?: string;
+}
+interface ResolvedEffectReverse {
+    handler?: string;
+    description?: string;
+}
+interface ResolvedEffectApprovalRequired {
+    required: boolean;
+    reason?: string;
+    mode?: string;
+}
+interface ResolvedEffectBehaviors {
+    postCondition?: ResolvedEffectPostCondition;
+    dryRun?: ResolvedEffectDryRun;
+    reverse?: ResolvedEffectReverse;
+    approvalRequired?: ResolvedEffectApprovalRequired;
+}
+type EffectInvocationMode = 'execute' | 'dryRun' | 'reverse';
+interface EffectInvocationMetadata {
+    mode?: EffectInvocationMode;
+    reverseHandler?: string;
+    sourceEffectKey?: string;
+    sourceEffectName?: string;
 }
 type ToolHandler = (input: any, context: EffectHandlerContext) => Promise<unknown>;
 /**
@@ -373,6 +405,8 @@ interface ToolSchema {
      * passed as the first argument to the handler).
      */
     static?: boolean;
+    /** Declarative runtime behaviors attached to the effect. */
+    metamodels?: ManifestEffectMetamodelSpec;
 }
 type EffectSchema = ToolSchema;
 /**
@@ -387,6 +421,8 @@ type EffectSchema = ToolSchema;
  */
 interface ToolWithHandler extends ToolSchema {
     handler: ToolHandler | InstanceToolHandler;
+    dryRunHandler?: ToolHandler | InstanceToolHandler;
+    reverseHandler?: ToolHandler | InstanceToolHandler;
 }
 type EffectWithHandler = ToolWithHandler;
 /**
@@ -411,6 +447,7 @@ interface DomainState {
         description?: string;
         inputSchema?: Record<string, unknown>;
         outputSchema?: Record<string, unknown>;
+        metamodels?: ManifestEffectMetamodelSpec;
     }>;
     [key: string]: unknown;
 }
@@ -437,6 +474,8 @@ interface ToolInfo {
     className?: string;
     /** Whether this is a static method */
     static?: boolean;
+    /** Declarative runtime behaviors attached to the effect. */
+    metamodels?: ManifestEffectMetamodelSpec;
 }
 interface EffectInfo extends ToolInfo {
 }
@@ -457,7 +496,7 @@ interface EffectsChangedEvent extends ToolsChangedEvent {
 }
 type EffectHandler = ToolHandler;
 type InstanceEffectHandler = InstanceToolHandler;
-type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
+type JobStatus = 'queued' | 'running' | 'awaitingTool' | 'awaitingHuman' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
 type JobFeedbackSentiment = 'good' | 'bad';
 interface JobFeedbackToolCall {
     callId?: string;
@@ -529,8 +568,15 @@ interface Prompt {
     type: 'confirm' | 'choice' | 'input';
     title: string;
     message: string;
-    options?: string[];
+    options?: Array<string | {
+        value: string;
+        label: string;
+        description?: string;
+    }>;
     defaultValue?: unknown;
+    placeholder?: string;
+    allowEmpty?: boolean;
+    metadata?: Record<string, unknown>;
 }
 type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
 interface SessionHeapFieldValue {
@@ -788,6 +834,65 @@ interface ManifestPropertySpec {
     type?: string;
     description?: string;
     required?: boolean;
+    note?: string | string[];
+    enum?: string[] | ManifestEnumRuleSpec;
+    filterBy?: boolean | string[] | ManifestFilterBySpec;
+    validate?: ManifestValidationRuleSpec[];
+}
+type ManifestValidationOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'true' | 'false' | 'regex' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with';
+interface ManifestEnumRuleSpec {
+    values: string[];
+    message?: string;
+}
+interface ManifestFilterBySpec {
+    operators: string[];
+    scalarType?: string;
+}
+interface ManifestValidationRuleSpec {
+    operator: ManifestValidationOperator;
+    stringValue?: string;
+    numberValue?: number;
+    booleanValue?: boolean;
+    message?: string;
+}
+interface ManifestStateMachineStateSpec {
+    name: string;
+    isFinal?: boolean;
+}
+interface ManifestStateMachineTransitionSpec {
+    name: string;
+    from: string;
+    to: string;
+}
+interface ManifestStateMachineSpec {
+    name: string;
+    entryState: string;
+    states: Array<string | ManifestStateMachineStateSpec>;
+    transitions: ManifestStateMachineTransitionSpec[];
+    finalStates?: string[];
+}
+interface ManifestPostConditionSpec {
+    condition: string;
+    description?: string;
+}
+interface ManifestDryRunSpec {
+    enabled?: boolean;
+    description?: string;
+}
+interface ManifestReverseSpec {
+    handler?: string;
+    description?: string;
+}
+interface ManifestApprovalRequiredSpec {
+    required?: boolean;
+    reason?: string;
+    mode?: string;
+}
+interface ManifestEffectMetamodelSpec {
+    postCondition?: string | ManifestPostConditionSpec;
+    dryRun?: boolean | ManifestDryRunSpec;
+    reverse?: string | ManifestReverseSpec;
+    approvalRequired?: boolean | ManifestApprovalRequiredSpec;
 }
 /**
  * Relationship definition between two classes
@@ -825,6 +930,7 @@ interface ManifestEffectDeclaration {
     outputSchema?: ManifestEffectSchema;
     stability?: 'stable' | 'experimental' | 'deprecated';
     tags?: string[];
+    metamodels?: ManifestEffectMetamodelSpec;
 }
 /**
  * A single operation in a manifest volume
@@ -840,6 +946,10 @@ interface ManifestOperation {
     instanceOf?: string;
     /** Define submodels/fields */
     has?: Record<string, ManifestPropertySpec>;
+    /** Advisory notes attached to the model/class itself */
+    note?: string | string[];
+    /** State machines attached to the created or targeted class */
+    stateMachines?: ManifestStateMachineSpec[];
     /** Define a relationship between two classes */
     defineRelationship?: ManifestRelationshipDef;
     /** Declare a build-owned effect */
@@ -1377,6 +1487,13 @@ declare class Environment extends Session {
      * Strips the alias prefix, returning the bare model path.
      */
     private _resolveAlias;
+    private _runGraphql;
+    private _applyFieldMetamodels;
+    private _applyModelMetamodels;
+    private _ensureWorkspaceToolsRoot;
+    private _storeEffectSchemas;
+    private _applyEffectMetamodels;
+    private _applyEffectDeclaration;
     /**
      * Apply a single manifest operation via GraphQL
      */
@@ -1547,6 +1664,7 @@ declare class Granular {
     private serializeEffect;
     private publishSandboxEffectCatalog;
     private syncSandboxEffectCatalog;
+    private recoverEffectHost;
     private startEffectHostHeartbeat;
     private stopEffectHostHeartbeat;
     private synchronizeEffectHost;
@@ -1649,4 +1767,13 @@ declare class Granular {
     private request;
 }
 
-export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };
+type EffectRuntimeRequest = {
+    effectKey: string;
+    effectName: string;
+    input: unknown;
+    context?: EffectHandlerContext;
+};
+declare function normalizeEffectBehaviors(value?: ManifestEffectMetamodelSpec | ResolvedEffectBehaviors | null): ResolvedEffectBehaviors;
+declare function invokeRegisteredEffect(effectMap: Map<string, ToolWithHandler>, request: EffectRuntimeRequest): Promise<unknown>;
+
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };