@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/cli/commands/oracle-init.js

@@ -0,0 +1,1122 @@
+/**
+ * `decision-oracle oracle init` — provision the WHOLE oracle: its wallet, its chain identity, its Matrix
+ * account and its on-chain entity with its full public identity (profile, domain card, agent card),
+ * in thirteen steps that each re-decide themselves against LIVE state. Every oracle built with the
+ * kit carries all of it (owner, 2026-10-01); `--logo` is the one optional input, and its absence is
+ * said out loud because the portal and the console then show a placeholder.
+ *
+ *   decision-oracle oracle init --protocol did:ixo:entity:… --kit-url https://my-oracle.example.com \
+ *     [--network devnet] [--env-file .dev.vars] [--logo <url>] [--openhands [--price-pay <n>]] \
+ *     [--only <step>] [--relogin] [--yes]
+ *
+ * Dry run by default: every step prints `do` or `skip (<why>)` and NOTHING is signed, created or
+ * written. `--yes` runs the same thirteen decisions and executes them. Re-running is always safe —
+ * the skip decision comes from the chain, the homeserver and the entity themselves, never from a
+ * marker this command wrote, so a partial failure, a redeploy or a second provider running it twice
+ * all converge on the same state.
+ *
+ *   1 fund      the AuthHub session tops ORACLE_ADDRESS up to FUND_UIXO (it pays for MsgEvaluateClaim)
+ *   2 iid       the oracle's OWN wallet creates `did:ixo:<ORACLE_ADDRESS>` + its `#matrix` service
+ *   3 key       … and adds the SERVICE_ED25519_MNEMONIC key, so UCANs minted as that DID resolve
+ *   4 matrix    … and creates + logs into the oracle's Matrix account (ORACLE_MATRIX_ACCESS_TOKEN)
+ *   5 entity    the session creates the oracle ENTITY (services + protocol edge inline)
+ *   6 orz       … its `#orz` authz config (the portal's entity→account bridge)
+ *   7 profile   … its `#pro` profile, built from the RUNNING oracle's `GET /v1/info`
+ *   8 domain    … its `#dmn` domain card (the portal's shape; added, or replaced when it drifted)
+ *   9 acard     … its `#acard` Agent Card (validated against the engine's schema; same rule)
+ *  10 linked    … the oracle→protocol edge, 11 service the `#eval` endpoint, 12 backlink the way back
+ *  13 index     the domain indexer is told the entity exists — AFTER `domain`, so it reads the card
+ *               (skipped when it already holds the anchored card; a failure is a warning, never fatal)
+ *
+ * TWO signers, deliberately. Steps 2–4 are the ORACLE's own identity: only its key may write its own
+ * IID document, and only its key can prove the address to the rooms bot. Everything else is the
+ * AuthHub session, which OWNS the entity it creates (`ownerAddress`/`ownerDid`/`controller`) — that
+ * owner does not have to be the oracle's runtime identity, and the oracle's `ORACLE_ADDRESS` still
+ * needs its own `EvaluateClaimAuthorization` on any collection. So the oracle's mnemonics
+ * (`ORACLE_SECP_MNEMONIC`, `SERVICE_ED25519_MNEMONIC`) are required only by steps 2–4: a deployed
+ * oracle whose keys live only in its worker secrets still runs `--only orz|profile|domain|acard…`
+ * on the session alone, from the public vars and `/v1/info`.
+ *
+ * No `--entity` flag: the entity is found by THIS ORACLE, never by its owner — one session may own
+ * the entities of several oracles. `ORACLE_ENTITY_DID`, when set, pins it (checked to be an oracle
+ * entity the session owns); otherwise it is the session's oracle entity whose `#orz` grants
+ * `ORACLE_ADDRESS` (the portal's own entity→account bridge, so it survives a moved host), else whose
+ * `#eval` is `--kit-url` (written inline by `entity`, so a run that died before `orz` still finds
+ * it). See `resolveOracleEntity`. `--only <step>` runs exactly one step, for debugging a stuck run.
+ */
+import { resolve } from "node:path";
+import process from "node:process";
+import { cidForBytes } from "../../lib/hash.js";
+import { deriveServiceKey } from "../../lib/ixo/identity.js";
+import { mxidFromDid } from "../../lib/matrix/mxid.js";
+import { NETWORKS } from "../../networks.js";
+import { evaluationFeeFor } from "../../oracle.js";
+import { parse } from "../lib/args.js";
+import { addLinkedEntityMsg, addLinkedResourceMsg, addServiceMsg, broadcast, confirm, deleteLinkedResourceMsg, deleteServiceMsg, entityDidFromEvents, fail, ownedOracleEntities, resolveEntity, resolveNetwork, STANDARD_FEE, sessionDocSigner, sha256Hex, uploadDoc, } from "../lib/chain.js";
+import { readProjectEnv } from "../lib/devvars.js";
+import { agentCardSchema, buildAgentCard, buildDomainCard, cardDrifted, fetchDoc, fetchJson, mergeCard, validateAgentCard, } from "../lib/identity-cards.js";
+import { appendDevVar, createMatrixAccount, matrixLogin, matrixPassword, matrixWhoami, roomsBotUrl, setDisplayName, } from "../lib/matrix-account.js";
+import { ed25519VerificationId, entityDocument, fundMsg, iidDocumentMsg, iidExists, oracleWalletSigner, spendableUixo, verificationMethodMsg, } from "../lib/oracle-account.js";
+import { buildSigner } from "../lib/session.js";
+const STEPS = [
+    "fund",
+    "iid",
+    "key",
+    "matrix",
+    "entity",
+    "orz",
+    "profile",
+    "domain",
+    "acard",
+    "linked",
+    "service",
+    "backlink",
+    "index",
+];
+/** The vars every step reads before anything runs — a project missing one is not provisionable. */
+const REQUIRED_VARS = ["ORACLE_ADDRESS", "ORACLE_DID", "ORACLE_MATRIX_USER_ID"];
+/** Gas for the oracle's own `MsgEvaluateClaim` txs — the oracle pays its own chain fees, never the
+ *  AuthHub session's. 1 IXO (`STANDARD_FEE` in `../lib/chain.ts` charges 150000uixo per tx this CLI
+ *  signs), so one top-up funds several of those before the wallet needs another. */
+const FUND_UIXO = "1000000";
+/**
+ * The oracle's `#eval` service becomes a permanent, publicly-discoverable chain record — so plain
+ * `http` is only tolerated for a localhost endpoint (a devnet dry run against `wrangler dev`), never
+ * for anything a real portal would resolve.
+ */
+function resolveKitUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        fail(`--kit-url '${value}' is not a valid URL`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        fail(`--kit-url must be http or https, got '${url.protocol}'`);
+    }
+    const isLocalhost = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+    if (url.protocol === "http:" && !isLocalhost) {
+        fail(`--kit-url '${value}' uses plain http for a non-localhost host — use https ` +
+            "(plain http is only allowed for localhost, e.g. a local `wrangler dev` dry run)");
+    }
+    return value;
+}
+function resolveStep(value) {
+    if (value === undefined)
+        return undefined;
+    const step = STEPS.find((s) => s === value);
+    if (!step)
+        fail(`unknown --only '${value}' (${STEPS.join("|")})`);
+    return step;
+}
+/** One of the oracle's own keys, for the step that acts as the oracle — or a loud stop naming it. */
+function oracleKey(ctx, value, envVar, step) {
+    return (value ??
+        fail(`step '${step}' acts as the oracle itself and needs ${envVar} — set it in ${ctx.envFileLabel} ` +
+            "(only iid, key and matrix use the oracle's keys; every other step runs on the AuthHub session)"));
+}
+/**
+ * Planned before the entity exists — a dry run on a fresh oracle, where there is nothing to read
+ * yet and the answer is always `do`. Reaching the `run` means `--only` skipped the step that
+ * creates the entity, which is a mistake worth saying out loud rather than half-doing.
+ */
+const afterEntity = (what) => ({
+    detail: `${what} — after the entity is created`,
+    run: async () => fail("no oracle entity yet — run `oracle init` without --only (or --only entity first)"),
+});
+/**
+ * Every step that decides from entity state reads the entity's IID document from the CHAIN, never
+ * blocksync — observed live on devnet: the indexer listed a resource 15+ minutes late while the
+ * chain had it, and a lagging "not anchored yet" makes a re-run broadcast a duplicate the chain
+ * rejects outright (`duplicated resource id {id}#pro`). Blocksync is left with only the two
+ * questions the document cannot answer: which entity an address owns, and who owns the protocol.
+ *
+ * Absent is not a skip-reason here — the entity DID came from a creation tx or from blocksync, so
+ * "no document" means the wrong network or a chain that lost it, and guessing either way would
+ * broadcast against the wrong entity.
+ */
+async function entityState(ctx, did) {
+    return ((await entityDocument(ctx.rpc, did)) ??
+        fail(`${did} has no IID document on ${ctx.network} (${ctx.rpc}) — wrong --network?`));
+}
+/** Every HTTP call whose failure is only a skip or a warning (the kit probe, the `#orz` doc, the
+ *  indexer) carries this deadline: a `wrangler dev` still booting accepts the socket and answers
+ *  nothing, which hung a live dry run for 32 minutes — an optional call must never do that. */
+const HTTP_TIMEOUT_MS = 10_000;
+/**
+ * The `granteeAddress` inside an already-anchored `#orz` document — what binds an entity to this
+ * oracle (`resolveOracleEntity`), and what a STALE one (the oracle identity was rotated after `#orz`
+ * was anchored) is caught by. `null` when the doc names no grantee; `undefined` when it cannot be
+ * READ (media down, a timeout) — which is not an answer: an unreadable `#orz` may be this oracle's.
+ */
+async function orzGrantee(orz) {
+    const doc = (await fetchDoc(orz))?.json;
+    if (!doc || typeof doc !== "object")
+        return undefined;
+    return typeof doc.granteeAddress === "string" ? doc.granteeAddress : null;
+}
+/**
+ * What binds an entity to THIS oracle, or null when nothing does: `#orz.granteeAddress ===
+ * ORACLE_ADDRESS` — the portal's own entity→account bridge, keyed on the oracle's runtime identity,
+ * so a moved host still matches — else `#eval === --kit-url`, which `entity` writes inline (a run
+ * that died before `orz` anchored). An `#orz` that cannot be READ is not "not ours": the run stops
+ * rather than mint a second entity for an oracle whose own `#orz` was down for a moment.
+ */
+async function bindingOf(ctx, did, doc) {
+    const orz = doc.linkedResource.find((r) => r.id.endsWith("#orz"));
+    const grantee = orz ? await orzGrantee(orz) : null;
+    if (grantee === ctx.address)
+        return `#orz grants ${ctx.address}`;
+    if (doc.service.some((s) => s.id.endsWith("#eval") && s.serviceEndpoint === ctx.kitUrl)) {
+        return `#eval is ${ctx.kitUrl}`;
+    }
+    if (grantee === undefined) {
+        fail(`can't decide which entity is this oracle's — the #orz of ${did} could not be read; retry (or set ORACLE_ENTITY_DID)`);
+    }
+    return null;
+}
+/**
+ * Which oracle entity is THIS oracle's — never "the one the session owns": an AuthHub session may
+ * own several oracles' entities, and picking up another's would make every later step skip on (or
+ * write onto) the wrong one.
+ *
+ *   - `ORACLE_ENTITY_DID` set ⇒ that one, after checking it is an oracle entity the session owns,
+ *     that the chain has its document AND that it is bound to this oracle (`bindingOf`) — a pin
+ *     naming a sibling oracle's entity fails loudly, never a write onto it.
+ *   - else the session's oracle entities, each read from the CHAIN, matched by `bindingOf` — the
+ *     `#orz` link first, the `#eval` one only when no entity has the first.
+ *   - two candidates on the same link ⇒ refuse and ask for the pin; guessing would write onto one
+ *     of them at random.
+ */
+async function resolveOracleEntity(ctx, pinned) {
+    const owned = await ownedOracleEntities(ctx.blocksync, ctx.signer.address);
+    if (pinned) {
+        if (!owned.some((e) => e.id === pinned)) {
+            fail(`ORACLE_ENTITY_DID ${pinned} is not an oracle entity owned by this session (${ctx.signer.address}) on ${ctx.network} — wrong session, wrong network, or the indexer has not caught up with a just-created entity`);
+        }
+        const binding = await bindingOf(ctx, pinned, await entityState(ctx, pinned));
+        if (!binding) {
+            fail(`ORACLE_ENTITY_DID ${pinned} is not this oracle's — its #orz does not grant ${ctx.address} and its #eval is not ${ctx.kitUrl}; refusing to write to another oracle's entity`);
+        }
+        return { did: pinned, binding: `ORACLE_ENTITY_DID, ${binding}` };
+    }
+    const byAddress = [];
+    const byKitUrl = [];
+    for (const { id } of owned) {
+        const doc = await entityDocument(ctx.rpc, id);
+        if (!doc)
+            continue;
+        const binding = await bindingOf(ctx, id, doc);
+        if (binding?.startsWith("#orz"))
+            byAddress.push(id);
+        else if (binding)
+            byKitUrl.push(id);
+    }
+    const [matches, binding] = byAddress.length > 0
+        ? [byAddress, `#orz grants ${ctx.address}`]
+        : [byKitUrl, `#eval is ${ctx.kitUrl}`];
+    if (matches.length > 1) {
+        fail(`${matches.length} oracle entities owned by this session are bound to this oracle (${binding}): ${matches.join(", ")} — set ORACLE_ENTITY_DID to the one to provision`);
+    }
+    return matches[0] ? { did: matches[0], binding } : undefined;
+}
+/** Printed wherever a logo would go: optional (owner), but the portal and the console show a
+ *  placeholder without one. */
+const NO_LOGO = "no --logo: the portal and the console show a placeholder — pass --logo <url>";
+/** The OpenHands per-review price: what the running oracle publishes, else `--price-pay`. */
+function openhandsPrice(ctx, info) {
+    return (info.apiMicroUsd ??
+        ctx.pricePayMicroUsd ??
+        fail(`--openhands needs a price: ${ctx.kitUrl}/v1/info publishes no pricing.api for ${ctx.protocolDid} — pass --price-pay <n>`));
+}
+async function cardSource(ctx, info) {
+    return {
+        entityDid: ctx.entityDid ?? fail("no oracle entity to card"),
+        issuerDid: ctx.signer.did,
+        name: info.name,
+        description: info.description,
+        kitUrl: ctx.kitUrl,
+        ...(ctx.logo ? { logo: ctx.logo } : {}),
+        ...(info.evaluationFee ? { evaluationFee: info.evaluationFee } : {}),
+        ...(ctx.openhands ? { openhands: { amountMicroUsd: openhandsPrice(ctx, info) } } : {}),
+        ...(await ctx
+            .apiPrice()
+            .then((amountMicroUsd) => (amountMicroUsd === null ? {} : { api: { amountMicroUsd } }))),
+    };
+}
+/**
+ * A document still on Matrix media is re-anchored onto the Vault by the next run (the doc's own
+ * bytes, merged as usual): writes left Matrix media, which may stop answering unauthenticated
+ * reads. Reading it stays supported (`readLinkedDoc`); only where it lives changes.
+ */
+const onMatrixMedia = (r) => r.serviceEndpoint.includes("/_matrix/media/");
+/**
+ * The `domain` / `acard` decision: add the card when there is none; skip when every field the KIT
+ * owns already says what we would write (`cardDrifted`); else REPLACE it (delete + add, one tx) with
+ * the kit's fields MERGED onto the live card, so a provider's own additions survive. A card that
+ * cannot be read is left alone with a warning. Read from the chain's document, like every
+ * entity-state decision. `check` sees the card that would actually be written.
+ */
+async function cardPlan(ctx, card, resource, check = () => { }) {
+    const entityDid = ctx.entityDid ?? fail("no oracle entity to card");
+    const entity = await entityState(ctx, entityDid);
+    const anchored = entity.linkedResource.find((r) => r.id.endsWith(resource.fragment));
+    // Read by its address only: the proof is judged below, where a stale one is repaired.
+    const served = anchored ? await fetchDoc({ serviceEndpoint: anchored.serviceEndpoint }) : null;
+    const live = served?.json ?? null;
+    if (anchored && (live === null || typeof live !== "object")) {
+        // Unreadable is not "drifted": replacing a card we could not read would overwrite whatever the
+        // provider put there on the strength of a timeout.
+        return {
+            detail: `⚠ ${resource.fragment} on ${entityDid} could not be read (${anchored.serviceEndpoint}) — left as is; re-run to retry`,
+        };
+    }
+    const logo = Boolean(ctx.logo);
+    const liveCard = live;
+    const drifted = liveCard !== null && cardDrifted(resource.fragment, liveCard, card, logo);
+    // The proof must be the CID of the bytes served (ixo-oracles-cli's convention): a card anchored
+    // with a sha256-hex proof, or whose media changed under it, is re-anchored even when its content
+    // is current — nothing else would ever repair it.
+    const proofOk = served !== null && anchored?.proof === (await cidForBytes(served.bytes));
+    const moving = anchored !== undefined && onMatrixMedia(anchored);
+    if (liveCard && !drifted && proofOk && !moving) {
+        return { detail: `${resource.fragment} on ${entityDid} already carries this card` };
+    }
+    const doc = liveCard ? mergeCard(resource.fragment, liveCard, card, logo) : card;
+    check(doc);
+    const { label, ...rest } = resource;
+    const why = !liveCard
+        ? "add"
+        : drifted
+            ? "replace (drifted; merged onto the live card)"
+            : !proofOk
+                ? `replace (proof ${anchored?.proof} is not the CID of its bytes)`
+                : "replace (moves off Matrix media)";
+    return {
+        detail: `${why} ${label} — uploaded as ${ctx.signer.did}`,
+        run: () => anchorDoc(ctx, { ...rest, doc, identityDoc: true, replace: anchored?.id }),
+    };
+}
+// --- the steps ------------------------------------------------------------------------------------
+const PLAN = {
+    /** 1. The oracle's wallet pays its own chain fees — without this it cannot sign anything. */
+    async fund(ctx) {
+        const balance = await spendableUixo(ctx.rpc, ctx.address);
+        const want = BigInt(FUND_UIXO);
+        if (balance >= want) {
+            return { detail: `${ctx.address} holds ${balance}uixo (≥ ${want}uixo)` };
+        }
+        return {
+            detail: `send ${want}uixo → ${ctx.address} (holds ${balance}uixo)`,
+            run: async () => {
+                const msg = await fundMsg(ctx.signer.address, ctx.address, FUND_UIXO);
+                confirm({
+                    network: ctx.network,
+                    signer: ctx.signer.address,
+                    action: "MsgSend (fund the oracle's own wallet)",
+                    lines: [`to: ${ctx.address}`, `amount: ${FUND_UIXO}uixo`],
+                    fee: STANDARD_FEE,
+                }, ctx.yes);
+                const { hash } = await broadcast(ctx.signer, [msg], "oracle-init: fund");
+                console.log(`✓ sent ${FUND_UIXO}uixo → ${ctx.address} (tx ${hash})`);
+            },
+        };
+    },
+    /** 2. `did:ixo:<ORACLE_ADDRESS>` itself — what the claim bot and the UCAN Store resolve us by. */
+    async iid(ctx) {
+        const { exists } = await iidExists(ctx.rpc, ctx.did);
+        if (exists)
+            return { detail: `${ctx.did} already has an IID document` };
+        return {
+            detail: `MsgCreateIidDocument ${ctx.did} + service #matrix → ${ctx.matrixBase}`,
+            run: async () => {
+                const msg = await iidDocumentMsg(ctx.did, ctx.address, oracleKey(ctx, ctx.oracleSigner, "ORACLE_SECP_MNEMONIC", "iid").pubkey, ctx.matrixBase);
+                confirm({
+                    network: ctx.network,
+                    signer: `${ctx.address} (the ORACLE's own wallet)`,
+                    action: "MsgCreateIidDocument (the oracle's account DID)",
+                    lines: [`did: ${ctx.did}`, `service #matrix: ${ctx.matrixBase}`],
+                    fee: STANDARD_FEE,
+                }, ctx.yes);
+                const { transactionHash } = await oracleKey(ctx, ctx.oracleSigner, "ORACLE_SECP_MNEMONIC", "iid").signAndBroadcast([msg], "oracle-init: iid");
+                console.log(`✓ IID document ${ctx.did} created (tx ${transactionHash})`);
+            },
+        };
+    },
+    /** 3. The Ed25519 key every UCAN this oracle mints as its did:ixo is signed with. */
+    async key(ctx) {
+        const edPublicKey = oracleKey(ctx, ctx.edPublicKey, "SERVICE_ED25519_MNEMONIC", "key");
+        const vmId = ed25519VerificationId(ctx.did, edPublicKey);
+        const { verificationMethodIds } = await iidExists(ctx.rpc, ctx.did);
+        if (verificationMethodIds.includes(vmId)) {
+            return { detail: `${vmId} is already a verification method` };
+        }
+        return {
+            detail: `MsgAddVerification ${vmId} (authentication + assertionMethod)`,
+            run: async () => {
+                const msg = await verificationMethodMsg(ctx.did, ctx.address, edPublicKey);
+                confirm({
+                    network: ctx.network,
+                    signer: `${ctx.address} (the ORACLE's own wallet)`,
+                    action: "MsgAddVerification (the SERVICE_ED25519_MNEMONIC key)",
+                    lines: [`did: ${ctx.did}`, `verification method: ${vmId}`],
+                    fee: STANDARD_FEE,
+                }, ctx.yes);
+                const { transactionHash } = await oracleKey(ctx, ctx.oracleSigner, "ORACLE_SECP_MNEMONIC", "key").signAndBroadcast([msg], "oracle-init: key");
+                console.log(`✓ Ed25519 verification method added (tx ${transactionHash})`);
+            },
+        };
+    },
+    /** 4. The Matrix account the review-card lane posts as — the only producer of its access token. */
+    async matrix(ctx) {
+        // `matrixWhoami` answers null for ANY non-2xx (a rotated token, but also a homeserver blip), so
+        // null means "log in again", never "there is no account" — creation is idempotent anyway.
+        let why;
+        if (ctx.relogin)
+            why = "--relogin";
+        else if (!ctx.token)
+            why = `no ORACLE_MATRIX_ACCESS_TOKEN in ${ctx.envFileLabel}`;
+        else {
+            const who = await matrixWhoami(ctx.matrixBase, ctx.token);
+            if (who === ctx.mxid) {
+                return { detail: `${ctx.envFileLabel} holds a live token for ${ctx.mxid}` };
+            }
+            why =
+                who === null
+                    ? `the homeserver did not answer for ${ctx.envFileLabel}'s token (rotated, or a blip) — re-login`
+                    : `${ctx.envFileLabel}'s token belongs to ${who} — re-login`;
+        }
+        return {
+            detail: `${why}: create-if-absent + log in as ${ctx.mxid}, token → ${ctx.envFileLabel} (a re-login mints a new Matrix device)`,
+            run: async () => {
+                confirm({
+                    network: ctx.network,
+                    signer: `${ctx.address} (signs the rooms bot's challenge)`,
+                    action: "create + log in to the oracle's own Matrix account",
+                    lines: [
+                        `account: ${ctx.mxid}`,
+                        `rooms bot: ${roomsBotUrl(ctx.matrixBase)}`,
+                        `access token → ${ctx.envFileLabel} (never printed)`,
+                    ],
+                }, ctx.yes);
+                const secpMnemonic = oracleKey(ctx, ctx.secpMnemonic, "ORACLE_SECP_MNEMONIC", "matrix");
+                const password = matrixPassword(secpMnemonic);
+                await createMatrixAccount({ log: (message) => console.log(`  ${message}`) }, {
+                    homeserverUrl: ctx.matrixBase,
+                    address: ctx.address,
+                    secpMnemonic,
+                    password,
+                });
+                const token = await matrixLogin(ctx.matrixBase, ctx.mxid, password);
+                appendDevVar(ctx.envFile, "ORACLE_MATRIX_ACCESS_TOKEN", token);
+                ctx.token = token;
+                // The display name is what a reviewer sees on the oracle's cards. The running oracle knows
+                // its own; before it is deployed, the MXID is at least unambiguous.
+                const info = await ctx.kitInfo();
+                await setDisplayName(ctx.matrixBase, token, ctx.mxid, info?.name ?? ctx.mxid);
+                console.log(`✓ ${ctx.mxid} ready — ORACLE_MATRIX_ACCESS_TOKEN written to ${ctx.envFileLabel}`);
+                console.log("  set it deployed with: wrangler secret put ORACLE_MATRIX_ACCESS_TOKEN");
+            },
+        };
+    },
+    /** 5. The entity — one tx carrying both services and the protocol edge. */
+    async entity(ctx) {
+        if (ctx.entityDid) {
+            return { detail: `${ctx.entityDid} is this oracle's (${ctx.entityBinding})` };
+        }
+        return {
+            detail: `MsgCreateEntity (oracle) owned by ${ctx.signer.did}, carrying #matrix, #eval and the protocol edge — none of this session's oracle entities is bound to this oracle (#orz granting ${ctx.address}, or #eval at ${ctx.kitUrl}); if you created one moments ago, wait for the indexer before --yes or a second entity is minted`,
+            run: async () => {
+                ctx.entityDid = await createOracleEntity(ctx);
+            },
+        };
+    },
+    /** 6. `#orz` — how the portal maps this entity to the account that holds its claim authz. */
+    async orz(ctx) {
+        if (!ctx.entityDid)
+            return afterEntity("#orz oracleAuthZConfig");
+        const entity = await entityState(ctx, ctx.entityDid);
+        const anchored = entity.linkedResource.find((r) => r.id.endsWith("#orz"));
+        if (anchored) {
+            // The address the portal grants claim authz to is baked into the anchored bytes, so rotating
+            // the oracle identity leaves the OLD one on chain and this step still says "already". The
+            // chain has no update for a LinkedResource and `MsgDeleteLinkedResource` is out of scope, so
+            // the most a re-run can do is name it.
+            const grantee = await orzGrantee(anchored);
+            if (typeof grantee === "string" && grantee !== ctx.address) {
+                return {
+                    detail: `⚠ #orz on ${ctx.entityDid} grants ${grantee}, not ORACLE_ADDRESS ${ctx.address} — re-anchoring it is manual (this command cannot replace a LinkedResource)`,
+                };
+            }
+            if (!onMatrixMedia(anchored))
+                return { detail: `#orz already on ${ctx.entityDid}` };
+            const live = (await fetchDoc(anchored))?.json ?? null;
+            if (live === null || typeof live !== "object") {
+                return {
+                    detail: `⚠ #orz on ${ctx.entityDid} could not be read (${anchored.serviceEndpoint}) — left as is; re-run to retry`,
+                };
+            }
+            return {
+                detail: `replace #orz (moves off Matrix media, same document) — uploaded as ${ctx.signer.did}`,
+                run: () => anchorDoc(ctx, {
+                    fragment: "#orz",
+                    type: anchored.type,
+                    description: anchored.description || "Oracle AuthZ Config",
+                    filename: "authz.json",
+                    doc: live,
+                    memo: "orz",
+                    replace: anchored.id,
+                }),
+            };
+        }
+        return {
+            detail: `#orz oracleAuthZConfig → granteeAddress ${ctx.address}`,
+            run: async () => {
+                // qiforge `src/utils/entity.ts:142-193` (`createAuthZConfig`), field for field — the doc at
+                // :155-175, the resource's own fields at :183-192. The two load-bearing ones are
+                // `granteeAddress` (the portal resolves the oracle's auth DID from it) and
+                // `requiredPermissions` (what its Grant-Role flow offers to grant).
+                const doc = {
+                    "@context": [
+                        "https://schema.org",
+                        {
+                            ixo: "https://w3id.org/ixo/context/v1",
+                            oracle: { "@id": ctx.entityDid, "@type": "@id" },
+                        },
+                    ],
+                    "@type": "Service",
+                    "@id": "oracle:OracleAuthorization",
+                    name: "OracleAuthorization",
+                    description: "OracleAuthorization",
+                    serviceType: "OracleClaimAuthorizationService",
+                    requiredPermissions: ["/ixo.claims.v1beta1.MsgCreateClaimAuthorization"],
+                    granteeAddress: ctx.address,
+                    granterAddress: "",
+                    // Decorative (the name a portal shows lives in `#pro`), so an undeployed oracle anchors
+                    // "" rather than blocking the step on a kit that isn't up yet.
+                    oracleName: (await ctx.kitInfo())?.name ?? "",
+                };
+                await anchorDoc(ctx, {
+                    fragment: "#orz",
+                    type: "oracleAuthZConfig",
+                    // Decorative — the LinkedResource description, not a lookup key. qiforge anchors the typo
+                    // "Orale AuthZ Config" (ixo-oracles-cli src/utils/entity.ts:190); we keep the correct
+                    // spelling, matching the portal's own producer (impacts-x-web entityCreation.ts:316).
+                    description: "Oracle AuthZ Config",
+                    filename: "authz.json",
+                    doc,
+                    memo: "orz",
+                });
+            },
+        };
+    },
+    /** 7. `#pro` — the name/description a portal lists, taken from the oracle that is actually running. */
+    async profile(ctx) {
+        if (!ctx.entityDid)
+            return afterEntity("#pro profile");
+        const entity = await entityState(ctx, ctx.entityDid);
+        const anchored = entity.linkedResource.find((r) => r.id.endsWith("#pro"));
+        if (anchored) {
+            // Add-only, with ONE exception: a `--logo` the live profile does not carry. The portal's
+            // avatar is `#pro.logo`, so a logo passed after the first run would otherwise never show.
+            // The live profile is the base — everything else in it (a hand-edited name, a location)
+            // stays exactly as it is.
+            const moving = onMatrixMedia(anchored);
+            if (!ctx.logo && !moving)
+                return { detail: `#pro already on ${ctx.entityDid}` };
+            const live = (await fetchDoc(anchored))?.json ?? null;
+            if (live === null || typeof live !== "object") {
+                return {
+                    detail: `⚠ #pro on ${ctx.entityDid} could not be read (${anchored.serviceEndpoint}) — left as is; re-run to retry`,
+                };
+            }
+            const profile = live;
+            const logo = ctx.logo || profile.logo;
+            if (profile.logo === logo && !moving) {
+                return { detail: `#pro already on ${ctx.entityDid}, with logo ${ctx.logo}` };
+            }
+            return {
+                detail: `${profile.logo === logo
+                    ? "replace #pro (moves off Matrix media, same profile)"
+                    : `replace #pro logo: ${String(profile.logo || "(none)")} → ${ctx.logo} (merged onto the live profile)`} — uploaded as ${ctx.signer.did}`,
+                run: () => anchorDoc(ctx, {
+                    fragment: "#pro",
+                    type: "Settings",
+                    description: "Profile",
+                    filename: "profile.json",
+                    doc: { ...profile, logo },
+                    memo: "profile",
+                    identityDoc: true,
+                    replace: anchored.id,
+                }),
+            };
+        }
+        const info = await ctx.kitInfo();
+        if (!info) {
+            // Not a failure: the profile is the one step that needs the oracle deployed, and every other
+            // step still has to run for a provider who is doing this before their first deploy.
+            return { detail: `${ctx.kitUrl}/v1/info not reachable — re-run after deploy` };
+        }
+        return {
+            detail: `#pro Settings → "${info.name}" from ${ctx.kitUrl}/v1/info — uploaded as ${ctx.signer.did}`,
+            run: async () => {
+                // qiforge `src/utils/entity.ts:477-525` (`addProfile`) — the doc at :490-506, the resource's
+                // own fields at :515-524. `orgName`/`brand`/`location`/`image` are qiforge's separate
+                // prompts; the oracle's own `/v1/info` is the only source here, so the names are all it and
+                // the rest are empty (a portal reads them as absent either way).
+                const doc = {
+                    "@context": {
+                        ixo: "https://w3id.org/ixo/ns/protocol/",
+                        "@id": "@type",
+                        type: "@type",
+                        "@protected": false,
+                    },
+                    id: "ixo:entity#profile",
+                    type: "profile",
+                    orgName: info.name,
+                    name: info.name,
+                    image: "",
+                    logo: ctx.logo,
+                    brand: info.name,
+                    location: "",
+                    description: info.description,
+                };
+                await anchorDoc(ctx, {
+                    fragment: "#pro",
+                    type: "Settings",
+                    description: "Profile",
+                    filename: "profile.json",
+                    doc,
+                    memo: "profile",
+                    identityDoc: true,
+                });
+            },
+        };
+    },
+    /** 8. `#dmn` — the domain card the indexer, the portal and the console list this oracle by. */
+    async domain(ctx) {
+        if (!ctx.entityDid)
+            return afterEntity("#dmn domainCard");
+        const info = await ctx.kitInfo();
+        if (!info)
+            return { detail: `${ctx.kitUrl}/v1/info not reachable — re-run after deploy` };
+        const card = buildDomainCard(await cardSource(ctx, info));
+        return cardPlan(ctx, card, {
+            fragment: "#dmn",
+            type: "domainCard",
+            description: "Domain Card",
+            filename: "domainCard.json",
+            memo: "domain",
+            label: `#dmn domainCard "${info.name}"${ctx.logo ? ` (logo ${ctx.logo})` : ` (${NO_LOGO})`}`,
+        });
+    },
+    /** 9. `#acard` — the Agent Card the portal's contract flow reads (`fetchAgentCard`). */
+    async acard(ctx) {
+        if (!ctx.entityDid)
+            return afterEntity("#acard agentCard");
+        const info = await ctx.kitInfo();
+        if (!info)
+            return { detail: `${ctx.kitUrl}/v1/info not reachable — re-run after deploy` };
+        const card = buildAgentCard(await cardSource(ctx, info));
+        if (card.credentialSubject.services.length === 0) {
+            return {
+                detail: `nothing to card — ${ctx.kitUrl} publishes no evaluation pricing and no Decision API price for ${ctx.protocolDid}`,
+            };
+        }
+        const { schema, source } = await agentCardSchema(NETWORKS[ctx.network].engineHost);
+        const services = card.credentialSubject.services.map((s) => s.id).join(", ");
+        return cardPlan(ctx, card, {
+            fragment: "#acard",
+            type: "agentCard",
+            description: "Agent Card",
+            filename: "agentCard.json",
+            memo: "acard",
+            label: `#acard agentCard "${info.name}" (services: ${services})`,
+        }, 
+        // Before anything is planned, let alone uploaded — and on the card that would really be
+        // written, the provider's merged-in services included: a card the engine refuses to parse is
+        // a bug here (or schema drift), and anchoring it would put an unreadable card in front of
+        // every portal that lists this oracle.
+        (doc) => {
+            const errors = validateAgentCard(doc, schema);
+            if (errors.length > 0) {
+                fail(`the Agent Card fails ${source}:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
+            }
+        });
+    },
+    /** 10. The oracle→protocol edge the portal's marketplace query filters on. */
+    async linked(ctx) {
+        if (!ctx.entityDid)
+            return afterEntity(`linkedEntity → ${ctx.protocolDid} (protocol)`);
+        const entityDid = ctx.entityDid;
+        // The LIVE entity, never a value carried from step 5: this is what makes the step correct
+        // whether the edge arrived inline with creation or is missing from an oracle made years ago.
+        const entity = await entityState(ctx, entityDid);
+        if (entity.linkedEntity.some((le) => le.id === ctx.protocolDid && le.relationship === "protocol")) {
+            return { detail: `edge → ${ctx.protocolDid} already on ${entityDid}` };
+        }
+        return {
+            detail: `MsgAddLinkedEntity → ${ctx.protocolDid} (${ctx.protocolType}, relationship: protocol)`,
+            run: async () => {
+                const msg = await addLinkedEntityMsg(entityDid, { id: ctx.protocolDid, type: ctx.protocolType, relationship: "protocol", service: "" }, ctx.signer.address);
+                confirm({
+                    network: ctx.network,
+                    signer: ctx.signer.address,
+                    action: "MsgAddLinkedEntity (oracle → protocol)",
+                    lines: [
+                        `oracle: ${entityDid}`,
+                        `protocol: ${ctx.protocolDid} (${ctx.protocolType})`,
+                        "relationship: protocol",
+                    ],
+                    fee: STANDARD_FEE,
+                }, ctx.yes);
+                const { hash } = await broadcast(ctx.signer, [msg], "oracle-init: linked");
+                console.log(`✓ linkedEntity → ${ctx.protocolDid} added (tx ${hash})`);
+            },
+        };
+    },
+    /** 11. `#eval` — the endpoint a commissioner's portal calls. Re-pointable, not just creatable. */
+    async service(ctx) {
+        if (!ctx.entityDid)
+            return afterEntity(`#eval EvalOracleAPI → ${ctx.kitUrl}`);
+        const entityDid = ctx.entityDid;
+        const entity = await entityState(ctx, entityDid);
+        const current = entity.service.find((s) => s.id.endsWith("#eval"));
+        if (current?.serviceEndpoint === ctx.kitUrl) {
+            return { detail: `#eval already points at ${ctx.kitUrl}` };
+        }
+        const service = { id: "{id}#eval", type: "EvalOracleAPI", serviceEndpoint: ctx.kitUrl };
+        return {
+            detail: current
+                ? `re-point #eval: ${current.serviceEndpoint} → ${ctx.kitUrl}`
+                : `#eval EvalOracleAPI → ${ctx.kitUrl}`,
+            run: async () => {
+                // A moved oracle (a real domain after a dry run on a tunnel) needs the OLD service gone, and
+                // the chain has no "update": delete + add, in ONE tx, exactly as qiforge's `updateOracleDomain`
+                // does (`src/utils/entity.ts:199-256`) — split across two txs the entity would briefly have
+                // no endpoint at all.
+                const msgs = current
+                    ? [
+                        await deleteServiceMsg(entityDid, "{id}#eval", ctx.signer.address),
+                        await addServiceMsg(entityDid, service, ctx.signer.address),
+                    ]
+                    : [await addServiceMsg(entityDid, service, ctx.signer.address)];
+                confirm({
+                    network: ctx.network,
+                    signer: ctx.signer.address,
+                    action: current ? "MsgDeleteService + MsgAddService (#eval)" : "MsgAddService (#eval)",
+                    lines: [
+                        `oracle: ${entityDid}`,
+                        ...(current ? [`current serviceEndpoint: ${current.serviceEndpoint}`] : []),
+                        `serviceEndpoint: ${ctx.kitUrl}`,
+                    ],
+                    fee: STANDARD_FEE,
+                }, ctx.yes);
+                const { hash } = await broadcast(ctx.signer, msgs, "oracle-init: service");
+                console.log(`✓ #eval → ${ctx.kitUrl} (tx ${hash})`);
+            },
+        };
+    },
+    /**
+     * 12. The PROTOCOL's edge back to the oracle. The portal's Authorization tab lists an entity's
+     * oracles from exactly this, so the link has to exist in BOTH directions for its action blocks to
+     * work — and it is signed by the session, which must therefore own the protocol.
+     */
+    async backlink(ctx) {
+        if (!ctx.entityDid)
+            return afterEntity(`linkedEntity → this oracle on ${ctx.protocolDid}`);
+        const entityDid = ctx.entityDid;
+        const protocol = await entityState(ctx, ctx.protocolDid);
+        if (protocol.linkedEntity.some((le) => le.id === entityDid && le.relationship === "oracle")) {
+            return { detail: `edge → ${entityDid} already on ${ctx.protocolDid}` };
+        }
+        const edge = { id: entityDid, type: "oracle", relationship: "oracle", service: "" };
+        // The one question the IID document does not answer: the entity module's `owner` is not a field
+        // on it (`controller` is who may write the document, which a transfer need not have moved), so
+        // the "is it ours to sign?" half stays a blocksync read — a stale answer here costs a wrong
+        // message, never a duplicate broadcast.
+        const { owner } = await resolveEntity(ctx.blocksync, ctx.protocolDid);
+        if (owner !== ctx.signer.address) {
+            // Not ours to sign: say exactly what the protocol's owner has to add.
+            return {
+                detail: `${ctx.protocolDid} is owned by ${owner ?? "(unknown)"}, not this session — ask them to add: ${JSON.stringify(edge)}`,
+            };
+        }
+        return {
+            detail: `MsgAddLinkedEntity on ${ctx.protocolDid} → ${entityDid} (relationship: oracle)`,
+            run: async () => {
+                const msg = await addLinkedEntityMsg(ctx.protocolDid, edge, ctx.signer.address);
+                confirm({
+                    network: ctx.network,
+                    signer: ctx.signer.address,
+                    action: "MsgAddLinkedEntity (protocol → oracle, the back-link)",
+                    lines: [`protocol: ${ctx.protocolDid}`, `oracle: ${entityDid}`, "relationship: oracle"],
+                    fee: STANDARD_FEE,
+                }, ctx.yes);
+                const { hash } = await broadcast(ctx.signer, [msg], "oracle-init: backlink");
+                console.log(`✓ linkedEntity → ${entityDid} added on the protocol (tx ${hash})`);
+            },
+        };
+    },
+    /**
+     * 13. Tell the domain indexer the entity exists — qiforge `src/utils/entity.ts:549-579`. Last, so
+     * it reads the `#dmn` the `domain` step just anchored. Skipped when the indexer already serves
+     * THAT card, finished: its `blockchain_version_id` is the anchored `#dmn` resource's proof
+     * (domain-indexer `types/indexed-entity.ts`) and its `status` is `completed` — so a changed card,
+     * or one still `pending`/`processing`, always re-submits. A dry run asks the indexer nothing: its
+     * `GET /domain-cards/:did` is not a pure read (it stamps `last_accessed_at`), so the check waits
+     * for `--yes`.
+     */
+    async index(ctx) {
+        const base = NETWORKS[ctx.network].domainIndexer;
+        const url = `${base}/index`;
+        if (!ctx.entityDid)
+            return afterEntity(`POST ${url}`);
+        const entityDid = ctx.entityDid;
+        const dmn = (await entityState(ctx, entityDid)).linkedResource.find((r) => r.id.endsWith("#dmn"));
+        if (dmn && ctx.yes) {
+            const indexed = (await fetchJson(`${base}/domain-cards/${encodeURIComponent(entityDid)}`));
+            if (indexed?.blockchain_version_id === dmn.proof && indexed.status === "completed") {
+                return { detail: `the indexer already serves the anchored #dmn (proof ${dmn.proof})` };
+            }
+        }
+        const check = dmn && !ctx.yes ? " — whether the indexer already serves this #dmn is checked on --yes" : "";
+        return {
+            detail: `POST ${url} { did: ${entityDid} }${dmn ? check : " — no #dmn anchored yet"}`,
+            run: async () => {
+                // A warning, never fatal (qiforge's own `log.warn`): the indexer is a convenience, the
+                // chain record is the truth, and nothing this command did needs undoing if it is down.
+                try {
+                    const res = await fetch(url, {
+                        method: "POST",
+                        headers: { accept: "application/json", "content-type": "application/json" },
+                        body: JSON.stringify({ did: entityDid }),
+                        signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+                    });
+                    if (!res.ok) {
+                        console.log(`⚠ domain indexer refused ${entityDid}: ${res.status} ${await res.text()}`);
+                        return;
+                    }
+                    console.log(`✓ ${entityDid} submitted to the domain indexer`);
+                }
+                catch (err) {
+                    console.log(`⚠ domain indexer unreachable (${err instanceof Error ? err.message : String(err)})`);
+                }
+            },
+        };
+    },
+};
+// --- the writes the steps share -------------------------------------------------------------------
+async function createOracleEntity(ctx) {
+    const { customMessages, ixo, utils } = await import("@ixo/impactxclient-sdk");
+    const now = Date.now();
+    confirm({
+        network: ctx.network,
+        signer: ctx.signer.address,
+        action: "MsgCreateEntity (oracle)",
+        lines: [
+            `owner: ${ctx.signer.did} (the AuthHub session that ran this — see the header comment)`,
+            `relayerNode: ${NETWORKS[ctx.network].relayerNodeDid}`,
+            `service #matrix: ${ctx.matrixBase}`,
+            `service #eval: ${ctx.kitUrl}`,
+            `linkedEntity → protocol: ${ctx.protocolDid} (${ctx.protocolType}, relationship: protocol)`,
+        ],
+        fee: STANDARD_FEE,
+    }, ctx.yes);
+    const msg = {
+        typeUrl: "/ixo.entity.v1beta1.MsgCreateEntity",
+        value: ixo.entity.v1beta1.MsgCreateEntity.fromPartial({
+            entityType: "oracle",
+            entityStatus: 0,
+            context: [],
+            // The exact shape `createEntity` (lib/chain.ts) uses for a protocol entity — the two entity
+            // kinds this CLI creates stay identical here.
+            verification: customMessages.iid.createIidVerificationMethods({
+                did: ctx.signer.did,
+                pubkey: await ctx.signer.getPubkey(),
+                address: ctx.signer.address,
+                controller: ctx.signer.did,
+                type: "secp",
+            }),
+            controller: [ctx.signer.did],
+            ownerAddress: ctx.signer.address,
+            ownerDid: ctx.signer.did,
+            relayerNode: NETWORKS[ctx.network].relayerNodeDid,
+            // Both services AND the protocol edge go in the SAME tx as creation — a fresh oracle needs
+            // exactly one broadcast, never a create-then-patch dance (`MsgCreateEntity.fromPartial`
+            // recurses `Service.fromPartial`/`LinkedEntity.fromPartial` over these plain objects itself).
+            service: [
+                { id: "{id}#matrix", type: "MatrixHomeServer", serviceEndpoint: ctx.matrixBase },
+                { id: "{id}#eval", type: "EvalOracleAPI", serviceEndpoint: ctx.kitUrl },
+            ],
+            linkedEntity: [
+                { id: ctx.protocolDid, type: ctx.protocolType, relationship: "protocol", service: "" },
+            ],
+            // An entity with no window is not shown by the portal — qiforge's own now → +100y
+            // (`src/utils/entity.ts:107-110`).
+            startDate: utils.proto.toTimestamp(new Date(now)),
+            endDate: utils.proto.toTimestamp(new Date(now + 100 * 365 * 24 * 60 * 60 * 1000)),
+        }),
+    };
+    const { hash, res } = await broadcast(ctx.signer, [msg], "oracle-init: entity");
+    const entityDid = entityDidFromEvents(res.events);
+    if (!entityDid)
+        fail(`entity created (tx ${hash}) but the DID could not be read from tx events`);
+    console.log(`✓ oracle entity created: ${entityDid} (tx ${hash})`);
+    // Pinned BEFORE anything else can fail: blocksync lists a new entity minutes late, so a re-run
+    // after a failure further down would find no entity bound to this oracle and mint a second one.
+    // With the pin, the re-run takes the `ORACLE_ENTITY_DID` path instead.
+    appendDevVar(ctx.envFile, "ORACLE_ENTITY_DID", entityDid);
+    ctx.entityPinned = true;
+    console.log(`  ORACLE_ENTITY_DID written to ${ctx.envFileLabel} — a re-run uses it`);
+    // Every step after this one reads the LIVE entity to decide whether to write, so the document has
+    // to be readable first or they would all re-add what the creation tx already carried. The tx is
+    // committed by now, so the chain answers immediately — the retry is only for the node behind the
+    // RPC endpoint being a beat behind the one that accepted the broadcast.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        if (attempt > 0)
+            await new Promise((r) => setTimeout(r, 1000));
+        if (await entityDocument(ctx.rpc, entityDid))
+            return entityDid;
+    }
+    fail(`entity ${entityDid} created but its IID document is not readable on ${ctx.rpc} yet — re-run \`oracle init --yes\` to finish the remaining steps`);
+}
+/**
+ * Store a JSON document on the IXO Vault (else the IPFS gateway — `uploadDoc`), signed as the
+ * entity's OWNER, the AuthHub session, and anchor it as a `LinkedResource`. Two writes, two confirm
+ * gates, one step.
+ */
+async function anchorDoc(ctx, resource) {
+    const entityDid = ctx.entityDid ?? fail("no oracle entity to anchor onto");
+    const bytes = new TextEncoder().encode(JSON.stringify(resource.doc));
+    confirm({
+        network: ctx.network,
+        signer: ctx.signer.did,
+        action: `upload ${resource.filename} to the IXO Vault (else the IPFS gateway)`,
+        lines: [`${bytes.byteLength} bytes → ${resource.fragment} on ${entityDid}`],
+    }, ctx.yes);
+    const { url, cid } = await uploadDoc(ctx.network, sessionDocSigner(ctx.signer), bytes, resource.filename, resource.identityDoc ? "application/ld+json" : "application/json");
+    const proof = resource.identityDoc ? cid : await sha256Hex(bytes);
+    const add = await addLinkedResourceMsg(entityDid, {
+        id: `{id}${resource.fragment}`,
+        type: resource.type,
+        description: resource.description,
+        mediaType: "application/json",
+        serviceEndpoint: url,
+        proof,
+        encrypted: "false",
+        right: "",
+    }, ctx.signer.address);
+    const msgs = resource.replace
+        ? [await deleteLinkedResourceMsg(entityDid, resource.replace, ctx.signer.address), add]
+        : [add];
+    confirm({
+        network: ctx.network,
+        signer: ctx.signer.address,
+        action: resource.replace
+            ? `MsgDeleteLinkedResource + MsgAddLinkedResource ${resource.fragment} (${resource.type})`
+            : `MsgAddLinkedResource ${resource.fragment} (${resource.type})`,
+        lines: [
+            `entity: ${entityDid}`,
+            ...(resource.replace ? [`replacing: ${resource.replace}`] : []),
+            `serviceEndpoint: ${url}`,
+            `proof: ${proof}`,
+        ],
+        fee: STANDARD_FEE,
+    }, ctx.yes);
+    const { hash } = await broadcast(ctx.signer, msgs, `oracle-init: ${resource.memo}`);
+    console.log(`✓ ${resource.fragment} ${resource.type} anchored (tx ${hash})`);
+}
+// --- the command ----------------------------------------------------------------------------------
+export async function run(argv) {
+    const { values } = parse(argv, {
+        options: {
+            protocol: { type: "string" },
+            "kit-url": { type: "string" },
+            network: { type: "string" },
+            "env-file": { type: "string" },
+            logo: { type: "string" },
+            openhands: { type: "boolean" },
+            "price-pay": { type: "string" },
+            only: { type: "string" },
+            relogin: { type: "boolean" },
+            yes: { type: "boolean" },
+        },
+    });
+    const protocolDid = values.protocol ?? fail("--protocol <did> is required");
+    const kitUrl = resolveKitUrl(values["kit-url"] ?? fail("--kit-url <http(s) url> is required"));
+    const network = resolveNetwork(values.network);
+    const only = resolveStep(values.only);
+    const yes = values.yes === true;
+    const openhands = values.openhands === true;
+    const pricePay = values["price-pay"];
+    if (pricePay !== undefined && !openhands)
+        fail("--price-pay only prices --openhands");
+    const pricePayMicroUsd = pricePay === undefined
+        ? undefined
+        : /^\d+(\.\d{1,6})?$/.test(pricePay) && Number(pricePay) > 0
+            ? Math.round(Number(pricePay) * 1_000_000)
+            : fail(`--price-pay must be a positive PAY amount (1 PAY = 1 USD), got '${pricePay}'`);
+    // ---- the oracle's own identity, from the project's own config files ----------------------------
+    const envFileLabel = values["env-file"] ?? ".dev.vars";
+    const envFile = resolve(process.cwd(), envFileLabel);
+    const env = (() => {
+        try {
+            return readProjectEnv(process.cwd(), { envFile: values["env-file"] });
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+    })();
+    const missing = REQUIRED_VARS.filter((key) => !env[key]);
+    if (missing.length > 0) {
+        fail(`missing ${missing.join(", ")} — set them in wrangler.jsonc "vars" or ${envFileLabel} ` +
+            "(`decision-oracle derive` prints the identity lines)");
+    }
+    const address = env.ORACLE_ADDRESS;
+    const did = `did:ixo:${address}`;
+    const matrixBase = NETWORKS[network].matrix.replace(/\/+$/, "");
+    const mxid = mxidFromDid(did, new URL(matrixBase).hostname);
+    // Both are DERIVED values a provider pasted in by hand — if either disagrees with ORACLE_ADDRESS,
+    // this command would write the wrong DID on chain or log into the wrong Matrix account, so they
+    // are checked before anything at all runs. (`ORACLE_ADDRESS` vs the mnemonic is asserted offline
+    // by `oracleWalletSigner` just below.)
+    if (env.ORACLE_DID !== did) {
+        fail(`ORACLE_DID (${env.ORACLE_DID}) is not ORACLE_ADDRESS's DID (${did})`);
+    }
+    if (env.ORACLE_MATRIX_USER_ID !== mxid) {
+        fail(`ORACLE_MATRIX_USER_ID (${env.ORACLE_MATRIX_USER_ID}) is not ${network}'s MXID for ${did} — expected ${mxid}`);
+    }
+    const signer = await buildSigner(network);
+    // Optional, but still asserted against ORACLE_ADDRESS up front whenever present.
+    const secpMnemonic = env.ORACLE_SECP_MNEMONIC || undefined;
+    const oracleSigner = secpMnemonic
+        ? await oracleWalletSigner(network, secpMnemonic, address)
+        : undefined;
+    const edPublicKey = env.SERVICE_ED25519_MNEMONIC
+        ? (await deriveServiceKey(env.SERVICE_ED25519_MNEMONIC)).publicKeyRaw
+        : undefined;
+    // Blocksync/RPC endpoints come ONLY from `NETWORKS[network]` (the `--network` flag), never the env
+    // file — see the identical note in `create-collection`/`publish-protocol`.
+    const blocksync = NETWORKS[network].blocksync;
+    const protocolEntity = await resolveEntity(blocksync, protocolDid);
+    if (!protocolEntity.type) {
+        fail(`protocol ${protocolDid} did not resolve on blocksync (indexer lag? wrong network/DID?)`);
+    }
+    let info;
+    let apiPrice;
+    const ctx = {
+        network,
+        yes,
+        relogin: values.relogin === true,
+        logo: values.logo ?? "",
+        openhands,
+        pricePayMicroUsd,
+        kitUrl,
+        blocksync,
+        rpc: NETWORKS[network].rpc,
+        matrixBase,
+        address,
+        did,
+        mxid,
+        secpMnemonic,
+        edPublicKey,
+        envFile,
+        envFileLabel,
+        token: env.ORACLE_MATRIX_ACCESS_TOKEN,
+        signer,
+        oracleSigner,
+        protocolDid,
+        protocolType: protocolEntity.type,
+        entityDid: undefined,
+        entityBinding: "",
+        entityPinned: false,
+        kitInfo: () => 
+        // A deadline, not just a catch: a `wrangler dev` mid-boot accepts the socket and answers
+        // nothing, which hung a live dry run for 32 minutes — a timeout reads as "not deployed yet",
+        // the same as a refused connection.
+        (info ??= fetch(`${kitUrl}/v1/info`, { signal: AbortSignal.timeout(HTTP_TIMEOUT_MS) })
+            .then(async (res) => {
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            if (typeof body.name !== "string")
+                return null;
+            const { evaluation, byProtocol, api } = body.pricing ?? {};
+            const apiMicroUsd = api
+                ? (api.byProtocol?.[protocolDid] ?? api.amountMicroUsd)
+                : undefined;
+            return {
+                name: body.name,
+                description: typeof body.description === "string" ? body.description : "",
+                ...(evaluation
+                    ? { evaluationFee: evaluationFeeFor({ evaluation, byProtocol }, protocolDid) }
+                    : {}),
+                ...(apiMicroUsd !== undefined ? { apiMicroUsd } : {}),
+            };
+        })
+            // Not deployed yet, or down — every caller here treats that as "no info", never a failure.
+            .catch(() => null)),
+        // The lane's public catalogue answers iff API_LANE is on (otherwise the lane's own 404), and
+        // its `price` IS `publishedPrice` — `byProtocol`, then `amountMicroUsd`, then the
+        // `API_PRICE_USD_CENTS` var — resolved by the running oracle itself, so the card can never
+        // advertise a price the facilitator would refuse.
+        apiPrice: () => (apiPrice ??= fetch(`${kitUrl}/v1/api/protocols`, {
+            signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+        })
+            .then(async (res) => {
+            if (!res.ok)
+                return null;
+            const { items } = (await res.json());
+            return items?.find((i) => i.protocolDid === protocolDid)?.price?.amountMicroUsd ?? null;
+        })
+            .catch(() => null)),
+    };
+    // The pin is per deployment: `env.<network>.vars` when wrangler.jsonc declares that env (where a
+    // provider keeps each network's entity), else the top-level vars — `.dev.vars` winning either way.
+    const pinned = (() => {
+        try {
+            return readProjectEnv(process.cwd(), { envFile: values["env-file"], env: network })
+                .ORACLE_ENTITY_DID;
+        }
+        catch {
+            return env.ORACLE_ENTITY_DID;
+        }
+    })();
+    const bound = await resolveOracleEntity(ctx, pinned || undefined);
+    ctx.entityDid = bound?.did;
+    ctx.entityBinding = bound?.binding ?? "";
+    ctx.entityPinned = bound?.binding.startsWith("ORACLE_ENTITY_DID") ?? false;
+    console.log(`signer  : ${signer.address} (${network})`);
+    console.log(`oracle  : ${did}`);
+    console.log(`entity  : ${ctx.entityDid ? `${ctx.entityDid} (${ctx.entityBinding})` : "(none yet)"}\n`);
+    for (const step of only ? [only] : STEPS) {
+        const plan = await PLAN[step](ctx);
+        console.log(`  ${step.padEnd(10)}${(plan.run ? "do" : "skip").padEnd(4)}  ${plan.detail}`);
+        if (yes)
+            await plan.run?.();
+    }
+    if (!yes) {
+        console.log("\n  DRY RUN — nothing signed, created or written. Re-run with --yes to execute.");
+    }
+    console.log("\n════ oracle ════");
+    console.log(`oracle entity DID : ${ctx.entityDid ?? "(not created yet)"}`);
+    if (ctx.entityDid && !ctx.entityPinned) {
+        console.log(`  set ORACLE_ENTITY_DID="${ctx.entityDid}" (a wrangler.jsonc var) — it pins this entity for every later run, and the review card names it`);
+    }
+    if (!ctx.logo) {
+        // Optional by the owner's call, but never silently: the full identity is mandatory, and a
+        // card without a logo is the one part of it a provider can still improve.
+        console.log("\n⚠ recommended: --logo <https url> — without it the domain card carries no logo, and the portal and the console show a placeholder");
+    }
+    if (ctx.entityDid) {
+        // The portal's marketplace query verbatim (impacts-x-web `gqlEvalOraclesByProtocol`): the edge
+        // filter lives under `iidById`, not on `entities` directly.
+        console.log("\nverify on blocksync (the portal's marketplace filter — oracles linked to this protocol):");
+        console.log(`  query { entities(filter: { type: { in: ["oracle", "oracle/evaluation"] }, iidById: { linkedEntity: { contains: [{ id: "${protocolDid}", relationship: "protocol" }] } } }) { nodes { id } } }`);
+    }
+    console.log("");
+    return 0;
+}
+//# sourceMappingURL=oracle-init.js.map