DNA OS — Developer Portal

system

ภาพรวมสถาปัตยกรรมระบบ

Architecture Overview

DNA OS แบ่งเป็น 8 เลเยอร์ที่พึ่งพาได้ทางเดียว (UI → API → Engine → Core → Services) โดยมี Registry เป็นแหล่งความจริงกลางที่ทุกเลเยอร์อ่าน

app/ (UI)
  └─ app/api/ (route handler)
       └─ engines/validation/dispatcher.ts  ── registry/command-registry.json
            └─ engines/*                    ── core/config-loader ── app_configs
                 └─ services/supabase/*      ── PostgreSQL + RLS
                      └─ presenter/* (สรุปผล)
registry/*  ← อ่านโดยทุกชั้น ห้ามเขียนจาก runtime

{
  "version": 1,
  "command": "debt.list",
  "args": {}
}

system

ลำดับการทำงานของคำขอ

Request Lifecycle

ทุกคำขอเดินผ่าน 7 ขั้นตอนเดียวกัน ตั้งแต่ auth guard จนถึง presenter ทำให้ตรวจสอบย้อนกลับได้ด้วย request_id เดียว

POST /api/v1/query
  header  X-DNA-Token: <token>
  body    { "command": "debt.list", "args": {} }
    ↓
services/supabase/api-tokens.ts   validateApiToken()        → token record
core/auth/session.ts              profiles.role ∈ admin_tier → ผ่าน
engines/authority/session-scope   resolveTokenDataScope()   → company scope
engines/validation/dispatcher.ts  registry gate + Rule 72   → allow (read)
cognitive/debts                   query invoice_debts       → rows
app/api/v1/query/route.ts         JSON + request_id         → 200

system

แผนที่ Registry กลาง

Central Registry Map

Registry แต่ละไฟล์มีเจ้าของชัดเจนและมี endpoint หรือ runtime เดียวที่อ่านมัน AI agent ใช้ตารางนี้เพื่อเลือกแหล่งข้อมูลก่อนเขียนโค้ดเชื่อมต่อ

// ภายใน repository
import commandRegistry from "@/registry/command-registry.json";

const readCommands = Object.entries(commandRegistry.commands)
  .filter(([, c]) => !c.requires_confirmation)
  .map(([name, c]) => ({ name, owner: c.owner, output: c.output }));

// ภายนอกรายการคำสั่งทั้งหมด (tool schema พร้อมใช้กับ LLM)
const spec = await fetch("/api/v1/spec").then((r) => r.json());

engines

เครื่องยนต์คำนวณราคา

Pricing Engine

engines/pricing.ts คำนวณต้นทุนสึกหรอ กำไร ค่าธรรมเนียมระบบ ค่าด่วน และ VAT โดยอ่านอัตราทั้งหมดจาก app_configs

wearCost      = fuel_cost × (wear_percent / 100)
totalWithWear = total_cost + wearCost
markup        = totalWithWear × (markup_percent / 100)
systemFee     = totalWithWear × (system_fee_percent / 100)
urgentFee     = is_urgent ? totalWithWear × (urgent_fee_percent / 100) : 0
profit        = markup − systemFee
sellingExVAT  = totalWithWear + markup + urgentFee
vat           = sellingExVAT × vat_rate      // vat_rate เก็บเป็นเศษส่วน เช่น 0.07
sellingPrice  = sellingExVAT + vat
pricePerTrip  = trips > 0 ? sellingPrice / trips : sellingPrice

// PricingInput
{
  "total_cost": 18500,
  "material_cost": 12000,
  "fuel_cost": 6500,
  "trips": 3,
  "is_urgent": true
}

// PricingResult
{
  "wear_cost": 325,
  "selling_price_ex_vat": 22022.5,
  "vat": 1541.58,
  "selling_price": 23564.08,
  "profit": 2536.13,
  "system_fee": 564.75,
  "urgent_fee": 1882.5,
  "price_per_trip": 7854.69,
  "audit": { "engine": "pricing", "input": {}, "rules": {}, "computed": {} }
}

engines

สัญญาของ Dispatcher

Dispatcher Contract

engines/validation/dispatcher.ts เป็นประตูเดียวที่แปลง command เป็นการเรียก engine โดยตรวจ registry และกฎความปลอดภัยก่อนทุกครั้ง

{
  "debt.list": {
    "owner": "cognitive/debts",
    "layer": "cognitive",
    "input": {},
    "output": "InvoiceDebt[]",
    "description": "แสดงรายการหนี้ค้างชำระ (OPEN)",
    "description_th": "แสดงรายการหนี้ที่ยังค้างชำระ (สถานะ OPEN)",
    "requires_confirmation": false
  }
}

// สำเร็จ
{ "ok": true, "command": "debt.list", "user": "owner@example.com", "data": [], "capability": { "owner_module": "cognitive/debts", "capability_ids": [] } }

// ถูกปฏิเสธเพราะต้องยืนยัน
{ "ok": false, "command": "debt.create", "error": "requires human confirmation", "requires_confirmation": true }

api

เรียกคำสั่งธุรกิจ

Runtime Query

POST /api/v1/query คือท่อหลักสำหรับ AI ภายนอกและ connector รับ command พร้อม args แล้วคืนข้อมูลที่ผ่านการตรวจสิทธิ์และขอบเขตข้อมูลแล้ว

curl -X POST https://<host>/api/v1/query \
  -H "Content-Type: application/json" \
  -H "X-DNA-Token: $DNA_OS_API_TOKEN" \
  -d '{"command":"debt.list","args":{}}'

{
  "ok": true,
  "command": "debt.list",
  "user": "owner@example.com",
  "data": [],
  "capability": { "owner_module": "cognitive/debts", "capability_ids": [] }
}

api

Endpoint ค้นหาโครงสร้างระบบ

Discovery Endpoints

ชุด endpoint แบบอ่านอย่างเดียวที่เปิดให้ทุก client ใช้ค้นหา command, module, capability, driver, workflow และกฎรัฐธรรมนูญของระบบ

{
  "schema_version": "1.0",
  "system": "DNA OS",
  "query_endpoint": "/api/v1/query",
  "auth": "Header: X-DNA-Token: <your-token>",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "debt__list",
        "description": "แสดงรายการหนี้ค้างชำระ (OPEN) | layer: cognitive | output: InvoiceDebt[]",
        "parameters": { "type": "object", "properties": {}, "required": [] },
        "_dna_command": "debt.list"
      }
    }
  ]
}

{
  "schema_version": "1.0",
  "capability_registry": {
    "source": "registry/capability-registry.json",
    "version": 1,
    "checksum": "..."
  },
  "composition_plan": null
}

{
  "schema_version": "1.0",
  "source": "registry/module-registry.json",
  "total": 1079,
  "modules": [
    { "path": "engines/pricing.ts", "owner": "engines", "layer": "engines", "purpose_th": "คำนวณราคา", "exports": ["calcPricing"], "status": "active" }
  ]
}

api

การออกและจัดการ API Token

API Token Management

Token ถูกออกโดยผู้ดูแลระบบเท่านั้น ผ่าน endpoint ที่ต้องมี session ระดับ admin tier และผูกกับบัญชีผู้ใช้จริงในระบบ

{
  "tokens": [
    { "id": "...", "label": "contractor-runtime", "scopes": ["read"], "created_at": "2026-11-11T00:00:00Z", "revoked_at": null }
  ]
}

curl -X POST https://<host>/api/admin/api-tokens \
  -H "Content-Type: application/json" \
  --cookie "session=<admin-session>" \
  -d '{"label":"contractor-runtime","scopes":["read"]}'

{
  "token": {
    "id": "...",
    "label": "contractor-runtime",
    "scopes": ["read"],
    "token": "dna_xxxxxxxxxxxxxxxx"
  }
}

integrations

LINE Webhook และ Mini App

LINE Messaging Integration

supabase/functions/line-webhook-v2 รับ event จาก LINE ตรวจลายเซ็น x-line-signature แล้วกระจายงานตามชนิด event ก่อนตอบ ACK ภายในเวลาที่ LINE กำหนด

curl -X POST "$SUPABASE_URL/functions/v1/line-webhook-v2" \
  -H "Content-Type: application/json" \
  -H "x-line-signature: <base64-hmac>" \
  -d '{
    "destination": "Uxxxxxxxxxxxxxxxx",
    "events": [{
      "type": "message",
      "replyToken": "xxxxxxxx",
      "source": { "userId": "Uxxxxxxxxxxxxxxxx", "type": "user" },
      "message": { "type": "text", "id": "1", "text": "ยอดค้างชำระ" }
    }]
  }'

{ "ok": true }

integrations

MCP Server สำหรับ AI Agent

MCP Server

dna-os-mcp-server เป็น protocol adapter ที่แปลง MCP tool call เป็น HTTP request ไปยัง endpoint ของ DNA OS โดยไม่ถือ business logic ของตัวเอง

{
  "mcpServers": {
    "dna-os": {
      "command": "node",
      "args": ["dna-os-mcp-server/dist/index.js"],
      "env": {
        "DNA_OS_BASE_URL": "https://<host>",
        "DNA_OS_API_TOKEN": "<token จาก /admin/api-tokens>"
      }
    }
  }
}

integrations

Connector และ Provider Registry

Connectors & Providers

Connector ทุกตัวอ้างอิง Provider ที่ประกาศใน registry/PROVIDER_DIRECTORY.json และเดินตามวงจรชีวิตที่กำหนดใน registry/connector-lifecycle.json

settings

ตัวแปรสภาพแวดล้อม

Environment Variables

รายการคีย์ที่ระบบอ่านจริง พร้อมขอบเขตการใช้งาน ค่าจริงเก็บใน .env.local ระหว่างพัฒนา และใน environment ของแพลตฟอร์มเมื่อขึ้น production

settings

ระบบสิทธิ์และขอบเขตข้อมูล

Access Control & Data Scope

สิทธิ์ถูกตัดสินจาก profiles.role ทุกคำขอ โดยเทียบกับ role_tiers ใน registry/permissions.json และขอบเขตข้อมูลถูกจำกัดตามบัญชีผู้ถือ token

settings

เกณฑ์การปล่อยระบบ (Deploy Gate)

Deploy Gate Criteria

ทุก release ต้องผ่าน deploy-gate ซึ่งตรวจสภาพแวดล้อม หลักฐาน Dev Loop สถานะสุขภาพ และความสอดคล้องของเลขเวอร์ชันก่อนอนุญาตให้ build

# ตรวจก่อน build (prebuild เรียกอัตโนมัติ)
npm run deploy-gate

# ผลที่ผ่าน
DNA OS Health Score: 100 / 100
PASSED: 8 / 8
FAILED: 0
READY

# ผลที่ไม่ผ่าน
Deploy Blocked — Dev Loop Pipeline
  - Dev Loop evidence query failed: <reason>

LINE → GatewayEvent → canonical evidence log Inbound LINE Observe

Trigger — LINE ยิง event เข้ามา — LINE ส่ง POST /api/gateway/observe/line พร้อม destination + events[] โดยไม่มี session; route อ่าน body เท่านั้นเพื่อรู้ว่ามาจากบัญชีไหน ยังไม่แตะฐานข้อมูล
app/api/gateway/observe/line/route.ts · POST

Gate — เลือก secret ของบัญชีปลายทาง — destination ถูกใช้ resolve channel secret จาก public.connect_external_account_credentials; ถ้าไม่พบจึงถอยไปใช้ LINE_CHANNEL_SECRET ของบัญชีหลัก
engines/connect/accounts.ts · resolveExternalAccountCredential
ปฏิเสธเมื่อ: ไม่มี secret เลย → 503

Gate — ตรวจลายเซ็นก่อนอ่าน/เขียนใด ๆ — HMAC-SHA256 ของ raw body เข้ารหัส base64 แล้วเทียบ x-line-signature ด้วย timingSafeEqual — body ที่ยังไม่ผ่านไม่ถูกตีความต่อ
engines/integration-gateway/adapters/line.ts · verifyLineSignature
ปฏิเสธเมื่อ: ลายเซ็นผิด/หาย → 401 · JSON เสีย → 400

Normalize — LINE event → GatewayEvent — แต่ละ event แปลเป็น capability กลาง (message / document / location / identity signal / interaction) และ evidence ถูกจำกัดด้วย key whitelist 9 คีย์ — ข้อความลูกค้าและ reply token ไม่มีช่องเดินทางเข้า core
engines/integration-gateway/adapters/line.ts · normalizeLineWebhook / EVIDENCE_KEYS
ปฏิเสธเมื่อ: ชนิด event ที่ยังไม่รองรับ → นับ skipped ไม่แต่ง capability ขึ้นเอง

Gate + Bus — สัญญาและช่องทาง — publish() ตรวจ isGatewayEvent ก่อน แล้วตรวจ channelIsEnabled (observe/propose เท่านั้น) จากนั้น dispatchEvent('gateway.<capability>') และเขียน integration_gateway_events; ช่อง propose มีแถว proposal รอเจ้าของตัดสิน
engines/integration-gateway/event-bus/bus.ts · publish · policy/gate.ts
ปฏิเสธเมื่อ: สัญญาไม่ครบ/ช่องปิด → ok:false แล้ว route ตอบ 500

Ack — เฉพาะเมื่อเขียนสำเร็จ — ตอบ { ok, accepted, skipped } หลังทุก event ผ่าน bus เท่านั้น ไม่ ack ล่วงหน้า
app/api/gateway/observe/line/route.ts · NextResponse.json

KBank webhook → staging → Observe Bank Inbound Ingest

Trigger — ธนาคารยิง webhook — POST /api/connectors/webhook/kbank รับเฉพาะ body ที่ผ่าน gate; ระหว่างรอ sandbox ยังไม่มี secret จริง จึงยังไม่มีการรับ event จากธนาคารได้
app/api/connectors/webhook/kbank/route.ts

Gate — สถานะ connector — getConnectedConnector ต้องได้ connector ที่ status = 'connected' และ enabled = true เท่านั้น; connector ที่ปิดหรือ error หยุดรับทันทีโดยไม่ต้อง deploy
core/connector-loader.ts · getConnectedConnector
ปฏิเสธเมื่อ: 404 connector_not_found / connector_not_enabled

Gate — ขนาด body — ปฏิเสธก่อน buffer เมื่อ content-length หรือ byte จริงเกิน 64KB
app/api/connectors/webhook/[slug]/_lib/webhookGate.ts · MAX_WEBHOOK_BODY_BYTES
ปฏิเสธเมื่อ: 413 body_too_large

Gate — ลายเซ็น (fail-closed สองชั้น) — ถ้า connector ไม่ได้ตั้ง signature_header หรือ signing_secret ระบบปฏิเสธ (ไม่ใช่ข้ามการตรวจ); เมื่อตั้งแล้วต้องมี header และ HMAC ต้องตรง timingSafeEqual ก่อน parse body
app/api/connectors/webhook/[slug]/_lib/webhookGate.ts · evaluateWebhookRequest
ปฏิเสธเมื่อ: 503 signature_not_configured · 401 signature_missing / signature_invalid

Staging — เก็บ raw ก่อนแปล — เขียน kbank_webhook_events (raw_body + allow-listed headers, status 'received') ก่อน normalize เพื่อให้ reconcile/payout มีหลักฐานระดับไบต์ ไม่ใช่แค่ evidence ที่แปลงแล้ว
app/api/connectors/webhook/kbank/route.ts · PHASE 1 (kbank_webhook_events insert)
ปฏิเสธเมื่อ: เขียน staging ไม่ได้ → 500 ไม่ ack body ที่ผ่านลายเซ็นแล้ว

Normalize + Publish — normalizeKBankWebhook แปลงเป็น capability กลาง payment.* / payout.* / transfer.* แล้ว publish เข้า Observe Channel
engines/integration-gateway/adapters/kbank.ts · normalizeKBankWebhook
ปฏิเสธเมื่อ: ไม่มี event ที่แปลงได้ → 400 · publish ล้ม → 500

Ack — { received: true, published } — ตอบหลัง publish สำเร็จทุก event เท่านั้น; ไม่มี published ก็ไม่ตอบว่ารับแล้ว
app/api/connectors/webhook/kbank/route.ts · NextResponse.json

GatewayEvent → Connect → canonical business event Business Event Bridge

Trigger — transport ส่ง canonical command — POST /api/internal/connect/event รับเฉพาะคำสั่งที่ normalize แล้ว (ไม่มี payload ของ LINE ติดมา, ไม่มีการ branch ตาม provider)
app/api/internal/connect/event/route.ts

Gate — secret ของ bridge — header x-connect-internal-secret ต้องตรงกับ CONNECT_INTERNAL_SECRET
app/api/internal/connect/event/route.ts · process.env.CONNECT_INTERNAL_SECRET
ปฏิเสธเมื่อ: ไม่ตั้ง secret → 503 · ไม่ตรง → 401

Gate — คำสั่งปิด + actor — รับ 4 คำสั่งเท่านั้น: business_event.create / .transition / .enrich / .link_transaction และต้องมี actor ทุกครั้ง
app/api/internal/connect/event/route.ts · COMMANDS
ปฏิเสธเมื่อ: คำสั่งนอกชุด/ไม่มี actor → 400

Write — canonical event writer เท่านั้น — createBusinessEvent / transitionBusinessEvent / enrichBusinessEvent / linkBusinessEventTransaction เป็นเจ้าของ allow-list ของ field และชุดสถานะ; ผู้เรียกส่ง row shape เข้ามาไม่ได้
engines/canonical/event-write.ts
ปฏิเสธเมื่อ: 422 EVENT_UNKNOWN_STATE / EVENT_TRANSITION_REFUSED / EVENT_FIELD_NOT_ALLOWED

Audit — metadata ที่บอกที่มา — ทุกแถวที่สร้างพก written_by = canonical:event-write@<actor> และ source_provider ไว้ใน metadata เพื่อตรวจย้อนได้โดยไม่ต้องเดา
engines/canonical/event-write.ts · createBusinessEvent

สลิป → canonical payment (guards → RPC เดียว) Money In

Trigger — transport แจ้งว่าพบหลักฐานการจ่าย — POST /api/internal/connect/payment-confirm รับเฉพาะ receipt_document_id + actor; ไม่รับ amount/outstanding เพราะผู้เรียกใส่ตัวเลขเงินเองไม่ได้
app/api/internal/connect/payment-confirm/route.ts

Gate — secret ของ bridge — header x-payment-confirm-internal-secret เทียบ PAYMENT_CONFIRM_INTERNAL_SECRET
app/api/internal/connect/payment-confirm/route.ts · process.env.PAYMENT_CONFIRM_INTERNAL_SECRET
ปฏิเสธเมื่อ: ไม่ตั้ง → 503 · ไม่ตรง → 401 · body ผิดรูป → 400

Flow + guards — ตรวจก่อนแตะเงิน — confirmReceiptPayment → confirmPayment: receipt ต้องเป็น transfer_slip/payment_advice, ต้องยังไม่ถูกจัดสรร, Σ allocation ≤ ยอด receipt, invoice ต้องไม่ VOID บริษัทตรง และไม่เกินยอดคงค้าง
engines/canonical/receipt-confirm-flow.ts · engines/canonical/payment-write.ts
ปฏิเสธเมื่อ: throw เป็นรหัส PAYMENT_* (เช่น PAYMENT_OVERPAYMENT_NOT_ALLOWED, PAYMENT_ALREADY_ALLOCATED)

Commit — RPC เดียว ไม่มี fallback — confirm_payment_allocation เขียน allocations + ledger + invoice projection + receipt state + snapshot + audit ใน transaction เดียว; writer ไม่เขียนแถวเงินเองเลย และไม่มีเส้นสำรอง
engines/canonical/payment-write.ts · confirmPayment → db.rpc('confirm_payment_allocation')
ปฏิเสธเมื่อ: RPC หาย/ปฏิเสธ → fail closed (mapPaymentRpcError)

Ack — ผลจริง ไม่ใช่ผลที่หวัง — ตอบ 200 { already_reconciled, new_outstanding, debt_event_id, acknowledgement }; acknowledgement เป็นส่วนเสริมและล้มได้โดยไม่ทำให้การยืนยันเงินล้ม
app/api/internal/connect/payment-confirm/route.ts · acknowledgePayment

เงินออก → canonical expense / payable Money Out

Trigger — transport แจ้งค่าใช้จ่าย/คำขอจ่าย — POST /api/internal/connect/expense รับ 3 คำสั่ง: expense.record, payable.request, payable.transition
app/api/internal/connect/expense/route.ts · COMMANDS

Gate — secret ของ bridge — header x-expense-internal-secret เทียบ EXPENSE_INTERNAL_SECRET
app/api/internal/connect/expense/route.ts
ปฏิเสธเมื่อ: ไม่ตั้ง → 503 · ไม่ตรง → 401

Write — writer ตัดสิน ไม่ใช่ผู้เรียก — recordCompanyExpense ตรวจ source (line_chat / subscription_email_sync / admin_manual) และ amount > 0; requestPartnerPayable ตั้ง status 'pending' เอง; transitionPartnerPayable อัปเดตแบบกรองสถานะต้นทาง
engines/canonical/expense-write.ts
ปฏิเสธเมื่อ: 0 แถวถูกอัปเดต → PAYABLE_TRANSITION_INVALID · 422 EXPENSE_* / PAYABLE_*

Policy — เวลาเสร็จมาจากหลักฐาน — completed_at ถูก derive จาก bank_email_verified เท่านั้น — ผู้เรียกตั้งเวลาเสร็จเองไม่ได้
engines/canonical/expense-write.ts · transitionPartnerPayable

Audit — ทุกแถวเงินออกมีร่องรอย — recordCanonicalAudit เขียน expense.recorded / payable.requested / payable.transitioned ทุกครั้ง
engines/canonical/audit.ts · recordCanonicalAudit

VCC → engine hours → total_engine_hours Telemetry to Engine Hours

Trigger — กล่อง GPS/รีเลย์ยิง ping — POST /api/internal/equipment/telemetry รับ { imei, vccVoltage, recordedAt? } จากฮาร์ดแวร์โดยตรง — ไม่มี session เพราะกล่องไม่ได้ล็อกอิน และยังไม่มีผู้ให้บริการกล่อง/SMS gateway รายใดถูกเลือก จึงใช้ shape กลางนี้แทนการเดา wire format ของ vendor
app/api/internal/equipment/telemetry/route.ts

Gate — bearer secret ของฮาร์ดแวร์ — header x-equipment-telemetry-secret ต้องตรงกับ EQUIPMENT_TELEMETRY_SECRET; ถ้ายังไม่ตั้งค่า ระบบตอบ 500 (ไม่ใช่ 503 แบบ bridge ธุรกิจ) ตามโค้ดจริง
app/api/internal/equipment/telemetry/route.ts · process.env.EQUIPMENT_TELEMETRY_SECRET
ปฏิเสธเมื่อ: ไม่ตั้งค่า → 500 · ไม่ตรง → 401

Validate — IMEI ต้องเป็นเครื่องที่รู้จัก — imei และ vccVoltage ต้องมาและมีชนิดถูกต้อง; ค้น equipment_assets ด้วย imei ถ้าไม่พบคือปฏิเสธ ไม่สร้างเครื่องใหม่ให้เอง
app/api/internal/equipment/telemetry/route.ts · equipment_assets lookup by imei
ปฏิเสธเมื่อ: ข้อมูลไม่ครบ → 400 · ไม่พบ IMEI → 404

Decision — VCC ≥ 13.5V คือเครื่องติด — engine_running = vccVoltage >= 13.5 โดยค่าคงที่ ENGINE_RUNNING_THRESHOLD_VCC อยู่ที่เดียว ไม่กระจายไปตามผู้ให้บริการกล่อง
app/api/internal/equipment/telemetry/route.ts · ENGINE_RUNNING_THRESHOLD_VCC

Evidence — เก็บ ping ดิบก่อนสะสม — insert equipment_telemetry_pings (recorded_at, engine_running, vcc_voltage, raw_payload) — เก็บ payload ดิบไว้ตรวจย้อน
app/api/internal/equipment/telemetry/route.ts · equipment_telemetry_pings insert
ปฏิเสธเมื่อ: เขียน ping ไม่ได้ → 500

Accumulate — ชั่วโมงเกิดจาก ping คู่ — accumulateEngineHours อ่าน ping ก่อนหน้า (strictly before) และบวกเฉพาะเมื่อทั้ง ping ก่อนและ ping ใหม่เป็น engine_running; delta ถูก cap ที่ MAX_GAP_HOURS = 0.5 ชม. เพราะ ping ปกติมาทุก 10–30 วินาที — ช่องว่างที่ใหญ่กว่านั้นคือสัญญาณขาด ไม่ใช่ชั่วโมงเดินเครื่องที่มองไม่เห็น และค่า gap จริงถูกคืนเป็น capped_from_hours
engines/equipment/engine-hours.ts · computeEngineHoursDelta / accumulateEngineHours
ปฏิเสธเมื่อ: ping ย้อนหลัง/เวลาเสีย → delta 0 ไม่ลบชั่วโมง · accumulate ล้ม → 500 พร้อม telemetry_saved:true

Ack + สถานะเครื่อง — ถ้า engine_running เป็นจริง อัปเดต current_status = RUNNING แล้วตอบ { ok, engine_running, delta_hours, capped_from_hours, new_total_hours } — ตัวเลขที่ตอบคือค่าที่เขียนจริง ไม่ใช่ค่าที่คำนวณลอย
app/api/internal/equipment/telemetry/route.ts · NextResponse.json

ชั่วโมงเครื่อง → resource transaction (ราคาจาก config จริง) Machinery Hours

Trigger — telematics/อีเมลแจ้งชั่วโมงเดินเครื่อง — POST /api/internal/connect/resource-transaction พร้อม source_event_id และเวลาจริงจากต้นทาง
app/api/internal/connect/resource-transaction/route.ts

Gate — secret ของ bridge — header x-resource-transaction-internal-secret เทียบ RESOURCE_TRANSACTION_INTERNAL_SECRET
app/api/internal/connect/resource-transaction/route.ts
ปฏิเสธเมื่อ: ไม่ตั้ง → 503 · ไม่ตรง → 401

Validate — ต้องอ้างของจริง — job_id ต้องมีอยู่จริงใน jobs, duration_hours > 0, started_at ต้องไม่เกิน received_at และ evidence_ref ต้องมี
engines/canonical/resource-transaction-write.ts · recordResourceTransaction
ปฏิเสธเมื่อ: RESOURCE_TRANSACTION_JOB_NOT_FOUND / INVALID_TIME / INVALID_DURATION

Authority — ราคาอ่านจาก config — fuel-price และ machinery_rates (base_rate_per_hour, fuel_consumption_lph, markup_margin) อ่านจาก app_configs; ขาดหรือผิดรูปคือหยุด ไม่ถอยไปใช้เลขเดิมในโค้ด
engines/canonical/resource-transaction-write.ts · readConfigAuthorities
ปฏิเสธเมื่อ: CONFIG_AUTHORITY_MISSING (zero rows written)

Idempotency — event เดียวสร้างแถวเดียว — source_event_id เป็น unique; ซ้ำจะคืนแถวเดิมพร้อม duplicate: true และยังกัน race 23505 ได้
engines/canonical/resource-transaction-write.ts · idempotency check
ปฏิเสธเมื่อ: ไม่ throw ซ้ำ — คืน duplicate: true แทนการเขียนทับ

Compute + Write + Audit — unit_cost = base_rate_per_hour + fuel_consumption_lph × fuel_price; unit_price = unit_cost + markup; total = duration_hours × unit_cost แล้วเขียนพร้อม audit transaction.created
engines/canonical/resource-transaction-write.ts · recordResourceTransaction

ข้อเสนอผู้ขาย ≠ ราคากลาง Price Authority

Trigger — มีข้อความตอบราคาเข้ามา — ช่องทางใดก็ได้ส่งข้อความตอบกลับ; ข้อความนั้นเป็นหลักฐาน ไม่ใช่สิทธิ์แก้ราคา
engines/canonical/material-price-write.ts · recordSellerOffer

Evidence — บันทึกข้อเสนอพร้อม audit ใน transaction เดียว — record_seller_offer_atomic เขียนแถวคำขอ + audit พร้อมกัน และคืน price_changed: false เสมอ
engines/canonical/material-price-write.ts · recordSellerOfferAtomic
ปฏิเสธเมื่อ: PRICE_REQUEST_NOT_FOUND / PRICE_REQUEST_NOT_PENDING / PRICE_INVALID

Authority — ใครมีสิทธิ์เปลี่ยนราคากลาง — applyMaterialPrice ใช้ resolveAuthority(action 'price.write'): เจ้าของหรือ delegation ที่ระบุชัดเท่านั้น — ADMIN_TIER อย่างเดียวหรือชื่อในแชตไม่พอ
core/authority/resolve.ts · resolveAuthority
ปฏิเสธเมื่อ: PRICE_FORBIDDEN:<reason>

Atomic commit — ราคาและ audit ไปด้วยกัน — apply_material_price_atomic เขียนราคา + audit ใน transaction เดียว และไม่มีเส้น 'เขียนแล้วค่อยย้อน' เพราะ compensation รับประกันไม่ได้
engines/canonical/material-price-write.ts · applyMaterialPriceAtomic
ปฏิเสธเมื่อ: RPC ยังไม่ apply → PRICE_ATOMIC_RPC_MISSING (ไม่ลดชั้นเป็นเขียนครึ่งเดียว)

Agent เรียกของจริงได้แค่ประตูที่เปิด Agent Authority

Trigger — agent/MCP client เรียกคำสั่ง — คำขอเข้ามาที่ route ของ MCP/dispatch ตามชนิดงาน (อ่านข้อมูล / วิเคราะห์ / รับงาน / อนุมัติ)
app/api/v1/mcp/business/dispatch/route.ts

Gate — session แอดมิน — business.dispatch ใช้ requireAuth(ADMIN_TIER) เป็นประตูเดียวกับ route แอดมินอื่น
app/api/v1/mcp/business/dispatch/route.ts · requireAuth(ADMIN_TIER)
ปฏิเสธเมื่อ: ไม่มี session/ชั้นไม่ถึง → ปฏิเสธก่อนอ่านข้อมูล

Gate — whitelist คำสั่งอ่าน — รับเฉพาะคำสั่งอ่านที่อยู่ในรายการ; คำสั่งอื่นไม่ถูกส่งต่อให้ dispatcher
app/api/v1/mcp/business/dispatch/route.ts · COMMAND_NOT_PERMITTED
ปฏิเสธเมื่อ: 403 COMMAND_NOT_PERMITTED

Gate — Execution Channel — channelIsEnabled('execute') ยังเป็น false ระบบจึงรายงานความสามารถตรง ๆ ว่า NOT_IMPLEMENTED แทนการจำลองสำเร็จ
app/api/admin/workspace/ai-agents/route.ts · engines/integration-gateway/policy/gate.ts
ปฏิเสธเมื่อ: execute_capability.status = 'NOT_IMPLEMENTED'

Gate — เจ้าของต้องยืนยันเอง — การอนุมัติที่แตะ production ต้องแนบ owner_verification_artifact; session แอดมินอย่างเดียวไม่พอ
app/api/gateway/proposals/[id]/decide/route.ts
ปฏิเสธเมื่อ: 403 OWNER_VERIFICATION_REQUIRED

Handoff — ส่งสัญญางาน ไม่ใช่สิทธิ์ — contractor ได้ JobContract + WorkerRequest พร้อม permittedReadScope/permittedWriteScope และ approvalPolicy; runtime ยัง PAUSED ตาม TASK-082
app/api/v1/mcp/contractor/task-claim/route.ts · registry/TASK_QUEUE.json
ปฏิเสธเมื่อ: intake ปิด → ไม่จ่ายงานใหม่