@ciromaciel/contract 1.3.0 → 1.4.0

package/README.md

@@ -141,6 +141,14 @@ import { OUTBOX_SQL, envelope, enqueueEvent, deliverDue, releaseHeld, retryDeliv
 
 The delivery queue every product shares. Each event is a row in `outbox` before it leaves, one per subscribed endpoint, signed with `./webhooks`. A 2xx is `sent`; 401 and 403 are `held` (probed hourly, released at once by `releaseHeld` when the secret changes); 410 is `failed`; anything else retries after 1 min, 5 min, 30 min, 2 h and 12 h. `OUTBOX_SQL` is the schema to put in the product's first migration. The product supplies a D1-shaped `db` and `decryptSecret(ciphertext)`.
 
+### `@ciromaciel/contract/feedback`
+
+```js
+import { createFeedback, FEEDBACK_SQL } from '@ciromaciel/contract/feedback'
+```
+
+"Sugerir ou relatar", the corner button of every panel (`FeedbackWidget` in `@ciromaciel/dashboard-kit`), on the worker side. `createFeedback({ product, prefix, error, requirePerson, locate, fields })` returns `handleRoutes` (`GET`/`POST /api/feedback`, behind the login), `handleHooks` (the Tasks' signed answers at `/feedback/tasks` and the build job's news at `/feedback/build`) and `runCron` (resend what the Tasks did not take; resend and then report what the triage never took). A request carries `<prefix>-<6 hex>` (`DK-1A2B3C`) and its thread is `<product>:<ref>`. `FEEDBACK_SQL` is the table; the product adds its own columns (`deck_id`) and names them in `locate().columns`. Only a person sends, and `locate` names only the account's own things. Env: `FEEDBACK_URL`, `FEEDBACK_SECRET`, `TASKS_WEBHOOK_SECRET`, `BUILD_SECRET`.
+
 ## Links
 
 - [Website](https://ciromaciel.click)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ciromaciel/contract",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "license": "MIT",
     "type": "module",
     "description": "A single response envelope, a closed catalogue of error codes, and helpers that make answering outside it impossible.",
@@ -16,7 +16,8 @@
         "./plan": "./src/plan/index.js",
         "./webhooks": "./src/webhooks.js",
         "./token": "./src/token.js",
-        "./outbox": "./src/outbox.js"
+        "./outbox": "./src/outbox.js",
+        "./feedback": "./src/feedback.js"
     },
     "scripts": {
         "test": "bun test tests/"

package/src/feedback.js

@@ -0,0 +1,417 @@
+// ============================================================================
+// @ciromaciel/contract/feedback — "Sugerir ou relatar", the same in every product
+// ============================================================================
+//
+//     import { createFeedback, FEEDBACK_SQL } from '@ciromaciel/contract/feedback'
+//
+//     const feedback = createFeedback({
+//         product: 'decks', prefix: 'DK',
+//         error: (code, message, details) => new ContractError(code, message, details),
+//         requirePerson: auth => requirePerson(auth, ContractError, CODES, 'Mandar uma sugestão'),
+//         locate: async ({ db, auth, body }) => ({ columns: { deck_id: … }, where: { deckTitle: … } }),
+//         fields: row => ({ deckId: row.deck_id }),
+//     })
+//
+// The panel's corner button (dashboard-kit FeedbackWidget) is the door to the improvement agent
+// (manager/docs/2026-10-11-AGENTE-DE-MELHORIAS.html). Blogs was the pilot, 11/10/2026; this module
+// is its routes/feedback.js with the product's pieces passed in, so the second product is a config
+// and not a copy.
+//
+//     POST /api/feedback   { kind: problem|idea, happens, wish?, context, …the product's ids }
+//     GET  /api/feedback   the account's own, newest first, with where each one is
+//     POST /feedback/tasks the Tasks' signed request.created / request.answered (the way back)
+//     POST /feedback/build the build job's signed news: building, review (with the preview), live
+//
+// The person writes only what happens and what they would like. WHERE comes from the panel
+// (`context`: the screen, the address, the browser, the window) and from the product (`locate`:
+// the names of its own things, only when they are the account's): the agent starts knowing the
+// place, not asking.
+//
+// The row is the record. When FEEDBACK_URL and FEEDBACK_SECRET are set (the Tasks' source
+// "Melhorias dos produtos"), a signed `feedback.created` goes there after the answer; a failed
+// send is tried again by the product's cron (`forwardPending`), and a feedback the triage never
+// took is sent once more and then reported stuck (`watchTriage`). Only a person sends.
+//
+// ENV the product's worker reads: FEEDBACK_URL, FEEDBACK_SECRET (the source), TASKS_WEBHOOK_SECRET
+// (the Tasks' outgoing webhook, the way back), BUILD_SECRET (the build job's news).
+
+import { CODES } from './codes.js'
+import { collection, created, ok, page } from './responses.js'
+import { envelope, sendSigned } from './outbox.js'
+import { verifyWebhook } from './webhooks.js'
+
+/**
+ * The table every product keeps. A product adds its own columns for its things (Blogs: blog_id,
+ * post_id; Decks: deck_id) in its migration, and names them in `locate().columns`.
+ */
+export const FEEDBACK_SQL = `
+CREATE TABLE IF NOT EXISTS feedback (
+    id TEXT PRIMARY KEY,
+    account_id TEXT NOT NULL,
+    number INTEGER NOT NULL,
+    kind TEXT NOT NULL,
+    happens TEXT NOT NULL,
+    wish TEXT NOT NULL DEFAULT '',
+    context TEXT NOT NULL DEFAULT '{}',
+    reporter_name TEXT NOT NULL DEFAULT '',
+    reporter_email TEXT NOT NULL DEFAULT '',
+    status TEXT NOT NULL DEFAULT 'received',
+    status_note TEXT NOT NULL DEFAULT '',
+    forwarded_at INTEGER,
+    forward_status INTEGER,
+    retries INTEGER NOT NULL DEFAULT 0,
+    retried_at INTEGER,
+    stuck_at INTEGER,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    UNIQUE (account_id, number)
+);
+CREATE INDEX IF NOT EXISTS idx_feedback_account ON feedback (account_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_feedback_forward ON feedback (forwarded_at, created_at);
+`
+
+export const FEEDBACK_KINDS = ['problem', 'idea']
+
+export const FEEDBACK_STATUS_LABELS = {
+    received: 'Recebido',
+    triaged: 'Em análise',
+    approved: 'Aprovado',
+    building: 'Em construção',
+    review: 'Em revisão',
+    live: 'No ar',
+    declined: 'Não vamos fazer',
+    needs_info: 'Precisa de mais detalhes',
+}
+
+/** How long a feedback may sit in "Recebido" after the Tasks took it before the next step. */
+export const STUCK_AFTER = 15 * 60
+
+/** Requests about a feedback that are not its triage: their creation moves nothing. */
+const FOLLOW_UP = / · (Revisar|A construção parou|A sugestão travou)\b/
+
+/** The Ciro's choice in the Tasks, as the status the person sees. */
+const OPTION_STATUS = { 'Aprovar e construir': 'approved', 'Pedir mais detalhes à pessoa': 'needs_info', 'Não vamos fazer': 'declined' }
+
+/** The choices that start the build job: the first approval builds; "Tentar de novo" answers a build that stopped. */
+const OPTION_JOB = { 'Aprovar e construir': 'build', 'Tentar de novo': 'build' }
+const RESEND_OPTION = 'Mandar de novo ao agente'
+
+/** The review's native answers (Tasks: kind review), as the job they start. */
+const REVIEW_JOB = { approved: 'ship', changes: 'revise', refused: 'discard' }
+
+const TRIAGE_PHASE = 'Triagem'
+const BUILD_STATUSES = ['building', 'review', 'live', 'approved', 'declined']
+const MAX_TEXT = 4000
+const CONTEXT_KEYS = { screen: 80, section: 40, path: 500, url: 1000, viewport: 20, browser: 300, language: 20, panelVersion: 40, timezone: 60 }
+const COLUMN = /^[a-z][a-z0-9_]{0,40}$/
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+const text = (value, max) =>
+    String(value ?? '')
+        .replace(/\r\n?/g, '\n')
+        .trim()
+        .slice(0, max)
+const parse = (value, fallback) => {
+    try {
+        return value ? JSON.parse(value) : fallback
+    } catch {
+        return fallback
+    }
+}
+const isOk = status => status >= 200 && status < 300
+export const isUuid = value => typeof value === 'string' && UUID.test(value)
+
+/** What the panel says about where it happened, kept to the known keys and sizes. */
+export function cleanContext(value) {
+    const input = value && typeof value === 'object' ? value : {}
+    return Object.fromEntries(
+        Object.entries(CONTEXT_KEYS)
+            .map(([key, max]) => [key, text(input[key], max)])
+            .filter(([, v]) => v)
+    )
+}
+
+/**
+ * The feedback of one product.
+ *
+ *   product        'blogs' — the event's product, the thread's key (`blogs:BL-…`), the machines' groups
+ *   prefix         'BL' — the code a request carries across systems: BL- and the first 6 hex of the id
+ *   error          (code, message, details) => Error the product's worker turns into its failure()
+ *   requirePerson  auth => void, throws when it is not a person (a key or an agent never sends)
+ *   locate         async ({ db, auth, body }) => { columns, where }: the product's columns of the row
+ *                  and the names added to the context; only what is the account's (never another's name)
+ *   fields         row => object: the product's ids in the API and in the events ({ blogId, postId })
+ *   userAgent      of the signed sends
+ *   fetch          for the tests; the global one by default
+ */
+export function createFeedback({ product, prefix, error, requirePerson, locate = async () => ({}), fields = () => ({}), userAgent = `ciromaciel-${product}/1.0`, fetch: fetchImpl }) {
+    if (!/^[a-z][a-z0-9-]{0,30}$/.test(String(product))) throw new Error('createFeedback: product is a lowercase key, like "decks".')
+    if (!/^[A-Z]{2,4}$/.test(String(prefix))) throw new Error('createFeedback: prefix is 2 to 4 capital letters, like "DK".')
+    const fail = (code, message, details) => error(code, message, details)
+
+    const refOf = id => `${prefix}-${String(id).replace(/-/g, '').slice(0, 6).toUpperCase()}`
+    const REF = new RegExp(`^${prefix}-([0-9A-F]{6})\\b`)
+    const WORK_KEY = new RegExp(`^${product}:(${prefix}-[0-9A-F]{6})$`)
+    const workKeyOf = id => `${product}:${refOf(id)}`
+    const byRef = (db, hex) => db.prepare('SELECT * FROM feedback WHERE id LIKE ?').bind(`${hex.toLowerCase()}%`).first()
+
+    function serialize(row) {
+        return {
+            id: row.id,
+            number: row.number,
+            ref: refOf(row.id),
+            kind: row.kind,
+            happens: row.happens,
+            wish: row.wish,
+            ...fields(row),
+            context: parse(row.context, {}),
+            status: row.status,
+            statusLabel: FEEDBACK_STATUS_LABELS[row.status] ?? row.status,
+            statusNote: row.status_note,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        }
+    }
+
+    /** The event the Tasks receives: everything the triage needs, in one piece. A resend is another event id. */
+    function eventOf(row, type = 'feedback.created', attempt = 0, extra = {}, eventId = null) {
+        return {
+            eventId: eventId ?? `${row.id}.${type}${attempt ? `.retry${attempt}` : ''}`,
+            body: envelope({
+                type,
+                at: row.created_at,
+                channel: 'panel',
+                person: { email: row.reporter_email || null, name: row.reporter_name || null },
+                properties: { product, id: row.id, ref: refOf(row.id), number: row.number, accountId: row.account_id, kind: row.kind, happens: row.happens, wish: row.wish, ...fields(row), ...parse(row.context, {}), ...extra },
+            }),
+        }
+    }
+
+    const isWired = env => Boolean(env.FEEDBACK_URL && env.FEEDBACK_SECRET)
+
+    /** One signed event to the Tasks' source; the HTTP status (0 when it did not answer). */
+    async function send(env, event) {
+        try {
+            const answer = await sendSigned({ url: env.FEEDBACK_URL, secret_ciphertext: env.FEEDBACK_SECRET }, event, { decryptSecret: async secret => secret, userAgent, ...(fetchImpl ? { fetch: fetchImpl } : {}) })
+            return answer?.status ?? 0
+        } catch {
+            return 0
+        }
+    }
+
+    async function forward(env, db, row, now) {
+        if (!isWired(env)) return false
+        const status = await send(env, eventOf(row))
+        await db
+            .prepare('UPDATE feedback SET forwarded_at = ?, forward_status = ? WHERE id = ?')
+            .bind(isOk(status) ? now : null, status, row.id)
+            .run()
+        return isOk(status)
+    }
+
+    /** Each status a feedback reaches, once (`feedback.status`): the Tasks' boards count the funnel from it. */
+    async function announceStatus(env, row, status, now) {
+        if (!isWired(env) || status === row.status) return
+        await send(env, eventOf({ ...row, created_at: now }, 'feedback.status', 0, { status, statusLabel: FEEDBACK_STATUS_LABELS[status] ?? status }, `${row.id}.feedback.status.${status}`))
+    }
+
+    async function resend(env, db, row, now) {
+        const attempt = (row.retries ?? 0) + 1
+        const status = await send(env, eventOf(row, 'feedback.created', attempt))
+        if (isOk(status)) await db.prepare('UPDATE feedback SET retries = ?, retried_at = ?, stuck_at = NULL WHERE id = ?').bind(attempt, now, row.id).run()
+        return isOk(status)
+    }
+
+    /**
+     * The cron's watch over the triage: taken by the Tasks and still "Recebido", after 15 minutes
+     * it goes to the agent once more; 15 minutes after that, `feedback.stuck`, which a rule in the
+     * Tasks turns into a request to the Ciro ("A sugestão travou").
+     */
+    async function watchTriage(env, db, now) {
+        if (!isWired(env)) return { resent: 0, stuck: 0 }
+        const { results } = await db
+            .prepare("SELECT * FROM feedback WHERE status = 'received' AND forwarded_at IS NOT NULL AND stuck_at IS NULL AND created_at > ? ORDER BY created_at LIMIT 20")
+            .bind(now - 3 * 86_400)
+            .all()
+        let resent = 0
+        let stuck = 0
+        for (const row of results) {
+            if (!row.retries && row.forwarded_at <= now - STUCK_AFTER) {
+                if (await resend(env, db, row, now)) resent++
+            } else if (row.retries && row.retried_at <= now - STUCK_AFTER) {
+                if (isOk(await send(env, eventOf(row, 'feedback.stuck', row.retries)))) {
+                    await db.prepare('UPDATE feedback SET stuck_at = ? WHERE id = ?').bind(now, row.id).run()
+                    stuck++
+                }
+            }
+        }
+        return { resent, stuck }
+    }
+
+    /** The cron's second chance: rows of the last 3 days the Tasks did not take yet. */
+    async function forwardPending(env, db, now) {
+        if (!isWired(env)) return 0
+        const { results } = await db
+            .prepare('SELECT * FROM feedback WHERE forwarded_at IS NULL AND created_at > ? ORDER BY created_at LIMIT 20')
+            .bind(now - 3 * 86_400)
+            .all()
+        let sent = 0
+        for (const row of results) if (await forward(env, db, row, now)) sent++
+        return sent
+    }
+
+    /** Both cron chores at once, for the product's scheduled(). */
+    async function runCron(env, db, now) {
+        return { sent: await forwardPending(env, db, now), ...(await watchTriage(env, db, now)) }
+    }
+
+    /**
+     * Starts the build job on the Tasks' machines: a signed `feedback.job` to the source, whose rule
+     * "Construir melhorias · <product>" runs the product's improvement job. `group` keeps two jobs of
+     * one group from running at once: the ships share one (two deploys never overlap), each
+     * improvement's build, revise and discard share another.
+     */
+    async function startJob(env, job, row, props) {
+        if (!isWired(env)) return 0
+        const feedback = { id: row.id, ref: refOf(row.id), number: row.number, kind: row.kind, happens: row.happens, wish: row.wish, context: parse(row.context, {}) }
+        const group = job === 'ship' ? `${product}-deploy` : `${product}-${feedback.ref.toLowerCase()}`
+        const payload = { feedback, workKey: workKeyOf(row.id), requestId: String(props.requestId ?? ''), note: String(props.note ?? '').slice(0, 2000), group }
+        const event = {
+            eventId: `${row.id}.feedback.job.${job}.${payload.requestId || Date.now()}`,
+            body: envelope({ type: 'feedback.job', at: Math.floor(Date.now() / 1000), channel: 'panel', person: { email: null, name: null }, properties: { product, ref: feedback.ref, job, ...payload } }),
+        }
+        return send(env, event)
+    }
+
+    async function readSigned(request, secret, maxBytes, now) {
+        const body = await request.text()
+        if (body.length > maxBytes) throw fail(CODES.PAYLOAD_TOO_LARGE, 'Evento grande demais.')
+        const check = await verifyWebhook([secret], { id: request.headers.get('x-ccm-id'), timestamp: request.headers.get('x-ccm-timestamp'), signature: request.headers.get('x-ccm-signature'), body }, now)
+        if (!check.ok) throw fail(CODES.UNAUTHORIZED, 'Assinatura inválida.')
+        return parse(body, {})
+    }
+
+    /**
+     * POST /feedback/tasks — public, signed with TASKS_WEBHOOK_SECRET. A request whose thread key
+     * (or, before the threads, whose title code) names a feedback moves it: created in the triage →
+     * Em análise; answered → the option the Ciro chose; refused → Não vamos fazer. Any other request
+     * of the Ciro's Tasks is acknowledged and ignored.
+     */
+    async function handleTasksHook({ request, env, db, pathname, method, now }) {
+        if (pathname !== '/feedback/tasks' || method !== 'POST') return null
+        if (!env.TASKS_WEBHOOK_SECRET) return null
+        const event = await readSigned(request, env.TASKS_WEBHOOK_SECRET, 64 * 1024, now)
+        const props = event?.data?.properties ?? {}
+        const fromWork = WORK_KEY.exec(String(props.workKey ?? ''))
+        const match = fromWork ? REF.exec(fromWork[1]) : REF.exec(String(props.title ?? ''))
+        if (!match || !['request.created', 'request.answered'].includes(event.type)) return ok({ accepted: 0 })
+        const row = await byRef(db, match[1])
+        if (!row) return ok({ accepted: 0 })
+        let status = row.status
+        let note = ''
+        let job = null
+        const isTriage = props.workKey ? props.phase === TRIAGE_PHASE : !FOLLOW_UP.test(String(props.title))
+        if (event.type === 'request.created' && row.status === 'received' && isTriage) status = 'triaged'
+        if (event.type === 'request.answered' && props.outcome === 'answered' && props.option === RESEND_OPTION) {
+            const sent = await resend(env, db, row, now)
+            return ok({ accepted: 1, status: row.status, resent: sent })
+        }
+        if (event.type === 'request.answered' && props.kind === 'review' && props.decision) {
+            // The review, answered natively: approve ships, changes rebuilds on the same branch with
+            // the note (meant for whoever redoes it, not for the person), refuse discards.
+            job = REVIEW_JOB[props.decision] ?? null
+            if (props.decision === 'refused') status = 'declined'
+            note = props.decision === 'changes' ? '' : String(props.note ?? '').slice(0, 500)
+        } else if (event.type === 'request.answered') {
+            if (props.outcome === 'refused') status = 'declined'
+            else if (props.outcome === 'answered') {
+                status = OPTION_STATUS[props.option] ?? status
+                job = OPTION_JOB[props.option] ?? null
+            }
+            note = String(props.note ?? '').slice(0, 500)
+        }
+        // "Pôr no ar" keeps "Em revisão" until the deploy is over: the job itself says "No ar".
+        const keepsNote = event.type !== 'request.answered' || props.decision === 'changes'
+        const isChanged = status !== row.status || (note && !keepsNote)
+        if (isChanged) {
+            await db
+                .prepare('UPDATE feedback SET status = ?, status_note = ?, updated_at = ? WHERE id = ?')
+                .bind(status, keepsNote ? row.status_note : note, now, row.id)
+                .run()
+            await announceStatus(env, row, status, now)
+        }
+        const dispatched = job ? await startJob(env, job, row, props) : null
+        if (!isChanged && !job) return ok({ accepted: 0 })
+        return ok({ accepted: 1, status, ...(job ? { job, dispatched } : {}) })
+    }
+
+    /** POST /feedback/build — public, signed with BUILD_SECRET: { ref, status, note? }, the job's news. */
+    async function handleBuildHook({ request, env, db, pathname, method, now }) {
+        if (pathname !== '/feedback/build' || method !== 'POST') return null
+        if (!env.BUILD_SECRET) return null
+        const input = await readSigned(request, env.BUILD_SECRET, 16 * 1024, now)
+        const match = REF.exec(String(input.ref ?? ''))
+        if (!match) throw fail(CODES.VALIDATION_ERROR, `Falta o código (${prefix}-…).`, { field: 'ref' })
+        if (!BUILD_STATUSES.includes(input.status)) throw fail(CODES.VALIDATION_ERROR, `O status é ${BUILD_STATUSES.join(', ')}.`, { field: 'status' })
+        const row = await byRef(db, match[1])
+        if (!row) return ok({ accepted: 0 })
+        await db
+            .prepare('UPDATE feedback SET status = ?, status_note = ?, updated_at = ? WHERE id = ?')
+            .bind(input.status, text(input.note, 500), now, row.id)
+            .run()
+        await announceStatus(env, row, input.status, now)
+        return ok({ accepted: 1, status: input.status })
+    }
+
+    /** The open hooks, in one call for the product's public chain. */
+    async function handleHooks(context) {
+        return (await handleTasksHook(context)) ?? (await handleBuildHook(context))
+    }
+
+    /** GET and POST /api/feedback, behind the product's login. */
+    async function handleRoutes(context) {
+        const { request, env, db, auth, pathname, method, now, ctx } = context
+        if (pathname !== '/api/feedback') return null
+
+        if (method === 'GET') {
+            const { results } = await db.prepare('SELECT * FROM feedback WHERE account_id = ? ORDER BY created_at DESC LIMIT 50').bind(auth.accountId).all()
+            return collection(results.map(serialize), page({ limit: 50, offset: 0, total: results.length }))
+        }
+
+        if (method === 'POST') {
+            requirePerson(auth)
+            const body = await readBody(request)
+            const kind = String(body.kind ?? '')
+            if (!FEEDBACK_KINDS.includes(kind)) throw fail(CODES.VALIDATION_ERROR, 'Escolha se é um problema ou uma melhoria.', { field: 'kind' })
+            const happens = text(body.happens, MAX_TEXT)
+            if (happens.length < 5) throw fail(CODES.VALIDATION_ERROR, kind === 'problem' ? 'Conte o que aconteceu.' : 'Conte a sua ideia.', { field: 'happens' })
+            const wish = text(body.wish, MAX_TEXT)
+            const located = (await locate({ db, auth, body })) ?? {}
+            const columns = Object.entries(located.columns ?? {}).filter(([name]) => COLUMN.test(name))
+            const where = { ...cleanContext(body.context), ...(located.where ?? {}) }
+            const id = crypto.randomUUID()
+            const number = ((await db.prepare('SELECT MAX(number) AS n FROM feedback WHERE account_id = ?').bind(auth.accountId).first())?.n ?? 0) + 1
+            const names = ['id', 'account_id', 'number', ...columns.map(([name]) => name), 'kind', 'happens', 'wish', 'context', 'reporter_name', 'reporter_email', 'created_at', 'updated_at']
+            const values = [id, auth.accountId, number, ...columns.map(([, value]) => value ?? null), kind, happens, wish, JSON.stringify(where), text(auth.name, 120), text(auth.email, 200), now, now]
+            await db
+                .prepare(`INSERT INTO feedback (${names.join(', ')}) VALUES (${names.map(() => '?').join(', ')})`)
+                .bind(...values)
+                .run()
+            const row = await db.prepare('SELECT * FROM feedback WHERE id = ?').bind(id).first()
+            // To the Tasks after the answer: the person never waits for the triage's door.
+            if (ctx?.waitUntil) ctx.waitUntil(forward(env, db, row, now).catch(() => {}))
+            return created(serialize(row))
+        }
+        return null
+    }
+
+    async function readBody(request) {
+        const raw = await request.text()
+        if (raw.length > 64 * 1024) throw fail(CODES.PAYLOAD_TOO_LARGE, 'Texto grande demais.')
+        const body = parse(raw, null)
+        if (!body || typeof body !== 'object' || Array.isArray(body)) throw fail(CODES.VALIDATION_ERROR, 'O corpo é um objeto JSON.')
+        return body
+    }
+
+    return { product, prefix, refOf, workKeyOf, serialize, handleRoutes, handleHooks, handleTasksHook, handleBuildHook, forwardPending, watchTriage, runCron }
+}