Migrate from scripts and point automations

Most operations run on an accretion of cron jobs, zaps, and one-off scripts. Each works until it does not, and none can say afterward what it did or why. This guide maps those automations onto Fibric's parts, walks one real cron job through the rewrite, and lays out an incremental cutover that keeps the old path running as a fallback until the new one has earned trust.

#What a script is missing

A script or a zap is a trigger, some logic, and a side effect, fused into one unit. That fusion is what makes it fragile: the retry loop is hand-rolled, the mutex is a lockfile that a crashed run leaves behind, the audit trail is whatever echo statements survived the last edit, and nothing stands between the logic and the side effect. When the logic is wrong, the side effect happens anyway. The 657-message flood that shaped the Fibric kernel was exactly this failure class: an ungoverned loop with direct access to a side effect, repeating until someone noticed.

Fibric pulls those fused parts back apart. The trigger becomes an event envelope. The logic becomes an operator that proposes rather than acts. The side effect becomes a capability that only a deterministic executor can invoke, under a fail-closed trust policy. The retry and mutex problems stop being your code at all: they are the executor's idempotency_key and single-flight entity_key primitives. And every action, taken or refused, leaves a receipt.

#Mapping automation parts to Fibric parts

Every migration starts with the same inventory. For each automation, name its trigger, its logic, its side effects, and its safety improvisations, then read each one across this table.

#A worked migration: the nightly stale-order hold

#The original script

A representative specimen: a cron job that runs at 02:00, finds open orders that have not shipped in five days, puts them on hold, and pings a channel. It has a lockfile, a hand-rolled retry, and no memory of what it did last week.

#!/usr/bin/env bash
# crontab: 0 2 * * *  /opt/jobs/hold-stale-orders.sh
set -e
exec 9>/var/lock/hold-stale.lock; flock -n 9 || exit 0   # the mutex

STALE=$(curl -s "$ORDERS_API/orders?status=open&age_gt=5d" | jq -r '.[].id')

for id in $STALE; do
  for i in 1 2 3; do                                    # the retry loop
    curl -sf -X POST "$ORDERS_API/orders/$id/hold" && break
    sleep 5
  done
  echo "held $id" >> /var/log/hold-stale.log            # the audit trail
done

curl -s -X POST "$CHAT_WEBHOOK" -d "{\"text\": \"held: $STALE\"}"

Read it against the mapping table: a cron trigger, a lockfile mutex, a retry loop that can double-apply if the first attempt succeeded but the response was lost, a log file as the only record, and a webhook call that fires even when $STALE is empty. Each line has a destination in the rewrite.

#The operator

The logic becomes a proposal. The operator senses through orders.read, decides which orders are stale, and proposes holds. It does not call the order API, and it does not notify anyone; it proposes that those things happen.

import { defineOperator } from "@fibric/sdk";

export default defineOperator({
  name: "stale-order-hold",
  capabilities: ["orders.read", "orders.hold", "notify.send"],
  goal: "Hold open orders that have not shipped in five days, and report what was held.",
  trigger: { source: "cron", schedule: "0 2 * * *" },   // the crontab line, as an envelope trigger

  async run(ctx) {
    const stale = await ctx.orders.read({ status: "open", ageGreaterThan: "5d" });
    // the script body becomes a proposal; execution belongs to the executor
    return ctx.propose(stale.map(o => ({
      capability: "orders.hold",
      args: { id: o.id },
    })));
  },
});

The lockfile and the retry loop have no equivalent lines. Each proposed hold carries an entity_key (the order) and an idempotency_key (stale-order-hold:SO-11290:hold); the executor serializes per entity and collapses repeats to DEDUP. If the 02:00 run crashes midway, the 02:00 run tomorrow re-proposes everything and only the unapplied holds execute.

#The policy, propose-only first

The initial policy grants the operator nothing unattended. Every proposal is disposed as ALERT: it lands in the human approval queue instead of executing silently, and every disposition leaves a receipt you can compare against what the legacy script did that same night.

# fail-closed: anything not listed is refused
version: 1
allow:
  - orders.hold
  - notify.send
decision: ALERT            # every action pauses for human confirmation
limits:
  orders.hold:
    max_per_run: 50       # cap the blast radius of any one run
    single_flight: by_order_id
require_receipt: true

#The first shadow run

Before even the ALERT stage, run the operator in shadow: a --dry-run prints the exact ExecutionPlan it would submit, including every idempotency key, and executes nothing. Compare its list against what the legacy script held that night.

fibric operators deploy ./stale-order-hold.ts --policy ./policy.yaml
fibric operators run stale-order-hold --dry-run

Parity on one night proves little; parity across a few weeks of nights, including the odd ones (empty result sets, upstream outages, month-end volume), is what earns the next rung.

#The incremental cutover ladder

Cutover is a ladder, not a switch. Each rung widens what the operator may do unattended, and each promotion is justified by receipts from the rung below. The legacy automation keeps running until the final rung.

#Rung 1: shadow

The operator runs propose-only: --dry-run by hand, or deployed with a policy whose only effect is producing an ALERT queue nobody approves from yet. The legacy path remains the only thing taking action. Your job on this rung is comparison: does the operator propose the same set of actions the script performs, night after night? Divergence in either direction is a finding, sometimes the operator is wrong, and sometimes it has caught a bug the script has had for years.

#Rung 2: ALERT-gated

The new path starts acting, with a human confirming each action from the approval queue, and the legacy cron job is disabled for this automation. Actions are slow on this rung by design; what you are buying is a supervised history. The ALERT receipts, what was proposed, what the human decided, how often the human said no, are the evidence that decides the next promotion. See Trust tiers for how the escalation queue works and the guardrails guide for promotion criteria.

#Rung 3: ALLOW within limits

Change the policy decision to ALLOW, keeping the caps: max_per_run, maxValue where money is involved, single-flight per entity. The operator now runs unattended inside a bounded envelope, and anything outside the envelope still disposes as BLOCK. Monitor the veto rate and the dedup rate as described in Monitor operators in production; a stable veto rate on this rung is the signature of a healthy migration.

#Rung 4: old path off

Only when the operator has run unattended through enough real variation, including at least one upstream incident, does the legacy automation get decommissioned, per the checklist below. Until then it stays installed and pausable, because the honest failure mode of any migration is discovering the new path's gap three weeks in and needing the old one back in minutes.

One transition deserves care: moving from rung 1 to rung 2 is the moment responsibility changes hands. Disable the legacy cron entry before the first approval is granted, in the same change window, so there is never an interval where both paths are acting on the same entities.

#Decommissioning the old path

Decommissioning is its own step, done deliberately after rung 3 has held. Work through the list per automation:

• Confirm the evidence. The operator has run unattended for an agreed period (weeks, not days) with a stable veto rate, no unexplained BLOCK receipts, and at least one upstream incident weathered correctly.
• Remove the trigger, keep the body. Delete the crontab entry or disable the zap first, and keep the script itself in version control. The trigger is the dangerous part; the code is the documentation of prior behavior.
• Revoke the script's credentials. The API keys and webhook URLs the script used should stop working. A decommissioned automation with live credentials is a resurrection waiting to happen, usually on the wrong day.
• Redirect its consumers. Anything that read the script's log file or depended on its side-effect timing now reads receipts, via fibric receipts export or the Receipts API.
• Record the mapping. Note which operator replaced which automation and when. Six months later, this is the answer to "what happened to the thing that used to hold stale orders."
• Retire the host last. Only after every automation on a box is migrated does the box itself go. Shared cron hosts accumulate undocumented passengers; check crontab -l for every user before assuming it is empty.

#Troubleshooting

#Keep going

• Monitor operators in production: the signals that tell you a migrated operator is healthy.
• Single-flight & idempotency: the primitives that replaced your lockfile and retry loop.
• Trust tiers: ALLOW, ALERT, and BLOCK in full, including the approval queue.
• The event envelope: the shape every trigger, cron tick included, travels in.
• Build an order-risk operator: a complete operator of the kind most script migrations end up as.
• Work in the sandbox: rehearse a migration end to end before touching the live system.