← back to indexbid_amendment_arrives

Bid amendment arrives risk 3 · mediumBid & specreflexion on

workflow_type: bid_amendment_arrives · owner: — · contract v2

New amendment to an existing bid. Cascade: diff against prior amendment, re-cost changed lines, regenerate affected spec sheets, update bid hub UI, surface deltas, deadline tracker update.

0 · Visual flow archify workflow graph (6 lanes: trigger → context → HITL → fan-out → post → verify)

Workflow flow
01 / Trigger 02 / Context + preconditions 03 / HITL gate (Mike approves) 04 / Fan-out cascade 05 / Post actions (log_run + reflexion + events) 06 / Verify (SQL / R2 / HTTP checks) How this workflow gets kicked off. Could be a chat-tool invocation, a cron tick, an inbound event (e.g. price.changed), or Mike clicking 'execute' from an admin page. TRIGGER kind: event sources: email_intake, manual_upload, portal_webhook invoker: Mike (single-admin) risk_level: 3i Manual Mike invokes risk 3 Before deciding anything, pull related data from D1 (the local mirror of NetSuite). Each query loads a slice of the entity's current state so the AI and Mike can review before any writes happen. LOAD CONTEXT (D1 queries before fan-out) bid: SELECT * FROM bids WHERE id=? prior_lines: SELECT * FROM bid_lines WHERE bid_id=? prior_amendment: SELECT max(amendment_number) FROM bid_amendments WHERE bid_id=?i Load context 3 D1 queries Safety checks that must pass before any writes. 'block' severity halts the run; 'warn' surfaces a warning but continues. Without these, a bad input could cascade into NetSuite. PRECONDITIONS (checked before fan-out) [block] bid_active: bid.status IN ('open','pending_submission') [warn] amendment_sequential: amendment_number = prior_amendment + 1i Preconditions 2 checks The HITL (Human-In-The-Loop) gate. The workflow stages a proposed_action and waits for Mike to approve in /proposed-actions.html. Only fires when risk_level >= 3. This is the invariant: no NS write happens without Mike's go-ahead. HITL GATE (Mike approves before fan-out) action_type: workflow_bid_amendment_arrives entity_ref: workflow:bid_amendment_arrives:run_<run_id> approver: mike (single-admin) risk_gate: >= 3 (this workflow = 3) approval window: typical <= 60 min envelope: proposed_actions row staged by runneri Mike approves stage_proposed_action risk ≥ 3 gate Write to the local D1 mirror (the read-side cache of NetSuite). Used for derived data and platform state. STUB today - per-tool d1_write logic lives in chat_tools/impls.ts. FAN-OUT #update_bid_lines -> D1: bid_lines kind: d1_write op: UPDATE bid_lines for changed entries op: INSERT bid_lines for added entries op: UPDATE bid_lines SET deleted_at=now for removed entries status: REAL (src/lib/workflow_runner.ts)i update_bid_lines d1_write STUB Fire an HTTP request to another endpoint (often a self-fetch to /api/). STUB today - runner doesn't yet make the call. FAN-OUT #regen_specs -> HTTP POST /api/spec/regenerate kind: http_call if: any spec referenced by changed lines status: REAL (src/lib/workflow_runner.ts)i regen_specs http_call STUB Wipe one or more KV cache keys so the next read pulls fresh data instead of stale cache. Real implementation - runs synchronously. FAN-OUT #hub_cache_bust -> KV: 2 keys kind: kv_invalidate key: hub:nycdoe:bid_?bid_id key: hub:bids:summary status: REAL (src/lib/workflow_runner.ts)i hub_cache_bust kv_invalidate REAL Always-runs at the end of every workflow execution: writes a row to workflow_run_log with status, duration, step counts, and errors. Real implementation. POST ACTION: log_run -> D1: workflow_run_log fields: run_id, workflow_type, status, started_at, completed_at, summary_json source: runner automatic (always)i log_run workflow_run_log REAL Writes an entry to reflexion_log so the AI 'remembers' what happened. Only fires if the contract has reflexion_enabled=1. Future workflows can search this log for prior context. Real implementation. POST ACTION: reflexion -> D1: reflexion_log tags: bid_amendment_arrives reflexion_enabled: True fields: run_id, narrative, tags source: runner automatic (when reflexion_enabled=1)i reflexion reflexion_log REAL Fires a workflow.completed / workflow.partial / workflow.failed event into the event ledger so downstream subscriptions can react. Uses an idempotency_key so producer retries collapse. Real implementation (R564). POST ACTION: event -> Event ledger (recordEvent) types: workflow.completed | workflow.partial | workflow.failed idempotency_key per run_id source: runner automatici event workflow.completed REAL A post-execution sanity check. The runner stages this with status='pending'; the verify-scheduler cron (every :08 and :38 hourly) wakes up after the configured window (e.g. +24h) and executes the sql_check, then flips status to pass/fail/timeout. Real implementation (R564). VERIFY: lines_updated window: 5s sql_check: SELECT COUNT(*) FROM bid_lines WHERE bid_id=? AND updated_at > ? scheduler: verify cron @ :08/:38 (R563) result row: workflow_verify_resultsi lines_updated ≤60m A post-execution sanity check. The runner stages this with status='pending'; the verify-scheduler cron (every :08 and :38 hourly) wakes up after the configured window (e.g. +24h) and executes the sql_check, then flips status to pass/fail/timeout. Real implementation (R564). VERIFY: hub_cache_busted window: 60s scheduler: verify cron @ :08/:38 (R563) result row: workflow_verify_resultsi hub_cache_busted ≤60m Legend User UI Agent logic Policy Tool action Context / trace
Open standalone archify diagram (export PNG / SVG) →

1 · Trigger FIRES WHEN…

kind
event
sources
["email_intake","manual_upload","portal_webhook"]

2 · Inputs required

namerequiredtype / hint
bid_idrequired—
amendment_numberrequired—
amendment_doc_r2_keyrequired—
received_atrequired—

3 · Context loaded D1 queries run before fan-out

name
bid
tables
bids
SELECT
  *
  FROM bids
  WHERE id=?
name
prior_lines
tables
bid_lines
SELECT
  *
  FROM bid_lines
  WHERE bid_id=?
name
prior_amendment
tables
bid_amendments
SELECT
  max(amendment_number)
  FROM bid_amendments
  WHERE bid_id=?

4 · Preconditions checked before any fan-out

checkruleseverity
bid_activebid.status IN ('open','pending_submission')block
amendment_sequentialamendment_number = prior_amendment + 1warn

5 · HITL gate

Risk level 3 ≥ 3 — runner stages a proposed_actions row before fan-out runs. Mike must approve in proposed-actions.html before any side-effect step executes (real or stub).

action_type
workflow_bid_amendment_arrives (proposal envelope)
entity_ref
workflow:bid_amendment_arrives:run_<run_id>
approver
mike (single-admin)

6 · Fan-out targets 3 total · 1 real · 2 stub

#1update_bid_lines d1_write STUB

operations
["UPDATE bid_lines for changed entries","INSERT bid_lines for added entries","UPDATE bid_lines SET deleted_at=now for removed entries"]
stub — not yet implemented in src/lib/workflow_runner.ts (kind d1_write hits the placeholder branch at line ~340 and emits step status 'stub'). Documented intent only.

#2regen_specs http_call STUB

method
POST
path
/api/spec/regenerate
condition (if)
any spec referenced by changed lines
stub — not yet implemented in src/lib/workflow_runner.ts (kind http_call hits the placeholder branch at line ~340 and emits step status 'stub'). Documented intent only.

#3hub_cache_bust kv_invalidate REAL

keys
hub:nycdoe:bid_?bid_id
hub:bids:summary

7 · Post actions declared + runner-automatic

idactionsource
runner_log_runINSERT into workflow_run_log (run_id, workflow_type, status, started_at, completed_at, summary_json)runner automatic
runner_reflexionINSERT into reflexion_log (tags=bid_amendment_arrives, run_id, narrative)runner automatic (reflexion_enabled=1)
log_runINSERT workflow_runsdeclared in contract
reflexionINSERT reflexion_log with tags=bid_amendment,bid_id:?declared in contract

8 · Verify checks written to workflow_verify_results (pending — verify cron not yet wired)

name
lines_updated
SELECT
  COUNT(*)
  FROM bid_lines
  WHERE bid_id=?
  AND updated_at > ?
name
hub_cache_busted

9 · Retry policy

max_attempts
3
backoff
exponential
base_ms
1000
max_ms
30000
alert_on_final_failure
true

10 · What changes when this workflow runs aggregated side effects

systemtable / resourceactionstatussource
KV (CACHE)hub:nycdoe:bid_?bid_idinvalidateREALfan-out #3 (hub_cache_bust)
KV (CACHE)hub:bids:summaryinvalidateREALfan-out #3 (hub_cache_bust)
D1workflow_run_logINSERT (run summary)REALrunner automatic
D1reflexion_logINSERT (tags=bid_amendment_arrives)REALrunner automatic
Eventworkflow.completed (or workflow.failed)fireREALrunner automatic
D1workflow_verify_resultsINSERT pending × 2REALrunner verify staging
D1proposed_actionsINSERT (HITL gate envelope)REALrunner HITL gate
D1unknownwriteSTUBfan-out #1 (update_bid_lines)
Worker HTTPPOST /api/spec/regenerateinvokeSTUBfan-out #2 (regen_specs)