← back to indexcustomer_quote

Customer quote (canonical) risk 3 · mediumCustomer opsreflexion on

workflow_type: customer_quote · owner: — · contract v2

Mike drafts a customer quote via chat. Cascade: NS quote record, proposed_pricing → pricing_master, customer email draft (HITL), AR/credit forecast update, quote PDF generation + R2 store.

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: hitl_approval event: proposed_actions approved with action_type=quote_draft 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) customer: SELECT * FROM customers WHERE id=? customer_programs: SELECT * FROM customer_programs WHERE customer_id=? AND status='active' AND del… current_pricing: SELECT item_code, case_price, cost_basis, margin_pct FROM pricing_master WHERE … open_quotes: SELECT id, generated_at FROM quotes WHERE customer_id=? AND lifecycle_status IN…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) [block] customer_exists: customer.id IS NOT NULL [warn] items_resolved: all item_codes match spec_items.item_code [block] customer_not_on_hold: customer.entitystatus != 'hold' [warn] margin_floor: all line.margin_pct >= 15i Preconditions 4 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_customer_quote entity_ref: workflow:customer_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 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_quote -> D1: multiple kind: d1_write op: INSERT quotes op: INSERT quote_lines (batch) status: REAL (src/lib/workflow_runner.ts)i write_quote 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 #render_pdf -> HTTP POST /api/quote/pdf kind: http_call if: include_pdf status: REAL (src/lib/workflow_runner.ts)i render_pdf http_call STUB 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 #send_email -> email draft kind: hitl_email_draft tool: send_quote_to_customer status: STUB (src/lib/workflow_runner.ts)i send_email hitl_email_draft STUB 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 #ns_push -> NS_PUSH_QUEUE: estimate kind: ns_push queue: NS_PUSH_QUEUE on_failure: retry_3_then_alert record_type: estimate status: REAL (src/lib/workflow_runner.ts)i ns_push 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 #ar_forecast_touch -> D1: customer_profiles kind: d1_write op: UPDATE customer_profiles SET last_quote_event=now WHERE customer_id=? status: REAL (src/lib/workflow_runner.ts)i ar_forecast_touch d1_write 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: customer_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: quote_persisted window: 2s sql_check: SELECT id, lifecycle_status FROM quotes WHERE id=? scheduler: verify cron @ :08/:38 (R563) result row: workflow_verify_resultsi quote_persisted ≤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: pdf_stored window: 10s scheduler: verify cron @ :08/:38 (R563) result row: workflow_verify_resultsi pdf_stored ≤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: email_sent window: 30s sql_check: SELECT id FROM outbound_email_log WHERE related_quote_id=? ORDER BY sent_at DES… scheduler: verify cron @ :08/:38 (R563) result row: workflow_verify_resultsi email_sent ≤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 approved with action_type=quote_draft"

2 · Inputs required

namerequiredtype / hint
customer_idrequired—
item_codes[]required—
school_yearrequired—
quote_idoptional—
catalogoptional—
include_pdfoptional—

3 · Context loaded D1 queries run before fan-out

name
customer
tables
customers
SELECT
  *
  FROM customers
  WHERE id=?
name
customer_programs
tables
customer_programs
SELECT
  *
  FROM customer_programs
  WHERE customer_id=?
  AND status='active'
  AND deleted_at IS NULL
name
current_pricing
tables
pricing_master
SELECT
  item_code, case_price, cost_basis, margin_pct
  FROM pricing_master
  WHERE customer_id=?
  AND item_code IN (?)
  AND school_year=?
name
open_quotes
tables
quotes
SELECT
  id, generated_at
  FROM quotes
  WHERE customer_id=?
  AND lifecycle_status IN ('draft','proposed','sent')
  ORDER BY generated_at DESC
  LIMIT 3

4 · Preconditions checked before any fan-out

checkruleseverity
customer_existscustomer.id IS NOT NULLblock
items_resolvedall item_codes match spec_items.item_codewarn
customer_not_on_holdcustomer.entitystatus != 'hold'block
margin_floorall line.margin_pct >= 15warn

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

6 · Fan-out targets 5 total · 0 real · 5 stub

#1write_quote d1_write STUB

operations
["INSERT quotes","INSERT quote_lines (batch)"]
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.

#2render_pdf http_call STUB

method
POST
path
/api/quote/pdf
produces
["R2 artifact at quotes/{id}.pdf"]
condition (if)
include_pdf
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.

#3send_email hitl_email_draft STUB

tool
send_quote_to_customer
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.

#4ns_push ns_push STUB

NS record_type
estimate
queue
NS_PUSH_QUEUE
payload
quote_with_lines
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.

#5ar_forecast_touch d1_write STUB

operations
["UPDATE customer_profiles SET last_quote_event=now WHERE customer_id=?"]
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.

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=customer_quote, run_id, narrative)runner automatic (reflexion_enabled=1)
log_runINSERT workflow_runsdeclared in contract
reflexionINSERT reflexion_log with tags=quote,customer:?,school_year:?declared in contract

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

name
quote_persisted
SELECT
  id, lifecycle_status
  FROM quotes
  WHERE id=?
name
pdf_stored
name
email_sent
SELECT
  id
  FROM outbound_email_log
  WHERE related_quote_id=?
  ORDER BY sent_at DESC
  LIMIT 1

9 · Retry policy

max_attempts
3
backoff
exponential
base_ms
1500
max_ms
30000
alert_on_final_failure
true

10 · What changes when this workflow runs aggregated side effects

systemtable / resourceactionstatussource
D1workflow_run_logINSERT (run summary)REALrunner automatic
D1reflexion_logINSERT (tags=customer_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
D1unknownwriteSTUBfan-out #1 (write_quote)
Worker HTTPPOST /api/quote/pdfinvokeSTUBfan-out #2 (render_pdf)
D1proposed_actionsINSERT (email draft via send_quote_to_customer)STUBfan-out #3 (send_email)
NetSuite (via NS_PUSH_QUEUE)estimatepushSTUBfan-out #4 (ns_push)
D1unknownwriteSTUBfan-out #5 (ar_forecast_touch)