@seasonkoh/webaz 0.1.25 → 0.1.27

package/dist/layer2-business/L2-9-contribution/build-task-quota.js

@@ -0,0 +1,337 @@
+import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
+export const QUOTA_TYPE_BUILD_TASK_CREATE = 'build_task.create';
+export const QUOTA_TYPES = new Set([QUOTA_TYPE_BUILD_TASK_CREATE]);
+export const URGENCIES = new Set(['low', 'normal', 'high']);
+// fallbacks when protocol_params is absent — kept in sync with DEFAULT_PARAMS in server.ts
+const DEFAULT_MAX_EXTRA_COUNT = 50;
+const DEFAULT_MAX_DURATION_HOURS = 72;
+const REASON_MIN = 5;
+const REASON_MAX = 2000;
+const MAX_LINKED_REFS = 20;
+const REF_MAX_LEN = 200;
+const isErr = (x) => !!x && typeof x === 'object' && 'error' in x;
+function paramNum(db, key, fallback) {
+    try {
+        const row = db.prepare('SELECT value FROM protocol_params WHERE key = ?').get(key);
+        if (!row || row.value == null)
+            return fallback;
+        const n = Number(row.value);
+        return Number.isFinite(n) ? n : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+export const maxQuotaExtraCount = (db) => paramNum(db, 'max_quota_extra_count', DEFAULT_MAX_EXTRA_COUNT);
+export const maxQuotaDurationHours = (db) => paramNum(db, 'max_quota_duration_hours', DEFAULT_MAX_DURATION_HOURS);
+export function initBuildTaskQuotaSchema(db) {
+    // requests + grant (single row); status drives the lifecycle
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS build_task_quota_requests (
+      id                       TEXT PRIMARY KEY,
+      quota_type               TEXT NOT NULL DEFAULT 'build_task.create',
+      requester_user_id        TEXT NOT NULL,
+      requested_extra_count    INTEGER NOT NULL,
+      reason                   TEXT NOT NULL,
+      linked_refs              TEXT,                                  -- JSON array of strings
+      urgency                  TEXT NOT NULL DEFAULT 'normal',        -- low | normal | high
+      requested_duration_hours INTEGER,
+      requested_expires_at     TEXT,
+      status                   TEXT NOT NULL DEFAULT 'pending',       -- pending|approved|rejected|expired|exhausted|revoked
+      decided_at               TEXT,
+      decided_by               TEXT,
+      decision_note            TEXT,
+      granted_count            INTEGER,
+      consumed_count           INTEGER NOT NULL DEFAULT 0,
+      expires_at               TEXT,
+      created_at               TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at               TEXT NOT NULL DEFAULT (datetime('now'))
+    )`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_bqr_status ON build_task_quota_requests(status, updated_at DESC)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_bqr_requester ON build_task_quota_requests(requester_user_id, status)`);
+    // at most one PENDING request per requester per quota type (a decided one frees the slot)
+    db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_bqr_one_pending ON build_task_quota_requests(requester_user_id, quota_type) WHERE status = 'pending'`);
+    // immutable audit/event history (append-only)
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS build_task_quota_events (
+      id          TEXT PRIMARY KEY,
+      request_id  TEXT NOT NULL,
+      actor_id    TEXT,
+      action      TEXT NOT NULL,   -- request_created|request_approved|request_rejected|grant_consumed|grant_expired|request_revoked
+      detail      TEXT,            -- JSON
+      created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+    )`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_bqe_request ON build_task_quota_events(request_id, created_at)`);
+}
+export function logQuotaEvent(db, requestId, actorId, action, detail) {
+    db.prepare(`INSERT INTO build_task_quota_events (id, request_id, actor_id, action, detail) VALUES (?,?,?,?,?)`)
+        .run(generateId('bqev'), requestId, actorId, action, detail ? JSON.stringify(detail) : null);
+}
+function parseRefs(input) {
+    const arr = Array.isArray(input) ? input : [];
+    return arr.map(r => String(r ?? '').trim()).filter(Boolean).slice(0, MAX_LINKED_REFS).map(r => r.slice(0, REF_MAX_LEN));
+}
+/** Lazily flip approved grants whose window has passed to 'expired' (audited). Best-effort, fail-closed. */
+export function expireStaleGrants(db) {
+    try {
+        const stale = db.prepare(`SELECT id FROM build_task_quota_requests
+       WHERE status = 'approved' AND expires_at IS NOT NULL AND datetime(expires_at) <= datetime('now')`).all();
+        for (const s of stale) {
+            db.prepare(`UPDATE build_task_quota_requests SET status='expired', updated_at=datetime('now') WHERE id = ? AND status='approved'`).run(s.id);
+            logQuotaEvent(db, s.id, null, 'grant_expired', null);
+        }
+    }
+    catch { /* table missing / fresh DB — nothing to expire */ }
+}
+export function createQuotaRequest(db, a) {
+    const quotaType = a.quotaType && QUOTA_TYPES.has(a.quotaType) ? a.quotaType : QUOTA_TYPE_BUILD_TASK_CREATE;
+    if (a.quotaType && !QUOTA_TYPES.has(a.quotaType))
+        return { error: 'unknown quota_type', error_code: 'BAD_QUOTA_TYPE' };
+    if (!a.requesterId)
+        return { error: 'requester required', error_code: 'REQUESTER_REQUIRED' };
+    const count = Math.trunc(Number(a.requestedExtraCount));
+    if (!Number.isFinite(count) || count <= 0)
+        return { error: 'requested_extra_count must be a positive integer', error_code: 'BAD_COUNT' };
+    const maxCount = maxQuotaExtraCount(db);
+    if (count > maxCount)
+        return { error: `requested_extra_count exceeds the max (${maxCount})`, error_code: 'COUNT_TOO_LARGE' };
+    const reason = String(a.reason ?? '').trim();
+    if (reason.length < REASON_MIN)
+        return { error: `reason is required (>= ${REASON_MIN} chars)`, error_code: 'REASON_REQUIRED' };
+    const reasonClamped = reason.slice(0, REASON_MAX);
+    const urgency = a.urgency && URGENCIES.has(a.urgency) ? a.urgency : 'normal';
+    if (a.urgency && !URGENCIES.has(a.urgency))
+        return { error: 'bad urgency', error_code: 'BAD_URGENCY' };
+    const maxDur = maxQuotaDurationHours(db);
+    let durationHours = null;
+    if (a.requestedDurationHours != null) {
+        durationHours = Math.trunc(Number(a.requestedDurationHours));
+        if (!Number.isFinite(durationHours) || durationHours <= 0)
+            return { error: 'requested_duration_hours must be a positive integer', error_code: 'BAD_DURATION' };
+        if (durationHours > maxDur)
+            return { error: `requested_duration_hours exceeds the max (${maxDur})`, error_code: 'DURATION_TOO_LARGE' };
+    }
+    const refs = JSON.stringify(parseRefs(a.linkedRefs));
+    const id = generateId('bqr');
+    try {
+        const tx = db.transaction(() => {
+            db.prepare(`INSERT INTO build_task_quota_requests
+           (id, quota_type, requester_user_id, requested_extra_count, reason, linked_refs, urgency, requested_duration_hours, requested_expires_at, status)
+         VALUES (?,?,?,?,?,?,?,?, ${durationHours != null ? `datetime('now','+${durationHours} hours')` : 'NULL'}, 'pending')`).run(id, quotaType, a.requesterId, count, reasonClamped, refs, urgency, durationHours);
+            logQuotaEvent(db, id, a.requesterId, 'request_created', { quota_type: quotaType, requested_extra_count: count, urgency });
+        });
+        tx();
+    }
+    catch (e) {
+        // partial unique index → an open pending request already exists
+        if (String(e.message || '').includes('idx_bqr_one_pending') || String(e.message || '').toUpperCase().includes('UNIQUE'))
+            return { error: 'you already have a pending quota request of this type', error_code: 'ALREADY_PENDING' };
+        return { error: 'failed to create quota request', error_code: 'CREATE_FAILED' };
+    }
+    return { id, status: 'pending' };
+}
+export function getQuotaRequest(db, id) {
+    expireStaleGrants(db);
+    return db.prepare('SELECT * FROM build_task_quota_requests WHERE id = ?').get(id);
+}
+export function listMyQuotaRequests(db, userId) {
+    expireStaleGrants(db);
+    return db.prepare('SELECT * FROM build_task_quota_requests WHERE requester_user_id = ? ORDER BY created_at DESC LIMIT 200').all(userId);
+}
+export function listQuotaRequests(db, f = {}) {
+    expireStaleGrants(db);
+    if (f.status)
+        return db.prepare('SELECT * FROM build_task_quota_requests WHERE status = ? ORDER BY created_at DESC LIMIT 500').all(f.status);
+    return db.prepare('SELECT * FROM build_task_quota_requests ORDER BY created_at DESC LIMIT 500').all();
+}
+/** Requester's create count over the trailing 24h — context for the root reviewer. */
+export function requesterUsage24h(db, userId) {
+    try {
+        return db.prepare(`SELECT COUNT(*) AS n FROM build_tasks WHERE created_by = ? AND created_at > datetime('now','-1 day')`).get(userId).n;
+    }
+    catch {
+        return 0;
+    }
+}
+export function approveQuotaRequest(db, id, approverId, a = {}) {
+    if (!approverId)
+        return { error: 'approver required', error_code: 'APPROVER_REQUIRED' };
+    expireStaleGrants(db);
+    let result = { error: 'unknown', error_code: 'UNKNOWN' };
+    try {
+        db.transaction(() => {
+            const r = db.prepare('SELECT * FROM build_task_quota_requests WHERE id = ?').get(id);
+            if (!r) {
+                result = { error: 'request not found', error_code: 'NOT_FOUND' };
+                return;
+            }
+            if (r.status !== 'pending') {
+                result = { error: `request is ${String(r.status)}, not pending`, error_code: 'BAD_STATE' };
+                return;
+            }
+            if (String(r.requester_user_id) === approverId) {
+                result = { error: 'cannot decide your own quota request', error_code: 'SELF_DECISION' };
+                return;
+            }
+            const maxCount = maxQuotaExtraCount(db);
+            let granted = a.grantedCount != null ? Math.trunc(Number(a.grantedCount)) : Number(r.requested_extra_count);
+            if (!Number.isFinite(granted) || granted <= 0) {
+                result = { error: 'granted count must be a positive integer', error_code: 'BAD_COUNT' };
+                return;
+            }
+            if (granted > maxCount) {
+                result = { error: `granted count exceeds the max (${maxCount})`, error_code: 'COUNT_TOO_LARGE' };
+                return;
+            }
+            const maxDur = maxQuotaDurationHours(db);
+            // prefer an explicit duration; else fall back to the requested duration; else the max
+            let durationHours = a.durationHours != null ? Math.trunc(Number(a.durationHours))
+                : (r.requested_duration_hours != null ? Number(r.requested_duration_hours) : maxDur);
+            if (!Number.isFinite(durationHours) || durationHours <= 0) {
+                result = { error: 'duration must be a positive integer', error_code: 'BAD_DURATION' };
+                return;
+            }
+            if (durationHours > maxDur) {
+                result = { error: `duration exceeds the max (${maxDur})`, error_code: 'DURATION_TOO_LARGE' };
+                return;
+            }
+            // compute the grant window. An explicit ISO expiresAt is normalized + range-checked via SQL.
+            if (a.expiresAt) {
+                const okFuture = db.prepare(`SELECT datetime(?) AS e, datetime('now') AS now, datetime('now','+${maxDur} hours') AS maxe`).get(a.expiresAt);
+                if (!okFuture.e) {
+                    result = { error: 'bad expires_at', error_code: 'BAD_EXPIRES_AT' };
+                    return;
+                }
+                if (okFuture.e <= okFuture.now) {
+                    result = { error: 'expires_at must be in the future', error_code: 'EXPIRES_IN_PAST' };
+                    return;
+                }
+                if (okFuture.e > okFuture.maxe) {
+                    result = { error: `expires_at exceeds the max window (${maxDur}h)`, error_code: 'EXPIRES_TOO_FAR' };
+                    return;
+                }
+                db.prepare(`UPDATE build_task_quota_requests
+          SET status='approved', decided_at=datetime('now'), decided_by=?, decision_note=?, granted_count=?, consumed_count=0, expires_at=datetime(?), updated_at=datetime('now')
+          WHERE id = ?`).run(approverId, a.decisionNote ?? null, granted, a.expiresAt, id);
+            }
+            else {
+                db.prepare(`UPDATE build_task_quota_requests
+          SET status='approved', decided_at=datetime('now'), decided_by=?, decision_note=?, granted_count=?, consumed_count=0, expires_at=datetime('now','+${durationHours} hours'), updated_at=datetime('now')
+          WHERE id = ?`).run(approverId, a.decisionNote ?? null, granted, id);
+            }
+            const after = db.prepare('SELECT expires_at FROM build_task_quota_requests WHERE id = ?').get(id);
+            logQuotaEvent(db, id, approverId, 'request_approved', { granted_count: granted, expires_at: after.expires_at, decision_note: a.decisionNote ?? null });
+            result = { ok: true, id, granted_count: granted, expires_at: after.expires_at };
+        })();
+    }
+    catch {
+        return { error: 'failed to approve quota request', error_code: 'APPROVE_FAILED' };
+    }
+    return result;
+}
+export function rejectQuotaRequest(db, id, approverId, a = {}) {
+    if (!approverId)
+        return { error: 'approver required', error_code: 'APPROVER_REQUIRED' };
+    let result = { error: 'unknown', error_code: 'UNKNOWN' };
+    try {
+        db.transaction(() => {
+            const r = db.prepare('SELECT * FROM build_task_quota_requests WHERE id = ?').get(id);
+            if (!r) {
+                result = { error: 'request not found', error_code: 'NOT_FOUND' };
+                return;
+            }
+            if (r.status !== 'pending') {
+                result = { error: `request is ${String(r.status)}, not pending`, error_code: 'BAD_STATE' };
+                return;
+            }
+            if (String(r.requester_user_id) === approverId) {
+                result = { error: 'cannot decide your own quota request', error_code: 'SELF_DECISION' };
+                return;
+            }
+            db.prepare(`UPDATE build_task_quota_requests SET status='rejected', decided_at=datetime('now'), decided_by=?, decision_note=?, updated_at=datetime('now') WHERE id = ?`)
+                .run(approverId, a.decisionNote ?? null, id);
+            logQuotaEvent(db, id, approverId, 'request_rejected', { decision_note: a.decisionNote ?? null });
+            result = { ok: true, id };
+        })();
+    }
+    catch {
+        return { error: 'failed to reject quota request', error_code: 'REJECT_FAILED' };
+    }
+    return result;
+}
+export function revokeQuotaRequest(db, id, approverId, a = {}) {
+    if (!approverId)
+        return { error: 'approver required', error_code: 'APPROVER_REQUIRED' };
+    let result = { error: 'unknown', error_code: 'UNKNOWN' };
+    try {
+        db.transaction(() => {
+            const r = db.prepare('SELECT * FROM build_task_quota_requests WHERE id = ?').get(id);
+            if (!r) {
+                result = { error: 'request not found', error_code: 'NOT_FOUND' };
+                return;
+            }
+            if (r.status !== 'approved') {
+                result = { error: `request is ${String(r.status)}, not an active grant`, error_code: 'BAD_STATE' };
+                return;
+            }
+            db.prepare(`UPDATE build_task_quota_requests SET status='revoked', decision_note=COALESCE(?, decision_note), updated_at=datetime('now') WHERE id = ?`)
+                .run(a.decisionNote ?? null, id);
+            logQuotaEvent(db, id, approverId, 'request_revoked', { decision_note: a.decisionNote ?? null });
+            result = { ok: true, id };
+        })();
+    }
+    catch {
+        return { error: 'failed to revoke quota grant', error_code: 'REVOKE_FAILED' };
+    }
+    return result;
+}
+/**
+ * Consume ONE unit from the oldest still-valid grant for (user, quota_type). MUST be called inside the
+ * caller's db.transaction so the unit is spent atomically with the task INSERT. Returns the grant id +
+ * remaining units on success, or null when no valid grant exists (caller then stays rate-limited).
+ * Fail-closed: any error (e.g. missing table) returns null. Expired grants are flipped + skipped.
+ */
+export function consumeQuotaForCreate(db, userId, quotaType = QUOTA_TYPE_BUILD_TASK_CREATE) {
+    try {
+        // lazily expire stale grants for this user first (audited)
+        const stale = db.prepare(`SELECT id FROM build_task_quota_requests
+       WHERE requester_user_id = ? AND quota_type = ? AND status='approved'
+         AND expires_at IS NOT NULL AND datetime(expires_at) <= datetime('now')`).all(userId, quotaType);
+        for (const s of stale) {
+            db.prepare(`UPDATE build_task_quota_requests SET status='expired', updated_at=datetime('now') WHERE id = ? AND status='approved'`).run(s.id);
+            logQuotaEvent(db, s.id, null, 'grant_expired', null);
+        }
+        const g = db.prepare(`SELECT id, granted_count, consumed_count FROM build_task_quota_requests
+       WHERE requester_user_id = ? AND quota_type = ? AND status='approved'
+         AND (expires_at IS NULL OR datetime(expires_at) > datetime('now'))
+         AND consumed_count < granted_count
+       ORDER BY datetime(expires_at) ASC, created_at ASC
+       LIMIT 1`).get(userId, quotaType);
+        if (!g)
+            return null;
+        const newConsumed = Number(g.consumed_count) + 1;
+        const exhausted = newConsumed >= Number(g.granted_count);
+        db.prepare(`UPDATE build_task_quota_requests SET consumed_count = ?, status = ?, updated_at=datetime('now') WHERE id = ?`)
+            .run(newConsumed, exhausted ? 'exhausted' : 'approved', g.id);
+        logQuotaEvent(db, g.id, userId, 'grant_consumed', { consumed_count: newConsumed, granted_count: g.granted_count, exhausted });
+        return { requestId: g.id, remaining: Number(g.granted_count) - newConsumed };
+    }
+    catch {
+        return null;
+    }
+}
+/** Total remaining (unexpired, unexhausted) units across a user's active grants — for the UI affordance. */
+export function remainingQuota(db, userId, quotaType = QUOTA_TYPE_BUILD_TASK_CREATE) {
+    try {
+        expireStaleGrants(db);
+        const row = db.prepare(`SELECT COALESCE(SUM(granted_count - consumed_count), 0) AS rem FROM build_task_quota_requests
+       WHERE requester_user_id = ? AND quota_type = ? AND status='approved'
+         AND (expires_at IS NULL OR datetime(expires_at) > datetime('now'))
+         AND consumed_count < granted_count`).get(userId, quotaType);
+        return Number(row.rem) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export { isErr as isQuotaError };

package/dist/layer2-business/L2-9-contribution/build-task-read.js

@@ -94,6 +94,21 @@ function shapeMetadata(row, shape) {
         estimated_context_size: row.estimated_context_size, estimated_agent_budget: row.estimated_agent_budget,
         value_state: row.value_state,
     };
+    // Honest estimate signal (#5): a proposal→draft conversion (task-proposal-draft.ts) seeds duration 0–0 +
+    // budget 'minimal' as a "no real estimate yet" placeholder — NOT a claim the task is instant / zero-cost.
+    // Surface a typed status so an agent never reads the placeholder as a real estimate. The raw
+    // estimated_duration / estimated_agent_budget / auto_claimable fields above are left untouched (no storage
+    // change); these are derived, advisory fields. estimate_status keys on the DURATION sentinel (null or 0–0):
+    // the draft path sets duration 0–0 together with budget 'minimal', so a 0–0 duration marks the whole estimate
+    // (duration + budget) as a placeholder. Budget alone is NOT used as the signal — 'minimal' is also a valid
+    // value for a genuinely tiny task. A 0–0/placeholder task that is nominally auto_claimable is downgraded to
+    // manual_review so a missing estimate is reviewed before the task is treated as routine.
+    const durMin = row.estimated_duration_min_minutes, durMax = row.estimated_duration_max_minutes;
+    const estimateUnknown = durMin == null || durMax == null || (durMin === 0 && durMax === 0);
+    const autoClaimable = row.auto_claimable === 1;
+    m.estimate_status = estimateUnknown ? 'unknown' : 'provided';
+    m.claimability = !autoClaimable || estimateUnknown ? 'manual_review' : 'auto_claimable';
+    m.human_review_required = m.claimability === 'manual_review';
     for (const k of LIST_ARRAY_FIELDS)
         m[k] = parseJsonList(row[k]);
     if (shape === 'detail') {
@@ -148,9 +163,17 @@ function buildWhere(scope, f) {
         where.push('m.audience = ?');
         params.push(f.audience);
     }
+    // auto_claimable filter is CLAIMABILITY-EQUIVALENT (#5), not a raw-field match — both directions mirror the
+    // derived claimability so list/filter/guard agree:
+    //   claimability='auto_claimable' ⟺ raw auto_claimable=1 AND a real (non 0–0/non-null) estimate
+    //   claimability='manual_review'  ⟺ raw auto_claimable=0 OR a 0–0/null placeholder estimate
+    // So `=true` excludes placeholder tasks, and `=false` INCLUDES a placeholder task even if its raw flag is 1.
     if (f.auto_claimable !== undefined) {
-        where.push('m.auto_claimable = ?');
-        params.push(f.auto_claimable ? 1 : 0);
+        const ESTIMATE_REAL = '(m.estimated_duration_min_minutes IS NOT NULL AND m.estimated_duration_max_minutes IS NOT NULL AND NOT (m.estimated_duration_min_minutes = 0 AND m.estimated_duration_max_minutes = 0))';
+        if (f.auto_claimable)
+            where.push(`m.auto_claimable = 1 AND ${ESTIMATE_REAL}`);
+        else
+            where.push(`(m.auto_claimable = 0 OR NOT ${ESTIMATE_REAL})`);
     }
     // required_capabilities (AND): required_capabilities is a JSON array of strings; match an exact element
     // via a quoted LIKE (dialect-agnostic; no json_each). ESCAPE so %/_ in a capability stay literal. This

package/dist/layer2-business/L2-9-contribution/build-tasks-engine.js

@@ -1,5 +1,6 @@
 import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
 import { creditBuildReputation, BUILD_POINTS } from './build-reputation-engine.js';
+import { consumeQuotaForCreate, QUOTA_TYPE_BUILD_TASK_CREATE } from './build-task-quota.js';
 export const TASK_STATUS = new Set(['open', 'claimed', 'in_review', 'done', 'abandoned']);
 export const TASK_PROVENANCE = new Set(['human', 'ai_assisted', 'ai_authored']);
 const CLAIM_TTL_DAYS = 7; // 认领后多久没进 in_review 自动回 open
@@ -45,7 +46,7 @@ export function initBuildTasksSchema(db) {
   `);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_build_task_events ON build_task_events(task_id, created_at)`);
 }
-function logTaskEvent(db, taskId, actorId, from, to, note) {
+export function logTaskEvent(db, taskId, actorId, from, to, note) {
     db.prepare(`INSERT INTO build_task_events (id, task_id, actor_id, from_status, to_status, note) VALUES (?,?,?,?,?,?)`)
         .run(generateId('btev'), taskId, actorId, from, to, note);
 }
@@ -60,6 +61,35 @@ export function releaseExpiredClaims(db) {
     }
     return expired.length;
 }
+/**
+ * Root admin accounts are exempt from the per-user create rate limit. The anti-spam cap
+ * (CREATE_RATE_PER_DAY) targets untrusted / public contributors; root maintainer actions are already
+ * gated by auth and recorded in admin_audit_log, so the cap adds friction without protection.
+ * Root = users.role = 'admin' AND users.admin_type = 'root' (the boot migration in server.ts forces
+ * any legacy admin with NULL admin_type to 'root', so the live root admin always carries 'root';
+ * matches the existing isRootAdmin / requireRootAdmin distinction).
+ * Regional / non-root admins stay capped — they should request more headroom via the separate
+ * quota-increase request workflow (PR #18) rather than a blanket exemption. Fail-closed: any lookup
+ * failure (unknown creator, non-root role, or a missing users table / missing admin_type column)
+ * returns false → the cap still applies, so non-root and test behavior is unchanged.
+ */
+function isCreateRateLimitExempt(db, userId) {
+    try {
+        const u = db.prepare('SELECT role, admin_type FROM users WHERE id = ?').get(userId);
+        return !!u && u.role === 'admin' && u.admin_type === 'root';
+    }
+    catch {
+        return false;
+    }
+}
+// sync INSERT + event log; callable directly or inside a db.transaction (e.g. atomic quota consume)
+function insertBuildTaskRow(db, fields) {
+    const id = generateId('bt');
+    db.prepare(`INSERT INTO build_tasks (id, title, area, description, rfc_ref, status, created_by)
+    VALUES (?,?,?,?,?, 'open', ?)`).run(id, fields.title, fields.area, fields.description, fields.rfcRef, fields.creatorId);
+    logTaskEvent(db, id, fields.creatorId, null, 'open', 'created');
+    return { id, status: 'open' };
+}
 export function createBuildTask(db, input) {
     const title = String(input.title || '').trim();
     if (title.length < 3)
@@ -69,15 +99,35 @@ export function createBuildTask(db, input) {
     const description = input.description ? String(input.description).slice(0, TEXT_MAX) : null;
     const area = input.area ? String(input.area).slice(0, 64) : null;
     const rfcRef = input.rfcRef ? String(input.rfcRef).slice(0, 64) : null;
+    const fields = { title, area, description, rfcRef, creatorId: input.creatorId };
+    // root admin accounts are exempt from the cap (accountable via auth + admin_audit_log)
+    if (isCreateRateLimitExempt(db, input.creatorId))
+        return insertBuildTaskRow(db, fields);
+    // anti-spam per-user daily cap
     const todayCount = db.prepare(`SELECT COUNT(*) AS n FROM build_tasks WHERE created_by = ? AND created_at > datetime('now','-1 day')`).get(input.creatorId).n;
-    if (todayCount >= CREATE_RATE_PER_DAY) {
-        return { error: `今日建任务已达上限(${CREATE_RATE_PER_DAY}/天)`, error_code: 'RATE_LIMITED' };
+    if (todayCount < CREATE_RATE_PER_DAY)
+        return insertBuildTaskRow(db, fields);
+    // cap exhausted — spend one unit of an approved quota grant ATOMICALLY with the INSERT, so a failed
+    // create never consumes quota. No valid grant → RATE_LIMITED (structured, so the UI can offer the
+    // "request extra quota" affordance). consumeQuotaForCreate is fail-closed (missing table → null).
+    const RATE_LIMITED_SENTINEL = '__RATE_LIMITED__';
+    try {
+        let ok = null;
+        db.transaction(() => {
+            const grant = consumeQuotaForCreate(db, input.creatorId, QUOTA_TYPE_BUILD_TASK_CREATE);
+            if (!grant)
+                throw new Error(RATE_LIMITED_SENTINEL);
+            const r = insertBuildTaskRow(db, fields);
+            ok = { id: r.id, status: r.status, via_grant: true, remaining_quota: grant.remaining };
+        })();
+        return ok;
+    }
+    catch (e) {
+        if (e.message === RATE_LIMITED_SENTINEL) {
+            return { error: `今日建任务已达上限(${CREATE_RATE_PER_DAY}/天)`, error_code: 'RATE_LIMITED', limit: CREATE_RATE_PER_DAY, used: todayCount, can_request: true };
+        }
+        throw e;
     }
-    const id = generateId('bt');
-    db.prepare(`INSERT INTO build_tasks (id, title, area, description, rfc_ref, status, created_by)
-    VALUES (?,?,?,?,?, 'open', ?)`).run(id, title, area, description, rfcRef, input.creatorId);
-    logTaskEvent(db, id, input.creatorId, null, 'open', 'created');
-    return { id, status: 'open' };
 }
 export function listBuildTasks(db, f = {}) {
     releaseExpiredClaims(db); // 先回收过期占坑,列表才准

package/dist/layer2-business/L2-9-contribution/canonical-contribution-target.js

@@ -1,4 +1,4 @@
-const DEFAULT_FULL_NAME = 'seasonsagents-art/webaz';
+const DEFAULT_FULL_NAME = 'webaz-protocol/webaz';
 const DEFAULT_BASE_BRANCH = 'main';
 /** The frozen canonical target from trusted config. Identical for every read response (public + member). */
 export function getCanonicalContributionTarget() {

package/dist/layer2-business/L2-9-contribution/contribution-facts-read.js

@@ -0,0 +1,66 @@
+import { resolveOperatorClaimAsOf } from './admin-coordination-resolver.js';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const dateOf = (ts) => (ts ? String(ts).slice(0, 10) : '');
+// GitHub: credential-backed facts whose executor is an actor the caller currently binds (same trust-root
+// join as identity-claim-read.ts FACTS_SQL). The b.account_id = ? anchor means only MY facts return.
+const GITHUB_FACTS_SQL = `
+  SELECT DISTINCT f.fact_id, f.source_event_key, f.source, f.type, f.artifact_ref, f.occurred_at,
+         f.executor_ref, f.provenance, f.status
+  FROM identity_bindings_active b
+  JOIN github_contribution_credentials c
+    ON c.github_actor_id = b.github_actor_id
+  JOIN github_fact_credentials l
+    ON l.credential_id = c.credential_id AND l.source_event_key = c.source_event_key
+  JOIN contribution_facts f
+    ON f.fact_id = l.fact_id AND f.source_event_key = l.source_event_key
+  WHERE b.account_id = ?
+    AND f.source = 'github'
+    AND f.executor_ref = 'github:' || b.github_actor_id
+  ORDER BY f.occurred_at DESC, f.fact_id`;
+// Admin coordination: every evidence-linked fact (executor admin:<seat>). Attribution is decided per-row
+// by the AS-OF resolver below — never by a stored accountable_ref. The link join also yields the
+// evidence_ref (source_type + opaque audit id); admin_audit_log.detail is never selected.
+const ADMIN_FACTS_SQL = `
+  SELECT f.fact_id, f.source_event_key, f.source, f.type, f.artifact_ref, f.occurred_at,
+         f.executor_ref, f.provenance, f.status, s.source_type, s.admin_audit_log_id
+  FROM admin_coordination_fact_sources s
+  JOIN contribution_facts f ON f.fact_id = s.fact_id
+  WHERE f.executor_ref LIKE 'admin:%'
+  ORDER BY f.occurred_at DESC, f.fact_id`;
+/** The caller's OWN attributable contribution facts (GitHub + admin coordination). Read-only; writes nothing. */
+export function getMyContributionFacts(db, accountId) {
+    const github = [];
+    const admin_coordination = [];
+    if (!accountId)
+        return { total: 0, groups: { github, admin_coordination, agent: [] } };
+    for (const r of db.prepare(GITHUB_FACTS_SQL).all(accountId)) {
+        github.push({
+            fact_id: r.fact_id, source_event_key: r.source_event_key, source: r.source, type: r.type ?? null,
+            occurred_at: r.occurred_at ?? null, executor_ref: r.executor_ref, attribution_via: 'github_binding',
+            contributor_account_id: accountId, artifact_ref: r.artifact_ref, status: r.status, provenance: r.provenance,
+            display_source_label: 'GitHub', display_source_label_en: 'GitHub',
+            display_summary: `GitHub · ${r.type || 'contribution'}${dateOf(r.occurred_at) ? ' · ' + dateOf(r.occurred_at) : ''}`,
+            evidence_ref: null, notice: 'evidence_only',
+        });
+    }
+    for (const r of db.prepare(ADMIN_FACTS_SQL).all()) {
+        const adminAccountId = String(r.executor_ref).slice('admin:'.length);
+        if (!adminAccountId || !r.occurred_at)
+            continue;
+        // AS-OF attribution: the operator claim effective when the work occurred decides the contributor.
+        const resolved = resolveOperatorClaimAsOf(db, adminAccountId, r.occurred_at);
+        if (!resolved || resolved.contributor_account_id !== accountId)
+            continue; // not mine → never shown
+        admin_coordination.push({
+            fact_id: r.fact_id, source_event_key: r.source_event_key, source: r.source, type: r.type ?? null,
+            occurred_at: r.occurred_at ?? null, executor_ref: r.executor_ref, attribution_via: 'operator_claim',
+            contributor_account_id: accountId, artifact_ref: r.artifact_ref, status: r.status, provenance: r.provenance,
+            display_source_label: '管理协调', display_source_label_en: 'Admin coordination',
+            display_summary: `管理协调 · ${r.source_type}${dateOf(r.occurred_at) ? ' · ' + dateOf(r.occurred_at) : ''}`,
+            // evidence_ref: opaque audit id + the action only — NEVER admin_audit_log.detail.
+            evidence_ref: { source_type: r.source_type, admin_audit_log_id: r.admin_audit_log_id },
+            notice: 'evidence_only',
+        });
+    }
+    return { total: github.length + admin_coordination.length, groups: { github, admin_coordination, agent: [] } };
+}

package/dist/layer2-business/L2-9-contribution/identity-claim-discovery.js

@@ -0,0 +1,55 @@
+/**
+ * F10 — claimable GitHub contribution DISCOVERY (read-only). Lets a logged-in account see which
+ * credential-backed GitHub contribution facts are currently CLAIMABLE — i.e. their GitHub actor is not
+ * yet bound by ANY account — so the F9 claim UI no longer depends on a maintainer hand-delivering
+ * `source_event_key` / `github_actor_id` (dogfood R3 finding F10, proposal tp_ce110fed).
+ *
+ * Trust / safety boundaries (mirrors identity-claim-read.ts, PR-F4):
+ *   - READ-ONLY: this module issues SELECT only — it never writes identity_bindings_active /
+ *     identity_binding_events / contribution_facts / github_fact_credentials /
+ *     identity_claim_challenges, never issues a challenge, never touches accountable_ref.
+ *   - Same credential-backed trust root as F2/F3b/F4: a fact is surfaced only when it is
+ *     `source='github'` + `status='active'` + linked to a credential whose actor matches the fact's
+ *     `executor_ref` ('github:' || actor) — a forged executor_ref without a credential never appears.
+ *   - CLAIMABLE = the actor has NO active binding (LEFT JOIN … IS NULL): an actor bound by another
+ *     account is excluded (it is theirs), and an actor bound by the CALLER is also excluded here —
+ *     those facts already appear in /github/me's attributable_facts (the F4 surface).
+ *   - No secret in the output: no account_id, credential_id, core_json/digest, token, nonce,
+ *     nonce_hash, proof material. Only minimal display fields + what the claim form needs
+ *     (source_event_key + github_actor_id — both already disclosed-by-design at claim-challenge).
+ *   - `accountId` is accepted for interface parity with the other read engines (the route always passes
+ *     the SESSION user) and reserved for future per-account filtering; discovery output is currently
+ *     account-independent by construction (unbound actors only).
+ *
+ * Visibility posture: same as claim-challenge (#311, by design) — an unclaimed, credential-backed
+ * contribution is discoverable and claimable; that is the point of the GitHub-first promise.
+ * No reward / score / valuation anywhere; the route wraps the response in the uncommitted-value boundary.
+ */
+import { dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 async read seam
+// Active, credential-backed, executor-matching GitHub facts whose actor is NOT bound by any account.
+// DISTINCT collapses credential-version upgrade chains (multiple credentials → the same fact carry the
+// same PR identity fields). Newest merged work first; bounded.
+const CLAIMABLE_SQL = `
+  SELECT DISTINCT f.fact_id, f.source_event_key, f.source, f.type, f.artifact_ref, f.occurred_at,
+         f.created_at, c.github_actor_id, c.repository_id, c.pr_number, c.merge_commit_sha,
+         c.merged_at, c.lifecycle_event
+  FROM contribution_facts f
+  JOIN github_fact_credentials l
+    ON l.fact_id = f.fact_id AND l.source_event_key = f.source_event_key
+  JOIN github_contribution_credentials c
+    ON c.credential_id = l.credential_id AND c.source_event_key = l.source_event_key
+  LEFT JOIN identity_bindings_active b
+    ON b.github_actor_id = c.github_actor_id
+  WHERE f.source = 'github'
+    AND f.status = 'active'
+    AND f.executor_ref = 'github:' || c.github_actor_id
+    AND b.github_actor_id IS NULL
+  ORDER BY COALESCE(c.merged_at, f.created_at) DESC, f.fact_id
+  LIMIT 50`;
+/** List the currently claimable (unbound-actor) credential-backed GitHub facts. Read-only. */
+export async function listClaimableGithubIdentityFacts(accountId) {
+    if (!accountId || typeof accountId !== 'string')
+        return { claimable_facts: [] };
+    const rows = await dbAll(CLAIMABLE_SQL, []);
+    return { claimable_facts: rows };
+}