@poa-box/core 0.1.0

package/dist/reads/task.d.ts

@@ -0,0 +1,286 @@
+/**
+ * Task-domain subgraph reads: the projects/tasks tree, task stats, permission
+ * masks, folders root, and v7 release history.
+ *
+ * Ports the read paths of `pop task list` / `view` / `stats` /
+ * `perms show` / `folders show` (src/commands/task/{list,view,stats,perms,
+ * folders}.ts) onto the injected GraphClient. Tier arrays come from
+ * ../graph/documents/task where they already exist; the stats / perms /
+ * folders documents lived inline in the CLI command files and are ported here
+ * verbatim, comments included — the live-verification notes are load-bearing.
+ */
+import type { GraphClient, FieldFallbackTier } from '../graph/client';
+/** Subgraph Task entity as served by FETCH_PROJECTS_DATA (fields vary by tier). */
+export interface SubgraphTask {
+    /** Composite entity id `<taskManager>-<taskId>`. */
+    id: string;
+    /** Bare numeric task id (string). */
+    taskId: string;
+    title: string | null;
+    metadataHash: string | null;
+    metadata: Record<string, any> | null;
+    status: string;
+    payout: string | null;
+    bountyToken?: string | null;
+    bountyPayout?: string | null;
+    assignee?: string | null;
+    assigneeUsername?: string | null;
+    requiresApplication?: boolean | null;
+    createdAt?: string | null;
+    /** v6 deadline fields — null means unset on-chain, absent means tier didn't serve them. */
+    completionWindow?: string | null;
+    absoluteDeadline?: string | null;
+    claimDeadline?: string | null;
+    reclaimCount?: string | null;
+    /** v7 release fields — tier 0 (Gnosis) only. */
+    releaseCount?: string | null;
+    lastReleasedAt?: string | null;
+    [key: string]: any;
+}
+/** Subgraph Project entity as served by FETCH_PROJECTS_DATA. */
+export interface SubgraphProject {
+    /** Composite entity id `<taskManager>-<projectIdHex>`. */
+    id: string;
+    title: string | null;
+    metadataHash?: string | null;
+    metadata?: Record<string, any> | null;
+    cap?: string | null;
+    createdAt?: string | null;
+    tasks?: SubgraphTask[];
+    [key: string]: any;
+}
+export interface ProjectsDataResult {
+    organization: {
+        id: string;
+        taskManager: {
+            id: string;
+            creatorHatIds?: string[];
+            projects: SubgraphProject[];
+        } | null;
+    } | null;
+}
+export interface ProjectsDataRead {
+    data: ProjectsDataResult;
+    /** Which tier served (see PROJECTS_DATA_TIERS in ../graph/documents/task). */
+    tierIndex: number;
+    /**
+     * Tier 0 adds the v7 release fields (subgraph #201, Gnosis only today);
+     * tier 1 is the same document WITHOUT them, so it still carries deadlines.
+     * `<= 1` and not `=== 0`: inserting the release tier shifted every index,
+     * and reading this as `=== 0` would silently degrade every non-Gnosis org.
+     */
+    hasDeadlineData: boolean;
+    /** Gate release-field rendering on the SERVED TIER, never on truthiness. */
+    hasReleaseData: boolean;
+}
+/**
+ * The org's full projects → tasks tree with tier fallback.
+ * Port of the read at src/commands/task/list.ts:129 (also view.ts:95).
+ */
+export declare function fetchProjectsData(client: GraphClient, orgId: string, chainId?: number): Promise<ProjectsDataRead>;
+/** A task row flattened out of the projects tree, with its project attached. */
+export interface TaskListRow extends SubgraphTask {
+    /** Composite project entity id the task belongs to. */
+    projectId: string;
+    projectTitle: string | null;
+}
+/**
+ * Flat list of an org's tasks — the friendliest first read (`pop task list`'s
+ * data, sans rendering). Sugar over fetchProjectsData: same tiered query, the
+ * projects → tasks tree flattened with each row keeping its project identity.
+ */
+export declare function listTasks(client: GraphClient, orgId: string, chainId?: number): Promise<TaskListRow[]>;
+/**
+ * Find a task in a FETCH_PROJECTS_DATA result by its NUMERIC task id.
+ * Port of src/commands/task/helpers.ts findSubgraphTask.
+ *
+ * The subgraph keys tasks by the composite `<taskManager>-<taskId>` while the contract (and
+ * `parseTaskId`) uses the bare number, so callers must pass the parsed id — matching on the raw
+ * `--task` argument silently misses whenever a user pastes the composite form back in.
+ *
+ * Shared because the write commands re-pin metadata from whatever this returns: a miss means
+ * they rebuild the doc from defaults and the full-overwrite write erases the task's real
+ * name/description/location/dueDate.
+ */
+export declare function findSubgraphTask(projects: SubgraphProject[], taskId: string): SubgraphTask | null;
+/** Port of the inline document at src/commands/task/stats.ts:12. */
+export declare const FETCH_TASK_STATS = "\n  query FetchTaskStats($orgId: Bytes!) {\n    organization(id: $orgId) {\n      users(first: 100) {\n        address\n        participationTokenBalance\n        membershipStatus\n        totalTasksCompleted\n        totalTasksReleased\n        totalTasksLostToExpiry\n        account { username }\n      }\n      taskManager {\n        projects(where: { deleted: false }, first: 100) {\n          title\n          tasks(first: 1000) {\n            taskId\n            title\n            status\n            payout\n            assignee\n            assigneeUsername\n            completer\n            completerUsername\n            createdAt\n          }\n        }\n      }\n    }\n  }\n";
+/**
+ * FETCH_TASK_STATS without the claim-churn counters (subgraph #201, TaskManager v7).
+ *
+ * The two counters are asymmetric: `totalTasksLostToExpiry` is live on Arbitrum too, but
+ * `totalTasksReleased` is Gnosis-only as of 2026-08-02 (verified: poa-arb-v-1 answers
+ * ``Type `User` has no field `totalTasksReleased```, which `isUnknownFieldError` matches).
+ * A document validates as a whole, so they have to share tier 0 — asking for the portable
+ * one alongside the Gnosis-only one costs nothing, since the whole query would fail anyway.
+ * Derived by deletion so the two tiers cannot drift apart.
+ */
+export declare const FETCH_TASK_STATS_LEGACY: string;
+export interface TaskStatsUser {
+    address: string;
+    participationTokenBalance: string | null;
+    membershipStatus: string | null;
+    totalTasksCompleted?: string | null;
+    /** Tier 0 only — null row means "not indexed on this chain", not zero. */
+    totalTasksReleased?: string | null;
+    totalTasksLostToExpiry?: string | null;
+    account: {
+        username: string | null;
+    } | null;
+}
+export interface TaskStatsResult {
+    organization: {
+        users: TaskStatsUser[];
+        taskManager: {
+            projects: Array<{
+                title: string | null;
+                tasks: SubgraphTask[];
+            }>;
+        } | null;
+    } | null;
+}
+export interface TaskStatsRead {
+    data: TaskStatsResult;
+    tierIndex: number;
+    /** True when the v7 claim-churn counters were served (tier 0). */
+    hasChurnCounters: boolean;
+}
+/**
+ * Raw per-member + per-project task analytics inputs.
+ * Port of the read at src/commands/task/stats.ts:62 (aggregation stays host-side).
+ */
+export declare function fetchTaskStats(client: GraphClient, orgId: string, chainId?: number): Promise<TaskStatsRead>;
+/**
+ * Tier 0: deployed v4 schema — GlobalRolePermission masks, organizerHatIds,
+ * per-project ProjectRolePermission masks.
+ * Port of PERMS_QUERY_FULL at src/commands/task/perms.ts:55. Masks are
+ * subgraph-only: they are NOT readable per-wearer on-chain.
+ */
+export declare const PERMS_QUERY_FULL = "\n  query TaskPermsFull($orgId: Bytes!) {\n    organization(id: $orgId) {\n      id\n      taskManager {\n        id\n        creatorHatIds\n        organizerHatIds\n        globalRolePermissions { hatId mask }\n        projects(where: { deleted: false }, first: 50) {\n          id\n          title\n          rolePermissions { hatId mask }\n        }\n      }\n    }\n  }\n";
+/** Tier 1: older schema — no global perms/organizer hats; boolean per-project flags. */
+export declare const PERMS_QUERY_LEGACY = "\n  query TaskPermsLegacy($orgId: Bytes!) {\n    organization(id: $orgId) {\n      id\n      taskManager {\n        id\n        creatorHatIds\n        projects(where: { deleted: false }, first: 50) {\n          id\n          title\n          rolePermissions { hatId canCreate canClaim canReview canAssign }\n        }\n      }\n    }\n  }\n";
+/** Tier array for `queryWithFieldFallback`, matching the CLI's order. */
+export declare function taskPermsTiers(orgId: string): FieldFallbackTier[];
+export interface SubgraphRolePermission {
+    hatId: string;
+    /** Tier 0 field. */
+    mask?: number | string;
+    /** Tier 1 (legacy) boolean fields. */
+    canCreate?: boolean;
+    canClaim?: boolean;
+    canReview?: boolean;
+    canAssign?: boolean;
+}
+export interface TaskPermsResult {
+    organization: {
+        id: string;
+        taskManager: {
+            id: string;
+            creatorHatIds?: string[];
+            organizerHatIds?: string[];
+            globalRolePermissions?: SubgraphRolePermission[];
+            projects: Array<{
+                id: string;
+                title: string | null;
+                rolePermissions?: SubgraphRolePermission[];
+            }>;
+        } | null;
+    } | null;
+}
+export interface TaskPermsRead {
+    data: TaskPermsResult;
+    tierIndex: number;
+}
+/**
+ * Global + per-project permission masks. Port of the read at
+ * src/commands/task/perms.ts:175 (`pop task perms show`).
+ */
+export declare function fetchTaskPerms(client: GraphClient, orgId: string, chainId?: number): Promise<TaskPermsRead>;
+/**
+ * Rebuild a mask from tier-1 boolean flags (partial: only bits 1..8 indexable).
+ * Port of src/commands/task/perms.ts maskFromBooleans.
+ */
+export declare function maskFromBooleans(rp: SubgraphRolePermission): number;
+/**
+ * Resolve --project-style input (bytes32 hex, subgraph composite ID, or title)
+ * to the on-chain bytes32 pid using an already-fetched projects list.
+ * Port of src/commands/task/perms.ts resolveProjectFromList (same messages).
+ */
+export declare function resolveProjectFromList(projects: Array<{
+    id: string;
+    title?: string | null;
+}>, input: string): {
+    pid: string;
+    title?: string;
+};
+/**
+ * Tier 0: v4 schema with folders provenance on Organization.
+ * Port of FOLDERS_QUERY_FULL at src/commands/task/folders.ts:54 — foldersRoot
+ * verified populated on live Gnosis (org Test6 = 0x8694f683…).
+ */
+export declare const FOLDERS_QUERY_FULL = "\n  query OrgFolders($orgId: Bytes!) {\n    organization(id: $orgId) {\n      id\n      foldersRoot\n      foldersUpdatedAt\n      foldersUpdatedBy\n    }\n  }\n";
+/** Tier 1: pre-folders schema. */
+export declare const FOLDERS_QUERY_LEGACY = "\n  query OrgFoldersLegacy($orgId: Bytes!) {\n    organization(id: $orgId) {\n      id\n    }\n  }\n";
+export interface OrgFoldersResult {
+    organization: {
+        id: string;
+        foldersRoot?: string | null;
+        foldersUpdatedAt?: string | null;
+        foldersUpdatedBy?: string | null;
+    } | null;
+}
+export interface OrgFoldersRead {
+    data: OrgFoldersResult;
+    tierIndex: number;
+    /**
+     * Normalised root, or null. A null foldersRoot means "no FoldersUpdated ever
+     * indexed", which is NOT the same as "root is zero" — callers must fall back
+     * to the on-chain lens (getFoldersRoot) rather than assume.
+     */
+    indexedRoot: string | null;
+}
+/**
+ * The org's indexed folders root + provenance. Port of the read at
+ * src/commands/task/folders.ts:169 (`pop task folders show`).
+ */
+export declare function fetchOrgFolders(client: GraphClient, orgId: string, chainId?: number): Promise<OrgFoldersRead>;
+/**
+ * Normalise a subgraph bytes32 to the 0x-prefixed lowercase form the lens returns.
+ * Port of src/commands/task/folders.ts normalizeRoot.
+ */
+export declare function normalizeRoot(value: string | null | undefined): string | null;
+export interface TaskReleaseEntry {
+    id: string;
+    previousClaimer: string;
+    previousClaimerUsername: string | null;
+    caller: string;
+    callerUsername: string | null;
+    selfRelease: boolean;
+    releasedAt: string;
+    releasedAtBlock?: string;
+    transactionHash: string;
+}
+export interface TaskReleaseHistoryResult {
+    task: {
+        id: string;
+        taskId: string;
+        status: string;
+        releaseCount?: string | null;
+        lastReleasedAt?: string | null;
+        releases?: TaskReleaseEntry[];
+    } | null;
+}
+export interface TaskReleaseHistoryRead {
+    data: TaskReleaseHistoryResult;
+    tierIndex: number;
+    /** tierIndex 1 means "release history not indexed here" — releases absent, not empty. */
+    hasReleaseHistory: boolean;
+}
+/**
+ * One task's release history (subgraph #201, Gnosis-only today). Port of the
+ * read at src/commands/task/view.ts:277. `taskEntityId` is the Task ENTITY id
+ * — `<lowercased taskManager address>-<numeric task id>`, not the bare number.
+ * The CLI issues this only when the shared projects document already reported
+ * `releaseCount > 0`, keeping the common path at one round-trip.
+ */
+export declare function fetchTaskReleaseHistory(client: GraphClient, taskEntityId: string, first?: number, chainId?: number): Promise<TaskReleaseHistoryRead>;

package/dist/reads/task.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * Task-domain subgraph reads: the projects/tasks tree, task stats, permission
+ * masks, folders root, and v7 release history.
+ *
+ * Ports the read paths of `pop task list` / `view` / `stats` /
+ * `perms show` / `folders show` (src/commands/task/{list,view,stats,perms,
+ * folders}.ts) onto the injected GraphClient. Tier arrays come from
+ * ../graph/documents/task where they already exist; the stats / perms /
+ * folders documents lived inline in the CLI command files and are ported here
+ * verbatim, comments included — the live-verification notes are load-bearing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOLDERS_QUERY_LEGACY = exports.FOLDERS_QUERY_FULL = exports.PERMS_QUERY_LEGACY = exports.PERMS_QUERY_FULL = exports.FETCH_TASK_STATS_LEGACY = exports.FETCH_TASK_STATS = void 0;
+exports.fetchProjectsData = fetchProjectsData;
+exports.listTasks = listTasks;
+exports.findSubgraphTask = findSubgraphTask;
+exports.fetchTaskStats = fetchTaskStats;
+exports.taskPermsTiers = taskPermsTiers;
+exports.fetchTaskPerms = fetchTaskPerms;
+exports.maskFromBooleans = maskFromBooleans;
+exports.resolveProjectFromList = resolveProjectFromList;
+exports.fetchOrgFolders = fetchOrgFolders;
+exports.normalizeRoot = normalizeRoot;
+exports.fetchTaskReleaseHistory = fetchTaskReleaseHistory;
+const task_1 = require("../graph/documents/task");
+const encoding_1 = require("../encoding");
+const perms_1 = require("../perms");
+const errors_1 = require("../errors");
+const exit_codes_1 = require("../exit-codes");
+const ethers_1 = require("ethers");
+/**
+ * The org's full projects → tasks tree with tier fallback.
+ * Port of the read at src/commands/task/list.ts:129 (also view.ts:95).
+ */
+async function fetchProjectsData(client, orgId, chainId) {
+    const { data, tierIndex } = await client.queryWithFieldFallback((0, task_1.projectsDataTiers)(orgId), { chainId });
+    return {
+        data,
+        tierIndex,
+        hasDeadlineData: tierIndex <= 1,
+        hasReleaseData: tierIndex === 0,
+    };
+}
+/**
+ * Flat list of an org's tasks — the friendliest first read (`pop task list`'s
+ * data, sans rendering). Sugar over fetchProjectsData: same tiered query, the
+ * projects → tasks tree flattened with each row keeping its project identity.
+ */
+async function listTasks(client, orgId, chainId) {
+    const { data } = await fetchProjectsData(client, orgId, chainId);
+    const projects = data.organization?.taskManager?.projects ?? [];
+    return projects.flatMap(p => (p.tasks ?? []).map(t => ({ ...t, projectId: p.id, projectTitle: p.title ?? null })));
+}
+/**
+ * Find a task in a FETCH_PROJECTS_DATA result by its NUMERIC task id.
+ * Port of src/commands/task/helpers.ts findSubgraphTask.
+ *
+ * The subgraph keys tasks by the composite `<taskManager>-<taskId>` while the contract (and
+ * `parseTaskId`) uses the bare number, so callers must pass the parsed id — matching on the raw
+ * `--task` argument silently misses whenever a user pastes the composite form back in.
+ *
+ * Shared because the write commands re-pin metadata from whatever this returns: a miss means
+ * they rebuild the doc from defaults and the full-overwrite write erases the task's real
+ * name/description/location/dueDate.
+ */
+function findSubgraphTask(projects, taskId) {
+    for (const project of projects || []) {
+        for (const task of project.tasks || []) {
+            if (task.taskId === taskId || task.id?.endsWith(`-${taskId}`))
+                return task;
+        }
+    }
+    return null;
+}
+// ────────────────────── task stats ──────────────────────
+/** Port of the inline document at src/commands/task/stats.ts:12. */
+exports.FETCH_TASK_STATS = `
+  query FetchTaskStats($orgId: Bytes!) {
+    organization(id: $orgId) {
+      users(first: 100) {
+        address
+        participationTokenBalance
+        membershipStatus
+        totalTasksCompleted
+        totalTasksReleased
+        totalTasksLostToExpiry
+        account { username }
+      }
+      taskManager {
+        projects(where: { deleted: false }, first: 100) {
+          title
+          tasks(first: 1000) {
+            taskId
+            title
+            status
+            payout
+            assignee
+            assigneeUsername
+            completer
+            completerUsername
+            createdAt
+          }
+        }
+      }
+    }
+  }
+`;
+/**
+ * FETCH_TASK_STATS without the claim-churn counters (subgraph #201, TaskManager v7).
+ *
+ * The two counters are asymmetric: `totalTasksLostToExpiry` is live on Arbitrum too, but
+ * `totalTasksReleased` is Gnosis-only as of 2026-08-02 (verified: poa-arb-v-1 answers
+ * ``Type `User` has no field `totalTasksReleased```, which `isUnknownFieldError` matches).
+ * A document validates as a whole, so they have to share tier 0 — asking for the portable
+ * one alongside the Gnosis-only one costs nothing, since the whole query would fail anyway.
+ * Derived by deletion so the two tiers cannot drift apart.
+ */
+exports.FETCH_TASK_STATS_LEGACY = exports.FETCH_TASK_STATS
+    .split('\n')
+    .filter((line) => !/^\s*(totalTasksReleased|totalTasksLostToExpiry)\s*$/.test(line))
+    .join('\n');
+/**
+ * Raw per-member + per-project task analytics inputs.
+ * Port of the read at src/commands/task/stats.ts:62 (aggregation stays host-side).
+ */
+async function fetchTaskStats(client, orgId, chainId) {
+    const { data, tierIndex } = await client.queryWithFieldFallback([
+        { query: exports.FETCH_TASK_STATS, variables: { orgId } },
+        { query: exports.FETCH_TASK_STATS_LEGACY, variables: { orgId } },
+    ], { chainId });
+    return { data, tierIndex, hasChurnCounters: tierIndex === 0 };
+}
+// ────────────────────── permission masks ──────────────────────
+/**
+ * Tier 0: deployed v4 schema — GlobalRolePermission masks, organizerHatIds,
+ * per-project ProjectRolePermission masks.
+ * Port of PERMS_QUERY_FULL at src/commands/task/perms.ts:55. Masks are
+ * subgraph-only: they are NOT readable per-wearer on-chain.
+ */
+exports.PERMS_QUERY_FULL = `
+  query TaskPermsFull($orgId: Bytes!) {
+    organization(id: $orgId) {
+      id
+      taskManager {
+        id
+        creatorHatIds
+        organizerHatIds
+        globalRolePermissions { hatId mask }
+        projects(where: { deleted: false }, first: 50) {
+          id
+          title
+          rolePermissions { hatId mask }
+        }
+      }
+    }
+  }
+`;
+/** Tier 1: older schema — no global perms/organizer hats; boolean per-project flags. */
+exports.PERMS_QUERY_LEGACY = `
+  query TaskPermsLegacy($orgId: Bytes!) {
+    organization(id: $orgId) {
+      id
+      taskManager {
+        id
+        creatorHatIds
+        projects(where: { deleted: false }, first: 50) {
+          id
+          title
+          rolePermissions { hatId canCreate canClaim canReview canAssign }
+        }
+      }
+    }
+  }
+`;
+/** Tier array for `queryWithFieldFallback`, matching the CLI's order. */
+function taskPermsTiers(orgId) {
+    return [
+        { query: exports.PERMS_QUERY_FULL, variables: { orgId } },
+        { query: exports.PERMS_QUERY_LEGACY, variables: { orgId } },
+    ];
+}
+/**
+ * Global + per-project permission masks. Port of the read at
+ * src/commands/task/perms.ts:175 (`pop task perms show`).
+ */
+async function fetchTaskPerms(client, orgId, chainId) {
+    return client.queryWithFieldFallback(taskPermsTiers(orgId), { chainId });
+}
+/**
+ * Rebuild a mask from tier-1 boolean flags (partial: only bits 1..8 indexable).
+ * Port of src/commands/task/perms.ts maskFromBooleans.
+ */
+function maskFromBooleans(rp) {
+    let mask = 0;
+    if (rp.canCreate)
+        mask |= perms_1.PERM_BITS.create;
+    if (rp.canClaim)
+        mask |= perms_1.PERM_BITS.claim;
+    if (rp.canReview)
+        mask |= perms_1.PERM_BITS.review;
+    if (rp.canAssign)
+        mask |= perms_1.PERM_BITS.assign;
+    return mask;
+}
+/**
+ * Resolve --project-style input (bytes32 hex, subgraph composite ID, or title)
+ * to the on-chain bytes32 pid using an already-fetched projects list.
+ * Port of src/commands/task/perms.ts resolveProjectFromList (same messages).
+ */
+function resolveProjectFromList(projects, input) {
+    if (input.startsWith('0x') && input.length === 66) {
+        const match = projects.find((p) => (0, encoding_1.parseProjectId)(p.id) === input);
+        return { pid: input, title: match?.title ?? undefined };
+    }
+    const byTitle = projects.find((p) => (p.title || '').toLowerCase() === input.toLowerCase());
+    if (byTitle)
+        return { pid: (0, encoding_1.parseProjectId)(byTitle.id), title: byTitle.title ?? undefined };
+    const available = projects.map((p) => p.title).filter(Boolean).join(', ');
+    throw new errors_1.CliError(`Project "${input}" not found.`, exit_codes_1.EXIT.USAGE, `Available projects: ${available || 'none'} (or pass the 0x-prefixed bytes32 project ID).`);
+}
+// ────────────────────── folders root ──────────────────────
+/**
+ * Tier 0: v4 schema with folders provenance on Organization.
+ * Port of FOLDERS_QUERY_FULL at src/commands/task/folders.ts:54 — foldersRoot
+ * verified populated on live Gnosis (org Test6 = 0x8694f683…).
+ */
+exports.FOLDERS_QUERY_FULL = `
+  query OrgFolders($orgId: Bytes!) {
+    organization(id: $orgId) {
+      id
+      foldersRoot
+      foldersUpdatedAt
+      foldersUpdatedBy
+    }
+  }
+`;
+/** Tier 1: pre-folders schema. */
+exports.FOLDERS_QUERY_LEGACY = `
+  query OrgFoldersLegacy($orgId: Bytes!) {
+    organization(id: $orgId) {
+      id
+    }
+  }
+`;
+/**
+ * The org's indexed folders root + provenance. Port of the read at
+ * src/commands/task/folders.ts:169 (`pop task folders show`).
+ */
+async function fetchOrgFolders(client, orgId, chainId) {
+    const { data, tierIndex } = await client.queryWithFieldFallback([
+        { query: exports.FOLDERS_QUERY_FULL, variables: { orgId } },
+        { query: exports.FOLDERS_QUERY_LEGACY, variables: { orgId } },
+    ], { chainId });
+    return { data, tierIndex, indexedRoot: normalizeRoot(data.organization?.foldersRoot) };
+}
+/**
+ * Normalise a subgraph bytes32 to the 0x-prefixed lowercase form the lens returns.
+ * Port of src/commands/task/folders.ts normalizeRoot.
+ */
+function normalizeRoot(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim().toLowerCase();
+    return ethers_1.ethers.utils.isHexString(trimmed, 32) ? trimmed : null;
+}
+/**
+ * One task's release history (subgraph #201, Gnosis-only today). Port of the
+ * read at src/commands/task/view.ts:277. `taskEntityId` is the Task ENTITY id
+ * — `<lowercased taskManager address>-<numeric task id>`, not the bare number.
+ * The CLI issues this only when the shared projects document already reported
+ * `releaseCount > 0`, keeping the common path at one round-trip.
+ */
+async function fetchTaskReleaseHistory(client, taskEntityId, first = 20, chainId) {
+    const { data, tierIndex } = await client.queryWithFieldFallback([
+        { query: task_1.FETCH_TASK_RELEASE_HISTORY, variables: { taskId: taskEntityId, first } },
+        { query: task_1.FETCH_TASK_RELEASE_HISTORY_LEGACY, variables: { taskId: taskEntityId } },
+    ], { chainId });
+    return { data, tierIndex, hasReleaseHistory: tierIndex === 0 };
+}

package/dist/reads/token.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Participation-token reads — typed wrappers over graph/documents/token.
+ *
+ * Serves the read paths of `pop token balance` (src/commands/token/balance.ts)
+ * and `pop token requests` (src/commands/token/requests.ts), plus the
+ * subgraph half of the token-address resolution in
+ * src/commands/token/helpers.ts.
+ *
+ * NOT ported here (deliberately — see the header of
+ * src/commands/token/helpers.ts): readTokenGates / checkWearsAnyHat /
+ * readTokenRequest. Those are provider-bound revert predictors that MUST stay
+ * on RPC: ParticipationTokenContract.executor/.hatsContract are the zero
+ * address on all live subgraph rows, memberHatIds/approverHatIds are not
+ * indexed at all, and requests(id) is the existence/state gate evaluated
+ * immediately before a write — subgraph lag there means knowingly
+ * broadcasting a doomed transaction.
+ */
+import type { GraphClient } from '../graph/client';
+/**
+ * Resolve an org (name or hex ID) to its ParticipationToken address.
+ * Port of resolveTokenAddress in src/commands/token/helpers.ts — the
+ * subgraph-only half of that file (the hat-gate readers stay in the CLI).
+ */
+export declare function resolveParticipationToken(client: GraphClient, orgIdOrName: string | undefined, chainId?: number): Promise<{
+    orgId: string;
+    tokenAddress: string;
+}>;
+/**
+ * Indexed balance snapshot for one holder.
+ *
+ * `balanceWei === null` means NO INDEXED ROW — not a zero balance. A missing
+ * TokenBalance row and a genuine zero are indistinguishable from the subgraph
+ * alone, so callers that must tell them apart settle it with an on-chain
+ * balanceOf (the CLI keeps that RPC fallback; see `pop token balance`).
+ */
+export interface TokenBalanceSnapshot {
+    tokenAddress: string;
+    /** Indexed ERC20 symbol ('PT', 'KUBIX', ... — populated on every live row), or null when the token contract is not indexed. */
+    symbol: string | null;
+    /** 18-decimal wei balance as a decimal string, or null when no row is indexed for this holder. */
+    balanceWei: string | null;
+    /** Unix seconds of the last indexed balance change, or null when no row. */
+    updatedAt: string | null;
+}
+/**
+ * Subgraph read behind `pop token balance` — src/commands/token/balance.ts.
+ * TokenBalance mirrors ERC20 balanceOf exactly (verified live: the sum of a
+ * token's TokenBalance rows equals its indexed totalSupply).
+ */
+export declare function getTokenBalance(client: GraphClient, tokenAddress: string, holder: string, chainId?: number): Promise<TokenBalanceSnapshot>;
+/**
+ * Raw indexed token-request row. Field availability depends on the query that
+ * served it: the pending query carries `createdAtBlock` but not the
+ * resolution fields; the all/user queries carry
+ * `approvedAt`/`cancelledAt`/`approver` but not `createdAtBlock`; the
+ * user-scoped query omits `requester` (it is the filter). `metadata` is the
+ * indexed {reason, submittedAt} document and may be null when the IPFS
+ * document was not resolvable at indexing time.
+ */
+export interface TokenRequestRow {
+    id: string;
+    requestId: string;
+    requester?: string;
+    /** 18-decimal wei as a decimal string. */
+    amount: string;
+    ipfsHash: string;
+    metadata: {
+        reason: string | null;
+        submittedAt: string | null;
+    } | null;
+    status: string;
+    createdAt: string;
+    createdAtBlock?: string;
+    approvedAt?: string | null;
+    cancelledAt?: string | null;
+    approver?: string | null;
+    transactionHash?: string | null;
+}
+/**
+ * List token requests for a ParticipationToken.
+ * Subgraph read behind `pop token requests` — src/commands/token/requests.ts
+ * (`status: 'pending'` ⇒ FETCH_PENDING_TOKEN_REQUESTS, `'all'` ⇒
+ * FETCH_ALL_TOKEN_REQUESTS; pending is the CLI default).
+ */
+export declare function listTokenRequests(client: GraphClient, tokenAddress: string, opts?: {
+    status?: 'pending' | 'all';
+    chainId?: number;
+}): Promise<TokenRequestRow[]>;
+/**
+ * One requester's token-request history (newest first, max 50) —
+ * FETCH_USER_TOKEN_REQUESTS from graph/documents/token. Rows omit
+ * `requester` (it is the filter variable).
+ */
+export declare function listUserTokenRequests(client: GraphClient, tokenAddress: string, userAddress: string, chainId?: number): Promise<TokenRequestRow[]>;