@seasonkoh/webaz 0.1.24 → 0.1.25

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

@@ -0,0 +1,231 @@
+/**
+ * GitHub Contribution Credential verifier/adapter — PURE function (PR 3A).
+ *
+ * Maps an ALREADY-FETCHED GitHub API response → an immutable credential (or a typed refusal).
+ * **No network I/O, no token.** PR body / self-reported JSON are NON-authoritative.
+ *
+ * TRUST BOUNDARY: this verifies STRUCTURE + repository anchoring of a CALLER-SUPPLIED object. It
+ * does NOT prove the object authentically came from GitHub, and the self-consistency check it runs
+ * is NOT tamper-proof (an attacker who controls the payload can recompute digests). Real
+ * authenticity requires an authenticated fetch / trusted signature — deferred to PR 3B.
+ * `verification_state='verified'` = structural + repo-anchor verification only.
+ *
+ * Lifecycle (merged-only profile): mints ONLY `merged`. reverted/superseded/void are deferred to PR 3B.
+ */
+import { z } from 'zod';
+import { digestCore, digestObject, credentialIdFromDigest } from './canonical.js';
+import { verifyCredentialSelfConsistency } from './self-consistency.js';
+import { GithubCredentialSchema, PROVENANCE, CONTRIBUTION_TYPES, CREDENTIAL_TYPE, CREDENTIAL_VERSION, } from './github-credential.schema.js';
+const idField = z.union([z.string(), z.number()]);
+// Full Zod schema for the external GitHub response — parsing it up-front means malformed input
+// (missing fields, wrong types, non-array commit_authors/reviews/check_conclusions, [null], {}…)
+// becomes a typed refusal instead of a thrown TypeError deep in the mapping code.
+const InputSchema = z.object({
+    repository: z.object({
+        id: idField,
+        owner: z.object({ login: z.string() }),
+        name: z.string(),
+        visibility: z.string().optional(),
+    }),
+    pull_request: z.object({
+        number: z.number(),
+        node_id: z.string(),
+        merged: z.boolean().optional(),
+        state: z.string().optional(),
+        merged_at: z.string().nullable().optional(),
+        merge_commit_sha: z.string().nullable().optional(),
+        base: z.object({ ref: z.string() }),
+        head: z.object({ ref: z.string(), sha: z.string() }),
+        user: z.object({ id: idField, login: z.string() }),
+        merged_by: z.object({ id: idField }).nullable().optional(),
+    }),
+    commit_authors: z.array(z.object({
+        author_id: idField.nullable().optional(),
+        login: z.string().nullable().optional(),
+        name: z.string().nullable().optional(),
+        is_coauthor: z.boolean().optional(),
+    })).optional(),
+    check_conclusions: z.array(z.string()).optional(),
+    reviews: z.array(z.object({ state: z.string(), user_id: idField.optional() })).optional(),
+    dco_state: z.enum(['present', 'absent', 'unknown']).optional(),
+    evidence_coverage: z.object({
+        checks: z.enum(['observed', 'unobserved', 'partial']).optional(),
+        reviews: z.enum(['observed', 'unobserved', 'partial']).optional(),
+        commit_authors: z.enum(['observed', 'unobserved', 'partial']).optional(),
+        dco: z.enum(['observed', 'unobserved']).optional(),
+    }).optional(),
+    observed_at: z.string().min(1),
+    self_reported: z.object({
+        task_id: z.string().nullable().optional(),
+        source_ref: z.string().nullable().optional(),
+        agent_provenance: z.string().optional(),
+        contribution_type: z.string().optional(),
+    }).optional(),
+});
+const s = (v) => v === null || v === undefined || v === '' ? null : String(v);
+function summarizeChecks(conclusions = []) {
+    const sum = { total: conclusions.length, success: 0, failure: 0, neutral: 0, other: 0 };
+    for (const c of conclusions) {
+        if (c === 'success')
+            sum.success++;
+        else if (c === 'failure' || c === 'timed_out' || c === 'cancelled')
+            sum.failure++;
+        else if (c === 'neutral' || c === 'skipped')
+            sum.neutral++;
+        else
+            sum.other++;
+    }
+    return sum;
+}
+// Reviews dedup + final-state rule: GitHub returns reviews chronologically; a reviewer can review
+// many times. A reviewer's FINAL state = the last DECISIVE review (APPROVED | CHANGES_REQUESTED |
+// DISMISSED); COMMENTED never changes the final state. We count one vote per reviewer.
+function summarizeReviews(reviews = []) {
+    const finalDecisive = new Map(); // reviewer id → last decisive state
+    const everCommented = new Set();
+    const allReviewers = [];
+    for (const r of reviews) {
+        const id = s(r.user_id);
+        if (!id)
+            continue;
+        if (!allReviewers.includes(id))
+            allReviewers.push(id);
+        const st = (r.state || '').toUpperCase();
+        if (st === 'APPROVED' || st === 'CHANGES_REQUESTED' || st === 'DISMISSED')
+            finalDecisive.set(id, st);
+        else if (st === 'COMMENTED')
+            everCommented.add(id);
+    }
+    let approved = 0, changes_requested = 0;
+    for (const st of finalDecisive.values()) {
+        if (st === 'APPROVED')
+            approved++;
+        else if (st === 'CHANGES_REQUESTED')
+            changes_requested++; // DISMISSED → counted in neither
+    }
+    let commented = 0;
+    for (const id of everCommented)
+        if (!finalDecisive.has(id))
+            commented++; // commented-only reviewers
+    return { approved, changes_requested, commented, reviewer_ids: allReviewers };
+}
+export function verifyGithubContribution(resp, opts) {
+    // merged-only profile: supports ONLY `merged` (a pure PR response cannot prove reverted/superseded/void).
+    const lifecycle = opts.lifecycle_event ?? 'merged';
+    if (lifecycle !== 'merged') {
+        return { ok: false, outcome: 'unsupported_lifecycle', reasons: [`lifecycle '${lifecycle}' not supported by the pure-PR verifier (merged-only profile; only 'merged'); reverted/superseded/void are deferred to PR 3B's lifecycle-event verifier`] };
+    }
+    // P2: parse the whole external response up-front — malformed input ⇒ typed refusal, never throws.
+    const parsed = InputSchema.safeParse(resp);
+    if (!parsed.success) {
+        return { ok: false, outcome: 'insufficient_evidence', reasons: parsed.error.issues.map(i => `${i.path.join('.') || '(root)'}: ${i.message}`) };
+    }
+    const r = parsed.data;
+    const repoId = s(r.repository.id);
+    const prNodeId = s(r.pull_request.node_id);
+    const baseRef = s(r.pull_request.base.ref);
+    const headSha = s(r.pull_request.head.sha);
+    const actorId = s(r.pull_request.user.id);
+    if (!repoId || !prNodeId || !baseRef || !headSha || !actorId) {
+        const reasons = [];
+        if (!repoId)
+            reasons.push('empty repository_id');
+        if (!prNodeId)
+            reasons.push('empty pr_node_id');
+        if (!baseRef)
+            reasons.push('empty base_ref');
+        if (!headSha)
+            reasons.push('empty head_sha');
+        if (!actorId)
+            reasons.push('empty github_actor_id');
+        return { ok: false, outcome: 'insufficient_evidence', reasons };
+    }
+    if (repoId !== opts.expectedRepositoryId) {
+        return { ok: false, outcome: 'wrong_repository', reasons: [`repository_id ${repoId} != expected ${opts.expectedRepositoryId}`] };
+    }
+    const mergeSha = s(r.pull_request.merge_commit_sha);
+    const mergedAt = s(r.pull_request.merged_at);
+    if (r.pull_request.merged !== true) {
+        return { ok: false, outcome: 'not_merged', reasons: [`pull_request.merged=${r.pull_request.merged}, state=${r.pull_request.state ?? '?'}`] };
+    }
+    if (!mergeSha)
+        return { ok: false, outcome: 'insufficient_evidence', reasons: ['merged=true but missing merge_commit_sha'] };
+    if (!mergedAt)
+        return { ok: false, outcome: 'insufficient_evidence', reasons: ['merged=true but missing merged_at'] };
+    // "cannot verify → never guess": no valid self-report ⇒ unknown / null, NOT human / code.
+    const prov = PROVENANCE.includes(r.self_reported?.agent_provenance) ? r.self_reported.agent_provenance : 'unknown';
+    const ctype = CONTRIBUTION_TYPES.includes(r.self_reported?.contribution_type) ? r.self_reported.contribution_type : null;
+    // immutable GitHub fact core (digest domain = credential_type + credential_version)
+    const core = {
+        credential_type: CREDENTIAL_TYPE,
+        credential_version: CREDENTIAL_VERSION,
+        repository_id: repoId,
+        pr_node_id: prNodeId,
+        pr_number: r.pull_request.number,
+        base_ref: baseRef,
+        head_sha: headSha,
+        merge_commit_sha: mergeSha,
+        merged_at: mergedAt,
+        github_actor_id: actorId,
+        lifecycle_event: lifecycle,
+        supersedes_credential_id: null, // merged forces a null parent link
+    };
+    const coreDigest = digestCore(core);
+    const credentialId = credentialIdFromDigest(coreDigest);
+    const observation = {
+        observed_at: r.observed_at,
+        repository_owner: r.repository.owner.login,
+        repository_name: r.repository.name,
+        repository_visibility_at_observation: (['public', 'private', 'internal'].includes(r.repository.visibility) ? r.repository.visibility : 'unknown'), // missing ⇒ unknown, never guessed public
+        head_ref: s(r.pull_request.head.ref) ?? baseRef,
+        github_login: r.pull_request.user.login,
+        commit_authors: (r.commit_authors ?? []).map(a => ({ author_id: s(a.author_id), login: a.login ?? null, name: a.name ?? null, is_coauthor: a.is_coauthor === true })),
+        agent_provenance: prov,
+        claimed_task_id: r.self_reported?.task_id ?? null,
+        source_ref: r.self_reported?.source_ref ?? null,
+        contribution_type: ctype,
+        verification_state: 'verified',
+        evidence_scope: opts.evidence_scope ?? 'public_metadata',
+        checks_summary: summarizeChecks(r.check_conclusions),
+        reviews_summary: summarizeReviews(r.reviews),
+        dco_state: r.dco_state ?? 'unknown',
+        evidence_coverage: {
+            // default 'unobserved' — a pure verifier (no fetch) observed no evidence. The adapter
+            // (3B-1/3B-2) supplies real coverage. Zeros/unknown only mean something when coverage='observed'.
+            checks: r.evidence_coverage?.checks ?? 'unobserved',
+            reviews: r.evidence_coverage?.reviews ?? 'unobserved',
+            commit_authors: r.evidence_coverage?.commit_authors ?? 'unobserved',
+            dco: r.evidence_coverage?.dco ?? 'unobserved',
+        },
+        merged_by_actor_id: s(r.pull_request.merged_by?.id),
+        evidence_refs: [`pr:${repoId}#${r.pull_request.number}`, `merge_sha:${mergeSha}`],
+        known_limitations: [
+            'PR 3A is a PURE verifier over a caller-supplied response; it does NOT prove the response authentically came from GitHub. verification_state=verified = structural + repository-anchor verification only.',
+            'The self-consistency check is NOT tamper-proof: an attacker who controls the payload can recompute digests. Real authenticity needs an authenticated fetch / trusted signature (PR 3B).',
+            'credential_id + core_digest authenticate ONLY the immutable GitHub fact core, NOT this observation envelope.',
+            'GitHub identity is contribution attribution + a future-claim candidate, NOT a Passkey owner (RFC-017 I-7).',
+            'self-reported fields (claimed_task_id/source_ref/provenance/contribution_type) are NON-authoritative and excluded from core_digest.',
+            'commit_authors marked is_coauthor=true come from commit-message Co-authored-by trailers: COMMIT-DECLARED and IDENTITY-UNVERIFIED (no GitHub id) — must NOT be used for identity claim or reward.',
+        ],
+    };
+    const credential = {
+        credential_id: credentialId,
+        event_source: 'github_api',
+        accountable_party_ref: null,
+        core,
+        core_digest: coreDigest,
+        observation,
+        observation_digest: digestObject(observation),
+    };
+    // schema validation (structure + cross-field) ...
+    const check = GithubCredentialSchema.safeParse(credential);
+    if (!check.success) {
+        return { ok: false, outcome: 'insufficient_evidence', reasons: check.error.issues.map(i => `${i.path.join('.')}: ${i.message}`) };
+    }
+    // ... and self-consistency (digests match content) — NOT a tamper-proof guarantee (see PR 3B).
+    const consistency = verifyCredentialSelfConsistency(credential);
+    if (!consistency.ok) {
+        return { ok: false, outcome: 'insufficient_evidence', reasons: consistency.reasons };
+    }
+    return { ok: true, credential };
+}

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

@@ -0,0 +1,145 @@
+import { seamBackendKind, seamSqliteHandle } from '../../layer0-foundation/L0-1-database/db.js';
+import { fetchGithubContributionCredential } from './github-credential/github-fetch-adapter.js';
+import { GithubCredentialSchema } from './github-credential/github-credential.schema.js';
+import { verifyCredentialSelfConsistency } from './github-credential/self-consistency.js';
+import { canonicalSerialize, sha256hex } from './github-credential/canonical.js';
+const MAX_BUSY_RETRIES = 5;
+const BUSY_BACKOFF_MS = 25;
+function refused(reason, detail) {
+    return { ok: false, status: 'refused', reason, detail };
+}
+function isSqliteBusy(err) {
+    const code = err?.code;
+    return code === 'SQLITE_BUSY' || code === 'SQLITE_BUSY_SNAPSHOT';
+}
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+export async function ingestGithubContribution(request, deps) {
+    // 1) trusted mapping — expectedRepositoryId is NEVER caller-reported (design §2)
+    const mapKey = `${request.owner}/${request.repo}`;
+    const expectedRepositoryId = deps.repositoryMapping.get(mapKey);
+    if (expectedRepositoryId === undefined)
+        return refused('repository_not_allowed', mapKey);
+    // 2) backend fail-closed BEFORE any network — no synchronous transaction on PG yet (design §5)
+    const kind = seamBackendKind();
+    const db = seamSqliteHandle();
+    if (kind !== 'sqlite' || db === null)
+        return refused('backend_unsupported', `backend=${kind ?? 'uninitialized'}`);
+    // 3) re-fetch + mint inside the trusted path (adapter uses globalThis.fetch) — OUTSIDE the transaction
+    const fetched = await fetchGithubContributionCredential({
+        owner: request.owner,
+        repo: request.repo,
+        prNumber: request.prNumber,
+        expectedRepositoryId,
+        token: deps.token,
+        timeoutMs: deps.timeoutMs,
+    });
+    if (!fetched.ok)
+        return refused(fetched.outcome, fetched.reasons.join('; '));
+    const credential = fetched.credential;
+    // 4) re-validate the minted credential (the trusted path must be self-consistent) — outside the tx
+    if (!GithubCredentialSchema.safeParse(credential).success) {
+        return refused('invariant_violation', 'minted credential failed schema re-validation');
+    }
+    const sc = verifyCredentialSelfConsistency(credential);
+    if (!sc.ok)
+        return refused('invariant_violation', `self-consistency: ${sc.reasons.join('; ')}`);
+    // 5) derive identity keys. source_event_key is VERSION-INDEPENDENT (credential_id includes the
+    //    version; a v2 and a future v3 of the same merge are ONE fact) — design §3.
+    const core = credential.core;
+    const mergeCommitSha = core.merge_commit_sha;
+    const mergedAt = core.merged_at;
+    if (mergeCommitSha === null || mergedAt === null) {
+        return refused('invariant_violation', 'merged core missing merge_commit_sha/merged_at');
+    }
+    const sourceEventKey = `github:${core.repository_id}:${core.pr_node_id}:merged`;
+    const factId = `cfact_${sha256hex(sourceEventKey).slice(0, 40)}`;
+    const observationId = `gco_${sha256hex(`${credential.credential_id}:${credential.observation_digest}`).slice(0, 40)}`;
+    const executorRef = `github:${core.github_actor_id}`;
+    // 6) ONE synchronous transaction — all four lookups + decision + INSERTs + result (design §5).
+    //    No async seam inside; raw prepared statements only; .immediate() = write lock up front.
+    const txn = db.transaction(() => {
+        const coreRow = db.prepare('SELECT core_digest FROM github_contribution_credentials WHERE credential_id = ?')
+            .get(credential.credential_id);
+        const obsRow = db.prepare('SELECT id FROM github_credential_observations WHERE credential_id = ? AND observation_digest = ?')
+            .get(credential.credential_id, credential.observation_digest);
+        const factRow = db.prepare('SELECT fact_id FROM contribution_facts WHERE source_event_key = ?')
+            .get(sourceEventKey);
+        const linkRow = db.prepare('SELECT fact_id FROM github_fact_credentials WHERE credential_id = ?')
+            .get(credential.credential_id);
+        const coreExists = coreRow !== undefined;
+        const obsExists = obsRow !== undefined;
+        const factExists = factRow !== undefined;
+        const linkExists = linkRow !== undefined;
+        // Defensive consistency: stored rows must agree with the deterministic derivations; any drift is a
+        // corrupted invariant → fail-closed, never silently repair (design §4 catch-all).
+        if (coreExists && coreRow.core_digest !== credential.core_digest) {
+            return refused('invariant_violation', 'stored core_digest mismatch for credential_id');
+        }
+        if (factExists && factRow.fact_id !== factId) {
+            return refused('invariant_violation', 'existing fact_id mismatch for source_event_key');
+        }
+        if (linkExists && linkRow.fact_id !== factId) {
+            return refused('invariant_violation', 'existing link points to a different fact');
+        }
+        const insertCore = () => {
+            db.prepare(`INSERT INTO github_contribution_credentials
+        (credential_id, core_digest, credential_version, source_event_key, repository_id, pr_node_id,
+         pr_number, merge_commit_sha, merged_at, github_actor_id, lifecycle_event, core_json)
+        VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`).run(credential.credential_id, credential.core_digest, core.credential_version, sourceEventKey, core.repository_id, core.pr_node_id, core.pr_number, mergeCommitSha, mergedAt, core.github_actor_id, core.lifecycle_event, canonicalSerialize(core));
+        };
+        const insertObs = () => {
+            db.prepare(`INSERT INTO github_credential_observations
+        (id, credential_id, observation_digest, observation_json, observed_at) VALUES (?,?,?,?,?)`).run(observationId, credential.credential_id, credential.observation_digest, canonicalSerialize(credential.observation), credential.observation.observed_at);
+        };
+        const insertFact = () => {
+            db.prepare(`INSERT INTO contribution_facts
+        (fact_id, source_event_key, source, type, artifact_ref, occurred_at, executor_ref,
+         accountable_ref, provenance, status) VALUES (?,?,?,?,?,?,?,?,?,?)`).run(factId, sourceEventKey, 'github', null, mergeCommitSha, mergedAt, executorRef, null, 'unknown', 'active');
+        };
+        const insertLink = () => {
+            // source_event_key on the link + the composite FKs (Codex #297 P2-1) force the linked credential
+            // and fact to share THIS source event — a cross-event mislink is rejected by the DB.
+            db.prepare('INSERT INTO github_fact_credentials (fact_id, credential_id, source_event_key) VALUES (?,?,?)')
+                .run(factId, credential.credential_id, sourceEventKey);
+        };
+        const result = (status) => ({ ok: true, status, fact_id: factId, credential_id: credential.credential_id, source_event_key: sourceEventKey });
+        // Precise state machine — ONLY the four valid tuples write; anything else fail-closed (design §4).
+        if (!coreExists && !obsExists && !factExists && !linkExists) {
+            insertCore();
+            insertObs();
+            insertFact();
+            insertLink();
+            return result('ingested');
+        }
+        if (!coreExists && !obsExists && factExists && !linkExists) {
+            // v2→v3 of the SAME merge: new immutable core + observation, LINKED to the existing fact. No 2nd fact.
+            insertCore();
+            insertObs();
+            insertLink();
+            return result('credential_upgraded');
+        }
+        if (coreExists && !obsExists && factExists && linkExists) {
+            insertObs();
+            return result('re_observed');
+        }
+        if (coreExists && obsExists && factExists && linkExists) {
+            return result('already_present');
+        }
+        return refused('invariant_violation', `uncovered state core=${coreExists} obs=${obsExists} fact=${factExists} link=${linkExists}`);
+    });
+    // 7) bounded SQLITE_BUSY retry → typed db_busy; genuinely unexpected errors fail LOUD (never a fake success)
+    for (let attempt = 0;; attempt++) {
+        try {
+            return txn.immediate();
+        }
+        catch (err) {
+            if (isSqliteBusy(err) && attempt < MAX_BUSY_RETRIES) {
+                await sleep(BUSY_BACKOFF_MS * (attempt + 1));
+                continue;
+            }
+            if (isSqliteBusy(err))
+                return refused('db_busy', `busy after ${MAX_BUSY_RETRIES} retries`);
+            throw err;
+        }
+    }
+}

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

@@ -0,0 +1,115 @@
+// child-first order (safe for DROP under foreign_keys=ON).
+const CONTRIB_TABLES = ['github_fact_credentials', 'github_credential_observations', 'contribution_facts', 'github_contribution_credentials'];
+const CREATE_CREDENTIALS = `
+  CREATE TABLE IF NOT EXISTS github_contribution_credentials (
+    credential_id        TEXT PRIMARY KEY,
+    core_digest          TEXT NOT NULL UNIQUE,
+    credential_version   TEXT NOT NULL,
+    source_event_key     TEXT NOT NULL,
+    repository_id        TEXT NOT NULL,
+    pr_node_id           TEXT NOT NULL,
+    pr_number            INTEGER NOT NULL,
+    merge_commit_sha     TEXT NOT NULL,
+    merged_at            TEXT NOT NULL,
+    github_actor_id      TEXT NOT NULL,
+    lifecycle_event      TEXT NOT NULL CHECK (lifecycle_event = 'merged'),
+    core_json            TEXT NOT NULL,
+    created_at           TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE (credential_id, source_event_key)
+  )
+`;
+const CREATE_OBSERVATIONS = `
+  CREATE TABLE IF NOT EXISTS github_credential_observations (
+    id                   TEXT PRIMARY KEY,
+    credential_id        TEXT NOT NULL REFERENCES github_contribution_credentials(credential_id),
+    observation_digest   TEXT NOT NULL,
+    observation_json     TEXT NOT NULL,
+    observed_at          TEXT NOT NULL,
+    created_at           TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE (credential_id, observation_digest)
+  )
+`;
+const CREATE_FACTS = `
+  CREATE TABLE IF NOT EXISTS contribution_facts (
+    fact_id              TEXT PRIMARY KEY,
+    source_event_key     TEXT NOT NULL UNIQUE,
+    source               TEXT NOT NULL CHECK (source IN ('github','in_protocol','governance','transaction')),
+    type                 TEXT CHECK (type IS NULL OR type IN ('code','tests','audit','maintenance','governance','usage','transaction','referral')),
+    artifact_ref         TEXT NOT NULL,
+    occurred_at          TEXT,
+    executor_ref         TEXT NOT NULL,
+    accountable_ref      TEXT,
+    provenance           TEXT NOT NULL DEFAULT 'unknown' CHECK (provenance IN ('human','ai_assisted','ai_authored','unknown')),
+    status               TEXT NOT NULL CHECK (status IN ('active','superseded','reverted','void','forfeited')),
+    immutable            INTEGER NOT NULL DEFAULT 1 CHECK (immutable = 1),
+    created_at           TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE (fact_id, source_event_key)
+  )
+`;
+const CREATE_LINK = `
+  CREATE TABLE IF NOT EXISTS github_fact_credentials (
+    fact_id              TEXT NOT NULL,
+    credential_id        TEXT NOT NULL,
+    source_event_key     TEXT NOT NULL,
+    created_at           TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (fact_id, credential_id),
+    UNIQUE (credential_id),
+    FOREIGN KEY (credential_id, source_event_key) REFERENCES github_contribution_credentials(credential_id, source_event_key),
+    FOREIGN KEY (fact_id, source_event_key) REFERENCES contribution_facts(fact_id, source_event_key)
+  )
+`;
+const CREATE_INDEX = `CREATE INDEX IF NOT EXISTS idx_ghc_source_event_key ON github_contribution_credentials(source_event_key)`;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function tableExists(db, name) {
+    return db.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name=?`).get(name) !== undefined;
+}
+function hasColumn(db, table, col) {
+    return db.prepare(`SELECT 1 FROM pragma_table_info('${table}') WHERE name=?`).get(col) !== undefined;
+}
+function hasUniqueOnCols(db, table, cols) {
+    const idxs = db.prepare(`SELECT * FROM pragma_index_list('${table}')`).all();
+    for (const idx of idxs) {
+        if (idx.unique !== 1)
+            continue;
+        const onCols = db.prepare(`SELECT name FROM pragma_index_info('${idx.name}') ORDER BY seqno`).all().map(r => r.name);
+        if (onCols.length === cols.length && onCols.every((c, i) => c === cols[i]))
+            return true;
+    }
+    return false;
+}
+function linkHasCompositeFk(db) {
+    const fks = db.prepare(`SELECT * FROM pragma_foreign_key_list('github_fact_credentials')`).all();
+    return fks.some(r => r.from === 'source_event_key');
+}
+/** Full-structure check (not just link existence): all 4 tables + the P2-1 composite UNIQUE/FK. */
+function isCurrentShape(db) {
+    return CONTRIB_TABLES.every(t => tableExists(db, t))
+        && hasColumn(db, 'github_fact_credentials', 'source_event_key')
+        && hasUniqueOnCols(db, 'github_contribution_credentials', ['credential_id', 'source_event_key'])
+        && hasUniqueOnCols(db, 'contribution_facts', ['fact_id', 'source_event_key'])
+        && linkHasCompositeFk(db);
+}
+export function initGithubCredentialStoreSchema(db) {
+    // One synchronous .immediate() transaction wraps detect + empty-check + DROP + rebuild, so the
+    // schema is never left half-migrated: any error (incl. mid-rebuild) rolls the whole step back.
+    const apply = db.transaction(() => {
+        const present = CONTRIB_TABLES.filter(t => tableExists(db, t));
+        if (present.length > 0 && !isCurrentShape(db)) {
+            // Old / partial / half-migrated shape. SQLite can't ALTER-ADD the composite UNIQUE/FK, so we
+            // recreate — but ONLY if every present contribution table is empty (fail loud otherwise; never
+            // drop data). This also auto-repairs a half-migrated state (e.g. link dropped, parents left).
+            const total = present.reduce((n, t) => n + db.prepare(`SELECT COUNT(*) AS c FROM ${t}`).get().c, 0);
+            if (total !== 0)
+                throw new Error('github credential store is old/partial shape but NOT empty — manual migration required (refusing to drop data)');
+            for (const t of CONTRIB_TABLES)
+                db.exec(`DROP TABLE IF EXISTS ${t}`);
+        }
+        // fresh / post-drop rebuild / idempotent no-op (IF NOT EXISTS) when already current.
+        db.exec(CREATE_CREDENTIALS);
+        db.exec(CREATE_OBSERVATIONS);
+        db.exec(CREATE_FACTS);
+        db.exec(CREATE_LINK);
+        db.exec(CREATE_INDEX);
+    });
+    apply.immediate();
+}

package/dist/layer2-business/L2-9-contribution/identity-binding-engine.js

@@ -0,0 +1,134 @@
+/**
+ * PR 4a — GitHub identity → WebAZ account binding engine + accountable read-overlay.
+ *
+ * Records an identity binding (append-only event log + a current-state projection) and resolves a
+ * contribution fact's CURRENT accountable party at read time. Design + threat model:
+ * docs/IDENTITY-CLAIM-DESIGN.md. Schema: identity-binding-store.ts.
+ *
+ * Trust boundary (4a vs 4b): this engine takes an **already-verified `githubActorId`** as trusted
+ * input — proving control of that GitHub identity (publication challenge) and the human Passkey gate
+ * are 4b's job (the same schema/trigger split as 3B-3a/3B-3b). The engine itself is internal: it
+ * exposes NO agent/MCP/API surface.
+ *
+ * Atomicity: one synchronous better-sqlite3 `db.transaction(...).immediate()` (BEGIN IMMEDIATE takes
+ * the write lock before the lookup → no double-bind race); the active projection's PK is the second
+ * line. Non-sqlite backend → fail-closed (`backend_unsupported`). SQLITE_BUSY → bounded retry → typed
+ * `db_busy`; genuinely unexpected errors are re-thrown loud.
+ *
+ * Append-only: the EVENT LOG (`identity_binding_events`) is INSERT-only (immutable). The current-state
+ * projection (`identity_bindings_active`) is mutable BY DESIGN (bound→INSERT, revoked→DELETE) — it is a
+ * cache rebuildable from the log, never the audit truth.
+ */
+import { dbOne, seamBackendKind, seamSqliteHandle } from '../../layer0-foundation/L0-1-database/db.js';
+import { sha256hex } from './github-credential/canonical.js';
+const MAX_BUSY_RETRIES = 5;
+const BUSY_BACKOFF_MS = 25;
+const isSqliteBusy = (e) => {
+    const c = e?.code;
+    return c === 'SQLITE_BUSY' || c === 'SQLITE_BUSY_SNAPSHOT';
+};
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+export const accountableRef = (accountId) => `webaz:${accountId}`;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// Runs `body` in one synchronous .immediate() transaction; maps the two infra refusals
+// (non-sqlite backend / SQLITE_BUSY exhaustion) into the caller's own result type T.
+async function runTx(buildRefused, body) {
+    const kind = seamBackendKind();
+    const db = seamSqliteHandle();
+    if (kind !== 'sqlite' || db === null)
+        return buildRefused('backend_unsupported', `backend=${kind ?? 'uninitialized'}`);
+    const txn = db.transaction(body(db));
+    for (let attempt = 0;; attempt++) {
+        try {
+            return txn.immediate();
+        }
+        catch (err) {
+            if (isSqliteBusy(err) && attempt < MAX_BUSY_RETRIES) {
+                await sleep(BUSY_BACKOFF_MS * (attempt + 1));
+                continue;
+            }
+            if (isSqliteBusy(err))
+                return buildRefused('db_busy', `busy after ${MAX_BUSY_RETRIES} retries`);
+            throw err;
+        }
+    }
+}
+/**
+ * Synchronous bind core — the bind state machine WITHOUT its own transaction or backend check, so it
+ * can run INSIDE a caller-supplied `db.transaction` (e.g. the PR-F2 claim engine consuming a challenge
+ * + binding in ONE tx, avoiding the nested-transaction conflict). `bindGithubIdentity` wraps this in its
+ * own `.immediate()` tx; behavior is identical (proven by the existing identity-binding tests + a
+ * dedicated equivalence test). `db` is a better-sqlite3 handle already inside a transaction.
+ */
+export function bindGithubIdentityCore(db, input) {
+    const { githubActorId, accountId, proofMethod, proofRef = null } = input;
+    const visibility = input.visibility ?? 'private';
+    if (!githubActorId || !accountId) {
+        return { ok: false, status: 'refused', reason: 'invalid_input', detail: 'githubActorId and accountId are required' };
+    }
+    const refused = (reason, detail) => ({ ok: false, status: 'refused', reason, detail });
+    const active = db.prepare('SELECT account_id FROM identity_bindings_active WHERE github_actor_id = ?')
+        .get(githubActorId);
+    if (active) {
+        if (active.account_id === accountId) {
+            return { ok: true, status: 'already_bound', github_actor_id: githubActorId, account_id: accountId, event_id: '' };
+        }
+        return refused('already_bound_to_other', 'github id is actively bound to a different account — revoke first');
+    }
+    const eventId = `ibe_${sha256hex(`bound:${githubActorId}:${accountId}:${Date.now()}:${Math.random()}`).slice(0, 40)}`;
+    const boundAt = new Date().toISOString();
+    db.prepare(`INSERT INTO identity_binding_events
+    (event_id, event_type, github_actor_id, account_id, visibility, proof_method, proof_ref, supersedes_event_id)
+    VALUES (?, 'bound', ?, ?, ?, ?, ?, NULL)`).run(eventId, githubActorId, accountId, visibility, proofMethod, proofRef);
+    db.prepare(`INSERT INTO identity_bindings_active
+    (github_actor_id, account_id, visibility, bound_event_id, bound_at) VALUES (?, ?, ?, ?, ?)`)
+        .run(githubActorId, accountId, visibility, eventId, boundAt);
+    return { ok: true, status: 'bound', github_actor_id: githubActorId, account_id: accountId, event_id: eventId };
+}
+export async function bindGithubIdentity(input) {
+    // Input validation BEFORE runTx (so bad input → invalid_input regardless of backend) — unchanged.
+    if (!input.githubActorId || !input.accountId) {
+        return { ok: false, status: 'refused', reason: 'invalid_input', detail: 'githubActorId and accountId are required' };
+    }
+    return runTx((reason, detail) => ({ ok: false, status: 'refused', reason, detail }), (db) => () => bindGithubIdentityCore(db, input));
+}
+export async function revokeGithubIdentityBinding(input) {
+    const { githubActorId, accountId, proofMethod, proofRef = null } = input;
+    if (!githubActorId || !accountId) {
+        return { ok: false, status: 'refused', reason: 'invalid_input', detail: 'githubActorId and accountId are required' };
+    }
+    const refused = (reason, detail) => ({ ok: false, status: 'refused', reason, detail });
+    return runTx((reason, detail) => refused(reason, detail), (db) => () => {
+        const active = db.prepare('SELECT account_id, visibility, bound_event_id FROM identity_bindings_active WHERE github_actor_id = ?')
+            .get(githubActorId);
+        if (!active)
+            return refused('not_bound', 'no active binding for this github id');
+        // Only the current account may self-revoke; admin_manual lets governance override (audited).
+        if (proofMethod !== 'admin_manual' && active.account_id !== accountId) {
+            return refused('not_owner', 'only the currently-bound account may revoke (or use admin_manual)');
+        }
+        const eventId = `ibe_${sha256hex(`revoked:${githubActorId}:${active.account_id}:${Date.now()}:${Math.random()}`).slice(0, 40)}`;
+        db.prepare(`INSERT INTO identity_binding_events
+        (event_id, event_type, github_actor_id, account_id, visibility, proof_method, proof_ref, supersedes_event_id)
+        VALUES (?, 'revoked', ?, ?, ?, ?, ?, ?)`)
+            .run(eventId, githubActorId, active.account_id, active.visibility, proofMethod, proofRef, active.bound_event_id);
+        db.prepare('DELETE FROM identity_bindings_active WHERE github_actor_id = ?').run(githubActorId);
+        return { ok: true, status: 'revoked', github_actor_id: githubActorId, account_id: active.account_id, event_id: eventId };
+    });
+}
+/**
+ * Read-overlay: the CURRENT accountable party for a contribution fact's `executor_ref`.
+ * Only `github:<id>` executors are bindable in v1; anything else (or no active binding) → null.
+ * Uses the async seam (a plain read, no transaction) so it composes with the rest of the read path.
+ */
+export async function resolveAccountable(executorRef) {
+    if (!executorRef.startsWith('github:'))
+        return null;
+    const githubActorId = executorRef.slice('github:'.length);
+    if (!githubActorId)
+        return null;
+    const row = await dbOne('SELECT account_id, visibility, bound_at, bound_event_id FROM identity_bindings_active WHERE github_actor_id = ?', [githubActorId]);
+    if (!row)
+        return null;
+    return { accountable_ref: accountableRef(row.account_id), account_id: row.account_id, visibility: row.visibility, bound_at: row.bound_at, bound_event_id: row.bound_event_id };
+}