Skip to content

feat(agentic-org): replay NATS outbox follow-up #5007

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AceHack merged 5 commits into from
May 25, 2026
Merged

feat(agentic-org): replay NATS outbox follow-up #5007

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dde684c
claim: task-pr-4990-nats-outbox-replay - clean replay
May 25, 2026
248a593
feat(agentic-org): add NATS outbox publisher contract
May 25, 2026
855add8
refactor(agentic-org): keep durable state adapter replaceable
May 25, 2026
50e6dd2
release: task-pr-4990-nats-outbox-replay - opened PR #5007
May 25, 2026
779720f
fix(agentic-org): address outbox publisher review
May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 26 additions & 15 deletions agentic-organization/docs/FIRST_IMPLEMENTATION_SLICE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@ Implemented as a small NodeNext TypeScript package slice.
This slice turns the first Agentic Organization runtime contract from
architecture prose into executable TypeScript.

It does not introduce NestJS, CockroachDB, NATS clients, Temporal,
Dapr, Hermes, Hindsight, or Kubernetes deployment manifests yet. Those
remain adapter layers. The goal is to prove the Organization command
shape before adding distributed infrastructure.
It does not introduce NestJS, live NATS connections, Temporal, Dapr,
Hermes, Hindsight, or Kubernetes deployment manifests yet. Those remain
adapter layers. The goal is to prove the Organization command and event
publication shape before adding distributed infrastructure.

The slice is intentionally generic. `send_supervisor_signal` is the
coordination primitive; specific downstream outcomes are lifecycle
Expand All @@ -29,6 +29,8 @@ send_supervisor_signal
-> chain-of-command signal
-> audit event
-> outbox event with canonical event envelope
-> outbox publisher
-> NATS JetStream event publisher adapter
-> NATS subject contract
-> LGTM span attributes
-> supervisor triage reaction plan
Expand All @@ -40,9 +42,10 @@ send_supervisor_signal
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@agentic-org/domain` | event envelope, command/event constants, aggregate constants, supervisor-chain communication types, hat communication briefs, work item state machine, shared records |
| `@agentic-org/application` | command pipeline, command-handler registry, state-store ports, idempotency conflict handling, supervisor signal handler |
| `@agentic-org/state` | in-memory Organization state-store factory fake |
| `@agentic-org/state-cockroach` | CockroachDB state-store factory contract, SQL statement catalog, and first core-state migration skeleton |
| `@agentic-org/messaging` | stable `agentic-org.<env>.<org>.<domain>.<event>` subject builder |
| `@agentic-org/state` | generic state-store/outbox-source ports plus the in-memory Organization state-store factory fake |
| `@agentic-org/state-cockroach` | first replaceable durable SQL implementation of the state-store/outbox-source ports, backed by CockroachDB |
| `@agentic-org/messaging` | stable `agentic-org.<env>.<org>.<domain>.<event>` subject builder, outbox publisher, event publisher port, and typed domain resolver |
| `@agentic-org/messaging-nats` | NATS JetStream event publisher adapter contract with canonical JSON payloads, headers, and message IDs |
| `@agentic-org/observability` | OpenTelemetry/LGTM span attribute projection |
| `@agentic-org/runtime` | first rule that plans triage for the target supervisor when a chain signal is sent |
| `@agentic-org/governance` | package dependency-boundary checks that prevent application code from importing concrete state/runtime adapters |
Expand Down Expand Up @@ -96,12 +99,20 @@ Hermes runs, MCP calls, and UI evidence.
- The command pipeline receives state-store factories and command
handlers through ports instead of constructing in-memory adapters or
branching on command types.
- State-store ports are async from the beginning so CockroachDB,
NATS-backed workers, and other real adapters do not inherit a fake
synchronous shape.
- State-store and outbox-source ports are async from the beginning so
durable SQL, NATS-backed workers, and other real adapters do not
inherit a fake synchronous shape.
- A governance test enforces that application code does not import the
state adapter, Cockroach adapter, NestJS, NATS, Dapr, Temporal,
Drizzle, or Postgres clients.
- A governance test enforces that the Cockroach state adapter does not
import messaging, NATS, or JetStream. Durable state can be swapped
without dragging transport concerns into the repository layer.
- The outbox publisher claims unpublished events, publishes each event
through an `EventPublisher` port, and marks rows published only after
the publish succeeds.
- The NATS adapter publishes canonical JSON envelopes with typed headers
and event IDs as message IDs for idempotent JetStream publication.
- Duplicate commands with the same idempotency key and request hash
replay the stored result.
- Duplicate commands with the same idempotency key and a different
Expand All @@ -113,11 +124,11 @@ Hermes runs, MCP calls, and UI evidence.

## Next Slice

The next slice should turn the CockroachDB adapter contract into a
transactional integration test once a local/dev Cockroach connection is
available, then add the NATS outbox publisher worker. The worker can
publish persisted outbox rows to JetStream and attach the same telemetry
attributes.
The next slice should add inbox/consumer dedupe before automation starts
performing side effects from NATS events. After that, wire the outbox
publisher into a worker host and add a transactional durable-state
adapter integration test using CockroachDB as the first cluster-backed
implementation once a local/dev connection is available.

Do not make the next slice a pile of bespoke request commands. Build the
generic supervisor triage lifecycle first, then let specialized
Expand Down
67 changes: 42 additions & 25 deletions agentic-organization/docs/TECHNICAL_CA_PACKAGE_ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,8 @@ The Organization owns:

The cluster provides:

- CockroachDB for authoritative Organization state;
- CockroachDB as the first durable SQL adapter for authoritative
Organization state;
- NATS JetStream for event transport, fanout, inboxes, replay, and DLQ;
- Temporal TS for durable long-running workflows;
- Dapr Actors for hot entity-local coordination;
Expand All @@ -77,7 +78,7 @@ Runtime host
-> command handler registry
-> policy check
-> domain state transition
-> CockroachDB transaction
-> durable state transaction through the state adapter
-> authoritative state
-> audit event
-> outbox event
Expand Down Expand Up @@ -163,9 +164,10 @@ calling them.

| Package | Owns |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `@agentic-org/state` | Drizzle schema, migrations, repositories, transactions, outbox, inbox, idempotency, leases |
| `@agentic-org/state-cockroach` | CockroachDB implementation of state-store ports, SQL statement catalog, and migration contracts |
| `@agentic-org/state` | generic state-store, outbox-source, inbox, idempotency, transaction, and lease ports |
| `@agentic-org/state-cockroach` | first replaceable durable SQL implementation of state-store and outbox-source ports |
| `@agentic-org/messaging` | NATS envelope builder, subject builder, JetStream publisher, consumer, DLQ, replay contracts |
| `@agentic-org/messaging-nats` | NATS JetStream implementation of the event publisher port, canonical JSON, headers, message IDs |
| `@agentic-org/workflows-temporal` | Temporal workflow and activity contracts, task queues, workflow clients |
| `@agentic-org/actors-dapr` | Dapr actor interfaces, actor implementations, reminders, actor state projection |
| `@agentic-org/mcp` | MCP schemas, tool registry, preflight checks, policy-checked tool handlers |
Expand Down Expand Up @@ -240,9 +242,10 @@ commands should register a handler; new persistence backends should
implement the same store-factory port.

State-store ports are async at the application boundary. In-memory
adapters may resolve immediately, but CockroachDB, transactional
outbox, inbox, and lease adapters must be able to perform real I/O
without changing command-handler contracts.
adapters may resolve immediately, but durable SQL, transactional outbox,
inbox, and lease adapters must be able to perform real I/O without
changing command-handler contracts. CockroachDB is the first durable SQL
adapter in the cluster, not an application-layer dependency.

## SOLID Rules

Expand Down Expand Up @@ -281,10 +284,11 @@ implement it. Runtime hosts bind implementations.

All state transitions are event-producing commands.

CockroachDB stores authoritative state, audit, idempotency, and outbox.
NATS JetStream carries event distribution, inboxes, live UI updates,
replayable integration streams, and DLQs. Logs, traces, and metrics are
evidence. They are not business truth.
The durable state adapter stores authoritative state, audit,
idempotency, and outbox. In `full-ai-cluster`, the first implementation
is CockroachDB. NATS JetStream carries event distribution, inboxes, live
UI updates, replayable integration streams, and DLQs. Logs, traces, and
metrics are evidence. They are not business truth.

### Canonical Event Envelope

Expand Down Expand Up @@ -344,6 +348,15 @@ type AgenticEventEnvelope<TPayload> = {
No app should publish raw NATS payloads directly. Publishing should go
through `@agentic-org/messaging`.

The generic outbox publisher should claim unpublished outbox events from
an `OutboxEventSource`, resolve the typed Organization messaging
domain, publish through an `EventPublisher` port, and mark the outbox
row published only after the publish succeeds. The NATS adapter is an
implementation of that port; it owns transport-specific concerns such as
headers, message IDs, and JSON serialization. This keeps the
Organization event loop extensible and testable without coupling the
publisher to the NATS client.

### Event-to-Automation Contract

Agentic Organization should behave like an event-driven operating system.
Expand Down Expand Up @@ -579,7 +592,7 @@ tree.

| Adapter package | Cluster dependency | Expected in-cluster target |
| --------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------- |
| `@agentic-org/state` | CockroachDB ArgoCD app | `cockroachdb-public.cockroachdb.svc.cluster.local:26257` |
| `@agentic-org/state-cockroach` | CockroachDB ArgoCD app | `cockroachdb-public.cockroachdb.svc.cluster.local:26257` |
| `@agentic-org/messaging` | NATS ArgoCD app with JetStream enabled | `nats.nats.svc.cluster.local:4222` |
| `@agentic-org/workflows-temporal` | Temporal ArgoCD app | `temporal-frontend.temporal.svc.cluster.local:7233` |
| `@agentic-org/actors-dapr` | Dapr control plane | Dapr sidecar plus `dapr-system` placement service |
Expand Down Expand Up @@ -668,7 +681,8 @@ They should get the narrowest network policy and credential scope first.

Current cluster readiness:

- CockroachDB exists as the distributed SQL substrate.
- CockroachDB exists as the first distributed SQL substrate. It is
consumed only through the durable state adapter boundary.
- NATS exists with JetStream enabled and Longhorn-backed file storage.
- Temporal and Dapr are present, but their Organization-specific
persistence/components still need wiring.
Expand All @@ -690,11 +704,11 @@ each substrate becomes live.

The same package architecture should run in three modes:

| Mode | Purpose | Runtime adapters |
| ----------------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
| unit/test | package and command tests | in-memory/fake adapters |
| local dev cluster | k3d/K3S parity with `full-ai-cluster` apps | real NATS/Cockroach when available, fake Hermes/hat-system if needed |
| full cluster | production-like AI cluster | real CockroachDB, NATS, Hindsight, Hermes, OpenZiti, hat-system, Temporal, Dapr |
| Mode | Purpose | Runtime adapters |
| ----------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| unit/test | package and command tests | in-memory/fake adapters |
| local dev cluster | k3d/K3S parity with `full-ai-cluster` apps | real NATS/durable SQL when available, fake Hermes/hat-system if needed |
| full cluster | production-like AI cluster | CockroachDB-backed state adapter, NATS, Hindsight, Hermes, OpenZiti, hat-system, Temporal, Dapr |

Do not create a Docker Compose architecture that diverges from
`full-ai-cluster`. Local development can use fakes or a dev cluster, but
Expand Down Expand Up @@ -761,6 +775,7 @@ other work.
- `@agentic-org/state-cockroach`;
- `@agentic-org/policy`;
- `@agentic-org/messaging`;
- `@agentic-org/messaging-nats`;
- `@agentic-org/observability`;
- `@agentic-org/work-os`;
- `@agentic-org/hats`;
Expand All @@ -770,8 +785,8 @@ other work.
- `@agentic-org/ui-projections`.
2. Implement the canonical command context, event envelope, typed enums,
and idempotency key builder.
3. Implement the first CockroachDB schema and Drizzle migrations for the
V0 executable contract.
3. Implement the first durable SQL schema and migrations for the V0
executable contract, using CockroachDB as the initial adapter.
4. Implement command handlers for:
- send supervisor signal;
- triage supervisor signal;
Expand All @@ -786,13 +801,15 @@ other work.
5. Use fake adapters for Hermes, Hindsight, Dapr, Temporal, and
hat-system.
6. Add NATS outbox publisher and one consumer after command tests pass.
7. Add the first rule catalog and reaction executor for ready work,
7. Add inbox/consumer dedupe before any NATS-driven automation performs
side effects.
8. Add the first rule catalog and reaction executor for ready work,
review staffing, QA staffing, blocker escalation, and late run
incidents.
8. Add the NestJS API and worker hosts.
9. Add UI projections for work board, review center, and evidence
timeline.
10. Add real cluster adapters one at a time.
9. Add the NestJS API and worker hosts.
10. Add UI projections for work board, review center, and evidence
timeline.
11. Add real cluster adapters one at a time.

## Extraction Path

Expand Down
Loading
Loading