@ixo/openhands-sdk 0.0.0-stage → 0.2.0

package/dist/esm/rubric/bridge.js

@@ -0,0 +1,911 @@
+import { CLAIM_KINDS, hostOf, normalizeTerms } from "./terms.js";
+/**
+ * What every source and AI check says when it could not answer at all.
+ *
+ * Not `review`. The engine turns an errored fact with `onError: "review"`
+ * into verdict `review` — chain status 5, nothing signed until somebody
+ * looks — and nobody ever looks: there is no review screen, and the
+ * campaign's poster is a key with nobody behind it. A mainnet claim in
+ * collection 8253 sat exactly there, held for ever, because one oracle fact
+ * errored. `reject` is still never an approval (the engine lets an errored
+ * `reject` beat any other verdict), and a refused claimant reads that the
+ * check was unreachable and can submit again; a held one reads nothing.
+ */
+export const ON_ERROR = "reject";
+/** The checker's own defaults (`services/worker-agent/src/config.ts`), carried over unchanged. */
+export const DEFAULT_COOLDOWN = { meters: 150, days: 7 };
+/**
+ * The name every source is declared under.
+ *
+ * The rubric format requires an `endpoint` and a `did:web` `audience` on
+ * every source, and hashes both into the rubric's id. Nothing ever calls
+ * them: the oracle answers by *name*, in-process. So they are one constant,
+ * agreed with the oracle, on a reserved domain that can never resolve.
+ */
+export const ORACLE_HOST = "oracle.openhands.invalid";
+/**
+ * The document as bytes, and the name those bytes answer to.
+ *
+ * Their resolver fetches whatever the chain points at and requires
+ * `hex(sha256(the exact bytes served)) === the on-chain proof`, so the text
+ * returned here is the text that must be uploaded — hashing one serialization
+ * and uploading another is the one mistake that cannot be caught by reading
+ * the code.
+ *
+ * **Not a CID.** Our claim ids and terms are CIDv1, and the `#vct` proof is
+ * one too, but a rubric's proof is a bare hex sha256. Two conventions live on
+ * one entity because each side's reader demands its own.
+ */
+export async function rubricDocument(terms, binding, options = {}) {
+    const { envelope } = toEngineRubric(terms, binding, options);
+    const text = JSON.stringify(envelope);
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+    const proof = [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+    return { text, proof };
+}
+// ------------------------------------------------------------ the vocabulary
+/**
+ * The names the oracle answers to, per gate. Exact: the oracle registers a
+ * handler per name (and per suffix, 2..5, for a rule that repeats within one
+ * rubric) and an unknown name falls through to the package's stock lanes,
+ * which know none of these.
+ */
+export const SOURCE_NAMES = {
+    "within-radius": "withinRadius",
+    located: "located",
+    "before-after": "beforeAfter",
+    "daylight-consistent": "daylight",
+    "weather-consistent": "weather",
+    "not-already-mapped": "notAlreadyMapped",
+    "re-measure": "reMeasure",
+    "at-registered-point": "atPoint",
+    "mapped-grid": "mappedGrid"
+};
+/** The cool-off source, emitted from the options rather than from a gate. */
+export const COOLDOWN_SOURCE = "cooldown";
+/** The marker source on a site ask, so the claim's `kind` is frozen on the receipt for the oracle's act policy. */
+export const SITE_SOURCE = "openhandsSite";
+/** The AI check, per judge criterion: `judge`, then `judge2..`. */
+export const JUDGE_NAME = "judge";
+/**
+ * Whether the photograph is evidence at all — asked of every photograph ask,
+ * by the bridge, whatever the terms say.
+ *
+ * **What bought it (mainnet, collections 8253 and 8231, September 2026).** An
+ * AI-generated square of an Italian piazza, reported as Giza, with a garbled
+ * burned-in timestamp and "Made with Google AI" in its own IPTC — approved,
+ * the judges at 98 and 99. One wallet photographing a computer monitor that
+ * was showing litter — moiré, a share icon, a mouse cursor in frame — approved
+ * five times, a cleanup's before and after shot fourteen seconds apart off the
+ * same screen among them. Paper balls on a tiled floor and a wrapper on
+ * somebody's carpet, approved as mapped messes. Every judge was right about
+ * the sentence it was given: the picture did show waste, the size was about a
+ * bagful, nobody's face was in it. No rule asked whether the picture was a
+ * photograph, and `JUDGE_GUIDANCE` told each judge that anything else wrong
+ * with the claim was not its to judge.
+ *
+ * Two facts the oracle reads off the file's own bytes, and one sentence a
+ * model rules on. They are rules "every ask of the shape carries" — like the
+ * cool-off and the duplicate rule — rather than criteria in the terms, for
+ * the reason those are: an ask already posted has its terms frozen, and a
+ * fake photograph is not something a poster should have to remember to
+ * forbid. `#rub` therefore says more than `#done` does, as it already did.
+ *
+ * Three refusals, all `invalid_evidence`:
+ *
+ * - `notMarkedGenerated` — the file itself (IPTC, XMP, trusted Content
+ *   Credentials) says a generator made it. That is the file's own confession.
+ * - the authenticity judge (`realPhotoRule`) — the picture is of a screen, a
+ *   print or a generator's work, or, where the ask is about waste on the
+ *   ground, of somebody's floor.
+ * - `notElsewhere` — the photograph's EXIF GPS is farther than `meters` from
+ *   the point the claim reported. A camera's last fix can be stale and a
+ *   browser's point can come from a cell tower, which is what the width of
+ *   `NOT_ELSEWHERE_FLOOR_METERS` is for: it forgives the instruments, so what
+ *   is left to refuse is another town.
+ *
+ * **None of them holds a claim for a person, because there is no person.**
+ * `onFail: "review"` would give a claim verdict `review` — chain status 5,
+ * nothing signed until somebody looks — and nobody ever looks: there is no review screen, and the campaign's poster
+ * is a key with nobody behind it. A claimant who is refused reads why and can
+ * go and take the photograph again; one who is held reads nothing and waits
+ * for ever. So a screen that cannot be made wide enough to refuse on is not
+ * written at all, and each refusal's `reason` says what to do about it.
+ */
+export const PHOTO_CHECKS = {
+    notMarkedGenerated: "notMarkedGenerated",
+    notElsewhere: "notElsewhere"
+};
+/**
+ * How far a photograph's own GPS may sit from the point the claim reported.
+ *
+ * Not the place rule — `within-radius` is that, and it stays as tight as the
+ * poster made it. This compares two readings of the SAME moment that come
+ * from different instruments: the camera's EXIF fix, which can be minutes
+ * stale, and the browser's geolocation (`nowAndHere`), which falls back to
+ * wifi and cell towers when no satellite fix arrives inside its eight
+ * seconds. The two honestly differ by hundreds of metres. This is meant to
+ * catch another city, not another street, so an ask's own radius is used only
+ * when it is WIDER than this — a 150 m cleanup radius would refuse honest
+ * phones all day.
+ */
+export const NOT_ELSEWHERE_FLOOR_METERS = 1000;
+/**
+ * The contract's ceiling on one name within one rubric: bare, then `2..5`.
+ *
+ * For an `ext` name it is a wall: the oracle registers exactly those handlers,
+ * and a sixth falls through to the stock lane and is POSTed to a host that can
+ * never resolve. The photograph screens are asked once per photograph and no
+ * claim carries more than two, so they sit under it by construction. For
+ * `judge` it is the contract's word rather than a wall — the stock judge
+ * answers whatever name a rubric declares — and the one judge the bridge adds
+ * of its own accord keeps to it: see where it is emitted.
+ */
+export const NAME_CEILING = 5;
+/** The one duplicate rule every photo ask carries. */
+export const UNIQUE_RULE_ID = "OH-DUP-1";
+/**
+ * The `send` keys per name, in the order they are written — the contract's
+ * table, verbatim. `bridge.test.ts` asserts the emitted keys against this,
+ * and the oracle's tests assert its handlers against the same document.
+ *
+ * `judge` is the *plain photo* row. An AI check sends what the ask's shape
+ * actually carries, which is more than one photograph on a pair —
+ * `JUDGE_SEND_KEYS` below is that table, and the one `bridge.test.ts` checks
+ * a pair and a site against.
+ */
+export const SEND_KEYS = {
+    withinRadius: ["lat", "lon", "photo", "centerLat", "centerLon", "meters"],
+    located: ["lat", "lon", "photo"],
+    beforeAfter: ["before", "after", "meters"],
+    daylight: ["text", "at", "fallbackAt", "lat", "lon"],
+    weather: ["text", "at", "fallbackAt", "lat", "lon"],
+    notAlreadyMapped: ["lat", "lon", "meters"],
+    cooldown: ["lat", "lon", "meters", "days"],
+    reMeasure: ["url", "text"],
+    atPoint: ["lat", "lon", "points", "meters"],
+    mappedGrid: ["box", "tag", "minEdits", "minFeatures", "days"],
+    openhandsSite: ["kind", "lat", "lon"],
+    notElsewhere: ["lat", "lon", "photo", "meters"],
+    notMarkedGenerated: ["photo"],
+    judge: ["task", "text", "photo"]
+};
+/**
+ * What a judge is sent, per ask shape — the fix for the 1149 patch rejections.
+ *
+ * A patch claim on a site carries four files: the before, the after (which is
+ * also `$photo`), and the bags in `$extraFile`. Sending only `$photo` handed
+ * the model ONE image and asked it whether two photographs showed the same
+ * place — it answered, correctly, that it could not compare one photograph,
+ * and every honest patch was refused. So a pair ask sends the pair, an ask
+ * that expects a second file sends it as `bags`, and a site also says which
+ * `kind` of claim arrived, because the two kinds carry different evidence.
+ *
+ * The keys are the contract's (`facts-contract.md`, amended 2026-09-16), and
+ * the engine's own AI lane forwards every attachment a `send` names as its own
+ * labelled input — a file it cannot read arrives as a descriptor rather than
+ * vanishing (evaluator spec §6.1).
+ */
+export const JUDGE_SEND_KEYS = {
+    text: ["task", "text"],
+    photo: ["task", "text", "photo"],
+    pair: ["task", "text", "photo", "before", "after"],
+    "pair-with-bags": ["task", "text", "photo", "before", "after", "bags"],
+    site: ["task", "text", "photo", "before", "after", "bags", "kind"]
+};
+/**
+ * The sentence every judge on a site ask is told first.
+ *
+ * One rubric serves both kinds of claim (the chain allows exactly one), so a
+ * criterion written for a patch is also read against the site photograph and
+ * the other way round. Without this the site judge read "before, after and the
+ * bags" as a rule the wide shot had broken. It says what each kind carries and
+ * that only the kind in front of the model is being ruled on; `$kind` in the
+ * send map is where the model learns which one that is.
+ */
+export const SITE_KIND_PREAMBLE = 'A claim of kind "patch" carries a before photograph, an after photograph and a photograph of the bags; a claim of kind "site" carries one wide photograph of the whole area. Rule only on what this claim\'s kind carries.';
+/**
+ * What every judge is told before the sentence it is ruling on.
+ *
+ * **The wrapper this sits inside is strict on purpose, and that is the
+ * problem.** The oracle's own prompt ends "Do not give benefit of the doubt.
+ * If a rule requires something and you cannot find it, that rule FAILS." That
+ * is the right posture for a rule about a fact and the wrong one for a
+ * judgement of degree: "the photograph supports the amount claimed" gets read
+ * as "prove the amount", and an honest phone photograph of a real pile proves
+ * nothing to that standard. Ask 43910 refused six of six real claims on
+ * testnet, one of them with nothing whatever wrong with it. This paragraph
+ * says what the evidence actually is — a phone, outdoors, one go — and which
+ * way doubt falls, so a rule of degree is read as one.
+ *
+ * **It cannot live in `criterion.text`, twice over.** That field is cut to 300
+ * characters by `parseTerms`, so a paragraph in it would arrive on the model's
+ * wire with its end chopped off; and `toEngineRubric` copies it verbatim into
+ * the reject gate's `reason`, which is the sentence a refused worker reads. A
+ * lecture on how to judge is not an explanation of why somebody was not paid.
+ * `instructions` is neither of those things: it is not part of the frozen
+ * terms, so it is not hashed on chain, and no worker ever sees it.
+ *
+ * **Its second half is about the refusal, not the verdict.** The model's own
+ * `reason` is the only per-claim explanation that ever reaches the person who
+ * did the work, and left to itself the model writes it to an auditor: "it
+ * therefore does not support the reported trailer-sized amount". Somebody who
+ * walked to a ditch and photographed it is owed a sentence they can act on —
+ * what was seen, what fell short, what would have been enough.
+ *
+ * The order of the last two matters. "Never list it as a failed rule" stays
+ * the final sentence, because that is the one protecting the verdict, and the
+ * instruction nearest the end is the one a model is least likely to drop.
+ *
+ * Validated by replaying 18 real claims — the real photographs, the real
+ * prompt: it was never once reported as a failed rule, and the verdicts moved
+ * from 13 of 18 to 16 of 18 agreeing with what a person would have decided.
+ *
+ * **Amended 2026-09-21, two clauses, after the fakes on 8253 and 8231**
+ * (`PHOTO_CHECKS` has the incident). Both were added, nothing was taken out,
+ * and neither has been replayed yet — the 18-claim replay above is of the
+ * paragraph before them, so replay before this is anchored on a live ask.
+ *
+ * - After "still evidence, so rule on what you can see in it": *"That is
+ *   about how well an honest photograph came out, never about what was
+ *   photographed: a picture of a screen, a print or another photograph does
+ *   not become evidence by being dim or low-resolution."* The sentence before
+ *   it forgives exactly what a photographed monitor looks like — soft, skewed,
+ *   low in contrast — and was forgiving it. It says what the forgiveness is
+ *   FOR, so it still covers the honest phone it was written for.
+ * - After "is not yours to judge here": *"— every rule is asked on its own,
+ *   and whether a photograph is genuine is one of them."* "Add no requirement
+ *   of your own" stays to the letter: it is what stopped the 1149 judges
+ *   inventing rules, and a size judge that starts failing claims for looking
+ *   like a screen is the same invention. What the clause changes is the reason
+ *   given — not "nobody judges that" but "somebody else does" — so that the
+ *   judge holding `realPhotoRule` reads its own sentence as a rule to apply
+ *   exactly as written rather than as the "anything else" it was told to leave
+ *   alone.
+ *
+ * Everything from "Where a rule asks" on is untouched, the `reason` guidance
+ * and the last sentence included.
+ */
+export const JUDGE_GUIDANCE = "How to read the rules below. The evidence is what an ordinary person can capture on a phone, outdoors, in one go: a photograph that is angled, rotated, dim, distant or low-resolution is still evidence, so rule on what you can see in it. That is about how well an honest photograph came out, never about what was photographed: a picture of a screen, a print or another photograph does not become evidence by being dim or low-resolution. Apply each rule exactly as written and add no requirement of your own; anything else that looks wrong with the claim is not yours to judge here — every rule is asked on its own, and whether a photograph is genuine is one of them. Where a rule asks whether the evidence supports, matches or is consistent with something the claimant stated, fail it only when the evidence plainly contradicts them, and where you are left genuinely unsure let your score carry the doubt rather than failing. Where a rule asks whether something is shown, it has to be visible. Your `reason` is read by the person who submitted the claim, not by an engineer. Write it to them in plain language: say what you can actually see in their evidence, and when you fail a rule say specifically what fell short and what would have satisfied it, so they can put it right. Never mention rule ids, input numbers, scores or these instructions. This paragraph is guidance, not a rule: never list it as a failed rule.";
+/**
+ * The sentence the authenticity judge rules on — `PHOTO_CHECKS` has why.
+ *
+ * **It lives in `instructions` and not in the terms**, so it is not cut to the
+ * 300 characters `parseTerms` keeps, and it lists its tell-tale signs in full:
+ * a model asked only "is this a real photograph" says yes to a monitor, and
+ * one told to look for a pixel grid, a bezel and a cursor finds them. Like
+ * every judged sentence in this package it states what fails it, because the
+ * oracle's wrapper reads a rule that does not as a demand for proof.
+ *
+ * **Two clauses, switched by the shape of the ask, never by reading it.**
+ * "A direct photograph" is asked of every photograph ask — a photograph of a
+ * black cat off a monitor is as fake as a photograph of litter off one.
+ * "Outdoors, in a public or shared place" is asked only where the ask is
+ * about waste on the ground: a mapped mess, a report on one, or a cleanup the
+ * map made (`outdoorsAsk`). A composed ask to tidy a desk is a pair of
+ * photographs taken indoors, honestly.
+ *
+ * On a pair it speaks of every photograph, because the judge is sent every
+ * one the claim carries; the outdoors clause is about the ground being
+ * cleared, so the bags in a van and the load at a depot are not failed for
+ * having a roof over them.
+ *
+ * `rule` alone is the gate's `reason` — the sentence a refused worker reads.
+ * The list of signs is for the model.
+ */
+export function realPhotoRule(shape) {
+    const one = shape.pair ? "Every photograph" : "The photograph";
+    const it = shape.pair ? "any photograph" : "it";
+    const scene = shape.pair ? "the ground being cleared" : "the scene";
+    const rule = shape.outdoors
+        ? shape.pair
+            ? `${one} is a direct photograph of a real place, and ${scene} is outdoors in a street, verge, park, beach, watercourse, lot or other public or shared outdoor space.`
+            : `${one} is a direct photograph of a real place, taken outdoors in a street, verge, park, beach, watercourse, lot or other public or shared outdoor space.`
+        : `${one} is a direct photograph of a real scene.`;
+    const screen = `${it} is a picture of a screen, monitor, print or another photograph (look for a pixel grid or moiré bands, a bezel, glare on glass, a cursor, a browser or app interface, the perspective skew of a flat glowing rectangle)`;
+    const generated = `${shape.pair ? "any" : "it"} shows signs of being computer-generated (garbled or nonsensical lettering, signs, dates or timestamps; an artificial vignette or frame; impossible geometry)`;
+    const indoors = `${scene} is indoors or part of somebody's home — a household floor, table, balcony or room`;
+    const fails = shape.outdoors ? `Fail this if ${screen}, if ${generated}, or if ${indoors}.` : `Fail this if ${screen}, or if ${generated}.`;
+    return { rule, text: `${rule} ${fails}` };
+}
+/** Per attempt. Their ceiling is 30 s; the oracle answers in-process, so this is generous. */
+const SOURCE_TIMEOUT_MS = 15_000;
+/**
+ * How far apart a pair's two photographs may be taken. The gate carries no
+ * radius by design — the place is the ask's `within-radius` gate — so that
+ * gate's radius is used when the ask has one, and this when it does not.
+ */
+const DEFAULT_PAIR_METERS = 150;
+// -------------------------------------------------------------- the fields
+/**
+ * The claim form's file questions (claim form v3, plan D3). Each is a SurveyJS
+ * file answer — `[{name, type, content: "https://…"}]` — which is what lets
+ * `mediaTypeIn`, `maxSizeMB` and the duplicate lanes see the bytes. On a
+ * pair, `photo` is the after photograph, the same as `file`.
+ */
+const PHOTO = "$photo";
+const BEFORE_PHOTO = "$beforePhoto";
+const AFTER_PHOTO = "$afterPhoto";
+const EXTRA_FILE = "$extraFile";
+/** Which kind of claim arrived — `patch` or `site` on a shared site. */
+const KIND = "$kind";
+const TEXT = "$deliverable";
+const LAT = "$location.lat";
+const LON = "$location.lon";
+const AT = "$location.at";
+/** The engine's own token for when the claim was submitted — the fallback when no reading carries a time. */
+const SUBMITTED_AT = "ctx.claim.submissionDate";
+/** Which deliverables carry a photograph in `$photo`. */
+const WITH_PHOTO = new Set(["photo", "photo-pair", "mess-report", "field-report", "file"]);
+/**
+ * Which deliverables ARE a photograph. `file` rides in `$photo` too, and is a
+ * scan, a video or a PDF as often as a picture: asking whether a document is
+ * "a direct photograph of a real scene" would refuse every honest one. So the
+ * photograph screens are not asked of it.
+ */
+const PHOTOGRAPH = new Set(["photo", "photo-pair", "mess-report", "field-report"]);
+/** The rules that make a claim report where it was — what `notElsewhere` compares the photograph against. */
+const PLACE_GATES = new Set(["located", "within-radius", "not-already-mapped", "at-registered-point"]);
+/** Long enough that no honest deliverable hits it; `lengthBetween` is inclusive. */
+const LENGTH_CEILING = 1_000_000;
+const MEGABYTE = 1_048_576;
+/** Bytes as the MB their `maxSizeMB` reads, rounded up to a hundredth so a limit never tightens. */
+const megabytes = (bytes) => Math.ceil((bytes / MEGABYTE) * 100) / 100;
+const escapeRegex = (raw) => raw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * A literal as a case-insensitive pattern, spelled out.
+ *
+ * Their `matches` compiles the pattern with no flags, and JavaScript has no
+ * inline `(?i)`, so case-insensitivity has to be written into the character
+ * classes. Our own gates all compare lowercased, so anything else would be a
+ * stricter rule than the poster agreed to.
+ */
+const insensitive = (literal) => [...literal].map((character) => (/[a-z]/i.test(character) ? `[${character.toLowerCase()}${character.toUpperCase()}]` : escapeRegex(character))).join("");
+/**
+ * A string that must reach the oracle as itself.
+ *
+ * A `send` value that begins like a reference (`$`, `~`, `.`, `ctx.`, `ext.`,
+ * `ai.`) IS a reference to their binder, and an ask titled "$5 for a photo"
+ * would bind to a question that does not exist and take the rubric down. A
+ * literal that could be mistaken for one is prefixed with a word.
+ */
+const literal = (text) => (/^[$~.]|^(?:ctx|ext|ai)\./.test(text) ? `Text: ${text}` : text);
+/** `OH-101-MENTIONS-URL` — their code grammar is `^[A-Z0-9]+-[0-9]+-[A-Z0-9-]+$`. */
+const codeFor = (index, label) => `OH-${100 + index}-${label.toUpperCase().replace(/[^A-Z0-9]+/g, "-").replace(/^-|-$/g, "")}`;
+const field = (name, op, value) => ({
+    "@type": "Condition",
+    field: name,
+    op,
+    ...(value === undefined ? {} : { value })
+});
+/**
+ * The words our own `reports-status` accepts, as one pattern.
+ *
+ * `verdict.ts` accepts a three-digit code introduced by a status word, or any
+ * of the phrases that say the site never answered. The context words matter:
+ * a bare three-digit number would let "I checked 200 pages" pass as a status,
+ * and a rule looser than ours would approve work our own checker rejects.
+ */
+const STATUS_WORDS = ["status", "code", "http", "returned", "returns", "responded", "responds", "answered", "answers", "gave"];
+const DOWN_WORDS = [
+    "did not answer",
+    "didn't answer",
+    "does not answer",
+    "no response",
+    "unreachable",
+    "timed out",
+    "timeout",
+    "could not connect",
+    "couldn't connect",
+    "connection refused",
+    "is down",
+    "not responding",
+    "never answered"
+];
+/* Bounded on both sides: the gap is capped so the pattern cannot backtrack,
+   which is also what keeps it inside their safe-regex subset. */
+const statusPattern = () => [...STATUS_WORDS.map((word) => `${insensitive(word)}[^0-9]{0,16}[0-9]{3}`), ...DOWN_WORDS.map(insensitive)].join("|");
+/** A native gate: the engine performs it itself. */
+function nativeGate(gate, index) {
+    switch (gate.id) {
+        /* `present` is false for null, "" and [] — exactly our "there is a
+           deliverable", which trims first and asks for length. */
+        case "non-empty":
+            return { "@type": "Gate", code: codeFor(index, "present"), reason: "Nothing was handed over", when: field(TEXT, "present"), onFail: "reject", class: "insufficient_evidence" };
+        case "min-length":
+            return {
+                "@type": "Gate",
+                code: codeFor(index, "length"),
+                reason: `Shorter than the ${gate.chars} characters this ask asked for`,
+                when: field(TEXT, "lengthBetween", [gate.chars, LENGTH_CEILING]),
+                onFail: "reject",
+                class: "insufficient_evidence"
+            };
+        /* We match the host, not the whole URL — a worker who writes
+           `docs.ixo.world responded 200` has named it. */
+        case "mentions-url":
+            return {
+                "@type": "Gate",
+                code: codeFor(index, "names-site"),
+                reason: `Never names ${hostOf(gate.url)}`,
+                when: field(TEXT, "matches", insensitive(hostOf(gate.url))),
+                onFail: "reject",
+                class: "invalid_evidence"
+            };
+        case "reports-status":
+            return {
+                "@type": "Gate",
+                code: codeFor(index, "reports-status"),
+                reason: "States no status and no failure",
+                when: field(TEXT, "matches", statusPattern()),
+                onFail: "reject",
+                class: "insufficient_evidence"
+            };
+        case "mentions-terms":
+            return {
+                "@type": "Gate",
+                code: codeFor(index, "terms"),
+                reason: `Missing ${gate.terms.map((term) => `"${term}"`).join(", ")}`,
+                when: { "@type": "Condition", all: gate.terms.map((term) => field(TEXT, "matches", insensitive(term))) },
+                onFail: "reject",
+                class: "invalid_evidence"
+            };
+        /*
+         * Facts about the attached file, which the engine reads off the claim's
+         * SurveyJS file answer. `mediaTypeIn` takes MIME globs, so `image/*` is
+         * passed as it is; a missing attachment fails both, which is right — on a
+         * photo ask the photograph IS the work.
+         */
+        case "file-type":
+            return {
+                "@type": "Gate",
+                code: codeFor(index, "file-type"),
+                reason: `The file handed over is not ${gate.accept}`,
+                when: field(PHOTO, "mediaTypeIn", [gate.accept]),
+                onFail: "reject",
+                class: "invalid_evidence"
+            };
+        case "max-bytes":
+            return {
+                "@type": "Gate",
+                code: codeFor(index, "file-size"),
+                reason: `The file handed over is larger than ${gate.bytes} bytes`,
+                when: field(PHOTO, "maxSizeMB", megabytes(gate.bytes)),
+                onFail: "reject",
+                class: "invalid_evidence"
+            };
+        /* The second file: it has to be there, and it has to fit. */
+        case "with-file":
+            return {
+                "@type": "Gate",
+                code: codeFor(index, "extra-file"),
+                reason: `No second file under ${gate.bytes} bytes came with it`,
+                when: { "@type": "Condition", all: [field(EXTRA_FILE, "present"), field(EXTRA_FILE, "maxSizeMB", megabytes(gate.bytes))] },
+                onFail: "reject",
+                class: "invalid_evidence"
+            };
+        default:
+            return null;
+    }
+}
+/**
+ * A sourced gate: the oracle answers it by name, with the rule's parameters
+ * sent as literals and the claim's fields sent as refs — the keys exactly as
+ * `SEND_KEYS` lists them. The `name` here is the bare vocabulary word; a
+ * suffix, when one is needed, is added once the whole rubric is known.
+ */
+function sourcedGate(gate, index, context) {
+    const name = SOURCE_NAMES[gate.id];
+    if (!name)
+        return null;
+    const reject = (label, reason, kind = "refuted") => ({ "@type": "Gate", code: codeFor(index, label), reason, onFail: "reject", class: kind });
+    switch (gate.id) {
+        case "within-radius":
+            return {
+                name,
+                send: { lat: LAT, lon: LON, photo: PHOTO, centerLat: gate.lat, centerLon: gate.lon, meters: gate.meters },
+                gate: reject("within-radius", `Not within ${gate.meters} m of ${gate.place || `${gate.lat}, ${gate.lon}`}`)
+            };
+        case "located":
+            return {
+                name,
+                send: { lat: LAT, lon: LON, photo: PHOTO },
+                gate: reject("located", "No location was reported", "insufficient_evidence")
+            };
+        case "before-after":
+            return {
+                name,
+                send: { before: BEFORE_PHOTO, after: AFTER_PHOTO, meters: context.radiusMeters ?? DEFAULT_PAIR_METERS },
+                gate: reject("before-after", "The two photographs are not of the same place, in that order")
+            };
+        case "daylight-consistent":
+            return {
+                name,
+                send: { text: TEXT, at: AT, fallbackAt: SUBMITTED_AT, lat: LAT, lon: LON },
+                gate: reject("daylight", "Describes light the sun could not have given at that place and time")
+            };
+        case "weather-consistent":
+            return {
+                name,
+                send: { text: TEXT, at: AT, fallbackAt: SUBMITTED_AT, lat: LAT, lon: LON },
+                gate: reject("weather", "Describes weather the archive did not record at that place and time")
+            };
+        case "not-already-mapped":
+            return {
+                name,
+                send: { lat: LAT, lon: LON, meters: gate.metres },
+                gate: reject("not-already-mapped", `Something approved on this ask is already within ${gate.metres} m`)
+            };
+        /* The URL is the ask's, not the claim's: the form carries none. */
+        case "re-measure":
+            return {
+                name,
+                send: { url: literal(gate.url), text: TEXT },
+                gate: reject("re-measure", `A fresh reading of ${hostOf(gate.url)} disagrees with the answer`)
+            };
+        /* Points as one JSON string: a `send` value is a string, a number or a
+           boolean, never a list, and the oracle parses it back. */
+        case "at-registered-point":
+            return {
+                name,
+                send: { lat: LAT, lon: LON, points: JSON.stringify(gate.points), meters: gate.metres },
+                gate: reject("at-point", `Not within ${gate.metres} m of any registered point`)
+            };
+        /* The box likewise: one JSON string, `{west, south, east, north}`. */
+        case "mapped-grid":
+            return {
+                name,
+                send: { box: JSON.stringify(gate.box), tag: gate.tag, minEdits: gate.minEdits, minFeatures: gate.minFeatures, days: gate.days },
+                gate: reject("mapped-grid", `Fewer than ${gate.minFeatures} ${gate.tag} features were mapped in ${gate.place || "the target area"}`)
+            };
+        default:
+            return null;
+    }
+}
+/**
+ * Is this ask about waste on the ground somewhere people share?
+ *
+ * Decided from what the terms ARE, never from their sentences: a mapped mess
+ * and a report on one by their deliverable, and a cleanup by what only the
+ * mess map writes into one — the pin it clears, a site, a disposal point.
+ * Anything else with a pair of photographs is somebody's own ask, and may
+ * honestly be indoors.
+ */
+const outdoorsAsk = (terms) => terms.deliverable.type === "mess-report" || terms.deliverable.type === "field-report" || terms.site === true || Boolean(terms.clears) || Boolean(terms.disposal);
+const extRef = (name) => field(`ext.${name}.valid`, "isTrue");
+/** `withinRadius`, `withinRadius2`, … — bare first, then a 2-based suffix, which is how the oracle registers handlers. */
+const suffixed = (name, ordinal) => (ordinal === 1 ? name : `${name}${ordinal}`);
+/**
+ * Terms → the engine's rubric.
+ *
+ * Never returns null and never leaves a rule out: every criterion is either a
+ * gate the engine runs or a source the oracle answers, and a gate that reads
+ * it. The judge criteria become AI checks; an `attest` criterion is refused
+ * (a term whose judge is the poster cannot be served by an oracle at all —
+ * `servableByOracle` says so before an ask is posted).
+ */
+export function toEngineRubric(terms, binding, options = {}) {
+    const normalized = normalizeTerms(terms);
+    const cooldown = options.cooldown === undefined ? DEFAULT_COOLDOWN : options.cooldown;
+    const withPhoto = WITH_PHOTO.has(normalized.deliverable.type);
+    const measure = (id) => {
+        for (const criterion of normalized.criteria)
+            if (criterion.kind === "measure" && criterion.gate.id === id)
+                return criterion.gate;
+        return null;
+    };
+    const radius = measure("within-radius");
+    const context = { radiusMeters: radius && radius.id === "within-radius" ? radius.meters : null };
+    /*
+     * What the judges are shown, decided once from the shape of the whole ask.
+     *
+     * A pair is an ask whose deliverable IS a pair, or one whose terms carry the
+     * `before-after` gate — the two travel together, and either alone still means
+     * two photographs exist. The bags ride along only where a second file is
+     * actually expected: a site (every patch hands one over) or a `with-file`
+     * gate that demands one. `kind` goes with the site preamble, and only there.
+     */
+    const pair = normalized.deliverable.type === "photo-pair" || measure("before-after") !== null;
+    /* A site, a second file, or a disposal photograph: the bags ride beside the pair. */
+    const expectsExtra = normalized.site === true || measure("with-file") !== null || measure("at-registered-point") !== null;
+    const judgeSend = {
+        task: literal(normalized.task),
+        text: TEXT,
+        ...(withPhoto ? { photo: PHOTO } : {}),
+        ...(pair ? { before: BEFORE_PHOTO, after: AFTER_PHOTO } : {}),
+        ...(pair && expectsExtra ? { bags: EXTRA_FILE } : {}),
+        ...(normalized.site ? { kind: KIND } : {})
+    };
+    const gates = [];
+    const aiChecks = [];
+    /* Sources by bare name first; the suffix is decided once the count is known. */
+    const pending = [];
+    let judges = 0;
+    /* Always first, and always emitted: their gates run in document order and
+       every other rule reads the deliverable. It is also the one rule every ask
+       has. */
+    gates.push(nativeGate({ id: "non-empty" }, 0));
+    /*
+     * Which kind of claim this is — asked before anything that depends on it,
+     * and never itself conditional.
+     *
+     * The scopes below are `$kind == "patch"`, and their null rule (§A.5) makes
+     * a condition on a missing answer FALSE rather than an error: a claim that
+     * simply says nothing would skip the pair rules instead of failing them,
+     * and be approved on what was left without ever showing a before and an
+     * after. The oracle's act policy reads the same answer and an unknown kind
+     * is neither held nor released, so it would be signed as well. So the kind
+     * is a gate of its own, pinned to the vocabulary rather than to mere
+     * presence — a claim calling itself something we do not serve is no better
+     * than one that says nothing.
+     */
+    if (normalized.site) {
+        gates.push({
+            "@type": "Gate",
+            code: codeFor(0, "kind"),
+            reason: "The claim does not say whether it is a patch or the whole site",
+            when: field(KIND, "in", [...CLAIM_KINDS]),
+            onFail: "reject",
+            class: "insufficient_evidence"
+        });
+    }
+    /* Where the refusals about the photograph itself go: after the two rules
+       every other rule leans on, before any rule about what the photograph
+       shows. "Is this evidence" is asked before "what is it evidence of". */
+    const authenticityAt = gates.length;
+    /*
+     * A rule that is only about one kind of claim, said as their condition.
+     *
+     * The criterion declares its own kind (`appliesTo`, written where the
+     * criterion is), so nothing here reads sentences or counts positions — a
+     * line a poster wrote carries no scope and is asked of every claim. And
+     * only on a site: anywhere else exactly one kind of claim can arrive, so a
+     * scope could only ever turn a rule off.
+     */
+    const scopeOf = (criterion) => normalized.site && "appliesTo" in criterion && criterion.appliesTo ? { appliesWhen: field(KIND, "==", criterion.appliesTo) } : null;
+    normalized.criteria.forEach((criterion, position) => {
+        const index = position + 1;
+        const scope = scopeOf(criterion);
+        if (criterion.kind === "measure") {
+            if (criterion.gate.id === "non-empty")
+                return; // already emitted, and their codes must be unique
+            const native = nativeGate(criterion.gate, index);
+            if (native) {
+                gates.push({ ...native, ...scope });
+                return;
+            }
+            const sourced = sourcedGate(criterion.gate, index, context);
+            if (!sourced)
+                throw new Error(`the bridge does not know the "${String(criterion.gate.id)}" gate`);
+            pending.push(sourced);
+            /* In document order; the `when` is written once the source's final
+               name is known. */
+            gates.push({ ...sourced.gate, ...scope, when: extRef(sourced.name) });
+            return;
+        }
+        if (criterion.kind === "judge") {
+            /*
+             * Their AI check is the same shape as our judge criterion: a sentence
+             * ruled on, yes or no, with the answer frozen before any decision uses
+             * it. What we send is named fields, never the whole claim — the same
+             * rule our own judge followed, for the same injection reason. The task
+             * is a literal: a browser submission carries no `task` of its own.
+             */
+            judges += 1;
+            const name = suffixed(JUDGE_NAME, judges);
+            aiChecks.push({
+                "@type": "AiCheck",
+                name,
+                send: { ...judgeSend },
+                /* The guidance first, always — see `JUDGE_GUIDANCE` for the six
+                   rejections that bought it. Then, on a site only, what each kind of
+                   claim carries (`SITE_KIND_PREAMBLE`). The criterion itself is last
+                   and is the only one of the three that is a rule. */
+                instructions: normalized.site ? [JUDGE_GUIDANCE, SITE_KIND_PREAMBLE, criterion.text] : [JUDGE_GUIDANCE, criterion.text],
+                expect: "boolean",
+                onError: ON_ERROR
+            });
+            /*
+             * The scope rides on the GATE, never on the check: their `AiCheck` is a
+             * closed object with no `appliesWhen` (schema.ts), so a check carrying
+             * one would make the whole rubric unparseable. The consequence is that a
+             * skipped gate's answer is still asked for — their fact coverage refuses
+             * a decision when a declared check has no fact on the wire — so the
+             * model is still paid a fraction of a penny to rule on a sentence that
+             * cannot decide anything. Cheap, and honest: nothing here pretends the
+             * question was not asked.
+             */
+            gates.push({
+                "@type": "Gate",
+                code: codeFor(index, "judged"),
+                reason: criterion.text,
+                ...scope,
+                when: field(`ai.${name}.valid`, "isTrue"),
+                onFail: "reject",
+                class: "refuted"
+            });
+            return;
+        }
+        /* `attest` is the poster's own eye by construction, and there is no
+           poster in this loop. An ask carrying one is not served by the oracle,
+           so it gets no rubric — `servableByOracle` is where that is decided. */
+        throw new Error(`criterion ${criterion.id} is attested by the poster; an oracle cannot serve it`);
+    });
+    /*
+     * Rules the terms do not spell out but every ask of the shape carries.
+     * Their gate codes continue the criterion numbering so they stay unique.
+     */
+    let extra = normalized.criteria.length;
+    const marker = (sourced) => {
+        pending.push(sourced);
+        gates.push({ ...sourced.gate, when: extRef(sourced.name) });
+    };
+    /* The cool-off, on an ordinary cleanup: not a site (patches are meant to
+       sit within metres of each other) and not a multi-spot ask (which already
+       says how far apart its spots must be). */
+    if (cooldown && measure("before-after") && !normalized.site && !measure("not-already-mapped")) {
+        extra += 1;
+        marker({
+            name: COOLDOWN_SOURCE,
+            send: { lat: LAT, lon: LON, meters: cooldown.meters, days: cooldown.days },
+            gate: { "@type": "Gate", code: codeFor(extra, "cooldown"), reason: `Somewhere within ${cooldown.meters} m was paid for in the last ${cooldown.days} days`, onFail: "reject", class: "refuted" }
+        });
+    }
+    /* The site marker: always answered yes; it exists so the claim's `kind`
+       is frozen on the receipt, where the oracle's act policy reads it to hold
+       a patch and release on the site claim. A gate reads it so the engine
+       resolves it. */
+    if (normalized.site) {
+        extra += 1;
+        marker({
+            name: SITE_SOURCE,
+            send: { kind: KIND, lat: LAT, lon: LON },
+            gate: { "@type": "Gate", code: codeFor(extra, "site"), reason: "The site marker could not be recorded", onFail: "reject", class: "insufficient_evidence" }
+        });
+    }
+    /*
+     * The photograph screens (`PHOTO_CHECKS`): on every ask whose deliverable is
+     * a photograph, whatever its terms say.
+     *
+     * **Which photographs.** `$photo` always — it is the one file every kind of
+     * claim carries. On a pair also `$beforePhoto`, numbered the way a repeated
+     * rule is (`notMarkedGenerated2`); `$afterPhoto` is `$photo` again and is
+     * not asked twice. NOT the before photograph on a site: the wide shot of a
+     * cleared site carries none, a fact about a missing file is an error rather
+     * than a no, and their `decide` refuses a claim for ANY errored source a
+     * rule names even when that rule's gate is skipped (S9 reads the rubric, not
+     * the outcome; `ON_ERROR` is `reject`) — so scoping the gate to a patch
+     * would not save the site claim, and every honest site shot would be
+     * refused. A patch's before photograph
+     * is still in front of the authenticity judge, which is sent everything.
+     * And not the second file, which is a document as often as a picture.
+     *
+     * **Where they sit.** All of them go in at `authenticityAt`, ahead of the
+     * terms' own rules: the first failed gate is terminal, so a claim that is
+     * not evidence at all is told that rather than which rule of the terms its
+     * picture happened to fail. Their codes continue the numbering after the
+     * cool-off and the marker, so no code an anchored rubric already carries
+     * changes its number.
+     */
+    const screens = [];
+    if (PHOTOGRAPH.has(normalized.deliverable.type)) {
+        const photos = pair && !normalized.site ? [PHOTO, BEFORE_PHOTO] : [PHOTO];
+        const said = (photo) => (photos.length === 1 ? "The photograph" : photo === BEFORE_PHOTO ? "The before photograph" : "The after photograph");
+        const screened = (sourced) => {
+            pending.push(sourced);
+            screens.push({ ...sourced.gate, when: extRef(sourced.name) });
+        };
+        for (const photo of photos) {
+            extra += 1;
+            screened({
+                name: PHOTO_CHECKS.notMarkedGenerated,
+                send: { photo },
+                gate: { "@type": "Gate", code: codeFor(extra, "not-generated"), reason: `${said(photo)} says of itself that an AI generator made it`, onFail: "reject", class: "invalid_evidence" }
+            });
+        }
+        /*
+         * The model's half. Named AFTER the terms' own judges — `judge4` on the
+         * mapping ask — although it is written and ruled on first: the screens
+         * that explain a refusal (`wcd/lib/ruleKeys.ts`) read `judgeN` as the
+         * N-th judged criterion of the terms, and taking `judge` for a rule the
+         * terms do not carry would blame the size rule for a face. Every check
+         * runs before any gate is decided, so the order here buys no saving; it
+         * decides which refusal a claim that fails several is told about.
+         *
+         * At the contract's ceiling it is left out rather than named `judge6`: the
+         * poster's five sentences are the contract, and this is ours.
+         */
+        const judged = normalized.criteria.filter((criterion) => criterion.kind === "judge").length;
+        if (judged < NAME_CEILING) {
+            const sentence = realPhotoRule({ pair, outdoors: outdoorsAsk(normalized) });
+            const name = suffixed(JUDGE_NAME, judged + 1);
+            extra += 1;
+            aiChecks.unshift({
+                "@type": "AiCheck",
+                name,
+                send: { ...judgeSend },
+                instructions: normalized.site ? [JUDGE_GUIDANCE, SITE_KIND_PREAMBLE, sentence.text] : [JUDGE_GUIDANCE, sentence.text],
+                expect: "boolean",
+                onError: ON_ERROR
+            });
+            screens.push({ "@type": "Gate", code: codeFor(extra, "real-photo"), reason: sentence.rule, when: field(`ai.${name}.valid`, "isTrue"), onFail: "reject", class: "invalid_evidence" });
+        }
+        /* Only where a rule makes the claim say where it was: an ask that never
+           asks has no reported point, the contract answers that with an error,
+           and an error is the outage path — every honest photograph of a black
+           cat, refused. The reason is the one a refused claimant reads,
+           so it ends with what to do. */
+        const placed = normalized.criteria.some((criterion) => criterion.kind === "measure" && PLACE_GATES.has(criterion.gate.id));
+        for (const photo of placed ? photos : []) {
+            extra += 1;
+            screened({
+                name: PHOTO_CHECKS.notElsewhere,
+                send: { lat: LAT, lon: LON, photo, meters: Math.max(context.radiusMeters ?? 0, NOT_ELSEWHERE_FLOOR_METERS) },
+                gate: {
+                    "@type": "Gate",
+                    code: codeFor(extra, "not-elsewhere"),
+                    reason: `${said(photo)}'s own GPS puts it far from the place reported — take the photograph at the place you are reporting`,
+                    onFail: "reject",
+                    class: "invalid_evidence"
+                }
+            });
+        }
+        gates.splice(authenticityAt, 0, ...screens);
+    }
+    /*
+     * Names, finally. A vocabulary word is used bare the first time and with a
+     * suffix from 2 when the same rule repeats within one rubric —
+     * `withinRadius`, `withinRadius2` — which is how the oracle registers its
+     * handlers too. The gates that read them are patched by code.
+     */
+    const seen = new Map();
+    const sources = pending.map((one) => {
+        const ordinal = (seen.get(one.name) ?? 0) + 1;
+        seen.set(one.name, ordinal);
+        const name = suffixed(one.name, ordinal);
+        const gate = gates.find((candidate) => candidate.code === one.gate.code);
+        if (gate)
+            gate.when = extRef(name);
+        return {
+            "@type": "ExternalSource",
+            name,
+            endpoint: `https://${ORACLE_HOST}/${name}`,
+            audience: `did:web:${ORACLE_HOST}`,
+            send: one.send,
+            expect: "boolean",
+            onError: ON_ERROR,
+            timeoutMs: SOURCE_TIMEOUT_MS
+        };
+    });
+    /* The same photograph, handed in twice, is paid once. Keyed by the
+       photograph; the attachment lanes (exact CID and near-duplicate) cover
+       every file on the claim regardless. One band: a near-certain duplicate
+       is refused, nothing is queued for a person. */
+    const unique = withPhoto
+        ? {
+            "@type": "Unique",
+            id: UNIQUE_RULE_ID,
+            by: [PHOTO],
+            countPrior: ["approved"],
+            attachments: true,
+            ai: { enabled: false },
+            thresholds: { rejectAtBps: 9000, reviewAtBps: 9000 }
+        }
+        : null;
+    return {
+        envelope: {
+            "@context": { ixo: "https://w3id.org/ixo/ns/protocol/", "@id": "@type", type: "@type", "@protected": true },
+            type: "ixo:entity#rubric",
+            rubric: {
+                "@type": "Rubric",
+                title: normalized.task.slice(0, 120),
+                claimSchema: { "@type": "ClaimSchemaBinding", protocol: binding.protocol, resource: "#vct", proof: binding.proof },
+                ...(sources.length > 0 ? { sources } : {}),
+                ...(aiChecks.length > 0 ? { aiChecks } : {}),
+                ...(unique ? { unique } : {}),
+                gates
+            }
+        }
+    };
+}
+//# sourceMappingURL=bridge.js.map