← back to indexdraft_quote

Draft customer quote risk 3 · mediumCustomer opsreflexion on

workflow_type: draft_quote · owner: — · contract v2

Multi-step quote drafting from natural-language request

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

Part 1 of 2
01 / Trigger 02 / Context + preconditions 03 / HITL gate (Mike approves) 04 / Fan-out (Part 1 of 2) 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: hitl_approval event: proposed_actions row with action_type='price_change' or 'bid_price_update' approved 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) current_pricing: SELECT * FROM pricing_master WHERE customer_id=? AND item_code=? bid_line: SELECT * FROM bid_lines WHERE bid_id=? AND item_code=? vendor_cost: SELECT unit_cost, effective_from FROM vendor_costs WHERE item_code=? ORDER BY e… reflexion: SELECT * FROM reflexion_log WHERE entity_type='customer' AND entity_id=? AND ta…i Load context 4 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) [warn] vendor_cost_recency: effective_from > datetime('now','-7 days') [block] new_price_positive: new_price > 0 [warn] margin_floor: (new_price - cost_basis) / new_price * 100 >= customer_program.margin_floori Preconditions 3 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_draft_quote entity_ref: workflow:draft_quote: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 Pushes a write back to NetSuite via the NS_PUSH_QUEUE. The push is staged in ns_pending_pushes first and only flips to 'applied' after NS confirms. STUB today - the runner logs intent but doesn't enqueue yet. FAN-OUT #write_ns -> NS_PUSH_QUEUE: itempricing kind: ns_push queue: NS_PUSH_QUEUE on_failure: retry_3_then_alert record_type: itempricing status: REAL (src/lib/workflow_runner.ts)i write_ns ns_push STUB 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 #write_d1 -> D1: pricing_master kind: d1_write parallel_with: write_ns op: UPDATE pricing_master SET case_price=?, cost_basis=?, margin_pct=?, updated_a… op: INSERT INTO pricing_history (customer_id,item_code,case_price,changed_at,chan… status: REAL (src/lib/workflow_runner.ts)i write_d1 d1_write STUB 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 if: bid_id present op: UPDATE bid_lines SET proposed_price=?, updated_at=now WHERE bid_id=? AND item… 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/<something>). STUB today - runner doesn't yet make the call. FAN-OUT #regen_bid_artifact -> HTTP POST /api/bids/:bid_id/regenerate kind: http_call if: bid_id present AND artifact_r2_key exists status: REAL (src/lib/workflow_runner.ts)i regen_bid_artifact 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 #invalidate_hub_cache -> KV: 2 keys kind: kv_invalidate if: bid_id IN active_hub_bids key: hub:nycdoe:bid_?bid_id key: hub:nycdoe:summary status: REAL (src/lib/workflow_runner.ts)i invalidate_hub_cache kv_invalidate REAL Set a follow-up flag on a row (e.g., 'needs_review') so a downstream cron or human picks it up later. STUB today. FAN-OUT #spec_sheet_check -> flag: INSERT proposed_actions (action_type=spec_review_needed, entity_ref=?sku) kind: flag if: abs(price_change_pct) > 5 action: INSERT proposed_actions (action_type=spec_review_needed, entity_ref=?sku) status: STUB (src/lib/workflow_runner.ts)i spec_sheet_check flag STUB 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: draft_quote 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: ns_reflects_new_price window: 15m sql_check: SELECT case_price FROM pricing_customer_prices WHERE customer_id=? AND item_cod… scheduler: verify cron @ :08/:38 (R563) result row: workflow_verify_resultsi ns_reflects_new_price ≤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 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: d1_pricing_master_upd… scheduler: verify cron @ :08/:38 (R563)i d1_pricing_master_upd… ≤60m Legend User UI Agent logic Policy Tool action Context / trace
Open standalone archify diagram (export PNG / SVG) →
Part 2 of 2
01 / Trigger 02 / Context + preconditions 03 / HITL gate (Mike approves) 04 / Fan-out (Part 2 of 2) 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: hitl_approval event: proposed_actions row with action_type='price_change' or 'bid_price_update' approved 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) current_pricing: SELECT * FROM pricing_master WHERE customer_id=? AND item_code=? bid_line: SELECT * FROM bid_lines WHERE bid_id=? AND item_code=? vendor_cost: SELECT unit_cost, effective_from FROM vendor_costs WHERE item_code=? ORDER BY e… reflexion: SELECT * FROM reflexion_log WHERE entity_type='customer' AND entity_id=? AND ta…i Load context 4 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) [warn] vendor_cost_recency: effective_from > datetime('now','-7 days') [block] new_price_positive: new_price > 0 [warn] margin_floor: (new_price - cost_basis) / new_price * 100 >= customer_program.margin_floori Preconditions 3 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_draft_quote entity_ref: workflow:draft_quote: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 Draft an email and stage it as a proposed_action for Mike's review. The email is NOT sent - only drafted + queued. STUB today. FAN-OUT #customer_notify -> email draft kind: hitl_email_draft if: customer has open quote AND price_increase tool: propose_email_to_customer status: STUB (src/lib/workflow_runner.ts)i customer_notify hitl_email_draft STUB 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: draft_quote 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: ns_reflects_new_price window: 15m sql_check: SELECT case_price FROM pricing_customer_prices WHERE customer_id=? AND item_cod… scheduler: verify cron @ :08/:38 (R563) result row: workflow_verify_resultsi ns_reflects_new_price ≤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 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: d1_pricing_master_upd… scheduler: verify cron @ :08/:38 (R563)i d1_pricing_master_upd… ≤60m Legend User UI Agent logic Policy Tool action Context / trace
Open standalone archify diagram (export PNG / SVG) →

1 · Trigger FIRES WHEN…

kind
hitl_approval
event
"proposed_actions row with action_type='price_change' or 'bid_price_update' approved"

2 · Inputs required

namerequiredtype / hint
customer_idrequired—
skurequired—
new_pricerequired—
effective_daterequired—
reasoning_textrequired—
bid_idoptional—

3 · Context loaded D1 queries run before fan-out

name
current_pricing
tables
pricing_master
SELECT
  *
  FROM pricing_master
  WHERE customer_id=?
  AND item_code=?
name
bid_line
tables
bid_lines
SELECT
  *
  FROM bid_lines
  WHERE bid_id=?
  AND item_code=?
name
vendor_cost
tables
vendor_costs
SELECT
  unit_cost, effective_from
  FROM vendor_costs
  WHERE item_code=?
  ORDER BY effective_from DESC
  LIMIT 1
name
reflexion
tables
reflexion_log
SELECT
  *
  FROM reflexion_log
  WHERE entity_type='customer'
  AND entity_id=?
  AND tags LIKE '%price%'

4 · Preconditions checked before any fan-out

checkruleseverity
vendor_cost_recencyeffective_from > datetime('now','-7 days')warn
new_price_positivenew_price > 0block
margin_floor(new_price - cost_basis) / new_price * 100 >= customer_program.margin_floorwarn

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_draft_quote (proposal envelope)
entity_ref
workflow:draft_quote:run_<run_id>
approver
mike (single-admin)

6 · Fan-out targets 7 total · 1 real · 6 stub

#1write_ns ns_push STUB

NS record_type
itempricing
fields
{"customer":"?customer_id","item":"?sku","price":"?new_price","effective":"?effective_date"}
queue
NS_PUSH_QUEUE
on_failure
retry_3_then_alert
stub — not yet implemented in src/lib/workflow_runner.ts (kind ns_push hits the placeholder branch at line ~340 and emits step status 'stub'). Documented intent only.

#2write_d1 d1_write STUB

parallel_with
write_ns
operations
["UPDATE pricing_master SET case_price=?, cost_basis=?, margin_pct=?, updated_at=now WHERE id=?","INSERT INTO pricing_history (customer_id,item_code,case_price,changed_at,changed_by) VALUES (?,?,?,now,?)"]
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.

#3update_bid_lines d1_write STUB

operations
["UPDATE bid_lines SET proposed_price=?, updated_at=now WHERE bid_id=? AND item_code=?"]
condition (if)
bid_id present
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.

#4regen_bid_artifact http_call STUB

method
POST
path
/api/bids/:bid_id/regenerate
produces
["updated bid PDF","updated price-quotes tab"]
condition (if)
bid_id present AND artifact_r2_key exists
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.

#5invalidate_hub_cache kv_invalidate REAL

keys
hub:nycdoe:bid_?bid_id
hub:nycdoe:summary
condition (if)
bid_id IN active_hub_bids

#6spec_sheet_check flag STUB

action
INSERT proposed_actions (action_type=spec_review_needed, entity_ref=?sku)
condition (if)
abs(price_change_pct) > 5
stub — not yet implemented in src/lib/workflow_runner.ts (kind flag hits the placeholder branch at line ~340 and emits step status 'stub'). Documented intent only.

#7customer_notify hitl_email_draft STUB

tool
propose_email_to_customer
condition (if)
customer has open quote AND price_increase
stub — not yet implemented in src/lib/workflow_runner.ts (kind hitl_email_draft hits the placeholder branch at line ~340 and emits step status 'stub'). Documented intent only.

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=draft_quote, run_id, narrative)runner automatic (reflexion_enabled=1)
log_runINSERT INTO workflow_runs (workflow_type, status, inputs_json, started_at, finished_at)declared in contract
reflexionINSERT INTO reflexion_log (workflow_run_id, entity_type, entity_id, outcome, tags)declared in contract
customer_profile_touchUPDATE customer_profiles SET last_pricing_event=now WHERE customer_id=?declared in contract

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

name
ns_reflects_new_price
when_to_run
15 min after run
SELECT
  case_price
  FROM pricing_customer_prices
  WHERE customer_id=?
  AND item_code=?
  AND last_synced_at > datetime('now','-15 minutes')
name
hub_cache_busted
name
d1_pricing_master_updated
SELECT
  case_price
  FROM pricing_master
  WHERE customer_id=?
  AND item_code=?

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 #5 (invalidate_hub_cache)
KV (CACHE)hub:nycdoe:summaryinvalidateREALfan-out #5 (invalidate_hub_cache)
D1workflow_run_logINSERT (run summary)REALrunner automatic
D1reflexion_logINSERT (tags=draft_quote)REALrunner automatic
Eventworkflow.completed (or workflow.failed)fireREALrunner automatic
D1workflow_verify_resultsINSERT pending × 3REALrunner verify staging
D1proposed_actionsINSERT (HITL gate envelope)REALrunner HITL gate
NetSuite (via NS_PUSH_QUEUE)itempricingpushSTUBfan-out #1 (write_ns)
D1unknownwriteSTUBfan-out #2 (write_d1)
D1unknownwriteSTUBfan-out #3 (update_bid_lines)
Worker HTTPPOST /api/bids/:bid_id/regenerateinvokeSTUBfan-out #4 (regen_bid_artifact)
D1flags / status fieldset =STUBfan-out #6 (spec_sheet_check)
D1proposed_actionsINSERT (email draft via propose_email_to_customer)STUBfan-out #7 (customer_notify)