@poa-box/core 0.1.0

package/dist/graph/documents/user.d.ts

@@ -0,0 +1,120 @@
+/**
+ * User & Account Queries
+ * Ported from frontend queries.js
+ */
+import type { FieldFallbackTier } from '../client';
+export declare const FETCH_USERNAME = "\n  query FetchUsernameNew($id: Bytes!) {\n    account(id: $id) {\n      id\n      username\n      profileMetadataHash\n      metadata {\n        id\n        bio\n        avatar\n        github\n        twitter\n        website\n      }\n    }\n  }\n";
+export declare const GET_ACCOUNT_BY_USERNAME = "\n  query GetAccountByUsername($username: String!) {\n    accounts(where: { username: $username }, first: 1) {\n      id\n      user\n      username\n    }\n  }\n";
+/**
+ * One-round-trip org snapshot for `pop user whoami`: org name + role-hat
+ * names, the org's QuickJoin module pointers, the caller's account
+ * (username + which registry it lives on), their ERC-20 participation-token
+ * balance, their org-user entity (membership, PT balance, hats worn), and
+ * their pending participation-token requests. The `status: Pending`
+ * filter is inlined (enum literal) to match FETCH_PENDING_TOKEN_REQUESTS
+ * in queries/token.ts.
+ *
+ * Every field here was verified NON-NULL against the live Gnosis
+ * (poa-gnosis-v-1) AND Arbitrum (poa-arb-v-1) deployments, and
+ * quickJoinContract.{accountRegistry,hatsContract,memberHatIds} were
+ * byte-compared against the matching eth_calls on both chains — including
+ * the empty-array memberHatIds case, which is genuinely empty on-chain and
+ * not an indexing gap.
+ *
+ * `account.registry` is carried so callers can prove the indexed account
+ * belongs to the SAME registry the org's QuickJoin consults before trusting
+ * the indexed username (a legacy org can point at a registry this subgraph
+ * does not index).
+ */
+export declare const FETCH_WHOAMI_ORG_DATA = "\n  query WhoamiOrgData(\n    $orgId: Bytes!\n    $orgUserID: String!\n    $tokenAddress: String!\n    $userAddress: Bytes!\n    $quickJoinAddress: ID!\n    $accountID: ID!\n    $tokenBalanceID: ID!\n  ) {\n    organization(id: $orgId) {\n      id\n      name\n      roles(where: { isUserRole: true }) {\n        hatId\n        name\n        # Hats Protocol's toggle flag. When it is false, Hats.isWearerOfHat returns\n        # false for EVERY wearer regardless of token balance, and the tokens are NOT\n        # burned \u2014 so User.currentHatIds still lists the hat. A membership answer\n        # derived from currentHatIds alone must AND it with this flag.\n        hat {\n          active\n        }\n      }\n    }\n    quickJoinContract(id: $quickJoinAddress) {\n      id\n      accountRegistry\n      hatsContract\n      memberHatIds\n    }\n    account(id: $accountID) {\n      id\n      username\n      isDeleted\n      registry {\n        id\n      }\n    }\n    tokenBalance(id: $tokenBalanceID) {\n      id\n      balance\n    }\n    user(id: $orgUserID) {\n      id\n      membershipStatus\n      participationTokenBalance\n      currentHatIds\n    }\n    tokenRequests(\n      where: { participationToken: $tokenAddress, requester: $userAddress, status: Pending }\n      first: 100\n    ) {\n      id\n    }\n  }\n";
+/**
+ * Standalone account lookup (no org): the username + registry for one
+ * address. Account.id is the LOWERCASED address. Used by `pop user whoami`
+ * when no org is configured — the username is home-chain account-registry
+ * state, so this runs against the home-chain subgraph instead of building a
+ * second JsonRpcProvider just to call getUsername.
+ */
+export declare const FETCH_ACCOUNT_USERNAME = "\n  query AccountUsername($accountID: ID!) {\n    account(id: $accountID) {\n      id\n      username\n      isDeleted\n      registry {\n        id\n      }\n    }\n  }\n";
+/**
+ * The org QuickJoin's module pointers plus the caller's account, in one
+ * round-trip. `pop user join` needs both: the registry QuickJoin consults
+ * (registering anywhere else leaves quickJoinWithUser reverting NoUsername)
+ * and whether a username already exists (1-tx vs 2-tx flow).
+ *
+ * The account is only trustworthy for that decision when
+ * `account.registry.id === quickJoinContract.accountRegistry` — see the
+ * guard in commands/user/join.ts.
+ */
+export declare const FETCH_QUICKJOIN_ACCOUNT = "\n  query QuickJoinAccount($quickJoinAddress: ID!, $accountID: ID!) {\n    quickJoinContract(id: $quickJoinAddress) {\n      id\n      accountRegistry\n      hatsContract\n      memberHatIds\n    }\n    account(id: $accountID) {\n      id\n      username\n      isDeleted\n      registry {\n        id\n      }\n    }\n  }\n";
+/**
+ * Just the QuickJoin module pointers — the addresses `pop user claim-hats`
+ * needs before running its (deliberately on-chain) pre-flight probes.
+ */
+export declare const FETCH_QUICKJOIN_MODULES = "\n  query QuickJoinModules($quickJoinAddress: ID!) {\n    quickJoinContract(id: $quickJoinAddress) {\n      id\n      accountRegistry\n      hatsContract\n      memberHatIds\n    }\n  }\n";
+/**
+ * The indexed account registry plus one account's username and profile
+ * metadata, in one round-trip — everything `pop user update-profile` needs
+ * before it writes. Replaces two separate subgraph queries plus a
+ * getUsername eth_call.
+ */
+export declare const FETCH_REGISTRY_AND_ACCOUNT = "\n  query RegistryAndAccount($accountID: ID!) {\n    universalAccountRegistries(first: 1) {\n      id\n    }\n    account(id: $accountID) {\n      id\n      username\n      isDeleted\n      metadata {\n        bio\n        avatar\n        github\n        twitter\n        website\n      }\n    }\n  }\n";
+/** Shape of the `account` selection shared by the queries above. */
+export interface IndexedAccount {
+    id: string;
+    username: string;
+    isDeleted: boolean;
+    registry?: {
+        id: string;
+    } | null;
+}
+/** Shape of the `quickJoinContract` selection shared by the queries above. */
+export interface IndexedQuickJoin {
+    id: string;
+    accountRegistry: string;
+    hatsContract: string;
+    memberHatIds: string[];
+}
+/**
+ * True when an indexed account can stand in for a live
+ * `registry.getUsername(addr)` read.
+ *
+ * Two ways it cannot:
+ *   - the account was deleted on-chain (the indexed username is a tombstone);
+ *   - it lives on a DIFFERENT registry than the one the caller is about to
+ *     transact against. Exactly one UniversalAccountRegistry is indexed per
+ *     deployment, but a legacy org's QuickJoin can point at another address
+ *     (verified: Gnosis org "Test5" points at 0x01a1…8513, which has no code
+ *     on Gnosis), and Account.id is the bare address — not registry-scoped —
+ *     so a username from the indexed registry would be the wrong answer.
+ *
+ * `expectedRegistry` omitted means "no registry constraint" (the caller is
+ * reading the subgraph's own registry).
+ */
+export declare function isAccountAuthoritative(account: IndexedAccount | null | undefined, expectedRegistry?: string | null): account is IndexedAccount;
+export declare const FETCH_USER_DATA = "\n  query FetchUserDataNew($orgUserID: String!, $userAddress: Bytes!) {\n    user(id: $orgUserID) {\n      id\n      address\n      participationTokenBalance\n      membershipStatus\n      currentHatIds\n      joinMethod\n      totalTasksCompleted\n      totalVotes\n      totalModulesCompleted\n      firstSeenAt\n      lastActiveAt\n      assignedTasks(first: 20) {\n        id\n        taskId\n        title\n        payout\n        status\n      }\n      completedTasks(first: 20) {\n        id\n        taskId\n        title\n        payout\n      }\n      hybridProposalsCreated(first: 20) {\n        id\n        proposalId\n        title\n        status\n        startTimestamp\n        endTimestamp\n      }\n      modulesCompleted(first: 20) {\n        moduleId\n        completedAt\n      }\n    }\n    account(id: $userAddress) {\n      id\n      username\n    }\n  }\n";
+/**
+ * FETCH_USER_DATA plus the per-user claim-churn counters (subgraph #201,
+ * TaskManager v7): how many claims this member released themselves, and how
+ * many were force-released out from under them after their claim expired.
+ *
+ * GNOSIS ONLY as of 2026-08-02. `totalTasksLostToExpiry` exists on BOTH
+ * deployments and only rides along here because a GraphQL document validates
+ * as a whole — there is no way to ask for it next to `totalTasksReleased`
+ * without the pair standing or falling together. Verified live that
+ * poa-arb-v-1 rejects this document with ``Type `User` has no field
+ * `totalTasksReleased``` (`isUnknownFieldError` matches /has no field/i, so
+ * the tier drops cleanly to FETCH_USER_DATA), while poa-gnosis-v-1 serves it.
+ *
+ * Both counters are zero on every live row on both chains today, so callers
+ * must gate rendering on the SERVED TIER: `0` ("indexed, never churned") has
+ * to stay distinguishable from absent ("not indexed here").
+ *
+ * Built by INSERTION so the two documents cannot drift apart, and so a
+ * reflow that broke the anchor would produce a visibly identical tier rather
+ * than a silently degraded one.
+ */
+export declare const FETCH_USER_DATA_WITH_CHURN: string;
+/** Tier order for `pop user profile`. Tier 1 is the untouched original. */
+export declare const USER_DATA_TIERS: string[];
+/** Build the tier array for `queryWithFieldFallback`. */
+export declare function userDataTiers(orgUserID: string, userAddress: string): FieldFallbackTier[];

package/dist/graph/documents/user.js

@@ -0,0 +1,302 @@
+"use strict";
+/**
+ * User & Account Queries
+ * Ported from frontend queries.js
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_DATA_TIERS = exports.FETCH_USER_DATA_WITH_CHURN = exports.FETCH_USER_DATA = exports.FETCH_REGISTRY_AND_ACCOUNT = exports.FETCH_QUICKJOIN_MODULES = exports.FETCH_QUICKJOIN_ACCOUNT = exports.FETCH_ACCOUNT_USERNAME = exports.FETCH_WHOAMI_ORG_DATA = exports.GET_ACCOUNT_BY_USERNAME = exports.FETCH_USERNAME = void 0;
+exports.isAccountAuthoritative = isAccountAuthoritative;
+exports.userDataTiers = userDataTiers;
+exports.FETCH_USERNAME = `
+  query FetchUsernameNew($id: Bytes!) {
+    account(id: $id) {
+      id
+      username
+      profileMetadataHash
+      metadata {
+        id
+        bio
+        avatar
+        github
+        twitter
+        website
+      }
+    }
+  }
+`;
+exports.GET_ACCOUNT_BY_USERNAME = `
+  query GetAccountByUsername($username: String!) {
+    accounts(where: { username: $username }, first: 1) {
+      id
+      user
+      username
+    }
+  }
+`;
+/**
+ * One-round-trip org snapshot for `pop user whoami`: org name + role-hat
+ * names, the org's QuickJoin module pointers, the caller's account
+ * (username + which registry it lives on), their ERC-20 participation-token
+ * balance, their org-user entity (membership, PT balance, hats worn), and
+ * their pending participation-token requests. The `status: Pending`
+ * filter is inlined (enum literal) to match FETCH_PENDING_TOKEN_REQUESTS
+ * in queries/token.ts.
+ *
+ * Every field here was verified NON-NULL against the live Gnosis
+ * (poa-gnosis-v-1) AND Arbitrum (poa-arb-v-1) deployments, and
+ * quickJoinContract.{accountRegistry,hatsContract,memberHatIds} were
+ * byte-compared against the matching eth_calls on both chains — including
+ * the empty-array memberHatIds case, which is genuinely empty on-chain and
+ * not an indexing gap.
+ *
+ * `account.registry` is carried so callers can prove the indexed account
+ * belongs to the SAME registry the org's QuickJoin consults before trusting
+ * the indexed username (a legacy org can point at a registry this subgraph
+ * does not index).
+ */
+exports.FETCH_WHOAMI_ORG_DATA = `
+  query WhoamiOrgData(
+    $orgId: Bytes!
+    $orgUserID: String!
+    $tokenAddress: String!
+    $userAddress: Bytes!
+    $quickJoinAddress: ID!
+    $accountID: ID!
+    $tokenBalanceID: ID!
+  ) {
+    organization(id: $orgId) {
+      id
+      name
+      roles(where: { isUserRole: true }) {
+        hatId
+        name
+        # Hats Protocol's toggle flag. When it is false, Hats.isWearerOfHat returns
+        # false for EVERY wearer regardless of token balance, and the tokens are NOT
+        # burned — so User.currentHatIds still lists the hat. A membership answer
+        # derived from currentHatIds alone must AND it with this flag.
+        hat {
+          active
+        }
+      }
+    }
+    quickJoinContract(id: $quickJoinAddress) {
+      id
+      accountRegistry
+      hatsContract
+      memberHatIds
+    }
+    account(id: $accountID) {
+      id
+      username
+      isDeleted
+      registry {
+        id
+      }
+    }
+    tokenBalance(id: $tokenBalanceID) {
+      id
+      balance
+    }
+    user(id: $orgUserID) {
+      id
+      membershipStatus
+      participationTokenBalance
+      currentHatIds
+    }
+    tokenRequests(
+      where: { participationToken: $tokenAddress, requester: $userAddress, status: Pending }
+      first: 100
+    ) {
+      id
+    }
+  }
+`;
+/**
+ * Standalone account lookup (no org): the username + registry for one
+ * address. Account.id is the LOWERCASED address. Used by `pop user whoami`
+ * when no org is configured — the username is home-chain account-registry
+ * state, so this runs against the home-chain subgraph instead of building a
+ * second JsonRpcProvider just to call getUsername.
+ */
+exports.FETCH_ACCOUNT_USERNAME = `
+  query AccountUsername($accountID: ID!) {
+    account(id: $accountID) {
+      id
+      username
+      isDeleted
+      registry {
+        id
+      }
+    }
+  }
+`;
+/**
+ * The org QuickJoin's module pointers plus the caller's account, in one
+ * round-trip. `pop user join` needs both: the registry QuickJoin consults
+ * (registering anywhere else leaves quickJoinWithUser reverting NoUsername)
+ * and whether a username already exists (1-tx vs 2-tx flow).
+ *
+ * The account is only trustworthy for that decision when
+ * `account.registry.id === quickJoinContract.accountRegistry` — see the
+ * guard in commands/user/join.ts.
+ */
+exports.FETCH_QUICKJOIN_ACCOUNT = `
+  query QuickJoinAccount($quickJoinAddress: ID!, $accountID: ID!) {
+    quickJoinContract(id: $quickJoinAddress) {
+      id
+      accountRegistry
+      hatsContract
+      memberHatIds
+    }
+    account(id: $accountID) {
+      id
+      username
+      isDeleted
+      registry {
+        id
+      }
+    }
+  }
+`;
+/**
+ * Just the QuickJoin module pointers — the addresses `pop user claim-hats`
+ * needs before running its (deliberately on-chain) pre-flight probes.
+ */
+exports.FETCH_QUICKJOIN_MODULES = `
+  query QuickJoinModules($quickJoinAddress: ID!) {
+    quickJoinContract(id: $quickJoinAddress) {
+      id
+      accountRegistry
+      hatsContract
+      memberHatIds
+    }
+  }
+`;
+/**
+ * The indexed account registry plus one account's username and profile
+ * metadata, in one round-trip — everything `pop user update-profile` needs
+ * before it writes. Replaces two separate subgraph queries plus a
+ * getUsername eth_call.
+ */
+exports.FETCH_REGISTRY_AND_ACCOUNT = `
+  query RegistryAndAccount($accountID: ID!) {
+    universalAccountRegistries(first: 1) {
+      id
+    }
+    account(id: $accountID) {
+      id
+      username
+      isDeleted
+      metadata {
+        bio
+        avatar
+        github
+        twitter
+        website
+      }
+    }
+  }
+`;
+/**
+ * True when an indexed account can stand in for a live
+ * `registry.getUsername(addr)` read.
+ *
+ * Two ways it cannot:
+ *   - the account was deleted on-chain (the indexed username is a tombstone);
+ *   - it lives on a DIFFERENT registry than the one the caller is about to
+ *     transact against. Exactly one UniversalAccountRegistry is indexed per
+ *     deployment, but a legacy org's QuickJoin can point at another address
+ *     (verified: Gnosis org "Test5" points at 0x01a1…8513, which has no code
+ *     on Gnosis), and Account.id is the bare address — not registry-scoped —
+ *     so a username from the indexed registry would be the wrong answer.
+ *
+ * `expectedRegistry` omitted means "no registry constraint" (the caller is
+ * reading the subgraph's own registry).
+ */
+function isAccountAuthoritative(account, expectedRegistry) {
+    if (!account || account.isDeleted)
+        return false;
+    if (!expectedRegistry)
+        return true;
+    const indexed = account.registry?.id;
+    if (!indexed)
+        return false;
+    return indexed.toLowerCase() === expectedRegistry.toLowerCase();
+}
+exports.FETCH_USER_DATA = `
+  query FetchUserDataNew($orgUserID: String!, $userAddress: Bytes!) {
+    user(id: $orgUserID) {
+      id
+      address
+      participationTokenBalance
+      membershipStatus
+      currentHatIds
+      joinMethod
+      totalTasksCompleted
+      totalVotes
+      totalModulesCompleted
+      firstSeenAt
+      lastActiveAt
+      assignedTasks(first: 20) {
+        id
+        taskId
+        title
+        payout
+        status
+      }
+      completedTasks(first: 20) {
+        id
+        taskId
+        title
+        payout
+      }
+      hybridProposalsCreated(first: 20) {
+        id
+        proposalId
+        title
+        status
+        startTimestamp
+        endTimestamp
+      }
+      modulesCompleted(first: 20) {
+        moduleId
+        completedAt
+      }
+    }
+    account(id: $userAddress) {
+      id
+      username
+    }
+  }
+`;
+/**
+ * FETCH_USER_DATA plus the per-user claim-churn counters (subgraph #201,
+ * TaskManager v7): how many claims this member released themselves, and how
+ * many were force-released out from under them after their claim expired.
+ *
+ * GNOSIS ONLY as of 2026-08-02. `totalTasksLostToExpiry` exists on BOTH
+ * deployments and only rides along here because a GraphQL document validates
+ * as a whole — there is no way to ask for it next to `totalTasksReleased`
+ * without the pair standing or falling together. Verified live that
+ * poa-arb-v-1 rejects this document with ``Type `User` has no field
+ * `totalTasksReleased``` (`isUnknownFieldError` matches /has no field/i, so
+ * the tier drops cleanly to FETCH_USER_DATA), while poa-gnosis-v-1 serves it.
+ *
+ * Both counters are zero on every live row on both chains today, so callers
+ * must gate rendering on the SERVED TIER: `0` ("indexed, never churned") has
+ * to stay distinguishable from absent ("not indexed here").
+ *
+ * Built by INSERTION so the two documents cannot drift apart, and so a
+ * reflow that broke the anchor would produce a visibly identical tier rather
+ * than a silently degraded one.
+ */
+exports.FETCH_USER_DATA_WITH_CHURN = exports.FETCH_USER_DATA.replace(/^(\s*)totalTasksCompleted$/m, '$1totalTasksCompleted\n$1totalTasksReleased\n$1totalTasksLostToExpiry');
+/** Tier order for `pop user profile`. Tier 1 is the untouched original. */
+exports.USER_DATA_TIERS = [
+    exports.FETCH_USER_DATA_WITH_CHURN, // 0: Gnosis — v7 claim-churn counters
+    exports.FETCH_USER_DATA, // 1: Arbitrum today — no releases indexed
+];
+/** Build the tier array for `queryWithFieldFallback`. */
+function userDataTiers(orgUserID, userAddress) {
+    return exports.USER_DATA_TIERS.map((query) => ({ query, variables: { orgUserID, userAddress } }));
+}

package/dist/graph/documents/voting-classes.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Voting-class queries — the subgraph mirror of HybridVoting.getClasses() /
+ * getProposalClasses(id) plus the two DISTINCT validity parameters
+ * (thresholdPct = % of weighted power, quorum = raw voter count).
+ *
+ * Model (verified live against poa-gnosis-v-1 and poa-arb-v-1):
+ *   HybridVotingContract { thresholdPct, quorum, classVersion, votingClasses }
+ *   VotingClass          { version, classIndex, strategy, slicePct, quadratic,
+ *                          minBalance, asset, hatIds, isActive }
+ *   Proposal             { classesVersion }   ← the frozen snapshot pointer
+ *
+ * A VotingClass row is NOT unique per contract — every setClasses() writes a
+ * fresh `version` (the block number) and keeps the old rows around, which is
+ * exactly what makes the per-proposal snapshot reconstructable. So every read
+ * here is "fetch the contract's class rows, then pick one version":
+ *   live config      → version == HybridVotingContract.classVersion
+ *   proposal snapshot→ version == Proposal.classesVersion
+ *
+ * Deployment tiering (src/lib/subgraph.ts queryWithFieldFallback): GraphQL
+ * validates a document as a whole, so `classVersion` — absent on subgraph
+ * deployments older than the class-versioning release — has to live in its own
+ * tier. The proposal-snapshot query deliberately has NO legacy tier: without
+ * `classesVersion` there is no way to identify the frozen snapshot, and
+ * silently showing the CURRENT classes for an old proposal would be worse than
+ * falling back to the on-chain getProposalClasses call.
+ */
+/** Live class config + threshold/quorum. Tier 0 — has classVersion. */
+export declare const FETCH_VOTING_CLASS_CONFIG = "\n  query FetchVotingClassConfig($hybridVoting: ID!) {\n    hybridVotingContract(id: $hybridVoting) {\n      id\n      thresholdPct\n      quorum\n      classVersion\n      votingClasses(first: 1000) {\n      version\n      classIndex\n      strategy\n      slicePct\n      quadratic\n      minBalance\n      asset\n      hatIds\n      isActive\n      }\n    }\n  }\n";
+/**
+ * Live class config, tier 1 — for deployments that predate `classVersion`.
+ * Without it the current version is recovered as max(version), which is
+ * correct as long as setClasses versions increase monotonically (they are
+ * block numbers, so they do).
+ */
+export declare const FETCH_VOTING_CLASS_CONFIG_LEGACY = "\n  query FetchVotingClassConfigLegacy($hybridVoting: ID!) {\n    hybridVotingContract(id: $hybridVoting) {\n      id\n      thresholdPct\n      quorum\n      votingClasses(first: 1000) {\n      version\n      classIndex\n      strategy\n      slicePct\n      quadratic\n      minBalance\n      asset\n      hatIds\n      isActive\n      }\n    }\n  }\n";
+/** Class snapshot frozen for one proposal + threshold/quorum. Single tier. */
+export declare const FETCH_PROPOSAL_VOTING_CLASSES = "\n  query FetchProposalVotingClasses($hybridVoting: ID!, $proposalId: BigInt!) {\n    hybridVotingContract(id: $hybridVoting) {\n      id\n      thresholdPct\n      quorum\n      proposals(where: { proposalId: $proposalId }) {\n        proposalId\n        classesVersion\n      }\n      votingClasses(first: 1000) {\n      version\n      classIndex\n      strategy\n      slicePct\n      quadratic\n      minBalance\n      asset\n      hatIds\n      isActive\n      }\n    }\n  }\n";
+/**
+ * Everything `pop vote analyze` needs in ONE round-trip: the frozen class
+ * snapshot, every ballot with its per-class raw power (Vote.classRawPowers is
+ * the exact quantity the command used to reconstruct from VoteCast logs), and
+ * the org's username map for display names.
+ */
+export declare const FETCH_PROPOSAL_VOTE_ANALYSIS = "\n  query FetchProposalVoteAnalysis($hybridVoting: ID!, $proposalId: BigInt!) {\n    hybridVotingContract(id: $hybridVoting) {\n      id\n      organization {\n        id\n        users(first: 100) {\n          address\n          account { username }\n        }\n      }\n      proposals(where: { proposalId: $proposalId }) {\n        proposalId\n        classesVersion\n        votes(first: 1000, orderBy: votedAt, orderDirection: asc) {\n          voter\n          voterUsername\n          optionIndexes\n          optionWeights\n          classRawPowers\n        }\n      }\n      votingClasses(first: 1000) {\n      version\n      classIndex\n      strategy\n      slicePct\n      quadratic\n      minBalance\n      asset\n      hatIds\n      isActive\n      }\n    }\n  }\n";
+/** One VotingClass row as returned by the subgraph (all scalars are strings/numbers). */
+export interface SubgraphVotingClass {
+    version: string;
+    classIndex: number;
+    strategy: string;
+    slicePct: number;
+    quadratic: boolean;
+    minBalance: string;
+    asset: string;
+    hatIds: string[];
+    isActive: boolean;
+}
+/**
+ * Pick the class rows belonging to one config version and order them by
+ * classIndex (the on-chain array order the whole slice/quorum math assumes).
+ *
+ * `version` null/undefined means the caller could not learn which version to
+ * use (legacy deployment without classVersion) — then the newest indexed
+ * version wins, which reproduces getClasses() but must NEVER be used to
+ * reconstruct an old proposal's frozen snapshot.
+ *
+ * Returns [] when nothing matches, which callers treat as "subgraph can't
+ * answer this" and fall back to the contract.
+ */
+export declare function selectClassSnapshot(rows: SubgraphVotingClass[] | undefined | null, version: string | number | null | undefined): SubgraphVotingClass[];

package/dist/graph/documents/voting-classes.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Voting-class queries — the subgraph mirror of HybridVoting.getClasses() /
+ * getProposalClasses(id) plus the two DISTINCT validity parameters
+ * (thresholdPct = % of weighted power, quorum = raw voter count).
+ *
+ * Model (verified live against poa-gnosis-v-1 and poa-arb-v-1):
+ *   HybridVotingContract { thresholdPct, quorum, classVersion, votingClasses }
+ *   VotingClass          { version, classIndex, strategy, slicePct, quadratic,
+ *                          minBalance, asset, hatIds, isActive }
+ *   Proposal             { classesVersion }   ← the frozen snapshot pointer
+ *
+ * A VotingClass row is NOT unique per contract — every setClasses() writes a
+ * fresh `version` (the block number) and keeps the old rows around, which is
+ * exactly what makes the per-proposal snapshot reconstructable. So every read
+ * here is "fetch the contract's class rows, then pick one version":
+ *   live config      → version == HybridVotingContract.classVersion
+ *   proposal snapshot→ version == Proposal.classesVersion
+ *
+ * Deployment tiering (src/lib/subgraph.ts queryWithFieldFallback): GraphQL
+ * validates a document as a whole, so `classVersion` — absent on subgraph
+ * deployments older than the class-versioning release — has to live in its own
+ * tier. The proposal-snapshot query deliberately has NO legacy tier: without
+ * `classesVersion` there is no way to identify the frozen snapshot, and
+ * silently showing the CURRENT classes for an old proposal would be worse than
+ * falling back to the on-chain getProposalClasses call.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FETCH_PROPOSAL_VOTE_ANALYSIS = exports.FETCH_PROPOSAL_VOTING_CLASSES = exports.FETCH_VOTING_CLASS_CONFIG_LEGACY = exports.FETCH_VOTING_CLASS_CONFIG = void 0;
+exports.selectClassSnapshot = selectClassSnapshot;
+/** Field set shared by every VotingClass selection. */
+const VOTING_CLASS_FIELDS = `
+      version
+      classIndex
+      strategy
+      slicePct
+      quadratic
+      minBalance
+      asset
+      hatIds
+      isActive`;
+/** Live class config + threshold/quorum. Tier 0 — has classVersion. */
+exports.FETCH_VOTING_CLASS_CONFIG = `
+  query FetchVotingClassConfig($hybridVoting: ID!) {
+    hybridVotingContract(id: $hybridVoting) {
+      id
+      thresholdPct
+      quorum
+      classVersion
+      votingClasses(first: 1000) {${VOTING_CLASS_FIELDS}
+      }
+    }
+  }
+`;
+/**
+ * Live class config, tier 1 — for deployments that predate `classVersion`.
+ * Without it the current version is recovered as max(version), which is
+ * correct as long as setClasses versions increase monotonically (they are
+ * block numbers, so they do).
+ */
+exports.FETCH_VOTING_CLASS_CONFIG_LEGACY = `
+  query FetchVotingClassConfigLegacy($hybridVoting: ID!) {
+    hybridVotingContract(id: $hybridVoting) {
+      id
+      thresholdPct
+      quorum
+      votingClasses(first: 1000) {${VOTING_CLASS_FIELDS}
+      }
+    }
+  }
+`;
+/** Class snapshot frozen for one proposal + threshold/quorum. Single tier. */
+exports.FETCH_PROPOSAL_VOTING_CLASSES = `
+  query FetchProposalVotingClasses($hybridVoting: ID!, $proposalId: BigInt!) {
+    hybridVotingContract(id: $hybridVoting) {
+      id
+      thresholdPct
+      quorum
+      proposals(where: { proposalId: $proposalId }) {
+        proposalId
+        classesVersion
+      }
+      votingClasses(first: 1000) {${VOTING_CLASS_FIELDS}
+      }
+    }
+  }
+`;
+/**
+ * Everything `pop vote analyze` needs in ONE round-trip: the frozen class
+ * snapshot, every ballot with its per-class raw power (Vote.classRawPowers is
+ * the exact quantity the command used to reconstruct from VoteCast logs), and
+ * the org's username map for display names.
+ */
+exports.FETCH_PROPOSAL_VOTE_ANALYSIS = `
+  query FetchProposalVoteAnalysis($hybridVoting: ID!, $proposalId: BigInt!) {
+    hybridVotingContract(id: $hybridVoting) {
+      id
+      organization {
+        id
+        users(first: 100) {
+          address
+          account { username }
+        }
+      }
+      proposals(where: { proposalId: $proposalId }) {
+        proposalId
+        classesVersion
+        votes(first: 1000, orderBy: votedAt, orderDirection: asc) {
+          voter
+          voterUsername
+          optionIndexes
+          optionWeights
+          classRawPowers
+        }
+      }
+      votingClasses(first: 1000) {${VOTING_CLASS_FIELDS}
+      }
+    }
+  }
+`;
+/**
+ * Pick the class rows belonging to one config version and order them by
+ * classIndex (the on-chain array order the whole slice/quorum math assumes).
+ *
+ * `version` null/undefined means the caller could not learn which version to
+ * use (legacy deployment without classVersion) — then the newest indexed
+ * version wins, which reproduces getClasses() but must NEVER be used to
+ * reconstruct an old proposal's frozen snapshot.
+ *
+ * Returns [] when nothing matches, which callers treat as "subgraph can't
+ * answer this" and fall back to the contract.
+ */
+function selectClassSnapshot(rows, version) {
+    const active = (rows ?? []).filter(r => r && r.isActive !== false);
+    if (active.length === 0)
+        return [];
+    let target = version === null || version === undefined ? null : String(version);
+    if (target === null) {
+        target = active.reduce((max, r) => {
+            const v = String(r.version);
+            if (max === null)
+                return v;
+            return BigInt(v) > BigInt(max) ? v : max;
+        }, null);
+    }
+    return active
+        .filter(r => String(r.version) === target)
+        .sort((a, b) => Number(a.classIndex) - Number(b.classIndex));
+}

package/dist/graph/documents/voting.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Voting Queries
+ * Ported from frontend queries.js
+ */
+/**
+ * Fuzzy --proposal resolution: recent proposals for ONE voting contract,
+ * addressed directly by contract address (works for HybridVoting and
+ * DirectDemocracyVoting — whichever entity matches the address answers,
+ * the other root field returns null). Titles are stored decoded by the
+ * subgraph, so they can be scored with bestMatches directly.
+ */
+export declare const RECENT_PROPOSALS_FOR_RESOLVE = "\n  query RecentProposalsForResolve($votingId: ID!, $first: Int!) {\n    hybridVotingContract(id: $votingId) {\n      id\n      proposals(orderBy: startTimestamp, orderDirection: desc, first: $first) {\n        proposalId\n        title\n        status\n        endTimestamp\n      }\n    }\n    directDemocracyVotingContract(id: $votingId) {\n      id\n      ddvProposals(orderBy: startTimestamp, orderDirection: desc, first: $first) {\n        proposalId\n        title\n        status\n        endTimestamp\n      }\n    }\n  }\n";
+/**
+ * One proposal's voting-window state for the cast pre-flight
+ * ("not obviously ended"). Same dual-entity addressing as above.
+ */
+export declare const PROPOSAL_STATE_FOR_PREFLIGHT = "\n  query ProposalStateForPreflight($votingId: ID!, $proposalId: BigInt!) {\n    hybridVotingContract(id: $votingId) {\n      proposals(where: { proposalId: $proposalId }, first: 1) {\n        proposalId\n        status\n        endTimestamp\n      }\n    }\n    directDemocracyVotingContract(id: $votingId) {\n      ddvProposals(where: { proposalId: $proposalId }, first: 1) {\n        proposalId\n        status\n        endTimestamp\n      }\n    }\n  }\n";
+export declare const FETCH_VOTING_DATA = "\n  query FetchVotingDataNew($orgId: Bytes!) {\n    organization(id: $orgId) {\n      id\n      hybridVoting {\n        id\n        thresholdPct\n        quorum\n        classVersion\n        votingClasses(where: { isActive: true }, orderBy: classIndex, orderDirection: asc) {\n          id\n          classIndex\n          version\n          strategy\n          slicePct\n          quadratic\n          minBalance\n          asset\n          hatIds\n          isActive\n        }\n        proposals(orderBy: startTimestamp, orderDirection: desc, first: 50) {\n          id\n          proposalId\n          title\n          descriptionHash\n          metadata {\n            id\n            description\n            optionNames\n          }\n          numOptions\n          startTimestamp\n          endTimestamp\n          status\n          winningOption\n          isValid\n          wasExecuted\n          executionFailed\n          executionError\n          isHatRestricted\n          restrictedHatIds\n          proposer\n          proposerUsername\n          creatorUsername\n          classesVersion\n          votes {\n            voter\n            voterUsername\n            optionIndexes\n            optionWeights\n            classRawPowers\n            votedAt\n          }\n        }\n      }\n      directDemocracyVoting {\n        id\n        thresholdPct\n        quorum\n        ddvProposals(orderBy: startTimestamp, orderDirection: desc, first: 50) {\n          id\n          proposalId\n          title\n          descriptionHash\n          metadata {\n            id\n            description\n            optionNames\n          }\n          numOptions\n          startTimestamp\n          endTimestamp\n          status\n          winningOption\n          isValid\n          executionFailed\n          executionError\n          isHatRestricted\n          restrictedHatIds\n          proposer\n          proposerUsername\n          votes {\n            voter\n            optionIndexes\n            optionWeights\n          }\n        }\n      }\n    }\n  }\n";
+/**
+ * FETCH_VOTING_DATA without the subgraph #195 attribution fields.
+ *
+ * A GraphQL document is validated as a whole, so a single unknown field fails the entire
+ * query — not just that selection. `pop vote announce-all` (a WRITE that announces winners)
+ * shares this document, so against a subgraph pinned before #195 the org would lose the
+ * ability to announce ANY proposal. Derived from the full query by deletion so the two
+ * cannot drift apart.
+ */
+export declare const FETCH_VOTING_DATA_LEGACY: string;