aimeat 2.2.0 → 2.3.0

package/dist/static/sdk-libs/exchange/format.js

@@ -0,0 +1,51 @@
+/**
+ * @file exchange/format.js
+ * @description Unit formatting for EXCHANGE figures. AIMEAT carries two units that must never be
+ *   added together or shown in each other's shape: money is an integer count of 6-decimal
+ *   micro-units in a named currency, morsels are plain integers and a throttle rather than a
+ *   currency. A figure that mixes them is not a rounding bug, it is a wrong number.
+ *
+ *   Money formatting itself belongs to aimeat-commerce and is NOT restated here — this delegates to
+ *   `AIMEAT.commerce.fmtMoney`, so the two libraries can never render "1.50 EUR" two different ways.
+ *   That is also why aimeat-commerce is a hard dependency of this library rather than a suggestion.
+ * @structure commerce() · fmtUnit(amount, unit, currency) · fmtMorsels(amount)
+ * @usage AIMEAT.exchange.fmtUnit(1500000, 'money', 'EUR')  // "1.50 EUR"
+ *        AIMEAT.exchange.fmtUnit(10, 'morsels')            // "10 morsels"
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+
+/** The aimeat-commerce surface, or null when it was not included. */
+function commerce() {
+  return (window.AIMEAT && window.AIMEAT.commerce) || null;
+}
+
+/** Morsels are plain integers — never a symbol, never a decimal, never an emoji. */
+export function fmtMorsels(amount) {
+  const n = Math.round(Number(amount) || 0);
+  return n + (Math.abs(n) === 1 ? ' morsel' : ' morsels');
+}
+
+/**
+ * Format one EXCHANGE figure in the unit it is actually denominated in.
+ *
+ * `unit: 'money'` (or any currency other than `morsel`) formats the integer micro-units through
+ * `AIMEAT.commerce.fmtMoney`; anything else formats plain morsels. The two are never combined into
+ * one figure — a capability priced in both is two prices, and an app should show them as two.
+ *
+ * @param {number} amount   Micro-units for money, whole morsels otherwise.
+ * @param {string} [unit]   `'money'` | `'morsels'` — or omit and pass a currency.
+ * @param {string} [currency]  `'EUR'` / `'USD'` when the unit is money.
+ * @returns {string}
+ * @throws {Error} When the unit is money and aimeat-commerce is not loaded — the alternative is
+ *   silently rendering micro-units as if they were euros, which is wrong by a factor of a million.
+ */
+export function fmtUnit(amount, unit, currency) {
+  const isMoney = unit === 'money' || (!!currency && currency !== 'morsel' && currency !== 'MORSEL');
+  if (!isMoney) return fmtMorsels(amount);
+  const c = commerce();
+  if (!c) {
+    throw new Error('AIMEAT.commerce is required to format money. Include aimeat-commerce.js before aimeat-exchange.js');
+  }
+  return c.fmtMoney(amount, currency);
+}

package/dist/static/sdk-libs/exchange/index.js

@@ -0,0 +1,70 @@
+/**
+ * @file exchange/index.js
+ * @description The aimeat-exchange library (NOSTE prompt 02, gap G19). Exposes AIMEAT.exchange — the
+ *   EXCHANGE marketplace from a BROWSER: browse and search listings, publish and manage your own,
+ *   read who is using them and what they have consumed, accept and switch off contracts, see what
+ *   you have spent and what you are owed, and work the demand side (needs and bids).
+ *
+ *   Until this existed the whole market was reachable only over REST-by-hand or by having an agent
+ *   drive MCP, which fits agent flows and fits nothing a human does in a page. Every selling app
+ *   needs this, which is why it is node core rather than an app-side helper.
+ *
+ *   SCOPE BOUNDARY. aimeat-commerce owns BUYING and money FORMATTING — checkout sessions, the 402
+ *   `accepts` surface, app-tool manifests, `fmtMoney`/`fmtAmount`/`MONEY_UNIT`. None of that is
+ *   restated here: this library depends on it for money rendering and defers to it for checkout,
+ *   and adds the market side — supply, listings, contracts, lineage, earnings.
+ *
+ *   SECURITY. It carries no secrets and asks for none. Seller payment credentials are server-side
+ *   and never readable. Authorisation is the server's job throughout: this sends the aimeat-auth
+ *   session and renders what comes back — it never decides who may see what.
+ * @structure imports the group modules (browse · sell · contracts · earnings · demand · format ·
+ *   odps-completeness), composes the AIMEAT.exchange surface, attaches it via _core/namespace.
+ * @usage
+ *   <script src="/v1/libs/aimeat-auth.js"></script>
+ *   <script src="/v1/libs/aimeat-commerce.js"></script>
+ *   <script src="/v1/libs/aimeat-exchange.js"></script>
+ *   const { offerings } = await AIMEAT.exchange.list({ q: 'company' });
+ *   const contract = await AIMEAT.exchange.accept(offerings[0].offeringId, { capUnits: 500 });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial: the EXCHANGE browser library (NOSTE prompt 02 / requirements R-K3).
+ */
+import { attach } from '../_core/namespace.js';
+import { info, list, search, get, odps, odpsYaml } from './browse.js';
+import {
+  publish, update, delist, stats, consumers, reconcile, providerHistory,
+  grants, grant, revokeGrant,
+} from './sell.js';
+import {
+  contracts, accept, off, history, spend, coordinateOf,
+  proposals, propose, acceptProposal, declineProposal, withdrawProposal,
+  startWork, deliverWork, work,
+} from './contracts.js';
+import { earnings } from './earnings.js';
+import { needs, postNeed, closeNeed, bids, bid, acceptBid } from './demand.js';
+import { fmtUnit, fmtMorsels } from './format.js';
+import { odpsCompleteness, ODPS_AUTHORED_FIELDS } from './odps-completeness.js';
+
+const exchange = {
+  // ── Browsing (public where the route is public) ──
+  info, list, search, get, odps, odpsYaml,
+
+  // ── Selling ──
+  publish, update, delist, stats, consumers, reconcile, providerHistory,
+  grants, grant, revokeGrant,
+
+  // ── Buying + contracts ──
+  contracts, accept, off, history, spend, coordinateOf,
+  proposals, propose, acceptProposal, declineProposal, withdrawProposal,
+  startWork, deliverWork, work,
+
+  // ── Earnings (read-only: the accrual, not a payout) ──
+  earnings,
+
+  // ── Demand ──
+  needs, postNeed, closeNeed, bids, bid, acceptBid,
+
+  // ── Helpers ──
+  fmtUnit, fmtMorsels, odpsCompleteness, ODPS_AUTHORED_FIELDS,
+};
+
+attach('exchange', exchange);

package/dist/static/sdk-libs/exchange/odps-completeness.js

@@ -0,0 +1,177 @@
+/**
+ * @file exchange/odps-completeness.js
+ * @description The ODPS fill-rate meter: given an offering, which Open Data Product Specification
+ *   v4.1 fields it fills and which are still blank, so an app can show a completeness bar whose
+ *   every gap is something the seller can actually go and fix.
+ *
+ *   WHAT IT MEASURES, and why that is the honest question. `tools/odps-coverage.ts` walks the whole
+ *   published v4.1 schema against a maximally-filled listing and splits every field three ways:
+ *   what AIMEAT DERIVES (product id, timestamps, status, pricing plans, access ports, licence
+ *   rights, observed usage — always present, never authored), what the PROVIDER authors (the `odps`
+ *   block, the provenance attestation, the listing's own framing), and what AIMEAT has no source
+ *   for at all. Counting the derived fields would put every listing above 60% on its first day and
+ *   move when the projection changed rather than when the seller did; counting the unreachable ones
+ *   would cap it below 100% forever. So this counts exactly the AUTHORED set — the same fields
+ *   `models/odps-schemas.ts` defines as "what the node cannot derive" — and each entry carries the
+ *   ODPS v4.1 path it lands on, so "missing" names a real place in a real document.
+ *
+ *   Deliberately dependency-free (no `window`, no fetch, no imports): the same function runs in the
+ *   browser bundle and in a Node test that checks it against the projection it describes.
+ * @structure ODPS_AUTHORED_FIELDS · valueAt · odpsCompleteness(offering)
+ * @usage const { percent, missing } = odpsCompleteness(offering);
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ *     Field set mirrors OdpsExtrasSchema + ProvenanceSchema + the listing's own framing, i.e. the
+ *     "provider must author" column of tools/odps-coverage.ts for ODPS v4.1.
+ */
+
+/**
+ * One measurable field: where it lives on the offering, where it lands in the ODPS document, and
+ * which part of the descriptor it belongs to.
+ * @typedef {Object} OdpsField
+ * @property {string} key     Dotted path on the OFFERING (`odps.valueProposition`, `provenance.source`, `title`).
+ * @property {string} path    Dotted path in the projected ODPS v4.1 document.
+ * @property {string} group   Grouping for a UI: framing · commitments · provenance · legal · support · governance.
+ * @property {string} label   Short human label.
+ */
+
+/**
+ * The fields a PROVIDER authors on an ODPS v4.1 descriptor. Order is presentation order: the ones a
+ * buyer reads first come first, so a completeness list doubles as a to-do list in priority order.
+ * @type {OdpsField[]}
+ */
+export const ODPS_AUTHORED_FIELDS = [
+  // ── Framing: what a buyer reads to decide ──
+  { key: 'title', path: 'product.details.name', group: 'framing', label: 'Title' },
+  { key: 'description', path: 'product.details.description', group: 'framing', label: 'Description' },
+  { key: 'odps.valueProposition', path: 'product.details.valueProposition', group: 'framing', label: 'Value proposition' },
+  { key: 'odps.productType', path: 'product.details.type', group: 'framing', label: 'Product type' },
+  { key: 'odps.categories', path: 'product.details.categories', group: 'framing', label: 'Categories' },
+  { key: 'tags', path: 'product.details.tags', group: 'framing', label: 'Tags' },
+  { key: 'odps.useCases', path: 'product.details.useCases', group: 'framing', label: 'Use cases' },
+  { key: 'odps.contentSample', path: 'product.details.contentSample', group: 'framing', label: 'Output sample' },
+  { key: 'odps.outputFileFormats', path: 'product.details.outputFileFormats', group: 'framing', label: 'Output formats' },
+  { key: 'odps.standards', path: 'product.details.standards', group: 'framing', label: 'Standards followed' },
+  { key: 'odps.productSeries', path: 'product.details.productSeries', group: 'framing', label: 'Product series' },
+  { key: 'odps.logoURL', path: 'product.details.logoURL', group: 'framing', label: 'Logo' },
+  { key: 'odps.brandSlogan', path: 'product.details.brandSlogan', group: 'framing', label: 'Slogan' },
+  { key: 'odps.recommendedDataProducts', path: 'product.details.recommendedDataProducts', group: 'framing', label: 'Related products' },
+
+  // ── Commitments: promises no observation can substitute for ──
+  { key: 'odps.sla', path: 'product.SLA.declarative', group: 'commitments', label: 'Service-level commitments' },
+  { key: 'odps.dataQuality', path: 'product.dataQuality.declarative', group: 'commitments', label: 'Data-quality commitments' },
+
+  // ── Provenance: where the material came from, and on what basis ──
+  { key: 'provenance.source', path: 'product.license.governance.ownership', group: 'provenance', label: 'Source' },
+  { key: 'provenance.legalBasis', path: 'product.license.governance.applicableLaws', group: 'provenance', label: 'Legal basis' },
+  { key: 'provenance.consentStatus', path: 'product.license.governance.audit', group: 'provenance', label: 'Consent status' },
+  { key: 'provenance.retention', path: 'product.license.governance.audit', group: 'provenance', label: 'Retention' },
+  { key: 'provenance.transformations', path: 'product.details.versionNotes', group: 'provenance', label: 'Transformations applied' },
+  { key: 'provenance.snapshotHash', path: 'product.dataAccess[].checksum', group: 'provenance', label: 'Snapshot hash' },
+  { key: 'provenance.lineage', path: 'product.license.governance.ownership', group: 'provenance', label: 'Upstream lineage' },
+
+  // ── Usage terms: the three flags every AIMEAT listing must state to be listed at all ──
+  { key: 'usageTerms', path: 'product.license.scope.rights', group: 'legal', label: 'Usage terms' },
+
+  // ── Legal identity + jurisdiction: what a validator reports as missing on an otherwise full listing ──
+  { key: 'odps.dataHolder.legalName', path: 'product.dataHolder.legalName', group: 'legal', label: 'Legal name' },
+  { key: 'odps.dataHolder.businessID', path: 'product.dataHolder.businessID', group: 'legal', label: 'Business ID' },
+  { key: 'odps.dataHolder.URL', path: 'product.dataHolder.URL', group: 'legal', label: 'Company website' },
+  { key: 'odps.dataHolder.addressCountry', path: 'product.dataHolder.addressCountry', group: 'legal', label: 'Country' },
+  { key: 'odps.dataHolder.addressLocality', path: 'product.dataHolder.addressLocality', group: 'legal', label: 'City' },
+  { key: 'odps.license.applicableLaws', path: 'product.license.governance.applicableLaws', group: 'legal', label: 'Applicable law' },
+  { key: 'odps.license.geographicalArea', path: 'product.license.scope.geographicalArea', group: 'legal', label: 'Geographical area' },
+  { key: 'odps.license.exclusive', path: 'product.license.scope.exclusive', group: 'legal', label: 'Exclusivity stated' },
+  { key: 'odps.license.terminationConditions', path: 'product.license.termination.terminationConditions', group: 'legal', label: 'Termination conditions' },
+
+  // ── Support + versioning: what a buyer needs after they have bought ──
+  { key: 'odps.documentationURL', path: 'product.SLA.declarative[].support.documentationURL', group: 'support', label: 'Documentation' },
+  { key: 'odps.supportEmail', path: 'product.SLA.declarative[].support.email', group: 'support', label: 'Support email' },
+  { key: 'odps.supportHours', path: 'product.SLA.declarative[].support.emailServiceHours', group: 'support', label: 'Support hours' },
+  { key: 'odps.issues', path: 'product.details.issues', group: 'support', label: 'Known issues' },
+  { key: 'odps.productVersion', path: 'product.details.productVersion', group: 'support', label: 'Product version' },
+
+  // ── Governance + tax: how strictly it is run, and what the price includes ──
+  { key: 'odps.language', path: 'product.details', group: 'governance', label: 'Content language' },
+  { key: 'odps.governanceProfile', path: 'product.details.governanceProfile', group: 'governance', label: 'Governance profile' },
+  { key: 'odps.portfolioPriority', path: 'product.details.portfolioPriority', group: 'governance', label: 'Portfolio priority' },
+  { key: 'odps.valueAddedTaxIncluded', path: 'product.pricingPlans.declarative[].valueAddedTaxIncluded', group: 'governance', label: 'VAT included' },
+  { key: 'odps.valueAddedTaxPercentage', path: 'product.pricingPlans.declarative[].valueAddedTaxPercentage', group: 'governance', label: 'VAT percentage' },
+];
+
+/**
+ * Read a dotted path off an object without throwing on a missing branch.
+ * @param {any} obj
+ * @param {string} path
+ * @returns {any}
+ */
+export function valueAt(obj, path) {
+  let node = obj;
+  for (const part of path.split('.')) {
+    if (node === null || node === undefined || typeof node !== 'object') return undefined;
+    node = node[part];
+  }
+  return node;
+}
+
+/**
+ * True when a value counts as STATED. `false` and `0` count — a provider who declares "not
+ * exclusive" or "0% VAT" has answered the question, and treating their answer as absence would tell
+ * them to go and fill in a field they already filled.
+ * @param {any} v
+ * @returns {boolean}
+ */
+function isFilled(v) {
+  if (v === undefined || v === null) return false;
+  if (typeof v === 'string') return v.trim().length > 0;
+  if (Array.isArray(v)) return v.length > 0;
+  if (typeof v === 'object') return Object.keys(v).length > 0;
+  return true;   // numbers (including 0) and booleans (including false)
+}
+
+/**
+ * The ODPS fill rate for one offering, plus exactly what is missing.
+ *
+ * Accepts the offering record itself, or the `{ offering, … }` detail envelope `get(id)` returns —
+ * an app usually has the latter in hand and should not have to remember which.
+ *
+ * @param {any} offering
+ * @returns {{ percent: number, filled: number, total: number,
+ *             missing: Array<{ key: string, path: string, group: string, label: string }>,
+ *             present: Array<{ key: string, path: string, group: string, label: string }>,
+ *             byGroup: Record<string, { filled: number, total: number, percent: number }>,
+ *             odpsVersion: string }}
+ */
+export function odpsCompleteness(offering) {
+  const o = (offering && offering.offering) ? offering.offering : (offering || {});
+  const missing = [];
+  const present = [];
+  const byGroup = /** @type {Record<string, { filled: number, total: number, percent: number }>} */ ({});
+
+  for (const field of ODPS_AUTHORED_FIELDS) {
+    const g = byGroup[field.group] || (byGroup[field.group] = { filled: 0, total: 0, percent: 0 });
+    g.total += 1;
+    if (isFilled(valueAt(o, field.key))) {
+      g.filled += 1;
+      present.push(field);
+    } else {
+      missing.push(field);
+    }
+  }
+  for (const k of Object.keys(byGroup)) {
+    byGroup[k].percent = Math.round((byGroup[k].filled / byGroup[k].total) * 100);
+  }
+
+  const total = ODPS_AUTHORED_FIELDS.length;
+  return {
+    percent: Math.round((present.length / total) * 100),
+    filled: present.length,
+    total,
+    missing,
+    present,
+    byGroup,
+    // The version the descriptor follows — stamped by the node onto provenance when the listing is
+    // written, so a listing authored before a version bump still says which spec it answers to.
+    odpsVersion: (o.provenance && o.provenance.odpsVersion) || '4.1',
+  };
+}

package/dist/static/sdk-libs/exchange/sell.js

@@ -0,0 +1,253 @@
+/**
+ * @file exchange/sell.js
+ * @description The SELL half of AIMEAT.exchange — putting a capability on the market and watching
+ *   what it does. Three kinds of supply share one publish call: a raw extension action, an app-tool
+ *   a provider app sells cross-app, and a task type one of the owner's agents performs. Pricing is
+ *   never sent from here in a way the server would trust — the node reads it authoritatively from
+ *   the source — so `publish` carries the framing (title, terms, provenance, ODPS block) and the
+ *   coordinate, and the price follows from what the source declares.
+ *
+ *   `stats` and `consumers` are the two halves of "is this being used, and by whom". `consumers` is
+ *   provider-only and carries the breakdown underneath each row: the human who pays, and beneath
+ *   them their agents, apps and ecosystem apps — which is how an app answers "is my data being read
+ *   from an application, or by an agent directly?".
+ * @structure publish(spec) · update(id, patch) · delist(id, opts) · stats(id) · consumers(id) ·
+ *   reconcile(opts) · providerHistory() · grants() · grant(spec) · revokeGrant(spec) · normalizeSpec
+ * @usage await AIMEAT.exchange.publish({ ext: 'prh-api', action: 'validate', title: '…', usageTerms: {…} });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { authed, pub, send, qs, exchangeError } from './client.js';
+import { get as getOffering } from './browse.js';
+
+const enc = encodeURIComponent;
+
+/** Pick the first defined value — lets every field be written camelCase or snake_case. */
+function pick(...vals) {
+  for (const v of vals) if (v !== undefined && v !== null) return v;
+  return undefined;
+}
+
+/** Drop undefined keys so an unset field is absent rather than explicitly null on the wire. */
+function compact(obj) {
+  const out = {};
+  for (const k of Object.keys(obj)) if (obj[k] !== undefined) out[k] = obj[k];
+  return out;
+}
+
+/**
+ * Normalise a listing spec into the body POST /v1/exchange/offerings expects. Accepts camelCase
+ * (what a JS app writes) or the wire's snake_case, so neither habit is punished.
+ * @param {Record<string, any>} spec
+ * @returns {Record<string, any>}
+ */
+export function normalizeSpec(spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  return compact({
+    kind: s.kind,
+    // ext-action: the extension + action you own.
+    ext: s.ext,
+    action: s.action,
+    // app-tool: one tool of one of your apps (the node pins its interface version on listing).
+    app_id: pick(s.appId, s.app_id),
+    tool: s.tool,
+    // agent-work: a task type one of your agents performs, settled per delivered task.
+    agent_name: pick(s.agentName, s.agent_name),
+    task_type: pick(s.taskType, s.task_type),
+    price_morsels: pick(s.priceMorsels, s.price_morsels),
+    price_money: pick(s.priceMoney, s.price_money),
+    plans: s.plans,
+    input_schema: pick(s.inputSchema, s.input_schema),
+    output_schema: pick(s.outputSchema, s.output_schema),
+    // Shared framing.
+    title: s.title,
+    description: s.description,
+    tags: s.tags,
+    usage_terms: pick(s.usageTerms, s.usage_terms),
+    provenance: s.provenance,
+    odps: s.odps,
+  });
+}
+
+/**
+ * List a supply OFFERING. The node enforces a legibility gate before anything reaches the market:
+ * a published input AND output schema (`SCHEMA_REQUIRED`) and stated usage terms
+ * (`USAGE_TERMS_REQUIRED`), because a listing nobody can integrate or govern is not supply. The
+ * price is read from the source, so an unpriced capability is refused with `NOT_PRICED` rather than
+ * listed for free.
+ * @param {Record<string, any>} spec
+ *   ext-action: `{ ext, action, title?, description?, tags?, usageTerms, provenance?, odps? }`
+ *   app-tool:   `{ kind: 'app-tool', appId, tool, … }`
+ *   agent-work: `{ kind: 'agent-work', agentName, taskType, priceMorsels|priceMoney, inputSchema, outputSchema, … }`
+ * @returns {Promise<any>}  The created offering.
+ */
+export async function publish(spec) {
+  const d = await send('/v1/exchange/offerings', 'POST', normalizeSpec(spec), 'Failed to list the offering');
+  return d.offering;
+}
+
+/**
+ * Change a listing's framing. DERIVED — the node has no PATCH route for an offering, deliberately:
+ * a listing is a PROJECTION of its source, and the source is where price and coordinate live. So
+ * this republishes the same coordinate with `patch` merged over the current framing, then delists
+ * the superseded record. Consequences, stated because they are real:
+ *   - the offering ID CHANGES. Existing contracts are unaffected (they key on the capability
+ *     coordinate, not the listing id), but a link you published to the old id will 404.
+ *   - price, plans and the metered coordinate are NOT patchable here. They come from the source —
+ *     change the extension action, the tool manifest or the agent offer, then call {@link reconcile}.
+ *   - a PROJECTED listing (`auto`) is refused with `SOURCE_MANAGED` rather than duplicated, because
+ *     the next reconcile would overwrite whatever this wrote. The message names the source to edit.
+ * @param {string} id     The offering to replace.
+ * @param {Record<string, any>} patch  Framing fields (title, description, tags, usageTerms, provenance, odps).
+ * @returns {Promise<any>}  The new offering.
+ */
+export async function update(id, patch) {
+  const detail = await getOffering(id);
+  const o = detail.offering;
+  if (o.auto) {
+    throw exchangeError({ error: {
+      code: 'SOURCE_MANAGED',
+      message: 'This listing is projected from its source (' + o.ext + '/' + o.action
+        + '). Edit the source — the app-tool manifest, the extension action or the agent offer — then call'
+        + ' AIMEAT.exchange.reconcile(). Editing the listing here would be undone by the next reconcile.',
+    } }, 'This listing is managed by its source');
+  }
+  const surface = o.surface || {};
+  const base = compact({
+    kind: o.kind,
+    ext: o.kind === 'ext-action' ? o.ext : undefined,
+    action: o.kind === 'ext-action' ? o.action : undefined,
+    appId: surface.kind === 'app-tool' ? surface.appId : undefined,
+    tool: surface.kind === 'app-tool' ? surface.tool : undefined,
+    agentName: surface.kind === 'agent-work' ? surface.agentName : undefined,
+    taskType: surface.kind === 'agent-work' ? surface.taskType : undefined,
+    priceMorsels: o.kind === 'agent-work' && o.unit === 'morsels' ? o.basePrice : undefined,
+    priceMoney: o.kind === 'agent-work' && o.unit === 'money' ? { amount: o.basePrice, currency: o.currency } : undefined,
+    inputSchema: o.taskSpec ? o.taskSpec.inputSchema : undefined,
+    outputSchema: o.taskSpec ? o.taskSpec.outputSchema : undefined,
+    title: o.title,
+    description: o.description,
+    tags: o.tags,
+    usageTerms: o.usageTerms,
+    provenance: o.provenance,
+    odps: o.odps,
+  });
+  // Publish the replacement FIRST: if it is refused, the seller still has the listing they had.
+  const next = await publish({ ...base, ...(patch || {}) });
+  await delist(id).catch(() => { /* the replacement is live; a stale twin is better than no listing */ });
+  return next;
+}
+
+/**
+ * Delist an offering you own. A PROJECTED listing answers `SOURCE_MANAGED` (409) instead, naming
+ * the source whose `exchange` flag actually controls it — pass `{ force: true }` to delist it until
+ * the next reconcile brings it back.
+ * @param {string} id
+ * @param {{ force?: boolean }} [opts]
+ * @returns {Promise<any>}
+ */
+export function delist(id, opts) {
+  const query = qs({ force: opts && opts.force ? '1' : null });
+  return authed('/v1/exchange/offerings/' + enc(id) + query, { method: 'DELETE' }, 'Failed to delist the offering');
+}
+
+/**
+ * One offering's usage: `{ activeContracts, totalContracts, totalCalls, totalSettledUnits,
+ * consumers, listedAt, lastUsedAt, timing: { count, p50Ms, p95Ms, maxMs } | null }`. Derived from
+ * the contracts against it, so it is a real record of demand rather than a counter anyone can set.
+ * Public — this is reputation. `timing` is null until the capability has actually served calls.
+ * @param {string} id
+ * @returns {Promise<any>}
+ */
+export async function stats(id) {
+  const d = await pub('/v1/exchange/offerings/' + enc(id), 'No such offering');
+  return d.stats;
+}
+
+/**
+ * PROVIDER-ONLY lineage: one row per contract against your offering — who holds it, what they have
+ * consumed, what it settled, the pacing morsels it burned, whether you are CARRYING them (a grant)
+ * rather than billing them, and when they last called.
+ *
+ * Each row carries `callers`: the breakdown of who under that consumer actually called. The row is
+ * the human who pays; underneath are their agents, apps and ecosystem apps, each with its own call
+ * count and spend. That is the answer to "is this being used from an application, or by an agent
+ * directly?" — and it is empty (not wrong) on contracts that predate the breakdown: the totals are
+ * still right, only unattributed.
+ * @param {string} id
+ * @returns {Promise<{ offeringId: string, consumers: any[], count: number }>}
+ */
+export function consumers(id) {
+  return authed('/v1/exchange/offerings/' + enc(id) + '/consumers', undefined, 'No such offering of yours');
+}
+
+/**
+ * Re-project YOUR listings from their sources. Normally automatic — writing a tool manifest, an
+ * extension or an agent offer projects it — this is the explicit handle.
+ * @param {{ dryRun?: boolean, migrate?: boolean, appId?: string, ext?: string, agent?: string }} [opts]
+ *   `dryRun` reports what would change without changing it; `migrate` adopts hand-authored listings
+ *   into the projection model, keeping their offering ids so existing contracts keep resolving.
+ * @returns {Promise<any>}  The reconcile report (`changes` with created/updated/adopted/delisted/skipped).
+ */
+export function reconcile(opts) {
+  const o = opts || {};
+  return send('/v1/exchange/reconcile', 'POST', compact({
+    dry_run: o.dryRun, migrate: o.migrate, app_id: o.appId, ext: o.ext, agent: o.agent,
+  }), 'Failed to reconcile your listings');
+}
+
+/**
+ * Your PAST (archived / superseded) contracts as a PROVIDER — what a renegotiation replaced, with
+ * the old terms and the final spend.
+ * @returns {Promise<{ history: any[], count: number }>}
+ */
+export function providerHistory() {
+  return authed('/v1/exchange/provider/history', undefined, 'Failed to read your provider history');
+}
+
+/**
+ * Everyone you are CARRYING: grants you have issued (free access to a capability you sell, at your
+ * cost) plus `carried` — what the whole guest list has cost you, per rail.
+ * @param {{ appId?: string }} [opts]
+ * @returns {Promise<{ grants: any[], count: number, carried: Record<string, number> }>}
+ */
+export function grants(opts) {
+  return authed('/v1/exchange/grants' + qs({ app_id: opts && opts.appId }), undefined, 'Failed to read your grants');
+}
+
+/**
+ * Issue a grant — you carry this consumer instead of billing them. Needs the `exchange:grant` scope
+ * when an app asks on the owner's behalf, because it gives away the owner's revenue.
+ * @param {{ consumer: string, offeringId: string, capCarriedUnits?: number, note?: string, appId?: string,
+ *          reason?: { appId: string, role: string } }} spec
+ * @returns {Promise<any>}  The issued grant.
+ */
+export async function grant(spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  const d = await send('/v1/exchange/grants', 'POST', compact({
+    consumer: s.consumer,
+    offering_id: pick(s.offeringId, s.offering_id),
+    cap_carried_units: pick(s.capCarriedUnits, s.cap_carried_units),
+    note: s.note,
+    app_id: pick(s.appId, s.app_id),
+    reason: s.reason ? { app_id: pick(s.reason.appId, s.reason.app_id), role: s.reason.role } : undefined,
+  }), 'Failed to issue the grant');
+  return d.grant;
+}
+
+/**
+ * Withdraw grants: `{ consumer, offeringId }` for one, or `{ appId, role?, consumer? }` for every
+ * grant an app issued under an approval it is taking back. Immediate — the next call falls back to
+ * whatever that consumer bought for themselves.
+ * @param {{ consumer?: string, offeringId?: string, appId?: string, role?: string }} spec
+ * @returns {Promise<{ revoked: number, grants: any[] }>}
+ */
+export function revokeGrant(spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  return send('/v1/exchange/grants/revoke', 'POST', compact({
+    consumer: s.consumer,
+    offering_id: pick(s.offeringId, s.offering_id),
+    app_id: pick(s.appId, s.app_id),
+    role: s.role,
+  }), 'Failed to withdraw the grant');
+}