These pages describe Fibric’s target architecture. Public CLI, API, SDK, and sandbox access are not available. Examples do not establish deployed capabilities.
Single-flight & idempotency
Two kernel primitives limit concurrent and repeated attempts: single-flight serializes side effects per entity, and a recorded idempotency key suppresses another invocation within the executor boundary. Stable keys, storage scope, and connector behavior determine the protection. Both checks are part of the deterministic executor. This page describes both primitives, the exact order the executor applies them in, and what that order means for retries.
#The two primitives
Every PlannedAction carries two keys, and each key drives a different control.
Single-flight per entity
At most one side effect is in flight per entity at any moment. Two runs that both want to touch order SO-10884 do not race; the second waits for the first to finish. Serialization is scoped by the key, so actions on different entities still run freely.
Recognized retries deduplicate
A key recorded after a successful invocation returns a dedup result instead of invoking the connector again, while the record is retained. A lost acknowledgement can leave the downstream outcome uncertain.
The reference kernel calls the idempotency key the "657-flood lock," after an ungoverned automation sent 657 messages to one customer. A stable key can collapse repeated proposals inside the executor, and single-flight can serialize work on the entity. Those controls materially reduce that failure class; they do not guarantee the behavior of a connector or downstream service.
Neither primitive is an option an operator sets. The DeterministicExecutor applies both to every side-effecting action it runs. An operator that proposes the same hold twice in one plan produces one hold and one DEDUP result. There is no code path around the gate.
#Concurrent proposals for the same entity
The executor keeps an in-flight map keyed by entity_key:
private inflight = new Map<string, Promise<void>>(); // single-flight per entity_key
Before an action does anything else, it looks up its entity_key in this map. If a prior action's gate is present, the new action awaits it before proceeding. This is serialization, not rejection: the second proposal is not refused, it is queued behind the first. Once the prior gate resolves, the waiting action proceeds through the normal pipeline, where the idempotency check and the trust gate still apply to it individually.
Walk through the case single-flight exists for. Two operator runs, A and B, fire close together — say a schedule tick and an inbound observation land within the same second — and both propose orders.hold on order SO-10884 with the same idempotency key.
-
Run A's action arrives first
No entry exists in the in-flight map for
order:SO-10884. Run A registers its gate and proceeds: dedup check (key unseen), trust evaluation, invoke. The hold call is now in flight against the order system. -
Run B's action arrives while A is in flight
Run B finds A's gate in the map and awaits it. It does not invoke, does not evaluate policy, does not race. It waits.
-
Run A completes
The invoke succeeds, the executor records A's idempotency key as seen, releases the gate, and removes its entry from the map.
-
Run B proceeds and deduplicates
Run B enters the pipeline, reaches the idempotency check, finds its key already seen, and returns
decision: 'DEDUP', ok: truewithout touching the connector. One hold was placed. Both runs report success.
Without the serialization step, both runs would pass the dedup check simultaneously — neither key seen yet — and both would invoke. Single-flight is what makes the idempotency check trustworthy under concurrency: by the time the second action checks the key, the first has either recorded it or failed.
#Key derivation
Both keys are built deterministically in operator code after reasoning and carried on every PlannedAction; the model should not invent them. The reference kernel enforces the supplied keys. Derive entity_key from the entity itself, stable across operators, such as order:SO-10884. An idempotency key can additionally identify the operator and intended operation:
| Key | Field on PlannedAction | Scope | Example |
|---|---|---|---|
| Entity key | entity_key |
Serialization. All side effects sharing this key run one at a time, in arrival order. | order:SO-10884 |
| Idempotency key | idempotency_key |
Deduplication. A recognized retained key suppresses another invocation within the executor boundary. | ship-risk:SO-10884:hold |
The two scopes are deliberately different. entity_key answers "what must not be touched concurrently" — usually a conversation, an order, an asset, a room. idempotency_key answers "what counts as the same action" — the entity plus the operation. A hold and a release on the same order share an entity key (they must not interleave) but carry different idempotency keys (they are different side effects, and both should apply).
Key choice is a design decision with real consequences. Make the idempotency key too broad — order:SO-10884 with no action segment — and the release deduplicates against the hold and never runs. Make it too narrow — appending a timestamp or run id — and every retry looks like a new action, which defeats the lock entirely. The operator:entity:action shape is the stable middle: the same operator intending the same operation on the same entity is one side effect, however many times it is proposed.
A key containing a run id, a timestamp, or a random component is unique per proposal, so a retried or re-planned action stops deduplicating. Derive the entity key from the thing itself, shared across operators. Derive the idempotency key from the logical effect, including operator and operation where that identity is appropriate; use a stable business version for a genuinely new effect.
#Execution order per action
The executor's runAction() applies its gates in a fixed order for every action in a plan. The order matters; several guarantees on this page fall directly out of it.
- Wait on in-flight work. If any prior action holds the gate for the same
entity_key, await it before doing anything else. - Reads run immediately. If the connector registry reports the tool is not side-effecting, the action is invoked at once — no policy evaluation, no idempotency check — and returns
decision: 'ALLOW', ok: truewith the result. - Idempotency check. For a side effect, a seen
idempotency_keyreturnsdecision: 'DEDUP', ok: truewithout invoking the connector. - Trust evaluation. The action is scored against your trust policies. A
BLOCKreturnsok: falsewith the errorblocked by trust policy, and nothing reaches the connector. - Invoke. The connector runs the tool with the proposed arguments.
- Only a successful invoke burns the key. The idempotency key is recorded as seen after the invoke succeeds, and only then. A failed invoke returns
ok: falsewith the error, and the key is left unburned. Before retrying an ambiguous failure, reconcile downstream state or rely on a downstream idempotency key.
Two consequences of the ordering are worth stating plainly. Because the dedup check (step 3) precedes the trust gate (step 4), an action that already applied does not consume an approval or appear in the escalation queue a second time; it short-circuits as DEDUP. A seen key means the executor recorded a successful invocation. It does not independently prove the current downstream state; a misleading vendor response or later external change still requires reconciliation.
The executor's run() walks a plan's actions sequentially, awaiting each result before starting the next. Ordering within a plan is guaranteed: a hold proposed before a notification completes (or fails) before the notification begins. Concurrency exists between runs, which is exactly the case single-flight serializes.
#Retry semantics
Step 6 is the whole retry story. The idempotency key is checked before every attempt and recorded only after a successful one, which gives retries a clean two-phase behavior:
- Before the first success, retries are real attempts. An invoke that fails — a timeout, a 500 from the vendor, a dropped connection — leaves the key unburned. The next proposal of the same action passes the dedup check, re-passes the trust gate, and invokes again. A timeout or dropped acknowledgement may still conceal a downstream success, so confirm the outcome or use vendor-side idempotency before retrying.
- After a success, retries collapse to
DEDUP. Once one attempt succeeds and the key is recorded, every subsequent proposal with the same key returnsdecision: 'DEDUP', ok: truewithout invoking. The dedup result reports a recorded prior success; verify downstream state when the actual effect matters.
A retained key suppresses recognized retries after recorded success. The important boundary is an ambiguous downstream result: if an invoke succeeds at the vendor but the success is lost in transit before the key is burned, a retry could re-invoke. Connectors mitigate this by passing the idempotency key downstream where the vendor's API supports one, making the write idempotent at both layers.
There is no separate retry API. To retry a failed action, propose it again with the same idempotency_key — in the next scheduled run, or explicitly with fibric operators run <name> --once. The executor sorts out whether the attempt is real or a dedup.
#ActionResult and dispositions
Every action in a plan produces an ActionResult. Its decision field is an ActionDisposition: the three trust decisions plus DEDUP, which only the executor can produce.
export type ActionDisposition = TrustDecision | 'DEDUP';
export interface ActionResult {
action: PlannedAction;
decision: ActionDisposition;
ok: boolean;
result?: unknown;
error?: string;
}
| Disposition | ok | Meaning |
|---|---|---|
ALLOW |
true on success; false with error if the invoke threw |
The action passed policy and was invoked unattended. Reads always carry this disposition. |
ALERT |
true on success; false with error if the invoke threw |
The action passed policy at the escalation tier: it was invoked and raised for human attention. |
BLOCK |
false, error: "blocked by trust policy" |
The trust gate vetoed the action. The connector was never invoked and the idempotency key was not burned. |
DEDUP |
true |
The idempotency key was already seen: this side effect has applied before. The connector was not invoked, and no result is returned. |
Here is the result array for a plan that proposed the same hold twice — the shape run B's caller would see in the walkthrough above, or any plan carrying an accidental duplicate:
[
{
"action": {
"connector": "magento",
"tool": "orders.hold",
"args": { "order": "SO-10884", "reason": "ship-risk-review" },
"entity_key": "order:SO-10884",
"idempotency_key": "ship-risk:SO-10884:hold"
},
"decision": "ALLOW",
"ok": true,
"result": { "status": "holded", "order": "SO-10884" }
},
{
"action": {
"connector": "magento",
"tool": "orders.hold",
"args": { "order": "SO-10884", "reason": "ship-risk-review" },
"entity_key": "order:SO-10884",
"idempotency_key": "ship-risk:SO-10884:hold"
},
"decision": "DEDUP",
"ok": true
}
]
One hold was placed. Both entries report ok: true: one records a successful invocation and the other recognizes its retained key. Those results do not independently verify downstream state. The disposition tells you which entry did the work, and the target receipt trail preserves the distinction for its agreed retention period.
#Durability
In the reference kernel, the dedup record is an in-memory Set<string> and the in-flight map lives in the process. That is correct for a single executor process and for development, and it is honest about its limits: a process restart forgets seen keys.
The target durable execution design uses storage such as Postgres or DynamoDB behind the DurableExec seam. A deployment must verify shared coordination, key retention, and restart recovery across its executor instances; the in-memory reference does not establish those properties. Durable records still cannot resolve an unacknowledged downstream effect on their own. See Architecture for the seam model.
#Keep going
- Trust tiers: the policy gate every side effect passes through between dedup and invoke.
- Receipts & audit: how every disposition on this page, including
DEDUP, is recorded permanently. - The event envelope: the tenant-scoped context every action runs under.
- Architecture: where the executor and the DurableExec seam sit in the kernel.