@ixo/openhands-sdk 0.0.0-stage → 0.2.0

package/dist/esm/geo/mentions.js

@@ -0,0 +1,190 @@
+import { searchPlaces } from "./search.js";
+/**
+ * Where a sentence says the work happens.
+ *
+ * Two asks were posted on 2026-10-06 that named a place and carried no
+ * geofence: "take a photo of the notice board in ljubljana, prešeren square"
+ * and "…the village noticeboard in Smokuč Slovenia". The cards said "From
+ * anywhere", truthfully, and the checker could not tell Smokuč from anywhere
+ * else. Peter's rule after it: **if an ask describes a place, a geofence is
+ * needed.** This is how the composer and the MCP find out that it does.
+ *
+ * Reading comes first and costs nothing: the phrase after *in, at, near,
+ * outside…*, kept only if it holds a word that names something rather than
+ * describing it ("Prešeren", "Smokuč", "Trubarjeva" — never "the park",
+ * "the morning", "good light"). A phrase that also holds a place noun
+ * ("square", "trg", "cesta", "street") is named on its face; that is how
+ * "prešeren square" counts, which the geocoder does not know by its English
+ * name. Anything else is asked of the map, at most twice per sentence, and
+ * counts only when the map answers with somewhere called by that word.
+ *
+ * It errs towards asking for a place. A false "this names a place" costs a
+ * poster one tap on a sheet or a reworded sentence; a missed one costs an ask
+ * whose location nobody can check.
+ */
+/** The words that put a place after them. Longest first, so "in front of" is read before "in". */
+const BEFORE = ["in front of", "next to", "outside", "opposite", "beside", "behind", "inside", "around", "along", "across", "near", "in", "at", "on", "by"];
+/**
+ * Words that end a place phrase: a new clause, a purpose, a time. Any word in
+ * `BEFORE` ends it too, and starts the next one. "to" and "from" end a phrase
+ * but never start one: "to check if…" would otherwise ask the map about a
+ * town called Check.
+ */
+const ENDS = new Set("and then to so with where which that who whose showing show for before after when if while from about because but or every each between during until within including plus how what whether as like it its is are was were be been has have had please can could should would will must may might do does did not no take make get go see check count find photograph photo picture snap shoot".split(" "));
+/** Words a place phrase may start with that are not part of the name. */
+const LEADING = new Set("the a an this that these those my your our their his her its some any one of".split(" "));
+/** Nouns that make a phrase a place on their own, beside a word that names it. */
+const PLACE_NOUNS = new Set("square sq trg plaza platz piazza street st cesta ulica ul road rd avenue ave lane boulevard blvd park garden gardens station church cathedral chapel bridge most beach market trznica village vas town mesto city river reka lake jezero castle grad museum school library harbour harbor port pier marina hill hrib mountain gora trail tower gate stadium mall airport cemetery embankment nabrezje promenade quay kino cinema theatre theater".split(" "));
+/**
+ * Words that describe rather than name. A phrase made only of these, articles
+ * and place nouns names nowhere in particular: "the park", "the main square",
+ * "my street", "the morning", "good light".
+ */
+const GENERIC = new Set([
+    ...PLACE_NOUNS,
+    ..."shop store stop corner centre center house home office building area place spot site entrance door window wall room kitchen desk table floor".split(" "),
+    ..."front back side top bottom left right middle north south east west local nearest nearby here there main old new big small little large".split(" "),
+    ..."notice board noticeboard sign bench bin bins tree trees field playground parking lot car bus train tram hospital hotel post bank supermarket pharmacy gym university campus neighbourhood neighborhood district block yard".split(" "),
+    ..."morning afternoon evening night today tonight tomorrow yesterday now weekend week month year hour hours minute minutes moment monday tuesday wednesday thursday friday saturday sunday am pm noon midnight time".split(" "),
+    ..."least most all focus daylight light dark detail english slovene camera hand person total general particular case order line view frame full clear sight public private good bad natural same".split(" "),
+    ..."red orange yellow green blue purple pink brown black white grey gray colour color".split(" "),
+    ..."favourite favorite usual nearest closest high low resolution quality".split(" "),
+    ..."phone camera app screen laptop computer paper website page link internet web email message chat".split(" "),
+    ..."cafe restaurant bar pub kiosk stall queue crowd traffic food drink coffee tea menu paint chalk ink costume dress shirt hat uniform bloom flower flowers rain snow sun shade water glass plastic metal wood stone box bag bottle cup plate stock sale use action motion progress".split(" ")
+]);
+/** Tokens of a sentence: words (letters, digits, apostrophes, hyphens) and the punctuation that ends a phrase. */
+const TOKENS = /[\p{L}\p{N}][\p{L}\p{N}'’-]*|[.,;:!?()"“”]/gu;
+/** A word as the comparisons see it: lower case, accents off. "Smokuč" and "smokuc" are one word. */
+export const fold = (word) => word
+    .normalize("NFD")
+    .replace(/\p{Mn}/gu, "")
+    .toLowerCase();
+const COORDINATES = /^-?\d{1,3}(\.\d+)?$/;
+/** Does this word name something, rather than describe it? */
+const naming = (word) => {
+    const folded = fold(word);
+    if (GENERIC.has(folded) || LEADING.has(folded) || ENDS.has(folded))
+        return false;
+    if (/^\d/.test(folded) || COORDINATES.test(folded))
+        return false;
+    return folded.length >= 3;
+};
+/**
+ * The phrases a sentence puts after a word like *in* or *at*, in order, with
+ * leading articles and descriptions trimmed — and only those that hold at
+ * least one word that names something. At most three: a sentence that names
+ * more places than that is describing a route, and the first is where it
+ * starts.
+ */
+export function placeMentions(sentence) {
+    const tokens = sentence.match(TOKENS) ?? [];
+    const lower = tokens.map(fold);
+    const found = [];
+    let index = 0;
+    while (index < tokens.length && found.length < 3) {
+        const starter = BEFORE.find((words) => {
+            const parts = words.split(" ");
+            return parts.every((part, offset) => lower[index + offset] === part);
+        });
+        if (!starter) {
+            index += 1;
+            continue;
+        }
+        index += starter.split(" ").length;
+        const phrase = [];
+        while (index < tokens.length && phrase.length < 7) {
+            const token = tokens[index];
+            const folded = lower[index];
+            if (/^[.;:!?()"“”]$/.test(token))
+                break;
+            if (ENDS.has(folded))
+                break;
+            if (BEFORE.some((words) => words.split(" ")[0] === folded))
+                break;
+            phrase.push(token);
+            index += 1;
+        }
+        /* "the top of Ljubljana Castle" is Ljubljana Castle; "Smokuč Slovenia," keeps its comma inside, never at the edge. */
+        while (phrase.length && (phrase[0] === "," || (!naming(phrase[0]) && !PLACE_NOUNS.has(fold(phrase[0])))))
+            phrase.shift();
+        while (phrase.length && phrase[phrase.length - 1] === ",")
+            phrase.pop();
+        if (!phrase.some(naming))
+            continue;
+        const text = phrase.join(" ").replace(/\s+,/g, ",");
+        if (!found.some((one) => fold(one) === fold(text)))
+            found.push(text);
+    }
+    return found;
+}
+/** Does a phrase say what kind of place it is, beside its name? "prešeren square" does; "Smokuč Slovenia" does not. */
+export const saysWhatItIs = (mention) => (mention.match(TOKENS) ?? []).some((word) => PLACE_NOUNS.has(fold(word)));
+/** What the map answers with that is not a place a person is sent to: a hotel called Morning, a shop called Bloom. */
+const NOT_A_PLACE = new Set(["tourism", "shop", "office", "craft", "building", "house", "club", "healthcare", "emergency"]);
+/**
+ * Two words are one name when they are equal, or long and share a stem —
+ * the way Slovene bends a name: "Prešeren" and "Prešernov", "Ljubljana" and
+ * "Ljubljani". Short words must be equal: "bloom" is not "Bloomfield".
+ */
+const sameName = (a, b) => a === b || (a.length >= 6 && b.length >= 6 && a.slice(0, 5) === b.slice(0, 5));
+/**
+ * The first place the map answered that is called by the phrase's naming
+ * words. A town, a street, a park, a venue counts on one shared name. A shop
+ * or a hotel counts only when every naming word matches, and there are at
+ * least two: "Pekarna Kroštl" is somewhere to go; "bloom", in "a tree in
+ * bloom", is a florist in another country.
+ */
+export function placeCalled(mention, places) {
+    const names = (mention.match(TOKENS) ?? []).filter(naming).map(fold);
+    for (const place of places) {
+        const called = (`${place.name} ${place.label}`.match(TOKENS) ?? []).map(fold);
+        const matches = (name) => called.some((word) => sameName(word, name));
+        if (NOT_A_PLACE.has(place.kind) ? names.length >= 2 && names.every(matches) : names.some(matches))
+            return place;
+    }
+    return null;
+}
+/** How many questions one sentence may put to the map. Nominatim allows one a second. */
+const ASKS_PER_SENTENCE = 2;
+/**
+ * The place a sentence names, and whether the answer can be trusted.
+ *
+ * `named` is null when it names none — and null too when the map could not be
+ * asked about a phrase only the map could settle, because a lookup that
+ * failed is not a reason to refuse somebody's ask. `unsure` says which: an
+ * answer given while the map was unreachable is not one to cache. A phrase
+ * that says what it is ("… square") never needs the map to count, only to be
+ * found.
+ */
+export async function placeIn(sentence, reach = {}) {
+    let asked = 0;
+    let failed = false;
+    const ask = async (query) => {
+        if (asked >= ASKS_PER_SENTENCE)
+            return [];
+        asked += 1;
+        const answer = await searchPlaces(query, reach);
+        if (answer === null)
+            failed = true;
+        return answer ?? [];
+    };
+    for (const mention of placeMentions(sentence)) {
+        if (saysWhatItIs(mention)) {
+            /* Named on its face. Find it if the map can — the whole phrase, then
+               the part before a comma ("ljubljana", of "ljubljana, prešeren square"),
+               so the sheet at least opens on the town. */
+            let found = placeCalled(mention, await ask(mention));
+            const first = mention.split(",")[0]?.trim();
+            if (!found && first && first !== mention)
+                found = placeCalled(first, await ask(first));
+            return { named: { mention, found }, unsure: false };
+        }
+        const found = placeCalled(mention, await ask(mention));
+        if (found)
+            return { named: { mention, found }, unsure: false };
+    }
+    return { named: null, unsure: failed };
+}
+/** The place a sentence names, or null. See `placeIn` for when null means "could not tell". */
+export const namedPlaceIn = async (sentence, reach = {}) => (await placeIn(sentence, reach)).named;
+//# sourceMappingURL=mentions.js.map

package/dist/esm/geo/mentions.js.map

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

package/dist/esm/geo/osm.d.ts

@@ -0,0 +1,112 @@
+import { type GeoBox } from "./box.ts";
+/**
+ * Reading what actually happened on the map.
+ *
+ * The premise of a verified mapping ask: the evidence is not a photograph, a
+ * phone's idea of where it is, or a sentence — it is **what appeared in
+ * OpenStreetMap**. That is public, it is attributed, and it cannot be faked
+ * by the person being paid without doing the work, which is the only kind of
+ * proof worth escrowing money against.
+ *
+ * Two questions, two APIs, and both are needed:
+ *
+ * - **Who edited here, and how much?** The changesets API. It answers with
+ *   changesets whose own bounding box *intersects* the query — so a huge
+ *   changeset merely grazing the area matches, and `changes_count` counts
+ *   every edit in it, most of them elsewhere. Attribution is trustworthy;
+ *   the edit count is an upper bound and is treated as one.
+ * - **What did the map gain?** Overpass, counting features of a tag newer
+ *   than a date. That is the number that says something happened.
+ *
+ * Neither is ours and both are volunteer-run. Failure is therefore ordinary,
+ * not exceptional: every function here answers `null` for "could not
+ * measure", never throws, and the gate that reads it treats null as *a person
+ * should look* rather than as a rejection. Punishing somebody because a free
+ * API was busy is exactly the unfairness this whole design exists to avoid.
+ */
+export interface Window {
+    from: string;
+    to: string;
+}
+export interface Changeset {
+    id: number;
+    user: string;
+    uid: number;
+    changes: number;
+    closedAt: string;
+    /** The changeset's own bounds, when it declares them. */
+    box: GeoBox | null;
+}
+export interface MapActivity {
+    /** Changesets that closed inside the window and overlap the box. */
+    changesets: Changeset[];
+    /** Distinct OSM usernames among them, lowercased for comparison. */
+    users: string[];
+}
+/** A tag we know how to count. Deliberately short — each is a real question. */
+export type FeatureTag = "building" | "highway";
+/** How the world is reached. Injected so tests never touch a live service. */
+export interface Reach {
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+/**
+ * Who edited inside this box, in this window.
+ *
+ * Null means the API did not answer. An empty `changesets` array means it did
+ * answer and nobody edited — a fact, and a different one.
+ */
+export declare function changesetsIn(box: GeoBox, window: Window, reach?: Reach): Promise<MapActivity | null>;
+/** What one person did here, out of everything that happened. */
+export declare function creditFor(activity: MapActivity, username: string): {
+    changesets: number;
+    edits: number;
+};
+/**
+ * How many features of a tag the box has gained since a date.
+ *
+ * `out count` rather than the features themselves: a populated city block
+ * would otherwise be megabytes of geometry to answer a question about one
+ * integer, and the courtesy owed to a free service is the whole reason this
+ * asks so narrowly.
+ */
+export declare function featureDelta(box: GeoBox, sinceISO: string, tag: FeatureTag, reach?: Reach): Promise<number | null>;
+/**
+ * The whole measurement for a mapping gate: attribution and activity together.
+ *
+ * Both are needed and they answer different doubts. Changesets alone would
+ * pass somebody who edited the right box and changed nothing that matters;
+ * feature counts alone would pass somebody standing next to whoever did the
+ * work. Requiring both is what makes the pair worth escrowing against.
+ */
+export interface MapMeasurement {
+    username: string | null;
+    changesetsByUser: number;
+    editsByUser: number;
+    featureDelta: number | null;
+    users: string[];
+    /** True when either API declined to answer — the gate reads this as "ask a person". */
+    incomplete: boolean;
+}
+export declare function measureMapping(args: {
+    box: GeoBox;
+    window: Window;
+    tag: FeatureTag;
+    username?: string | null;
+}, reach?: Reach): Promise<MapMeasurement>;
+/**
+ * The OpenStreetMap account a worker asks to be credited.
+ *
+ * Read leniently on purpose: this is the one fact the map reading cannot
+ * supply for itself, and a mapper who wrote their name plainly should not
+ * lose a bounty to a format. Any of these is enough —
+ *
+ *   osm: alice        OSM user alice        @alice
+ *   openstreetmap.org/user/alice
+ *
+ * — and nothing else is guessed. A deliverable that names no account fails
+ * the gate rather than crediting whoever happens to have been mapping there,
+ * which would pay the wrong person for real work.
+ */
+export declare function osmUsernameIn(deliverable: string): string | null;
+//# sourceMappingURL=osm.d.ts.map

package/dist/esm/geo/osm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"osm.d.ts","sourceRoot":"","sources":["../../../src/geo/osm.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4C,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,oEAAoE;IACpE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AA4BhD,8EAA8E;AAC9E,MAAM,WAAW,KAAK;IACpB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAeD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,KAAU,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA2C9G;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAIxG;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4B5H;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uFAAuF;IACvF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,KAAK,GAAE,KAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAajK;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAchE"}

package/dist/esm/geo/osm.js

@@ -0,0 +1,171 @@
+import { boxesOverlap, osmBboxParam, overpassBbox } from "./box.js";
+const OSM_API = "https://api.openstreetmap.org/api/0.6/changesets.json";
+/*
+ * Overpass, and its understudy.
+ *
+ * The main instance rate-limits hard and fast — a second query a minute after
+ * the first came back as an HTML error page, not JSON, with HTTP 200. So
+ * anything that is not JSON is treated as "busy", the mirror is tried once,
+ * and then we stop: a checker that hammers a volunteer service to answer a
+ * question about somebody's bounty is not a checker anybody should run.
+ */
+const OVERPASS = ["https://overpass-api.de/api/interpreter", "https://overpass.kumi.systems/api/interpreter"];
+/**
+ * Who is asking.
+ *
+ * Not decoration: OpenStreetMap's API policy requires a User-Agent that
+ * identifies the application, and it enforces that by throttling anything
+ * generic into the ground. Measured 2026-08-17 — the same query, at the same
+ * moment, answered **200 for curl and 429 for Node's default fetch**, whose
+ * agent string says only that it is Node. Cloudflare Workers send their own
+ * unremarkable string, so without this the checker would have looked broken
+ * in production and fine on a laptop.
+ */
+const USER_AGENT = "OpenhandsNetwork/1.0 (verified work; +https://openhands-network.vercel.app)";
+const withTimeout = async (reach, url, init) => {
+    const call = reach.fetch ?? globalThis.fetch;
+    try {
+        return await call(url, {
+            ...init,
+            headers: { "user-agent": USER_AGENT, ...(init?.headers ?? {}) },
+            signal: AbortSignal.timeout(reach.timeoutMs ?? 30_000)
+        });
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Who edited inside this box, in this window.
+ *
+ * Null means the API did not answer. An empty `changesets` array means it did
+ * answer and nobody edited — a fact, and a different one.
+ */
+export async function changesetsIn(box, window, reach = {}) {
+    const url = `${OSM_API}?bbox=${encodeURIComponent(osmBboxParam(box))}&time=${encodeURIComponent(`${window.from},${window.to}`)}`;
+    const response = await withTimeout(reach, url, { headers: { accept: "application/json" } });
+    if (!response?.ok)
+        return null;
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(body.changesets))
+        return null;
+    const from = Date.parse(window.from);
+    const to = Date.parse(window.to);
+    const changesets = body.changesets
+        .map((raw) => {
+        const entry = raw;
+        const id = Number(entry.id);
+        const user = typeof entry.user === "string" ? entry.user : "";
+        const closedAt = typeof entry.closed_at === "string" ? entry.closed_at : "";
+        if (!Number.isFinite(id) || !user || !closedAt)
+            return null;
+        const bounds = typeof entry.min_lon === "number" && typeof entry.min_lat === "number" && typeof entry.max_lon === "number" && typeof entry.max_lat === "number"
+            ? { west: entry.min_lon, south: entry.min_lat, east: entry.max_lon, north: entry.max_lat }
+            : null;
+        return { id, user, uid: Number(entry.uid) || 0, changes: Number(entry.changes_count) || 0, closedAt, box: bounds };
+    })
+        .filter((changeset) => {
+        if (!changeset)
+            return false;
+        /* The API's `time` filter is generous about which end it matches, and an
+           open changeset can still be edited — so the window is applied here, to
+           the moment the work was actually finished. */
+        const closed = Date.parse(changeset.closedAt);
+        if (!Number.isFinite(closed) || closed < from || closed > to)
+            return false;
+        /* And its own bounds must genuinely meet ours. */
+        return changeset.box ? boxesOverlap(changeset.box, box) : true;
+    });
+    return { changesets, users: [...new Set(changesets.map((changeset) => changeset.user.toLowerCase()))] };
+}
+/** What one person did here, out of everything that happened. */
+export function creditFor(activity, username) {
+    const wanted = username.trim().toLowerCase();
+    const theirs = activity.changesets.filter((changeset) => changeset.user.toLowerCase() === wanted);
+    return { changesets: theirs.length, edits: theirs.reduce((total, changeset) => total + changeset.changes, 0) };
+}
+/**
+ * How many features of a tag the box has gained since a date.
+ *
+ * `out count` rather than the features themselves: a populated city block
+ * would otherwise be megabytes of geometry to answer a question about one
+ * integer, and the courtesy owed to a free service is the whole reason this
+ * asks so narrowly.
+ */
+export async function featureDelta(box, sinceISO, tag, reach = {}) {
+    const query = `[out:json][timeout:25];(way["${tag}"](${overpassBbox(box)})(newer:"${sinceISO}"););out count;`;
+    for (const endpoint of OVERPASS) {
+        const response = await withTimeout(reach, endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: new URLSearchParams({ data: query }).toString()
+        });
+        if (!response?.ok)
+            continue;
+        /* A busy Overpass answers 200 with an HTML error page. Parsing is the
+           only way to tell that from an answer, so a parse failure means "try the
+           mirror", not "no features". */
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            continue;
+        }
+        const total = body.elements?.[0]?.tags?.total;
+        if (total === undefined)
+            continue;
+        const count = Number(total);
+        if (Number.isFinite(count))
+            return count;
+    }
+    return null;
+}
+export async function measureMapping(args, reach = {}) {
+    const [activity, delta] = await Promise.all([changesetsIn(args.box, args.window, reach), featureDelta(args.box, args.window.from, args.tag, reach)]);
+    const credit = activity && args.username ? creditFor(activity, args.username) : { changesets: 0, edits: 0 };
+    return {
+        username: args.username ?? null,
+        changesetsByUser: credit.changesets,
+        editsByUser: credit.edits,
+        featureDelta: delta,
+        users: activity?.users ?? [],
+        incomplete: !activity || delta === null
+    };
+}
+/**
+ * The OpenStreetMap account a worker asks to be credited.
+ *
+ * Read leniently on purpose: this is the one fact the map reading cannot
+ * supply for itself, and a mapper who wrote their name plainly should not
+ * lose a bounty to a format. Any of these is enough —
+ *
+ *   osm: alice        OSM user alice        @alice
+ *   openstreetmap.org/user/alice
+ *
+ * — and nothing else is guessed. A deliverable that names no account fails
+ * the gate rather than crediting whoever happens to have been mapping there,
+ * which would pay the wrong person for real work.
+ */
+export function osmUsernameIn(deliverable) {
+    const patterns = [
+        /openstreetmap\.org\/user\/([A-Za-z0-9_\-. ]{1,60}?)(?:[/?#\s]|$)/i,
+        /\bosm(?:\s+user(?:name)?)?\s*[:=]\s*@?([A-Za-z0-9_\-.]{1,60})/i,
+        /\bopenstreetmap\s+(?:user(?:name)?\s*)?[:=]?\s*@?([A-Za-z0-9_\-.]{1,60})/i,
+        /\buser(?:name)?\s*[:=]\s*@?([A-Za-z0-9_\-.]{1,60})/i,
+        /(?:^|\s)@([A-Za-z0-9_\-.]{2,60})/
+    ];
+    for (const pattern of patterns) {
+        const found = deliverable.match(pattern)?.[1]?.trim();
+        if (found)
+            return decodeURIComponent(found);
+    }
+    return null;
+}
+//# sourceMappingURL=osm.js.map

package/dist/esm/geo/osm.js.map

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

package/dist/esm/geo/place.d.ts

@@ -0,0 +1,51 @@
+import { type Geometry } from "./tiles.ts";
+interface Address {
+    road?: string;
+    pedestrian?: string;
+    neighbourhood?: string;
+    quarter?: string;
+    suburb?: string;
+    city?: string;
+    town?: string;
+    village?: string;
+    municipality?: string;
+    county?: string;
+    state?: string;
+    country?: string;
+}
+/**
+ * Two parts at most: something specific, then something everyone knows.
+ *
+ * "Pražakova ulica, Ljubljana" is a place. The full `display_name` —
+ * *"Pražakova ulica, Ledina, Grajski grič, Četrtna skupnost Center, Ljubljana,
+ * Upravna Enota Ljubljana, 1000, Slovenija"* — is a filing cabinet, and it is
+ * what this function exists to avoid putting in a sentence about money.
+ */
+export declare function labelFrom(address: Address | undefined, fallback?: string): string | null;
+/**
+ * Third-party text on a page about money.
+ *
+ * Nominatim's data is whatever a stranger typed into OpenStreetMap, so it is
+ * treated the way every other borrowed string here is: control characters
+ * stripped, whitespace collapsed, length capped. Plain text, never markup.
+ */
+export declare function clean(raw: string | null | undefined): string | null;
+/** How the world is reached. Injected so tests never touch a live service. */
+export interface Reach {
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * The name of a point, at a granularity that suits how much ground is meant.
+ *
+ * The zoom is the whole design: asked coarsely it answers "Slovenija", asked
+ * finely it answers a street. Sharing `zoomForMetres` with the map means the
+ * words and the picture always agree about scale.
+ */
+export declare function placeName(point: {
+    lat: number;
+    lon: number;
+}, zoom: number, reach?: Reach): Promise<string | null>;
+/** The name for whatever an ask describes — the one callers actually want. */
+export declare const nameForGeometry: (geometry: Geometry, reach?: Reach) => Promise<string | null>;
+export {};
+//# sourceMappingURL=place.d.ts.map

package/dist/esm/geo/place.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place.d.ts","sourceRoot":"","sources":["../../../src/geo/place.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,QAAQ,EAAoB,MAAM,YAAY,CAAC;AAsC5E,UAAU,OAAO;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBxF;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAMnE;AAED,8EAA8E;AAC9E,MAAM,WAAW,KAAK;IACpB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiB5H;AAED,8EAA8E;AAC9E,eAAO,MAAM,eAAe,GAAI,UAAU,QAAQ,EAAE,QAAO,KAAU,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAA0E,CAAC"}