@ixo/openhands-sdk 0.0.0-stage → 0.1.0

package/dist/esm/campaign/spot.js

@@ -0,0 +1,167 @@
+import { ACCESS, VOLUME, WASTE, dominantWaste, isAssessment, needsProfessionals, spotPhrase, spotSays, spotTarget, wastesOf } from "./bands.js";
+/**
+ * The standing ask the map is made of — and, by re-export, the bands it is
+ * priced with.
+ *
+ * The tables moved to `bands.ts` when the map route ran out of bytes: a
+ * client that shows a price was carrying this file's criterion prose with
+ * it. Everything is re-exported here, so every existing import keeps
+ * working and only the client surfaces were changed to ask for the
+ * smaller half.
+ */
+export { ACCESS, VOLUME, WASTE, dominantWaste, isAssessment, needsProfessionals, spotPhrase, spotSays, spotTarget, wastesOf };
+/**
+ * The standing ask that the map is made of.
+ *
+ * **One ask, not one per pin** — a pin cannot have its own ask before anybody
+ * knows the mess is there. So this is a single collection with a large quota
+ * that stays open for the campaign, and every approved claim on it is a pin.
+ *
+ * Which is exactly why it declares `publish: "on-approval"`. A claim body is
+ * withheld while its ask is still taking answers, so that answers cannot be
+ * copied — right for a question with one answer, and fatal here, where the
+ * whole output is meant to be looked at. An approved mess report cannot
+ * usefully be copied anyway: `not-already-mapped` refuses the duplicate.
+ */
+export function messTerms(args) {
+    const metres = args.metres ?? 60;
+    return {
+        v: 2,
+        task: "Map a mess. Photograph illegal waste where you find it",
+        deliverable: {
+            type: "mess-report",
+            prompt: "One photograph of the mess, taken from far enough back to show how big it is. The answer states the reported size on its first line."
+        },
+        ...(args.campaign ? { campaign: args.campaign } : {}),
+        publish: "on-approval",
+        criteria: [
+            { id: "c1", kind: "measure", gate: { id: "located" } },
+            { id: "c2", kind: "measure", gate: { id: "not-already-mapped", metres } },
+            /*
+             * **A rule that does not say what fails it is read as a demand for
+             * proof.** This said what counted and then what did not, and left the
+             * model to infer the refusal — inside a wrapper that ends "if a rule
+             * requires something and you cannot find it, that rule FAILS". So it
+             * now states its own failure condition in as many words, which is the
+             * shape every judged sentence in this package was changed to after ask
+             * 43910 refused six of six real claims.
+             */
+            {
+                id: "c3",
+                kind: "judge",
+                text: "The photograph shows waste dumped or abandoned where it does not belong. Waste that is properly contained does not count: a bin in use, a skip in service, a building site in operation. Fail this if no discarded waste is visible, or everything visible is properly contained.",
+                confidence: 0.6
+            },
+            /*
+             * **It has to say where the claim is, or the judge is guessing.**
+             *
+             * This read "the photograph supports the reported amount of waste" and
+             * the judge was never shown the reported amount — the terms are frozen at
+             * posting and the estimate arrives with each submission. On the first
+             * live run it passed a single paint bucket as "a car boot", which is not
+             * a lenient judge, it is a judge with nothing to compare against. One of
+             * the three defences against an inflated estimate was doing nothing.
+             *
+             * So the submission states its own claim in its first line — see the
+             * deliverable prompt — and this criterion points at it.
+             *
+             * **And then it over-corrected.** "Fail it if the photograph shows
+             * conspicuously less than claimed" is a judgement of degree, and the
+             * oracle's wrapper reads one of those as "prove the amount": a real
+             * pile of bags photographed from six feet away was refused as not
+             * demonstrably a car boot. Two clauses fixed that in replay and both
+             * are load-bearing — a bagful is the floor, so any genuine pile clears
+             * the smallest band; and the amount is what the waste comes to gathered
+             * up, not how far it is spread, which is what a wide shot of a thin
+             * scatter was being failed for.
+             *
+             * **And the scatter clause did not land.** Of 19 real claims on testnet
+             * ask 43943, 11 were rejected and 6 of those on this criterion — the
+             * largest single cause. Four of the six refuse in the same words:
+             * "small, spread-out amount", "scattered litter between the posts",
+             * "scattered pieces spread through the grass". The sentence already told
+             * the judge to count what it gathers up rather than the ground it
+             * covers, and the judge went on failing thin scatters anyway. Implying
+             * it was not enough, so this says it outright: scattered litter counts.
+             *
+             * **One band of tolerance, deliberately.** A band is what a person can
+             * eyeball — bands.ts says as much, that somebody sees "about a car boot"
+             * and cannot see 0.5 m3 — so failing a claim for being one band out
+             * punishes honest imprecision rather than a false claim. It was a coin
+             * flip at the boundary too: the same photograph with the same sentence
+             * and the same band scored 94 and passed, then 88 and failed, twenty
+             * minutes apart. The chain allows one evaluation per claim, so that
+             * rejection is permanent and there is no appeal. Two bands short is
+             * still refused, which is what catches a bagful called a truck.
+             *
+             * The price of the tolerance is that a band claimed one high now passes,
+             * and the band sets the cleanup pool's target — so over-claiming costs
+             * money rather than being caught here. Replayed against all 19 claims
+             * before it shipped: the six wrongly rejected pass, the thirteen already
+             * approved still pass, and both fraud controls — the smallest litter
+             * photographed and claimed as a truck — still fail.
+             */
+            {
+                id: "c4",
+                kind: "judge",
+                text: "The size on the answer's first line is a rough band a person eyeballed, not a measurement: bagful, car boot, trailer, truck. Judge what the waste would fill once gathered and bagged, not the ground it lies on — scattered litter counts. Fail only if the photograph is two or more bands short.",
+                confidence: 0.55
+            },
+            /*
+             * **There is no c5, and the gap is the point: it asked about a flag the
+             * judge cannot see.**
+             *
+             * It read "the answer's hazard flag matches the photograph". A judge is
+             * sent three things — the ask's `task`, the deliverable text and the
+             * photograph (`JUDGE_SEND_KEYS.photo` in `bridge.ts`) — and the hazard
+             * flag is none of them. The finder's tap travels as a top-level
+             * envelope field (`hazard: true`, see `submitSpot`), the claim form
+             * declares no `hazard` question for a rule to read, and so nothing maps
+             * it onto the wire. The model said exactly that, verbatim, in four of
+             * the six claims ask 43910 refused: "No hazard flag is provided in the
+             * inputs." A rule whose subject is missing FAILS under the oracle's
+             * wrapper, so this criterion could only ever reject — including the one
+             * claim of the six that was otherwise perfect.
+             *
+             * Deleting it costs the safety path nothing. The flag was never routed
+             * by this judge: the fold reads the envelope field directly (`pin.hazard`
+             * in `campaign/spots.ts`) and sends the pin to professionals with
+             * no crowd ever offered it, and a second person can abort on site
+             * through the field-report ask. What is gone is only the check on
+             * whether the flag was honest, and that was buying rejections rather
+             * than safety.
+             *
+             * **To bring it back**, three things have to land together, in this
+             * order: a `hazard` question in `claimForm.ts` (which is a new form
+             * name and a new entity — see the note there on form drift), the
+             * submitters writing the envelope field into it, and `hazard` added to
+             * the `photo` row of `JUDGE_SEND_KEYS`. Any two of the three still
+             * gives a judge a rule it cannot see.
+             */
+            /*
+             * **An approved photograph renders publicly, by itself.**
+             *
+             * `publish: "on-approval"` is what makes the map possible and it means
+             * nobody reviews a picture before strangers see it. A photograph can
+             * pass every waste test and still carry a face, a licence plate or
+             * somebody's front window — which is a different harm from a bad pin
+             * and needs its own refusal. Its confidence is the highest here because
+             * this is the one rule that passes when the judge believes there is
+             * nothing wrong: doubt has to fall to a person, not to a stranger whose
+             * face is about to be published.
+             *
+             * It says who does NOT count as identifiable because it was reading a
+             * blurred figure at the end of a street as a face and refusing the
+             * photograph: outdoors, in one shot, somebody is nearly always in frame.
+             */
+            {
+                id: "c6",
+                kind: "judge",
+                text: "This photograph can be published as it stands: nobody in it is identifiable and no vehicle registration is legible. People who are distant, blurred, turned away or only partly in frame are not identifiable. Fail this only if a recognisable face or a readable number plate is visible.",
+                confidence: 0.75
+            }
+        ],
+        judge: { kind: "oracle", address: args.judge.address, rewardUixo: args.judge.rewardUixo }
+    };
+}
+//# sourceMappingURL=spot.js.map

package/dist/esm/campaign/spot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spot.js","sourceRoot":"","sources":["../../../src/campaign/spot.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAyD,MAAM,YAAY,CAAC;AAEvM;;;;;;;;;GASG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;AAG9H;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,IAKzB;IACC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;IAEjC,OAAO;QACL,CAAC,EAAE,CAAC;QACJ,IAAI,EAAE,wDAAwD;QAC9D,WAAW,EAAE;YACX,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,sIAAsI;SAC/I;QACD,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,OAAO,EAAE,aAAa;QACtB,QAAQ,EAAE;YACR,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE;YACtD,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,oBAAoB,EAAE,MAAM,EAAE,EAAE;YACzE;;;;;;;;eAQG;YACH;gBACE,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,mRAAmR;gBACzR,UAAU,EAAE,GAAG;aAChB;YACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAgDG;YACH;gBACE,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,qSAAqS;gBAC3S,UAAU,EAAE,IAAI;aACjB;YACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eA8BG;YACH;;;;;;;;;;;;;;;eAeG;YACH;gBACE,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,6RAA6R;gBACnS,UAAU,EAAE,IAAI;aACjB;SACF;QACD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE;KAC1F,CAAC;AACJ,CAAC"}

package/dist/esm/campaign/spots.d.ts

@@ -0,0 +1,437 @@
+/**
+ * Every mess anybody has mapped, read straight off the chain.
+ *
+ * **There is no database here, and that is the point.** A pin is an approved
+ * claim on the standing mapping ask; its photograph is a content-addressed file
+ * anyone can fetch; its price comes from three bands the finder chose. Nothing
+ * in the map is a fact this server owns, so nothing in the map dies with this
+ * server — which is the whole argument, given that the last global effort to
+ * map waste took its hundreds of thousands of points down with a DNS record.
+ *
+ * The claim bodies are readable while the ask is still open because the terms
+ * say `publish: "on-approval"`. See `AskTerms.publish` for why that is safe
+ * here and nowhere else.
+ */
+/**
+ * What has happened to a pin, folded from the chain and nothing else.
+ *
+ * The states are ordered by finality: a spot somebody has reported gone is
+ * gone whatever else was said about it, and one flagged hazardous goes to
+ * professionals however much money was pledged. Deriving this from receipts
+ * rather than from a ledger is what keeps the map a public record — a
+ * campaign cannot quietly drop the spots that went badly, because it does not
+ * own the list.
+ */
+/**
+ * What became of a pin.
+ *
+ * **`open` replaced `mapped` and `funded` together**, and the disappearance
+ * of that pair is the whole cleanup rethink in one line. A pin used to wait
+ * for its price to be met — `mapped` while it waited, `funded` once enough
+ * money had arrived to post an ask at a number somebody guessed. There is no
+ * number now: an approved mess is an ask straight away, its pool starts at
+ * nothing, and whoever cleans it takes whatever is in the pot. So a pin is
+ * simply open, with or without money in it, and the money is a separate fact
+ * the sheet shows rather than a gate the pin has to pass.
+ */
+/**
+ * `expired`: its ask ran its days and nobody cleared it. Nothing can be filed
+ * against it any more, its pool is on its way back to whoever funded it, and
+ * the one thing left to do about the mess — if it is still there — is to map
+ * it again, which posts a fresh ask with a fresh pot.
+ */
+export type PinState = "open" | "cleaning" | "cleaned" | "expired" | "gone" | "professionals";
+/**
+ * A pin somebody can put their hands to right now.
+ *
+ * **Not a question about money.** Under the pool rule every approved pin gets
+ * its cleanup ask from the campaign's own legs on the next pass, and whoever
+ * cleans it is paid whatever has arrived in the pot by then — so a mess with
+ * an empty pot is still a mess you can go and clear. The map's banner was
+ * left counting funded pins when that changed, and read "0 ready to clean"
+ * over a map full of them (2026-09-16).
+ *
+ * The ask does have to exist: the few minutes between a pin's approval and
+ * the next pool pass is a mess with nothing yet to answer.
+ */
+export { cleanable } from "./cleanable.ts";
+export interface Pin {
+    claimId: string;
+    lat: number;
+    lon: number;
+    /** How the position was known. Shown, never quietly upgraded. */
+    source: "photo" | "reported";
+    /** Small enough to draw two hundred of; the photograph is the other one. */
+    thumb: string | null;
+    photo: string | null;
+    /**
+     * The mapping photograph's own content address.
+     *
+     * `photo` is a URL for a screen; this is the CID for an envelope. A cleanup
+     * with no before photograph of its own sends the mapping photograph as
+     * the before, declared as such, and a claim names photographs by CID.
+     */
+    photoCid?: string | null;
+    /**
+     * The thumbnail's address, for the same reason `photoCid` is kept: `thumb`
+     * and `photo` are PATHS, and a path belongs to the app that built it (see
+     * `inThisApp`). An address is the same in every app.
+     */
+    thumbCid?: string | null;
+    /**
+     * Who has promised to come and clean this, and until when.
+     *
+     * A count and a few names, never a list of people: the crew line says
+     * "Žan and two others are coming", which is what a person scanning a map
+     * can use, and the addresses stay where they belong. Only promises still
+     * standing are counted — a crew is who is coming, not who once said so.
+     */
+    crew?: {
+        count: number;
+        names: string[];
+    };
+    /**
+     * The three bands the finder chose, as they chose them.
+     *
+     * `wastes` is every kind they saw, when they said more than one
+     * (IXO-4928); `waste` is the dominant one and is always present, so
+     * everything written before this round still reads.
+     */
+    assessment: {
+        volume: string;
+        waste: string;
+        wastes?: string[];
+        access: string;
+    } | null;
+    /**
+     * The finder said this is dangerous and should not be approached.
+     *
+     * A flag on the report rather than a separate ask: the person is standing in
+     * front of it, and asking them to file a different kind of claim to say
+     * "don't come here" is asking them to do paperwork about a hazard. The fold
+     * routes a flagged pin to `professionals` and no crowd is ever offered it.
+     */
+    hazard?: boolean;
+    /**
+     * How long the finder asked the cleanup ask to stand, in days — only when
+     * they chose. The campaign's rule carries the default and the set they
+     * could choose from; the worker holds their pick to that set when it
+     * posts, so this is a wish the rule may refuse, never an instruction.
+     */
+    days?: number;
+    /** What the finder called themselves, if anything. */
+    alias: string | null;
+    /**
+     * What the finder called this place — "Prešernov trg, Ljubljana".
+     *
+     * A name, not coordinates. Every surface that talks about a spot needs one:
+     * a cleanup ask is named for the mess and its place, a share card has to say
+     * where, and "46.3881, 14.1660" is a machine's memo. Null on any pin mapped
+     * before the snap flow started asking.
+     */
+    place: string | null;
+    /**
+     * The country the finder was standing in, as a two-letter code — what the
+     * place lookup already knew at mapping time and used to be thrown away.
+     * A sponsor with a budget for one country filters on it; a pin mapped
+     * before this was recorded simply has none.
+     */
+    country?: string;
+    mappedAt: string | null;
+    words: string | null;
+    /** Absent on a single-ask read; set by `loadCampaignPins`. */
+    state?: PinState;
+    /** The cleanup ask that cleared, or is clearing, this pin. */
+    cleanupId?: string | null;
+    /** That ask's admin account: the pool anybody may pay into. */
+    poolAddress?: string | null;
+    /** What a cleaner would be paid right now, base units. */
+    poolBase?: number;
+    /** Too much for one person: its ask takes patches from many. */
+    big?: boolean;
+    /** Patches held on a site, waiting for somebody to show the whole area clear. */
+    patches?: {
+        count: number;
+        people: number;
+    };
+    /**
+     * How many patches this site's ask can hold — its quota on the chain.
+     *
+     * The number a person standing in front of a truckload wants: how many of
+     * us does this take? It is also what the campaign pre-paid in checker
+     * legs, so it starts small and the pool pass raises it as people turn up
+     * — which is why the sheet says "up to", not "exactly".
+     */
+    patchesMax?: number;
+    /** When the cleanup was approved — the start of this place's cool-down. */
+    cleanedAt?: string | null;
+    /**
+     * When this spot's cleanup ask stops taking answers.
+     *
+     * The one date a funded pin actually has, and the only honest thing to put
+     * in somebody's calendar: after it, nobody can earn this cleanup.
+     */
+    endsAt?: string | null;
+    /** How backed this spot is by the funding round's own arithmetic — attached
+     *  by a reader that draws it, never by this loader. This app's campaign map
+     *  was that reader; it is retired (IXO-5270). */
+    backing?: {
+        raisedBase: number;
+        targetBase: number;
+    };
+}
+interface Body {
+    location?: {
+        lat?: number;
+        lon?: number;
+        source?: string;
+    } | null;
+    file?: string;
+    thumb?: string;
+    alias?: string;
+    place?: string;
+    country?: string;
+    deliverable?: string;
+    assessment?: {
+        volume?: string;
+        waste?: string;
+        wastes?: string[];
+        access?: string;
+    };
+    hazard?: boolean;
+    days?: number;
+}
+/** How many claim bodies one load reads itself when the worker has read the rest (fold.ts `readCampaignPins`). */
+export declare const FRESH_BODY_READS = 60;
+/**
+ * A pin's coordinates come from the claim body, not from the terms.
+ *
+ * Everywhere else in this estate the poster names the place and the worker
+ * proves they were near it. Here finding the place *is* the work, so the
+ * coordinates arrive inside the submission — which also means a body that
+ * cannot be read is a pin that cannot be drawn, rather than a pin drawn in the
+ * wrong spot. Dropped, quietly and on purpose.
+ */
+export declare function pinOf(claimId: string, at: string | null, body: Body): Pin | null;
+/**
+ * The map's whole data source.
+ *
+ * One GraphQL read for the approved claims, then their bodies in parallel —
+ * the bodies are immutable and content-addressed, so they cache for as long as
+ * anyone likes. A body that will not load costs one pin, never the page.
+ */
+export declare function loadPins(collectionId: string, limit?: number): Promise<Pin[]>;
+interface Collection {
+    id: string;
+    state: number;
+    endDate: string | null;
+    entity: string;
+    /** The ask's admin account — for a cleanup, this is its pool. */
+    admin?: string | null;
+    quota?: number | null;
+    /** Claims already decided. A pool holds back the legs of the rest. */
+    evaluated?: number | null;
+    /** The legs this ask actually posted with — never assumed from a constant. */
+    payments?: Record<string, {
+        amount?: {
+            denom: string;
+            amount: string;
+        }[] | null;
+    } | null> | null;
+    claimsByCollectionId: {
+        nodes: {
+            claimId: string;
+            submissionDate: string | null;
+            agentAddress?: string | null;
+            evaluationByClaimId: {
+                status: number | null;
+                evaluationDate?: string | null;
+            } | null;
+        }[];
+    };
+}
+/** The published terms of an ask, read from its entity. Cached per call.
+    Exported for the board, which reads campaigns off the same documents. */
+/**
+ * What a terms cache holds: the read itself, so two folds asking about the
+ * same entity at the same moment share one round trip instead of racing to
+ * make two. A settled value is accepted too, for callers that seed one.
+ */
+export type TermsCache = Map<string, Promise<Record<string, unknown> | null> | Record<string, unknown> | null>;
+export declare function termsOf(entityDid: string, cache: TermsCache): Promise<Record<string, unknown> | null>;
+/**
+ * Every pin in a campaign, with what became of it.
+ *
+ * One scan of the collections in the window, split by what each ask is for:
+ * mapping asks give the pins, cleanup asks say which pin they clear, field
+ * reports say what somebody found standing there. Nothing here reads a
+ * ledger; a spot's whole life is public or it is not true.
+ */
+/**
+ * A campaign's collections, split by what each ask is for.
+ *
+ * One walk, three buckets: the mapping asks that give the pins, the cleanup
+ * asks that say which pin they clear, and the field reports that say what
+ * somebody found standing there. Both the map fold and the confirmation count
+ * read it, so they can never disagree about what belongs to this campaign.
+ *
+ * **A campaign that runs all year outlives one page of results.** This used to
+ * take the newest 400 collections in a fixed 90-day window and stop — every
+ * collection there is on a three-day rehearsal, and a map that silently
+ * forgets its oldest pins on day 91 otherwise. Those are exactly the spots a
+ * down-band clock exists to rescue.
+ *
+ * So it pages, and the window becomes the campaign's own life:
+ * `NEXT_PUBLIC_CAMPAIGN_SINCE` is its start date, set once. Without it the old
+ * ninety-day default stands, because the alternative is walking every
+ * collection the chain has ever held — measured, not feared: no filter at all
+ * turned this into a five-thousand-collection scan taking three minutes, since
+ * each one costs a terms fetch to find out it belongs to somebody else. With
+ * the campaign's own window it is under two seconds.
+ */
+export interface CampaignCollections {
+    mapping: Collection[];
+    cleanups: {
+        node: Collection;
+        clears: string;
+        open: boolean;
+    }[];
+    reports: Collection[];
+    /** Promises to come and clean. Unjudged by design — see `commit.ts`. */
+    commitments: Collection[];
+}
+export declare const campaignWalkTtlMs: () => number;
+/** `configure({ campaignSince })`, else `NEXT_PUBLIC_CAMPAIGN_SINCE`, else undefined (the walk then reads 90 days back). */
+export declare const campaignSince: () => string | undefined;
+/** `configure({ campaignReadBudgetMs })`, else `CAMPAIGN_READ_BUDGET_MS`, else 20000. */
+export declare const campaignReadBudgetMs: () => number;
+/**
+ * A read of the campaign that stopped before it had seen everything.
+ *
+ * The walk has a budget, and it used to return whatever it had when the
+ * budget ran out — including nothing at all, which every caller then treated
+ * as "this campaign has no pins" and cached. Running out of time is not an
+ * answer about the campaign. It is thrown, with what was found so far, and
+ * `campaignCollections` decides: the last complete read if there is one, the
+ * partial one if it found anything, and otherwise the failure it is.
+ */
+export declare class CampaignReadIncomplete extends Error {
+    readonly partial: CampaignCollections;
+    constructor(partial: CampaignCollections, why: string);
+}
+/** Throws when the walk was cut short; returns the read otherwise. Pure, so the rule can be tested without an index. */
+export declare function completeOrThrow(out: CampaignCollections, cut: {
+    pagesCutShort: boolean;
+    unread: number;
+    seen: number;
+}): CampaignCollections;
+/** What a read that failed is answered with. Exported for the test; `campaignCollections` is its only caller. */
+export declare function afterFailedRead(campaign: string, error: unknown): CampaignCollections;
+/** For tests: forget every read this process has kept. */
+export declare function forgetCampaignReads(): void;
+export declare function campaignCollections(campaign: string, options?: {
+    since?: string;
+    limit?: number;
+    budgetMs?: number;
+}): Promise<CampaignCollections>;
+/**
+ * Every pin in a campaign, with what became of it.
+ *
+ * Nothing here reads a ledger; a spot's whole life is public or it is not
+ * true.
+ */
+/**
+ * A pin the worker read, with its photographs addressed for THIS app.
+ *
+ * `thumb` and `photo` are same-origin paths (`docPath`), and `docPath` carries
+ * the base path of whoever runs it: `/cleanup/api/doc/<cid>` in the youth app,
+ * `/api/doc/<cid>` in the main one. While each app projected its own pins that
+ * was invisible. The worker projects them once for both, and it has no base
+ * path — so the youth app served the worker's `/api/doc/<cid>`, which is a 404
+ * under `/cleanup`, and every pin on the production map lost its photograph
+ * (2026-09-20, the morning the campaign became rows).
+ *
+ * A path is the reading app's to build, so it is rebuilt here from the
+ * address: the one the pin carries when it has it, else the last segment of
+ * whatever path was stored, under whatever prefix. Anything that is not one
+ * of our document paths — an absolute URL, a shape from some later release —
+ * is left exactly as it was. Returns a copy: the state a load writes onto a
+ * pin must never reach the set that is kept between loads.
+ */
+export declare function inThisApp(pin: Pin): Pin;
+export declare function loadCampaignPins(campaign: string, options?: {
+    since?: string;
+    limit?: number;
+}): Promise<Pin[]>;
+/**
+ * What is in each open pin's pot, read from the chain in one go.
+ *
+ * A balance per pin would be one request each and a map draws two hundred;
+ * the distinct pool addresses are asked for together instead. A pool that
+ * cannot be read is left undefined rather than shown as zero — "nothing in
+ * the pot" and "we could not look" are different sentences, and only one of
+ * them should discourage a backer.
+ */
+export declare const POOL_TTL_MS = 60000;
+export declare const POOL_READS_PER_LOAD = 300;
+/**
+ * Which pots this load reads: the ones never read, then the stalest, never
+ * more than the cap — and among equals, the newest ask first. Pure, so the
+ * rule can be tested without a chain.
+ */
+export declare function poolsToRead(live: {
+    address: string;
+    askId: number;
+}[], memo: ReadonlyMap<string, {
+    at: number;
+    base: number;
+}>, now: number, cap?: number, ttlMs?: number): string[];
+/**
+ * How many people have stood at each pin and said it is really there.
+ *
+ * The count that lets a truck-sized spot take somebody's money: sponsor funds
+ * never escrow against one person's say-so. It reads the campaign's own field
+ * reports — the same standing ask the "it's gone" tap writes to — and not, as
+ * it once did, the newest two hundred claims on the entire chain regardless of
+ * who filed them or what they were about.
+ *
+ * Every pin at once, from one walk. A funding round asks this about each spot
+ * it is considering, and the older shape answered by re-walking the campaign
+ * every time — forty spots, forty scans, each one a window's worth of terms
+ * fetches.
+ */
+export declare function confirmationsIn(campaign: string, options?: {
+    since?: string;
+    limit?: number;
+}): Promise<Map<string, number>>;
+/** The same question about one pin. Prefer `confirmationsIn` in a loop. */
+export declare function confirmationsFor(campaign: string, claimId: string, options?: {
+    since?: string;
+    limit?: number;
+}): Promise<number>;
+/**
+ * The campaign's standing mapping ask, if it has one open.
+ *
+ * One campaign, one mapping ask — the novelty gate refuses duplicates within
+ * one ask, so a second would let the same mess be mapped twice for two fees.
+ */
+/**
+ * The campaign's open ask of a given kind, found rather than configured.
+ *
+ * `NEXT_PUBLIC_MESS_ASK` names one collection, is build-inlined, and therefore
+ * turns "the mapping ask filled up, post another" into a redeploy nobody can
+ * do from a phone. A campaign that runs all year will do that several times,
+ * and will also want a standing field-report ask and a commitment ask that
+ * nobody wants to name in three environments each.
+ *
+ * So: ask the campaign what it has open. The env var still wins where it is
+ * set, because pinning one collection is exactly right during a rehearsal.
+ */
+export declare function openAskOfType(campaign: string, type: string, options?: {
+    since?: string;
+}): Promise<string | null>;
+/** The campaign's open mapping ask — the one the map is made of. */
+export declare const openMappingAsk: (campaign: string, options?: {
+    since?: string;
+}) => Promise<string | null>;
+//# sourceMappingURL=spots.d.ts.map

package/dist/esm/campaign/spots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spots.d.ts","sourceRoot":"","sources":["../../../src/campaign/spots.ts"],"names":[],"mappings":"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"}