v1.29.0 — Security in Depth, Reducer Naming, Hostname/Subject Encoding

Released 2026-05-10. GitHub release.

v1.29.0 ships the first-class implementation of Microbus’s security-in-depth story: gencreds and genmanifest are now full-fledged CLI tools that derive each microservice’s interservice ACL and manifest directly from its source code. The release also formalizes a reducer-by-prefix naming convention for agentic workflow state, refines the NATS subject encoding for hostnames and paths, and adds an agent-rule-loading mechanism keyed off the local CLAUDE.md.

An upgrade-v1-29-0 skill ships under .claude/skills/upgrade/ to mechanize the migration.

Highlights

  • gencreds and genmanifest shipped. Two new CLI tools under cmd/ that scan a microservice’s source code and produce its .creds (NATS user JWT + interservice ACL) and manifest.yaml. This is the implementation backing the true-to-code interservice ACL claim — the allow-list is derived from the actual call sites, not from configuration.
  • Reducer-by-prefix naming. Workflow state fields whose names start with sum*, list*, or set* automatically select the corresponding reducer at fan-in. Anything else gets the default replace-on-write behavior. The convention is enforced at codegen time by genmanifest.
  • NATS subject encoding refactor. Hostnames and paths are now encoded into NATS subjects through a single canonical scheme, with explicit handling for “weird” hostname and path characters. See the updated NATS subject layout.
  • Local CLAUDE.md triggers secondary rules. Topic-specific rule files (workflows.txt, sequel.txt, etc.) are now loaded contextually based on what the local CLAUDE.md declares the microservice does. The agent loads only the rules it needs for the current microservice, keeping the context window tight.
  • Canonical ValidateHostname in httpx. Hostname validation centralized to one function used across the connector, the HTTP ingress, and metrics — replacing duplicate validators that had drifted apart.

New Features

gencreds (under cmd/gencreds/)

A new CLI that consumes a microservice’s source tree and produces a signed .creds file containing:

  • A NATS user JWT identifying the microservice.
  • An interservice ACL (PUB and SUB rules) derived from connector.Subscribe registrations and outbound call sites.
  • ACL consolidation that collapses overlapping grants into compact form.

Sub-modules: aclbuild, aclconsolidate, aclencode, scan, scan_calls, sign, and a bundle command that wraps a build artifact + its .creds. Operators run gencreds at deploy time; the broker enforces what gencreds produced.

See the dedicated Interservice ACL doc for the security model and Trust-root tier for how :666 grants get audited.

genmanifest (under cmd/genmanifest/)

A new CLI that extracts each microservice’s manifest.yaml from its source code — endpoints, configs, tickers, events, tasks, workflows, all reflected automatically. Replaces the prior hand-maintenance pattern with an extract-from-code workflow:

  • Parses *api/endpoints.go and intermediate.go for feature definitions.
  • Validates HTTP method strings, path argument syntax, and reducer-prefix conventions.
  • Emits a clean manifest.yaml ready for the codegen pipeline.

Workflow State Reducers — Prefix Naming

Workflow state fields whose names start with a recognized prefix automatically use the corresponding reducer when parallel branches fan in:

PrefixReducerBehavior
sum*numeric addSums values from each branch
list*appendConcatenates arrays from each branch
set*union/mergeDe-duplicated array union, or field-by-field object merge
anything elsereplaceLast-write-wins

The character right after the prefix must be uppercase; summary, listening, setup do not match. Tasks must produce only the delta their branch generates, not the full accumulated value, otherwise fan-in produces duplicates.

The Reducers reference page at agentic-workflows/reducers covers the full mechanics, the delta rule with worked examples, set* semantics (array vs object), and edge cases. The creditflow example was updated to demonstrate the convention; the LLM service’s ChatLoop workflow uses listMessages and sumTokens accordingly.

Local CLAUDE.md → Secondary Rule Triggers

A microservice’s local CLAUDE.md can now declare which topic-specific rule files the agent should load when working in that directory. The convention:

  • A workflow-using microservice’s CLAUDE.md triggers .claude/rules/workflows.txt.
  • A SQL-CRUD microservice’s CLAUDE.md triggers .claude/rules/sequel.txt.
  • The base microbus.md rules are always loaded.

This cuts agent context usage materially on projects with many microservices, since each session only loads the rule subset relevant to the current microservice.

NATS Subject Encoding Refactor

Hostnames and paths now encode into NATS subjects through a single scheme that handles edge cases (uppercase, hyphens, dots, path arguments) consistently. The cmd/schema/encode.go package gains explicit unit-test coverage for “weird” hostnames and paths to lock the encoding behavior.

For most users this is internal — the framework constructs and parses subjects on your behalf. If you have code that builds NATS subjects directly (e.g. for monitoring or ad-hoc subscriptions), refer to the updated NATS subject layout for the exact encoding rules.

Improvements

  • Canonical httpx.ValidateHostname. One function for hostname validation across the framework. The connector, HTTP ingress, and metrics microservice now share the same validator. Subtle inconsistencies between the prior duplicates are gone.
  • Skill catalog refresh. Removed the obsolete chart-topology skill. Updated housekeeping, init-project, take-tour, review-microservice, add-task, add-workflow, and the sequel skills to align with the new conventions. New init-project/env.yaml template.
  • Per-package CLAUDE.md updates. Refreshed design-rationale notes across connector, httpx, sub, application, cmd/gencreds, cmd/genmanifest, the LLM service, the OpenAPI portal, and example microservices.

Breaking Changes

The migration skill (upgrade-v1-29-0) handles each of these. Manual migration is not recommended.

  • Reducer-prefix enforcement. Workflow state fields that participate in fan-in must use the prefix convention or get the replace-on-write default. Pre-1.29 graphs that relied on graph.SetReducer(field, reducer) continue to work — SetReducer remains the escape hatch — but new code should prefer the prefix convention.
  • .creds regeneration. Every microservice’s .creds should be regenerated with the new gencreds, since the ACL emission scheme has been polished and the canonical ValidateHostname may catch edge cases the old validator missed. The upgrade skill regenerates them in place.
  • manifest.yaml regeneration. Likewise, every microservice’s manifest.yaml should be regenerated with the new genmanifest to pick up the reducer-prefix detection and updated emit logic. The upgrade skill walks the project.
  • Hostname validation strictness. A handful of edge-case hostnames that were silently accepted by older validators may now fail at startup. Conformant hostnames are unaffected.

Migration

From inside a Microbus project, ask Claude Code to “upgrade Microbus”:

Get the latest version of Microbus.

The upgrade skill handles the version bump end-to-end:

  1. Bump go.mod to v1.29.0 and go mod tidy.
  2. Refresh .claude/rules/, .claude/skills/, and project-wide framework-managed files.
  3. Re-run genmanifest for every microservice; reconcile any manifest.yaml schema drift.
  4. Re-run gencreds for every microservice; regenerate .creds.
  5. Apply the reducer-prefix convention to existing workflow tasks where the rename is mechanical (the skill flags any ambiguous renames for human review).
  6. Update local CLAUDE.md files with the secondary-rule triggers where applicable.
  7. Build and run the integration test suite to verify.

After the skill completes, run go vet ./... and go test ./... -count=1. Review any // TODO: comments the skill emitted at sites that needed human judgment.

Documentation

Backward Release Notes v1.28.0 Forward