@dan-ai-studio/dshopencodego 0.1.14 → 0.1.16

package/lib/types/catalog/go-doc.js

@@ -0,0 +1,192 @@
+/**
+ * The provider's own Go documentation as a data source.
+ *
+ * No API exposes the per-model allowances: the gateway's `/models` answers ids,
+ * and `/usage` answers account-wide percentages. The numbers live on a docs page
+ * whose source is a markdown file in the provider's repository, so this module
+ * fetches that file and parses its tables — allowances (with the provider's own
+ * request estimates) and the endpoint table that names each model's protocol.
+ *
+ * The document is the primary source. The transcribed table in `go-limits.ts`
+ * stays behind it as a startup seed and a permanent fallback for the day the
+ * URL moves, and its age is surfaced wherever it is used.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/go-doc
+ */
+import { attributionHeaders, LlmError } from '@deepseek-ai/dsh-llm';
+import { METADATA_FETCH_TIMEOUT_MS } from "./constants.js";
+import { readBoundedText } from "./json-response.js";
+/**
+ * Documentation sources, tried in order.
+ *
+ * The repository file is the source of truth; the jsDelivr entry caches the
+ * same path and is tried when GitHub itself is unreachable.
+ */
+export const GO_DOC_URLS = [
+    'https://raw.githubusercontent.com/anomalyco/opencode/dev/packages/web/src/content/docs/go.mdx',
+    'https://cdn.jsdelivr.net/gh/anomalyco/opencode@dev/packages/web/src/content/docs/go.mdx',
+];
+/** The document is about 30 KB; the cap leaves room without inviting a flood. */
+export const GO_DOC_MAX_BYTES = 1024 * 1024;
+/** The protocol each documented endpoint path names. */
+const ENDPOINT_PROTOCOLS = {
+    '/chat/completions': 'openai-completions',
+    '/messages': 'anthropic-messages',
+    '/responses': 'openai-responses',
+};
+/** Strip markdown decoration (`**bold**`, `` `code` ``) from one cell. */
+function cell(value) {
+    return (value ?? '').replace(/[*`]/g, '').trim();
+}
+/**
+ * A display name without its tier suffix, so the three tables join.
+ * `Qwen3.7 Plus (≤ 256K tokens)` and `DeepSeek V4 Pro (Peak)` both reduce to the
+ * name the endpoint table carries.
+ */
+function baseName(name) {
+    return name.replace(/\s*\(.*\)\s*$/, '').trim();
+}
+/** `$60` → 60; `Unlimited 限时` → `unlimited`; anything else → undefined. */
+function parseAllowance(value) {
+    if (/^unlimited\b/i.test(value) || value.startsWith('无限制'))
+        return 'unlimited';
+    const match = value.match(/\$([\d,]+(?:\.\d+)?)/);
+    if (match?.[1] === undefined)
+        return undefined;
+    const amount = Number(match[1].replace(/,/g, ''));
+    return Number.isFinite(amount) ? amount : undefined;
+}
+/** `6,320` → 6320; `Unlimited` → `unlimited`; anything else → undefined. */
+function parseCount(value) {
+    if (/^unlimited\b/i.test(value) || value.startsWith('无限制'))
+        return 'unlimited';
+    const amount = Number(value.replace(/,/g, ''));
+    return value.length > 0 && Number.isFinite(amount) ? amount : undefined;
+}
+/**
+ * The protocol a documented endpoint names.
+ *
+ * Matched by path suffix: the table spells full URLs, and every supported API
+ * lives at a distinct tail (`/chat/completions`, `/messages`, `/responses`).
+ */
+function protocolOfEndpoint(endpoint) {
+    for (const [suffix, protocol] of Object.entries(ENDPOINT_PROTOCOLS)) {
+        if (endpoint.endsWith(suffix))
+            return protocol;
+    }
+    return undefined;
+}
+/**
+ * The data rows of the table whose header carries `required`.
+ *
+ * Data starts after the header and its separator, and ends at the first line
+ * that is not a table row, so three tables in one document stay apart.
+ * @param lines - the document, split into lines.
+ * @param required - a header cell that table alone carries.
+ * @returns one array of trimmed cells per data row.
+ */
+function tableRows(lines, required) {
+    const start = lines.findIndex(line => line.startsWith('|') && line.includes(required));
+    if (start < 0)
+        return [];
+    const rows = [];
+    for (let index = start + 2; index < lines.length; index++) {
+        const line = lines[index] ?? '';
+        if (!line.startsWith('|'))
+            break;
+        rows.push(line.split('|').slice(1, -1).map(entry => entry.trim()));
+    }
+    return rows;
+}
+/**
+ * Parse the Go documentation into the two data sets this plugin consumes.
+ *
+ * Titles are the join key: the allowance tables name models the way the page
+ * presents them while the endpoint table carries the ids, so ids come from the
+ * endpoint table and the other two attach by normalised display name. A row
+ * that names no known model, or states no usable number, is skipped rather than
+ * guessed; a tiered model whose rows disagree is dropped entirely.
+ * @param markdown - the raw document text.
+ * @returns the parsed allowances and protocols; both may be empty when the
+ *   document does not carry the expected tables.
+ */
+export function parseGoDocument(markdown) {
+    const lines = markdown.split('\n');
+    const ids = new Map();
+    const protocols = new Map();
+    for (const row of tableRows(lines, 'Model ID')) {
+        const name = cell(row[0]);
+        const id = cell(row[1]);
+        if (name.length === 0 || id.length === 0)
+            continue;
+        ids.set(name, id);
+        const protocol = protocolOfEndpoint(cell(row[2]));
+        if (protocol !== undefined)
+            protocols.set(id, protocol);
+    }
+    const quotas = new Map();
+    for (const row of tableRows(lines, 'Monthly limit')) {
+        const id = ids.get(baseName(cell(row[0])));
+        if (id === undefined)
+            continue;
+        const monthlyUsd = parseAllowance(cell(row[5]));
+        if (monthlyUsd === undefined)
+            continue;
+        const previous = quotas.get(id);
+        // Tiered rows (token bands, peak/off-peak) repeat one allowance; the first
+        // row wins, and a disagreement drops the model instead of picking a band.
+        if (previous === undefined)
+            quotas.set(id, { monthlyUsd });
+        else if (previous.monthlyUsd !== monthlyUsd)
+            quotas.delete(id);
+    }
+    for (const row of tableRows(lines, 'requests per month')) {
+        const id = ids.get(baseName(cell(row[0])));
+        if (id === undefined)
+            continue;
+        const monthlyRequests = parseCount(cell(row[3]));
+        const quota = quotas.get(id);
+        if (monthlyRequests === undefined || quota === undefined)
+            continue;
+        quotas.set(id, { ...quota, monthlyRequests });
+    }
+    return { quotas, protocols };
+}
+/**
+ * Fetch and parse the documentation, trying each source in turn.
+ *
+ * A source that answers without a usable allowance table counts as a failure,
+ * not as an empty document: that is what a moved or restructured page looks
+ * like, and the caller must keep its previous data rather than blank the page.
+ * @param signal - caller cancellation, if any.
+ * @returns the parsed document from the first source that carried one.
+ * @throws {LlmError} `DOCUMENT_UNAVAILABLE` when every source failed.
+ */
+export async function fetchGoDocument(signal) {
+    const failures = [];
+    for (const url of GO_DOC_URLS) {
+        try {
+            const timeout = AbortSignal.timeout(METADATA_FETCH_TIMEOUT_MS);
+            const response = await fetch(url, {
+                redirect: 'error',
+                headers: { ...attributionHeaders(), accept: 'text/plain', 'cache-control': 'no-cache' },
+                signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
+            });
+            if (!response.ok) {
+                await response.body?.cancel().catch(() => { });
+                failures.push(`${url} answered HTTP ${response.status}`);
+                continue;
+            }
+            const document = parseGoDocument(await readBoundedText(response, GO_DOC_MAX_BYTES));
+            if (document.quotas.size === 0) {
+                failures.push(`${url} carried no allowance table`);
+                continue;
+            }
+            return document;
+        }
+        catch (error) {
+            failures.push(`${url}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    throw new LlmError(`could not read the Go documentation (${failures.join('; ')})`, 'DOCUMENT_UNAVAILABLE');
+}

package/lib/types/catalog/index.d.ts

@@ -3,21 +3,26 @@
  *
  * Membership comes from the gateway listing, capability from models.dev, and
  * exact protocol/wire quirks from the installed pi-ai catalog, merged through
- * the ladder in `./protocol.ts`. The snapshot is cached for the configured
- * refresh interval, and an unknown model id forces one revalidation even inside
- * that interval — that is what makes a model the gateway added this morning
- * callable this afternoon without a plugin release.
+ * the ladder in `./protocol.ts`. Per-model allowances, and a protocol for the
+ * models nothing else covers, come from the provider's own documentation (see
+ * `./go-doc.ts`). The snapshot is cached for the configured refresh interval,
+ * and an unknown model id forces one revalidation even inside that interval —
+ * that is what makes a model the gateway added this morning callable this
+ * afternoon without a plugin release.
  *
  * Failures degrade rather than empty: a listing outage keeps the last known
  * models and marks the snapshot not-live, a metadata outage keeps the last
- * document, and a single unparseable model is reported by id while every other
- * model keeps serving.
+ * document, a documentation outage keeps the last parsed allowances (or leaves
+ * the page on its frozen seed), and a single unparseable model is reported by
+ * id while every other model keeps serving.
  *
  * @module @dan-ai-studio/dshopencodego/catalog
  */
 import type { Provider } from '@earendil-works/pi-ai';
 import type { LlmDiscoveredModel } from '@deepseek-ai/dsh-llm';
+import type { GoDoc } from './go-doc.ts';
 import type { ModelDefaults, ModelFacts } from './metadata.ts';
+import type { GoQuota } from '../go-limits.ts';
 export { PROVIDER_ID, DISPLAY_NAME, DEFAULT_BASE_URL } from './constants.ts';
 export { readModelIds, fetchModelIds } from './gateway.ts';
 export { readOnlineMetadata, toPiModel, modelBaseURL } from './metadata.ts';
@@ -34,6 +39,12 @@ export interface CatalogSnapshot {
     readonly provider: Provider;
     /** Whether the gateway listing answered during this build. */
     readonly live: boolean;
+    /**
+     * Allowances parsed from the provider's own documentation, once a fetch has
+     * succeeded in this process. Absent until then, and across restarts; the page
+     * falls back to the frozen seed in `go-limits.ts`.
+     */
+    readonly documentQuotas?: ReadonlyMap<string, GoQuota>;
     /** Retained for explicit discovery when the listing failed. */
     readonly listingFailure?: unknown;
     readonly fetchedAtMs: number;
@@ -63,6 +74,11 @@ export interface CatalogOptions {
     /** Configured per-id protocol overrides. */
     readonly overrides: Readonly<Record<string, string>>;
     readonly observers?: CatalogObservers;
+    /**
+     * Read the provider documentation. Defaults to the real fetch; tests inject a
+     * fixed document so the suite stays offline.
+     */
+    readonly readDocument?: () => Promise<GoDoc>;
 }
 /**
  * One gateway's catalog. Requests reuse a cached snapshot; explicit discovery
@@ -75,6 +91,8 @@ export declare class OpencodeGoCatalog {
     private metadataDocument;
     private metadataETag;
     private lastMetadata;
+    /** The last parsed documentation; retained across failed fetches. */
+    private document;
     constructor(options: CatalogOptions);
     /** The cached snapshot, refreshed when it is older than the configured TTL. */
     snapshot(force?: boolean): Promise<CatalogSnapshot>;
@@ -89,10 +107,22 @@ export declare class OpencodeGoCatalog {
      *   the id but this build cannot configure it, naming the reason.
      */
     forModel(id: string): Promise<CatalogSnapshot>;
-    /** Revalidate both sources, reusing the metadata document when it is unchanged. */
+    /** Revalidate every source, reusing the metadata document when it is unchanged. */
     private build;
     /** Merge the listing with the metadata document and the installed entries. */
     private assemble;
+    /** The document allowances as a snapshot field, absent until one fetch lands. */
+    private documentQuotas;
+    /**
+     * Prefer the documented protocol over anything below the installed catalog.
+     *
+     * The endpoint table is the provider's own statement, so it outranks both the
+     * family guess and models.dev's SDK hint — this turns an `inferred` badge into
+     * a known answer for ids the installed catalog misses. It never overrides a
+     * builtin entry or a configured override: those carry the wire quirks the
+     * adapter relies on.
+     */
+    private withDocumentedProtocol;
     /** Facts for an id no source describes, from the ladder and the route defaults. */
     private inferredFacts;
     /** Conditional metadata GET: an unchanged document keeps its parsed form. */

package/lib/types/catalog/index.js

@@ -3,15 +3,18 @@
  *
  * Membership comes from the gateway listing, capability from models.dev, and
  * exact protocol/wire quirks from the installed pi-ai catalog, merged through
- * the ladder in `./protocol.ts`. The snapshot is cached for the configured
- * refresh interval, and an unknown model id forces one revalidation even inside
- * that interval — that is what makes a model the gateway added this morning
- * callable this afternoon without a plugin release.
+ * the ladder in `./protocol.ts`. Per-model allowances, and a protocol for the
+ * models nothing else covers, come from the provider's own documentation (see
+ * `./go-doc.ts`). The snapshot is cached for the configured refresh interval,
+ * and an unknown model id forces one revalidation even inside that interval —
+ * that is what makes a model the gateway added this morning callable this
+ * afternoon without a plugin release.
  *
  * Failures degrade rather than empty: a listing outage keeps the last known
  * models and marks the snapshot not-live, a metadata outage keeps the last
- * document, and a single unparseable model is reported by id while every other
- * model keeps serving.
+ * document, a documentation outage keeps the last parsed allowances (or leaves
+ * the page on its frozen seed), and a single unparseable model is reported by
+ * id while every other model keeps serving.
  *
  * @module @dan-ai-studio/dshopencodego/catalog
  */
@@ -23,6 +26,7 @@ import { openAIResponsesApi } from '@earendil-works/pi-ai/api/openai-responses.l
 import { attributionHeaders, LlmError } from '@deepseek-ai/dsh-llm';
 import { DISPLAY_NAME, MODEL_METADATA_MAX_BYTES, MODEL_METADATA_URL, PROVIDER_ID, METADATA_FETCH_TIMEOUT_MS, } from "./constants.js";
 import { fetchModelIds } from "./gateway.js";
+import { fetchGoDocument, GO_DOC_URLS } from "./go-doc.js";
 import { readBoundedJson } from "./json-response.js";
 import { readOnlineMetadata, toPiModel } from "./metadata.js";
 export { PROVIDER_ID, DISPLAY_NAME, DEFAULT_BASE_URL } from "./constants.js";
@@ -80,6 +84,8 @@ export class OpencodeGoCatalog {
     metadataDocument;
     metadataETag;
     lastMetadata;
+    /** The last parsed documentation; retained across failed fetches. */
+    document;
     constructor(options) {
         this.options = options;
     }
@@ -118,12 +124,14 @@ export class OpencodeGoCatalog {
         }
         return snapshot;
     }
-    /** Revalidate both sources, reusing the metadata document when it is unchanged. */
+    /** Revalidate every source, reusing the metadata document when it is unchanged. */
     async build() {
         const builtin = builtinModels(this.options.baseURL);
-        const [listing, metadata] = await Promise.allSettled([
+        const readDocument = this.options.readDocument ?? fetchGoDocument;
+        const [listing, metadata, documentation] = await Promise.allSettled([
             fetchModelIds(this.options.baseURL),
             this.refreshMetadata(builtin),
+            readDocument(),
         ]);
         if (metadata.status === 'rejected') {
             this.options.observers?.onFallback?.({
@@ -132,6 +140,18 @@ export class OpencodeGoCatalog {
                 kept: this.lastMetadata?.models.size ?? 0,
             });
         }
+        if (documentation.status === 'fulfilled') {
+            this.document = documentation.value;
+        }
+        else {
+            // Not a page-stale event: the allowances keep their previous source, and
+            // the page says so wherever the frozen seed is in use.
+            this.options.observers?.onFallback?.({
+                url: GO_DOC_URLS[0] ?? 'the Go documentation',
+                error: documentation.reason,
+                kept: this.document?.quotas.size ?? 0,
+            });
+        }
         if (listing.status === 'rejected') {
             // Once observed, an outage must not resurrect retired models: the last
             // successful listing stays authoritative until a new one arrives.
@@ -149,6 +169,7 @@ export class OpencodeGoCatalog {
                 live: false,
                 listingFailure: listing.reason,
                 fetchedAtMs: Date.now(),
+                ...this.documentQuotas(),
             };
         }
         // A metadata outage keeps the last successful parse: the previous document
@@ -177,7 +198,7 @@ export class OpencodeGoCatalog {
             // (`@ai-sdk/openai-compatible`) makes Chat Completions the best available
             // guess, and the route defaults size it; the settings surface marks it as
             // inferred so a wrong guess is visible and overridable.
-            facts.set(id, this.inferredFacts(id, builtin));
+            facts.set(id, this.withDocumentedProtocol(this.inferredFacts(id, builtin)));
         }
         if (unavailable.size > 0) {
             this.options.observers?.onUnconfigured?.([...unavailable].map(([id, reason]) => ({ id, reason })));
@@ -188,8 +209,28 @@ export class OpencodeGoCatalog {
             provider: buildProvider(this.options.baseURL, [...facts.values()].map(fact => toPiModel(fact, this.options.baseURL))),
             live: true,
             fetchedAtMs: Date.now(),
+            ...this.documentQuotas(),
         };
     }
+    /** The document allowances as a snapshot field, absent until one fetch lands. */
+    documentQuotas() {
+        return this.document === undefined ? {} : { documentQuotas: this.document.quotas };
+    }
+    /**
+     * Prefer the documented protocol over anything below the installed catalog.
+     *
+     * The endpoint table is the provider's own statement, so it outranks both the
+     * family guess and models.dev's SDK hint — this turns an `inferred` badge into
+     * a known answer for ids the installed catalog misses. It never overrides a
+     * builtin entry or a configured override: those carry the wire quirks the
+     * adapter relies on.
+     */
+    withDocumentedProtocol(facts) {
+        if (facts.protocolSource !== 'inferred' && facts.protocolSource !== 'online')
+            return facts;
+        const documented = this.document?.protocols.get(facts.id);
+        return documented === undefined ? facts : { ...facts, api: documented, protocolSource: 'document' };
+    }
     /** Facts for an id no source describes, from the ladder and the route defaults. */
     inferredFacts(id, builtin) {
         const exact = builtin.get(id);

package/lib/types/catalog/json-response.d.ts

@@ -1,8 +1,9 @@
 /**
- * Bounded JSON reads shared by the catalog and usage endpoints.
+ * Bounded body reads shared by the catalog, the usage endpoint, and the Go
+ * documentation fetch.
  *
- * Every outbound metadata read is capped before parsing: the metadata document
- * is third-party, and a truncated or oversized reply must surface as a named
+ * Every outbound metadata read is capped before parsing: the documents are
+ * third-party, and a truncated or oversized reply must surface as a named
  * failure rather than as memory growth.
  *
  * @module @dan-ai-studio/dshopencodego/catalog/json-response
@@ -17,3 +18,5 @@
  *   or invalid JSON.
  */
 export declare function readBoundedJson(response: Response, url: string, maxBytes: number): Promise<unknown>;
+/** Decode a body as text, aborting once it passes the cap. */
+export declare function readBoundedText(response: Response, maxBytes: number): Promise<string>;

package/lib/types/catalog/json-response.js

@@ -1,8 +1,9 @@
 /**
- * Bounded JSON reads shared by the catalog and usage endpoints.
+ * Bounded body reads shared by the catalog, the usage endpoint, and the Go
+ * documentation fetch.
  *
- * Every outbound metadata read is capped before parsing: the metadata document
- * is third-party, and a truncated or oversized reply must surface as a named
+ * Every outbound metadata read is capped before parsing: the documents are
+ * third-party, and a truncated or oversized reply must surface as a named
  * failure rather than as memory growth.
  *
  * @module @dan-ai-studio/dshopencodego/catalog/json-response
@@ -39,8 +40,8 @@ export async function readBoundedJson(response, url, maxBytes) {
         throw new LlmError(`${url} did not answer with JSON`, 'DISCOVERY_FAILED', { cause: error });
     }
 }
-/** Decode a body, aborting once it passes the cap. */
-async function readBoundedText(response, maxBytes) {
+/** Decode a body as text, aborting once it passes the cap. */
+export async function readBoundedText(response, maxBytes) {
     if (response.body === null)
         return '';
     const reader = response.body.getReader();

package/lib/types/catalog/protocol.d.ts

@@ -24,8 +24,13 @@ import type { Api } from '@earendil-works/pi-ai';
 export type WireProtocol = 'anthropic-messages' | 'openai-completions' | 'openai-responses';
 /** Every protocol this plugin can drive, in catalog order. */
 export declare const WIRE_PROTOCOLS: readonly WireProtocol[];
-/** Which evidence level produced a protocol decision. */
-export type ProtocolSource = 'builtin' | 'online' | 'inferred' | 'override';
+/**
+ * Which evidence level produced a protocol decision, most authoritative first:
+ * a configured `override`, the installed catalog (`builtin`), the provider's own
+ * endpoint table (`document`), models.dev's SDK hint (`online`), and last the
+ * family rule (`inferred`).
+ */
+export type ProtocolSource = 'builtin' | 'document' | 'online' | 'inferred' | 'override';
 /** One model's protocol decision with the evidence that produced it. */
 export interface ProtocolDecision {
     readonly api: WireProtocol;

package/lib/types/catalog/reading.d.ts

@@ -21,6 +21,11 @@ export interface CatalogReading {
     readonly error?: string;
     /** When the underlying snapshot was built. */
     readonly fetchedAtMs: number;
+    /**
+     * Where the per-model allowances came from: the provider's live document, or
+     * the frozen seed (whose transcription date the page shows alongside).
+     */
+    readonly quotaSource: 'document' | 'seed';
     /** Counts the settings page shows without walking the list again. */
     readonly counts: {
         readonly total: number;

package/lib/types/catalog/reading.js

@@ -20,9 +20,10 @@ import { goQuotaFor } from "../go-limits.js";
  *   explain them instead of hiding them.
  */
 export function catalogReading(snapshot, visibility, listingFailure) {
+    const documentQuotas = snapshot.documentQuotas;
     const rows = [
         ...[...snapshot.facts.values()].map(fact => {
-            const quota = goQuotaFor(fact.id);
+            const quota = documentQuotas === undefined ? goQuotaFor(fact.id) : documentQuotas.get(fact.id);
             const priced = fact.cost.input > 0 || fact.cost.output > 0;
             return {
                 id: fact.id,
@@ -58,6 +59,7 @@ export function catalogReading(snapshot, visibility, listingFailure) {
         stale: !snapshot.live,
         ...!snapshot.live && listingFailure !== undefined ? { error: listingFailure } : {},
         fetchedAtMs: snapshot.fetchedAtMs,
+        quotaSource: documentQuotas === undefined ? 'seed' : 'document',
         counts: {
             total: models.length,
             enabled,

package/lib/types/config.d.ts

@@ -77,8 +77,13 @@ export interface OpencodeGoConfig {
      */
     retryPolicy?: RetryPolicyConfig;
 }
-/** Plain resolved values used by the adapter. */
-export declare const PlainConfig: z<OpencodeGoConfig>;
+/**
+ * Plain resolved values used by the adapter.
+ *
+ * The input side is a partial on purpose: a profile writes only the fields it
+ * overrides, and the schema's own defaults fill the rest.
+ */
+export declare const PlainConfig: z<Partial<OpencodeGoConfig>, OpencodeGoConfig>;
 /** 0.1.7's Loader retains these references when profile fields change. */
 export type LiveConfig = {
     [K in keyof OpencodeGoConfig]-?: {

package/lib/types/config.js

@@ -44,7 +44,12 @@ const fields = {
     modelProtocols: z.dict(z.string()).default({}),
     retryPolicy: RetryPolicySchema,
 };
-/** Plain resolved values used by the adapter. */
+/**
+ * Plain resolved values used by the adapter.
+ *
+ * The input side is a partial on purpose: a profile writes only the fields it
+ * overrides, and the schema's own defaults fill the rest.
+ */
 export const PlainConfig = z.object(fields);
 /** Runtime schema for {@link OpencodeGoConfig}; every field stays live. */
 export const Config = z.object(Object.fromEntries(Object.entries(fields).map(([key, schema]) => [key, schema.volatile()])));

package/lib/types/go-limits.d.ts

@@ -1,21 +1,33 @@
 /**
- * Go's published per-model quota.
+ * The frozen seed of Go's published per-model quota.
  *
- * No API exposes this — the gateway's `/v1/models` answers only ids, and
- * `/usage` answers three account-wide percentages — so the numbers are
- * transcribed from the provider's own documentation.
+ * No API exposes these numbers — the gateway's `/v1/models` answers ids and
+ * `/usage` answers account-wide percentages — so the live figures are parsed
+ * from the provider's own documentation by `catalog/go-doc.ts`. This table is
+ * the seed and the last resort behind that fetch:
+ *
+ * - it renders instantly at startup, before the first fetch resolves;
+ * - it keeps working when every source fails, including the day the document
+ *   URL moves.
+ *
+ * It is deliberately **not** updated as models arrive: wherever it is shown its
+ * transcription date travels with it, so a stale number is never silent, and a
+ * model it does not list simply shows no allowance until a fetch succeeds.
  *
  * Source: https://opencode.ai/docs/zh-cn/go — the 「使用限制」 and
- * 「预估请求数」 tables. Transcribed 2026-09-25.
+ * 「预估请求数」 tables. Transcribed 2026-09-25, frozen 2026-09-26.
  *
  * Two caveats are part of the data's meaning, not noise:
  * - `monthlyUsd` is the hard monthly allowance; the request counts are the
  *   provider's own estimate for a typical request mix, not a hard ceiling.
- * - DeepSeek V4.1 Flash carries a limited-time 4x allowance (until 2026-09-27)
- *   already reflected here; the archived numbers follow the provider page.
+ * - DeepSeek V4.1 Flash carried a limited-time 4x allowance in this snapshot;
+ *   the provider has since made the listed $60 permanent, which only the live
+ *   document reports.
  *
  * @module @dan-ai-studio/dshopencodego/go-limits
  */
+/** The date this seed was transcribed from the provider's page. */
+export declare const SEED_TRANSCRIBED = "2026-09-25";
 /** One model's published Go allowance. */
 export interface GoQuota {
     /** Monthly usage allowance in USD, or `unlimited` where none is published. */
@@ -23,12 +35,12 @@ export interface GoQuota {
     /** Provider's estimated requests per month for a typical mix, when listed. */
     readonly monthlyRequests?: number | 'unlimited';
 }
-/** The transcribed table, keyed by model id. */
-export declare const GO_QUOTAS: Readonly<Record<string, GoQuota>>;
+/** The frozen seed table, keyed by model id. Not a maintenance target. */
+export declare const SEED_QUOTAS: Readonly<Record<string, GoQuota>>;
 /**
- * The published quota for one model id.
+ * The seed allowance for one model id.
  * @param id - the gateway's model id.
- * @returns the transcribed allowance, or undefined when the page lists none.
+ * @returns the frozen seed entry, or undefined when the page listed none.
  */
 export declare function goQuotaFor(id: string): GoQuota | undefined;
 /**

package/lib/types/go-limits.js

@@ -1,23 +1,35 @@
 /**
- * Go's published per-model quota.
+ * The frozen seed of Go's published per-model quota.
  *
- * No API exposes this — the gateway's `/v1/models` answers only ids, and
- * `/usage` answers three account-wide percentages — so the numbers are
- * transcribed from the provider's own documentation.
+ * No API exposes these numbers — the gateway's `/v1/models` answers ids and
+ * `/usage` answers account-wide percentages — so the live figures are parsed
+ * from the provider's own documentation by `catalog/go-doc.ts`. This table is
+ * the seed and the last resort behind that fetch:
+ *
+ * - it renders instantly at startup, before the first fetch resolves;
+ * - it keeps working when every source fails, including the day the document
+ *   URL moves.
+ *
+ * It is deliberately **not** updated as models arrive: wherever it is shown its
+ * transcription date travels with it, so a stale number is never silent, and a
+ * model it does not list simply shows no allowance until a fetch succeeds.
  *
  * Source: https://opencode.ai/docs/zh-cn/go — the 「使用限制」 and
- * 「预估请求数」 tables. Transcribed 2026-09-25.
+ * 「预估请求数」 tables. Transcribed 2026-09-25, frozen 2026-09-26.
  *
  * Two caveats are part of the data's meaning, not noise:
  * - `monthlyUsd` is the hard monthly allowance; the request counts are the
  *   provider's own estimate for a typical request mix, not a hard ceiling.
- * - DeepSeek V4.1 Flash carries a limited-time 4x allowance (until 2026-09-27)
- *   already reflected here; the archived numbers follow the provider page.
+ * - DeepSeek V4.1 Flash carried a limited-time 4x allowance in this snapshot;
+ *   the provider has since made the listed $60 permanent, which only the live
+ *   document reports.
  *
  * @module @dan-ai-studio/dshopencodego/go-limits
  */
-/** The transcribed table, keyed by model id. */
-export const GO_QUOTAS = {
+/** The date this seed was transcribed from the provider's page. */
+export const SEED_TRANSCRIBED = '2026-09-25';
+/** The frozen seed table, keyed by model id. Not a maintenance target. */
+export const SEED_QUOTAS = {
     'glm-5.3-flash': { monthlyUsd: 60, monthlyRequests: 31_580 },
     'glm-5.3': { monthlyUsd: 15, monthlyRequests: 1_080 },
     'glm-5.2': { monthlyUsd: 60, monthlyRequests: 4_300 },
@@ -53,12 +65,12 @@ export const GO_QUOTAS = {
     'gpt-5.6-luna': { monthlyUsd: 15, monthlyRequests: 10_250 },
 };
 /**
- * The published quota for one model id.
+ * The seed allowance for one model id.
  * @param id - the gateway's model id.
- * @returns the transcribed allowance, or undefined when the page lists none.
+ * @returns the frozen seed entry, or undefined when the page listed none.
  */
 export function goQuotaFor(id) {
-    return Object.hasOwn(GO_QUOTAS, id) ? GO_QUOTAS[id] : undefined;
+    return Object.hasOwn(SEED_QUOTAS, id) ? SEED_QUOTAS[id] : undefined;
 }
 /**
  * Rank a quota for "most usable first" ordering: unlimited beats any finite