aimeat 2.1.0 → 2.3.0

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

@@ -0,0 +1,106 @@
+/**
+ * @file exchange/demand.js
+ * @description The DEMAND side of AIMEAT.exchange — an app says what it needs and cannot produce
+ *   itself, providers bid, the requester accepts one and a contract is minted. A need is always
+ *   posted on behalf of a specific app (`appId`), which is what turns a wish into a request a
+ *   provider can judge: they can see who they would be serving before offering.
+ * @structure needs(opts) · postNeed(spec) · closeNeed(id) · bids(needId) · bid(needId, spec) ·
+ *   acceptBid(needId, bidId, opts)
+ * @usage await AIMEAT.exchange.postNeed({ appId: 'alice/crm', description: '…', spec: { requiredFields: [...] } });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { authed, pub, send, qs } from './client.js';
+
+const enc = encodeURIComponent;
+
+function compact(obj) {
+  const out = {};
+  for (const k of Object.keys(obj)) if (obj[k] !== undefined) out[k] = obj[k];
+  return out;
+}
+function pick(...vals) {
+  for (const v of vals) if (v !== undefined && v !== null) return v;
+  return undefined;
+}
+
+/**
+ * Browse needs. Public. Each is enriched with `appContext` — the requesting app's published name
+ * and description — so a provider judges the consumer, not just the ask.
+ * @param {{ open?: boolean, mine?: boolean }} [opts]  `mine` requires a session.
+ * @returns {Promise<{ needs: any[], count: number }>}
+ */
+export function needs(opts) {
+  const o = opts || {};
+  const query = qs({ open: o.open ? '1' : null, mine: o.mine ? '1' : null });
+  return o.mine
+    ? authed('/v1/exchange/needs' + query, undefined, 'Failed to read your needs')
+    : pub('/v1/exchange/needs' + query, 'Failed to browse needs');
+}
+
+/**
+ * Post an open need. `appId` is REQUIRED (`NEED_APP_REQUIRED` without it) — a need belongs to the
+ * app that will call the answer. The response carries `matches`: offerings that already satisfy it,
+ * so the requester can accept one directly instead of waiting for a bid.
+ * @param {{ appId: string, description: string, ext?: string, action?: string,
+ *           spec?: { requiredFields?: string[], format?: string, sample?: string, notes?: string,
+ *                    inputSchema?: object, outputSchema?: object },
+ *           usageIntent?: string, budgetUnit?: 'money'|'morsels', budgetCap?: number,
+ *           autonomy?: 'supervised'|'auto' }} spec
+ * @returns {Promise<{ need: any, matches: any[] }>}
+ */
+export function postNeed(spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  return send('/v1/exchange/needs', 'POST', compact({
+    app_id: pick(s.appId, s.app_id),
+    description: s.description,
+    ext: s.ext,
+    action: s.action,
+    spec: s.spec,
+    usage_intent: pick(s.usageIntent, s.usage_intent),
+    budget_unit: pick(s.budgetUnit, s.budget_unit),
+    budget_cap: pick(s.budgetCap, s.budget_cap),
+    autonomy: s.autonomy,
+  }), 'Failed to post the need');
+}
+
+/** Close one of your own needs. */
+export function closeNeed(id) {
+  return send('/v1/exchange/needs/' + enc(id) + '/close', 'POST', {}, 'Failed to close the need');
+}
+
+/** The bids on a need. Public — demand and the answers to it are both browsable. */
+export function bids(needId) {
+  return pub('/v1/exchange/needs/' + enc(needId) + '/bids', 'Failed to read bids');
+}
+
+/**
+ * Bid on an open need with an action YOUR extension owns (anything else is refused, 403).
+ * @param {string} needId
+ * @param {{ ext: string, action: string, offeringId?: string, planId?: string, note?: string }} spec
+ * @returns {Promise<any>}  The open bid.
+ */
+export async function bid(needId, spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  const d = await send('/v1/exchange/needs/' + enc(needId) + '/bids', 'POST', compact({
+    ext: s.ext, action: s.action,
+    offering_id: pick(s.offeringId, s.offering_id),
+    plan_id: pick(s.planId, s.plan_id),
+    note: s.note,
+  }), 'Failed to place the bid');
+  return d.bid;
+}
+
+/**
+ * The REQUESTER accepts a bid → the entitlement is minted (consumer = requester, provider = bidder)
+ * at the provider's authoritative price, and the need is marked matched.
+ * @param {string} needId
+ * @param {string} bidId
+ * @param {{ capUnits?: number }} [opts]  Defaults to the need's own budget cap.
+ * @returns {Promise<any>}
+ */
+export function acceptBid(needId, bidId, opts) {
+  const o = /** @type {Record<string, any>} */ (opts || {});
+  return send('/v1/exchange/needs/' + enc(needId) + '/bids/' + enc(bidId) + '/accept', 'POST',
+    compact({ cap_units: pick(o.capUnits, o.cap_units) }), 'Failed to accept the bid');
+}

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

@@ -0,0 +1,39 @@
+/**
+ * @file exchange/earnings.js
+ * @description What the market OWES the caller. A money-priced metered call settles through the
+ *   accrual rail: no per-call payment-processor charge and no custodial escrow — each call books the
+ *   seller's net (price minus the platform rake) as a `pending` payable. This reads that book.
+ *
+ *   What it deliberately is NOT: a payout, an invoice, or a way to mark something settled. The
+ *   figure is made READABLE here; moving money is a later phase, and a browser library that implied
+ *   otherwise would be making a promise about money that nothing behind it keeps.
+ *
+ *   SECURITY: no payment credentials pass through here in either direction. A seller's PSP
+ *   configuration is server-side and never readable; this call returns amounts and buyers, nothing
+ *   that could be used to charge anyone.
+ * @structure earnings(opts)
+ * @usage const e = await AIMEAT.exchange.earnings();  // e.currencies.EUR.pending
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { authed, qs } from './client.js';
+
+/**
+ * The caller's own accrued earnings, per currency, with the per-entry breakdown behind the figure.
+ *
+ * Returns `{ seller, currencies: { EUR: { pending, settled, total, entries } }, entries: [{
+ * tracking_code, amount, currency, method, status, at, reference, buyer }], count, note }`.
+ * Amounts are NET of the platform rake, in the currency's integer micro-units — format them with
+ * {@link module:exchange/format.fmtUnit}, never by dividing by hand.
+ *
+ * `pending` means booked as owed and not yet paid out. Owner-scoped by the server on the money
+ * identity, so an owner's agent or a granted app reads the OWNER's earnings and never another
+ * seller's; a non-owner principal needs the `wallet:read` scope.
+ * @param {{ status?: 'pending'|'settled', currency?: string, limit?: number }} [opts]
+ * @returns {Promise<any>}
+ */
+export function earnings(opts) {
+  const o = opts || {};
+  return authed('/v1/exchange/earnings' + qs({ status: o.status, currency: o.currency, limit: o.limit }),
+    undefined, 'Failed to read your earnings');
+}

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',
+  };
+}