@seasonkoh/webaz 0.1.26 → 0.1.27

package/dist/layer1-agent/L1-1-mcp-server/server.js

@@ -521,7 +521,7 @@ Options:
                 },
                 promoter_api_key: {
                     type: 'string',
-                    description: "Referrer api_key (optional). ⚠️ Only L1 recorded (direct referrer, 70% commission); L2/L3 can't be inferred via MCP, redirects per region rule (singapore-like high max_levels → charity chain_gap; global max_levels=1 → global_fund region cap). Full 7:2:1 three-tier chain requires buyer clicking ?ref= URL from webaz_share_link (creates product_share_attribution).",
+                    description: "Referrer api_key (optional). ⚠️ Only L1 recorded (direct referrer, 70% commission); L2/L3 can't be inferred via MCP, so the undelivered L2/L3 portions go to commission_reserve (protocol reserve, in-only). Full 7:2:1 three-tier chain requires buyer clicking ?ref= URL from webaz_share_link (creates product_share_attribution).",
                 },
                 // B2 隐私购物
                 anonymous_recipient: {
@@ -1444,7 +1444,8 @@ Discovery + suggesting need NO api_key (anyone / any agent can browse and propos
 Actions:
 - list_open (default): open public tasks (opt. filters: area / risk_level / auto_claimable / required_capabilities / agent_capabilities / max_duration_minutes / estimated_context_size / estimated_agent_budget — estimated_agent_budget is a resource/effort estimate, NOT a payment). Each task carries its execution boundary + the trusted canonical contribution target. NO api_key needed.
 - detail: one task's full execution boundary (allowed/forbidden paths, prohibited actions, acceptance criteria, verification commands, deliverables, definition_of_done) + the canonical repo to PR to + a copy-ready agent_handoff. NO api_key needed.
-- suggest: propose a NEW task (title + summary/reason; opt. area/expected_outcome/source_ref/github_login). It enters the maintainer inbox — it is a suggestion, NOT a contribution fact / reward / participation, and never auto-becomes a task. NO api_key needed.
+- suggest: propose a NEW task (title + summary/reason; opt. area/expected_outcome/source_ref/github_login). It enters the maintainer inbox — it is a suggestion, NOT a contribution fact / reward / participation, and never auto-becomes a task. NO api_key needed (but pass your key to LINK it to your account so you can track it via my_suggestions).
+- my_suggestions: your OWN past proposals + their review status / public_reply / next_action (api_key). Agent-readable 回执 so a proposer-agent can act on the maintainer's decision (needs_info → resubmit; converted → see converted_ref).
 - claim: take an open task (api_key); provenance=human|ai_assisted|ai_authored (self-declared, not detected); auto-expires ~7d if not submitted. Returns a handoff — point a coding agent at it; the human needn't know git but stays accountable (Passkey).
 - submit: mark in_review with pr_ref + verification_summary (api_key). The PR's base repo MUST be the canonical WebAZ repo, and a verification_summary (what you ran/verified) is REQUIRED — both server-enforced. A human maintainer reviews next; done ≠ merge.
 - status: tasks you hold (api_key).
@@ -1454,12 +1455,12 @@ Coordinates + records only — NO merge/reward; acceptance (done) = human mainta
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['list_open', 'detail', 'suggest', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | detail | suggest | claim | submit | status | profile' },
+                action: { type: 'string', enum: ['list_open', 'detail', 'suggest', 'my_suggestions', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | detail | suggest | my_suggestions | claim | submit | status | profile' },
                 api_key: { type: 'string', description: 'claim/submit/status/profile: your api_key (accountable identity). NOT needed for list_open/detail/suggest. (or set the WEBAZ_API_KEY env var)' },
                 task_id: { type: 'string', description: 'detail / claim / submit: the task id' },
                 area: { type: 'string', description: 'list_open: area filter / suggest: suggested area (e.g. search / docs / mcp)' },
                 risk_level: { type: 'string', enum: ['low', 'medium', 'high', 'critical'], description: 'list_open: optional risk filter' },
-                auto_claimable: { type: 'boolean', description: 'list_open: optional filter — only auto-claimable (true) or manual-claim (false) tasks' },
+                auto_claimable: { type: 'boolean', description: 'list_open: optional filter — true returns tasks an agent can just do (auto-claimable AND with a real effort estimate; matches the derived claimability=auto_claimable), false returns manual-claim tasks. A task with a placeholder (unknown) estimate is treated as manual_review even if its raw auto_claimable flag is true, so it is excluded from true.' },
                 required_capabilities: { type: 'string', description: 'list_open: optional filter — comma-separated; matches tasks that REQUIRE ALL of the listed capabilities (superset/AND match on the task requirement). For "tasks my agent can do", use agent_capabilities instead.' },
                 agent_capabilities: { type: 'string', description: 'list_open: optional filter — capabilities your agent HAS (comma-separated); matches tasks whose required_capabilities are a SUBSET of these, i.e. tasks your agent can actually do' },
                 max_duration_minutes: { type: 'number', description: 'list_open: optional filter — only tasks whose estimated max duration fits within this many minutes (your idle time)' },
@@ -1518,18 +1519,22 @@ async function handleFeedback(args) {
 }
 // RFC-006 断点1(b)交接:从【可信】canonical 目标(API 响应里,绝不硬编码/不取自 task metadata)构造"怎么真正
 // 动手"。人的编码 agent 做 git/PR;Passkey 真人担责。sandbox 运行 / 本地草稿不算正式参与。
-function buildContributeHandoff(cct, taskId) {
+function buildContributeHandoff(cct, taskId, caseId) {
     const c = (cct ?? {});
-    const repoUrl = c.canonical_github_url || 'https://github.com/seasonsagents-art/webaz';
-    const baseRepo = c.expected_pr_base_repo || c.canonical_repository_full_name || 'seasonsagents-art/webaz';
+    const repoUrl = c.canonical_github_url || 'https://github.com/webaz-protocol/webaz';
+    const baseRepo = c.expected_pr_base_repo || c.canonical_repository_full_name || 'webaz-protocol/webaz';
     const baseBranch = c.base_branch || 'main';
+    // case_id threads proposal → task → PR. = the source proposal id when this task came from a proposal,
+    // else the task id itself. Quote it in the PR so the whole case stays traceable end to end.
+    const cid = caseId || taskId;
     return {
+        case_id: cid,
         canonical_repo: baseRepo,
         repo: repoUrl,
         base_branch: baseBranch,
         start_here: 'Read AGENTS.md (project map + before-you-code + PR flow), then CONTRIBUTING.md.',
         do_the_work: 'Point a coding agent (e.g. Claude Code) at the repo on a single-topic branch. The buyer/shopping agent is not the coding agent — hand off to one.',
-        submit_pr: `Open a PR whose BASE repo is ${baseRepo} (${repoUrl}), base branch ${baseBranch}. If any target repo differs from this canonical repo, STOP and ask the human — never contribute to a non-canonical repository.`,
+        submit_pr: `Open a PR whose BASE repo is ${baseRepo} (${repoUrl}), base branch ${baseBranch}. Reference case ${cid} in the PR title/body so the proposal → task → PR chain stays traceable. If any target repo differs from this canonical repo, STOP and ask the human — never contribute to a non-canonical repository.`,
         pr_flow: 'Commit with DCO sign-off (git commit -s). If AI-authored, mark the PR per the meta-rule. Humans merge — no auto-merge.',
         then: `When the PR is open, report it back: webaz_contribute action=submit task_id=${taskId} pr_ref=#<N> verification_summary="<the verification_commands you ran + their results>". Both pr_ref and verification_summary are required.`,
         not_participation: 'A sandbox run or a local-only draft is NOT participation and is NOT a contribution; only a merged PR (or recognized issue/task/RFC) on the canonical repo enters the contribution record.',
@@ -1580,7 +1585,7 @@ export async function handleContribute(args) {
             return { error: 'task_id required for action=detail' };
         const r = await apiCall('/api/public/build-tasks/' + encodeURIComponent(tid));
         if (!r.error && r.task)
-            r.agent_handoff = buildContributeHandoff(r.canonical_contribution_target, tid);
+            r.agent_handoff = buildContributeHandoff(r.canonical_contribution_target, tid, r.task.case_id);
         return r;
     }
     if (action === 'suggest') {
@@ -1592,6 +1597,7 @@ export async function handleContribute(args) {
             return { error: 'summary (the reason) required for action=suggest' };
         const r = await apiCall('/api/public/task-proposals', {
             method: 'POST',
+            apiKey, // optional — when present, links the proposal to the submitter so it shows up in action=my_suggestions (still works anonymously)
             body: {
                 title, summary,
                 suggested_area: args.area ?? args.suggested_area,
@@ -1600,6 +1606,8 @@ export async function handleContribute(args) {
                 proposer_github_login: args.proposer_github_login,
             },
         });
+        if (!r.error && r.linked_to_account)
+            r._next = 'Track this proposal\'s review status + reply: webaz_contribute action=my_suggestions api_key=<key>.';
         // typed errors (RATE_LIMITED / DUPLICATE_PROPOSAL / validation) are already mapped by apiCall; the
         // success response already carries the route-level `proposal_notice` (suggestion ≠ contribution/reward).
         return r;
@@ -1612,6 +1620,13 @@ export async function handleContribute(args) {
         };
     if (action === 'status')
         return apiCall('/api/build-tasks?mine=1', { apiKey });
+    if (action === 'my_suggestions') {
+        // your OWN past proposals + review status/public_reply/next_action (agent-readable 回执). Own rows only (server-enforced).
+        const r = await apiCall('/api/me/task-proposals', { apiKey });
+        if (!r.error)
+            r._next = 'Each item carries status + public_reply + next_action. needs_info → resubmit via action=suggest referencing the id; converted → see converted_ref.';
+        return r;
+    }
     if (action === 'profile')
         return apiCall('/api/build-reputation/me', { apiKey });
     if (action === 'claim') {
@@ -1730,8 +1745,11 @@ async function handleInfo() {
         // 连接两个场景:用协议(本工具) ↔ 改协议(开发协作)。想改 WebAZ 本身的 agent 从这里进。
         for_contributors: {
             note: 'Want to change WebAZ itself (not just use it)? This is an open, agent-native protocol — AI-authored PRs are welcome, with accountability. / 想改 WebAZ 本身(不只是用)?这是开放的 agent 原生协议,欢迎 AI 提 PR,但需问责。',
-            repo: 'https://github.com/seasonsagents-art/webaz',
+            repo: 'https://github.com/webaz-protocol/webaz',
             start_here: 'AGENTS.md (project map + before-you-code + PR flow) → CONTRIBUTING.md (full guide)',
+            // 低门槛路径:无需 api_key、无需 clone 仓库,直接经协议发现任务 / 提建议(对外 well-known 入口也有,见 agent_quickstart)。
+            no_key_path: 'No api_key needed to START contributing: discover open tasks and submit a suggestion via webaz_contribute action=list_open / action=suggest (mirrors GET /api/public/build-tasks + POST /api/public/task-proposals). / 无需 key 即可起步:webaz_contribute action=list_open 发现开放任务、action=suggest 提建议。',
+            contribution_boundary: 'A suggestion is a proposal in the maintainer review inbox — NOT a contribution fact, NOT formal participation, and NOT any economic or redemption right; recorded contribution is facts / evidence / attribution only (RFC-017). / 建议只是进入维护者审阅箱的提议,不是贡献事实、不是正式参与、不构成任何经济或兑现权利;记录的贡献只是事实/证据/归属(RFC-017)。',
             ai_accountability: 'AI-authored PRs: add 🤖🤖🤖 to the PR title; the agent must be triggered by a Passkey-bound human (webazer) who is accountable. / AI 提 PR:标题加 🤖🤖🤖,且须由已绑 Passkey 的真人(webazer)触发并担责。',
         },
         // NETWORK 模式:真网络 live 状态(best-effort 拉自 webaz.xyz);SANDBOX 模式为 null。
@@ -1741,10 +1759,10 @@ async function handleInfo() {
         // 佣金机制 —— 纯功能性描述(怎么运作),不做"自证清白"式辩护。
         commission_model: {
             split: '7:2:1 — L1 70% / L2 20% / L3 10% of an order\'s commission_pool',
-            jurisdiction_tiers: 'Tiers are graded by the order region\'s max_levels — NOT a uniform 3 tiers everywhere. e.g. global region max_levels=1 → L1 only; singapore (etc.) max_levels=3 → up to L3. A region may also be 0 (no commission tiers; pool → community fund).',
+            jurisdiction_tiers: 'Tiers are graded by the order region\'s max_levels — NOT a uniform 3 tiers everywhere. e.g. global region max_levels=1 → L1 only; singapore (etc.) max_levels=3 → up to L3. A region may also be 0 (no commission tiers; pool → commission_reserve / protocol reserve).',
             attribution: 'EXPLICIT per-order — commission goes to the promoter attributed at purchase time, not derived from the buyer\'s sponsor chain.',
             how_to_attribute: 'L1: webaz_place_order(promoter_api_key) records the direct promoter. Full L2/L3 chain requires the buyer to arrive via a webaz_share_link /i/<permanent_code> (?ref=<permanent_code>) URL clicked in a browser (builds product_share_attribution).',
-            redirect_rules: 'chain_gap (no L / invalid sponsor) → charity_fund; level beyond the region cap → global_fund.',
+            redirect_rules: 'all undelivered commission (chain_gap / no L / invalid sponsor / level beyond the region cap / max_levels=0 / opt-out / escrow expiry) → commission_reserve (protocol reserve, in-only; use decided by governance).',
             l1_gate: 'the promoter must be a verified buyer (≥1 completed order) to receive commission, otherwise that share redirects.',
             opt_in: 'Participation is opt-in (RFC-002): default = off. A user applies (Passkey + ≥1 completed order); attribution is always recorded. Commission destination is state-dependent: never_activated / auto_downgraded → held in pending_commission_escrow (30d grace), recoverable by (re-)activating within the window, else swept to commission_reserve; deactivated (active opt-out) → future commission goes directly to commission_reserve, NOT escrow and NOT recoverable. Never to charity_fund. See docs/rfcs/RFC-002-rewards-opt-in.md.',
         },
@@ -3438,7 +3456,7 @@ function handleRotateKey(args) {
         },
     };
 }
-// ─── 推广 / 双轨 (Tokenomics) ───────────────────────────────────
+// ─── 推广 / 推荐网络 (Tokenomics) ───────────────────────────────────
 async function handleReferral(args) {
     // RFC-003 Batch 2:NETWORK 模式 → webaz.xyz 真网络聚合(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_referral') === 'network') {
@@ -3465,16 +3483,9 @@ async function handleReferral(args) {
     const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
     const override = db.prepare("SELECT l1_share_override FROM users WHERE id = ?").get(userId)?.l1_share_override ?? 0;
     const canL1 = override === 1 || (override === 0 && completed > 0);
-    // 原子能双轨
+    // Neutral participation record only — placement position + per-leg PV. Matching-rewards engine excised (#401):
+    // no Score / tier / pair-volume / payout is read or exposed.
     const me = db.prepare("SELECT total_left_pv, total_right_pv, left_child_id, right_child_id, placement_id, placement_side FROM users WHERE id = ?").get(userId);
-    const score = db.prepare(`
-    SELECT COALESCE(SUM(CASE WHEN settled_at IS NULL THEN score ELSE 0 END),0) as pending,
-           COALESCE(SUM(CASE WHEN settled_at IS NOT NULL THEN waz_amount ELSE 0 END),0) as settled_waz
-    FROM binary_score_records WHERE user_id = ?
-  `).get(userId);
-    const tiers = db.prepare("SELECT tier, pv_threshold, score_per_hit FROM binary_tier_config WHERE active=1 ORDER BY tier ASC").all();
-    const pair = Math.min(Number(me?.total_left_pv ?? 0), Number(me?.total_right_pv ?? 0));
-    const nextTier = tiers.find(t => t.pv_threshold > pair);
     // invite / share links use permanent_code ONLY — never usr_xxx. (sandbox users have one from register.)
     const permaCode = db.prepare("SELECT permanent_code FROM users WHERE id = ?").get(userId)?.permanent_code || null;
     return {
@@ -3496,15 +3507,12 @@ async function handleReferral(args) {
             l1: byLevel[1], l2: byLevel[2], l3: byLevel[3],
             grand_total: byLevel[1].total + byLevel[2].total + byLevel[3].total,
         },
-        binary: {
-            // pre-public 去左右码:只暴露唯一的推荐码;放置侧别由系统自动决定(无 left/right 选择)
+        placement: {
+            // Neutral participation/attribution record: a single referral code + per-leg PV. No matching rewards.
             referral_link: permaCode ? `/i/${permaCode}` : null,
             total_left_pv: Number(me?.total_left_pv ?? 0),
             total_right_pv: Number(me?.total_right_pv ?? 0),
-            pair_volume: pair,
-            next_tier: nextTier ? { tier: nextTier.tier, pv_threshold: nextTier.pv_threshold, score_per_hit: nextTier.score_per_hit, pv_needed: nextTier.pv_threshold - pair } : null,
-            score_pending: score.pending,
-            waz_total_earned: score.settled_waz,
+            note: 'total_left_pv / total_right_pv are a participation / attribution record only — not income, not redeemable, no entitlement.',
         },
         rewards_status: (() => {
             // RFC-002 §3.5 — 4 states + pending escrow visibility (PR-4)

package/dist/layer2-business/L2-9-contribution/admin-coordination-ingestion-engine.js

@@ -0,0 +1,181 @@
+import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
+import { coordinationActionSpec, LIVE_ADMIN_COORDINATION_AUDIT_ACTIONS } from './admin-coordination-store.js';
+import { resolveOperatorClaimAsOf, resolveAgentMandateAsOf } from './admin-coordination-resolver.js';
+import { readAdminActionContext } from '../../pwa/admin-audit.js';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function deriveProvenance(ctx) {
+    const p = ctx.provenance;
+    if (p === 'human' || p === 'ai_assisted' || p === 'ai_authored' || p === 'unknown')
+        return p;
+    if (ctx.actor_type === 'agent')
+        return ctx.agent_mode === 'agent_assisted' ? 'ai_assisted' : 'ai_authored';
+    if (ctx.actor_type === 'human' || ctx.actor_type === 'admin_account')
+        return ctx.agent_mode === 'human_direct' ? 'human' : 'unknown';
+    return 'unknown';
+}
+export function ingestAdminCoordinationFact(db, input) {
+    const { auditId, redactionSummary } = input;
+    if (!auditId)
+        return { ok: false, reason: 'invalid_input', detail: 'auditId is required' };
+    // ── anchor: the audit row is the evidence truth; read EVERYTHING from it (incl. the coordinated
+    // object target_id) so the fact can NEVER point at a different object than the audit row records ──
+    const row = db.prepare('SELECT id, admin_id, action, detail, created_at, target_type, target_id FROM admin_audit_log WHERE id = ?').get(auditId);
+    if (!row)
+        return { ok: false, reason: 'audit_row_not_found', detail: auditId };
+    const action = row.action;
+    const spec = coordinationActionSpec(action);
+    if (!spec)
+        return { ok: false, reason: 'unknown_action', detail: action }; // allowlist fail-closed
+    const ctx = readAdminActionContext(row.detail);
+    const actorType = ctx.actor_type;
+    const adminAccountId = row.admin_id;
+    const occurredAt = row.created_at;
+    // legacy / context-less / system rows are NOT contribution-eligible.
+    if (actorType !== 'human' && actorType !== 'admin_account' && actorType !== 'agent') {
+        return { ok: false, reason: 'not_eligible_context', detail: `actor_type=${String(actorType)}` };
+    }
+    // ── attribution gate (as-of) — NOT written onto the fact; only proves the work is attributable ──
+    let contributorAccountId;
+    let via;
+    let executorRef;
+    if (actorType === 'agent') {
+        const actorRef = String(ctx.actor_ref || '');
+        const agentRef = actorRef.startsWith('agent:') ? actorRef.slice('agent:'.length) : actorRef;
+        const mandateId = ctx.mandate_id ? String(ctx.mandate_id) : '';
+        // The audit row's mandate_id is REQUIRED and DECIDES attribution — resolve by (agent_ref, mandate_id),
+        // never by agent_ref alone (one agent_ref may hold several mandates → wrong-account错账 otherwise).
+        if (!agentRef || !mandateId)
+            return { ok: false, reason: 'not_eligible_context', detail: 'agent action requires _ctx.actor_ref + _ctx.mandate_id' };
+        const m = resolveAgentMandateAsOf(db, agentRef, mandateId, occurredAt);
+        if (!m)
+            return { ok: false, reason: 'no_attribution', detail: `no valid mandate (agent_ref=${agentRef}, mandate_id=${mandateId}) as-of occurred_at` };
+        if (!m.allowed_actions.includes(action))
+            return { ok: false, reason: 'agent_action_not_in_mandate', detail: action };
+        contributorAccountId = m.owner_contributor_account_id;
+        via = 'agent_mandate';
+        executorRef = `agent:${agentRef}#${mandateId}`; // mandate encoded → deterministic read-time resolution
+    }
+    else {
+        const c = resolveOperatorClaimAsOf(db, adminAccountId, occurredAt);
+        if (!c)
+            return { ok: false, reason: 'no_attribution', detail: 'no approved operator claim as-of occurred_at' };
+        // A self/related (root/founder bootstrap) approval that is NOT honestly disclosed must NOT enter
+        // production evidence — fail closed until an append-only marking correction discloses self_or_related.
+        if (c.self_related && !c.honestly_disclosed) {
+            return { ok: false, reason: 'self_related_not_disclosed', detail: `claim ${c.claim_event_id} is self/related but marked ${c.approval_kind}/${c.conflict_disclosure}; needs a governance-marking correction` };
+        }
+        contributorAccountId = c.contributor_account_id;
+        via = 'operator_claim';
+        executorRef = `admin:${adminAccountId}`;
+    }
+    const provenance = deriveProvenance(ctx);
+    const visibility = input.visibility ?? 'governance_only';
+    const sourceEventKey = `admin:${auditId}:coordination`;
+    // The coordinated object is the audit row's target_id (NOT a caller-supplied value). artifact_ref is
+    // NOT NULL → fall back to the action when the row has no target_id; source_id mirrors it (or NULL).
+    const targetId = row.target_id ?? null;
+    const artifactRef = targetId || action;
+    // dry-run: all gates passed; report what WOULD happen without writing (read-only — no insert, no tx).
+    if (input.dryRun) {
+        const existing = db.prepare('SELECT fact_id FROM contribution_facts WHERE source_event_key = ?').get(sourceEventKey);
+        return { ok: true, status: existing ? 'already_present' : 'would_ingest', factId: existing?.fact_id ?? '(dry-run)', sourceEventKey, executorRef, contributorAccountId, via };
+    }
+    const run = db.transaction(() => {
+        const existing = db.prepare('SELECT fact_id FROM contribution_facts WHERE source_event_key = ?').get(sourceEventKey);
+        if (existing)
+            return { factId: existing.fact_id, status: 'already_present' };
+        const factId = generateId('cfact');
+        db.prepare(`INSERT INTO contribution_facts (fact_id, source_event_key, source, type, artifact_ref, occurred_at, executor_ref, accountable_ref, provenance, status, immutable)
+       VALUES (?,?,?,?,?,?,?, NULL, ?, 'active', 1)`).run(factId, sourceEventKey, spec.factSource, spec.factType, artifactRef, occurredAt, executorRef, provenance);
+        db.prepare(`INSERT INTO admin_coordination_fact_sources (fact_id, admin_audit_log_id, source_type, source_id, visibility, redaction_summary)
+       VALUES (?,?,?,?,?,?)`).run(factId, auditId, action, targetId, visibility, redactionSummary ?? null);
+        return { factId, status: 'ingested' };
+    });
+    const out = run.immediate();
+    return { ok: true, status: out.status, factId: out.factId, sourceEventKey, executorRef, contributorAccountId, via };
+}
+// ───────────────────────────── batch / operator entry ─────────────────────────────
+// Small, bounded, manual-run batch over ALLOWLISTED audit rows. NOT a historical backfill: the operator
+// scopes it with sinceTime / sinceId + a hard limit, and it is DRY-RUN unless `commit` is set. Each row
+// goes through the SAME single-row engine above (same fail-closed gates, same idempotency), so the batch
+// adds no new attribution logic — it only selects candidates and aggregates the per-row outcomes.
+export const DEFAULT_INGEST_LIMIT = 50;
+export const MAX_INGEST_LIMIT = 500;
+/**
+ * Parse the `--commit` switch at the production write entry. Accept ONLY a bare flag (`raw === ''`) or
+ * `--commit=true`. Anything else (`false`, `0`, `no`, …) THROWS — an explicit dry-run intent must never
+ * be misread as a write. `undefined` (flag absent) → false (dry-run).
+ */
+export function parseCommitSwitch(raw) {
+    if (raw === undefined)
+        return false;
+    if (raw === '' || raw === 'true')
+        return true;
+    throw new Error(`invalid_commit_flag: --commit takes no value (or =true); got ${JSON.stringify(raw)}`);
+}
+/**
+ * Select rows whose action is in the LIVE production set (only the real `operator_claim.*` actions —
+ * NOT the reserved concept names), run each through the single-row engine, and aggregate. Dry-run by
+ * default (NOTHING written unless `commit: true`). The candidate query filters to the live set so
+ * non-coordination AND reserved-concept rows are never even scanned; unknown/uneligible/no-claim rows
+ * that DO match still fail closed per-row and are reported as `skipped` with a reason.
+ *
+ * THROWS `invalid_cursor` when `sinceId` is supplied but matches no audit row — a fail-closed guard so a
+ * typo'd cursor can NEVER silently degrade into a from-the-beginning (backfill) scan.
+ *
+ * THROWS `commit_requires_cursor` when `commit` is true but NEITHER `sinceTime` nor `sinceId` is given —
+ * a no-cursor commit would write from the earliest live row, i.e. a small historical backfill. This
+ * pipeline is "from the present, cursor + limit scoped", so a write MUST be cursor-bounded. A no-cursor
+ * DRY-RUN is still allowed (preview from the earliest row writes nothing).
+ */
+export function ingestAdminCoordinationSince(db, options = {}) {
+    const commit = options.commit === true;
+    if (commit && !options.sinceTime && !options.sinceId) {
+        throw new Error('commit_requires_cursor: --commit requires --since-time or --since-id (no-cursor commit would backfill history); run a dry-run first to find a cursor');
+    }
+    const limit = Math.min(Math.max(1, options.limit ?? DEFAULT_INGEST_LIMIT), MAX_INGEST_LIMIT);
+    const actions = [...LIVE_ADMIN_COORDINATION_AUDIT_ACTIONS];
+    const placeholders = actions.map(() => '?').join(',');
+    const where = [`action IN (${placeholders})`];
+    const params = [...actions];
+    // resume cursor: rows strictly after (cursorTime, cursorId) in (created_at ASC, id ASC) order.
+    let cursorTime = options.sinceTime;
+    let cursorId;
+    if (options.sinceId) {
+        const c = db.prepare('SELECT id, created_at FROM admin_audit_log WHERE id = ?').get(options.sinceId);
+        // fail-closed: an explicit-but-unknown cursor must NOT degrade into a full from-earliest scan.
+        if (!c)
+            throw new Error(`invalid_cursor: no admin_audit_log row with id=${options.sinceId}`);
+        cursorTime = c.created_at;
+        cursorId = c.id;
+    }
+    if (cursorTime && cursorId) {
+        where.push('(created_at > ? OR (created_at = ? AND id > ?))');
+        params.push(cursorTime, cursorTime, cursorId);
+    }
+    else if (cursorTime) {
+        where.push('created_at > ?');
+        params.push(cursorTime);
+    }
+    params.push(limit);
+    const candidates = db.prepare(`SELECT id, action, admin_id, created_at FROM admin_audit_log WHERE ${where.join(' AND ')} ORDER BY created_at ASC, id ASC LIMIT ?`).all(...params);
+    const rows = [];
+    let ingested = 0, wouldIngest = 0, alreadyPresent = 0, skipped = 0;
+    for (const cand of candidates) {
+        const r = ingestAdminCoordinationFact(db, { auditId: cand.id, visibility: options.visibility, dryRun: !commit });
+        const base = { auditId: cand.id, action: cand.action, adminId: cand.admin_id, occurredAt: cand.created_at };
+        if (!r.ok) {
+            skipped++;
+            rows.push({ ...base, outcome: 'skipped', reason: r.reason + (r.detail ? `: ${r.detail}` : '') });
+            continue;
+        }
+        if (r.status === 'ingested')
+            ingested++;
+        else if (r.status === 'would_ingest')
+            wouldIngest++;
+        else
+            alreadyPresent++;
+        rows.push({ ...base, outcome: r.status, contributorAccountId: r.contributorAccountId, via: r.via, factId: r.factId });
+    }
+    return { committed: commit, scanned: candidates.length, ingested, wouldIngest, alreadyPresent, skipped, limit, rows };
+}

package/dist/layer2-business/L2-9-contribution/admin-coordination-resolver.js

@@ -0,0 +1,114 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/** As-of resolution of which contributor a non-root admin SEAT was attributed to at `asOf`. */
+export function resolveOperatorClaimAsOf(db, adminAccountId, asOf) {
+    const events = db.prepare(`SELECT event_type, contributor_account_id, approval_kind, approved_by, conflict_disclosure, event_id, effective_from, supersedes_event_id, created_at
+     FROM admin_operator_claim_events WHERE admin_account_id = ? ORDER BY effective_from ASC, created_at ASC, rowid ASC`).all(adminAccountId);
+    // An approval is terminated as-of `asOf` iff a revoked/superseded event that is EFFECTIVE by then
+    // LINKS to it (supersedes_event_id). Link-based (not a timestamp window) so a same-second
+    // approve→revoke and a same-instant rotation both resolve deterministically.
+    const terminatedIds = new Set(events
+        .filter(e => (e.event_type === 'revoked' || e.event_type === 'superseded') && e.effective_from && e.effective_from <= asOf && e.supersedes_event_id)
+        .map(e => e.supersedes_event_id));
+    const active = events.filter(e => e.event_type === 'approved' && e.effective_from && e.effective_from <= asOf && !terminatedIds.has(e.event_id));
+    if (active.length === 0)
+        return null;
+    const latest = active[active.length - 1]; // latest effective approval still active as-of asOf
+    // Overlay the LATEST append-only marking correction (if any). The correction never changes the
+    // contributor or the effective interval — only the disclosure marking — so it applies regardless of
+    // asOf (the approval was always self/related; we are only recording that honestly now).
+    const correction = db.prepare(`SELECT approval_kind, conflict_disclosure FROM admin_operator_claim_marking_corrections
+     WHERE approved_event_id = ? ORDER BY corrected_at DESC, rowid DESC LIMIT 1`).get(latest.event_id);
+    const approvalKind = (correction?.approval_kind ?? latest.approval_kind) ?? null;
+    const conflictDisclosure = correction?.conflict_disclosure ?? latest.conflict_disclosure;
+    const approvedBy = latest.approved_by ?? null;
+    // self/related = the approver was itself a party to the claim (admin seat or contributor) — a
+    // root/founder bootstrap self-approval. Such an approval MUST disclose self_or_related + a
+    // non-independent_governance kind; otherwise it is dishonestly marked (gated downstream).
+    const selfRelated = !!approvedBy && (approvedBy === adminAccountId || approvedBy === latest.contributor_account_id);
+    const honestlyDisclosed = !selfRelated || (conflictDisclosure === 'self_or_related' && approvalKind !== 'independent_governance');
+    return {
+        contributor_account_id: latest.contributor_account_id,
+        approval_kind: approvalKind,
+        conflict_disclosure: conflictDisclosure,
+        claim_event_id: latest.event_id,
+        approved_by: approvedBy,
+        self_related: selfRelated,
+        corrected: !!correction,
+        honestly_disclosed: honestlyDisclosed,
+    };
+}
+/**
+ * As-of resolution of a SPECIFIC agent mandate (agent_ref + mandate_id) effective at `asOf` (→ owner
+ * contributor). Keyed on BOTH agent_ref AND mandate_id: when one agent_ref has several mandates, the
+ * audit row's mandate_id decides attribution — never "whichever mandate is latest" (which would
+ * mis-credit). A mandate_id belonging to a different agent_ref does not match.
+ */
+export function resolveAgentMandateAsOf(db, agentRef, mandateId, asOf) {
+    if (!agentRef || !mandateId)
+        return null;
+    const events = db.prepare(`SELECT event_type, mandate_id, owner_contributor_account_id, allowed_actions, effective_from, expires_at, revoked_at, event_id, created_at
+     FROM agent_execution_mandate_events WHERE agent_ref = ? AND mandate_id = ? ORDER BY effective_from ASC, created_at ASC`).all(agentRef, mandateId);
+    const grants = events.filter(e => e.event_type === 'granted' &&
+        e.effective_from && e.effective_from <= asOf &&
+        (!e.expires_at || e.expires_at >= asOf) &&
+        (!e.revoked_at || e.revoked_at > asOf));
+    if (grants.length === 0)
+        return null;
+    const latest = grants[grants.length - 1];
+    const terminated = events.some(e => (e.event_type === 'revoked' || e.event_type === 'superseded') &&
+        e.effective_from && e.effective_from > latest.effective_from && e.effective_from <= asOf);
+    if (terminated)
+        return null;
+    let allowed = [];
+    try {
+        const p = JSON.parse(latest.allowed_actions);
+        if (Array.isArray(p))
+            allowed = p.map(String);
+    }
+    catch {
+        allowed = [];
+    }
+    return { owner_contributor_account_id: latest.owner_contributor_account_id, mandate_id: latest.mandate_id, allowed_actions: allowed, grant_event_id: latest.event_id };
+}
+/**
+ * Unified resolver. `github:<id>` → current identity binding; `admin:<id>` / `agent:<ref>` → as-of
+ * claim/mandate at `occurredAt`. Returns null when no valid attribution exists (the fact then has no
+ * resolvable contributor — it stays evidence only).
+ */
+export function resolveCoordinationContributor(db, executorRef, occurredAt) {
+    if (executorRef.startsWith('github:')) {
+        const githubActorId = executorRef.slice('github:'.length);
+        if (!githubActorId)
+            return null;
+        const row = db.prepare('SELECT account_id FROM identity_bindings_active WHERE github_actor_id = ?').get(githubActorId);
+        if (!row)
+            return null;
+        return { contributor_account_id: row.account_id, via: 'github_binding', detail: {} };
+    }
+    if (executorRef.startsWith('admin:')) {
+        const adminAccountId = executorRef.slice('admin:'.length);
+        if (!adminAccountId)
+            return null;
+        const r = resolveOperatorClaimAsOf(db, adminAccountId, occurredAt);
+        if (!r)
+            return null;
+        return { contributor_account_id: r.contributor_account_id, via: 'operator_claim', detail: { approval_kind: r.approval_kind, conflict_disclosure: r.conflict_disclosure, claim_event_id: r.claim_event_id } };
+    }
+    if (executorRef.startsWith('agent:')) {
+        // executor_ref for agents is `agent:<agent_ref>#<mandate_id>` — the mandate is encoded so read-time
+        // resolution is as deterministic as ingest-time (no "latest mandate wins" ambiguity).
+        const rest = executorRef.slice('agent:'.length);
+        const hash = rest.indexOf('#');
+        if (hash < 0)
+            return null; // no mandate encoded → not resolvable (refuse rather than guess)
+        const agentRef = rest.slice(0, hash);
+        const mandateId = rest.slice(hash + 1);
+        if (!agentRef || !mandateId)
+            return null;
+        const r = resolveAgentMandateAsOf(db, agentRef, mandateId, occurredAt);
+        if (!r)
+            return null;
+        return { contributor_account_id: r.owner_contributor_account_id, via: 'agent_mandate', detail: { mandate_id: r.mandate_id } };
+    }
+    return null;
+}