Docs
Reference preview
Reference preview

These pages describe Fibric’s target architecture. Public CLI, API, SDK, and sandbox access are not available. Examples do not establish deployed capabilities.

Guides

Write guardrail policies

A guardrail policy is the deterministic half of every Fibric operation: the model proposes an ExecutionPlan, and the policy decides what may run. Policies are fail-closed, so anything a rule does not explicitly allow is refused. This guide covers the policy document in full: its anatomy, how rules evaluate, how to scope them by capability, how to validate a policy before it sees a live plan, and three worked examples you can adapt.

i
Two forms, one gate

This reference shows a proposed YAML authoring format and the kernel’s TrustPolicy array. Capability binding and a YAML adapter would map the first to the second; the public authoring workflow is not available. The examples describe the target managed approval flow. The reference executor treats ALERT as executable and does not provide that queue. See Trust tiers for the boundary.

#Policy document anatomy

A policy is a plain YAML document: a name, the operator it governs, an ordered list of rules, and a default that is always deny. Each rule permits one capability, optionally requiring confirmation or applying constraints. Omitted capabilities are refused. Rate limits and single-flight operate in the executor; maxValue and predicates are trust-evaluator constraints. The document below is a complete, realistic policy; every field it uses is defined in the table that follows.

policy.yaml
# governs one operator; apply with: fibric policy apply ./policy.yaml
policy: order-risk-guardrails
applies_to: order-risk-watcher

rules:
  # internal notes are low-risk: allow them without constraint
  - allow: conversation.note.write

  # holds are allowed, but capped and serialized per order
  - allow: order.hold
    limit:
      per: hour
      max: 25              # a flood cannot exceed this
    single_flight: order_id  # one in-flight hold per order

  # refunds within the cap require review; above it they block
  - require_confirmation: refund.issue
    max_value: 250

  # order.cancel has no grant and is refused by omission

# the default is always deny; stating it makes review unambiguous
default: deny
require_receipt: true
FieldTypeMeaning
policystringThe policy's name. Referenced by fibric policy validate and recorded on every receipt the policy disposes.
applies_tostringThe operator this document governs. This document supplies operator-scoped rules. Active tenant policies also participate; a side effect blocks when the combined rule set has no permission or a matching constraint fails.
ruleslistThe rule list. Each entry names one capability under allow or require_confirmation, plus optional constraints. Omit capabilities that must not run.
allowstring (capability)Grants the named capability. An allow with constraints grants it only while every constraint passes; a failing constraint blocks the action.
denystring (capability)Use default: deny and omit the capability’s grant. An explicit decision: BLOCK is not a veto implemented by the reference evaluator; do not use it to override another matching permission.
require_confirmationstring (capability)Permits the capability only with a human in the loop. A matching action is parked, not run, and disposes as ALERT. Approval executes the original action under its original idempotency key.
limit.perrun | minute | hour | dayThe window a rate limit counts within. per: run caps a single operator run, the form the quickstart uses; the time-based windows cap sustained throughput.
limit.maxintegerThe most actions the rule permits within one window. The count is enforced by the executor, not the model, so a runaway proposal cannot talk its way past it.
single_flightstring (key field)Serializes side effects per entity: at most one in-flight action for each distinct value of the named field. This becomes the action's entity_key. See Single-flight & idempotency.
max_valuenumberA value ceiling. The executor compares it against the action's value field, a refund amount, for example, and blocks anything above it.
defaultdenyWhat happens to an action no rule matches. The only accepted value is deny; the field exists so the fail-closed posture is stated in the document rather than assumed.
require_receiptbooleanRequires an immutable receipt for every disposed action, including blocked ones. Defaults to true; leaving it explicit keeps the guarantee visible in review.

#Rule evaluation and default-closed semantics

Only side-effecting actions are gated. Reads pass through without a policy match, which is why a read-only operator such as the one in Build an ops analyst can run under an empty rule list. For every side-effecting action in a proposed plan, evaluation follows three steps, in order:

  1. Match. The evaluator collects every rule whose capability names the action. No matching rule means the action is blocked; the fail-closed refusal is the absence of permission, not the presence of a deny.
  2. Constrain. Every max_value or predicate constraint on every matching rule must pass; any failure blocks the action. The executor separately enforces rate limits and serializes work under the entity lock. Lock contention waits or returns a retryable conflict; it is not a trust-policy BLOCK.
  3. Decide. If any matching rule is a require_confirmation, the action disposes as ALERT and waits for a person. Otherwise it disposes as ALLOW and runs.

Rule order in the document does not create precedence; matching is by capability, and constraints compose. Order the rules for the human reader.

#What the YAML compiles to

The proposed adapter maps capability rules into TrustPolicy entries selected by connector and tool (leaving either undefined matches any). maxValue and predicate are constraints: all must pass before the matching ALLOW or ALERT decision applies. BLOCK is returned for no match or a failed constraint. Rate-limit, lock, and approval controls sit outside this pure evaluator:

YAMLKernelDisposition
allow: <capability>a policy with decision: 'ALLOW' matching the capability's connector and toolALLOW while constraints pass
require_confirmation: <capability>a matching policy with decision: 'ALERT'ALERT: parked for human approval
max_value: nmaxValue: n on the compiled policy; compared against the action's valueBLOCK when exceeded
deny / default: denyomitted capability grant: evaluate() returns BLOCK when nothing matchesBLOCK, fail closed

The executor adds one more disposition the policy never produces: DEDUP, returned when an action's idempotency_key has already been applied. A recognized retained key short-circuits before trust evaluation. A failed attempt has no recorded success key and can run again; the proposed limiter must define how attempts are counted.

!
No matching permission blocks side effects

There is no permissive failure mode. A policy that fails to parse must stop activation. An empty policy adds no permission; side effects block when no active tenant or embedded rule permits them. Removing one rule is different: another matching rule may still permit the action, and removing a constraint may widen permission. Review the complete effective policy before applying a change. It never acts without permission. See Governance & trust for why the platform is built this way.

#Scoping rules by capability

Rules name capabilities, never vendors. order.hold, conversation.note.write, and refund.issue are capability names; which connector serves each one is decided by the tenant's role bindings, described in Capabilities. This indirection is what keeps a policy stable across infrastructure changes: swap the order system behind the orders role and the policy governing order.hold does not change, because it never mentioned the old vendor.

Capability indirection can let the same policy serve sandbox and production. The sandbox guide illustrates rebinding sandbox-orders; production bindings, permissions, limits, and downstream behavior still require validation.

Scope each rule as narrowly as the operation allows:

#Validate before anything acts

Two commands let you exercise a policy with zero side effects: one static, one against a real proposal.

#Static validation

fibric policy validate checks a policy against an operator without running anything: every capability the operator declares is compared against the rule list, and the command reports what would be allowed, escalated, and refused.

bash
fibric policy apply ./policy.yaml
fibric policy validate order-risk-guardrails --against order-risk-watcher
$ fibric policy validate order-risk-guardrails --against order-risk-watcher conversation.note.write allow unconstrained order.hold allow limit 25/hour · single-flight by order_id refund.issue confirm ≤ $250 · above ceiling → block order.cancel deny no matching grant orders.read read not gated ✓ valid · no capability the operator declares is left implicit

#Dry-running a live proposal

fibric operators run --dry-run goes one step further: the operator senses and proposes for real, and the executor evaluates the plan against the applied policy, but nothing executes. The output shows every proposed action, its would-be disposition, and the idempotency key each step would carry, which is how you confirm dedup behavior before the first real run.

bash
fibric operators run order-risk-watcher --dry-run
$ fibric operators run order-risk-watcher --dry-run sensed 38 open orders reasoned proposed 4 actions (dry run: nothing will execute) would-be dispositions: order.hold SO-11290 ALLOW key=order-risk:SO-11290:hold order.hold SO-11304 ALLOW key=order-risk:SO-11304:hold refund.issue SO-11288 BLOCK $410 > $250 → exceeds cap order.cancel SO-11251 BLOCK no matching grant ✓ dry run complete · 0 side effects · plan written to .fibric/dev/plans/

For local iteration before a deploy exists at all, the fibric dev harness replays recorded envelopes through the same evaluator; that workflow is covered in Testing connectors and the sandbox guide.

#Worked examples

#A notify-only starter policy

The safest first policy for a new operator grants nothing but notification. The operator senses, reasons, and proposes at full fidelity; the only thing that can reach the world is a message. This is the policy to run for the first week while you read receipts and learn what the operator wants to do.

policy.yaml
policy: ship-risk-starter
applies_to: ship-risk

rules:
  - allow: orders.notify
    limit:
      per: hour
      max: 10

default: deny
require_receipt: true

With this as the only active rule set, proposed holds and refunds dispose as BLOCK and are receipted with the proposal attached. Check that tenant policies add no matching permission before using it as a notify-only rollout. The blocked receipts are the point: they show you, with real data, exactly which rules the operator has earned before you grant them.

#A value-capped refund policy, in both forms

This policy requires review for refunds within a $250 cap and blocks larger refunds. A failed cap is not an escalation condition; adding a broad confirmation rule does not override it. In the proposed YAML form:

policy.yaml
policy: refund-guardrails
applies_to: refund-guard

rules:
  # within the cap: review; above the cap: block
  - require_confirmation: refund.issue
    max_value: 250

default: deny

And the TrustPolicy array it compiles to, with the capability resolved to its bound connector and tool:

policy/trust.ts
import type { TrustPolicy } from "@fibric/sdk";

// everything not listed here is blocked by omission:
// there is no "allow the rest" rule to forget.
export const policies: TrustPolicy[] = [
  // within the cap: ALERT; above the cap: BLOCK
  {
    connector: "payments",
    tool: "refunds.create",
    maxValue: 250,
    decision: "ALERT",
  },
];

Walk three proposals through it. A $180 refund matches the policy and passes the cap, so evaluate() returns ALERT. The target managed approval workflow holds it for an authorized person; the reference executor alone does not. A $900 refund exceeds the cap and returns BLOCK, which approval cannot override. A $50 account credit through credits.apply matches nothing, so evaluate() returns BLOCK. You never wrote a rule against credits; the refusal is structural. The full walkthrough, including the plan JSON and receipts, is in Guard a refund flow.

#A rate-limited hold policy

Rate limits address one failure class: the runaway loop. The incident that shaped the reference kernel was an ungoverned automation that sent 657 messages to one customer. Stable idempotency keys can collapse repeats of the same proposed action, while rate limits cap distinct actions per window. These controls materially reduce flood risk, but they still require correct key design, connector behavior, and downstream reconciliation.

policy.yaml
policy: hold-guardrails
applies_to: order-risk-watcher

rules:
  - allow: order.hold
    limit:
      per: hour
      max: 25              # the flood ceiling, enforced by the executor
    single_flight: order_id  # never two holds in flight for one order

default: deny

When the limit is reached, the twenty-sixth hold in the hour disposes BLOCK with the limit named in the receipt. The operator keeps sensing and proposing; the executor resumes allowing when the window rolls. Nothing about the containment depends on the model behaving well.

#Common mistakes

SymptomLikely causeFix
Every action disposes BLOCK after a deployThe policy failed to parse or was never applied; a broken policy denies everything rather than falling open.Run fibric policy validate: it reports parse errors and shows the effective grant per capability.
An action you allowed still blocksA value or predicate constraint failed, or a separate executor rate limit was exhausted. A held single-flight lock causes waiting or a retryable conflict rather than a policy refusal.Read the receipt; the failing constraint is named. Dispositions and their reasons are always receipted, blocked ones included.
A capability acts that you meant to refuseAnother matching rule still permits it. Refusal by omission works only when no matching permission remains; an unsupported explicit veto does not override a grant.Remove or constrain the allow. Use fibric policy validate to see every rule that speaks for the capability.
Rate limit consumed faster than expectedCounting distinct actions, not proposals: each allowed action in a window counts once, but retries do not, because DEDUP happens before evaluation.Check fibric receipts tail --decision ALLOW for the window; the count there is the count the limiter saw.
An ALERT action ran twice after approvalA repeated approval, changed key, independent writer, or ambiguous vendor result may be involved. The intended approval path retains the original key, but that alone does not establish what the vendor applied.Compare receipt ids, action keys, and downstream records. Reconcile the actual effect before retrying or approving again.
Policy references a capability the operator lacksTypo in the capability name, or the connector serving it was unbound from the role.fibric policy validate --against flags rules that match nothing the operator declares; fibric capabilities ls shows what is bound.

#Keep going