@seasonkoh/webaz 0.1.24 → 0.1.26

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

@@ -0,0 +1,222 @@
+import { RISK_LEVELS, AUDIENCES, CONTEXT_SIZES, AGENT_BUDGETS, parseJsonList } from './build-task-agent-metadata-store.js';
+import { TASK_STATUS, releaseExpiredClaims } from './build-tasks-engine.js';
+import { getCanonicalContributionTarget } from './canonical-contribution-target.js';
+import { withUncommittedValueBoundary } from './contribution-display-envelope.js';
+/**
+ * The single read envelope: stamps the SAME trusted canonical_contribution_target (anti GitHub-target
+ * confusion) AND the uncommitted value_boundary onto every task-board read response (public + member), so
+ * an agent always gets the identical, config-sourced target — never one derived from task metadata.
+ */
+export function withContributionReadEnvelope(payload) {
+    return withUncommittedValueBoundary({ ...payload, canonical_contribution_target: getCanonicalContributionTarget() });
+}
+/** Validate raw query filters — fail-closed: an unknown value is rejected, never silently ignored. */
+export function validateTaskFilters(q) {
+    const f = {};
+    const bad = (code, detail) => ({ ok: false, code, detail });
+    if (q.status !== undefined) {
+        if (typeof q.status !== 'string' || !TASK_STATUS.has(q.status))
+            return bad('INVALID_FILTER_STATUS', 'status must be open|claimed|in_review|done|abandoned');
+        f.status = q.status;
+    }
+    if (q.area !== undefined) {
+        if (typeof q.area !== 'string' || q.area.trim().length === 0)
+            return bad('INVALID_FILTER_AREA', 'area must be a non-empty string');
+        f.area = q.area.slice(0, 64);
+    }
+    if (q.risk_level !== undefined) {
+        if (typeof q.risk_level !== 'string' || !RISK_LEVELS.includes(q.risk_level))
+            return bad('INVALID_FILTER_RISK_LEVEL', `risk_level must be ${RISK_LEVELS.join('|')}`);
+        f.risk_level = q.risk_level;
+    }
+    if (q.audience !== undefined) {
+        if (typeof q.audience !== 'string' || !AUDIENCES.includes(q.audience))
+            return bad('INVALID_FILTER_AUDIENCE', `audience must be ${AUDIENCES.join('|')}`);
+        f.audience = q.audience;
+    }
+    if (q.auto_claimable !== undefined) {
+        if (q.auto_claimable !== 'true' && q.auto_claimable !== 'false')
+            return bad('INVALID_FILTER_AUTO_CLAIMABLE', 'auto_claimable must be true|false');
+        f.auto_claimable = q.auto_claimable === 'true';
+    }
+    // required_capabilities: comma-separated; a task matches if it requires ALL of them (AND). Capped to keep
+    // the WHERE bounded; fail-closed on a non-string / empty list.
+    if (q.required_capabilities !== undefined) {
+        if (typeof q.required_capabilities !== 'string')
+            return bad('INVALID_FILTER_REQUIRED_CAPABILITIES', 'required_capabilities must be a comma-separated string');
+        const caps = q.required_capabilities.split(',').map(s => s.trim()).filter(Boolean).slice(0, 10).map(c => c.slice(0, 64));
+        if (caps.length === 0)
+            return bad('INVALID_FILTER_REQUIRED_CAPABILITIES', 'required_capabilities must list at least one non-empty capability');
+        f.requiredCapabilities = caps;
+    }
+    // agent_capabilities: the agent's OWN capability set — match tasks whose required_capabilities are a
+    // SUBSET (tasks the agent can actually do). Distinct from required_capabilities (which is AND/superset:
+    // "task requires all listed"). Same 10-item / 64-char caps; fail-closed on non-string / empty.
+    if (q.agent_capabilities !== undefined) {
+        if (typeof q.agent_capabilities !== 'string')
+            return bad('INVALID_FILTER_AGENT_CAPABILITIES', 'agent_capabilities must be a comma-separated string');
+        const caps = q.agent_capabilities.split(',').map(s => s.trim()).filter(Boolean).slice(0, 10).map(c => c.slice(0, 64));
+        if (caps.length === 0)
+            return bad('INVALID_FILTER_AGENT_CAPABILITIES', 'agent_capabilities must list at least one non-empty capability');
+        f.agentCapabilities = caps;
+    }
+    // max_duration_minutes: only tasks whose estimated max duration fits within this many minutes. Fail-closed
+    // on non-string / non-positive-integer / out-of-range.
+    if (q.max_duration_minutes !== undefined) {
+        if (typeof q.max_duration_minutes !== 'string')
+            return bad('INVALID_FILTER_MAX_DURATION', 'max_duration_minutes must be a positive integer');
+        const n = Number(q.max_duration_minutes);
+        if (!Number.isInteger(n) || n <= 0 || n > 100000)
+            return bad('INVALID_FILTER_MAX_DURATION', 'max_duration_minutes must be a positive integer (1..100000)');
+        f.maxDurationMinutes = n;
+    }
+    if (q.estimated_context_size !== undefined) {
+        if (typeof q.estimated_context_size !== 'string' || !CONTEXT_SIZES.includes(q.estimated_context_size))
+            return bad('INVALID_FILTER_CONTEXT_SIZE', `estimated_context_size must be ${CONTEXT_SIZES.join('|')}`);
+        f.estimated_context_size = q.estimated_context_size;
+    }
+    if (q.estimated_agent_budget !== undefined) {
+        if (typeof q.estimated_agent_budget !== 'string' || !AGENT_BUDGETS.includes(q.estimated_agent_budget))
+            return bad('INVALID_FILTER_AGENT_BUDGET', `estimated_agent_budget must be ${AGENT_BUDGETS.join('|')}`);
+        f.estimated_agent_budget = q.estimated_agent_budget;
+    }
+    return { ok: true, filters: f };
+}
+const LIST_ARRAY_FIELDS = ['required_capabilities', 'dependencies', 'blocking_conditions'];
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function shapeMetadata(row, shape) {
+    if (row.task_type == null)
+        return null; // no satellite row → old task, compatible
+    const m = {
+        task_type: row.task_type, risk_level: row.risk_level, audience: row.audience,
+        agent_autonomy: row.agent_autonomy, auto_claimable: row.auto_claimable === 1,
+        estimated_duration: { min_minutes: row.estimated_duration_min_minutes, max_minutes: row.estimated_duration_max_minutes },
+        estimated_context_size: row.estimated_context_size, estimated_agent_budget: row.estimated_agent_budget,
+        value_state: row.value_state,
+    };
+    for (const k of LIST_ARRAY_FIELDS)
+        m[k] = parseJsonList(row[k]);
+    if (shape === 'detail') {
+        m.source_ref = row.source_ref;
+        m.version = row.version;
+        m.expected_results = row.expected_results;
+        m.definition_of_done = row.definition_of_done;
+        m.contribution_type = row.contribution_type;
+        m.accountable_party_required = row.accountable_party_required === 1;
+        for (const k of ['allowed_paths', 'forbidden_paths', 'prohibited_actions', 'human_confirmation_points', 'acceptance_criteria', 'verification_commands', 'deliverables'])
+            m[k] = parseJsonList(row[k]);
+    }
+    return m;
+}
+// FULL legacy build_tasks core — the member (logged-in) endpoint MUST keep every old field for backward
+// compatibility (Codex regression): only agent_metadata / value_boundary / canonical_contribution_target
+// are APPENDED. The public endpoint uses the lighter task_id shape.
+const FULL_CORE = ['id', 'title', 'area', 'description', 'rfc_ref', 'status', 'claimer_id', 'claimer_provenance',
+    'pr_ref', 'claimed_at', 'claim_expires_at', 'created_by', 'resolution', 'resolved_by', 'created_at', 'updated_at'];
+function shapeCoreFull(row) { const o = {}; for (const k of FULL_CORE)
+    o[k] = row[k]; return o; }
+function shapeCoreLight(row) {
+    return { task_id: row.id, title: row.title, area: row.area, status: row.status, claimer_id: row.claimer_id, created_by: row.created_by, created_at: row.created_at, updated_at: row.updated_at };
+}
+function buildWhere(scope, f) {
+    const where = [];
+    const params = [];
+    const join = scope === 'public' ? 'JOIN' : 'LEFT JOIN';
+    if (scope === 'public') {
+        where.push("m.audience = 'public'", "t.status = 'open'");
+    }
+    else {
+        where.push("(m.audience IS NULL OR m.audience = 'public')");
+    } // member: hide restricted/internal
+    if (f.status) {
+        where.push('t.status = ?');
+        params.push(f.status);
+    }
+    if (f.area) {
+        where.push('t.area = ?');
+        params.push(f.area);
+    }
+    if (f.claimerId) {
+        where.push('t.claimer_id = ?');
+        params.push(f.claimerId);
+    }
+    if (f.risk_level) {
+        where.push('m.risk_level = ?');
+        params.push(f.risk_level);
+    }
+    if (f.audience) {
+        where.push('m.audience = ?');
+        params.push(f.audience);
+    }
+    if (f.auto_claimable !== undefined) {
+        where.push('m.auto_claimable = ?');
+        params.push(f.auto_claimable ? 1 : 0);
+    }
+    // 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
+    // ANDs with the scope clause above, so restricted/internal never leak even when a filter matches.
+    if (f.requiredCapabilities)
+        for (const cap of f.requiredCapabilities) {
+            where.push("m.required_capabilities LIKE ? ESCAPE '\\'");
+            params.push('%"' + cap.replace(/[\\%_]/g, c => '\\' + c) + '"%');
+        }
+    // max_duration_minutes: the task's estimated max duration must be known AND fit within the requested time.
+    if (f.maxDurationMinutes !== undefined) {
+        where.push('m.estimated_duration_max_minutes IS NOT NULL AND m.estimated_duration_max_minutes <= ?');
+        params.push(f.maxDurationMinutes);
+    }
+    if (f.estimated_context_size) {
+        where.push('m.estimated_context_size = ?');
+        params.push(f.estimated_context_size);
+    }
+    if (f.estimated_agent_budget) {
+        where.push('m.estimated_agent_budget = ?');
+        params.push(f.estimated_agent_budget);
+    }
+    return { where, params, join };
+}
+// SELECT t.* (every legacy build_tasks column) + the explicit metadata columns (NOT m.created_at, to
+// avoid colliding with t.created_at; m.* names are otherwise disjoint from t.*).
+const META_COLS = `m.task_type, m.source_ref, m.version, m.allowed_paths, m.forbidden_paths, m.prohibited_actions,
+  m.risk_level, m.audience, m.agent_autonomy, m.auto_claimable, m.human_confirmation_points,
+  m.required_capabilities, m.acceptance_criteria, m.verification_commands, m.expected_results,
+  m.deliverables, m.definition_of_done, m.estimated_duration_min_minutes, m.estimated_duration_max_minutes,
+  m.estimated_context_size, m.estimated_agent_budget, m.dependencies, m.blocking_conditions, m.value_state,
+  m.contribution_type, m.accountable_party_required`;
+/** List tasks visible in `scope` (member = full legacy core; public = light), with parsed agent_metadata or null. */
+export function listBuildTasksWithAgentMetadata(db, filters, scope) {
+    releaseExpiredClaims(db); // RFC-006 TTL: recycle expired claims before reading (parity with listBuildTasks)
+    const LIST_LIMIT = 200;
+    const { where, params, join } = buildWhere(scope, filters);
+    // agent_capabilities is a JS subset filter, so it must run BEFORE the cap — applying SQL LIMIT first would
+    // drop a doable task that sorted past row 200 (Codex P2: a real false-negative). When it is active we fetch
+    // the full SCOPED candidate set (already bounded by the scope/other WHERE clauses) and cap after filtering.
+    const limitSql = filters.agentCapabilities ? '' : ` LIMIT ${LIST_LIMIT}`;
+    let rows = db.prepare(`SELECT t.*, ${META_COLS} FROM build_tasks t ${join} build_task_agent_metadata m ON m.task_id = t.id
+    WHERE ${where.join(' AND ')}
+    ORDER BY (t.status='open') DESC, t.updated_at DESC${limitSql}`).all(...params);
+    // agent_capabilities (SUBSET): keep tasks whose required_capabilities are all within the agent's set —
+    // i.e. tasks the agent can do — then cap. Dialect-agnostic (no json_each). No-leak intact: the scope WHERE
+    // already excluded restricted/internal, so this can only narrow. A no-metadata task (member scope) has no
+    // required_capabilities → [] → vacuously a subset (no skills required).
+    if (filters.agentCapabilities) {
+        const have = new Set(filters.agentCapabilities);
+        rows = rows.filter(r => parseJsonList(r.required_capabilities).every(c => have.has(c))).slice(0, LIST_LIMIT);
+    }
+    return rows.map(r => ({ ...(scope === 'public' ? shapeCoreLight(r) : shapeCoreFull(r)), agent_metadata: shapeMetadata(r, 'list') }));
+}
+/** Detail for one task visible in `scope`, else null (no leak). Member keeps the full legacy core + events. */
+export function getBuildTaskWithAgentMetadata(db, id, scope) {
+    releaseExpiredClaims(db); // RFC-006 TTL parity with getBuildTask
+    const { where, params, join } = buildWhere(scope, {});
+    const row = db.prepare(`SELECT t.*, ${META_COLS} FROM build_tasks t ${join} build_task_agent_metadata m ON m.task_id = t.id
+    WHERE ${where.join(' AND ')} AND t.id = ?`).get(...params, id);
+    if (!row)
+        return null;
+    const core = scope === 'public' ? shapeCoreLight(row) : shapeCoreFull(row);
+    const out = { ...core, agent_metadata: shapeMetadata(row, 'detail') };
+    if (scope !== 'public') { // member detail keeps the build_task_events list (old getBuildTask behavior)
+        out.events = db.prepare(`SELECT actor_id, from_status, to_status, note, created_at FROM build_task_events WHERE task_id = ? ORDER BY created_at`).all(id);
+    }
+    return out;
+}

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

@@ -45,7 +45,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);
 }
@@ -131,7 +131,10 @@ export function claimBuildTask(db, taskId, userId, provenance) {
     const row = db.prepare(`SELECT claim_expires_at FROM build_tasks WHERE id = ?`).get(taskId);
     return { id: taskId, status: 'claimed', claim_expires_at: row.claim_expires_at };
 }
-export function submitBuildTask(db, taskId, userId, prRef, note) {
+// `verificationSummary` (what the contributor ran/verified) is the submit evidence — stored in the
+// existing build_task_events.note (no schema churn). The ROUTE requires it; the engine stores it if
+// present, staying backward-compatible for any direct caller.
+export function submitBuildTask(db, taskId, userId, prRef, note, verificationSummary) {
     const t = db.prepare(`SELECT status, claimer_id FROM build_tasks WHERE id = ?`).get(taskId);
     if (!t)
         return { error: '任务不存在', error_code: 'NOT_FOUND' };
@@ -141,7 +144,12 @@ export function submitBuildTask(db, taskId, userId, prRef, note) {
         return { error: `任务状态为 ${t.status},仅 claimed 可提交进 in_review`, error_code: 'BAD_STATE' };
     const pr = prRef ? String(prRef).slice(0, 300) : null;
     db.prepare(`UPDATE build_tasks SET status='in_review', pr_ref=?, updated_at=datetime('now') WHERE id = ? AND status='claimed'`).run(pr, taskId);
-    logTaskEvent(db, taskId, userId, 'claimed', 'in_review', note ? `pr=${pr || '?'} note=${String(note).slice(0, 200)}` : `pr=${pr || '?'}`);
+    const parts = [`pr=${pr || '?'}`];
+    if (verificationSummary)
+        parts.push(`verify=${String(verificationSummary).slice(0, 500)}`);
+    if (note)
+        parts.push(`note=${String(note).slice(0, 200)}`);
+    logTaskEvent(db, taskId, userId, 'claimed', 'in_review', parts.join(' '));
     return { id: taskId, status: 'in_review' };
 }
 // 认领者主动放弃 → 回 open(让别人接)

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

@@ -0,0 +1,16 @@
+const DEFAULT_FULL_NAME = 'seasonsagents-art/webaz';
+const DEFAULT_BASE_BRANCH = 'main';
+/** The frozen canonical target from trusted config. Identical for every read response (public + member). */
+export function getCanonicalContributionTarget() {
+    const fullName = (process.env.CANONICAL_GITHUB_REPO || DEFAULT_FULL_NAME).trim();
+    const baseBranch = (process.env.CANONICAL_GITHUB_BASE_BRANCH || DEFAULT_BASE_BRANCH).trim();
+    const repoId = (process.env.CANONICAL_GITHUB_REPOSITORY_ID || '').trim() || null;
+    return Object.freeze({
+        canonical_repository_id: repoId,
+        canonical_repository_full_name: fullName,
+        canonical_github_url: `https://github.com/${fullName}`,
+        base_branch: baseBranch,
+        expected_pr_base_repo: fullName,
+        note: 'Trusted constant — NOT derived from task metadata or source_ref. Only a merged PR whose base repo is this canonical repository can become a WebAZ contribution fact; a task source_ref is a reference only. If a target repo differs from this canonical repo, STOP and ask the user to confirm — do not contribute to a non-canonical repository.',
+    });
+}

package/dist/layer2-business/L2-9-contribution/contribution-display-envelope.js

@@ -0,0 +1,40 @@
+/**
+ * PR-5A — Contribution display: the uncommitted-value boundary (RFC-017 I-12 / §7).
+ *
+ * This is the SAFETY CONTRACT that must wrap every contribution metering/display surface BEFORE any
+ * valuation/scoring is ever built. RFC-017 separates three layers — fact · valuation · redemption — and
+ * locks the boundary: today the protocol grants NO economic value. So any surface that shows facts /
+ * attribution must carry an explicit, machine-readable boundary saying so, so the act of *measuring and
+ * displaying* contribution can never read as a payout promise (the legal/trust firewall, RFC-017 §7 R1).
+ *
+ * This module is PURELY a display contract: it computes/scores NOTHING, stores NOTHING, and imports NO
+ * reward / KYC / wallet / valuation module (enforced by the §8 iron-rule guard, rule5). It only stamps a
+ * constant boundary onto a payload:
+ *   - value_state      = 'uncommitted'   (RFC-017 I-12 — the whole-protocol stance)
+ *   - valuation_state  = 'not_defined'   (the valuation layer is deferred to a future DAO + team)
+ *   - redemption_state = 'not_defined'   (the redemption layer is explicitly uncommitted in full)
+ *   - economic_rights  = false           (grants no security / equity / debt / redemption right)
+ * and NO amount / currency / yield / payout field is ever added (the notice deliberately does not even
+ * name those words, so a display can carry the boundary without listing a "value").
+ *
+ * spec: docs/rfcs/RFC-017-contribution-protocol-v1.md §I-12/§7 · docs/IDENTITY-CLAIM-DESIGN.md §8.8.
+ */
+// Frozen constant — there is exactly ONE boundary stance pre-launch; callers must not vary it. The notice
+// is an informational disclaimer ONLY; it intentionally avoids the words amount/currency/yield/payout/
+// reward so a display never restates a "value", and it promises nothing.
+export const UNCOMMITTED_VALUE_BOUNDARY = Object.freeze({
+    value_state: 'uncommitted',
+    valuation_state: 'not_defined',
+    redemption_state: 'not_defined',
+    economic_rights: false,
+    boundary_ref: 'RFC-017 I-12',
+    notice_en: 'Informational record of contribution facts and attribution only. It is not a financial instrument and confers no economic or redemption right; nothing here is promised or guaranteed (RFC-017 I-12 / §7).',
+    notice_zh: '仅为贡献事实与归属的信息性记录,不是金融工具,不授予任何经济或兑现权利,此处不作任何承诺或保证(RFC-017 I-12 / §7)。',
+});
+/**
+ * Stamp the uncommitted-value boundary onto a contribution display payload, under a single top-level
+ * `value_boundary` key. Pure: returns a new object, never mutates the input, adds no economic field.
+ */
+export function withUncommittedValueBoundary(payload) {
+    return { ...payload, value_boundary: UNCOMMITTED_VALUE_BOUNDARY };
+}

package/dist/layer2-business/L2-9-contribution/contribution-score-contract.js

@@ -0,0 +1,36 @@
+// Frozen metadata the static guard asserts against — makes the boundary a CODE contract, not just prose.
+export const CONTRIBUTION_SCORE_V1 = Object.freeze({
+    score_version: 'v1',
+    // user-facing field names of a displayed score (guard: none may be an economic-promise term)
+    display_fields: ['score_version', 'contribution_score', 'components', 'value_boundary'],
+    // evidence component keys (weights/formula DEFERRED to governance — invariant 4/7)
+    component_keys: ['accepted_contributions', 'reviews_provided', 'maintenance_actions', 'impact_observed', 'reverted_penalty'],
+    // READ-ONLY inputs — all pre-existing models; v1 adds NO table and NO write path (§3)
+    input_sources: [
+        'contribution_facts (RFC-017 fact layer)',
+        'github_contribution_credentials + github_fact_credentials',
+        'identity_bindings_active accountable overlay (/github/me, PR-F4)',
+        'build_reputation read model (RFC-006, PR5B)',
+    ],
+    // hard boundary flags (the whole point of this PR)
+    display_requires_value_boundary: true,
+    decides_money_or_rights: false,
+    is_redeemable: false,
+    defines_reward_formula: false,
+    requires_or_unlocks_kyc: false,
+    affects_wallet_escrow_commission: false,
+    affects_binary_tree_position: false,
+    gates_verifier_or_arbitrator: false,
+    revisable_by_governance: true,
+    // the 8 locked invariants (full text: docs/CONTRIBUTION-SCORE-V1-DESIGN.md §2)
+    invariants: [
+        'uncommitted only',
+        'no economic rights',
+        'no redemption',
+        'no reward formula (deferred)',
+        'no KYC / fulfillment',
+        'explainable by evidence_refs',
+        'revisable by governance',
+        'every displayed score carries value_boundary',
+    ],
+});

package/dist/layer2-business/L2-9-contribution/contribution-score-evidence.js

@@ -0,0 +1,61 @@
+/**
+ * PR5E — Contribution Score v1 read-only EVIDENCE COLLECTOR. Aggregates component-level evidence ONLY;
+ * computes NO score: no `contribution_score`, no total, no weights / formula / curve / tier / reward /
+ * eligibility (all deferred — RFC-017 + the #318 contract). Read-only: no DB write, no new table, no
+ * schema change; attribution is the read overlay, so `contribution_facts.accountable_ref` stays NULL.
+ * Any future display of this evidence inherits the PR5A uncommitted-value boundary.
+ *
+ * For a logged-in account it returns one ScoreComponentV1 ({ key, raw_count, evidence_refs[] }) per fixed
+ * contract component key (#318), sourced ONLY from existing models:
+ *   - accepted_contributions: ACTIVE GitHub credential-BACKED facts attributable to the account — the
+ *     /github/me overlay trust root (contribution_facts ⋈ github_fact_credentials ⋈
+ *     github_contribution_credentials, executor = a currently-bound actor).
+ *   - reviews_provided / maintenance_actions: the active attributable facts of type 'audit' / 'maintenance'.
+ *   - impact_observed: NO impact-observation source exists in the current models → 0 / [] (NOT fabricated
+ *     to look complete; a future PR wires a real source).
+ *   - reverted_penalty: NO source yet → 0 / []. Lifecycle status changes (revert/supersede/void) belong to
+ *     a FUTURE append-only status-events overlay; `contribution_facts.status` is as-ingested 'active' and
+ *     is NEVER updated in place (GITHUB-CREDENTIAL-INGESTION-DESIGN.md; github-credential-ingestion-engine.ts).
+ *     So we deliberately do NOT read `status='reverted'` here — that would both stay perpetually 0 under the
+ *     current ingestion AND tempt future code into an in-place status mutation that violates append-only.
+ *     reverted_penalty is wired to the real status-events overlay only once that overlay PR lands.
+ * `evidence_refs` are real `contribution_facts.fact_id` values (invariant 6 — explainable by evidence).
+ *
+ * spec: docs/CONTRIBUTION-SCORE-V1-DESIGN.md · contribution-score-contract.ts · docs/IDENTITY-CLAIM-DESIGN.md §8.7.
+ */
+import { dbAll } from '../../layer0-foundation/L0-1-database/db.js';
+// Active attributable facts: the SAME credential-backed + executor-bound-to-me overlay as /github/me
+// (PR-F4), anchored on b.account_id = the caller, so only the account's own facts are seen. status='active'
+// is the as-ingested value (never updated in place); a future status-events overlay will derive lifecycle.
+const ATTRIBUTABLE_ACTIVE_FACTS_SQL = `
+  SELECT DISTINCT f.fact_id, f.type
+  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.status = 'active'
+    AND f.executor_ref = 'github:' || b.github_actor_id
+  ORDER BY f.fact_id`;
+const component = (key, refs) => ({ key, raw_count: refs.length, evidence_refs: refs });
+/**
+ * Collect the five fixed-contract evidence components for `accountId`. Returns counts + evidence_refs
+ * only — never a `contribution_score`. Order matches CONTRIBUTION_SCORE_V1.component_keys (#318).
+ */
+export async function collectContributionScoreEvidence(accountId) {
+    if (!accountId) {
+        return ['accepted_contributions', 'reviews_provided', 'maintenance_actions', 'impact_observed', 'reverted_penalty']
+            .map(k => component(k, []));
+    }
+    const active = await dbAll(ATTRIBUTABLE_ACTIVE_FACTS_SQL, [accountId]);
+    const ofType = (rows, t) => rows.filter(r => r.type === t).map(r => r.fact_id);
+    return [
+        component('accepted_contributions', active.map(r => r.fact_id)),
+        component('reviews_provided', ofType(active, 'audit')),
+        component('maintenance_actions', ofType(active, 'maintenance')),
+        component('impact_observed', []), // no evidence source in v1 models (not fabricated)
+        component('reverted_penalty', []), // no status-events overlay source yet — NOT read from fact.status (append-only)
+    ];
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Canonical serialization + SHA-256 digest for GitHub Contribution Credentials (PR 3A).
+ *
+ * Reuse note: `canonicalSerialize` below is **byte-identical** to
+ * `src/layer0-foundation/L0-2-state-machine/order-chain.ts` canonicalSerialize (the
+ * repo's established canonical-JSON idiom). It is inlined here so the credential verifier
+ * stays a self-contained pure module (no coupling to the order state machine); the static
+ * test asserts equivalence with the src version on samples (no-drift guard).
+ *
+ * No new dependency — SHA-256 via Node built-in `node:crypto`.
+ */
+import { createHash } from 'node:crypto';
+/** Deterministic canonical JSON: recursively sort object keys; arrays keep order. */
+export function canonicalSerialize(obj) {
+    if (obj === null || obj === undefined)
+        return JSON.stringify(obj);
+    if (Array.isArray(obj))
+        return '[' + obj.map(canonicalSerialize).join(',') + ']';
+    if (typeof obj === 'object') {
+        const keys = Object.keys(obj).sort();
+        return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalSerialize(obj[k])).join(',') + '}';
+    }
+    return JSON.stringify(obj);
+}
+export const sha256hex = (s) => createHash('sha256').update(s).digest('hex');
+/**
+ * The `core` object = the immutable, GitHub-authoritative fact. These are the ONLY fields
+ * that the `core_digest` (and thus `credential_id`) authenticate. The observation envelope
+ * (display names, observed_at, self-reported, evidence summaries) is explicitly NOT part of
+ * this digest — it is mutable / non-authoritative and carries its own `observation_digest`.
+ */
+export const DIGEST_CORE_FIELDS = [
+    'credential_type', // fixed protocol domain — isolates this credential family in the digest
+    'credential_version', // version domain — a future v2 of the SAME GitHub fact gets a DIFFERENT id
+    'repository_id',
+    'pr_node_id',
+    'pr_number',
+    'base_ref',
+    'head_sha',
+    'merge_commit_sha',
+    'merged_at',
+    'github_actor_id',
+    'lifecycle_event',
+    'supersedes_credential_id', // lifecycle parent link is bound into the immutable fact
+];
+/** Canonical SHA-256 over the exact core-field set (key-order independent). */
+export function digestCore(source) {
+    const picked = {};
+    for (const k of DIGEST_CORE_FIELDS)
+        picked[k] = source[k] === undefined ? null : source[k];
+    return sha256hex(canonicalSerialize(picked));
+}
+/** Canonical SHA-256 over an arbitrary (observation) object — key-order independent. */
+export function digestObject(obj) {
+    return sha256hex(canonicalSerialize(obj));
+}
+/** Deterministic credential id derived from the CORE digest (idempotent for the same fact). */
+export function credentialIdFromDigest(coreDigest) {
+    return `ghc_${coreDigest.slice(0, 40)}`;
+}

package/dist/layer2-business/L2-9-contribution/github-credential/github-credential.schema.js

@@ -0,0 +1,140 @@
+/**
+ * GitHub Immutable Contribution Credential v2 — machine-readable contract (canonical).
+ *
+ * A credential proves a GitHub FACT (a merged PR) observed via a GitHub API response. It is a *candidate* for RFC-017's contribution fact layer — NOT a
+ * Passkey/KYC claim, scoring, or reward. Distinct from: Contribution Fact (RFC-017
+ * authoritative, produced later), Identity Claim (future Passkey), Valuation/Reward (never here).
+ *
+ * Immutability model (Codex #294 audit):
+ *   - `core`  = the immutable GitHub fact. `core_digest` (and `credential_id` derived from it)
+ *               authenticate ONLY this. Lifecycle parent link `supersedes_credential_id` is in core.
+ *   - `observation` = a NON-authoritative, MUTABLE envelope (display names, observed_at,
+ *               self-reported task/provenance, evidence summaries). It carries its OWN
+ *               `observation_digest`. The same fact re-observed → same credential_id/core_digest,
+ *               possibly different observation_digest. credential_id does NOT authenticate the
+ *               observation envelope.
+ *
+ * Trust boundary: this is a PURE verifier over a CALLER-SUPPLIED response. It validates
+ * STRUCTURE + repository anchoring; it does NOT prove the response authentically came from
+ * GitHub. `verification_state='verified'` = structural + repo-anchor verification only.
+ * Source-authenticity (authenticated fetch) is deferred to PR 3B.
+ *
+ * Canonical = zod (no new dependency). The committed JSON Schema is generated by
+ * `toJSONSchema()` (drift-guarded) and carries the cross-field rules as `allOf` if/then.
+ */
+import { z } from 'zod';
+export const CONTRIBUTION_TYPES = ['code', 'tests', 'audit', 'maintenance', 'governance', 'usage', 'transaction', 'referral']; // RFC-017 §5
+// 'unknown' included so a missing/invalid self-report is recorded honestly, NOT guessed as human.
+export const PROVENANCE = ['human', 'ai_assisted', 'ai_authored', 'unknown'];
+// 'unknown' included so a missing GitHub visibility is recorded honestly, NOT assumed public.
+export const VISIBILITY = ['public', 'private', 'internal', 'unknown'];
+export const VERIFICATION_STATE = ['verified', 'unverified', 'insufficient_evidence'];
+export const EVIDENCE_SCOPE = ['public_metadata', 'repo_collaborator_metadata'];
+export const DCO_STATE = ['present', 'absent', 'unknown'];
+// per-evidence-stream coverage — machine-readable so a consumer can tell "observed zero" from
+// "not observed". 'partial' = fetched but truncated at the page cap (more may exist).
+export const EVIDENCE_COVERAGE = ['observed', 'unobserved', 'partial'];
+// The PURE PR verifier mints ONLY the `merged` lifecycle (merged-only profile). A pure PR response
+// cannot independently prove reverted / superseded / void (it only proves THIS PR merged, not that
+// it rolled back a target credential) — ALL of them are DEFERRED to a separate lifecycle-event
+// verifier (PR 3B) with their own trusted evidence + reason rules. The field/enum keeps the slot
+// for forward compatibility; the verifier forces `merged` + `supersedes_credential_id = null`.
+export const LIFECYCLE_EVENT = ['merged'];
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const nonNegInt = z.number().int().min(0);
+export const CREDENTIAL_TYPE = 'github_contribution_credential';
+// v2 (PR 3B-2): adds observation.evidence_coverage. A strict schema rejects unknown fields in BOTH
+// directions, so an additive field is NOT v1-compatible — this is a formal version bump. There are
+// no persisted v1 credentials (no storage yet), so v2 cleanly supersedes. credential_version is in
+// the digest, so v2 of the same GitHub fact gets a different credential_id (domain/version isolation).
+export const CREDENTIAL_VERSION = '2';
+// ── immutable GitHub fact core ──────────────────────────────────────────────
+// strictObject: reject unknown fields so the immutable core cannot carry un-digested claims,
+// and so zod matches the JSON Schema's additionalProperties:false (consumer parity).
+export const CoreObject = z.strictObject({
+    credential_type: z.literal(CREDENTIAL_TYPE), // fixed protocol domain (digest isolation)
+    credential_version: z.literal(CREDENTIAL_VERSION), // version domain (v2 of same fact ⇒ different id)
+    repository_id: z.string().min(1), // stable GitHub node/database id
+    pr_node_id: z.string().min(1), // stable
+    pr_number: z.number().int().positive(),
+    base_ref: z.string().min(1),
+    head_sha: z.string().min(1), // actual observed head sha (force-push aware)
+    merge_commit_sha: z.string().min(1).nullable(),
+    merged_at: z.string().min(1).nullable(),
+    github_actor_id: z.string().min(1), // stable
+    lifecycle_event: z.enum(LIFECYCLE_EVENT),
+    supersedes_credential_id: z.string().min(1).nullable(), // merged-only profile ⇒ always null (reverted/etc. deferred)
+});
+// ── non-authoritative, mutable observation envelope (strictObject — reject unknown fields) ──
+export const ObservationObject = z.strictObject({
+    observed_at: z.string().min(1),
+    repository_owner: z.string().min(1), // display (mutable)
+    repository_name: z.string().min(1), // display (mutable)
+    repository_visibility_at_observation: z.enum(VISIBILITY), // 'unknown' when GitHub didn't say (never guessed public)
+    head_ref: z.string().min(1), // display (branch may be renamed/deleted)
+    github_login: z.string().min(1), // display (mutable)
+    commit_authors: z.array(z.strictObject({
+        author_id: z.string().nullable(), login: z.string().nullable(), name: z.string().nullable(), is_coauthor: z.boolean(),
+    })), // NO emails (rule 10)
+    agent_provenance: z.enum(PROVENANCE), // self-declared; 'unknown' when not validly self-reported (never guessed human)
+    claimed_task_id: z.string().nullable(), // self-reported, NON-authoritative (rule 1/9)
+    source_ref: z.string().nullable(), // self-reported, NON-authoritative
+    contribution_type: z.enum(CONTRIBUTION_TYPES).nullable(), // candidate classification; null when not self-reported (never guessed 'code')
+    verification_state: z.enum(VERIFICATION_STATE), // structural + repo-anchor only (see trust boundary)
+    evidence_scope: z.enum(EVIDENCE_SCOPE),
+    checks_summary: z.strictObject({ total: nonNegInt, success: nonNegInt, failure: nonNegInt, neutral: nonNegInt, other: nonNegInt }),
+    reviews_summary: z.strictObject({ approved: nonNegInt, changes_requested: nonNegInt, commented: nonNegInt, reviewer_ids: z.array(z.string()) }),
+    dco_state: z.enum(DCO_STATE), // independent of co-authors (rule 8)
+    // machine-readable per-stream coverage: distinguishes "observed zero" from "not observed".
+    // A summary's zeros/unknown are only meaningful when its coverage is 'observed'.
+    // required in v2 — every minted credential reports per-stream coverage.
+    evidence_coverage: z.strictObject({
+        checks: z.enum(EVIDENCE_COVERAGE),
+        reviews: z.enum(EVIDENCE_COVERAGE),
+        commit_authors: z.enum(EVIDENCE_COVERAGE),
+        dco: z.enum(['observed', 'unobserved']), // single check, no pagination → no 'partial'
+    }),
+    merged_by_actor_id: z.string().nullable(),
+    evidence_refs: z.array(z.string()), // stable refs (no tokens/PII)
+    known_limitations: z.array(z.string()),
+});
+export const GithubCredentialObject = z.strictObject({
+    credential_id: z.string().min(1), // = ghc_<core_digest[0:40]>; authenticates ONLY core
+    event_source: z.literal('github_api'), // CLAIMED source; not proof of source authenticity (see trust boundary)
+    accountable_party_ref: z.null(), // rule 7: reserved, set later on the FACT (not here)
+    core: CoreObject,
+    core_digest: z.string().regex(SHA256_HEX), // SHA-256 over core fields — the immutable fact identity
+    observation: ObservationObject,
+    observation_digest: z.string().regex(SHA256_HEX), // SHA-256 over the observation envelope (a specific observation)
+});
+export const GithubCredentialSchema = GithubCredentialObject.superRefine((c, ctx) => {
+    // merged-only profile: lifecycle is `merged` only ⇒ a merge happened, verified, and NO parent link.
+    if (c.core.lifecycle_event === 'merged') {
+        if (c.core.merge_commit_sha === null)
+            ctx.addIssue({ code: 'custom', path: ['core', 'merge_commit_sha'], message: 'merged requires merge_commit_sha' });
+        if (c.core.merged_at === null)
+            ctx.addIssue({ code: 'custom', path: ['core', 'merged_at'], message: 'merged requires merged_at' });
+        if (c.observation.verification_state !== 'verified')
+            ctx.addIssue({ code: 'custom', path: ['observation', 'verification_state'], message: 'minted credential requires verification_state=verified' });
+        if (c.core.supersedes_credential_id !== null)
+            ctx.addIssue({ code: 'custom', path: ['core', 'supersedes_credential_id'], message: 'merged must NOT supersede (null parent link)' });
+    }
+});
+/** Structural JSON Schema (Draft 2020-12) + cross-field if/then (parity with superRefine). */
+export function toJSONSchema() {
+    const base = z.toJSONSchema(GithubCredentialObject);
+    base.allOf = [
+        // merged ⇒ merge anchors present + verified + NO parent link
+        {
+            if: { properties: { core: { properties: { lifecycle_event: { const: 'merged' } }, required: ['lifecycle_event'] } }, required: ['core'] },
+            then: {
+                properties: {
+                    core: { properties: { merge_commit_sha: { type: 'string' }, merged_at: { type: 'string' }, supersedes_credential_id: { type: 'null' } }, required: ['merge_commit_sha', 'merged_at', 'supersedes_credential_id'] },
+                    observation: { properties: { verification_state: { const: 'verified' } }, required: ['verification_state'] },
+                },
+                required: ['core', 'observation'],
+            },
+        },
+    ];
+    return base;
+}