feat(operator): harden controllers, enable webhooks, enforce timeouts…

.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
   "name": "Kubebuilder DevContainer",
-  "image": "docker.io/golang:1.24-bookworm",
+  "image": "docker.io/golang:1.25-bookworm",
   "features": {
     "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
     "ghcr.io/devcontainers/features/git:1": {}

.github/workflows/docker.yml

@@ -24,7 +24,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -63,7 +63,7 @@ jobs:
     needs: build
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Build image for scanning
         uses: docker/build-push-action@v6
@@ -81,7 +81,7 @@ jobs:
           severity: 'CRITICAL,HIGH'
 
       - name: Upload Trivy results
-        uses: github/codeql-action/upload-sarif@v3
+        uses: github/codeql-action/upload-sarif@v4
         if: always()
         with:
           sarif_file: 'trivy-results.sarif'

.github/workflows/lint.yml

@@ -4,16 +4,19 @@ on:
   push:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   lint:
     name: Run on Ubuntu
     runs-on: ubuntu-latest
     steps:
       - name: Clone the code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
 

.github/workflows/release-please.yml

@@ -34,7 +34,7 @@ jobs:
       # Build and push Docker images when release is created
       - name: Checkout code
         if: ${{ steps.release.outputs.release_created }}
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Docker Buildx
         if: ${{ steps.release.outputs.release_created }}

.github/workflows/test-e2e.yml

@@ -4,16 +4,19 @@ on:
   push:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   test-e2e:
     name: Run on Ubuntu
     runs-on: ubuntu-latest
     steps:
       - name: Clone the code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
 

.github/workflows/test.yml

@@ -4,16 +4,19 @@ on:
   push:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Run on Ubuntu
     runs-on: ubuntu-latest
     steps:
       - name: Clone the code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
 

CODE_OF_CONDUCT.md

@@ -46,15 +46,18 @@ We agree to restrict the following behaviors in our community. Instances, threat
 
 Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
 
-When an incident does occur, it is important to report it promptly. To report a possible violation, **[NOTE: describe your means of reporting here.]**
+When an incident does occur, it is important to report it promptly. To report a possible violation, please contact the Community Moderators via one of the following channels:
+
+- Email: [email protected]
+- GitHub Discussions: https://github.com/bubustack/bobrapet/discussions (select the Community Moderation category)
+
+If you are uncomfortable reporting publicly, email is preferred. We aim to acknowledge reports within 72 hours and will keep reporters updated as appropriate.
 
 Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
 
 
 ## Addressing and Repairing Harm
 
-**[NOTE: The remedies and repairs outlined below are suggestions based on best practices in code of conduct enforcement. If your community has its own established enforcement process, be sure to edit this section to describe your own policies.]**
-
 If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
 
 1) Warning

Dockerfile

@@ -1,5 +1,5 @@
 # Build the manager binary
-FROM golang:1.24-bookworm AS builder
+FROM golang:1.25-bookworm AS builder
 ARG TARGETOS
 ARG TARGETARCH
 

README.md

@@ -2,9 +2,12 @@
 [![Go Reference](https://pkg.go.dev/badge/github.com/bubustack/bobrapet.svg)](https://pkg.go.dev/github.com/bubustack/bobrapet)
 [![Go Report Card](https://goreportcard.com/badge/github.com/bubustack/bobrapet)](https://goreportcard.com/report/github.com/bubustack/bobrapet)
 
-Bobrapet is a powerful, cloud-native workflow engine for orchestrating complex AI and data processing pipelines on Kubernetes. It leverages the declarative power of Custom Resource Definitions (CRDs) to let you define, manage, and execute multi-step, event-driven workflows with unparalleled flexibility and control.
+Bobrapet is a powerful, cloud-native workflow engine for orchestrating complex AI and data processing pipelines on Kubernetes. It leverages the declarative power of Custom Resource Definitions (CRDs) to let you define, manage, and execute multi-step, event-driven workflows with flexibility and control.
 
-For full product docs, visit: https://bubustack.io/docs/
+Quick links:
+- Operator docs: https://bubustack.io/docs/bobrapet
+- Quickstart: https://bubustack.io/docs/bobrapet/guides/quickstart
+- CRD reference: https://bubustack.io/docs/bobrapet/reference/crds
 
 ## 🌟 Key Features
 
@@ -19,14 +22,8 @@ For full product docs, visit: https://bubustack.io/docs/
 
 ## 🏗️ Architecture
 
-The `bobrapet` operator is engineered for robustness and maintainability, following best practices for Kubernetes controller design. The core `StoryRun` controller, for example, is built on a modular, sub-reconciler pattern:
-
-- **Main Controller**: Acts as a lean, high-level orchestrator.
-- **RBAC Manager**: Manages all RBAC-related resources (`ServiceAccount`, `Role`, `RoleBinding`).
-- **DAG Reconciler**: Contains the entire workflow state machine, handling state synchronization, dependency analysis, and scheduling.
-- **Step Executor**: Manages the specific logic for launching different types of steps (`engram`, `executeStory`, etc.).
-
-This clean separation of concerns makes the operator highly scalable, testable, and easy to extend.
+High-level architecture, patterns, and controller internals are documented on the website:
+- Overview and architecture: https://bubustack.io/docs/bobrapet/explanations/architecture
 
 ## 📚 Core Concepts
 
@@ -39,32 +36,8 @@ This clean separation of concerns makes the operator highly scalable, testable,
 
 ## 🧰 Workflow Primitives
 
-Beyond running custom `Engrams`, `Story` resources can use a rich set of built-in primitives for advanced control flow:
-
-- **`loop`**: Iterate over a list and expand a template step per item.
-  - `with.items`: CEL‑resolvable data (evaluated with `inputs`, `steps` contexts)
-  - `with.template`: a single `Step` to instantiate per item
-  - Limits: max 100 iterations; creates child `StepRun`s and records them under `status.primitiveChildren[step]`; marks the loop step Running ("Loop expanded").
-
-- **`parallel`**: Run multiple steps concurrently.
-  - `with.steps[]`: array of `Step` entries; each branch’s `with` is CEL‑resolved with `inputs` and `steps`
-  - Creates sibling `StepRun`s; marks the parallel step Running ("Parallel block expanded").
-
-- **`stop`**: Terminate the workflow early.
-  - `with.phase`: one of `Succeeded|Failed|Canceled` (defaults to `Succeeded`)
-  - `with.message`: optional human message
-  - Sets `StoryRun.status.phase/message` and returns.
-
-- **`executeStory`**: Run another `Story` as a sub‑workflow.
-  - `with.storyRef`: `{ name, namespace? }`
-  - Current status: placeholder; marks step Succeeded with a message.
-
-- **`condition`, `switch`, `setData`, `transform`, `filter`, `mergeData`**:
-  - Batch path: controller marks these primitives Succeeded with outputs available (no pod launch).
-  - Evidence: batch primitive completion (internal/controller/runs/step_executor.go:49-51)
-  - Streaming path: `transform` is evaluated in the Hub (CEL over payload/inputs) and forwarded downstream.
-
-- API declares additional types (`wait`, `throttle`, `batch`, `gate`) for future use.
+See the guides for primitives, batch vs. streaming, impulses, and storage configuration:
+- Guides: https://bubustack.io/docs/bobrapet/guides
 
 ## 🚀 Quick Start
 
@@ -129,13 +102,9 @@ kubectl get stepruns -l bubustack.io/storyrun=summarize-k8s-docs
 
 ## Environment variables (operator-injected; consumed by SDK)
 
-- Identity: `BUBU_STORY_NAME`, `BUBU_STORYRUN_ID`, `BUBU_STEP_NAME`, `BUBU_STEPRUN_NAME`, `BUBU_STEPRUN_NAMESPACE`, `BUBU_STARTED_AT`
-- Inputs/Config: `BUBU_INPUTS`, `BUBU_CONFIG`, `BUBU_EXECUTION_MODE`
-- Storage: `BUBU_MAX_INLINE_SIZE`, `BUBU_STORAGE_PROVIDER`, `BUBU_STORAGE_TIMEOUT`, `BUBU_STORAGE_S3_BUCKET`, `BUBU_STORAGE_S3_REGION`, `BUBU_STORAGE_S3_ENDPOINT`
-- gRPC (server/client): `BUBU_GRPC_PORT`, `BUBU_GRPC_MAX_RECV_BYTES`, `BUBU_GRPC_MAX_SEND_BYTES`, `BUBU_GRPC_CLIENT_MAX_RECV_BYTES`, `BUBU_GRPC_CLIENT_MAX_SEND_BYTES`, `BUBU_GRPC_MESSAGE_TIMEOUT`, `BUBU_GRPC_CHANNEL_SEND_TIMEOUT`, `BUBU_GRPC_RECONNECT_BASE_BACKOFF`, `BUBU_GRPC_RECONNECT_MAX_BACKOFF`, `BUBU_GRPC_RECONNECT_MAX_RETRIES`
-- TLS (optional): `BUBU_GRPC_TLS_CERT_FILE`, `BUBU_GRPC_TLS_KEY_FILE`, `BUBU_GRPC_CA_FILE`, `BUBU_GRPC_CLIENT_TLS`, `BUBU_GRPC_CLIENT_CERT_FILE`, `BUBU_GRPC_CLIENT_KEY_FILE`, `BUBU_GRPC_REQUIRE_TLS`
-
-See detailed tables in `bubustack.io/docs/reference`.
+For complete environment variable listings and defaults, see the operator configuration and transport reference:
+- Operator config: https://bubustack.io/docs/bobrapet/reference/config
+- gRPC transport: https://bubustack.io/docs/bobrapet/reference/grpc
 
 ## 🛠️ Local Development
 

SECURITY.md

@@ -2,7 +2,9 @@
 
 ## Supported versions
 
-We provide security updates for the latest released version of the operator. Please ensure you are using a supported version to receive security patches.
+We provide security updates for the latest released minor of the operator. Please ensure you are using a supported version to receive security patches. We generally support the latest minor and the immediately previous minor.
+
+Supported Kubernetes versions: we aim to support N-2 of upstream stable releases. For example, when Kubernetes 1.31 is current, we target 1.31, 1.30, 1.29. See `config/crd/kustomization.yaml` and CI matrices for exact compatibility.
 
 ## Reporting a vulnerability
 
@@ -18,7 +20,7 @@ When reporting a vulnerability, please provide the following information:
 
 - **A clear description** of the vulnerability and its potential impact.
 - **Steps to reproduce** the vulnerability, including any example code, scripts, or configurations.
-- **The version(s) of the SDK** affected.
+- **The version(s) of the operator** affected.
 - **Your contact information** for us to follow up with you.
 
 ## Disclosure process
@@ -27,7 +29,9 @@ When reporting a vulnerability, please provide the following information:
 2.  **Confirmation**: We will acknowledge your report within 48 hours.
 3.  **Investigation**: We will investigate the vulnerability and determine its scope and impact. We may contact you for additional information during this phase.
 4.  **Fix**: We will develop a patch for the vulnerability.
-5.  **Disclosure**: We will create a security advisory, issue a CVE, and release a new version with the patch. We will credit you for your discovery unless you prefer to remain anonymous.
+5.  **Disclosure**: We will create a security advisory, issue a CVE (if applicable), and release a new version with the patch. We will credit you for your discovery unless you prefer to remain anonymous.
+
+We aim to resolve high severity vulnerabilities within 30 days, medium within 60 days, and low within 90 days, subject to complexity and scope. We'll keep you informed of progress.
 
 We aim to resolve all vulnerabilities as quickly as possible. The timeline for a fix and disclosure will vary depending on the complexity and severity of the vulnerability. We will keep you informed of our progress throughout the process.
 

SUPPORT.md

@@ -15,10 +15,26 @@ For questions, discussions, and community support, please use the following chan
 - **GitHub Issues**: For bug reports and feature requests, please open an issue: https://github.com/bubustack/bobrapet/issues
 - **GitHub Discussions**: For general questions and sharing your projects, please use Discussions: https://github.com/bubustack/bobrapet/discussions
 
+### Triage and response SLAs (best effort)
+
+- We triage new GitHub issues Mon–Fri during business hours.
+- Initial response target: within 2 business days.
+- Security reports follow the timelines in SECURITY.md.
+
+### Supported versions
+
+- We generally support the latest minor release and the previous minor release of the operator.
+- Kubernetes compatibility target: N-2 upstream stable releases.
+
 ## Commercial support
 
 For commercial support, including enterprise features, dedicated support channels, and SLAs, contact [[email protected]](mailto:[email protected]).
 
 ## Reporting security vulnerabilities
 
 To report a security vulnerability, please follow the instructions in our [Security Policy](./SECURITY.md).
+
+### Related documentation
+
+- Troubleshooting: https://bubustack.io/docs/bobrapet/troubleshooting
+- Known issues: https://github.com/bubustack/bobrapet/issues?q=is%3Aissue+is%3Aopen+label%3Abug

cmd/main.go

@@ -194,7 +194,11 @@ func main() {
 	managerCtx := ctrl.SetupSignalHandler()
 	setup.SetupIndexers(managerCtx, mgr)
 
-	operatorConfigManager := config.NewOperatorConfigManager(mgr.GetClient(), "bobrapet-system", "bobrapet-operator-config")
+	operatorConfigManager := config.NewOperatorConfigManager(
+		mgr.GetClient(),
+		"bobrapet-system",
+		"bobrapet-operator-config",
+	)
 	setupLog.Info("Operator configuration manager initialized")
 	if err := mgr.Add(operatorConfigManager); err != nil {
 		setupLog.Error(err, "unable to add operator config manager to manager")

config/crd/bases/bubustack.io_engrams.yaml

@@ -358,6 +358,7 @@ spec:
                   Pending → Running → {Succeeded|Failed|Canceled|Compensated|Paused|Blocked|Scheduling|Timeout|Aborted}
 
                   Some resources may also support Paused for manual intervention scenarios.
+                  nolint:lll
                 enum:
                 - Pending
                 - Running

config/crd/bases/bubustack.io_impulses.yaml

@@ -464,6 +464,7 @@ spec:
                   Pending → Running → {Succeeded|Failed|Canceled|Compensated|Paused|Blocked|Scheduling|Timeout|Aborted}
 
                   Some resources may also support Paused for manual intervention scenarios.
+                  nolint:lll
                 enum:
                 - Pending
                 - Running