productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/firstMoveTensions.js

@@ -0,0 +1,93 @@
+import { gitRunOrNull } from "./gitRun.js";
+const IGNORED_TOP = new Set(["node_modules", "dist", "build", "out", "vendor", "coverage", ".git", "docs", ".github", "examples", "specs"]);
+const TEST_RE = /(^|\/)(tests?|__tests__|spec|specs|e2e)(\/|$)|\.(test|spec)\.[a-z]+$|_test\.[a-z]+$/i;
+const SOURCE_RE = /\.(ts|tsx|js|jsx|py|go|rb|rs|java|kt|swift|php|cs|scala|c|cc|cpp|h|hpp|m|mm)$/i;
+function git(root, args) {
+    return gitRunOrNull(args, { cwd: root, stdio: ["ignore", "pipe", "ignore"] });
+}
+// A generic top-level container (src/, lib/, app/) isn't a meaningful "area" —
+// everything's under it. Descend one level so the tension names the real room
+// (src/payments) rather than the whole house (src).
+const CONTAINER = new Set(["src", "lib", "app", "pkg", "packages", "internal", "cmd", "source", "sources", "components", "modules"]);
+function topDir(file) {
+    const parts = file.split("/");
+    if (parts.length < 2)
+        return null; // a root-level file has no owning dir
+    if (CONTAINER.has(parts[0]) && parts.length >= 3)
+        return `${parts[0]}/${parts[1]}`;
+    return parts[0];
+}
+// Churn × test-gap: the area you change most, held against whether anything
+// tests it. Two facts the repo holds; the tension is that the busiest code is
+// the least-covered. Universal (git only), cheap, low false-positive.
+function churnVsTests(root) {
+    // Last 100 non-merge commits — robust for low-velocity repos where a date
+    // window would be nearly empty.
+    const raw = git(root, ["log", "-n", "100", "--no-merges", "--name-only", "--format=%x00%H"]);
+    if (raw === null)
+        return null;
+    const commits = raw.split("\0").filter((c) => c.trim() !== "");
+    const M = commits.length;
+    if (M < 12)
+        return null; // too little history to claim a pattern (anti-slop floor)
+    const commitsTouchingDir = new Map();
+    for (const block of commits) {
+        const files = block.split(/\r?\n/).slice(1).filter(Boolean);
+        const dirs = new Set();
+        for (const f of files) {
+            if (!SOURCE_RE.test(f) || TEST_RE.test(f))
+                continue;
+            const d = topDir(f);
+            if (d && !IGNORED_TOP.has(d))
+                dirs.add(d);
+        }
+        for (const d of dirs)
+            commitsTouchingDir.set(d, (commitsTouchingDir.get(d) ?? 0) + 1);
+    }
+    if (commitsTouchingDir.size === 0)
+        return null;
+    const [busiest, count] = [...commitsTouchingDir.entries()].sort((a, b) => b[1] - a[1])[0];
+    // Must be genuinely dominant, not just "an area that got touched".
+    if (count < 5 || count < M * 0.2)
+        return null;
+    // Does any test reference the busiest dir? A test file under it, or one whose
+    // path names it. (Path heuristic — never a coverage claim, just evidence.)
+    const tracked = (git(root, ["ls-files"]) ?? "").split(/\r?\n/).filter(Boolean);
+    const testFiles = tracked.filter((f) => TEST_RE.test(f));
+    // The area may be "src/payments"; a test that covers it is one UNDER it, or one
+    // whose path/name references the leaf ("payments") — match the leaf, not the path.
+    const leaf = busiest.split("/").pop() ?? busiest;
+    const covered = testFiles.some((t) => t.startsWith(`${busiest}/`) || t.toLowerCase().includes(leaf.toLowerCase()));
+    if (covered)
+        return null; // the busiest area IS tested — no tension here
+    const noTestsAnywhere = testFiles.length === 0;
+    return {
+        id: "churn-vs-tests",
+        factA: `You've changed ${busiest}/ in ${count} of your last ${M} commits — it's the busiest room in the house.`,
+        factB: noTestsAnywhere ? `There isn't a test anywhere in the project.` : `Nothing in your test suite references ${busiest}/.`,
+        ask: `Which of those two are you not comfortable with?`,
+        title: `A safety net for ${busiest}/ — the code you change most, with no test under it`,
+        evidence: [`${busiest}/ touched in ${count}/${M} recent commits`, noTestsAnywhere ? "no test files found in the repo" : `${testFiles.length} test file(s), none referencing ${busiest}/`],
+        confidence: count >= M * 0.35 ? "high" : "medium",
+    };
+}
+// Ordered by grounding strength. First non-null wins as the headline tension;
+// the rest stay available as "also saw" (future). Only add detectors that are
+// cheap, grounded, and low-false-positive — a wrong first-run insight is worse
+// than a boring one.
+const DETECTORS = [churnVsTests];
+export function detectTensions(root) {
+    const found = [];
+    for (const detect of DETECTORS) {
+        try {
+            const t = detect(root);
+            if (t)
+                found.push(t);
+        }
+        catch {
+            // a detector that throws must never break the first read — skip it.
+        }
+    }
+    // High-confidence first; a tension foo isn't sure of never leads.
+    return found.sort((a, b) => (a.confidence === b.confidence ? 0 : a.confidence === "high" ? -1 : 1));
+}

package/dist-public/src/gitRun.d.ts

@@ -0,0 +1,21 @@
+type GitStdio = Array<"ignore" | "pipe" | "inherit">;
+export type GitRunOptions = {
+    cwd?: string;
+    maxBuffer?: number;
+    stdio?: GitStdio;
+    timeout?: number;
+    env?: NodeJS.ProcessEnv;
+};
+export type GitRunResult = {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    message: string;
+};
+export declare function gitRun(args: string[], opts?: GitRunOptions): GitRunResult;
+export declare function gitRunOrNull(args: string[], opts?: GitRunOptions): string | null;
+export declare function gitRunBuffer(args: string[], opts?: GitRunOptions): {
+    ok: boolean;
+    stdout: Buffer;
+};
+export {};

package/dist-public/src/gitRun.js

@@ -0,0 +1,50 @@
+// One shared wrapper for productfoo's git invocations. It reports outcome; the caller
+// owns what a failure means — some sites fail open (null/[] and continue),
+// others fail closed. Implemented over execFileSync so each site's existing
+// stdio/maxBuffer/stderr-echo semantics survive: execFileSync's default echoes
+// the child's stderr to the parent process, and a site that historically
+// silenced git must keep doing so by passing `stdio` explicitly.
+import { execFileSync } from "node:child_process";
+// Only forward options a caller actually set, so execFileSync's defaults
+// (cwd = process.cwd(), maxBuffer = 1 MiB, stderr echoed to the parent) hold
+// exactly where they held before.
+function execOptions(opts) {
+    return {
+        ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        ...(opts.maxBuffer !== undefined ? { maxBuffer: opts.maxBuffer } : {}),
+        ...(opts.stdio !== undefined ? { stdio: opts.stdio } : {}),
+        ...(opts.timeout !== undefined ? { timeout: opts.timeout } : {}),
+        ...(opts.env !== undefined ? { env: opts.env } : {}),
+    };
+}
+export function gitRun(args, opts = {}) {
+    try {
+        const stdout = execFileSync("git", args, { encoding: "utf8", ...execOptions(opts) });
+        return { ok: true, stdout: stdout ?? "", stderr: "", message: "" };
+    }
+    catch (error) {
+        const failure = error;
+        return {
+            ok: false,
+            stdout: typeof failure.stdout === "string" ? failure.stdout : "",
+            stderr: typeof failure.stderr === "string" ? failure.stderr : "",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+// Convenience for the common fail-open sites: stdout on success, null on any
+// git failure (including git not being installed).
+export function gitRunOrNull(args, opts = {}) {
+    const result = gitRun(args, opts);
+    return result.ok ? result.stdout : null;
+}
+// Raw-bytes variant for reading blobs (e.g. staged file content) where the
+// binary guard must inspect real bytes, not a utf8 re-encoding.
+export function gitRunBuffer(args, opts = {}) {
+    try {
+        return { ok: true, stdout: execFileSync("git", args, execOptions(opts)) };
+    }
+    catch {
+        return { ok: false, stdout: Buffer.alloc(0) };
+    }
+}

package/dist-public/src/githubReconcile.d.ts

@@ -0,0 +1,94 @@
+import { type GithubFixture, type SourceId } from "./sourceIngress.js";
+export type GithubCheck = {
+    name?: string;
+    conclusion?: string;
+};
+export type GithubEvidence = {
+    merged?: boolean;
+    state?: string;
+    checks?: GithubCheck[];
+    commits?: Array<{
+        message?: string;
+        files?: string[];
+    }>;
+    files_changed?: string[];
+};
+export type CriterionCheck = {
+    kind: "pr_merged";
+} | {
+    kind: "checks_pass";
+} | {
+    kind: "path_changed";
+    path: string;
+};
+export type DoneWhenCriterion = {
+    id: string;
+    text?: string;
+    check?: CriterionCheck;
+};
+export type NotVerifiedReason = "no-linkage" | "signal-absent" | "out-of-reach";
+export type CriterionStatus = "corroborated" | "contradicted" | "unresolvable";
+export type Verdict = "satisfied" | "drifted" | "not-verified";
+export type CriterionVerdict = {
+    criterion_id: string;
+    status: CriterionStatus;
+    reason?: NotVerifiedReason;
+    basis: string;
+    teach?: string;
+};
+export declare function verifyCriterion(criterion: DoneWhenCriterion, ev: GithubEvidence, linked: boolean): CriterionVerdict;
+export type ReconcileResult = {
+    verdict: Verdict;
+    criteria: CriterionVerdict[];
+    counts: {
+        corroborated: number;
+        contradicted: number;
+        unresolvable: number;
+    };
+    observed_at?: string;
+};
+export declare function aggregateVerdict(criteria: CriterionVerdict[]): Verdict;
+export declare function reconcileDoneWhen(opts: {
+    criteria: DoneWhenCriterion[];
+    evidence: GithubEvidence;
+    linked: boolean;
+    observedAt?: string;
+}): ReconcileResult;
+export declare const DEFAULT_VERDICT_MAX_AGE_SECONDS = 86400;
+export declare function isStale(observedAt: string, now: string, maxAgeSeconds?: number): boolean;
+export declare function recordGithubConflicts(packetDir: string, sourceId: SourceId, result: ReconcileResult, at: string): number;
+export type GithubReceipt = {
+    schema_version: "0.1";
+    packet: string;
+    source_id: SourceId;
+    verdict: Verdict;
+    observed_at?: string;
+    counts: ReconcileResult["counts"];
+    criteria: Array<{
+        criterion_id: string;
+        verdict: Verdict;
+        reason?: NotVerifiedReason;
+        basis: string;
+    }>;
+};
+export declare function evidenceFromFixture(fixture: GithubFixture): GithubEvidence;
+export type PrProof = {
+    evidence: GithubEvidence;
+    result: ReconcileResult;
+    receipt: GithubReceipt;
+    linked: boolean;
+};
+export declare function reconcilePrProof(opts: {
+    packet: string;
+    sourceId: SourceId;
+    fixture: GithubFixture;
+    specId: string;
+    criteria: DoneWhenCriterion[];
+    observedAt?: string;
+}): PrProof;
+export declare function buildGithubReceipt(opts: {
+    packet: string;
+    sourceId: SourceId;
+    result: ReconcileResult;
+}): GithubReceipt;
+export declare function renderGithubReceipt(receipt: GithubReceipt): string;

package/dist-public/src/githubReconcile.js

@@ -0,0 +1,205 @@
+// GitHub done_when verdict engine (github-integration-v0 T-003/T-004). Reconciles
+// a packet's done_when criteria against the typed GitHub facts of an approved PR
+// into a fail-closed tri-state verdict. Pure + offline: the runtime/CLI supplies
+// the evidence, this module decides. It consumes sourceIngress for the source
+// identity and the payload-free conflict-event shape; it re-implements no
+// substrate behavior (R-005). This is the PROOF axis (criterion ↔ evidence) —
+// orthogonal to and composing with packetReconcile's COVERAGE axis (changed-file
+// ↔ task); the two are named as one drift model with two axes, never merged
+// (D-011). `no-linkage` here is the proof-axis analog of the coverage axis's
+// `unmapped`.
+import { appendSourceConflictEvent, githubLinkageForSpec } from "./sourceIngress.js";
+// null = no diff information at all (signal-absent); [] = diff known but empty.
+function changedFiles(ev) {
+    const hasInfo = ev.files_changed !== undefined || (ev.commits ?? []).some((c) => c.files !== undefined);
+    if (!hasInfo)
+        return null;
+    return [...(ev.files_changed ?? []), ...(ev.commits ?? []).flatMap((c) => c.files ?? [])];
+}
+// Errors that teach (R-006): each not-verified reason names the concept, the fix,
+// and the next command — the Rust-compiler bar, not a bare assertion.
+const teachFor = {
+    "no-linkage": (c) => `not-verified (no-linkage): no PR/commit is bound to ${c.id} → add a Foo-Spec trailer to the implementing commit (or pass --source github:<pr-url>), then re-run foo asp reconcile`,
+    "signal-absent": (c) => `not-verified (signal-absent): ${c.id} needs a GitHub signal that is not present yet (e.g. no required checks, or the PR is still open) → re-run once the signal exists`,
+    "out-of-reach": (c) => `not-verified (out-of-reach): ${c.id} asserts something read-only GitHub signal cannot confirm → verify by test/review, or declare a check predicate (pr_merged | checks_pass | path_changed)`,
+};
+// Verify ONE criterion against the typed evidence (R-006). Corroboration is read
+// only from typed fields; free text never corroborates. Precedence inside a
+// criterion is fail-closed: an explicit contradiction beats a missing signal.
+export function verifyCriterion(criterion, ev, linked) {
+    const nv = (reason, basis) => ({
+        criterion_id: criterion.id,
+        status: "unresolvable",
+        reason,
+        basis,
+        teach: teachFor[reason](criterion),
+    });
+    // (1) no-linkage: nothing binds this PR to the criterion's packet (D-009).
+    if (!linked)
+        return nv("no-linkage", "no PR/commit is bound to this criterion's task via the Foo-Spec trailer");
+    // (3) out-of-reach: no typed predicate, so GitHub signal cannot speak to it.
+    const check = criterion.check;
+    if (!check)
+        return nv("out-of-reach", "no GitHub-checkable predicate; the criterion is outside read-only GitHub signal");
+    if (check.kind === "pr_merged") {
+        if (ev.merged === true)
+            return { criterion_id: criterion.id, status: "corroborated", basis: "PR is merged" };
+        if (ev.merged === false)
+            return { criterion_id: criterion.id, status: "contradicted", basis: `PR is not merged (state: ${ev.state ?? "open"})` };
+        return nv("signal-absent", "PR merge state is not present in the evidence");
+    }
+    if (check.kind === "checks_pass") {
+        const checks = ev.checks ?? [];
+        if (checks.length === 0)
+            return nv("signal-absent", "no required checks are present");
+        const failed = checks.find((c) => c.conclusion === "failure");
+        if (failed)
+            return { criterion_id: criterion.id, status: "contradicted", basis: `a required check = failure` };
+        if (checks.every((c) => c.conclusion === "success")) {
+            return { criterion_id: criterion.id, status: "corroborated", basis: `${checks.length}/${checks.length} required checks green` };
+        }
+        // pending/neutral/unknown conclusions present and none failed: cannot confirm green.
+        return nv("signal-absent", "not all required checks have a success conclusion yet");
+    }
+    // path_changed
+    const files = changedFiles(ev);
+    if (files === null)
+        return nv("signal-absent", "no diff/file information is present in the evidence");
+    const hit = files.some((f) => f === check.path || f.startsWith(check.path) || f.includes(check.path));
+    return hit
+        ? { criterion_id: criterion.id, status: "corroborated", basis: `a commit changed ${check.path}` }
+        : { criterion_id: criterion.id, status: "contradicted", basis: `no commit changed ${check.path}` };
+}
+// Aggregate per-criterion statuses into the fail-closed verdict (R-005): any
+// contradicted → drifted; else any unresolvable → not-verified; else satisfied.
+// `satisfied` therefore requires positive corroboration on EVERY criterion —
+// silence is never a pass. An empty criteria set is not-verified, not satisfied.
+export function aggregateVerdict(criteria) {
+    if (criteria.length === 0)
+        return "not-verified";
+    if (criteria.some((c) => c.status === "contradicted"))
+        return "drifted";
+    if (criteria.some((c) => c.status === "unresolvable"))
+        return "not-verified";
+    return "satisfied";
+}
+export function reconcileDoneWhen(opts) {
+    const criteria = opts.criteria.map((c) => verifyCriterion(c, opts.evidence, opts.linked));
+    return {
+        verdict: aggregateVerdict(criteria),
+        criteria,
+        counts: {
+            corroborated: criteria.filter((c) => c.status === "corroborated").length,
+            contradicted: criteria.filter((c) => c.status === "contradicted").length,
+            unresolvable: criteria.filter((c) => c.status === "unresolvable").length,
+        },
+        observed_at: opts.observedAt,
+    };
+}
+// Freshness (R-005 / OQ-2 carried default): a typed-fact verdict is stamped with
+// observed_at and goes stale past the window, so a re-run is prompted rather than
+// a cached `satisfied` trusted. Fail-closed: an unparseable timestamp is stale.
+export const DEFAULT_VERDICT_MAX_AGE_SECONDS = 86400;
+export function isStale(observedAt, now, maxAgeSeconds = DEFAULT_VERDICT_MAX_AGE_SECONDS) {
+    const obs = Date.parse(observedAt);
+    const cur = Date.parse(now);
+    if (Number.isNaN(obs) || Number.isNaN(cur))
+        return true;
+    return (cur - obs) / 1000 > maxAgeSeconds;
+}
+// Record a payload-free conflict event for each contradicted criterion (C-006),
+// reusing the substrate writer. Returns the number of conflicts recorded. The
+// event carries only criterion ids/status — no raw GitHub payload (B1).
+export function recordGithubConflicts(packetDir, sourceId, result, at) {
+    const contradicted = result.criteria.filter((c) => c.status === "contradicted");
+    if (contradicted.length === 0)
+        return 0;
+    appendSourceConflictEvent(packetDir, {
+        source_id: sourceId,
+        conflicts: contradicted.map((c) => ({ criterion_id: c.criterion_id, status: c.status })),
+        note: "GitHub evidence contradicts a done_when criterion; not promoted (github-integration-v0 R-004/R-005).",
+    }, at);
+    return contradicted.length;
+}
+// --- Dual-reader proof receipt (github-integration-v0 T-006/R-008) ----------
+// The per-criterion status maps to the criterion-level verdict vocabulary.
+const CRITERION_VERDICT = {
+    corroborated: "satisfied",
+    contradicted: "drifted",
+    unresolvable: "not-verified",
+};
+// --- Shared PR-reconcile engine (reconcile-anywhere-v0 T-001) ----------------
+// The PROOF-axis core both entry points share (D-001): `asp reconcile --source
+// github:` (packet path — criteria from tasks.yaml) and the top-level packet-free
+// `foo reconcile`. Free text still never corroborates; only typed fields feed the
+// verdict. Keeping this one function is the anti-drift mitigation the D-001
+// dissent named: two entry points, one engine.
+// Lift the typed GithubEvidence out of an offline fixture (or a runtime-supplied
+// PR payload of the same shape). Only typed fields cross; bodies/titles stay out.
+export function evidenceFromFixture(fixture) {
+    return {
+        merged: fixture.merged,
+        state: fixture.state,
+        checks: fixture.checks,
+        commits: fixture.commits,
+        files_changed: fixture.files_changed,
+    };
+}
+// Given a PR fixture + a packet's done_when criteria, produce the typed-fact
+// verdict and dual-reader receipt. `asp reconcile` delegates here (behavior
+// preserved); the packet-free command reuses `evidenceFromFixture` and this same
+// verdict once a packet has been adopted.
+export function reconcilePrProof(opts) {
+    const evidence = evidenceFromFixture(opts.fixture);
+    const linked = githubLinkageForSpec({
+        specId: opts.specId,
+        commitMessages: (opts.fixture.commits ?? []).map((c) => c.message ?? ""),
+        branch: opts.fixture.branch,
+        prBody: opts.fixture.body,
+    }).linked;
+    const result = reconcileDoneWhen({ criteria: opts.criteria, evidence, linked, observedAt: opts.observedAt });
+    const receipt = buildGithubReceipt({ packet: opts.packet, sourceId: opts.sourceId, result });
+    return { evidence, result, receipt, linked };
+}
+export function buildGithubReceipt(opts) {
+    return {
+        schema_version: "0.1",
+        packet: opts.packet,
+        source_id: opts.sourceId,
+        verdict: opts.result.verdict,
+        observed_at: opts.result.observed_at,
+        counts: opts.result.counts,
+        criteria: opts.result.criteria.map((c) => ({
+            criterion_id: c.criterion_id,
+            verdict: CRITERION_VERDICT[c.status],
+            reason: c.reason,
+            basis: c.basis,
+        })),
+    };
+}
+// Render the receipt as a copy-pasteable PR comment the DEVELOPER posts (foo posts
+// nothing, R-008/R-007). Dual-reader: human-scannable markdown lines PLUS a
+// machine block in an HTML comment (invisible in rendered markdown) so an agent
+// re-reading the PR reconstructs the verdict without re-running. Payload-free.
+export function renderGithubReceipt(receipt) {
+    const lines = receipt.criteria.map((c) => `- ${c.criterion_id}: ${c.verdict}${c.reason ? ` (${c.reason})` : ""} — ${c.basis}`);
+    const machine = JSON.stringify({
+        foo_verdict: {
+            schema_version: receipt.schema_version,
+            packet: receipt.packet,
+            source_id: receipt.source_id,
+            verdict: receipt.verdict,
+            observed_at: receipt.observed_at,
+            criteria: receipt.criteria.map((c) => ({ criterion_id: c.criterion_id, verdict: c.verdict, reason: c.reason })),
+        },
+    });
+    return [
+        `**foo proof receipt** — \`${receipt.packet}\` · verdict: **${receipt.verdict}**`,
+        `source: ${receipt.source_id.provider}:${receipt.source_id.connection_id} (${receipt.source_id.external_id ?? "repo"}) · ${receipt.counts.corroborated} satisfied / ${receipt.counts.contradicted} drifted / ${receipt.counts.unresolvable} not-verified`,
+        "",
+        ...(lines.length ? lines : ["- (no criteria evaluated)"]),
+        "",
+        `<!-- foo:verdict ${machine} -->`,
+        "",
+    ].join("\n");
+}

package/dist-public/src/gmailNango.d.ts

@@ -0,0 +1,131 @@
+export type FetchLike = typeof globalThis.fetch;
+export type GmailRuntimeErrorCode = "not_connected" | "auth_expired" | "access_denied" | "provider_failure" | "network" | "provider_timeout" | "thread_too_large" | "budget_exhausted";
+export declare class GmailRuntimeError extends Error {
+    readonly code: GmailRuntimeErrorCode;
+    constructor(code: GmailRuntimeErrorCode, message: string);
+}
+export type GmailConnection = {
+    connection_ref: string;
+    broker: "nango";
+    credential: {
+        type: "oauth2";
+        access_token: string;
+    };
+    credential_type: "oauth2";
+    body_scope: "granted" | "missing" | "unknown";
+};
+export declare const GMAIL_POLICY: {
+    readonly policy_version: "gmail-local-worker-0.1";
+    readonly max_response_bytes: number;
+    readonly fetch_timeout_ms: 90000;
+    readonly max_model_input_tokens: 100000;
+    readonly max_list_pages: 5;
+    readonly min_request_interval_ms: 350;
+    readonly quiet_period_hours: 48;
+};
+export type GmailConnectionEnv = Record<string, string | undefined>;
+export declare function gmailConnectionConfigured(env: GmailConnectionEnv): boolean;
+export declare function gmailCredentialBroker(_env: GmailConnectionEnv): "nango" | null;
+/**
+ * Resolve the verified user's Gmail credential through Nango. There is no
+ * direct fallback (D-002): the mailbox belongs to one person, so the OAuth
+ * grant is always brokered, refreshable, and revocable centrally. productfoo receives
+ * the token for one command and never persists or prints it.
+ */
+export declare function resolveGmailConnection(input: {
+    env: GmailConnectionEnv;
+    fetchImpl: FetchLike;
+}): Promise<GmailConnection>;
+export type GmailThreadRef = {
+    id: string;
+    snippet?: string;
+};
+export type GmailMessageHeader = {
+    name?: string;
+    value?: string;
+};
+export type GmailThreadMessage = {
+    id: string;
+    internal_date?: string;
+    labels?: string[];
+    from?: {
+        display_name?: string;
+        email?: string;
+    };
+    to?: Array<{
+        display_name?: string;
+        email?: string;
+    }>;
+    subject?: string;
+    body_text?: string;
+};
+export type GmailThread = {
+    id: string;
+    messages: GmailThreadMessage[];
+};
+type GmailClientOptions = {
+    fetchImpl: FetchLike;
+    baseUrl?: string;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    fetchTimeoutMs?: number;
+};
+/**
+ * Minimal read-only Gmail REST client. Only documented read operations are
+ * reachable — every request method is GET and anything else routes through
+ * the single write-refusal choke point (R-009), so the refusal is testable
+ * rather than scattered. There is no attachment fetch method at all (D-003).
+ */
+export declare class GmailClient {
+    private readonly credential;
+    private readonly options;
+    readonly requests: {
+        profile: number;
+        list: number;
+        metadata: number;
+        thread: number;
+    };
+    private lastRequestAt;
+    private readonly baseUrl;
+    private readonly fetchTimeoutMs;
+    private readonly sleep;
+    private readonly now;
+    constructor(credential: {
+        type: "oauth2";
+        access_token: string;
+    }, options: GmailClientOptions);
+    private request;
+    /** The mailbox owner's address (metadata only) — defines "internal" for a per-user mailbox (R-004). */
+    profile(): Promise<{
+        email?: string;
+    }>;
+    /**
+     * Bounded metadata listing (R-004): explicit labels, a time window expressed
+     * as Gmail's after/before query operators, a page ceiling, no message
+     * bodies. A listing that exceeds the ceiling returns `truncated` and the
+     * run stops — it never widens.
+     */
+    listThreads(scope: {
+        label_ids: string[];
+        from: string;
+        to: string;
+    }): Promise<{
+        threads: GmailThreadRef[];
+        pages: number;
+        truncated: boolean;
+    }>;
+    /**
+     * One thread's headers only (format=metadata) — the bounded listing read
+     * (R-004): participants and dates without any message body. Bodies are
+     * fetched solely by `thread()` under the minted proof (R-007).
+     */
+    threadMetadata(threadId: string): Promise<GmailThread>;
+    /**
+     * Exactly one thread's messages (R-007). This method refuses to ask for
+     * more than one identifier — a fixture observes that no request ever
+     * carries one. Attachment parts are skipped, never fetched (D-003).
+     */
+    thread(threadId: string): Promise<GmailThread>;
+    private parseMessage;
+}
+export {};