Risk Classification Rules

Every Tool spec in Fascia is evaluated by the Risk Engine before deployment. The Risk Engine analyzes the flow graph, identifies unsafe patterns, and assigns a risk level that determines whether the tool can be deployed.

Risk Levels

Green -- Safe to Deploy

A tool receives a Green risk level when all of the following conditions are true:

• Only Entity actions are used (create, update, transition, soft-delete) -- no raw SQL writes.
• An explicit transaction boundary node exists around all write operations.
• An idempotency key is present for all non-read operations.
• No unbounded queries -- all read nodes include pagination or explicit limits.
• No external calls are present, or all external calls are placed outside transaction boundaries.

Deployment: Allowed. Green tools can be deployed without any additional steps.

Yellow -- Requires Acknowledgment

A tool receives a Yellow risk level when any of the following conditions are detected:

Condition	Description
External call in state transition	A payment, email, sms, or httpRequest node is used during an entity status transition.
Missing retry on external node	An external node (payment, email, sms, httpRequest) does not have a retry node configured.
High row impact	A single write operation affects more than 100 rows.
Missing idempotency key	A write operation does not have an idempotency key derived from its input.
Read without explicit limit	A read node has no pagination or row limit, risking a full table scan.
Missing timeout on external node	An external node does not have a timeout node configured.

Deployment: Allowed with acknowledgment. The user must review and explicitly acknowledge each Yellow warning. Acknowledgments are recorded in the audit log.

Red -- BLOCKED

A tool receives a Red risk level when any of the following conditions are detected:

Condition	Description
Raw write	SQL executed without the Entity abstraction layer (bypassing validation and audit).
Unbounded update	An UPDATE operation without a WHERE clause or without a row limit.
Payment without rollback	A payment node with no compensation or rollback mechanism for failure.
Missing transaction boundary	Write operations exist outside of an explicit transaction boundary node.
Hard delete	An attempt to permanently delete data instead of using soft-delete (deletedAt timestamp).
External call with side effects inside transaction	A payment, email, sms, or httpRequest node with side effects is placed inside a transaction boundary. If the transaction rolls back, the external side effect cannot be undone.
Write without status machine	A write node targets an entity that does not define a status machine.
Circular dependency	The flow graph contains a cycle (not a valid DAG).

Deployment: BLOCKED. Red risk tools cannot be deployed under any circumstances. The issues must be resolved before the tool can proceed through risk analysis. Red signals cannot be acknowledged or dismissed.

Auto-Fix Suggestions

When the Risk Engine detects a risk signal, it provides specific remediation guidance:

Signal	Suggested Fix
Missing transaction	Wrap all write nodes in a transaction boundary node.
External call in transaction	Move the external call outside the transaction boundary. Add a compensation flow to handle rollback scenarios.
Missing retry	Add a retry node with a maximum of 3 attempts and exponential backoff.
Unbounded update	Add a WHERE condition to scope the update, or add an explicit row limit.
Payment without rollback	Add a compensation flow (e.g., automatic refund on downstream failure).
Missing idempotency	Add an idempotencyKey derived from a hash of the input fields.
Hard delete	Convert to a soft delete by setting the deletedAt timestamp instead of removing the row.
Missing timeout	Add a timeout node with a 30-second default around the external call.

These suggestions are presented in Chat Studio and Flow Studio during the design phase. The Safety Agent can apply many of these fixes automatically when the user approves.

Risk Escalation

Level	Deployment Policy	User Action Required
Green	Deploy freely	None
Yellow	Deploy after acknowledgment	User must review and accept each warning. Acknowledgment is logged in the audit trail.
Red	Deployment blocked	User must fix all Red signals. Red signals cannot be acknowledged or dismissed -- they must be structurally resolved.

Evaluation Flow

The Risk Engine evaluates a Tool spec in this order:

1. Structural validation -- Verify the flow graph is a valid DAG with a single start node and no orphan nodes.
2. Red signal scan -- Check for any Red conditions. If found, the tool is immediately classified as Red.
3. Yellow signal scan -- Check for any Yellow conditions. If found (and no Red signals exist), the tool is classified as Yellow.
4. Green confirmation -- If no Red or Yellow signals are detected, the tool is classified as Green.

The risk level is recorded in the riskLevel field of the Tool spec. This field is set by the Risk Engine and cannot be manually overridden.

Examples

Green Tool

A simple CRUD tool that reads data, writes within a transaction, and has an idempotency key:

[Read Customer] --> [Transaction] --> [Write Order] --> [Assert Invariant]

• All writes inside a transaction boundary.
• No external calls.
• Idempotency key derived from input.
• Read has explicit limit.

Result: Green -- safe to deploy.

Yellow Tool

A reservation tool that sends a confirmation email without a retry:

[Transaction] --> [Write Reservation] --> [Email Confirmation]

• Write is inside a transaction -- good.
• Email node is outside the transaction -- good.
• Email node has no retry configured -- Yellow signal.
• Email node has no timeout configured -- Yellow signal.

Result: Yellow -- user must acknowledge the missing retry and timeout.

Red Tool

A payment tool that processes a charge inside a transaction:

[Transaction] --> [Write Order] --> [Payment Charge] --> [Commit]

• Payment node is inside the transaction boundary. If the transaction rolls back after the charge succeeds, the payment cannot be reversed automatically.

Result: Red -- deployment blocked. The payment node must be moved outside the transaction with a compensation flow added.

See Also

• Tool Spec Schema -- The riskLevel field and flow graph structure
• Policy Spec Schema -- Policies work alongside risk rules to enforce safety
• System Architecture -- How the Risk Engine fits into the build phase