@poa-box/core 0.1.0

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

@@ -0,0 +1,9 @@
+/**
+ * Org Activity Query
+ * Compound query for agent heartbeat — fetches all recent changes since a timestamp.
+ * Single subgraph round-trip replaces 6+ separate calls.
+ *
+ * Uses nested org queries for tasks/members (known working pattern),
+ * and top-level queries for vouches/tokenRequests/proposals (validated in other query files).
+ */
+export declare const FETCH_ORG_ACTIVITY = "\n  query FetchOrgActivity(\n    $orgId: Bytes!\n    $hybridVotingId: String\n    $eligibilityModuleId: Bytes\n    $tokenAddress: String\n  ) {\n    # Org overview + tasks + members via nested pattern (known working)\n    organization(id: $orgId) {\n      id\n      name\n      participationToken {\n        id\n        totalSupply\n        symbol\n      }\n      paymentManager {\n        distributionCounter\n      }\n      taskManager {\n        id\n        projects(where: { deleted: false }, first: 50) {\n          id\n          title\n          tasks(first: 200, orderBy: taskId, orderDirection: desc) {\n            id\n            taskId\n            title\n            status\n            payout\n            assignee\n            assigneeUsername\n            completer\n            completerUsername\n            createdAt\n            assignedAt\n            submittedAt\n            completedAt\n          }\n        }\n      }\n      users(orderBy: firstSeenAt, orderDirection: desc, first: 20) {\n        address\n        account { username }\n        membershipStatus\n        joinMethod\n        firstSeenAt\n        currentHatIds\n      }\n      directDemocracyVoting {\n        ddvProposals(\n          where: { status: \"Active\" }\n          orderBy: startTimestamp\n          orderDirection: desc\n          first: 50\n        ) {\n          id\n          proposalId\n          title\n          metadata { description optionNames }\n          numOptions\n          startTimestamp\n          endTimestamp\n          status\n          isHatRestricted\n          restrictedHatIds\n          votes { voter optionIndexes optionWeights }\n        }\n      }\n    }\n\n    # Active hybrid proposals \u2014 top-level query (validated: proposals entity exists)\n    activeHybridProposals: proposals(\n      where: { hybridVoting: $hybridVotingId, status: \"Active\" }\n      orderBy: startTimestamp\n      orderDirection: desc\n      first: 50\n    ) {\n      id\n      proposalId\n      title\n      metadata { description optionNames }\n      numOptions\n      startTimestamp\n      endTimestamp\n      status\n      isHatRestricted\n      restrictedHatIds\n      votes {\n        voter\n        voterUsername\n        optionIndexes\n        optionWeights\n        classRawPowers\n        votedAt\n      }\n    }\n\n    # Recently ended hybrid proposals (catch outcomes since last heartbeat)\n    endedHybridProposals: proposals(\n      where: { hybridVoting: $hybridVotingId, status: \"Ended\" }\n      orderBy: startTimestamp\n      orderDirection: desc\n      first: 10\n    ) {\n      id\n      proposalId\n      title\n      status\n      winningOption\n      isValid\n      wasExecuted\n      executionFailed\n      executionError\n      votes { voter optionIndexes optionWeights }\n    }\n\n    # Active vouches \u2014 top-level query (validated in vouch.ts). isActive carries the\n    # epoch filter: deployments that index the vouch epoch flip it false for every vouch\n    # a configureVouching/resetVouches/clearWearerVouches voided, so this listing needs no\n    # extra field. Older deployments still list superseded vouches \u2014 stale rather than\n    # wrong, which is fine for an activity feed but NOT for quorum maths (see vouch.ts).\n    activeVouches: vouches(\n      where: { eligibilityModule: $eligibilityModuleId, isActive: true }\n      orderBy: createdAt\n      orderDirection: desc\n      first: 100\n    ) {\n      hatId\n      wearer\n      wearerUsername\n      voucher\n      voucherUsername\n      vouchCount\n      createdAt\n    }\n\n    # Pending token requests \u2014 top-level query (validated in token.ts)\n    pendingTokenRequests: tokenRequests(\n      where: { participationToken: $tokenAddress, status: Pending }\n      orderBy: createdAt\n      orderDirection: desc\n      first: 50\n    ) {\n      requestId\n      requester\n      amount\n      metadata { reason }\n      status\n      createdAt\n    }\n  }\n";

package/dist/graph/documents/activity.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Org Activity Query
+ * Compound query for agent heartbeat — fetches all recent changes since a timestamp.
+ * Single subgraph round-trip replaces 6+ separate calls.
+ *
+ * Uses nested org queries for tasks/members (known working pattern),
+ * and top-level queries for vouches/tokenRequests/proposals (validated in other query files).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FETCH_ORG_ACTIVITY = void 0;
+exports.FETCH_ORG_ACTIVITY = `
+  query FetchOrgActivity(
+    $orgId: Bytes!
+    $hybridVotingId: String
+    $eligibilityModuleId: Bytes
+    $tokenAddress: String
+  ) {
+    # Org overview + tasks + members via nested pattern (known working)
+    organization(id: $orgId) {
+      id
+      name
+      participationToken {
+        id
+        totalSupply
+        symbol
+      }
+      paymentManager {
+        distributionCounter
+      }
+      taskManager {
+        id
+        projects(where: { deleted: false }, first: 50) {
+          id
+          title
+          tasks(first: 200, orderBy: taskId, orderDirection: desc) {
+            id
+            taskId
+            title
+            status
+            payout
+            assignee
+            assigneeUsername
+            completer
+            completerUsername
+            createdAt
+            assignedAt
+            submittedAt
+            completedAt
+          }
+        }
+      }
+      users(orderBy: firstSeenAt, orderDirection: desc, first: 20) {
+        address
+        account { username }
+        membershipStatus
+        joinMethod
+        firstSeenAt
+        currentHatIds
+      }
+      directDemocracyVoting {
+        ddvProposals(
+          where: { status: "Active" }
+          orderBy: startTimestamp
+          orderDirection: desc
+          first: 50
+        ) {
+          id
+          proposalId
+          title
+          metadata { description optionNames }
+          numOptions
+          startTimestamp
+          endTimestamp
+          status
+          isHatRestricted
+          restrictedHatIds
+          votes { voter optionIndexes optionWeights }
+        }
+      }
+    }
+
+    # Active hybrid proposals — top-level query (validated: proposals entity exists)
+    activeHybridProposals: proposals(
+      where: { hybridVoting: $hybridVotingId, status: "Active" }
+      orderBy: startTimestamp
+      orderDirection: desc
+      first: 50
+    ) {
+      id
+      proposalId
+      title
+      metadata { description optionNames }
+      numOptions
+      startTimestamp
+      endTimestamp
+      status
+      isHatRestricted
+      restrictedHatIds
+      votes {
+        voter
+        voterUsername
+        optionIndexes
+        optionWeights
+        classRawPowers
+        votedAt
+      }
+    }
+
+    # Recently ended hybrid proposals (catch outcomes since last heartbeat)
+    endedHybridProposals: proposals(
+      where: { hybridVoting: $hybridVotingId, status: "Ended" }
+      orderBy: startTimestamp
+      orderDirection: desc
+      first: 10
+    ) {
+      id
+      proposalId
+      title
+      status
+      winningOption
+      isValid
+      wasExecuted
+      executionFailed
+      executionError
+      votes { voter optionIndexes optionWeights }
+    }
+
+    # Active vouches — top-level query (validated in vouch.ts). isActive carries the
+    # epoch filter: deployments that index the vouch epoch flip it false for every vouch
+    # a configureVouching/resetVouches/clearWearerVouches voided, so this listing needs no
+    # extra field. Older deployments still list superseded vouches — stale rather than
+    # wrong, which is fine for an activity feed but NOT for quorum maths (see vouch.ts).
+    activeVouches: vouches(
+      where: { eligibilityModule: $eligibilityModuleId, isActive: true }
+      orderBy: createdAt
+      orderDirection: desc
+      first: 100
+    ) {
+      hatId
+      wearer
+      wearerUsername
+      voucher
+      voucherUsername
+      vouchCount
+      createdAt
+    }
+
+    # Pending token requests — top-level query (validated in token.ts)
+    pendingTokenRequests: tokenRequests(
+      where: { participationToken: $tokenAddress, status: Pending }
+      orderBy: createdAt
+      orderDirection: desc
+      first: 50
+    ) {
+      requestId
+      requester
+      amount
+      metadata { reason }
+      status
+      createdAt
+    }
+  }
+`;

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

@@ -0,0 +1,172 @@
+/**
+ * Beacon / implementation queries — "which implementation is behind this proxy,
+ * and which version is that".
+ *
+ * Everything here replaces an RPC read that was either expensive or silently
+ * unreliable:
+ *
+ *   - eth_getStorageAt(proxy, EIP-1967 beacon slot) + beacon.implementation()
+ *     → RegisteredContract.beacon → SwitchableBeaconContract.mode → the
+ *       implementation the beacon resolves to.
+ *   - PoaManager.getCurrentImplementationById(typeId)
+ *     → Beacon(typeId).currentImplementation.
+ *   - OrgRegistry.isAutoUpgrade(keccak256(orgId ‖ typeId))
+ *     → RegisteredContract.autoUpgrade (and no ContractUnknown revert path).
+ *   - eth_getLogs(ImplementationRegistered, block 0 → latest)
+ *     → BeaconUpgradeEvent.{newImplementation,version}.
+ *
+ * VERIFIED AGAINST LIVE DATA (Gnosis poa-gnosis-v-1 and Arbitrum poa-arb-v-1,
+ * 2026-07-30) — every field selected below is non-null on real rows, with two
+ * deliberate exceptions that are handled as gaps rather than trusted:
+ *
+ *   - SwitchableBeaconContract.mirrorBeacon is NULL on EVERY live row on BOTH
+ *     deployments. The Mirror branch therefore joins the global Beacon by
+ *     typeId (RegisteredContract.typeId), never by mirrorBeacon.
+ *   - SwitchableBeaconContract.pinnedImplementation is NULL on every live row
+ *     and there is not a single row with mode = "Pinned" on either chain, so
+ *     the field has never been observed populated. Pinned beacons therefore
+ *     fall back to RPC unless the row actually carries a value.
+ *
+ * The join that IS used was checked end to end on Gnosis org "Test6":
+ *   RegisteredContract(TaskManager).beacon = 0x4af43d51…d4da7c5
+ *   == eth_getStorageAt(proxy 0x3d93f0d0…, EIP-1967 beacon slot)
+ *   SwitchableBeaconContract(0x4af43d51…).mode = "Mirror"
+ *   Beacon("gnosis-<TaskManager typeId>").currentImplementation
+ *     = 0x7833c467… == beacon.implementation() over RPC. Match.
+ *
+ * A separate workstream is adding an implementation-address-keyed entity to
+ * the subgraph (Beacon.currentImplementation only answers for the CURRENT
+ * mirror implementation, not pinned or historical ones). Both query sets are
+ * expressed as tier ARRAYS fed to queryWithFieldFallback so that entity can be
+ * slotted in as a new tier 0 without touching any caller.
+ */
+import type { GraphClient } from '../client';
+export interface BeaconRow {
+    typeId: string;
+    typeName: string;
+    currentImplementation: string;
+    version: string | null;
+    /**
+     * The global beacon's own address. Only selected by the org-module documents,
+     * where it is needed to prove a Mirror beacon still mirrors THIS beacon.
+     */
+    beaconAddress?: string | null;
+}
+export interface RegisteredContractRow {
+    id: string;
+    typeId: string;
+    proxy: string;
+    beacon: string | null;
+    autoUpgrade: boolean | null;
+}
+export interface SwitchableBeaconRow {
+    /** The beacon's own address (entity id), lowercased by the indexer. */
+    id: string;
+    typeId: string | null;
+    /**
+     * "Mirror" | "Static" as written by the deployed mappings ("Pinned" is
+     * accepted as a forward-compatible alias). Anything else is unknown → RPC.
+     */
+    mode: string | null;
+    /**
+     * NULL on every live row today, because the SwitchableBeacon constructor sets
+     * it without emitting MirrorSet. A real setMirror() populates it — at which
+     * point it MUST be compared against Beacon.beaconAddress before joining the
+     * global beacon by typeId.
+     */
+    mirrorBeacon: string | null;
+    /** Never observed populated; only trusted when actually present. */
+    pinnedImplementation: string | null;
+}
+/** Tier 0: RegisteredContract + SwitchableBeaconContract + global Beacon. */
+export declare const ORG_MODULE_BEACONS_FULL = "\n  query OrgModuleBeacons($orgId: Bytes!, $orgIdStr: String!) {\n    registeredContracts(first: 100, where: { orgId: $orgId }) {\n      id\n      typeId\n      proxy\n      beacon\n      autoUpgrade\n    }\n    switchableBeaconContracts(first: 100, where: { organization: $orgIdStr }) {\n      id\n      typeId\n      mode\n      mirrorBeacon\n      pinnedImplementation\n    }\n    beacons(first: 100) {\n      typeId\n      typeName\n      currentImplementation\n      version\n      # Needed to prove a Mirror beacon still mirrors THIS global beacon.\n      # Only tier 0 selects it: tiers 1/2 carry no SwitchableBeaconContract rows,\n      # so their mode is unknown and they already degrade to RPC.\n      beaconAddress\n    }\n  }\n";
+/** Tier 1: deployment without SwitchableBeaconContract (mode unknown → RPC). */
+export declare const ORG_MODULE_BEACONS_NO_SWITCHABLE = "\n  query OrgModuleBeaconsNoSwitchable($orgId: Bytes!) {\n    registeredContracts(first: 100, where: { orgId: $orgId }) {\n      id\n      typeId\n      proxy\n      beacon\n      autoUpgrade\n    }\n    beacons(first: 100) {\n      typeId\n      typeName\n      currentImplementation\n      version\n    }\n  }\n";
+/** Tier 2: global beacons only (still kills getCurrentImplementationById). */
+export declare const ORG_MODULE_BEACONS_MINIMAL = "\n  query OrgModuleBeaconsMinimal {\n    beacons(first: 100) {\n      typeId\n      typeName\n      currentImplementation\n      version\n    }\n  }\n";
+/** Tier 0: implementation → version index (global beacons + upgrade history). */
+export declare const IMPLEMENTATION_VERSIONS_FULL = "\n  query ImplementationVersions($first: Int!, $skip: Int!) {\n    beacons(first: 100) {\n      typeId\n      typeName\n      currentImplementation\n      version\n    }\n    beaconUpgradeEvents(first: $first, skip: $skip, orderBy: upgradedAt, orderDirection: asc) {\n      typeId\n      newImplementation\n      version\n    }\n  }\n";
+/** Tier 1: deployment without BeaconUpgradeEvent — current implementations only. */
+export declare const IMPLEMENTATION_VERSIONS_BEACONS_ONLY = "\n  query ImplementationVersionsBeaconsOnly {\n    beacons(first: 100) {\n      typeId\n      typeName\n      currentImplementation\n      version\n    }\n  }\n";
+export interface ModuleBeaconEntry {
+    registered?: RegisteredContractRow;
+    switchable?: SwitchableBeaconRow;
+    globalBeacon?: BeaconRow;
+}
+export interface OrgBeaconSnapshot {
+    /** Keyed by lowercased typeId. */
+    byTypeId: Map<string, ModuleBeaconEntry>;
+    /** Which queryWithFieldFallback tier answered (0 = richest). */
+    tierIndex: number;
+}
+/**
+ * Checksum an address that came from the subgraph (which lowercases them) so
+ * subgraph-served values are byte-identical to the RPC-served ones the JSON
+ * output has always carried. Returns null for anything unparseable/zero.
+ */
+export declare function checksumAddress(value: string | null | undefined): string | null;
+/** Build the per-typeId index from raw query rows (pure — unit testable). */
+export declare function buildOrgBeaconSnapshot(data: {
+    registeredContracts?: RegisteredContractRow[];
+    switchableBeaconContracts?: SwitchableBeaconRow[];
+    beacons?: BeaconRow[];
+}, tierIndex?: number): OrgBeaconSnapshot;
+/**
+ * Which implementation the org's module proxy currently delegates to, per the
+ * subgraph. Returns null whenever the subgraph cannot answer with confidence —
+ * the caller must then fall back to RPC. Never guesses.
+ */
+export declare function resolveImplementationFromSnapshot(snapshot: OrgBeaconSnapshot | null | undefined, typeId: string): {
+    implementation: string;
+    version: string | null;
+    mode: string;
+} | null;
+/** Latest protocol implementation for a module type (PoaManager equivalent). */
+export declare function latestImplementationFromSnapshot(snapshot: OrgBeaconSnapshot | null | undefined, typeId: string): string | null;
+/**
+ * Registration-time autoUpgrade HINT — NOT an OrgRegistry.isAutoUpgrade equivalent.
+ *
+ * The deployed subgraph writes RegisteredContract.autoUpgrade once, inside
+ * handleContractRegistered, and never again: schema.graphql annotates it
+ * "immutable, set at registration" and there is no AutoUpgradeSet handler at all.
+ * OrgRegistry.setAutoUpgrade(orgId, typeId, bool) is a live mutator, so after an
+ * executor turns auto-upgrade OFF this value keeps reporting the registration-time
+ * `true` forever — and 91/91 live Gnosis rows are `true`, so the divergent case has
+ * never once been exercised.
+ *
+ * Callers that render a pinning claim MUST prefer the on-chain isAutoUpgrade read
+ * and use this only when OrgRegistry is unreachable (see org/status.ts).
+ */
+export declare function autoUpgradeFromSnapshot(snapshot: OrgBeaconSnapshot | null | undefined, typeId: string): boolean | null;
+/** The proxy's beacon address, when indexed — lets callers skip getStorageAt. */
+export declare function beaconAddressFromSnapshot(snapshot: OrgBeaconSnapshot | null | undefined, typeId: string): string | null;
+/**
+ * Fetch the org's module→beacon snapshot. Throws only on transport failure;
+ * callers treat a throw as "no snapshot" and use their RPC path.
+ */
+export declare function fetchOrgBeaconSnapshot(client: GraphClient, orgId: string, chainId?: number): Promise<OrgBeaconSnapshot>;
+export interface ImplementationVersionRow {
+    typeName: string;
+    version: string;
+    implementation: string;
+    /** True when this address is a global beacon's CURRENT implementation. */
+    latest: boolean;
+}
+/**
+ * Every implementation address the subgraph can name a version for, keyed by
+ * lowercased address.
+ *
+ * Sources: Beacon.currentImplementation (the live one per type) and
+ * BeaconUpgradeEvent.newImplementation (every implementation a global beacon
+ * has ever pointed at). Verified live: 71 upgrade events on Gnosis with zero
+ * null newImplementation/version values, and identical implementation
+ * addresses on Arbitrum (deterministic deploys), so the index is chain-safe.
+ *
+ * NOT covered: an implementation that was registered but never promoted onto a
+ * global beacon (only reachable by pinning to it). Callers keep the registry
+ * eth_getLogs scan as the explicit fallback for exactly that case.
+ */
+export declare function fetchImplementationVersionIndex(client: GraphClient, chainId?: number): Promise<{
+    index: Map<string, ImplementationVersionRow>;
+    tierIndex: number;
+}>;