@poa-box/core 0.1.0

package/dist/tx/zkemail.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ZK Email transaction builders — port of `pop zkemail propose-allowlist`
+ * (src/commands/zkemail/propose-allowlist.ts).
+ *
+ * `ZkEmailInvites.setActiveAllowlist(bytes32 root, bytes32 cidDigest)` is
+ * onlyExecutor, so it cannot be sent directly by a member wallet — it goes
+ * through a HybridVoting proposal whose option 0 executes the call from the
+ * Executor. Same shape as the treasury governance wraps (./governance).
+ *
+ * Allowlist BUILDING is not here: the browser-pure ../zkemail module
+ * (buildAllowlist, treeFromDoc, assertRootMatches, summarize, domainHash,
+ * emailHash) already owns the Poseidon-hashed merkle construction —
+ * `pop zkemail build-allowlist` is that module plus file I/O and an optional
+ * pin, so hosts compose buildAllowlist + pinJson + ipfsCidToBytes32 directly.
+ */
+import { ethers } from 'ethers';
+import type { TxIntent } from './intent';
+import type { PopContext } from '../context';
+/**
+ * Normalize --root to bytes32. A zero root would make the module dormant and
+ * revert every claim, so it is rejected. Port of the guard in
+ * src/commands/zkemail/propose-allowlist.ts.
+ */
+export declare function normalizeAllowlistRoot(root: string): string;
+/**
+ * Normalize --cid to the bytes32 digest the contract stores + the CIDv0 form.
+ *
+ * ipfsCidToBytes32 falls back to keccak256(string) for anything that is
+ * neither a Qm… CIDv0 nor a 0x-bytes32, which yields a non-zero digest that
+ * sails past a HashZero check and commits a dead pointer on-chain. Accept only
+ * the two forms the contract can round-trip. Port of the guard in
+ * src/commands/zkemail/propose-allowlist.ts.
+ */
+export declare function normalizeAllowlistCid(cid: string): {
+    cidDigest: string;
+    cidV0: string | null;
+};
+export interface SetAllowlistProposalArgs {
+    hybridVotingAddress: string;
+    zkEmailInvitesAddress: string;
+    /** Normalized bytes32 (see normalizeAllowlistRoot). */
+    root: string;
+    /** bytes32 multihash digest (see normalizeAllowlistCid). */
+    cidDigest: string;
+    descriptionHash: string;
+    durationMinutes: ethers.BigNumberish;
+    orgId?: string;
+    summary?: Record<string, unknown>;
+    ipfs?: {
+        cid: string;
+        metadata: unknown;
+    };
+}
+/**
+ * Port of `pop zkemail propose-allowlist` —
+ * src/commands/zkemail/propose-allowlist.ts. HybridVoting.createProposal
+ * wrapping [[zkEmailInvites, 0, setActiveAllowlist(root, cidDigest)], []]
+ * (setActiveAllowlist is onlyExecutor).
+ */
+export declare function buildSetAllowlistProposal(a: SetAllowlistProposalArgs): TxIntent;
+export interface ProposeAllowlistParams {
+    org: string;
+    /** Merkle root from build-allowlist (../zkemail buildAllowlist). */
+    root: string;
+    /** IPFS CIDv0 (Qm…) of the pinned allowlist file, or its 0x-bytes32 digest. */
+    cid: string;
+    /** Voting window in minutes (CLI default 1440 = 24h). */
+    durationMinutes?: number;
+    /** Skip fetching the pinned file to confirm it reproduces --root (not recommended). */
+    skipVerify?: boolean;
+}
+/**
+ * Resolved port of `pop zkemail propose-allowlist` —
+ * src/commands/zkemail/propose-allowlist.ts.
+ *
+ * Guards replicated from the CLI:
+ *   - root != HashZero; --cid restricted to CIDv0 or 0x-bytes32 (the keccak
+ *     fallback of ipfsCidToBytes32 would commit a dead pointer)
+ *   - unless skipVerify, the pinned file is fetched and assertRootMatches
+ *     confirms it reproduces the root being committed (a mismatch costs a full
+ *     governance cycle to undo)
+ *   - the CURRENT root (display + metadata) comes from the indexed activeRoot,
+ *     identity-guarded, with merkleRoot() as the on-chain fallback
+ *   - module.executor() vs the org's Executor mismatch fails fast — the
+ *     Unauthorized revert would otherwise only surface AFTER the full vote.
+ *     `executor` deliberately stays on-chain (it gates that check, the one
+ *     place subgraph lag is unacceptable in this command), so the check runs
+ *     only when ctx.provider is supplied.
+ */
+export declare function proposeAllowlistIntent(ctx: PopContext, params: ProposeAllowlistParams): Promise<TxIntent>;

package/dist/tx/zkemail.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * ZK Email transaction builders — port of `pop zkemail propose-allowlist`
+ * (src/commands/zkemail/propose-allowlist.ts).
+ *
+ * `ZkEmailInvites.setActiveAllowlist(bytes32 root, bytes32 cidDigest)` is
+ * onlyExecutor, so it cannot be sent directly by a member wallet — it goes
+ * through a HybridVoting proposal whose option 0 executes the call from the
+ * Executor. Same shape as the treasury governance wraps (./governance).
+ *
+ * Allowlist BUILDING is not here: the browser-pure ../zkemail module
+ * (buildAllowlist, treeFromDoc, assertRootMatches, summarize, domainHash,
+ * emailHash) already owns the Poseidon-hashed merkle construction —
+ * `pop zkemail build-allowlist` is that module plus file I/O and an optional
+ * pin, so hosts compose buildAllowlist + pinJson + ipfsCidToBytes32 directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAllowlistRoot = normalizeAllowlistRoot;
+exports.normalizeAllowlistCid = normalizeAllowlistCid;
+exports.buildSetAllowlistProposal = buildSetAllowlistProposal;
+exports.proposeAllowlistIntent = proposeAllowlistIntent;
+const ethers_1 = require("ethers");
+const contracts_1 = require("../contracts");
+const governance_1 = require("./governance");
+const resolve_1 = require("../reads/resolve");
+const zkemail_1 = require("../reads/zkemail");
+const proposal_1 = require("../metadata/proposal");
+const ipfs_1 = require("../ipfs");
+const encoding_1 = require("../encoding");
+const zkemail_2 = require("../zkemail");
+const errors_1 = require("../errors");
+const exit_codes_1 = require("../exit-codes");
+// ---------------------------------------------------------------------------
+// Pure input normalization (the CLI's guards, verbatim messages)
+// ---------------------------------------------------------------------------
+/**
+ * Normalize --root to bytes32. A zero root would make the module dormant and
+ * revert every claim, so it is rejected. Port of the guard in
+ * src/commands/zkemail/propose-allowlist.ts.
+ */
+function normalizeAllowlistRoot(root) {
+    let normalized;
+    try {
+        normalized = ethers_1.ethers.utils.hexZeroPad(ethers_1.ethers.utils.hexlify(root), 32);
+    }
+    catch {
+        throw new errors_1.CliError(`--root "${root}" is not a valid bytes32.`, exit_codes_1.EXIT.USAGE);
+    }
+    if (normalized === ethers_1.ethers.constants.HashZero) {
+        throw new errors_1.CliError('A zero root would make the module dormant and revert every claim.', exit_codes_1.EXIT.USAGE, 'Pass the root printed by pop zkemail build-allowlist.');
+    }
+    return normalized;
+}
+/**
+ * Normalize --cid to the bytes32 digest the contract stores + the CIDv0 form.
+ *
+ * ipfsCidToBytes32 falls back to keccak256(string) for anything that is
+ * neither a Qm… CIDv0 nor a 0x-bytes32, which yields a non-zero digest that
+ * sails past a HashZero check and commits a dead pointer on-chain. Accept only
+ * the two forms the contract can round-trip. Port of the guard in
+ * src/commands/zkemail/propose-allowlist.ts.
+ */
+function normalizeAllowlistCid(cid) {
+    const isCidV0 = /^Qm[1-9A-HJ-NP-Za-km-z]{44}$/.test(cid);
+    const isBytes32 = /^0x[0-9a-fA-F]{64}$/.test(cid);
+    if (!isCidV0 && !isBytes32) {
+        throw new errors_1.CliError(`--cid "${cid}" is not a CIDv0 (Qm…) or a 0x bytes32 digest.`, exit_codes_1.EXIT.USAGE, cid.startsWith('baf')
+            ? 'That looks like a CIDv1. The contract stores a raw 32-byte multihash digest, so the '
+                + 'file must be pinned as CIDv0 — re-pin with --cid-version=0 (pop pins CIDv0 by default).'
+            : 'Pass the CID printed by pop zkemail build-allowlist --pin.');
+    }
+    const cidDigest = (0, encoding_1.ipfsCidToBytes32)(cid);
+    if (cidDigest === ethers_1.ethers.constants.HashZero) {
+        throw new errors_1.CliError(`--cid "${cid}" did not decode to a valid digest.`, exit_codes_1.EXIT.USAGE);
+    }
+    return { cidDigest, cidV0: isCidV0 ? cid : (0, encoding_1.bytes32ToIpfsCid)(cidDigest) };
+}
+/**
+ * Port of `pop zkemail propose-allowlist` —
+ * src/commands/zkemail/propose-allowlist.ts. HybridVoting.createProposal
+ * wrapping [[zkEmailInvites, 0, setActiveAllowlist(root, cidDigest)], []]
+ * (setActiveAllowlist is onlyExecutor).
+ */
+function buildSetAllowlistProposal(a) {
+    const iface = new ethers_1.ethers.utils.Interface((0, contracts_1.getAbi)('ZkEmailInvites'));
+    const call = iface.encodeFunctionData('setActiveAllowlist', [a.root, a.cidDigest]);
+    const calls = [
+        { target: a.zkEmailInvitesAddress, value: ethers_1.ethers.BigNumber.from(0), calldata: call },
+    ];
+    return (0, governance_1.buildGovernanceProposal)({
+        votingAddress: a.hybridVotingAddress,
+        votingAbiName: 'HybridVotingNew',
+        title: 'Set ZK Email invite allowlist',
+        descriptionHash: a.descriptionHash,
+        durationMinutes: a.durationMinutes,
+        numOptions: 2,
+        batches: [calls, []], // option 0 = set, option 1 = keep current
+        hatIds: [],
+        domain: 'zkemail',
+        action: 'propose-allowlist',
+        orgId: a.orgId,
+        summary: a.summary ?? { module: a.zkEmailInvitesAddress, newRoot: a.root },
+        ipfs: a.ipfs,
+    });
+}
+/**
+ * Resolved port of `pop zkemail propose-allowlist` —
+ * src/commands/zkemail/propose-allowlist.ts.
+ *
+ * Guards replicated from the CLI:
+ *   - root != HashZero; --cid restricted to CIDv0 or 0x-bytes32 (the keccak
+ *     fallback of ipfsCidToBytes32 would commit a dead pointer)
+ *   - unless skipVerify, the pinned file is fetched and assertRootMatches
+ *     confirms it reproduces the root being committed (a mismatch costs a full
+ *     governance cycle to undo)
+ *   - the CURRENT root (display + metadata) comes from the indexed activeRoot,
+ *     identity-guarded, with merkleRoot() as the on-chain fallback
+ *   - module.executor() vs the org's Executor mismatch fails fast — the
+ *     Unauthorized revert would otherwise only surface AFTER the full vote.
+ *     `executor` deliberately stays on-chain (it gates that check, the one
+ *     place subgraph lag is unacceptable in this command), so the check runs
+ *     only when ctx.provider is supplied.
+ */
+async function proposeAllowlistIntent(ctx, params) {
+    const durationMinutes = params.durationMinutes ?? 1440;
+    const modules = await (0, resolve_1.resolveOrgModules)(ctx.client, params.org, ctx.chainId);
+    const orgId = modules.orgId;
+    const moduleAddr = modules.zkEmailInvitesAddress;
+    if (!moduleAddr) {
+        throw new errors_1.CliError(`Org ${orgId} has no ZkEmailInvites module.`, exit_codes_1.EXIT.PRECONDITION, 'ZK Email invites are opt-in per org — the module is wired at deploy time via '
+            + 'OrgDeployer.deployFullOrgWithZkEmail.');
+    }
+    const hybridVotingAddr = modules.hybridVotingAddress;
+    if (!hybridVotingAddr) {
+        throw new errors_1.CliError(`Org "${orgId}" has no HybridVoting module, so an executor-gated call cannot be proposed.`, exit_codes_1.EXIT.PRECONDITION);
+    }
+    // Normalize the root and CID.
+    const root = normalizeAllowlistRoot(params.root);
+    const { cidDigest, cidV0 } = normalizeAllowlistCid(params.cid);
+    // Verify the pinned file actually reproduces the root being committed.
+    let entrySummary = '(not verified)';
+    if (!params.skipVerify) {
+        const doc = await (0, ipfs_1.fetchJson)(cidV0 || params.cid, ctx.ipfs);
+        if (!doc) {
+            throw new errors_1.CliError(`Could not fetch allowlist ${cidV0 || params.cid} from IPFS.`, exit_codes_1.EXIT.INFRA, 'Pin the file before proposing, or pass --skip-verify if you are certain it is retrievable.');
+        }
+        // Mismatch here means --root and --cid disagree; committing them would cost a full
+        // governance cycle to undo, so fail before the proposal exists.
+        (0, zkemail_2.assertRootMatches)(doc, root, 'root you are proposing (--root)');
+        const s = (0, zkemail_2.summarize)(doc);
+        entrySummary = `${doc.entries?.length ?? 0} entries (${s.domains.length} domain, ${s.emails.length} specific)`;
+    }
+    // Read the current commit so the diff is visible in the metadata.
+    //
+    // The root is DISPLAY ONLY (the proposal description), so it comes from the
+    // indexed ZkEmailInvites.activeRoot. A module row that exists with a null
+    // activeRoot is dormant, exactly what merkleRoot() == 0 means on-chain; a
+    // MISSING row means "not indexed yet" and falls back to the contract so a
+    // brand-new module still renders its real root.
+    const indexedRoot = await (0, zkemail_1.fetchIndexedActiveRoot)(ctx.client, orgId, moduleAddr, ctx.chainId);
+    let currentRoot;
+    let moduleExecutor = null;
+    if (ctx.provider) {
+        const readModule = new ethers_1.ethers.Contract(moduleAddr, (0, contracts_1.getAbi)('ZkEmailInvites'), ctx.provider);
+        [currentRoot, moduleExecutor] = await Promise.all([
+            indexedRoot != null ? Promise.resolve(indexedRoot) : readModule.merkleRoot(),
+            readModule.executor(),
+        ]);
+    }
+    else if (indexedRoot != null) {
+        currentRoot = indexedRoot;
+    }
+    else {
+        throw new errors_1.CliError('The module is not indexed yet and no provider was supplied — cannot read the current allowlist root.', exit_codes_1.EXIT.INFRA, 'Pass a provider in the context, or retry once the subgraph has indexed the module.');
+    }
+    // setActiveAllowlist is onlyExecutor, and the proposal executes from the org's Executor.
+    // If the module answers to a different one the call reverts Unauthorized only AFTER the
+    // full voting window — check now, while it is still free.
+    const orgExecutor = modules.executorAddress;
+    if (moduleExecutor && orgExecutor && moduleExecutor.toLowerCase() !== orgExecutor.toLowerCase()) {
+        throw new errors_1.CliError(`The ZkEmailInvites module answers to executor ${moduleExecutor}, but this org's Executor `
+            + `is ${orgExecutor}. A proposal from this org could never execute the call.`, exit_codes_1.EXIT.PRECONDITION, 'The module was deployed against a different executor, or the executor was rotated. '
+            + 'Re-wire the module before proposing.');
+    }
+    const metadata = (0, proposal_1.buildProposalMetadata)({
+        description: `Set the ZK Email invite allowlist to root ${root} (IPFS ${cidV0 ?? params.cid}). `
+            + `${entrySummary}. Replaces ${currentRoot === ethers_1.ethers.constants.HashZero ? 'no active allowlist' : currentRoot}. `
+            + 'Anyone who can prove a DKIM-signed email from an allowlisted domain or address may then claim the listed role hats.',
+        optionNames: ['Set this allowlist', 'Keep the current allowlist'],
+    });
+    const metaCid = await (0, ipfs_1.pinJson)((0, proposal_1.serializeProposalMetadata)(metadata), ctx.ipfs);
+    const descriptionHash = (0, encoding_1.ipfsCidToBytes32)(metaCid);
+    return buildSetAllowlistProposal({
+        hybridVotingAddress: hybridVotingAddr,
+        zkEmailInvitesAddress: moduleAddr,
+        root,
+        cidDigest,
+        descriptionHash,
+        durationMinutes,
+        orgId,
+        summary: {
+            module: moduleAddr,
+            newRoot: root,
+            cid: cidV0 ?? params.cid,
+            currentRoot,
+            allowlist: entrySummary,
+        },
+        ipfs: { cid: metaCid, metadata },
+    });
+}

package/dist/validation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Input Validation
+ */
+export declare function requireArg<T>(value: T | undefined, name: string): T;
+export declare function requireAddress(address: string | undefined, name: string): string;
+export declare function requirePositiveNumber(value: number | string, name: string): number;
+/** Username: 3-32 chars, alphanumeric + underscores only (matches contract/frontend rules) */
+export declare function requireValidUsername(username: string): string;

package/dist/validation.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Input Validation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireArg = requireArg;
+exports.requireAddress = requireAddress;
+exports.requirePositiveNumber = requirePositiveNumber;
+exports.requireValidUsername = requireValidUsername;
+const ethers_1 = require("ethers");
+function requireArg(value, name) {
+    if (value === undefined || value === null || value === '') {
+        throw new Error(`Missing required argument: --${name}`);
+    }
+    return value;
+}
+function requireAddress(address, name) {
+    if (!address || !ethers_1.ethers.utils.isAddress(address)) {
+        throw new Error(`Invalid address for --${name}: ${address}`);
+    }
+    return ethers_1.ethers.utils.getAddress(address);
+}
+function requirePositiveNumber(value, name) {
+    const num = typeof value === 'string' ? parseFloat(value) : value;
+    if (isNaN(num) || num <= 0 || !isFinite(num)) {
+        throw new Error(`--${name} must be a positive finite number, got: ${value}`);
+    }
+    return num;
+}
+/** Username: 3-32 chars, alphanumeric + underscores only (matches contract/frontend rules) */
+function requireValidUsername(username) {
+    if (!username || username.length < 3 || username.length > 32) {
+        throw new Error('Username must be 3-32 characters');
+    }
+    if (!/^[a-zA-Z0-9_]+$/.test(username)) {
+        throw new Error('Username can only contain letters, numbers, and underscores');
+    }
+    return username;
+}

package/dist/version.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Implementation Version Detection
+ * Resolves a proxy's implementation (EIP-1967 beacon / implementation slots,
+ * SwitchableBeacon.implementation()) and probes the implementation bytecode
+ * for feature selectors so commands can degrade gracefully on orgs whose
+ * TaskManager is pinned to an older version.
+ *
+ * Verified against contracts repo origin/main:
+ * - src/SwitchableBeacon.sol — `implementation()` (IBeacon accessor)
+ * - src/TaskManager.sol — createTask (9-arg v6), createTasksBatch(bytes32,
+ *   CreateTaskInput[]), updateTaskMetadata, setFolders signatures and the
+ *   CreateTaskInput struct field order.
+ * - src/TaskManager.sol v7 (contracts PR #187) — unclaimTask(uint256).
+ *
+ * RPC COST (2026-07): this module is on the hot path of task
+ * list/create/create-batch/update/edit-meta/folders, and each call used to cost
+ * eth_getStorageAt + eth_call(implementation) + eth_getCode — the last of which
+ * ships ~20 KB of hex. Both halves now have a cheaper first choice:
+ *
+ *   1. Beacon address — the subgraph knows it (RegisteredContract.beacon).
+ *      Requires the caller to pass `orgId` AND a `client` (the injected
+ *      GraphClient); without either the EIP-1967 slot walk runs exactly as
+ *      before. The implementation is still fetched FROM the beacon over RPC,
+ *      because this function gates writes (see
+ *      beaconImplementationViaSubgraph).
+ *   2. Feature set — memoized per implementation ADDRESS (see
+ *      KNOWN_TM_IMPLEMENTATION_FEATURES). Deployed bytecode at an address is
+ *      immutable, so this is a cache of a fact, not a guess about a version
+ *      string. An unrecognised address falls back to the bytecode scan, so the
+ *      table can only ever remove work — never invent a feature.
+ */
+import { ethers } from 'ethers';
+import type { GraphClient } from './graph/client';
+import type { OrgBeaconSnapshot } from './graph/documents/beacons';
+/** EIP-1967 beacon slot: keccak256('eip1967.proxy.beacon') - 1 */
+export declare const EIP1967_BEACON_SLOT = "0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50";
+/** EIP-1967 implementation slot: keccak256('eip1967.proxy.implementation') - 1 */
+export declare const EIP1967_IMPLEMENTATION_SLOT = "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+export interface TaskManagerFeatures {
+    /** v6 createTask with absoluteDeadline + completionWindow params */
+    deadlines: boolean;
+    /** createTasksBatch(bytes32, CreateTaskInput[]) */
+    batchCreate: boolean;
+    /** updateTaskMetadata(uint256, bytes, bytes32) */
+    editMeta: boolean;
+    /** setFolders(bytes32, bytes32) */
+    folders: boolean;
+    /** pre-v6 7-arg createTask (no deadline params) */
+    legacyCreate7: boolean;
+    /** v7 unclaimTask(uint256) — release a CLAIMED task back to the pool */
+    unclaim: boolean;
+}
+/**
+ * Human-readable fragments whose runtime-computed selectors identify each
+ * feature in implementation bytecode. Signatures verified against contracts
+ * repo origin/main src/TaskManager.sol (CreateTaskInput field order:
+ * payout, title, metadataHash, bountyToken, bountyPayout,
+ * requiresApplication, absoluteDeadline, completionWindow).
+ */
+export declare const TM_FEATURE_FRAGMENTS: Record<keyof TaskManagerFeatures, string>;
+/**
+ * Legacy (pre-v6) TaskManager write fragments, for building a fallback
+ * Interface when the org's implementation predates the deadline fields.
+ */
+export declare const LEGACY_TM_FRAGMENTS: string[];
+/**
+ * Compute the 4-byte selector for a human-readable function fragment at
+ * runtime (never hardcode selector hex — signatures drift, keccak does not).
+ */
+export declare function computeSelector(fragment: string): string;
+/**
+ * Resolve the implementation behind `proxy`:
+ * 1. EIP-1967 beacon slot set → call implementation() on the beacon
+ *    (works for SwitchableBeacon and any IBeacon).
+ * 2. EIP-1967 implementation slot set → that address.
+ * 3. Neither → `proxy` is not a proxy; return it (checksummed) as-is.
+ */
+export declare function getImplementation(provider: ethers.providers.Provider, proxy: string): Promise<string>;
+/** keccak256("TaskManager") — the PoaManager/OrgRegistry module type id. */
+export declare const TASK_MANAGER_TYPE_ID: string;
+/** Run the selector scan over already-fetched implementation bytecode. */
+export declare function featuresFromBytecode(code: string): TaskManagerFeatures;
+/**
+ * Memoized feature scan per TaskManager IMPLEMENTATION ADDRESS (lowercased).
+ *
+ * Deliberately keyed by address, not by version string. A version→feature table
+ * is a guess that fails silently when a release changes shape; deployed
+ * bytecode at an address is immutable, so each row below is a recorded fact.
+ * Every row was produced by running `featuresFromBytecode` against live
+ * eth_getCode on 2026-07-30 (v7 row added 2026-08-02) — on BOTH Gnosis and
+ * Arbitrum, which return byte-identical code at these addresses (deterministic
+ * deploys), so a row is not chain-specific. The version comment is
+ * documentation only; nothing keys off it.
+ *
+ * FAIL CLOSED: an address that is not listed here is scanned over RPC. Adding a
+ * new TaskManager release is optional — omitting it costs one eth_getCode, it
+ * never mis-reports a feature.
+ */
+export declare const KNOWN_TM_IMPLEMENTATION_FEATURES: Record<string, TaskManagerFeatures>;
+export interface DetectFeaturesOptions {
+    /**
+     * Org id. When supplied (together with `client`), the proxy's BEACON address
+     * comes from the subgraph (RegisteredContract.beacon) instead of an EIP-1967
+     * slot read; the implementation is still fetched from that beacon over RPC.
+     * Omit it and behaviour is exactly as before.
+     */
+    orgId?: string;
+    /** Force the pure-RPC path (offline use / tests). */
+    skipSubgraph?: boolean;
+    /**
+     * Injected GraphClient for the beacon-snapshot read. Core never constructs
+     * one itself; without a client the subgraph shortcut is skipped and the
+     * EIP-1967 slot walk runs — identical to skipSubgraph.
+     */
+    client?: GraphClient;
+    /**
+     * Alternative injection: a snapshot fetcher. Takes precedence over `client`.
+     * Hosts that already wrap the snapshot read in their own module (the CLI's
+     * src/queries/beacons, which tests mock) inject that wrapper here so the
+     * seam stays interceptable.
+     */
+    fetchBeaconSnapshot?: (orgId: string, chainId: number) => Promise<OrgBeaconSnapshot>;
+}
+/**
+ * Probe a TaskManager proxy's implementation for feature selectors.
+ *
+ * Resolution order (each step falls back to the next, never guesses):
+ *   implementation: subgraph (needs `opts.orgId` + `opts.client`) → EIP-1967
+ *                   slot walk
+ *   features:       KNOWN_TM_IMPLEMENTATION_FEATURES → eth_getCode scan
+ *
+ * Results are cached per `chainId:proxy` for the process lifetime. Pass
+ * `chainId` if known to skip the getNetwork round-trip.
+ */
+export declare function detectTaskManagerFeatures(provider: ethers.providers.Provider, proxy: string, chainId?: number, opts?: DetectFeaturesOptions): Promise<TaskManagerFeatures>;
+/**
+ * Standard degradation message for commands that hit an org whose
+ * implementation predates a feature.
+ */
+export declare function featureUnavailable(feature: string, needsVersion: string, remedy: string): string;
+/** Test-only: reset the module-level feature cache. */
+export declare function _clearVersionCacheForTest(): void;