@seasonkoh/webaz 0.1.26 → 0.1.27

package/dist/layer2-business/L2-9-contribution/task-proposal-draft.js

@@ -1,16 +1,51 @@
-import { createBuildTask, logTaskEvent } from './build-tasks-engine.js';
-import { insertBuildTaskAgentMetadata, getBuildTaskAgentMetadata, setBuildTaskAudience, RISK_LEVELS, TASK_TYPES } from './build-task-agent-metadata-store.js';
+import { createBuildTask, logTaskEvent, releaseExpiredClaims } from './build-tasks-engine.js';
+import { insertBuildTaskAgentMetadata, getBuildTaskAgentMetadata, setBuildTaskAudience, setBuildTaskEstimate, RISK_LEVELS, TASK_TYPES, CONTEXT_SIZES, AGENT_BUDGETS } from './build-task-agent-metadata-store.js';
 import { reviewTaskProposal } from './task-proposal-store.js';
 /** Source-proposal ↔ draft-task link (lets a draft preserve its origin WITHOUT marking the proposal terminal). */
 export function initTaskProposalDraftLinkSchema(db) {
     db.exec(`CREATE TABLE IF NOT EXISTS task_proposal_draft_links (
-    task_id     TEXT PRIMARY KEY,
-    proposal_id TEXT NOT NULL,
-    created_by  TEXT NOT NULL,
-    created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+    task_id      TEXT PRIMARY KEY,
+    proposal_id  TEXT NOT NULL,
+    created_by   TEXT NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'active',
+    discarded_by TEXT,
+    discarded_at TEXT,
+    created_at   TEXT NOT NULL DEFAULT (datetime('now'))
   )`);
-    // UNIQUE: one draft per source proposal (aligns the DB with the createDraftFromProposal business rule).
-    db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_tpdl_proposal ON task_proposal_draft_links(proposal_id)`);
+    // Additive migration for pre-existing DBs (ALTER after CREATE; fresh DBs already have these columns).
+    // status = 'active' | 'discarded'. A discarded link is SOFT-deleted: the row is retained for provenance
+    // (retroactive reward / anchor-side traceability / dispute), and it frees the proposal's draft slot.
+    try {
+        const cols = db.prepare('PRAGMA table_info(task_proposal_draft_links)').all();
+        if (!cols.some(c => c.name === 'status'))
+            db.exec("ALTER TABLE task_proposal_draft_links ADD COLUMN status TEXT NOT NULL DEFAULT 'active'");
+        if (!cols.some(c => c.name === 'discarded_by'))
+            db.exec('ALTER TABLE task_proposal_draft_links ADD COLUMN discarded_by TEXT');
+        if (!cols.some(c => c.name === 'discarded_at'))
+            db.exec('ALTER TABLE task_proposal_draft_links ADD COLUMN discarded_at TEXT');
+    }
+    catch { /* best-effort additive migration */ }
+    // PARTIAL UNIQUE: at most one ACTIVE draft per proposal (discarded links are retained but excluded), so a
+    // discarded draft truly frees the slot. Replaces the old full unique index on proposal_id.
+    try {
+        db.exec('DROP INDEX IF EXISTS idx_tpdl_proposal');
+    }
+    catch { /* noop */ }
+    db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_tpdl_proposal_active ON task_proposal_draft_links(proposal_id) WHERE status = 'active'");
+}
+/**
+ * case_id threads a case end to end: proposal → task → PR. For a task converted from a proposal it is that
+ * source proposal id (so proposer + contributor + PR all quote the same id); for a directly-created task it
+ * is the task id itself. Guarded: the link table may be absent in minimal setups → fall back to the task id.
+ */
+export function caseIdForTask(db, taskId) {
+    try {
+        const link = db.prepare('SELECT proposal_id FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
+        if (link?.proposal_id)
+            return link.proposal_id;
+    }
+    catch { /* link table absent → case_id is the task id */ }
+    return taskId;
 }
 const strList = (v) => Array.isArray(v) ? v.slice(0, 50).map(s => String(s).slice(0, 500)).filter(s => s.trim()) : [];
 const txt = (v) => (v ?? '').trim();
@@ -49,8 +84,8 @@ export function createDraftFromProposal(db, a) {
         return { error: 'proposal not found', error_code: 'PROPOSAL_NOT_FOUND' };
     if (prop.status === 'rejected' || prop.status === 'converted')
         return { error: `proposal already ${prop.status}`, error_code: 'PROPOSAL_TERMINAL' };
-    // one draft per proposal (without using a terminal proposal status as the guard)
-    const existingLink = db.prepare('SELECT task_id FROM task_proposal_draft_links WHERE proposal_id = ?').get(a.proposalId);
+    // one ACTIVE draft per proposal (a discarded draft is soft-deleted and frees the slot; not terminal-status based)
+    const existingLink = db.prepare("SELECT task_id FROM task_proposal_draft_links WHERE proposal_id = ? AND status != 'discarded'").get(a.proposalId);
     if (existingLink)
         return { error: `a task draft already exists for this proposal (${existingLink.task_id})`, error_code: 'PROPOSAL_HAS_DRAFT' };
     // draft risk stays low/medium (high/critical metadata rules are out of scope for this PR)
@@ -60,6 +95,20 @@ export function createDraftFromProposal(db, a) {
     if (a.riskLevel === 'high' || a.riskLevel === 'critical')
         return { error: 'draft risk_level must be low or medium (high/critical deferred)', error_code: 'RISK_TOO_HIGH_FOR_DRAFT' };
     const taskType = (a.taskType && TASK_TYPES.includes(a.taskType)) ? a.taskType : 'other';
+    // (a) #34/#5: an OPTIONAL real effort estimate. Provided → validated + stored; omitted → 0–0 placeholder
+    // (draft stays internal/unclaimable, and publishDraftBuildTask fails closed until a real estimate exists).
+    let durMin = 0, durMax = 0;
+    if (a.estimatedDurationMinMinutes !== undefined || a.estimatedDurationMaxMinutes !== undefined) {
+        const mn = Number(a.estimatedDurationMinMinutes), mx = Number(a.estimatedDurationMaxMinutes);
+        if (!Number.isInteger(mn) || !Number.isInteger(mx) || mn < 0 || mx < mn || mx < 1)
+            return { error: 'estimated_duration must be integer minutes with max >= min and max >= 1 (a real, non-zero estimate)', error_code: 'BAD_ESTIMATE' };
+        durMin = mn;
+        durMax = mx;
+    }
+    if (a.estimatedAgentBudget !== undefined && !AGENT_BUDGETS.includes(a.estimatedAgentBudget))
+        return { error: 'invalid estimated_agent_budget', error_code: 'BAD_AGENT_BUDGET' };
+    if (a.estimatedContextSize !== undefined && !CONTEXT_SIZES.includes(a.estimatedContextSize))
+        return { error: 'invalid estimated_context_size', error_code: 'BAD_CONTEXT_SIZE' };
     // 2) assemble the agent-handoff fields and VALIDATE completeness BEFORE creating anything — the existing
     //    task model requires these to be executable, so we never create an incomplete/orphan task.
     const allowed = strList(a.allowedPaths);
@@ -100,10 +149,10 @@ export function createDraftFromProposal(db, a) {
         expected_results: expected,
         deliverables: deliver,
         definition_of_done: dod,
-        estimated_duration_min_minutes: 0,
-        estimated_duration_max_minutes: 0,
-        estimated_context_size: 'small',
-        estimated_agent_budget: 'minimal',
+        estimated_duration_min_minutes: durMin,
+        estimated_duration_max_minutes: durMax,
+        estimated_context_size: a.estimatedContextSize ?? 'small',
+        estimated_agent_budget: a.estimatedAgentBudget ?? 'minimal',
         value_state: 'uncommitted',
         contribution_type: 'task',
         accountable_party_required: true,
@@ -123,7 +172,7 @@ export function listDraftBuildTasks(db) {
     FROM build_tasks t
     JOIN build_task_agent_metadata m ON m.task_id = t.id
     LEFT JOIN task_proposal_draft_links l ON l.task_id = t.id
-    WHERE m.audience = 'internal' AND t.status = 'open'
+    WHERE m.audience = 'internal' AND t.status = 'open' AND (l.status IS NULL OR l.status != 'discarded')
     ORDER BY t.created_at DESC LIMIT 200
   `).all();
 }
@@ -151,7 +200,7 @@ export function validateDraftForPublish(task, meta) {
  * so a public, claimable task can never coexist with a rejected source proposal. The audience flip + proposal
  * conversion run in one transaction (both or neither).
  */
-export function publishDraftBuildTask(db, taskId, adminId) {
+export function publishDraftBuildTask(db, taskId, adminId, estimate) {
     const meta = getBuildTaskAgentMetadata(db, taskId);
     if (!meta)
         return { error: 'task has no draft metadata', error_code: 'NOT_A_DRAFT' };
@@ -164,9 +213,11 @@ export function publishDraftBuildTask(db, taskId, adminId) {
     if (missing.length > 0)
         return { error: `draft incomplete — fill before publish: ${missing.join(', ')}`, error_code: 'DRAFT_INCOMPLETE', missing };
     // validate the linked proposal FIRST — do not publish on top of a rejected / elsewhere-converted proposal.
-    const link = db.prepare('SELECT proposal_id FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
+    const link = db.prepare('SELECT proposal_id, status FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
     let proposalToConvert = null;
     if (link) {
+        if (link.status === 'discarded')
+            return { error: 'draft was discarded — cannot publish', error_code: 'DRAFT_DISCARDED' };
         const prop = db.prepare('SELECT status, converted_ref FROM task_proposals WHERE id = ?').get(link.proposal_id);
         if (prop) {
             if (prop.status === 'rejected')
@@ -177,8 +228,34 @@ export function publishDraftBuildTask(db, taskId, adminId) {
                 proposalToConvert = link.proposal_id;
         }
     }
-    // all validation passed → publish atomically: flip audience + (if applicable) mark the proposal converted.
+    // (a) #34/#5: FAIL-CLOSED on a placeholder estimate (checked AFTER proposal validity, so a dead/rejected
+    // source surfaces its own error first). A published task must carry a REAL effort estimate (non 0–0 /
+    // non-null duration), else the claim guard would correctly refuse it as manual_review forever ("published
+    // but unclaimable"). The maintainer may supply the estimate here; otherwise the draft's stored estimate must
+    // already be real. The override is validated + persisted inside the publish transaction below.
+    const overrideEstimate = !!estimate && (estimate.minMinutes !== undefined || estimate.maxMinutes !== undefined);
+    let effMin = meta.estimated_duration_min_minutes;
+    let effMax = meta.estimated_duration_max_minutes;
+    if (overrideEstimate) {
+        const mn = Number(estimate.minMinutes), mx = Number(estimate.maxMinutes);
+        if (!Number.isInteger(mn) || !Number.isInteger(mx) || mn < 0 || mx < mn || mx < 1)
+            return { error: 'estimated_duration must be integer minutes with max >= min and max >= 1 (a real, non-zero estimate)', error_code: 'BAD_ESTIMATE' };
+        effMin = mn;
+        effMax = mx;
+    }
+    if (estimate?.budget !== undefined && !AGENT_BUDGETS.includes(estimate.budget))
+        return { error: 'invalid estimated_agent_budget', error_code: 'BAD_AGENT_BUDGET' };
+    if (estimate?.contextSize !== undefined && !CONTEXT_SIZES.includes(estimate.contextSize))
+        return { error: 'invalid estimated_context_size', error_code: 'BAD_CONTEXT_SIZE' };
+    const estimateReal = effMin != null && effMax != null && !(effMin === 0 && effMax === 0);
+    if (!estimateReal)
+        return { error: 'a real effort estimate is required before publishing (the draft still has the 0–0 placeholder); supply estimate {minMinutes, maxMinutes}', error_code: 'DRAFT_ESTIMATE_REQUIRED' };
+    // all validation passed → publish atomically: persist any estimate override + flip audience + (if
+    // applicable) mark the proposal converted. All-or-nothing.
     db.transaction(() => {
+        if (overrideEstimate || estimate?.budget !== undefined || estimate?.contextSize !== undefined) {
+            setBuildTaskEstimate(db, taskId, { minMinutes: effMin, maxMinutes: effMax, budget: estimate?.budget, contextSize: estimate?.contextSize });
+        }
         setBuildTaskAudience(db, taskId, 'public');
         logTaskEvent(db, taskId, adminId, t.status, t.status, 'published from draft (audience → public)');
         if (proposalToConvert) {
@@ -189,3 +266,95 @@ export function publishDraftBuildTask(db, taskId, adminId) {
     })();
     return { ok: true, task_id: taskId };
 }
+/**
+ * DISCARD an unpublished internal draft — SOFT-delete (status='discarded'); the link row is RETAINED for
+ * provenance (retroactive reward / anchor-side traceability / dispute). Discarding frees the proposal's draft
+ * slot (createDraftFromProposal counts only non-discarded links), so a fresh draft can be created.
+ *
+ * Fail-closed: ONLY an internal, unpublished, unclaimed draft may be discarded. A published draft (audience
+ * flipped to public), a claimed task, or an already-converted source proposal is REFUSED — discard never
+ * touches anything that's live on the board or already accepted. Scope is discard only (NOT a generic edit).
+ */
+export function discardDraft(db, taskId, adminId) {
+    const link = db.prepare('SELECT proposal_id, status FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
+    if (!link)
+        return { error: 'no draft link for this task', error_code: 'NOT_FOUND' };
+    if (link.status === 'discarded')
+        return { ok: true, task_id: taskId, already_discarded: true }; // idempotent
+    // fail-closed guards — only an internal, unpublished, unclaimed draft of a non-converted proposal
+    const meta = getBuildTaskAgentMetadata(db, taskId);
+    if (!meta)
+        return { error: 'task has no draft metadata', error_code: 'NOT_A_DRAFT' };
+    if (meta.audience !== 'internal')
+        return { error: 'task is published (audience is not internal) — cannot discard', error_code: 'ALREADY_PUBLISHED' };
+    const t = db.prepare('SELECT status, claimer_id FROM build_tasks WHERE id = ?').get(taskId);
+    if (!t)
+        return { error: 'task not found', error_code: 'NOT_FOUND' };
+    if (t.claimer_id)
+        return { error: 'task is claimed — cannot discard', error_code: 'DRAFT_CLAIMED' };
+    const prop = db.prepare('SELECT status FROM task_proposals WHERE id = ?').get(link.proposal_id);
+    if (prop && prop.status === 'converted')
+        return { error: 'source proposal already converted — cannot discard', error_code: 'ALREADY_CONVERTED' };
+    db.prepare("UPDATE task_proposal_draft_links SET status = 'discarded', discarded_by = ?, discarded_at = datetime('now') WHERE task_id = ?").run(adminId, taskId);
+    return { ok: true, task_id: taskId };
+}
+/**
+ * Full stored body of an UNPUBLISHED internal draft — for pre-publish PREVIEW so a maintainer publishes
+ * against the exact content that will go live (not a blind button). Returns null unless the task is an
+ * internal-audience draft (getBuildTaskWithAgentMetadata's member/public scopes deliberately hide internal,
+ * so this admin-only read exists). Read-only — does not change publish behavior.
+ */
+export function getDraftBuildTaskDetail(db, taskId) {
+    const meta = getBuildTaskAgentMetadata(db, taskId);
+    if (!meta || meta.audience !== 'internal')
+        return null; // only unpublished internal drafts are previewable here
+    const t = db.prepare('SELECT id, title, area, description, rfc_ref, status, created_by, created_at FROM build_tasks WHERE id = ?').get(taskId);
+    if (!t)
+        return null;
+    const link = db.prepare('SELECT proposal_id, status FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
+    return {
+        ...t,
+        source_proposal_id: link?.proposal_id ?? null,
+        draft_link_status: link?.status ?? null,
+        agent_metadata: meta, // full body: allowed/forbidden paths, prohibited_actions, acceptance_criteria, verification_commands, deliverables, definition_of_done, expected_results, risk_level, auto_claimable, …
+    };
+}
+/**
+ * Recovery: WITHDRAW a published task that was converted from a proposal — pull it off the public board and
+ * REOPEN the source proposal so a corrected draft can be built. Fail-closed: only an UNCLAIMED, open,
+ * published task (audience='public') may be withdrawn (a claimed / in_review / done task is refused).
+ *
+ * Soft-delete semantics (provenance retained): the build_task is set status='abandoned' (off the board, row
+ * kept), the draft link is marked 'discarded' (kept, frees the slot), and the proposal is un-converted
+ * (status='new', converted_ref cleared) so createDraftFromProposal works again. Scope = recovery only.
+ */
+export function withdrawPublishedTask(db, taskId, adminId) {
+    releaseExpiredClaims(db); // an expired claim is effectively unclaimed
+    const meta = getBuildTaskAgentMetadata(db, taskId);
+    if (!meta)
+        return { error: 'task not found', error_code: 'NOT_FOUND' };
+    if (meta.audience !== 'public')
+        return { error: 'task is not published (use discard for an internal draft)', error_code: 'NOT_PUBLISHED' };
+    const t = db.prepare('SELECT status, claimer_id FROM build_tasks WHERE id = ?').get(taskId);
+    if (!t)
+        return { error: 'task not found', error_code: 'NOT_FOUND' };
+    if (t.claimer_id || t.status !== 'open')
+        return { error: `task is ${t.status}${t.claimer_id ? ' (claimed)' : ''} — only an UNCLAIMED open task can be withdrawn`, error_code: 'TASK_CLAIMED' };
+    const link = db.prepare('SELECT proposal_id, status FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
+    let reopened = null;
+    db.transaction(() => {
+        db.prepare("UPDATE build_tasks SET status = 'abandoned', updated_at = datetime('now') WHERE id = ?").run(taskId);
+        logTaskEvent(db, taskId, adminId, t.status, 'abandoned', 'withdrawn by admin — published task pulled off the board (recovery)');
+        if (link) {
+            if (link.status !== 'discarded')
+                db.prepare("UPDATE task_proposal_draft_links SET status = 'discarded', discarded_by = ?, discarded_at = datetime('now') WHERE task_id = ?").run(adminId, taskId);
+            const prop = db.prepare('SELECT status, converted_ref FROM task_proposals WHERE id = ?').get(link.proposal_id);
+            if (prop && prop.status === 'converted' && prop.converted_ref === taskId) {
+                db.prepare("UPDATE task_proposals SET status = 'new', converted_ref = NULL, reviewer_id = NULL, review_note = ?, updated_at = datetime('now') WHERE id = ?")
+                    .run(`reopened: published task ${taskId} withdrawn by admin`, link.proposal_id);
+                reopened = link.proposal_id;
+            }
+        }
+    })();
+    return { ok: true, task_id: taskId, reopened_proposal_id: reopened };
+}

package/dist/layer2-business/L2-9-contribution/task-proposal-store.js

@@ -15,6 +15,7 @@ const CREATE_TABLE = `
     status                TEXT NOT NULL DEFAULT 'new' CHECK (status IN ('new','needs_info','rejected','converted')),
     reviewer_id           TEXT,
     review_note           TEXT CHECK (review_note IS NULL OR length(review_note) <= 2000),
+    public_reply          TEXT CHECK (public_reply IS NULL OR length(public_reply) <= 2000),
     converted_ref         TEXT CHECK (converted_ref IS NULL OR length(converted_ref) <= 500),
     created_at            TEXT NOT NULL DEFAULT (datetime('now')),
     updated_at            TEXT NOT NULL DEFAULT (datetime('now'))
@@ -24,6 +25,14 @@ const CREATE_INDEX = `CREATE INDEX IF NOT EXISTS idx_task_proposals_status ON ta
 export function initTaskProposalSchema(db) {
     db.exec(CREATE_TABLE);
     db.exec(CREATE_INDEX);
+    // Additive migration for pre-existing DBs (ALTER after CREATE; fresh DBs already have the column via CREATE_TABLE).
+    // public_reply = the proposer-facing reply (distinct from the admin-internal review_note).
+    try {
+        const cols = db.prepare('PRAGMA table_info(task_proposals)').all();
+        if (!cols.some(c => c.name === 'public_reply'))
+            db.exec('ALTER TABLE task_proposals ADD COLUMN public_reply TEXT');
+    }
+    catch { /* best-effort additive migration */ }
 }
 /** Validate a public submission — fail-closed: bad/oversized fields are rejected, never silently truncated. */
 export function validateProposalInput(body) {
@@ -102,9 +111,21 @@ export function listTaskProposals(db, filter = {}) {
         params.push(filter.status);
     }
     return db.prepare(`SELECT id, title, summary, suggested_area, expected_outcome, source_ref, proposer_account_id,
-    proposer_github_login, status, reviewer_id, review_note, converted_ref, created_at, updated_at FROM task_proposals
+    proposer_github_login, status, reviewer_id, review_note, public_reply, converted_ref, created_at, updated_at FROM task_proposals
     ${where.length ? 'WHERE ' + where.join(' AND ') : ''} ORDER BY created_at DESC LIMIT 200`).all(...params);
 }
+/**
+ * Proposer-facing read: returns ONLY the caller's own proposals, and ONLY proposer-safe fields.
+ * Deliberately excludes the admin-internal `review_note`, `reviewer_id`, and never returns other users' rows
+ * (least-privilege; the proposer sees status + the proposer-facing `public_reply` + converted_ref).
+ */
+export function listMyProposals(db, accountId) {
+    if (!accountId)
+        return [];
+    return db.prepare(`SELECT id, title, summary, suggested_area, expected_outcome, source_ref, status,
+    public_reply, converted_ref, created_at, updated_at FROM task_proposals
+    WHERE proposer_account_id = ? ORDER BY created_at DESC LIMIT 100`).all(accountId);
+}
 /**
  * Review a proposal: needs_info / rejected / converted. NO build_task is created here (conversion is a
  * later manual maintainer step — deferred). Terminal states (rejected/converted) cannot be re-reviewed.
@@ -112,18 +133,22 @@ export function listTaskProposals(db, filter = {}) {
  * product decision — the non-code contribution evidence chain { proposer → reviewer → converted_ref }.
  * Recording only; no reward/score is computed.
  */
-export function reviewTaskProposal(db, id, reviewerId, status, note, convertedRef) {
+export function reviewTaskProposal(db, id, reviewerId, status, note, convertedRef, publicReply) {
     if (!REVIEW_TARGETS.includes(status))
         return { error: 'status must be needs_info | rejected | converted', code: 'BAD_STATUS' };
     if (convertedRef != null && (typeof convertedRef !== 'string' || convertedRef.length > CONVERTED_REF_MAX))
         return { error: 'converted_ref invalid/too long', code: 'CONVERTED_REF_TOO_LONG' };
+    if (publicReply != null && typeof publicReply !== 'string')
+        return { error: 'public_reply must be a string', code: 'PUBLIC_REPLY_INVALID' };
     const cur = db.prepare('SELECT status FROM task_proposals WHERE id = ?').get(id);
     if (!cur)
         return { error: 'proposal not found', code: 'NOT_FOUND' };
     if (cur.status === 'rejected' || cur.status === 'converted')
         return { error: `proposal already ${cur.status}`, code: 'ALREADY_TERMINAL' };
     const ref = status === 'converted' && typeof convertedRef === 'string' && convertedRef.trim() ? convertedRef.trim() : null;
-    db.prepare(`UPDATE task_proposals SET status = ?, reviewer_id = ?, review_note = ?, converted_ref = ?, updated_at = datetime('now') WHERE id = ?`)
-        .run(status, reviewerId, note ? String(note).slice(0, NOTE_MAX) : null, ref, id);
+    // public_reply: update only when provided (COALESCE keeps a prior reply if this review omits it).
+    const reply = publicReply != null ? String(publicReply).slice(0, NOTE_MAX) : null;
+    db.prepare(`UPDATE task_proposals SET status = ?, reviewer_id = ?, review_note = ?, public_reply = COALESCE(?, public_reply), converted_ref = ?, updated_at = datetime('now') WHERE id = ?`)
+        .run(status, reviewerId, note ? String(note).slice(0, NOTE_MAX) : null, reply, ref, id);
     return { id, status, converted_ref: ref };
 }

package/dist/ledger.js

@@ -42,7 +42,7 @@ export function debitStakeThenBalance(db, userId, amountU) {
 }
 /**
  * 通用基金/池表的【绝对值】入账(整数 base-units):读当前→加 delta→写 toDecimal。
- *   用于 global_fund / management_bonus_pool / commission_reserve / charity_fund 等单行池表。
+ *   用于 global_fund / protocol_reserve_pool / commission_reserve / charity_fund 等单行池表。
  *   table / 列名 / whereClause 均为【代码字面量】(非用户输入)→ 无 SQL 注入面。
  *   行不存在 → UPDATE 影响 0 行(与历史相对更新一致)。
  */

package/dist/pwa/admin-audit.js

@@ -0,0 +1,38 @@
+import { generateId } from '../layer0-foundation/L0-1-database/schema.js';
+/** Default context for an action logged without explicit accountability — NOT contribution-eligible. */
+function normalizeContext(ctx) {
+    return {
+        actor_type: ctx?.actorType ?? 'unknown_agent',
+        actor_ref: ctx?.actorRef ?? null,
+        agent_mode: ctx?.agentMode ?? 'unknown_agent',
+        human_authorization_id: ctx?.humanAuthorizationId ?? null,
+        mandate_id: ctx?.mandateId ?? null,
+        approval_kind: ctx?.approvalKind ?? null,
+        conflict_disclosure: ctx?.conflictDisclosure ?? 'unknown',
+        provenance: ctx?.provenance ?? null,
+    };
+}
+/**
+ * Write one admin_audit_log row (with `detail._ctx` accountability context) and return its id. The id
+ * is what the coordination ingestion engine references as `admin_audit_log_id`.
+ */
+export function logAdminAction(db, input) {
+    const id = generateId('audit');
+    const detail = JSON.stringify({ ...(input.detail ?? {}), _ctx: normalizeContext(input.context) });
+    db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail) VALUES (?,?,?,?,?,?)`)
+        .run(id, input.adminId, input.action, input.targetType ?? null, input.targetId ?? null, detail);
+    return id;
+}
+/** Read back the accountability context of an audit row. Absent `_ctx` → unknown / not eligible. */
+export function readAdminActionContext(detailJson) {
+    if (!detailJson)
+        return normalizeContext();
+    try {
+        const parsed = JSON.parse(detailJson);
+        const ctx = parsed && typeof parsed === 'object' ? parsed._ctx : undefined;
+        return ctx && typeof ctx === 'object' ? ctx : normalizeContext();
+    }
+    catch {
+        return normalizeContext();
+    }
+}

package/dist/pwa/anti-abuse-thresholds.js

@@ -0,0 +1,135 @@
+/** 默认值 === 抽取前的硬编码字面量。修改这里 = 修改全协议默认行为。 */
+export const DEFAULT_ANTI_ABUSE_THRESHOLDS = {
+    trustDisputePenalty: 10,
+    trustSybilFreeThreshold: 3,
+    trustSybilPenalty: 5,
+    trustCrossPenalty: 3,
+    trustRatelimitPenalty: 2,
+    trustLevelTrusted: 20,
+    trustLevelQuality: 50,
+    trustLevelLegend: 80,
+    strikeWarnWindowDays: 7,
+    strikeWarnEscalateCount: 1,
+    strikeSuspendWindowDays: 30,
+    strikeSuspendEscalateCount: 2,
+    strikeWarnExpiryHours: 24,
+    strikeSuspendExpiryDays: 7,
+    outlierWindowDays: 180,
+    outlierSuspendCount: 3,
+    outlierRevokeCount: 5,
+    outlierSuspendDays: 30,
+};
+/**
+ * protocol_params 注册定义（spread 进 server.ts 的 DEFAULT_PARAMS）。
+ * value 必须与 DEFAULT_ANTI_ABUSE_THRESHOLDS 完全一致（测试强制校验）。
+ */
+export const ANTI_ABUSE_PARAMS = [
+    // P1-2 agent 信任公式（公开框架 + 治理可调系数）。等级阈值 cap=1000 给治理收紧空间。
+    { key: 'agent_trust_dispute_penalty', value: '10', type: 'number', description: 'agent 信任分:每次败诉 dispute(refund/partial)扣分(#420 P1-2)', category: 'security', min: 0, max: 100 },
+    { key: 'agent_trust_sybil_free_threshold', value: '3', type: 'number', description: 'agent 信任分:同 IP 注册账户数 ≤ 此值不计 sybil 罚分(含本账户)(#420 P1-2)', category: 'security', min: 0, max: 100 },
+    { key: 'agent_trust_sybil_penalty', value: '5', type: 'number', description: 'agent 信任分:超出 free 阈值后每多 1 个同 IP 账户扣分(#420 P1-2)', category: 'security', min: 0, max: 100 },
+    { key: 'agent_trust_cross_penalty', value: '3', type: 'number', description: 'agent 信任分:每次放置同支审计(commission cross)命中扣分(#420 P1-2)', category: 'security', min: 0, max: 100 },
+    { key: 'agent_trust_ratelimit_penalty', value: '2', type: 'number', description: 'agent 信任分:30d 内每次 429 限速命中扣分(#420 P1-2)', category: 'security', min: 0, max: 100 },
+    { key: 'agent_trust_level_trusted', value: '20', type: 'number', description: 'agent 信任分 ≥ 此值 → trusted 级(#420 P1-2;等级 gate 速率上限)', category: 'security', min: 0, max: 1000 },
+    { key: 'agent_trust_level_quality', value: '50', type: 'number', description: 'agent 信任分 ≥ 此值 → quality 级(#420 P1-2)', category: 'security', min: 0, max: 1000 },
+    { key: 'agent_trust_level_legend', value: '80', type: 'number', description: 'agent 信任分 ≥ 此值 → legend 级(#420 P1-2)', category: 'security', min: 0, max: 1000 },
+    // P1-4 agent strike 升级阶梯（公开 consequence-transparency,见 negative-space.ts;数值治理可调）
+    { key: 'agent_strike_warn_window_days', value: '7', type: 'number', description: 'agent strike:统计 warning 的回看窗口(天)(#420 P1-4)', category: 'security', min: 1, max: 365 },
+    { key: 'agent_strike_warn_escalate_count', value: '1', type: 'number', description: 'agent strike:窗口内已有 ≥N 次 warning 时本次 warning 升级为 suspend_7d(默认 1=累计第 2 次升级)(#420 P1-4)', category: 'security', min: 1, max: 100 },
+    { key: 'agent_strike_suspend_window_days', value: '30', type: 'number', description: 'agent strike:统计 suspend_7d 的回看窗口(天)(#420 P1-4)', category: 'security', min: 1, max: 365 },
+    { key: 'agent_strike_suspend_escalate_count', value: '2', type: 'number', description: 'agent strike:窗口内已有 ≥N 次 suspend_7d 时升级为 permanent(默认 2=累计第 3 次升级)(#420 P1-4)', category: 'security', min: 1, max: 100 },
+    { key: 'agent_strike_warn_expiry_hours', value: '24', type: 'number', description: 'agent strike:warning 自动过期小时数(#420 P1-4)', category: 'security', min: 1, max: 720 },
+    { key: 'agent_strike_suspend_expiry_days', value: '7', type: 'number', description: 'agent strike:suspend_7d 自动过期天数(#420 P1-4)', category: 'security', min: 1, max: 365 },
+    // P1-3 verifier outlier 处罚阈值（少数票 was_majority=0 即时处罚;非 playbook §6.2 confirmed_wrong cron）
+    { key: 'verifier_outlier_window_days', value: '180', type: 'number', description: 'verifier outlier:统计少数票(was_majority=0)的回看窗口(天)(#420 P1-3)', category: 'governance', min: 1, max: 730 },
+    { key: 'verifier_outlier_suspend_count', value: '3', type: 'number', description: 'verifier outlier:窗口内 ≥N 次 → 暂停资格(#420 P1-3)', category: 'governance', min: 1, max: 100 },
+    { key: 'verifier_outlier_revoke_count', value: '5', type: 'number', description: 'verifier outlier:窗口内 ≥N 次 → 永久撤销资格(#420 P1-3)', category: 'governance', min: 1, max: 100 },
+    { key: 'verifier_outlier_suspend_days', value: '30', type: 'number', description: 'verifier outlier:暂停时长(天)(#420 P1-3)', category: 'governance', min: 1, max: 365 },
+];
+// ── 同步读取器（与生产热路径同步语义:better-sqlite3 prepared get）──
+function num(db, key, fallback) {
+    try {
+        const r = db.prepare('SELECT value FROM protocol_params WHERE key = ?').get(key);
+        if (!r)
+            return fallback;
+        const n = Number(r.value);
+        return Number.isFinite(n) ? n : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** 用于会被插入 SQL 字符串的窗口天数:强制非负整数(injection-safe + 语义正确)。 */
+function intNum(db, key, fallback) {
+    const n = Math.round(num(db, key, fallback));
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+/** 从 protocol_params 读取全部反滥用阈值;缺行/坏值回落默认(= 当前生产行为)。 */
+export function readAntiAbuseThresholds(db) {
+    const d = DEFAULT_ANTI_ABUSE_THRESHOLDS;
+    return {
+        trustDisputePenalty: num(db, 'agent_trust_dispute_penalty', d.trustDisputePenalty),
+        trustSybilFreeThreshold: num(db, 'agent_trust_sybil_free_threshold', d.trustSybilFreeThreshold),
+        trustSybilPenalty: num(db, 'agent_trust_sybil_penalty', d.trustSybilPenalty),
+        trustCrossPenalty: num(db, 'agent_trust_cross_penalty', d.trustCrossPenalty),
+        trustRatelimitPenalty: num(db, 'agent_trust_ratelimit_penalty', d.trustRatelimitPenalty),
+        trustLevelTrusted: num(db, 'agent_trust_level_trusted', d.trustLevelTrusted),
+        trustLevelQuality: num(db, 'agent_trust_level_quality', d.trustLevelQuality),
+        trustLevelLegend: num(db, 'agent_trust_level_legend', d.trustLevelLegend),
+        strikeWarnWindowDays: intNum(db, 'agent_strike_warn_window_days', d.strikeWarnWindowDays),
+        strikeWarnEscalateCount: num(db, 'agent_strike_warn_escalate_count', d.strikeWarnEscalateCount),
+        strikeSuspendWindowDays: intNum(db, 'agent_strike_suspend_window_days', d.strikeSuspendWindowDays),
+        strikeSuspendEscalateCount: num(db, 'agent_strike_suspend_escalate_count', d.strikeSuspendEscalateCount),
+        strikeWarnExpiryHours: num(db, 'agent_strike_warn_expiry_hours', d.strikeWarnExpiryHours),
+        strikeSuspendExpiryDays: num(db, 'agent_strike_suspend_expiry_days', d.strikeSuspendExpiryDays),
+        outlierWindowDays: intNum(db, 'verifier_outlier_window_days', d.outlierWindowDays),
+        outlierSuspendCount: num(db, 'verifier_outlier_suspend_count', d.outlierSuspendCount),
+        outlierRevokeCount: num(db, 'verifier_outlier_revoke_count', d.outlierRevokeCount),
+        outlierSuspendDays: num(db, 'verifier_outlier_suspend_days', d.outlierSuspendDays),
+    };
+}
+// ── 纯决策函数（生产 + 测试共用;无副作用,不读 db）──
+/** P1-2:trust 分 → 等级。镜像原 server.ts:3818-3821 的 ≥ 级联。 */
+export function agentTrustLevel(score, t) {
+    if (score >= t.trustLevelLegend)
+        return 'legend';
+    if (score >= t.trustLevelQuality)
+        return 'quality';
+    if (score >= t.trustLevelTrusted)
+        return 'trusted';
+    return 'new';
+}
+/** P1-2:sybil 罚分。镜像原 `sybilSize > free ? -(sybilSize-free)*pen : 0`。返回非正数。 */
+export function agentSybilPenalty(sybilSize, t) {
+    return sybilSize > t.trustSybilFreeThreshold ? -(sybilSize - t.trustSybilFreeThreshold) * t.trustSybilPenalty : 0;
+}
+/**
+ * P1-4:strike 升级判定。镜像原 server.ts:4493-4502。
+ * priorWarnings = 窗口内已有未过期 warning 数;priorSuspends = 窗口内已有 suspend_7d 数。
+ */
+export function agentStrikeSeverity(initial, priorWarnings, priorSuspends, t) {
+    let severity = initial;
+    let escalated = false;
+    if (initial === 'warning' && priorWarnings >= t.strikeWarnEscalateCount) {
+        severity = 'suspend_7d';
+        escalated = true;
+    }
+    if (initial === 'suspend_7d' || severity === 'suspend_7d') {
+        if (priorSuspends >= t.strikeSuspendEscalateCount) {
+            severity = 'permanent';
+            escalated = true;
+        }
+    }
+    return { severity, escalated };
+}
+/**
+ * P1-3:verifier outlier 累计数 → 处罚档位（不含 existing/dup 守卫,由调用方各自施加）。
+ * 镜像原 revoke-优先、suspend-其次 的阈值比较。
+ */
+export function verifierOutlierBand(count, t) {
+    if (count >= t.outlierRevokeCount)
+        return 'revoke';
+    if (count >= t.outlierSuspendCount)
+        return 'suspend';
+    return 'none';
+}

package/dist/pwa/cf-origin-guard.js

@@ -0,0 +1,33 @@
+import { timingSafeEqual } from 'node:crypto';
+export const CF_ORIGIN_HEADER = 'x-cf-origin-secret';
+function safeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+export function createCfOriginGuard(env = process.env) {
+    const mode = (env.CF_ORIGIN_GUARD_MODE || 'off').toLowerCase();
+    const secret = env.CF_ORIGIN_SHARED_SECRET || '';
+    const exempt = new Set((env.CF_ORIGIN_GUARD_EXEMPT || '/api/health,/healthz')
+        .split(',').map(s => s.trim()).filter(Boolean));
+    return function cfOriginGuard(req, res, next) {
+        if (mode === 'off')
+            return next();
+        if (exempt.has(req.path))
+            return next();
+        if (!secret) {
+            if (mode === 'enforce') {
+                console.error('[cf-origin-guard] enforce set but CF_ORIGIN_SHARED_SECRET is empty — failing OPEN (no block)');
+            }
+            return next();
+        }
+        const got = req.get(CF_ORIGIN_HEADER) || '';
+        if (got && safeEqual(got, secret))
+            return next(); // arrived via Cloudflare
+        if (mode === 'observe') {
+            console.warn(`[cf-origin-guard] observe: would block direct-origin ${req.method} ${req.path} ip=${req.ip}`);
+            return next();
+        }
+        res.status(403).json({ error: 'direct origin access not allowed; use the public endpoint', error_code: 'CF_ORIGIN_ONLY' });
+    };
+}

package/dist/pwa/contract-fingerprint.js

@@ -35,6 +35,7 @@ export const CONTRACT_CHANGES = [
     { contract_version: 2, date: '2026-06-06', surface: 'entity', kind: 'added', summary: '§① entity dictionary gains product + dispute entities (conservative public fields; dispute = redacted dispute_cases) + goal_index pointer. Additive — existing order entity unchanged; agents may ignore.' },
     { contract_version: 3, date: '2026-06-09', surface: 'entity', kind: 'changed', summary: '§① order lifecycle: corrected declined_nofault state meaning text — it is NOT terminal (transitions declined_nofault→completed on settlement). Dropped the contradictory "(terminal)" label that conflicted with the auto-derived terminal:false. Semantics/state-machine unchanged; text-only clarification for agents reading the entity dictionary.' },
     { contract_version: 4, date: '2026-06-09', surface: 'capability', kind: 'changed', summary: '§② capability matrix: POST /api/reviews/:type/:id/claim now requires the new "review_claim" action scope instead of being SAFE (unscoped). The review-claim path locks a 5 WAZ stake (escrow), so it belongs under default-deny accountability like other value writes. GET reviews endpoints stay open.', migration: 'A declared agent that calls review claim must add the "review_claim" scope to its api_key (or hold a Passkey, or declare "*"). Passkey-bound humans and "*" agents are unaffected; GET reviews unchanged.' },
+    { contract_version: 5, date: '2026-06-24', surface: 'integration', kind: 'added', summary: '§④ integration-contract entry (/.well-known/webaz-integration.json) gains an agent_quickstart block: a 60-second stranger-agent cold-start with discrete, machine-parseable fields (canonical_start_url, public_readonly_entrypoints, anonymous_allowed_actions, authenticated_required_actions, safe_next_actions, proposal_flow, contribution_boundary). Additive — no existing field changed; agents may ignore. NB: this surface is NOT covered by the §②/§① fingerprint, so it is registered here by hand.' },
 ];
 export function buildChangeFeed() {
     return {

package/dist/pwa/data/onboarding-cases.js

@@ -77,14 +77,14 @@ export const ONBOARDING_CASES = [
         ],
         decision_options: [
             { key: 'release_seller', text_zh: 'release_seller', text_en: 'release_seller' },
-            { key: 'refund_buyer', text_zh: 'refund_buyer + 物流 stake 优先赔买家 + management_bonus_pool 兜底', text_en: 'refund_buyer + logistics stake to buyer first + management_bonus_pool covers shortfall' },
+            { key: 'refund_buyer', text_zh: 'refund_buyer + 物流 stake 优先赔买家 + protocol_reserve_pool 兜底', text_en: 'refund_buyer + logistics stake to buyer first + protocol_reserve_pool covers shortfall' },
             { key: 'partial_refund', text_zh: 'partial_refund 50/50', text_en: 'partial_refund 50/50' },
             { key: 'liability_split', text_zh: 'liability_split(卖家一半 / 物流方一半)', text_en: 'liability_split (half seller / half logistics)' },
         ],
         expected_verdict: 'refund_buyer',
         key_principles: [
             'ARBITRATION-PLAYBOOK Case 2 物流卡顿 — 卖家无过错应保护',
-            'management_bonus_pool 来源 = ECONOMIC §3 ④a + 失效活动罚没',
+            'protocol_reserve_pool 来源 = ECONOMIC §3 ④a + 失效活动罚没',
             '资金流向:物流 stake 优先赔买家(不入 pool),pool 仅兜底差额',
             '物流方 debt_to_protocol 累计 → > 1000 WAZ 角色暂停',
         ],

package/dist/pwa/data/onboarding-quiz.js

@@ -128,7 +128,7 @@ export const ONBOARDING_QUIZ = [
         question_en: 'Case 2 logistics stuck: seller has shipping doc, buyer never received, logistics gone 45 days. Arbitrator should:',
         options: [
             { key: 'A', text_zh: 'release_seller(卖家无过错)', text_en: 'release_seller (seller has no fault)' },
-            { key: 'B', text_zh: 'refund_buyer + 物流 stake **优先赔买家**(不足部分由 management_bonus_pool 兜底差额)', text_en: 'refund_buyer + logistics stake **goes to buyer first** (shortfall covered by management_bonus_pool)' },
+            { key: 'B', text_zh: 'refund_buyer + 物流 stake **优先赔买家**(不足部分由 protocol_reserve_pool 兜底差额)', text_en: 'refund_buyer + logistics stake **goes to buyer first** (shortfall covered by protocol_reserve_pool)' },
             { key: 'C', text_zh: 'partial_refund 50/50', text_en: 'partial_refund 50/50' },
             { key: 'D', text_zh: 'liability_split,卖家一半物流方一半', text_en: 'liability_split, half seller half logistics' },
         ],

package/dist/pwa/economic-participation.js

@@ -9,10 +9,10 @@
  *   - 守恒是硬不变量:所有罚没【再分配,绝不增发】(settleFault)。
  *   - 诚实 status:已上线角色标 live;通用第三方承保方(无真实需求)标 scaffolded → 自有 RFC + enters-core 门控,不过早造接口。
  *
- * 公平三原则锚([[project_fairness_principle]]):公开透明 / 谁责任谁承担 / 无责方零成本。
+ * 公平三原则锚:公开透明 / 谁责任谁承担 / 无责方零成本。
  */
 import { SOFTWARE_VERSION, CONTRACT_VERSION } from '../version.js';
-const GH = 'https://github.com/seasonsagents-art/webaz/blob/main';
+const GH = 'https://github.com/webaz-protocol/webaz/blob/main';
 const BASE = 'https://webaz.xyz';
 export function buildEconomicParticipation(getParam) {
     const num = (k, f) => getParam(k, f);