dsh-agent-plugins-market 0.9.0 → 0.9.2

package/lib/types/packages/market-translation/src/application/translation/document.d.ts

@@ -0,0 +1,54 @@
+import type { DocumentTranslation } from '../../../../market-contracts/src/contracts/translation.js';
+/** Legacy description chunk bound. Document paragraphs use a separate sentence budget. */
+export declare const MAX_DOCUMENT_CHUNK_CHARS = 800;
+/** Conservative document payload bound, below the smallest target batch allowance. */
+export declare const MAX_PARAGRAPH_REQUEST_CHARS = 1600;
+/** No character fallback: a sentence that exceeds the bound keeps its paragraph authored. */
+export declare function paragraphParts(text: string): string[] | undefined;
+/**
+ * Transform prose in a single GFM/math tree. All non-text inline nodes and block
+ * structures stay local; providers see paragraph text with ordered boundaries.
+ * A malformed boundary sequence leaves that paragraph authored, never rewrites
+ * link destinations, code, or the surrounding list/reference structure.
+ */
+export declare function translateMarkdownDocument(source: string, localize: (text: string, parts: readonly string[] | undefined) => {
+    text: string;
+    pending: boolean;
+    failed?: boolean;
+}): DocumentTranslation;
+/** One piece of a document: the text to send, and whether it is worth sending at all. */
+export interface DocumentChunk {
+    /** The slice exactly as authored, so a body nothing was translated for reassembles unchanged. */
+    text: string;
+    /** False for verbatim regions — fenced code — which no provider should ever see. */
+    translatable: boolean;
+    /**
+     * The authored text between this chunk and the next, byte for byte: the line
+     * ending that closed it, the blank lines that followed, and — on the last
+     * chunk — whatever trails the body.
+     *
+     * It is never sent to a provider, which is what keeps a model from eating the
+     * blank line between two blocks. Reassembly is
+     * `chunks.map(chunk => chunk.text + chunk.separator).join('')`.
+     */
+    separator: string;
+}
+/**
+ * Split a document body into translation units, in document order.
+ *
+ * The returned chunks partition the body: each chunk's text followed by its own
+ * {@link DocumentChunk.separator}, concatenated in order, is the input byte for
+ * byte. Every prose chunk fits {@link MAX_DOCUMENT_CHUNK_CHARS}; code chunks are
+ * as long as the fence they hold, however long that is, because they are never
+ * sent anywhere.
+ *
+ * The fence rule reads a fence indented up to three spaces as a fence, which is
+ * exactly a fence inside a list item, and passes it through verbatim like any
+ * other. A four-space indented code block is read as prose — the Markdown rule
+ * for it is contextual, and the indentation it shares with a list item's
+ * continuation text made every non-contextual test for it wrong on real
+ * documents — so its text does reach a provider.
+ * @param text - the document body, frontmatter already removed by the caller.
+ * @returns the chunks, in document order; none for a body with no text at all.
+ */
+export declare function chunkDocument(text: string): DocumentChunk[];

package/lib/types/packages/market-translation/src/application/translation/localizer.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Localize translatable fields without ever blocking the read path.
+ *
+ * The market reads an upstream catalog whose prose is English. A zh deployment
+ * wants Chinese, so every unit with no cached translation is queued for the
+ * provider chain and the caller keeps rendering the original until the
+ * translation lands.
+ *
+ * Three properties matter more than throughput:
+ *
+ * - **The read never waits.** {@link TranslationLocalizer.localize} is
+ *   synchronous and answers from the in-memory cache. A miss returns the
+ *   original text plus a pending flag; the work happens off the read path.
+ * - **A failure is invisible.** An unavailable, throttled, or broken provider
+ *   degrades to the original text. Nothing here throws into the caller.
+ * - **Each text is paid for once.** The cache survives restarts, and the queue
+ *   is indexed by the source text: the cache key names the entity, but two
+ *   entities carrying one text share one provider call and each keeps its own
+ *   entry. A text that keeps failing backs off instead of retrying in a loop.
+ * @module application/translation/localizer
+ */
+import type { TranslationUnit } from './unit.js';
+import { type TranslationProvider } from './chain.js';
+/** The localization answer for one field. */
+export interface LocalizedText {
+    /** The text to render now: the translation when cached, else the original. */
+    text: string;
+    /** True when a translation is queued or in flight and the text may improve. */
+    pending: boolean;
+}
+export interface LocalizerOptions {
+    /** The plugin's own storage root; the cache file lives directly inside it. */
+    dataRoot: string;
+    /** The ordered provider chain; empty means translation is a no-op. */
+    providers: readonly TranslationProvider[];
+    /**
+     * Stable identity of the current chain, folded into every cache key.
+     *
+     * Read per call, never cached: a deployment that switches providers must
+     * miss the cache it filled under the old one rather than serve the old
+     * engine's output as if it were the new engine's.
+     */
+    providerIdentity: () => string;
+    /**
+     * Whether translation is switched on, read per call rather than captured.
+     *
+     * The settings switch can flip long after construction, so a chain built once
+     * must still stop and start with it. Absent means always on, which keeps the
+     * localizer usable on its own in a test.
+     */
+    enabled?: (() => boolean) | undefined;
+    /** Clock seam; tests drive backoff and TTL through it. */
+    now?: (() => number) | undefined;
+}
+/** Texts per provider call. Bounds both payload size and the blast radius of one failure. */
+export declare const MAX_BATCH_SIZE = 20;
+/**
+ * Source characters per provider call.
+ *
+ * The model hop sizes one call's output from the source that call carries (see
+ * `runtime/host/llm-translator.ts`), so this is the input half of the same
+ * number: 6,400 source characters is what one call's response is sized for, and
+ * {@link MAX_DOCUMENT_CHUNK_CHARS} bounds each text inside it first. A
+ * count-only cap let a batch of document chunks ask for several times the output
+ * the call is allowed to produce, and a generation cut off at that ceiling fails
+ * the whole batch *and* retires the model hop for the rest of the session
+ * (`chain.ts` trips a provider on any failure).
+ *
+ * The expansion this covers is measured over this repository's own bilingual
+ * documents — 0.461 of the English character count at the median, 0.617 at the
+ * worst, over 90 pairs. What that costs in *tokens* is an estimate rather than a
+ * measurement, because nothing in this tree tokenizes; the arithmetic lives with
+ * the translator's own constant.
+ *
+ * The binding constraint is the model hop's own output budget, not a vendor
+ * request limit. The two public endpoints this chain calls are the consumer
+ * endpoints the vendors' own translation widgets call, not the Cloud APIs whose
+ * documented per-request limits are quoted for these products, so no
+ * request-size number is claimed here. Moving a hop onto an officially
+ * documented API would have to re-derive this constant against that API's own
+ * limit.
+ *
+ * Description traffic reaches this budget only for a long field: a description
+ * longer than one chunk travels in chunks like a document body, and everything
+ * shorter batches by count.
+ */
+export declare const MAX_BATCH_CHARS = 6400;
+/**
+ * English output can expand Chinese source; reserve a smaller raw-source batch
+ * for the model adapter's estimated 1.5 tokens per source character. Separators
+ * and masking can expand the payload further, so this is not a truncation guarantee.
+ */
+export declare const MAX_EN_BATCH_CHARS = 2400;
+/**
+ * How long an enqueue waits for company before its batch starts.
+ *
+ * Callers enqueue as they discover text: the panel learns one description per
+ * file it reads, so a synchronous pump sent one text per provider call. A
+ * short deferral lets a burst land in one batch, and a lone unit waits at most
+ * this long — invisible beside a provider round trip. A batch that is already
+ * full never waits: {@link TranslationLocalizer.schedulePump} cancels the
+ * window and starts it immediately, so a burst's throughput is unchanged and
+ * only its grouping is.
+ */
+export declare const BATCH_COALESCE_MS = 25;
+/**
+ * Whether prose contains text to translate into the resolved interface language.
+ * Chinese targets retain the Latin-versus-Han heuristic; English targets accept
+ * any Han text, including Chinese embedded in predominantly English prose.
+ * @param text - upstream prose; blank and absent values never queue work.
+ * @param target - resolved target language, defaulting to Chinese for existing callers.
+ */
+export declare function needsTranslation(text: string | undefined, target?: string): text is string;
+/**
+ * Owns the translation cache, the text-indexed queue, and the retry policy.
+ *
+ * One instance per plugin activation; {@link load} must run before the first
+ * {@link localize} so cached translations are available synchronously.
+ */
+export declare class TranslationLocalizer {
+    private readonly dataRoot;
+    private readonly providers;
+    private readonly providerIdentity;
+    private readonly now;
+    private entries;
+    /**
+     * Translations indexed by source text rather than by entity.
+     *
+     * The cache key names the entity, which is what makes the file the record of
+     * what was translated for whom — and it is also what made one text two
+     * provider calls when two entities carried it. This index is the other half:
+     * a text already answered for one entity answers for every other, and the
+     * answer is written under the second entity's own key so its durable record
+     * is complete as well.
+     *
+     * Derived state, never loaded from disk: entries are keyed by entity and
+     * carry no text, so the index warms as reads hit those entries and as batches
+     * land. Every entity read in one session is therefore served from the first
+     * read of its text, and the next session serves each entity from its own
+     * entry.
+     */
+    private readonly byText;
+    private readonly documentRetries;
+    /** The text each queued or running job owns, so a second entity carrying it waits for that answer. */
+    private readonly owners;
+    private readonly pending;
+    /** Keys already running, so a second request for one key does not queue twice. */
+    private readonly inflight;
+    /**
+     * Per-text attempt count and the earliest retry time.
+     *
+     * Keyed by text rather than by entity key: a text the provider cannot answer
+     * fails the same way wherever it is rendered, so one attempt budget belongs
+     * to it. Keyed per entity, a broken chain would burn that budget once per
+     * field — the spend this index exists to bound.
+     */
+    private readonly retry;
+    private active;
+    /** Invalidated work cannot mutate a later queue or cache. */
+    private generation;
+    private readonly controllers;
+    private lastEnabled;
+    /** Serializes cache writes and deletion, including a write already in flight. */
+    private persistence;
+    /** The armed coalescing window, or undefined when no pump is scheduled. */
+    private pumpTimer;
+    private dirty;
+    private flushTimer;
+    private disposed;
+    /** Consulted per call: the settings switch may flip long after construction. */
+    private readonly enabled;
+    constructor(options: LocalizerOptions);
+    /**
+     * Read the persisted cache once. A missing or unreadable file is not an
+     * error: the market simply starts with nothing translated.
+     */
+    load(): Promise<void>;
+    /**
+     * Drop every cached translation, in memory and on disk.
+     *
+     * The caller re-reads afterwards: the panel translates lazily, so the next
+     * read is what repopulates the cache.
+     *
+     * A provider the chain retired after an earlier failure goes with it. Clearing
+     * is an explicit "translate this again", and without this half a single
+     * cut-off generation — or one endpoint that was down for a minute — leaves
+     * the model hop out of the chain for the rest of the process: every later
+     * batch skips it, every read reports nothing pending, and no control on screen
+     * can bring it back. The cost bound the chain exists for is one attempt per
+     * user request, not one for the process's lifetime.
+     * Invalidates queued and running work. Calls made after the reset starts may
+     * enqueue new work; their writes follow the deletion.
+     * @returns fulfillment after prior cache writes and the deletion finish.
+     */
+    clear(): Promise<void>;
+    /**
+     * Forget why translation failed, keeping every translation already made.
+     *
+     * This is the settings switch's own "try again", and it is not the same as
+     * {@link clear}: clearing re-pays for the whole cache, while switching back on
+     * only asks for the failures to be forgotten. Both halves of a failure record
+     * go together — the per-text attempt budget, or a text that spent its four
+     * attempts never queues again, and the chain's process-wide breaker, or a
+     * retired provider is skipped for the rest of the process. Resetting one
+     * without the other is why switching off and on used to recover nothing that
+     * clearing the cache did not.
+     */
+    resetFailures(): void;
+    /**
+     * Apply a live settings change. Off cancels unfinished work without deleting
+     * cached answers; on resets failures and waits for the next read to enqueue.
+     * Call from the settings subscription so cancellation needs no panel read.
+     */
+    onEnabledChanged(): void;
+    private syncEnabled;
+    private cancelWork;
+    /** Number of texts waiting for a provider call; drives the client's re-read. */
+    get pendingCount(): number;
+    /**
+     * Resolve one field for the active locale.
+     *
+     * Never awaits and never throws. A cached translation wins; otherwise the
+     * original text is returned and the unit is queued when the chain has an
+     * available provider and the text actually needs translating.
+     *
+     * The preference is resolved to the language the interface actually renders
+     * before anything else reads it, and that target — not the preference tag —
+     * is what the cache key and the provider call carry. So `ja` and `zh-Hant`
+     * read the Chinese dictionary and are served the Chinese entry a `zh` reader
+     * already paid for, and an English interface answers the same way here as it
+     * does at every surface's own gate.
+     * @param unit - the surface, entity id, role, and upstream text.
+     * @param locale - the host interface preference the panel renders under.
+     * @returns the text to render now and whether it may still improve.
+     */
+    localize(unit: TranslationUnit, locale: string): LocalizedText;
+    /**
+     * Identity of one source text under a target and a provider chain.
+     *
+     * The target and the chain are part of it for the reason the cache key
+     * carries them: a Chinese answer must never serve an English request, and one
+     * engine's output must never be handed over as another's. The role is absent
+     * on purpose — a description and a document chunk with the same text are one
+     * text to translate, and the translation of a string does not depend on which
+     * field it fills.
+     * @param target - the resolved target language tag.
+     * @param identity - the provider chain's identity for this call.
+     * @param text - the source text exactly as authored.
+     * @returns the index key shared by every entity carrying this text.
+     */
+    private textIdentity;
+    private identityFor;
+    /** Retry this document's failed texts without discarding completed translations. */
+    retryDocument(surface: TranslationUnit['surface'], id: string): void;
+    /** Publish and persist a paragraph only after every bounded part has an answer. */
+    localizeParagraph(unit: TranslationUnit, parts: readonly string[] | undefined, locale: string): LocalizedText & {
+        failed?: boolean;
+    };
+    /** Write one shared answer under one entity's key and mark the cache for a flush. */
+    private record;
+    /**
+     * Queue one job unless its text is already queued, running, or backing off.
+     *
+     * The return value is what the caller reports as pending, so a text that is
+     * waiting out a backoff — or that has exhausted its attempts — answers
+     * "nothing more is coming" and the panel stops re-reading. Reporting pending
+     * for work that will never start would poll the overview forever. An entity
+     * whose text is in flight for another entity reports pending without queueing
+     * a call of its own: one call answers both, and the alias is served the
+     * moment it lands.
+     * @param job - the unit to translate and the key it will be cached under.
+     * @returns whether this text now has work queued or running.
+     */
+    private enqueue;
+    /**
+     * Arrange the next pump: now for a full batch, else after the coalescing
+     * window so the units a burst is still adding ride the same provider call.
+     */
+    private schedulePump;
+    /** Only work with the same target can fill a provider batch. */
+    private hasFullBatch;
+    /** Start as many queued batches as the concurrency cap allows. */
+    private pump;
+    /**
+     * Run one batch. A batch-level failure backs off every member; a single empty
+     * result backs off only that text, so one bad text cannot stall nineteen good
+     * ones. Every failure path is silent for the caller: the panel keeps the
+     * original text either way.
+     */
+    private run;
+    /** Record one failed attempt and push the text's next try further out. */
+    private fail;
+    /**
+     * Batch successful translations into one write instead of one per text.
+     *
+     * A translation that lands after {@link dispose} has no timer to ride and no
+     * later read to pick it up, so it is written immediately: otherwise the call
+     * is paid for and the result is dropped on unload.
+     */
+    private scheduleFlush;
+    /** Persist the cache when it changed. A failed write keeps the in-memory copy. */
+    flush(): Promise<void>;
+    /**
+     * Wait until the queue drains or the deadline passes.
+     *
+     * Warm-up uses this so a scan can hand off and a test can assert the result
+     * without polling; production never blocks a request on it.
+     * @param deadlineMs - maximum wait; omitted waits for the queue alone.
+     * @returns whether the queue drained before the deadline.
+     */
+    settle(deadlineMs?: number): Promise<boolean>;
+    /**
+     * Cancel timers and drop queued work; in-flight calls finish and are
+     * persisted by {@link flush}.
+     *
+     * A disposed instance cannot deliver its queue — {@link enqueue} refuses new
+     * work and the pump refuses to start — so leaving it populated would strand
+     * its units behind a {@link pendingCount} that never falls, and a
+     * {@link settle} waiting on them would run out its deadline instead of
+     * returning. Dropping them costs nothing durable: translation is lazy, the
+     * cache is the only state that has to survive, and the next activation's
+     * first read queues whatever is still missing.
+     */
+    dispose(): void;
+}

package/lib/types/packages/market-translation/src/application/translation/service.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The market's translation service: the reads a catalog surface asks for, over
+ * one localizer this service owns.
+ *
+ * The three reads are the whole translation vocabulary a surface needs — one
+ * entity's fields, one authored text, one Markdown document — and every one of
+ * them resolves through the same localizer, so the cache, the queue and the
+ * provider chain stay a single instance per activation. The localizer's own
+ * lifecycle (load, dispose, clear, enabled edge, settle) is forwarded rather
+ * than re-exposed, so a caller cannot reach past it.
+ * @module application/translation/service
+ */
+import type { DocumentTranslation, TranslationFields, TranslationSurfaceKind } from '../../../../market-contracts/src/contracts/translation.js';
+import { type LocalizerOptions } from './localizer.js';
+/** Composition options of the service; the localizer's own options, unchanged. */
+export type TranslationServiceOptions = LocalizerOptions;
+export declare class TranslationService {
+    private readonly localizer;
+    constructor(options: LocalizerOptions);
+    /** Read the persisted cache once, before the first {@link translateFields} read. */
+    load(): Promise<void>;
+    /** Cancel timers and drop queued work; in-flight calls finish and are persisted. */
+    dispose(): void;
+    /** Drop every cached translation, in memory and on disk. */
+    clear(): Promise<void>;
+    /** Apply a live display-preference change: off cancels unfinished work, on forgets failures. */
+    onEnabledChanged(): void;
+    /** Wait until the queue drains or the deadline passes. */
+    settle(deadlineMs?: number): Promise<boolean>;
+    /**
+     * Translate one entity's description for a surface.
+     *
+     * Only the description is a translatable field: a name is an identity the user
+     * types, greps, and matches against upstream documentation, so the collector
+     * hands back no unit for one. Nothing here waits on a provider: an uncached
+     * field answers with the upstream text and reports itself pending.
+     *
+     * A description longer than one chunk travels in chunks, exactly as a
+     * document body does ({@link localizeText}), so the size of an upstream field
+     * is never a reason for a provider call to be cut off.
+     *
+     * Exposed for the panel and status surfaces that build their own rows; it is
+     * not part of the HTTP route surface.
+     * @param surface - the surface the entity belongs to.
+     * @param id - the entity's stable identity inside that surface.
+     * @param fields - the entity's upstream name and description.
+     * @param locale - the host locale this read resolved once; there is no
+     * default, because a default would re-read the host preference per entity and
+     * make a read's cost scale with its row count.
+     * @returns the translated fields and how many of them are still pending.
+     */
+    translateFields(surface: TranslationSurfaceKind, id: string, fields: {
+        name?: string | undefined;
+        description?: string | undefined;
+    }, locale: string): {
+        fields: TranslationFields;
+        pending: number;
+    };
+    /**
+     * Translate one authored text, chunk by chunk, and reassemble it exactly.
+     *
+     * Every text the layer sends travels the way a document does: split on blank
+     * lines into chunks one request may carry, fenced code passed through
+     * verbatim, and the authored text between chunks re-emitted rather than
+     * synthesized — so a text nothing was translated for comes back byte for
+     * byte, and a translated one keeps the author's own blank lines. A
+     * description is chunked for the same reason a document is: the model hop
+     * sizes one call's output from the source it carries, and a text that exceeds
+     * that budget is cut off mid-generation, which fails the batch and retires the
+     * provider for the rest of the session.
+     * @param surface - the surface the entity belongs to.
+     * @param id - the entity's stable identity inside that surface.
+     * @param role - which text of the entity this is; the cache key's role slot.
+     * @param text - the authored text.
+     * @param locale - the interface language this read resolved once.
+     * @returns the reassembled text and how many of its chunks are still in flight.
+     */
+    private localizeText;
+    /**
+     * Translate paragraphs in one complete Markdown tree. The provider receives
+     * prose only. Links, code, math, references and nested containers remain local.
+     * The result includes a translated document and paragraph-paired Markdown.
+     * Unchanged output preserves the source bytes. Changed output preserves the
+     * parsed structure and uses canonical Markdown formatting. Pending paragraphs
+     * remain authored until complete. The retry flag resets only this document
+     * failure budgets and the provider breaker, without clearing cached successes.
+     */
+    translateDocument(surface: TranslationSurfaceKind, id: string, text: string, locale: string, retry?: boolean): DocumentTranslation;
+}

package/lib/types/packages/market-translation/src/application/translation/unit.d.ts

@@ -0,0 +1,35 @@
+import type { TranslationRole, TranslationSurfaceKind } from '../../../../market-contracts/src/contracts/translation.js';
+/** One translatable field: the entity it belongs to and the source text. */
+export interface TranslationUnit {
+    surface: TranslationSurfaceKind;
+    /** Stable identity of the entity inside its surface (e.g. "sourceId/suiteId"). */
+    id: string;
+    /** The upstream text, exactly as authored. */
+    text: string;
+    /**
+     * Which text of the entity this is; the cache key's role slot.
+     *
+     * Absent means {@link TranslationRole}'s description — the only role the
+     * layer had before document bodies joined it — so every entry already on disk
+     * keeps the key it was written under.
+     */
+    role?: TranslationRole | undefined;
+    /** Optional cache namespace for document algorithms; legacy fields omit it. */
+    strategy?: string | undefined;
+}
+/**
+ * Collect units for one entity, skipping empty or undefined text.
+ *
+ * Descriptions only: a name is an identifier the user types and matches against
+ * upstream documentation, and translating one made it harder to recognize than
+ * the original. The text is carried verbatim — the emptiness check trims, but
+ * the unit does not, so the cache key stays tied to what upstream authored.
+ * @param surface - the surface the entity belongs to.
+ * @param id - the entity's stable identity inside that surface.
+ * @param fields - the entity's upstream name and description.
+ * @returns the units to translate.
+ */
+export declare function collectUnits(surface: TranslationSurfaceKind, id: string, fields: {
+    name?: string | undefined;
+    description?: string | undefined;
+}): TranslationUnit[];

package/lib/types/packages/market-translation/src/index.d.ts

@@ -0,0 +1,4 @@
+/** Explicit cross-domain entry surface. Internal modules are not import targets for siblings. */
+export { TranslationService } from './application/translation/service.js';
+export { createLlmTranslator } from './runtime/host/llm-translator.js';
+export { createTranslationProviders } from './runtime/host/translation-providers.js';

package/lib/types/packages/market-translation/src/runtime/host/llm-translator.d.ts

@@ -0,0 +1,30 @@
+import type { TranslationProvider } from '../../application/translation/chain.js';
+/** The host seams this translator reads; every one is optional at composition. */
+export interface TranslatorHost {
+    get?(name: string): unknown;
+}
+/** Ceiling for one call, so a large one cannot ask for an unbounded generation. */
+export declare const MAX_OUTPUT_TOKENS_CAP = 4096;
+/**
+ * The output budget for one call carrying this much source text.
+ *
+ * Sized from the source rather than from the text count: what a call has to
+ * answer is the expansion of the text it was handed, so a batch of one long
+ * text and a batch of twenty short ones are budgeted by the same rule.
+ * @param sourceChars - characters in the user turn this call will send.
+ * @param locale - target language; English uses the larger expansion allowance.
+ * @returns the output token ceiling to ask the route for.
+ */
+export declare function outputTokenBudget(sourceChars: number, locale?: string): number;
+/**
+ * Build the model-backed provider over one plugin context.
+ *
+ * Every read is deferred to the call, because the LLM and default-model
+ * services provision after apply() returns; a value captured here would stay
+ * undefined for the life of the process. available() therefore re-resolves the
+ * route on each question, and a deployment with no model configured never
+ * queues work nothing can complete.
+ * @param host - the plugin context, read structurally so tests can pass a stub.
+ * @returns a provider bound to this context.
+ */
+export declare function createLlmTranslator(host: TranslatorHost): TranslationProvider;

package/lib/types/packages/market-translation/src/runtime/host/machine-translator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The two keyless public machine-translation endpoints, as batch adapters.
+ *
+ * Both are called by the chain in `application/translation/chain.ts`; the
+ * network effect lives here so the chain stays pure orchestration. Each
+ * endpoint takes one array and answers with one array in the same order, which
+ * is what lets a batch of twenty units travel as a single request.
+ *
+ * Neither requires registration, a token or a proxy, and that is the whole
+ * point of the pair: the market ships translation on by default, with nothing
+ * for the operator to configure.
+ * @module runtime/host/machine-translator
+ */
+import type { TranslationProviderId } from '../../../../market-contracts/src/contracts/translation.js';
+/** One batch translation over a keyless public endpoint. */
+export interface MachineTranslationRequest {
+    /** The texts to translate, in the order the answers must come back in. */
+    texts: readonly string[];
+    /** Target locale id, as the host names it (for example `zh`). */
+    locale: string;
+    /** Caller cancellation, merged by the chain with this provider's deadline. */
+    signal: AbortSignal;
+}
+/** One batch translation result, tagged with the endpoint that produced it. */
+export interface MachineTranslationResult {
+    /** The translations, positionally aligned with the request. */
+    texts: string[];
+    /** The endpoint that answered. */
+    provider: TranslationProviderId;
+}
+/**
+ * Translate one batch through Google's public endpoint.
+ *
+ * The body is the endpoint's own protobuf-JSON envelope: a single triple of
+ * texts, source language and target language, tagged `wt_lib` so the answer
+ * comes back as a plain array rather than as the widget's HTML payload.
+ * @param request - the batch, its target locale and cancellation.
+ * @returns the translations and the provider id.
+ * @throws when the request fails, the endpoint refuses it, or the answer does not line up.
+ */
+export declare function googleTranslate(request: MachineTranslationRequest): Promise<MachineTranslationResult>;
+/**
+ * Translate one batch through Microsoft's public endpoint.
+ *
+ * The body is the bare string array, and the languages ride the query string.
+ * `isEnterpriseClient=false` selects the consumer backend, which is the one
+ * that answers without authentication.
+ * @param request - the batch, its target locale and cancellation.
+ * @returns the translations and the provider id.
+ * @throws when the request fails, the endpoint refuses it, or the answer does not line up.
+ */
+export declare function microsoftTranslate(request: MachineTranslationRequest): Promise<MachineTranslationResult>;

package/lib/types/packages/market-translation/src/runtime/host/text-masking.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Mask the spans a machine engine corrupts, then restore them from its answer.
+ *
+ * Neither keyless endpoint leaves technical text alone: Google's HTML aligner
+ * escapes a bare `<`, and Microsoft folds angle brackets into pseudo-tags. The
+ * spans those engines damage — inline code, URLs, tag fragments and `${VAR}`
+ * paths — are exactly what a catalog description is made of, and the fixed terms
+ * are the ones an engine likes to paraphrase. Sending a bracketed token instead
+ * keeps the payload plain, and the restore table puts the original text back.
+ *
+ * The same table is the integrity check. An answer is accepted only when every
+ * placeholder it recorded comes back exactly once and nothing placeholder-shaped
+ * was invented, so a truncated or rewritten answer is discarded rather than
+ * rendered with a stray `⟦C1⟧` in it.
+ * @module runtime/host/text-masking
+ */
+/** One masked payload: the text to send, and the restore table. */
+export interface MaskedText {
+    /** The text to hand to a translation engine. */
+    text: string;
+    /** Placeholder to original span, for {@link unmaskText}. */
+    placeholders: ReadonlyMap<string, string>;
+}
+/**
+ * Replace every span the engines damage with a numbered placeholder.
+ * @param input - the upstream text, exactly as authored.
+ * @returns the text to send, and the table that restores it.
+ */
+export declare function maskText(input: string): MaskedText;
+/**
+ * Put every masked span back, or reject the answer.
+ *
+ * An answer is rejected — `undefined`, so the caller discards the item instead
+ * of caching it — when a placeholder is missing, arrives twice, or when the
+ * engine invented one of its own. A short answer that dropped a placeholder
+ * would otherwise restore a sentence with a hole in it, and an invented one
+ * would render as literal brackets.
+ * @param masked - the text the engine returned.
+ * @param placeholders - the table {@link maskText} produced for that text.
+ * @returns the restored text, or `undefined` when the answer cannot be trusted.
+ */
+export declare function unmaskText(masked: string, placeholders: ReadonlyMap<string, string>): string | undefined;