@poa-box/core 0.1.0

package/dist/reads/user.d.ts

@@ -0,0 +1,229 @@
+/**
+ * User & account reads — typed wrappers over graph/documents/user.
+ *
+ * Serves the read paths of `pop user whoami` (src/commands/user/whoami.ts),
+ * `pop user profile` (src/commands/user/profile.ts), and the pre-write reads
+ * of `pop user join` / `pop user claim-hats` / `pop user update-profile`.
+ *
+ * Usernames and profile metadata are HOME-CHAIN account-registry state
+ * (that's where `pop user register` writes and `pop user profile` reads), so
+ * the account-scoped helpers default to HOME_CHAIN_ID rather than the
+ * client's default chain. An explicit chainId always wins.
+ *
+ * A null row from any of these means NOT-INDEXED, not nonexistent — the CLI
+ * keeps live RPC fallbacks (getUsername, balanceOf, Hats.balanceOf) for every
+ * decision where that difference matters, and `isAccountAuthoritative`
+ * (re-exported below) is the guard that says when an indexed account may
+ * stand in for a live registry read.
+ */
+import type { GraphClient } from '../graph/client';
+import { IndexedAccount, IndexedQuickJoin } from '../graph/documents/user';
+export { isAccountAuthoritative } from '../graph/documents/user';
+export type { IndexedAccount, IndexedQuickJoin } from '../graph/documents/user';
+/** Row shape of GET_ACCOUNT_BY_USERNAME. `id` is the lowercased address. */
+export interface AccountByUsername {
+    id: string;
+    user: string;
+    username: string;
+}
+/**
+ * Username → address resolution (GET_ACCOUNT_BY_USERNAME). Returns null when
+ * no account is indexed under that exact username (usernames are unique on
+ * the registry, so first-of-one is the whole answer).
+ */
+export declare function getAccountByUsername(client: GraphClient, username: string, chainId?: number): Promise<AccountByUsername | null>;
+/** Account + profile metadata served by FETCH_USERNAME. */
+export interface AccountProfile {
+    id: string;
+    username: string;
+    profileMetadataHash: string | null;
+    metadata: {
+        id: string;
+        bio: string | null;
+        avatar: string | null;
+        github: string | null;
+        twitter: string | null;
+        website: string | null;
+    } | null;
+}
+/**
+ * One address's username + profile metadata — the home-chain read behind
+ * `pop user profile` (src/commands/user/profile.ts). Null means no indexed
+ * account (never registered, or indexer lag after a fresh registration).
+ */
+export declare function getAccountProfile(client: GraphClient, address: string, chainId?: number): Promise<AccountProfile | null>;
+/**
+ * Standalone username lookup (username + isDeleted + registry) — the no-org
+ * path of `pop user whoami` (src/commands/user/whoami.ts). Gate any use of
+ * the returned username with isAccountAuthoritative before trusting it in
+ * place of a live registry.getUsername read.
+ */
+export declare function getAccountUsername(client: GraphClient, address: string, chainId?: number): Promise<IndexedAccount | null>;
+/**
+ * The org QuickJoin's module pointers plus one caller's account, in one
+ * round-trip — the pre-write read of `pop user join`
+ * (src/commands/user/join.ts). The account may only stand in for a live
+ * getUsername read when
+ * `isAccountAuthoritative(account, quickJoinContract.accountRegistry)`; and
+ * the CLI ALWAYS re-reads the registry pointer live before writing, because
+ * QuickJoin.updateAddresses can re-point it (see the join command header for
+ * why trusting the indexed pointer is unrecoverable in both directions).
+ */
+export declare function getQuickJoinAccount(client: GraphClient, quickJoinAddress: string, accountAddress: string, chainId?: number): Promise<{
+    quickJoinContract: IndexedQuickJoin | null;
+    account: IndexedAccount | null;
+}>;
+/**
+ * Just the QuickJoin module pointers (accountRegistry / hatsContract /
+ * memberHatIds) — the address read of `pop user claim-hats`
+ * (src/commands/user/claim-hats.ts). The pointers are static deploy-time
+ * values, byte-verified against the live eth_calls on Gnosis and Arbitrum;
+ * the claim pre-flight probes themselves stay on-chain in the CLI.
+ */
+export declare function getQuickJoinModules(client: GraphClient, quickJoinAddress: string, chainId?: number): Promise<IndexedQuickJoin | null>;
+/** Account row served by FETCH_REGISTRY_AND_ACCOUNT (profile-merge shape). */
+export interface RegistryAccount {
+    id: string;
+    username: string;
+    isDeleted: boolean;
+    metadata: {
+        bio: string | null;
+        avatar: string | null;
+        github: string | null;
+        twitter: string | null;
+        website: string | null;
+    } | null;
+}
+/**
+ * The indexed account registry plus one account's username and profile
+ * metadata, in one round-trip — everything `pop user update-profile`
+ * (src/commands/user/update-profile.ts) reads before it writes.
+ * `registryAddress === null` means the registry is not indexed on this chain
+ * (subgraph syncing) — the CLI treats that as EXIT.INFRA.
+ */
+export declare function getRegistryAndAccount(client: GraphClient, address: string, chainId?: number): Promise<{
+    registryAddress: string | null;
+    account: RegistryAccount | null;
+}>;
+/** Org-scoped user entity served by the FETCH_USER_DATA tier family. */
+export interface OrgUser {
+    id: string;
+    address: string;
+    participationTokenBalance: string | null;
+    membershipStatus: string | null;
+    currentHatIds: string[] | null;
+    joinMethod: string | null;
+    totalTasksCompleted: string | null;
+    totalVotes: string | null;
+    totalModulesCompleted: string | null;
+    firstSeenAt: string | null;
+    lastActiveAt: string | null;
+    assignedTasks: Array<{
+        id: string;
+        taskId: string;
+        title: string | null;
+        payout: string | null;
+        status: string;
+    }>;
+    completedTasks: Array<{
+        id: string;
+        taskId: string;
+        title: string | null;
+        payout: string | null;
+    }>;
+    hybridProposalsCreated: Array<{
+        id: string;
+        proposalId: string;
+        title: string | null;
+        status: string | null;
+        startTimestamp: string | null;
+        endTimestamp: string | null;
+    }>;
+    modulesCompleted: Array<{
+        moduleId: string;
+        completedAt: string | null;
+    }>;
+    /** v7 claim-churn counters — ONLY when hasChurnCounters (tier 0, Gnosis today). */
+    totalTasksReleased?: string;
+    totalTasksLostToExpiry?: string;
+}
+export interface OrgUserProfile {
+    /** Org-scoped User entity, or null when the address never touched the org. */
+    user: OrgUser | null;
+    /** Same-chain account row (username), or null. */
+    account: {
+        id: string;
+        username: string;
+    } | null;
+    /**
+     * True when tier 0 (FETCH_USER_DATA_WITH_CHURN) served the answer. Callers
+     * must gate any use of totalTasksReleased/totalTasksLostToExpiry on this —
+     * `0` ("indexed, never churned") must stay distinguishable from absent
+     * ("not indexed on this chain").
+     */
+    hasChurnCounters: boolean;
+}
+/**
+ * Org membership stats for one address — the org-scoped read of
+ * `pop user profile` (src/commands/user/profile.ts). The subgraph User id is
+ * `<orgHexId>-<address>`, so an org NAME resolves to the hex id first
+ * (a name used directly would silently match nothing). Tier 0 carries the v7
+ * claim-churn counters (Gnosis only today); tier 1 is the same document
+ * without them.
+ */
+export declare function getOrgUserProfile(client: GraphClient, orgIdOrName: string, address: string, chainId?: number): Promise<OrgUserProfile>;
+/** Full whoami snapshot — the one-round-trip payload of FETCH_WHOAMI_ORG_DATA. */
+export interface WhoamiOrgData {
+    organization: {
+        id: string;
+        name: string | null;
+        roles: Array<{
+            hatId: string;
+            name: string | null;
+            hat: {
+                active: boolean;
+            } | null;
+        }>;
+    } | null;
+    quickJoinContract: IndexedQuickJoin | null;
+    account: IndexedAccount | null;
+    tokenBalance: {
+        id: string;
+        balance: string;
+    } | null;
+    user: {
+        id: string;
+        membershipStatus: string | null;
+        participationTokenBalance: string | null;
+        currentHatIds: string[] | null;
+    } | null;
+    /** Pending requests by this user — the CLI reports `tokenRequests.length`. */
+    tokenRequests: Array<{
+        id: string;
+    }>;
+}
+/**
+ * One-round-trip org snapshot for `pop user whoami`
+ * (src/commands/user/whoami.ts): org name + role hats (with the Hats toggle
+ * flag), QuickJoin pointers, the caller's account/PT balance/org-user row,
+ * and their pending token requests. Variables are composed exactly as the
+ * CLI does — AddressZero placeholders keep the document valid when a module
+ * is missing (those selections then simply return null).
+ *
+ * Interpretation stays with the caller (the CLI keeps RPC fallbacks for
+ * username/PT/membership): gate `account.username` with
+ * isAccountAuthoritative(account, quickJoinContract?.accountRegistry), AND
+ * membership derived from currentHatIds with the role's `hat.active` flag —
+ * a toggled-off hat still appears in currentHatIds because Hats does not
+ * burn the token.
+ */
+export declare function getWhoamiOrgData(client: GraphClient, params: {
+    /** Org hex ID (as returned by resolveOrgId / OrgModules.orgId). */
+    orgId: string;
+    /** ParticipationToken address, or null/undefined when the org has none. */
+    participationTokenAddress?: string | null;
+    /** QuickJoin address, or null/undefined when the org has none. */
+    quickJoinAddress?: string | null;
+    /** The identity being inspected. */
+    address: string;
+}, chainId?: number): Promise<WhoamiOrgData | null>;

package/dist/reads/user.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * User & account reads — typed wrappers over graph/documents/user.
+ *
+ * Serves the read paths of `pop user whoami` (src/commands/user/whoami.ts),
+ * `pop user profile` (src/commands/user/profile.ts), and the pre-write reads
+ * of `pop user join` / `pop user claim-hats` / `pop user update-profile`.
+ *
+ * Usernames and profile metadata are HOME-CHAIN account-registry state
+ * (that's where `pop user register` writes and `pop user profile` reads), so
+ * the account-scoped helpers default to HOME_CHAIN_ID rather than the
+ * client's default chain. An explicit chainId always wins.
+ *
+ * A null row from any of these means NOT-INDEXED, not nonexistent — the CLI
+ * keeps live RPC fallbacks (getUsername, balanceOf, Hats.balanceOf) for every
+ * decision where that difference matters, and `isAccountAuthoritative`
+ * (re-exported below) is the guard that says when an indexed account may
+ * stand in for a live registry read.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAccountAuthoritative = void 0;
+exports.getAccountByUsername = getAccountByUsername;
+exports.getAccountProfile = getAccountProfile;
+exports.getAccountUsername = getAccountUsername;
+exports.getQuickJoinAccount = getQuickJoinAccount;
+exports.getQuickJoinModules = getQuickJoinModules;
+exports.getRegistryAndAccount = getRegistryAndAccount;
+exports.getOrgUserProfile = getOrgUserProfile;
+exports.getWhoamiOrgData = getWhoamiOrgData;
+const ethers_1 = require("ethers");
+const user_1 = require("../graph/documents/user");
+const chains_1 = require("../chains");
+const resolve_1 = require("./resolve");
+// Pure selection helpers live in the documents module — re-exported here so
+// read-layer consumers get the guard next to the reads it guards.
+var user_2 = require("../graph/documents/user");
+Object.defineProperty(exports, "isAccountAuthoritative", { enumerable: true, get: function () { return user_2.isAccountAuthoritative; } });
+/**
+ * Username → address resolution (GET_ACCOUNT_BY_USERNAME). Returns null when
+ * no account is indexed under that exact username (usernames are unique on
+ * the registry, so first-of-one is the whole answer).
+ */
+async function getAccountByUsername(client, username, chainId = chains_1.HOME_CHAIN_ID) {
+    const result = await client.query(user_1.GET_ACCOUNT_BY_USERNAME, { username }, chainId);
+    return result.accounts?.[0] ?? null;
+}
+/**
+ * One address's username + profile metadata — the home-chain read behind
+ * `pop user profile` (src/commands/user/profile.ts). Null means no indexed
+ * account (never registered, or indexer lag after a fresh registration).
+ */
+async function getAccountProfile(client, address, chainId = chains_1.HOME_CHAIN_ID) {
+    const result = await client.query(user_1.FETCH_USERNAME, { id: address.toLowerCase() }, chainId);
+    return result.account ?? null;
+}
+/**
+ * Standalone username lookup (username + isDeleted + registry) — the no-org
+ * path of `pop user whoami` (src/commands/user/whoami.ts). Gate any use of
+ * the returned username with isAccountAuthoritative before trusting it in
+ * place of a live registry.getUsername read.
+ */
+async function getAccountUsername(client, address, chainId = chains_1.HOME_CHAIN_ID) {
+    const result = await client.query(user_1.FETCH_ACCOUNT_USERNAME, { accountID: address.toLowerCase() }, chainId);
+    return result.account ?? null;
+}
+/**
+ * The org QuickJoin's module pointers plus one caller's account, in one
+ * round-trip — the pre-write read of `pop user join`
+ * (src/commands/user/join.ts). The account may only stand in for a live
+ * getUsername read when
+ * `isAccountAuthoritative(account, quickJoinContract.accountRegistry)`; and
+ * the CLI ALWAYS re-reads the registry pointer live before writing, because
+ * QuickJoin.updateAddresses can re-point it (see the join command header for
+ * why trusting the indexed pointer is unrecoverable in both directions).
+ */
+async function getQuickJoinAccount(client, quickJoinAddress, accountAddress, chainId) {
+    const result = await client.query(user_1.FETCH_QUICKJOIN_ACCOUNT, { quickJoinAddress: quickJoinAddress.toLowerCase(), accountID: accountAddress.toLowerCase() }, chainId);
+    return {
+        quickJoinContract: result?.quickJoinContract ?? null,
+        account: result?.account ?? null,
+    };
+}
+/**
+ * Just the QuickJoin module pointers (accountRegistry / hatsContract /
+ * memberHatIds) — the address read of `pop user claim-hats`
+ * (src/commands/user/claim-hats.ts). The pointers are static deploy-time
+ * values, byte-verified against the live eth_calls on Gnosis and Arbitrum;
+ * the claim pre-flight probes themselves stay on-chain in the CLI.
+ */
+async function getQuickJoinModules(client, quickJoinAddress, chainId) {
+    const result = await client.query(user_1.FETCH_QUICKJOIN_MODULES, { quickJoinAddress: quickJoinAddress.toLowerCase() }, chainId);
+    return result?.quickJoinContract ?? null;
+}
+/**
+ * The indexed account registry plus one account's username and profile
+ * metadata, in one round-trip — everything `pop user update-profile`
+ * (src/commands/user/update-profile.ts) reads before it writes.
+ * `registryAddress === null` means the registry is not indexed on this chain
+ * (subgraph syncing) — the CLI treats that as EXIT.INFRA.
+ */
+async function getRegistryAndAccount(client, address, chainId = chains_1.HOME_CHAIN_ID) {
+    const result = await client.query(user_1.FETCH_REGISTRY_AND_ACCOUNT, { accountID: address.toLowerCase() }, chainId);
+    return {
+        registryAddress: result?.universalAccountRegistries?.[0]?.id ?? null,
+        account: result?.account ?? null,
+    };
+}
+/**
+ * Org membership stats for one address — the org-scoped read of
+ * `pop user profile` (src/commands/user/profile.ts). The subgraph User id is
+ * `<orgHexId>-<address>`, so an org NAME resolves to the hex id first
+ * (a name used directly would silently match nothing). Tier 0 carries the v7
+ * claim-churn counters (Gnosis only today); tier 1 is the same document
+ * without them.
+ */
+async function getOrgUserProfile(client, orgIdOrName, address, chainId) {
+    const orgId = await (0, resolve_1.resolveOrgId)(client, orgIdOrName, chainId);
+    const orgUserID = `${orgId.toLowerCase()}-${address.toLowerCase()}`;
+    const { data, tierIndex } = await client.queryWithFieldFallback((0, user_1.userDataTiers)(orgUserID, address.toLowerCase()), { chainId });
+    return {
+        user: data.user ?? null,
+        account: data.account ?? null,
+        hasChurnCounters: tierIndex === 0,
+    };
+}
+/**
+ * One-round-trip org snapshot for `pop user whoami`
+ * (src/commands/user/whoami.ts): org name + role hats (with the Hats toggle
+ * flag), QuickJoin pointers, the caller's account/PT balance/org-user row,
+ * and their pending token requests. Variables are composed exactly as the
+ * CLI does — AddressZero placeholders keep the document valid when a module
+ * is missing (those selections then simply return null).
+ *
+ * Interpretation stays with the caller (the CLI keeps RPC fallbacks for
+ * username/PT/membership): gate `account.username` with
+ * isAccountAuthoritative(account, quickJoinContract?.accountRegistry), AND
+ * membership derived from currentHatIds with the role's `hat.active` flag —
+ * a toggled-off hat still appears in currentHatIds because Hats does not
+ * burn the token.
+ */
+async function getWhoamiOrgData(client, params, chainId) {
+    const address = params.address.toLowerCase();
+    const tokenAddress = params.participationTokenAddress || ethers_1.ethers.constants.AddressZero;
+    const quickJoinAddress = (params.quickJoinAddress || ethers_1.ethers.constants.AddressZero).toLowerCase();
+    const result = await client.query(user_1.FETCH_WHOAMI_ORG_DATA, {
+        orgId: params.orgId,
+        orgUserID: `${params.orgId}-${address}`,
+        tokenAddress,
+        userAddress: address,
+        quickJoinAddress,
+        accountID: address,
+        tokenBalanceID: `${tokenAddress.toLowerCase()}-${address}`,
+    }, chainId);
+    return result ?? null;
+}

package/dist/reads/vote.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Vote/governance reads — typed wrappers over the voting graph documents for
+ * the entities the CLI's `pop vote list / results / execute / classes show`
+ * commands read, plus the pure selection helpers those commands share
+ * (fuzzy --proposal resolution, announce-all candidate selection, the
+ * execute state gate, results tallying, class-snapshot normalization).
+ *
+ * Raw subgraph entity shapes only — scalars arrive as strings.
+ */
+import type { GraphClient } from '../graph/client';
+import { SubgraphVotingClass } from '../graph/documents/voting-classes';
+/** One ballot as indexed by the subgraph (FETCH_VOTING_DATA field set). */
+export interface SubgraphProposalVote {
+    voter: string;
+    voterUsername?: string | null;
+    optionIndexes: string[];
+    optionWeights: string[];
+    classRawPowers?: string[] | null;
+    votedAt?: string | null;
+}
+/**
+ * One proposal row (hybrid `proposals` or DD `ddvProposals`). Fields absent on
+ * the legacy (pre-#195) tier — proposer/proposerUsername/creatorUsername/
+ * classesVersion — arrive as undefined when that tier served the request.
+ */
+export interface SubgraphProposal {
+    id?: string;
+    proposalId: string;
+    title?: string | null;
+    descriptionHash?: string;
+    metadata?: {
+        id?: string;
+        description?: string | null;
+        optionNames?: string[] | null;
+    } | null;
+    numOptions?: string | number;
+    startTimestamp?: string;
+    endTimestamp?: string | null;
+    status: string;
+    winningOption?: string | null;
+    isValid?: boolean | null;
+    wasExecuted?: boolean | null;
+    executionFailed?: boolean | null;
+    executionError?: string | null;
+    isHatRestricted?: boolean | null;
+    restrictedHatIds?: string[] | null;
+    proposer?: string | null;
+    proposerUsername?: string | null;
+    creatorUsername?: string | null;
+    classesVersion?: string | null;
+    votes?: SubgraphProposalVote[];
+}
+export interface SubgraphHybridVoting {
+    id: string;
+    thresholdPct?: string | number | null;
+    quorum?: string | number | null;
+    classVersion?: string | null;
+    votingClasses?: SubgraphVotingClass[];
+    proposals?: SubgraphProposal[];
+}
+export interface SubgraphDirectDemocracyVoting {
+    id: string;
+    thresholdPct?: string | number | null;
+    quorum?: string | number | null;
+    ddvProposals?: SubgraphProposal[];
+}
+/** Organization root of FETCH_VOTING_DATA — null means the org is not indexed. */
+export interface VotingOrgData {
+    id: string;
+    hybridVoting?: SubgraphHybridVoting | null;
+    directDemocracyVoting?: SubgraphDirectDemocracyVoting | null;
+}
+/**
+ * Port of the `pop vote list` / `pop vote announce-all` data fetch
+ * (src/commands/vote/list.ts, src/commands/vote/announce-all.ts):
+ * FETCH_VOTING_DATA with the pre-#195 legacy tier as fallback.
+ *
+ * A GraphQL document validates as a whole, so one unknown field fails the
+ * entire query — the legacy tier keeps listing (and announcing) working
+ * against a pre-#195 subgraph deployment.
+ */
+export declare function fetchVotingData(client: GraphClient, orgIdOrName: string, chainId?: number): Promise<VotingOrgData | null>;
+export interface ProposalCandidate {
+    proposalId: string;
+    title: string;
+    status: string;
+    endTimestamp?: string;
+}
+/**
+ * Port of `fetchRecentProposals` (src/commands/vote/helpers.ts): recent
+ * proposal titles for ONE voting contract, addressed by contract address —
+ * works for both Hybrid and DD (whichever entity matches answers, the other
+ * root field returns null).
+ */
+export declare function fetchRecentProposals(client: GraphClient, contractAddr: string, chainId?: number, first?: number): Promise<ProposalCandidate[]>;
+/**
+ * Port of `resolveProposalId` (src/commands/vote/helpers.ts): resolve a
+ * user-supplied proposal argument to a numeric proposal ID.
+ *
+ * - Numeric input → returned as-is (no network round-trip).
+ * - Anything else → fuzzy title query against the voting contract's recent
+ *   proposals, scored with Jaccard bestMatches at threshold 0.5.
+ *     - exactly one match → resolved
+ *     - multiple matches  → CliError listing the candidates (the CLI's
+ *       non-TTY behavior; the interactive picker is CLI UX and not ported)
+ *     - zero matches      → CliError listing the 5 most recent titles
+ *
+ * opts.preferActive (used by `vote cast`): when several proposals match but
+ * exactly ONE is still Active, that one wins — you can only cast on an open
+ * proposal, so ended homonyms are not ambiguity.
+ */
+export declare function resolveProposalId(client: GraphClient, input: string, contractAddr: string, chainId?: number, opts?: {
+    preferActive?: boolean;
+}): Promise<number>;
+export interface AnnounceCandidate {
+    id: string;
+    type: 'hybrid' | 'dd';
+    title: string;
+    /** True when this is an H-05 retry of a failed execution. */
+    retry: boolean;
+}
+/**
+ * Pure port of the `pop vote announce-all` candidate filter
+ * (src/commands/vote/announce-all.ts): proposals ready to announce are
+ *   - status "Ended" (subgraph updated), OR
+ *   - status "Active" but endTimestamp has passed (subgraph hasn't updated)
+ * excluding already-announced ones — EXCEPT the H-05 retry case: a FAILED
+ * execution is not "done". Audit H-05 releases the in-flight `executed` lock
+ * in the catch branch, so the proposal is re-announceable — but it already
+ * has a winningOption (Winner is emitted regardless), so the plain
+ * already-announced test would skip it forever and silently.
+ *
+ * Callers should still per-proposal callStatic-probe announceWinner before
+ * broadcasting (the CLI skips would-revert candidates without burning gas).
+ *
+ * @param nowSeconds unix seconds "now" — pass chain time when available.
+ */
+export declare function selectAnnounceCandidates(org: VotingOrgData, nowSeconds: number): AnnounceCandidate[];
+/** Pre-broadcast finalization state machine row (pop vote execute). */
+export interface ProposalExecutionState {
+    proposalId: string;
+    status: string;
+    winningOption?: string | null;
+    wasExecuted?: boolean | null;
+    executionFailed?: boolean | null;
+    isValid?: boolean | null;
+    winnerAnnouncedAt?: string | null;
+}
+/** The `pop vote execute` state-gate document (src/commands/vote/execute.ts). */
+export declare const GET_PROPOSAL_EXECUTION_STATE = "\n  query GetProposal($votingId: String!, $proposalId: String!) {\n    proposals(where: { hybridVoting: $votingId, proposalId: $proposalId }, first: 1) {\n      proposalId\n      status\n      winningOption\n      wasExecuted\n      executionFailed\n      isValid\n      winnerAnnouncedAt\n    }\n  }\n";
+/**
+ * Port of the `pop vote execute` subgraph state gate: fetch the one proposal
+ * row the finalize decision is made from. Null row means the proposal is not
+ * indexed (the CLI treats that as not found).
+ */
+export declare function fetchProposalExecutionState(client: GraphClient, hybridVotingAddress: string, proposalId: number | string, chainId?: number): Promise<ProposalExecutionState | null>;
+export type ExecuteGateDecision = 
+/** wasExecuted — nothing to do (the CLI info-returns). */
+{
+    kind: 'already-executed';
+}
+/** Announced and execution did NOT fail — nothing to do. */
+ | {
+    kind: 'already-announced';
+    isValid?: boolean | null;
+}
+/** Still Active/etc. — the CLI throws PRECONDITION here. */
+ | {
+    kind: 'not-ended';
+    status: string;
+}
+/**
+ * Proceed to the callStatic probe + announceWinner. When
+ * retryingFailedExecution is true this is the H-05 retry path: the
+ * announce succeeded, the execution reverted, and re-running
+ * announceWinner is the intended fix (the callStatic probe arbitrates —
+ * a pre-#185 contract reverts AlreadyExecuted there).
+ */
+ | {
+    kind: 'ready';
+    retryingFailedExecution: boolean;
+};
+/**
+ * Pure port of the `pop vote execute` decision ladder over the subgraph row
+ * (same evaluation order as src/commands/vote/execute.ts). The caller maps
+ * 'not-ended' to the CLI's PRECONDITION error and the two "nothing to do"
+ * kinds to graceful no-ops.
+ */
+export declare function evaluateExecuteGate(proposal: ProposalExecutionState): ExecuteGateDecision;
+export interface ProposalResultsRankEntry {
+    rank: number;
+    option: number;
+    name: string;
+    score: number;
+}
+export interface ProposalResultsVoter {
+    voter: string;
+    allocations: Record<string, number>;
+}
+/** The `pop vote results --json` report shape (an output contract — do not reshape). */
+export interface ProposalResults {
+    proposalId: string;
+    title?: string | null;
+    status: string;
+    /** IDENTITY or null — deliberately never an address (see fetch doc comment). */
+    proposedBy: string | null;
+    proposerAddress: string | null;
+    classVersionAtCreation: string | null;
+    liveClassVersion: string | null;
+    classConfigDrifted: boolean;
+    winnerAnnouncedAt: number | null;
+    executedAt: number | null;
+    executedCallsCount: number | null;
+    actionSummaries: string[];
+    promotedFrom: string | null;
+    totalVoters: number;
+    supportThresholdPct?: number;
+    quorumVoterCount?: number;
+    ranking: ProposalResultsRankEntry[];
+    voters: ProposalResultsVoter[];
+    winner?: ProposalResultsRankEntry;
+}
+/**
+ * The `pop vote results` proposal document (src/commands/vote/results.ts).
+ * Two tiers: the #195 attribution/provenance fields, then the pre-#195 field
+ * set. A GraphQL document validates as a whole, so without the fallback an
+ * endpoint that predates #195 would lose the rankings and voter breakdown
+ * this read exists to serve. The legacy tier is spelled out rather than
+ * derived so a reformat cannot silently turn it into a copy of the modern one.
+ */
+export declare function buildProposalResultsQuery(orgId: string, proposalId: number, modern: boolean): string;
+/**
+ * Pure port of the `pop vote results` tally/ranking/attribution computation
+ * (src/commands/vote/results.ts) over the fetched hybridVoting row.
+ *
+ * Attribution: subgraph #195. proposer* are the current names; creator* the
+ * older aliases populated identically from transaction.from. proposedBy is an
+ * IDENTITY or null — never an address: most proposers are Executor or
+ * smart-account addresses with no username, and returning the address here
+ * would make `proposedBy === 'someone'` silently false for them while looking
+ * like a resolved name. The address is always available as proposerAddress.
+ */
+export declare function computeProposalResults(hybridVoting: {
+    thresholdPct?: string | number | null;
+    quorum?: string | number | null;
+    classVersion?: string | null;
+    proposals?: Array<SubgraphProposal & {
+        winnerAnnouncedAt?: string | null;
+        executedAt?: string | null;
+        executedCallsCount?: string | number | null;
+        metadata?: {
+            description?: string | null;
+            optionNames?: string[] | null;
+            actionSummaries?: string[] | null;
+            promotedFrom?: string | null;
+        } | null;
+    }>;
+}): ProposalResults | null;
+/**
+ * Port of `pop vote results` (src/commands/vote/results.ts): rankings +
+ * per-voter breakdown for one proposal. Throws the CLI's not-found error when
+ * the proposal is not indexed.
+ */
+export declare function fetchProposalResults(client: GraphClient, orgIdOrName: string, proposalId: number, chainId?: number): Promise<ProposalResults>;
+/** Normalized class row — identical shape from the subgraph and the contract. */
+export interface NormalizedClass {
+    classIndex: number;
+    strategy: string;
+    slicePct: number;
+    quadratic: boolean;
+    minBalance: string;
+    asset: string;
+    hatIds: string[];
+}
+export interface ClassConfigSnapshot {
+    classes: NormalizedClass[];
+    supportThresholdPct: number;
+    quorumVoterCount: number;
+}
+/**
+ * Subgraph rows → the exact shape the contract path produces. `asset` is
+ * checksummed because ethers returns a checksummed address and the subgraph
+ * returns lowercase Bytes; without this the `asset` value would change casing
+ * depending on which source answered.
+ */
+export declare function normalizeSubgraphClasses(rows: SubgraphVotingClass[]): NormalizedClass[];
+/**
+ * Port of `pop vote classes show`'s subgraph read
+ * (fetchClassConfigFromSubgraph, src/commands/vote/classes.ts): the class
+ * table + both validity parameters. Returns null whenever the subgraph cannot
+ * answer authoritatively (contract not indexed, no rows for the requested
+ * version, missing schema fields, network error) so the caller falls back to
+ * the contract (getClasses()/getProposalClasses()/thresholdPct()/quorum())
+ * instead of showing an empty table.
+ */
+export declare function fetchClassConfig(client: GraphClient, hybridVotingAddress: string, proposalId?: number, chainId?: number): Promise<ClassConfigSnapshot | null>;