Flower

View saved version →

---
name: flower-action-runtime-guide
description: Use when creating, building, modifying, reviewing, migrating, or testing Java code that uses flower-action-runtime, including new Maven or Gradle project setup, Maven Central dependency and backend-module selection, ActionProposal and ActionDefinition design, registry/validation/policy/approval/pre-execution controls, visibility-safe owner-aware in-memory or JDBC duplicate handling, explicit failure retry policy, synchronous/async/deferred executor selection, ActionRun and RunStore persistence, JDBC CAS concurrency, completion/cancellation/recovery, Flower workflow or event-loop backends, and 0.1/0.2-to-0.3 migration.
---

# Flower Action Runtime Guide

## Overview

Use this skill to keep business actions behind one explicit control boundary
while supporting approval, audit, asynchronous work, durable completion, and
safe concurrent state changes.

This skill owns action-runtime guidance. When the host also authors Flower
Flows, Steps, Guards, Workers, event waits, or checkpoints, also load the
sibling `flower-app-guide` skill and follow both sets of rules.

## Start Here

Always read:

- `references/00-guide-version.md`
- `references/01-runtime-quick-rules.md`
- `references/90-verification.md`

Then read the reference that matches the task.

## Reference Routing

- Creating a Maven or Gradle host, choosing Action Runtime modules, adding or
  upgrading dependencies, or resolving Flower compatibility: read
  `references/05-build-and-module-selection.md`.
- Designing actions, proposal identity, definitions, policy, approval,
  pre-execution checks, results, audit, or idempotency: read
  `references/10-action-model-and-controls.md`.
- Choosing synchronous, in-process async, or durable deferred execution and
  implementing completion/cancellation: read
  `references/20-execution-modes.md`.
- Working with `ActionRun`, custom `RunStore`, JDBC schema/migrations, CAS,
  recovery, or multiple server instances: read
  `references/30-persistence-and-concurrency.md`.
- Selecting `DefaultActionRuntime`, the workflow backend, or the event-loop
  backend: read `references/40-flower-backends.md`.
- Writing unit, parity, concurrency, persistence, or recovery tests: read
  `references/50-testing.md`.
- Integrating the runtime into REST, MCP, schedulers, AI planners, Spring, a
  domain application, or Flower's common observation pipeline: read
  `references/60-host-integration.md`.

## Workflow

1. Identify the business side effect and every entry point that can request it.
2. Before changing a host build, read
   `references/05-build-and-module-selection.md`, preserve compatible host
   dependency management, and select only requirement-backed modules. Pin the
   published Maven Central `0.3.3` artifacts and verify APIs against the
   `v0.3.3` source tag. Inspect a mutable checkout only when modifying the
   runtime itself; its main branch may be a later SNAPSHOT.
3. Define a stable action id and register exactly one controlled executor.
4. Map request channel, proposer type, execution principal, tenant, run id, and
   idempotency key without collapsing them into one actor field. In 0.3,
   `ActionOrigin` no longer exists.
5. Configure validation, policy, approval, duplicate handling, audit/trace, and
   the pre-execution guard before exposing the action.
6. Choose the executor mode by lifetime and durability, not by convenience.
7. Use a queryable `RunStore` for approval, async, deferred, callback, or
   cancellation work. `InMemoryRunStore` may be sufficient for same-JVM
   local/test use; use a shared durable store for restart-sensitive,
   multi-instance, or production deferred work.
8. If Flower drives the backend, keep Worker/EventWorker ticks non-blocking and
   keep governance semantics in the shared action pipeline.
9. Add focused failure, resume, race, and recovery tests. Before reporting the
   work complete, map every applicable control to a named test and apply the
   controlled-action completion gate below, then run the complete verification
   appropriate to the changed modules.

## Controlled-Action Completion Gate

A generic duplicate test is not evidence for every duplicate-safety property.
First classify completed-result visibility as tenant-global/shareable,
principal-restricted, resource-bound, or a combination. Do not invent a
principal or resource boundary merely to satisfy this checklist. Keep each
applicable scenario as a distinct named test:

1. When policy has a denied-principal boundary, complete an authorized request,
   then retry the same tenant, action id, idempotency key, and resource when one
   applies, as a denied execution principal. Assert policy denial before
   `RETURN_EXISTING`, no cached output/result or protected run/resource
   disclosure, and no additional domain side effect.
2. When the action or result is resource-bound, complete a request for resource
   A, then reuse the same tenant, action id, and idempotency key for resource B
   with a request that is otherwise valid and authorized for B. Assert that A's
   result and protected data are not returned for B.

Record a short N/A reason for a genuinely absent visibility dimension or an
intentionally shareable result.

When a stateful duplicate policy claims concurrent duplicate suppression
and caches or finalizes reservations, also run a deterministic full-pipeline
race. Both contenders must call the Action Runtime; any accepted request must
pass through the registered executor. Place barriers or latches immediately
before the atomic reserve/complete transitions and never wait while holding the
per-scope lock. Assert exactly one `DuplicateActionDecisionType.ACCEPT`
reservation, exactly one executor invocation/domain side effect, and no
terminal overwrite. During the race the duplicate may observe the in-progress
rejection or the original result; every later duplicate must return the
unchanged original cached terminal result. A policy-only race is still useful
for ownership and ABA assertions, but it does not prove the runtime side-effect
count and cannot replace this full-pipeline test.

## Unsafe Control-Bypass Response Contract

When a request asks an admin, callback, retry, recovery, or other entry point
to call the side effect directly or return an existing result before
authorization, the agent-authored user-facing response must:

1. Explicitly refuse both the direct side-effect path and the
   pre-authorization duplicate/result lookup.
2. State that trusted execution principal and tenant come from host context
   and remain separate from request channel and proposer metadata.
3. Preserve definition resolution, validation, authorization/policy,
   visibility-safe duplicate handling, approval, audit, `PreExecutionGuard`,
   and the registered executor boundary.
4. State that approval/resume re-resolves the definition, re-validates current
   input, re-evaluates current policy, and runs `PreExecutionGuard` immediately
   before dispatch.
5. Explain that an early or insufficiently scoped cached-result lookup can
   disclose another tenant's, principal's, or resource's result.

Do not leave these consequences and controls implicit or only in referenced
guidance, and do not suggest a feature flag, alternate service, raw SQL, or
callback path that recreates the bypass.

## Non-Negotiable Rules

- Treat UI, REST, batch, MCP, scheduler, and AI output as proposals. Only a
  registered `ActionExecutor` may perform the controlled side effect.
- Never bypass registry, validation, policy, approval, duplicate handling, or
  audit in a resume, callback, retry, recovery, or admin path.
- Re-resolve, re-validate, re-evaluate policy, and run `PreExecutionGuard`
  after approval and immediately before dispatch.
- Do not block Flower Worker or EventWorker ticks with domain work, HTTP, LLM,
  tools, sleeps, or `Future.get()`.
- Use `ActionExecutionResult.code()` and `RetryDisposition` for machine
  decisions. Do not parse human messages or leave failure retry safety
  implicit.
- Give every action request a unique `runId`. Use the idempotency key to group
  transport retries; do not reuse a run id for a new request.
- Make every `RunStore` transition versioned CAS. Do not add an unconditional
  update/upsert path to the runtime SPI.
- Authenticate callback callers and verify tenant, run id, and attempt token.
- Make external cancellation hooks idempotent for the same run attempt and
  operation id.
- Scope duplicate reservations by at least tenant, action id, and idempotency
  key. Add principal or resource scope when an existing result is not safely
  shareable within the tenant.
- In `0.3.3`, `InMemoryDuplicateActionPolicy` scopes by tenant, action id,
  idempotency key, and an optional trusted visibility scope. Do not use the
  tenant-wide default when a cached result contains
  principal- or resource-restricted data. Authorizing the current request
  before lookup is insufficient when that authorization may concern a
  different resource from the cached result. Bind reservation/result lookup to
  a stable trusted principal or canonical resource identity through
  `DuplicateVisibilityScopeResolver`, or reject the duplicate without returning
  the cached result. Never derive that scope from arbitrary request payload,
  AI output, or an unverified callback. Run the corresponding
  denied-principal or authorized cross-resource test when that visibility
  boundary exists; otherwise record the dimension as N/A without inventing it.
- The `0.3.3` `InMemoryDuplicateActionPolicy` uses one owner-aware atomic state
  per scope and can suppress concurrent duplicates inside one JVM. It remains
  non-durable and unbounded: reservations/results disappear on restart, do not
  coordinate multiple processes, and are never evicted. Use
  `JdbcDuplicateActionPolicy` or another shared durable policy when restart or
  multi-instance coordination matters.
- Keep duplicate reservation state separate from `ActionRun` lifecycle state.
  For the shipped JDBC policy, apply the matching host-owned
  `db/action_duplicate/<dialect>.sql` or additive migration. Do not add an
  automatic TTL/lease takeover: an old `RUNNING` reservation does not prove
  that an external side effect stopped. Reconcile `ActionRun` and domain state
  before any explicit repair.
- Treat duplicate reservation, completion, and release as one atomic
  owner-aware per-scope state machine. Retain the current reservation owner
  from trusted execution identity, normally the unique `runId`; apply
  `complete()` or `release()` only while that caller still owns the
  reservation. Do not coordinate `completed` and `running` through separate
  unguarded reads and writes. A reserve racing with completion must observe the
  existing reservation or completed result, never accept again or overwrite
  terminal truth. A stale or repeated completion/release must not alter a
  newer owner's reservation. Use one lock or atomic map transition in-process
  and durable uniqueness/CAS in production. Test reserve-versus-complete plus
  stale/double-complete and stale/double-release ABA sequences with barriers
  or latches; prove one accepted execution, one side effect, stable terminal
  truth, and preservation of the current owner.
- Resolve, validate, and authorize the current request before duplicate
  reservation or `RETURN_EXISTING` result lookup.
- Treat `CANCELLED` as the runtime's terminal acceptance decision, not proof
  that an external operation physically stopped.
- Treat deferred dispatch as at-least-once-capable integration, not an
  exactly-once guarantee. Require deterministic operation ids, idempotent
  dispatch, authenticated callbacks, reconciliation, and an orphan policy.
- Treat `ActionRun` as runtime lifecycle truth. Flower checkpoints, events,
  signals, futures, and callback payloads are orchestration or delivery data.

## Source Of Truth

For a consuming application, the published `0.3.3` artifacts and the matching
`v0.3.3` source tag are authoritative. Never make a distributable guide,
sample, or plugin depend on a mutable checkout, `mavenLocal()`, or a SNAPSHOT.
When modifying the runtime itself, its checked-out source and tests become the
working source of truth. Useful upstream documents include:

```text
flower-action-runtime/README.md
flower-action-runtime/flower-action-runtime-core/README.md
flower-action-runtime/docs/architecture/DEFERRED_ACTION_EXECUTION.md
flower-action-runtime/docs/architecture/ACTION_RUN_PERSISTENCE.md
flower-action-runtime/docs/architecture/DURABLE_DUPLICATE_HANDLING.md
flower-action-runtime/docs/architecture/EXECUTION_BACKEND_STRATEGY.md
flower-action-runtime/docs/architecture/V0_2_MIGRATION_AND_MODULE_IMPACT.md
flower-action-runtime/docs/architecture/V0_3_MIGRATION_AND_MODULE_IMPACT.md
```

Referenced files: 11

View saved version →

---
name: flower-app-guide
description: Use when creating, building, modifying, reviewing, or testing application code that uses Flower, including new Maven or Gradle project setup, Maven Central dependency and module selection, Flow and Step design, Step Guards, non-blocking Worker ticks, worker-lane selection, event/signal/timeout waits, Spring Boot Engine or Worker wiring, runtime console/dump observability, standalone Flower Studio trace/graph/evaluation inspection, Kafka/Bloom/domain event integration, durable checkpoint/resume, flower-testkit tests, and flower-check adoption in a host app.
---

# Flower App Guide

## Overview

Use this skill when implementing application workflows with Flower. The goal is
to help an AI coding agent produce explicit, testable Flow/Step application code
instead of scattered callbacks, hidden polling loops, sleeps, or ad-hoc status
switches.

This skill is for applications that use Flower. It is not primarily for
modifying the Flower framework source itself.

Use `flower-agent-guide` for AgentRun, Tool-loop, transcript, or Agent model
gateway semantics. Use `flower-ai-harness-guide` for one AI task's validation,
refine, fallback, provider, or recovery semantics. Load this app guide as well
when either task changes host Flower wiring or Flow/Step code.

## Start Here

Always read:

- `references/00-guide-version.md`
- `references/01-app-quick-rules.md`
- `references/90-verification.md`

Then read the area-specific reference that matches the application work.

## Reference Routing

- Creating a Maven or Gradle host, choosing Flower modules, adding or upgrading
  dependencies, configuring the Spring Boot starter, selecting offline
  evaluation support, or installing
  `flower-check`: read `references/05-build-and-module-selection.md`.
- Designing a Flow, Step classes, Step ids, StepResult transitions, or app workflow module: read `references/10-flow-step-authoring.md`.
- Waiting for Kafka/domain events, callbacks, signals, timeouts, or Bloom events: read `references/20-events-and-waits.md`.
- Durable application flows, checkpoints, resume, idempotency, or `ExecutionContext`: read `references/30-durable-app-flows.md`.
- Tests for Flow behavior, manual ticks, fake clocks, event publishing, or recovery tests: read `references/40-testing-with-testkit.md`.
- Event-driven app workloads such as LLM/tool/external/human waits that fit `flower-eventloop`: read `references/50-eventloop-for-apps.md`.
- Adding `flower-check` to an application build or fixing checker findings: read `references/60-flower-check-adoption.md`.
- Visualizing the static Flow structure of a source project, producing a
  machine-readable Flow inventory, or checking structural changes with
  `flower-flow-graph`: read `references/65-flow-graph-tooling.md`.
- Using Step Guards for pre-step checks, holds, redirects, or fail-fast conditions: read `references/70-step-guards.md`.
- Inspecting Engine, Worker, Flow, or Step execution in a Spring Boot host,
  exposing a protected dump endpoint or built-in console, or selecting
  observability integration: read
  `references/80-spring-boot-observability.md`.
- Connecting a Flower application to the standalone Flower Studio, exporting
  correlated observation or evaluation JSONL, or inspecting local Traces,
  execution graphs, evaluations, and monitoring: read
  `references/85-flower-studio-integration.md`.

## Workflow

1. Inspect the host build, Java and Spring baseline, execution model, database,
   and test setup. For a new project or dependency change, select the smallest
   requirement-backed module set from
   `references/05-build-and-module-selection.md`.
2. Identify the application workflow being modeled and the domain state that is
   the source of truth.
3. Choose whether the ordinary tick-driven Flower model or the event-loop model
   fits the workload.
4. Model business phases as explicit Steps with stable string step ids.
5. Choose Flower worker lanes by execution character, not by feature name.
6. Keep each Step small: start work, observe domain state/events/time, and
   return an explicit `StepResult`.
7. Keep blocking IO, LLM calls, tool calls, and long work outside the Flower
   worker tick. Steps should submit work and observe results, not wait inside
   the lane thread. If a request asks for blocking work in a tick, the
   user-facing response must explicitly state that the synchronous wait
   occupies the lane, stalls unrelated Flows, and creates backpressure; do not
   leave that consequence implicit or only in referenced guidance. Refuse that
   mechanism and still provide the complete safe replacement: dispatch once,
   observe persisted state or an event on later ticks, include an explicit
   deadline/cancellation path, and preserve deterministic tests. For a durable
   or restartable Flow, never keep completion truth only in a `Future`,
   `CompletionStage`, or Step field, and never re-dispatch merely because that
   volatile handle disappeared. Persist the operation id, lifecycle state,
   result/failure, and deadline as applicable; completion code persists the
   result before it signals the Flow, and recovery observes the same operation.
8. Give every long-lived external or domain wait an explicit cancellation,
   deadline/timeout, max-bound, or other terminal path appropriate to its
   semantics. When a durable wait is time-bounded, persist its deadline before
   entering the wait. A truly indefinite monitor needs a narrowly reasoned
   suppression that explains its ownership and liveness model; never justify a
   suppression merely by calling a wait "intentional" or "unbounded."
9. Audit every Flower Check suppression in the workflow being changed,
   including pre-existing suppressions. A clean checker report does not prove
   suppressed code is safe. Remove or redesign a suppression unless the source
   explains why the checker-recognized Flower-native alternative is
   incompatible or unsuitable for the selected persistence, semantics, or
   operational model and deterministic tests cover the selected terminal
   control, duplicate delivery, and restart where supported. Map that evidence
   to each suppression independently: coverage for a later or similar wait
   never satisfies an earlier suppressed wait, and extending a workflow must
   not delete existing suppression-specific recovery coverage.
10. Add deterministic tests with manual ticks or `flower-testkit`. Recovery
    tests must assert every execution identity value the application supplied:
    `tenantId`, `userId`, `sessionId`, `runId`, `traceId`, and
    `correlationId`, not only a subset. Apply this independently to every
    recovery scenario and supported wait state, including success,
    deadline/timeout, cancellation, and duplicate-delivery paths; assertions
    in one recovery test never cover another. Assert identity at the first
    observable post-recovery point; with `FlowTestHarness`, this is immediately
    after the first deterministic tick following `recover(...)` or
    `recoverAll(...)`. Assert it again at terminal state when a snapshot
    remains available. For event- or signal-driven waits, deliver the same
    notification more than once and prove business side effects and terminal
    state remain correct. Drive manual ticks only from the test or host control
    thread; never re-enter the same Worker from a Step, Guard, listener, or
    callback already running on that Worker's tick thread.
11. Run the verification command from `references/90-verification.md` that
   matches the host application.

## Flower Source And Docs

When the public Flower repository is available, inspect its README, examples,
and module docs for exact API names before writing code. Application code should
follow the public API and examples first.

```text
https://github.com/flowerjvm/flower
flower/README.md
flower/docs/
```

Referenced files: 15