@stigmer/protos 0.0.69 → 0.0.70

package/ai/stigmer/agentic/workflowexecution/v1/spec_pb.d.ts

@@ -8,57 +8,27 @@ export declare const file_ai_stigmer_agentic_workflowexecution_v1_spec: GenFile;
 /**
  * WorkflowExecutionSpec defines the user-provided inputs for a workflow execution.
  *
+ * @internal
  * This is the "Execution" layer in the Template→Instance→Execution pattern.
  * WorkflowExecutionSpec is ephemeral - it defines the inputs for a single runtime invocation.
- *
- * Following Stigmer proto standards:
- * - Spec contains ONLY user inputs (what the user controls)
- * - Status contains execution state (what the system manages)
- *
  * The spec is immutable after creation. To retry with different inputs, create a new
  * WorkflowExecution with updated spec values.
  *
- * Spec vs Status Separation:
- * ✅ Spec: workflow_instance_id, workflow_id, trigger_message, trigger_metadata, runtime_env
- * ✅ Status: phase, tasks, output, error, timestamps
- *
  * Instance Resolution (matches AgentExecution pattern):
  * - Either workflow_instance_id OR workflow_id must be provided
  * - If workflow_instance_id: Use the specified instance directly
  * - If workflow_id: Resolve to workflow's default instance (auto-create if missing)
  * - Handler enforces: at least one must be provided
  *
- * Example Use Case 1 (Direct Instance Reference):
- * spec {
- *   workflow_instance_id: "wfi-customer-onboarding-prod"
- *   trigger_message: "New signup: john.doe@example.com"
- *   trigger_metadata: {
- *     "source": "web_signup_form"
- *     "ip_address": "203.0.113.42"
- *     "referrer": "https://marketing.example.com/campaign"
- *     "timestamp": "2025-01-11T14:30:22Z"
- *   }
- *   runtime_env: {
- *     "CUSTOMER_EMAIL": { value: "john.doe@example.com" }
- *     "CUSTOMER_PLAN": { value: "pro" }
- *     "STRIPE_API_KEY": { secret_ref: "sec-stripe-prod" }
- *   }
- * }
- *
- * Example Use Case 2 (Default Instance Resolution):
- * spec {
- *   workflow_id: "wf-customer-onboarding"  // System resolves to default instance
- *   trigger_message: "New signup: john.doe@example.com"
- *   runtime_env: {
- *     "CUSTOMER_EMAIL": { value: "john.doe@example.com" }
- *   }
- * }
- *
  * @generated from message ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionSpec
  */
 export type WorkflowExecutionSpec = Message<"ai.stigmer.agentic.workflowexecution.v1.WorkflowExecutionSpec"> & {
     /**
-     * ID of the WorkflowInstance to execute (optional).
+     * ID of the WorkflowInstance to execute.
+     *
+     * @internal
+     * Either workflow_instance_id OR workflow_id must be provided.
+     * Handler enforces this validation.
      *
      * The WorkflowInstance contains:
      * - Reference to the Workflow template (orchestration definition)
@@ -67,29 +37,16 @@ export type WorkflowExecutionSpec = Message<"ai.stigmer.agentic.workflowexecutio
      *
      * Format: "wfi-{slug}" (e.g., "wfi-customer-onboarding-prod")
      *
-     * Relationship:
-     * Workflow (template) → WorkflowInstance (config + secrets) → WorkflowExecution (runtime)
-     *
-     * Example:
-     * workflow_instance_id: "wfi-customer-onboarding-prod"
-     *
-     * The workflow_instance_id determines:
-     * - Which Workflow template to execute (the orchestration blueprint)
-     * - Which Environments provide configuration and secrets
-     * - What default values apply (if runtime_env doesn't override)
-     *
      * Authorization:
      * User must have "execute" permission on the referenced WorkflowInstance.
      *
-     * Note: Either workflow_instance_id OR workflow_id must be provided.
-     * Handler enforces this validation.
-     *
      * @generated from field: string workflow_instance_id = 1;
      */
     workflowInstanceId: string;
     /**
-     * ID of the Workflow template to execute (optional).
+     * ID of the Workflow template to execute (alternative to workflow_instance_id).
      *
+     * @internal
      * When workflow_id is provided without workflow_instance_id, the system:
      * 1. Checks if the Workflow has a default_instance_id in its status
      * 2. If exists: Uses the default instance
@@ -99,49 +56,25 @@ export type WorkflowExecutionSpec = Message<"ai.stigmer.agentic.workflowexecutio
      *
      * Format: "wf-{slug}" (e.g., "wf-customer-onboarding")
      *
-     * This provides a simpler UX for common cases where users want to
-     * "just execute a workflow" without manually managing instances.
-     *
-     * Use Cases:
-     * - Quick workflow execution without instance setup
-     * - Development and testing (use default instance)
-     * - Simple workflows that don't need custom configuration
-     *
-     * For advanced use cases requiring custom environment bindings or
-     * multiple instances with different configurations, use workflow_instance_id.
+     * Either workflow_instance_id OR workflow_id must be provided.
+     * Handler enforces this validation.
      *
      * Authorization:
      * User must have "execute" permission on the resolved WorkflowInstance.
      *
-     * Note: Either workflow_instance_id OR workflow_id must be provided.
-     * Handler enforces this validation.
-     *
      * @generated from field: string workflow_id = 6;
      */
     workflowId: string;
     /**
-     * Input message or payload for the workflow.
+     * Input message or payload that triggers the workflow.
      *
+     * @internal
      * This is the primary input to the workflow - the "trigger event" or "request payload".
-     * It can be:
-     * - A human-readable message (for conversational workflows)
-     * - A JSON payload (for API-triggered workflows)
-     * - An event description (for webhook/event-driven workflows)
+     * It can be a human-readable message, a JSON payload, or an event description.
      *
      * The workflow can access this value using: {{workflow.input.trigger_message}}
      * Tasks can reference it in their input configurations.
      *
-     * Examples:
-     *
-     * Conversational workflow:
-     * trigger_message: "Analyze sentiment of recent customer feedback"
-     *
-     * API workflow:
-     * trigger_message: '{"customer_id": "cus-abc123", "action": "upgrade_plan"}'
-     *
-     * Event-driven workflow:
-     * trigger_message: "Payment received: $99.00 for order #12345"
-     *
      * The trigger_message is optional - some workflows don't need input (scheduled jobs,
      * workflows that fetch data from APIs, etc.).
      *
@@ -149,9 +82,9 @@ export type WorkflowExecutionSpec = Message<"ai.stigmer.agentic.workflowexecutio
      */
     triggerMessage: string;
     /**
-     * Trigger context metadata.
+     * Contextual metadata about what triggered this execution.
      *
-     * Contains contextual information about who/what triggered this execution and how.
+     * @internal
      * This metadata is NOT used by the workflow logic itself - it's for audit, debugging,
      * and analytics.
      *
@@ -159,44 +92,19 @@ export type WorkflowExecutionSpec = Message<"ai.stigmer.agentic.workflowexecutio
      * - "source": How was this triggered? (api, webhook, schedule, manual, ui)
      * - "caller_id": Who triggered it? (usr-abc123, sys-scheduler, webhook-stripe)
      * - "ip_address": Client IP address (for API/UI triggers)
-     * - "user_agent": Client user agent (for API/UI triggers)
-     * - "referrer": HTTP referrer (for UI triggers)
      * - "webhook_id": Webhook ID (for webhook triggers)
      * - "schedule_id": Schedule ID (for scheduled triggers)
      * - "timestamp": When was it triggered? (ISO 8601)
      *
-     * Example (API trigger):
-     * trigger_metadata: {
-     *   "source": "api"
-     *   "caller_id": "usr-john-doe"
-     *   "ip_address": "203.0.113.42"
-     *   "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
-     *   "timestamp": "2025-01-11T14:30:22Z"
-     * }
-     *
-     * Example (webhook trigger):
-     * trigger_metadata: {
-     *   "source": "webhook"
-     *   "webhook_id": "whk-stripe-payment-received"
-     *   "webhook_source": "stripe.com"
-     *   "event_type": "payment_intent.succeeded"
-     *   "timestamp": "2025-01-11T14:30:22Z"
-     * }
-     *
-     * Use Cases:
-     * - Audit trail: Who triggered this execution and when?
-     * - Analytics: Which trigger sources are most common?
-     * - Debugging: Was this triggered by a webhook or manually?
-     * - Rate limiting: Limit executions per user/source
-     *
      * @generated from field: map<string, string> trigger_metadata = 4;
      */
     triggerMetadata: {
         [key: string]: string;
     };
     /**
-     * Runtime environment variables and secrets (execution-scoped).
+     * Execution-scoped environment variables and secrets that override instance defaults.
      *
+     * @internal
      * These values are only available for this specific execution and override values
      * from Environments and Workflow defaults.
      *
@@ -205,26 +113,6 @@ export type WorkflowExecutionSpec = Message<"ai.stigmer.agentic.workflowexecutio
      * 2. Environment values (from WorkflowInstance.environment_ids)
      * 3. Workflow defaults (from Workflow.default_env)
      *
-     * Use Cases:
-     *
-     * 1. B2B SaaS Integrations (e.g., Plant & Cloud):
-     * runtime_env: {
-     *   "CUSTOMER_API_KEY": { secret_ref: "sec-customer-abc-api-key" }
-     *   "CUSTOMER_WORKSPACE_ID": { value: "ws-customer-abc" }
-     * }
-     *
-     * 2. Dynamic Configuration:
-     * runtime_env: {
-     *   "DEPLOYMENT_REGION": { value: "us-west-2" }
-     *   "ENABLE_BETA_FEATURES": { value: "true" }
-     * }
-     *
-     * 3. Temporary Overrides (testing, debugging):
-     * runtime_env: {
-     *   "LOG_LEVEL": { value: "debug" }
-     *   "DRY_RUN": { value: "true" }
-     * }
-     *
      * Value Types:
      * - value: Plain text value (not encrypted, use for non-sensitive config)
      * - secret_ref: Reference to a Secret resource (encrypted, use for API keys, passwords)
@@ -234,22 +122,6 @@ export type WorkflowExecutionSpec = Message<"ai.stigmer.agentic.workflowexecutio
      * - ExecutionContext is deleted when execution completes (ephemeral secrets)
      * - Secret references are resolved at runtime (never exposed in logs)
      *
-     * Example:
-     * runtime_env: {
-     *   "CUSTOMER_EMAIL": {
-     *     value: "john.doe@example.com"
-     *   }
-     *   "STRIPE_API_KEY": {
-     *     secret_ref: "sec-stripe-prod"
-     *   }
-     *   "WEBHOOK_URL": {
-     *     secret_ref: "sec-webhook-callback-url"
-     *   }
-     *   "ENABLE_NOTIFICATIONS": {
-     *     value: "true"
-     *   }
-     * }
-     *
      * Tasks can access these values using: {{env.VARIABLE_NAME}}
      *
      * @generated from field: map<string, ai.stigmer.agentic.executioncontext.v1.ExecutionValue> runtime_env = 5;
@@ -258,13 +130,13 @@ export type WorkflowExecutionSpec = Message<"ai.stigmer.agentic.workflowexecutio
         [key: string]: ExecutionValue;
     };
     /**
-     * Temporal task token for async activity completion (optional).
+     * Opaque callback token for asynchronous completion by a parent orchestrator.
      *
-     * **Purpose**: Enables async activity completion pattern where the caller
-     * (typically a parent workflow or orchestrator) waits for actual workflow completion
-     * without blocking worker threads.
+     * @internal
+     * Enables async completion pattern where the caller (typically a parent workflow)
+     * waits for actual workflow completion without blocking worker threads.
      *
-     * **Flow**:
+     * Flow:
      * 1. Caller (Temporal activity) extracts its task token
      * 2. Passes token in this field when creating WorkflowExecution
      * 3. Returns activity.ErrResultPending (activity paused, thread released)
@@ -272,54 +144,19 @@ export type WorkflowExecutionSpec = Message<"ai.stigmer.agentic.workflowexecutio
      * 5. Workflow calls ActivityCompletionClient.complete(token, result)
      * 6. Temporal resumes the paused activity with the result
      *
-     * **Benefits**:
-     * - Correctness: Caller waits for actual completion, not just ACK
-     * - Scalability: Worker threads not blocked during long-running execution
-     * - Resilience: Token is durable in Temporal; survives restarts
-     * - Decoupling: Caller doesn't poll or manage workflow lifecycle
-     *
-     * **When Empty**:
-     * - Empty/null = fire-and-forget or direct API call (backward compatible)
-     * - Workflow execution proceeds normally, no callback performed
-     * - Use case: CLI commands, API requests, non-workflow triggers
-     *
-     * **When Provided**:
-     * - Workflow MUST complete the external activity using this token
-     * - Both success and failure paths must call completion
-     * - Token uniquely identifies the external activity execution
-     *
-     * **Token Format**:
-     * - Opaque binary blob from Temporal SDK (typically 100-200 bytes)
-     * - Contains: namespace, workflow ID, run ID, activity ID, attempt
-     * - DO NOT parse or modify - treat as opaque handle
-     *
-     * **Security**:
-     * - Token grants ability to complete the activity (bearer token)
-     * - Should only be passed through trusted internal services
-     * - Logged as Base64-encoded string (truncated for security)
-     *
-     * **Timeout**:
-     * - Caller should set StartToCloseTimeout (e.g., 24 hours)
-     * - If token callback never arrives, activity times out
-     * - Prevents infinite hangs if workflow crashes
+     * When empty: fire-and-forget or direct API call (backward compatible).
+     * When provided: workflow MUST complete the external activity using this token.
      *
-     * **Observability**:
-     * - Token is logged at creation time (Base64, first 20 chars)
-     * - Activity appears as "Running" in Temporal UI until completed
-     * - Both caller workflow and this workflow visible in Temporal
+     * Token format: opaque binary blob from Temporal SDK (typically 100-200 bytes).
+     * DO NOT parse or modify - treat as opaque handle.
      *
-     * **Consistency with AgentExecution**:
-     * - Same pattern as AgentExecution.spec.callback_token
-     * - Enables workflow-calling-workflow scenarios
-     * - Future: WorkflowExecution calling WorkflowExecution
+     * Same pattern as AgentExecution.spec.callback_token.
      *
-     * **References**:
+     * References:
      * - ADR: docs/adr/20260122-async-agent-execution-temporal-token-handshake.md
      * - Temporal Docs: https://docs.temporal.io/activities#asynchronous-activity-completion
-     * - Go SDK: https://pkg.go.dev/go.temporal.io/sdk/activity#ErrResultPending
-     * - Java SDK: https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/ActivityCompletionClient.html
      *
-     * @since 2026-01-22 (Phase 3: Workflow Async Completion)
+     * @since 2026-01-22
      *
      * @generated from field: bytes callback_token = 7;
      */

package/ai/stigmer/agentic/workflowexecution/v1/spec_pb.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/workflowexecution/v1/spec_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,2IAA2I;AAC3I,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,gDAAgD,EAAE,MAAM,mCAAmC,CAAC;AAGrG;;GAEG;AACH,MAAM,CAAC,MAAM,iDAAiD,GAAY,aAAa,CACrF,QAAQ,CAAC,qyBAAqyB,EAAE,CAAC,gDAAgD,CAAC,CAAC,CAAC;AAoUt2B;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAsC,aAAa,CACzF,WAAW,CAAC,iDAAiD,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"spec_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/workflowexecution/v1/spec_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,2IAA2I;AAC3I,oBAAoB;AAGpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,gDAAgD,EAAE,MAAM,mCAAmC,CAAC;AAGrG;;GAEG;AACH,MAAM,CAAC,MAAM,iDAAiD,GAAY,aAAa,CACrF,QAAQ,CAAC,qyBAAqyB,EAAE,CAAC,gDAAgD,CAAC,CAAC,CAAC;AAiKt2B;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAsC,aAAa,CACzF,WAAW,CAAC,iDAAiD,EAAE,CAAC,CAAC,CAAC"}

package/ai/stigmer/agentic/workflowinstance/v1/api_pb.d.ts

@@ -10,7 +10,8 @@ export declare const file_ai_stigmer_agentic_workflowinstance_v1_api: GenFile;
 /**
  * WorkflowInstance represents a configured deployment of a Workflow template.
  *
- * WorkflowInstance is the "Instance" layer in the Template→Instance→Execution pattern.
+ * @internal
+ * This is the "Instance" layer in the Template→Instance→Execution pattern.
  * It binds a reusable Workflow template to specific environments containing credentials,
  * configuration, and secrets needed for execution.
  *
@@ -34,42 +35,34 @@ export declare const file_ai_stigmer_agentic_workflowinstance_v1_api: GenFile;
 export type WorkflowInstance = Message<"ai.stigmer.agentic.workflowinstance.v1.WorkflowInstance"> & {
     /**
      * API version for this resource type.
-     * Format: 'agentic.stigmer.ai/v1'
-     * Validated as const to ensure version consistency.
      *
      * @generated from field: string api_version = 1;
      */
     apiVersion: string;
     /**
      * Resource kind identifier.
-     * Must be exactly 'WorkflowInstance' to match the message name.
-     * Validated as const for type safety.
      *
      * @generated from field: string kind = 2;
      */
     kind: string;
     /**
-     * Standard resource metadata including name, id, slug, labels, tags, and annotations.
-     * WorkflowInstances belong to an organization. Visibility controls access:
-     * - PUBLIC: Shared templates accessible to all users
-     * - PRIVATE: Organization-internal instances
+     * Resource metadata including name, organization, visibility, and labels.
      *
      * @generated from field: ai.stigmer.commons.apiresource.ApiResourceMetadata metadata = 3;
      */
     metadata?: ApiResourceMetadata;
     /**
-     * User-provided configuration for this workflow instance.
-     * Defines which Workflow template to use and which Environments provide configuration/secrets.
-     * See WorkflowInstanceSpec for detailed field documentation.
+     * Configurable properties: workflow reference, description, and environment bindings.
      *
      * @generated from field: ai.stigmer.agentic.workflowinstance.v1.WorkflowInstanceSpec spec = 4;
      */
     spec?: WorkflowInstanceSpec;
     /**
-     * System-managed status and audit information.
-     * Contains creation/update timestamps, version number, and other audit metadata.
-     * This is a simple status (no custom execution state) since WorkflowInstance is configuration only.
-     * Execution state is tracked in WorkflowExecution resources.
+     * System-managed audit information.
+     *
+     * @internal
+     * This is a simple status (no custom execution state) since WorkflowInstance
+     * is configuration only. Execution state is tracked in WorkflowExecution resources.
      *
      * @generated from field: ai.stigmer.commons.apiresource.ApiResourceAuditStatus status = 5;
      */

package/ai/stigmer/agentic/workflowinstance/v1/api_pb.js.map

@@ -1 +1 @@
-{"version":3,"file":"api_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/workflowinstance/v1/api_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,wIAAwI;AACxI,oBAAoB;AAWpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,gDAAgD,EAAE,MAAM,WAAW,CAAC;AAE7E,OAAO,EAAE,4CAA4C,EAAE,MAAM,0CAA0C,CAAC;AAExG,OAAO,EAAE,0CAA0C,EAAE,MAAM,wCAAwC,CAAC;AACpG,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,+CAA+C,GAAY,aAAa,CACnF,QAAQ,CAAC,wkBAAwkB,EAAE,CAAC,gDAAgD,EAAE,4CAA4C,EAAE,0CAA0C,EAAE,0BAA0B,CAAC,CAAC,CAAC;AA2E/vB;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAiC,aAAa,CAC/E,WAAW,CAAC,+CAA+C,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"api_pb.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/workflowinstance/v1/api_pb.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,wIAAwI;AACxI,oBAAoB;AAWpB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,gDAAgD,EAAE,MAAM,WAAW,CAAC;AAE7E,OAAO,EAAE,4CAA4C,EAAE,MAAM,0CAA0C,CAAC;AAExG,OAAO,EAAE,0CAA0C,EAAE,MAAM,wCAAwC,CAAC;AACpG,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF;;GAEG;AACH,MAAM,CAAC,MAAM,+CAA+C,GAAY,aAAa,CACnF,QAAQ,CAAC,wkBAAwkB,EAAE,CAAC,gDAAgD,EAAE,4CAA4C,EAAE,0CAA0C,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAoE/vB;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAiC,aAAa,CAC/E,WAAW,CAAC,+CAA+C,EAAE,CAAC,CAAC,CAAC"}

package/ai/stigmer/agentic/workflowinstance/v1/command_connect.d.ts

@@ -1,6 +1,7 @@
 /**
- * WorkflowInstanceCommandController handles write operations (Create, Update, Delete) for WorkflowInstance resources.
+ * WorkflowInstanceCommandController handles write operations for workflow instances.
  *
+ * @internal
  * This service provides the CUD (Create, Update, Delete) operations following the
  * Command-Query Separation pattern. All RPCs that modify state go through this controller.
  *
@@ -18,6 +19,8 @@ export declare const WorkflowInstanceCommandController: {
     readonly methods: {
         /**
          * Create or update a workflow instance.
+         *
+         * @internal
          * The authorization and state-operation are determined depending on whether the workflow instance
          * is going to be created or updated which is determined as part of the request execution.
          *
@@ -30,10 +33,9 @@ export declare const WorkflowInstanceCommandController: {
             readonly kind: any;
         };
         /**
-         * Create a new workflow instance.
-         *
-         * Creates a configured deployment of a Workflow template with environment bindings.
+         * Create a workflow instance.
          *
+         * @internal
          * Input validation:
          * - metadata.org must be specified
          * - spec.workflow_id must be a valid Workflow resource ID
@@ -45,16 +47,6 @@ export declare const WorkflowInstanceCommandController: {
          * 2. User has permission to access all referenced Environment resources
          * 3. Owner scope is valid for the user's organization/identity
          *
-         * Returns:
-         * The created WorkflowInstance with:
-         * - Assigned resource ID (metadata.id)
-         * - Created timestamp (status.audit.created_at)
-         * - Initial version (status.audit.version = 1)
-         *
-         * Example:
-         * Input: WorkflowInstance with workflow_id="wfl-123", environment_refs=["env-prod"]
-         * Output: WorkflowInstance with id="wfi-abc456", created_at="2025-01-11T10:00:00Z"
-         *
          * @generated from rpc ai.stigmer.agentic.workflowinstance.v1.WorkflowInstanceCommandController.create
          */
         readonly create: {
@@ -66,30 +58,20 @@ export declare const WorkflowInstanceCommandController: {
         /**
          * Update an existing workflow instance.
          *
-         * Modifies the configuration of an existing WorkflowInstance.
-         * You can update:
-         * - spec.description (change descriptive text)
-         * - spec.environment_refs (add/remove/reorder environment bindings)
+         * @internal
+         * Mutable fields:
+         * - spec.description, spec.environment_refs
          * - metadata.labels, metadata.tags, metadata.annotations
          *
-         * You cannot update:
-         * - spec.workflow_id (must delete and recreate to change template)
-         * - metadata.id (immutable resource identifier)
-         * - metadata.org (immutable after creation)
+         * Immutable fields (must delete and recreate to change):
+         * - spec.workflow_id, metadata.id, metadata.org
          *
          * Authorization:
          * Requires "update" permission on the specific WorkflowInstance resource.
          * Field path "metadata.id" identifies which resource to authorize.
          *
-         * Versioning:
          * Each update increments status.audit.version and updates status.audit.updated_at.
          *
-         * Returns:
-         * The updated WorkflowInstance with:
-         * - Incremented version number
-         * - Updated timestamp
-         * - Modified spec fields
-         *
          * Error: PERMISSION_DENIED if user lacks update permission
          *
          * @generated from rpc ai.stigmer.agentic.workflowinstance.v1.WorkflowInstanceCommandController.update
@@ -103,10 +85,8 @@ export declare const WorkflowInstanceCommandController: {
         /**
          * Delete a workflow instance.
          *
+         * @internal
          * Permanently removes a WorkflowInstance resource.
-         *
-         * Important:
-         * - Deletion is permanent and cannot be undone
          * - Does NOT delete the referenced Workflow template (templates are reusable)
          * - Does NOT delete the referenced Environment resources (environments are reusable)
          * - DOES cascade delete any dependent WorkflowExecution resources (executions belong to instance)
@@ -115,14 +95,7 @@ export declare const WorkflowInstanceCommandController: {
          * Requires "delete" permission on the specific WorkflowInstance resource.
          * Field path "value" extracts the resource ID from WorkflowInstanceId wrapper.
          *
-         * Use Cases:
-         * - Remove deprecated instances
-         * - Clean up test/dev instances
-         * - Decommission old deployment configurations
-         *
-         * Returns:
-         * The deleted WorkflowInstance (final state before deletion).
-         * Useful for audit logs and confirming what was deleted.
+         * Returns the deleted WorkflowInstance (final state before deletion).
          *
          * Error: PERMISSION_DENIED if user lacks delete permission
          * Error: NOT_FOUND if instance ID doesn't exist

package/ai/stigmer/agentic/workflowinstance/v1/command_connect.js

@@ -4,8 +4,9 @@
 // @ts-nocheck
 import { MethodKind } from "@bufbuild/protobuf";
 /**
- * WorkflowInstanceCommandController handles write operations (Create, Update, Delete) for WorkflowInstance resources.
+ * WorkflowInstanceCommandController handles write operations for workflow instances.
  *
+ * @internal
  * This service provides the CUD (Create, Update, Delete) operations following the
  * Command-Query Separation pattern. All RPCs that modify state go through this controller.
  *
@@ -23,6 +24,8 @@ export const WorkflowInstanceCommandController = {
     methods: {
         /**
          * Create or update a workflow instance.
+         *
+         * @internal
          * The authorization and state-operation are determined depending on whether the workflow instance
          * is going to be created or updated which is determined as part of the request execution.
          *
@@ -35,10 +38,9 @@ export const WorkflowInstanceCommandController = {
             kind: MethodKind.Unary,
         },
         /**
-         * Create a new workflow instance.
-         *
-         * Creates a configured deployment of a Workflow template with environment bindings.
+         * Create a workflow instance.
          *
+         * @internal
          * Input validation:
          * - metadata.org must be specified
          * - spec.workflow_id must be a valid Workflow resource ID
@@ -50,16 +52,6 @@ export const WorkflowInstanceCommandController = {
          * 2. User has permission to access all referenced Environment resources
          * 3. Owner scope is valid for the user's organization/identity
          *
-         * Returns:
-         * The created WorkflowInstance with:
-         * - Assigned resource ID (metadata.id)
-         * - Created timestamp (status.audit.created_at)
-         * - Initial version (status.audit.version = 1)
-         *
-         * Example:
-         * Input: WorkflowInstance with workflow_id="wfl-123", environment_refs=["env-prod"]
-         * Output: WorkflowInstance with id="wfi-abc456", created_at="2025-01-11T10:00:00Z"
-         *
          * @generated from rpc ai.stigmer.agentic.workflowinstance.v1.WorkflowInstanceCommandController.create
          */
         create: {
@@ -71,30 +63,20 @@ export const WorkflowInstanceCommandController = {
         /**
          * Update an existing workflow instance.
          *
-         * Modifies the configuration of an existing WorkflowInstance.
-         * You can update:
-         * - spec.description (change descriptive text)
-         * - spec.environment_refs (add/remove/reorder environment bindings)
+         * @internal
+         * Mutable fields:
+         * - spec.description, spec.environment_refs
          * - metadata.labels, metadata.tags, metadata.annotations
          *
-         * You cannot update:
-         * - spec.workflow_id (must delete and recreate to change template)
-         * - metadata.id (immutable resource identifier)
-         * - metadata.org (immutable after creation)
+         * Immutable fields (must delete and recreate to change):
+         * - spec.workflow_id, metadata.id, metadata.org
          *
          * Authorization:
          * Requires "update" permission on the specific WorkflowInstance resource.
          * Field path "metadata.id" identifies which resource to authorize.
          *
-         * Versioning:
          * Each update increments status.audit.version and updates status.audit.updated_at.
          *
-         * Returns:
-         * The updated WorkflowInstance with:
-         * - Incremented version number
-         * - Updated timestamp
-         * - Modified spec fields
-         *
          * Error: PERMISSION_DENIED if user lacks update permission
          *
          * @generated from rpc ai.stigmer.agentic.workflowinstance.v1.WorkflowInstanceCommandController.update
@@ -108,10 +90,8 @@ export const WorkflowInstanceCommandController = {
         /**
          * Delete a workflow instance.
          *
+         * @internal
          * Permanently removes a WorkflowInstance resource.
-         *
-         * Important:
-         * - Deletion is permanent and cannot be undone
          * - Does NOT delete the referenced Workflow template (templates are reusable)
          * - Does NOT delete the referenced Environment resources (environments are reusable)
          * - DOES cascade delete any dependent WorkflowExecution resources (executions belong to instance)
@@ -120,14 +100,7 @@ export const WorkflowInstanceCommandController = {
          * Requires "delete" permission on the specific WorkflowInstance resource.
          * Field path "value" extracts the resource ID from WorkflowInstanceId wrapper.
          *
-         * Use Cases:
-         * - Remove deprecated instances
-         * - Clean up test/dev instances
-         * - Decommission old deployment configurations
-         *
-         * Returns:
-         * The deleted WorkflowInstance (final state before deletion).
-         * Useful for audit logs and confirming what was deleted.
+         * Returns the deleted WorkflowInstance (final state before deletion).
          *
          * Error: PERMISSION_DENIED if user lacks delete permission
          * Error: NOT_FOUND if instance ID doesn't exist

package/ai/stigmer/agentic/workflowinstance/v1/command_connect.js.map

@@ -1 +1 @@
-{"version":3,"file":"command_connect.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/workflowinstance/v1/command_connect.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,4IAA4I;AAC5I,oBAAoB;AACpB,cAAc;AAKd,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC/C,QAAQ,EAAE,0EAA0E;IACpF,OAAO,EAAE;QACP;;;;;;WAMG;QACH,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,CAAC,EAAE,gBAAgB;YACnB,CAAC,EAAE,gBAAgB;YACnB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;;;;;;;;WA2BG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,gBAAgB;YACnB,CAAC,EAAE,gBAAgB;YACnB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA8BG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,gBAAgB;YACnB,CAAC,EAAE,gBAAgB;YACnB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA4BG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,kBAAkB;YACrB,CAAC,EAAE,gBAAgB;YACnB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;KACF;CACO,CAAC"}
+{"version":3,"file":"command_connect.js","sourceRoot":"","sources":["../../../../../../ai/stigmer/agentic/workflowinstance/v1/command_connect.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,4IAA4I;AAC5I,oBAAoB;AACpB,cAAc;AAKd,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC/C,QAAQ,EAAE,0EAA0E;IACpF,OAAO,EAAE;QACP;;;;;;;;WAQG;QACH,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,CAAC,EAAE,gBAAgB;YACnB,CAAC,EAAE,gBAAgB;YACnB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;WAgBG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,gBAAgB;YACnB,CAAC,EAAE,gBAAgB;YACnB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;;WAoBG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,gBAAgB;YACnB,CAAC,EAAE,gBAAgB;YACnB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;QACD;;;;;;;;;;;;;;;;;;;WAmBG;QACH,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,CAAC,EAAE,kBAAkB;YACrB,CAAC,EAAE,gBAAgB;YACnB,IAAI,EAAE,UAAU,CAAC,KAAK;SACvB;KACF;CACO,CAAC"}