@phis/contracts 0.3.1 → 0.4.0

package/dist/threads.d.ts

@@ -0,0 +1,363 @@
+/**
+ * Threads, in the words both ends read them with.
+ *
+ * A thread is a conversation between people on one Site: two colleagues, a group, two groups, or a
+ * customer and a Support queue. Core stores it, the site UI renders it, and an Add-on may be handed a
+ * bounded view of one -- three readers of one shape, which is why the shape lives here rather than in
+ * any of them.
+ *
+ * It was two shapes before this file existed. The Site routes answered with database records carrying
+ * addresses, `threads:v1` answered with a projection that deliberately carried none, and the Support
+ * Module typed itself against the first. The same thread therefore had two descriptions, and the one a
+ * reader got depended on which door they came through.
+ *
+ * Who may see what is not in this file and cannot be: visibility is decided in Core, per reader, and a
+ * vocabulary shared with a browser is the last place to state a rule. What is here is what a visible
+ * thread looks like once Core has decided it is one.
+ */
+import type { PhisUserProjection } from "./capabilities.js";
+/**
+ * Who a thread is between.
+ *
+ * The kind is fixed when the thread is opened and is not a filter over its participants: it says which
+ * conversation this is, and each one is offered, or not, by the Modules a Site runs.
+ */
+export declare const PhisThreadKind: {
+    /** Staff to Staff, between people who share a group. */
+    readonly Direct: 0;
+    /** Inside one group, its members among themselves. */
+    readonly Group: 1;
+    /** Between groups, each participating as a whole. */
+    readonly CrossGroup: 2;
+    /** A requester and a Support queue's group. */
+    readonly Support: 3;
+};
+export type PhisThreadKindValue = (typeof PhisThreadKind)[keyof typeof PhisThreadKind];
+/**
+ * Where a thread stands.
+ *
+ * One row carries it, so archiving is the thread being closed for everyone in it rather than one reader
+ * hiding it from themselves.
+ */
+export declare const PhisThreadStatus: {
+    readonly Open: 0;
+    readonly Archived: 1;
+};
+export type PhisThreadStatusValue = (typeof PhisThreadStatus)[keyof typeof PhisThreadStatus];
+/** What is true of a thread, as bit flags. */
+export declare const PhisThreadFlag: {
+    /** No new messages are accepted; what is there stays readable. */
+    readonly Locked: number;
+};
+/**
+ * What a participant is to the thread, as bit flags.
+ *
+ * `Requester` is the one that changes what a reader sees rather than what they may do: it marks the
+ * person a Support thread is *about*, and internal messages are written past them.
+ */
+export declare const PhisThreadParticipantFlag: {
+    /** The person this Support thread belongs to. At most one participant carries it. */
+    readonly Requester: number;
+    /**
+     * This requester has acknowledged that the conversation is mirrored outside.
+     *
+     * Their messages are exported only once it is set. A customer's words are their own, and handing them
+     * to a third party is not a decision Staff may take for them.
+     */
+    readonly ExternalConsent: number;
+    /** Left the thread; their messages stay, and nothing new reaches them. */
+    readonly Left: number;
+    /** Still in it, without being notified. */
+    readonly Muted: number;
+};
+/**
+ * What is true of one message, as bit flags.
+ *
+ * `Internal` and `Confidential` answer different questions and are deliberately independent. `Internal`
+ * is *who may read it* -- Staff participants, and not the requester the note is about. `Confidential`
+ * is *where it may go* -- nowhere outside Core: not to an integration, not into the body of a
+ * notification, and not to an Add-on, which is handed the message with its text withheld and this flag
+ * set. A customer may set it themselves, which is the case that matters: a password pasted into a
+ * Support thread must be readable by the people helping and must never be mirrored anywhere.
+ */
+export declare const PhisThreadMessageFlag: {
+    readonly Internal: number;
+    readonly Confidential: number;
+    /** Edited after it was written, at its source where it came from one. */
+    readonly Edited: number;
+    /** Withdrawn: the text is gone, the message stays so the conversation still reads. */
+    readonly Redacted: number;
+    /** Written by an integration from something outside, and therefore never exported back to it. */
+    readonly Imported: number;
+    /**
+     * `sourceLang` was recognised by a translator rather than declared by whoever delivered the message.
+     *
+     * The difference between an assertion and a guess, which is why it is a flag and not a shrug. An
+     * integration states the language from something it actually has -- a mail header, the locale of the
+     * page a form was submitted from -- and a translator states what a model made of the text: right for a
+     * paragraph, a coin toss for "bongo". Anything routing or counting on the column has to be able to see
+     * which of the two it is looking at.
+     *
+     * It is set where a translation reported a language for a message that declared none, because the
+     * recognition arrives as a field on a translation that was paid for anyway and throwing it away would
+     * leave the column empty for every message a person ever wrote. Never set by a caller: Core sets it
+     * together with the value, and a declared language is never overwritten by a detected one.
+     */
+    readonly LangDetected: number;
+};
+/**
+ * Which kinds of thread a Site offers at all, as bit flags.
+ *
+ * Not a switch anybody flips. It is the union of what the Site's active Modules declare, materialized
+ * the way declared Media Space kinds are, so a Site gains a kind by running a Module that needs it. A
+ * kind that stops being declared hides its threads and deletes nothing.
+ */
+export declare const PhisSiteThreadKindFlag: {
+    readonly Direct: number;
+    readonly Group: number;
+    readonly CrossGroup: number;
+    readonly Support: number;
+};
+/**
+ * How a Module names the kind it needs, in the Area preset.
+ *
+ * A declaration travels as text, not as a number: it is written into a published Area preset by the
+ * Builder and read back by the control plane, and a stored bit would freeze the numbering of a
+ * vocabulary that is still allowed to grow. Two ends therefore have to spell these identically, which
+ * is why they are here and not in either of them.
+ *
+ * The order is the serialization order, so an unchanged selection writes byte-identically.
+ */
+export declare const PHIS_DECLARABLE_THREAD_KINDS: readonly ["direct", "group", "crossGroup", "support"];
+export type PhisDeclarableThreadKind = (typeof PHIS_DECLARABLE_THREAD_KINDS)[number];
+/** What a declared name means, for whoever has to turn one into a thread or a Site flag. */
+export declare const PHIS_THREAD_KIND_BY_DECLARATION: Readonly<Record<PhisDeclarableThreadKind, PhisThreadKindValue>>;
+export declare const PHIS_SITE_THREAD_KIND_FLAG_BY_DECLARATION: Readonly<Record<PhisDeclarableThreadKind, number>>;
+/** One thread, as a list shows it. */
+export type PhisThreadSummary = {
+    id: number;
+    kind: PhisThreadKindValue;
+    status: PhisThreadStatusValue;
+    flags: number;
+    subject: string | null;
+    createdAt: string;
+    updatedAt: string;
+    latestMessageAt: string | null;
+    /** Whether this reader has messages they have not seen. */
+    unread: boolean;
+};
+/**
+ * Who is in a thread.
+ *
+ * A group participates as a group: its members are resolved when the thread is read, so somebody who
+ * joins the group afterwards is in the conversation and somebody who leaves it is not. Expanding a
+ * group into people at the moment it was named would have frozen a membership that keeps moving.
+ */
+export type PhisThreadParticipant = {
+    kind: "user";
+    user: PhisUserProjection;
+    flags: number;
+} | {
+    kind: "group";
+    groupId: number;
+    name: string;
+    flags: number;
+};
+/**
+ * Who wrote a message.
+ *
+ * A person is projected as a group member sees one: a display name, a company where the group discloses
+ * it, never an address. An integration is not dressed up as a person -- it says which provider it is and
+ * carries the outside name it is relaying, so "octocat on GitHub" reads as what it is.
+ */
+export type PhisThreadMessageAuthor = {
+    kind: "user";
+    user: PhisUserProjection;
+} | {
+    kind: "integration";
+    providerId: string;
+    externalName: string | null;
+    externalUrl: string | null;
+} | {
+    kind: "system";
+};
+/**
+ * A file hanging on a message.
+ *
+ * Readable by whoever may read the message it hangs on, which is the whole rule: it travels inside the
+ * message rather than beside it, so an attachment on a note this reader is not shown is not in their
+ * copy of the conversation at all. Where the bytes sit -- a person's own Space, an Add-on's -- says who
+ * pays for them and who administers them, and answers nothing about who reads.
+ *
+ * There is no address on the Asset itself. Its delivery policy is `Internal`, and the only way to its
+ * bytes is the message that names it.
+ */
+export type PhisThreadMessageAsset = {
+    assetId: number;
+    fileName: string;
+    contentType: string;
+    byteSize: number;
+    flags: number;
+    /** Where the bytes are fetched from, relative to the Site. */
+    href: string;
+};
+export type PhisThreadMessage = {
+    id: number;
+    author: PhisThreadMessageAuthor;
+    /** Null where the text is withheld from this reader: redacted, or confidential to an Add-on. */
+    bodyText: string | null;
+    bodyMarkdown: string | null;
+    /**
+     * The language the body is written in, where an integration recorded it. Null is `not declared`.
+     *
+     * Never to be read as the Site's default. Nobody is asked for this: a person writing on a Site is
+     * offered no language picker, because a translator determines the source language itself. What fills it
+     * is an integration that already knows -- a mail header, the locale of the page a form came from -- so a
+     * message written by a person arrives carrying null, which is the honest answer and the one a
+     * translation reads as "you detect it".
+     *
+     * It is also filled afterwards, by the translation of a message that declared none: the language comes
+     * back as a field on a translation somebody paid for, and dropping it would keep the column empty for
+     * everything a person ever wrote. Such a value carries `LangDetected`, because a recognition is a guess
+     * and an integration's declaration is not, and a declared language is never overwritten by one.
+     *
+     * It sits on the message and not on the thread, because two people writing to each other in different
+     * languages is the case it exists for.
+     */
+    sourceLang: string | null;
+    flags: number;
+    /** What hangs on it, in the order it was attached. Empty for a message carrying only text. */
+    assets: PhisThreadMessageAsset[];
+    createdAt: string;
+    updatedAt: string;
+};
+export type PhisThreadDetail = {
+    thread: PhisThreadSummary;
+    participants: PhisThreadParticipant[];
+    /** A window of the conversation, oldest first. */
+    messages: PhisThreadMessage[];
+    /** Whether older messages remain beyond the window `messages` carries. */
+    hasMoreMessages: boolean;
+};
+/**
+ * The threads capability: `@phis/server/threads:v1`.
+ *
+ * **With an actor, an Add-on sees what its actor sees.** Every read goes through the predicate Core
+ * applies to its own thread routes, so there is no listing here a person could not have obtained
+ * themselves, and no way to turn a Site's threads into something an Add-on can walk.
+ *
+ * **Without an actor -- a job, a verified hook, an event -- it reaches a thread it owns or one it is
+ * linked to**, and nothing else. It owns the threads it opened with no actor behind it. It is linked to
+ * a thread when a `resource-links:v1` row of its own carries `Synced` and points at that thread, at a
+ * ticket, or at a ticket task whose thread it is -- and that row was written by a person who could see
+ * the thread. The link is therefore that person's consent, for one integration and one conversation,
+ * and removing it withdraws the access. There is still no listing: an actorless Add-on finds a thread by
+ * the reference it recorded, never by walking.
+ *
+ * `Internal` messages are never handed to an actorless Add-on. `Confidential` ones arrive with their
+ * text withheld, whatever the Add-on's actor could read.
+ */
+export type PhisThreadsCapabilityV1 = {
+    /** The threads the acting user is in, newest activity first. Needs an actor. */
+    list(options?: {
+        page?: number;
+        pageSize?: number;
+        unreadOnly?: boolean;
+    }): Promise<PhisThreadSummary[]>;
+    /** One thread with a window of its messages, or null where it is not reachable. */
+    get(threadId: number, options?: {
+        messageLimit?: number;
+        beforeMessageId?: number | null;
+    }): Promise<PhisThreadDetail | null>;
+    /**
+     * Opens a thread.
+     *
+     * With no actor the thread is opened as this Add-on's own, which is what an integration reporting an
+     * outside event needs and what makes the conversation reachable afterwards. Participants are named as
+     * user ids, group ids, or both, and every one is checked against this Site before anything is written.
+     *
+     * `messageFlags` is normalized rather than trusted: `Internal` requires an actor who is Staff, and
+     * `Imported` is Core's to set on what arrives through an integration.
+     */
+    create(input: {
+        kind: PhisThreadKindValue;
+        subject?: string | null;
+        message: string;
+        messageMarkdown?: string | null;
+        /**
+         * What the opening message is written in, where the integration knows.
+         *
+         * This is the **only** way the field is ever written: no Site route accepts it and no surface offers
+         * it, so a value present means an integration said so. An integration that does not know leaves it
+         * out, and the message carries null.
+         *
+         * A locale key the platform holds; anything else is refused rather than stored. Core checks that the
+         * key is well-formed and not that it is true -- naming a language over text in another one misleads
+         * every reader of it, and nothing contradicts the claim.
+         */
+        messageSourceLang?: string | null;
+        messageFlags?: number;
+        participantUserIds?: number[];
+        participantGroupIds?: number[];
+        /**
+         * Files to hang on the message, from this Add-on's own Space.
+         *
+         * Custody follows the uploader: an Add-on attaches what it wrote through `assets:v1`, never a
+         * person's file, because attaching somebody else's would put a record on their quota they did not
+         * agree to carry. Who may read it is the message's answer and never the Space's -- so a file an
+         * Add-on attaches is read by everyone in the conversation, and one it is shown is not thereby its
+         * own.
+         */
+        assetIds?: number[];
+        /** This Add-on's own reference for the message, unique within this Add-on. */
+        externalRef?: string;
+        externalAuthor?: {
+            name: string;
+            url?: string;
+        };
+    }): Promise<PhisThreadDetail>;
+    /**
+     * Adds a message to a reachable thread.
+     *
+     * Idempotent on `externalRef` where one is given: the same reference answers with the thread as it
+     * stands instead of writing a second message, which is what a webhook delivered twice needs.
+     */
+    reply(input: {
+        threadId: number;
+        message: string;
+        messageMarkdown?: string | null;
+        /** What this message is written in, on the terms `create` states. */
+        messageSourceLang?: string | null;
+        messageFlags?: number;
+        /** Files to hang on the reply, from this Add-on's own Space. See `create`. */
+        assetIds?: number[];
+        externalRef?: string;
+        externalAuthor?: {
+            name: string;
+            url?: string;
+        };
+    }): Promise<PhisThreadDetail | null>;
+    /** Brings more people into a reachable thread. Adds only; it never removes. */
+    addParticipants(input: {
+        threadId: number;
+        participantUserIds?: number[];
+        participantGroupIds?: number[];
+    }): Promise<PhisThreadDetail | null>;
+    /** Moves a reachable thread between open and archived, for everyone in it. */
+    setStatus(input: {
+        threadId: number;
+        status: PhisThreadStatusValue;
+    }): Promise<boolean>;
+    /** Marks the thread read for the acting user, up to its newest message or to one named. */
+    markRead(input: {
+        threadId: number;
+        messageId?: number | null;
+    }): Promise<boolean>;
+    /**
+     * The thread carrying one of this Add-on's own message references, or null.
+     *
+     * How an actorless Add-on arrives at a thread at all. The reference is the one it passed to `create`
+     * or `reply`, so it finds its way back to a conversation it already knows about and to no other.
+     */
+    findByExternalRef(externalRef: string): Promise<PhisThreadDetail | null>;
+};

package/dist/threads.js

@@ -0,0 +1,146 @@
+/**
+ * Threads, in the words both ends read them with.
+ *
+ * A thread is a conversation between people on one Site: two colleagues, a group, two groups, or a
+ * customer and a Support queue. Core stores it, the site UI renders it, and an Add-on may be handed a
+ * bounded view of one -- three readers of one shape, which is why the shape lives here rather than in
+ * any of them.
+ *
+ * It was two shapes before this file existed. The Site routes answered with database records carrying
+ * addresses, `threads:v1` answered with a projection that deliberately carried none, and the Support
+ * Module typed itself against the first. The same thread therefore had two descriptions, and the one a
+ * reader got depended on which door they came through.
+ *
+ * Who may see what is not in this file and cannot be: visibility is decided in Core, per reader, and a
+ * vocabulary shared with a browser is the last place to state a rule. What is here is what a visible
+ * thread looks like once Core has decided it is one.
+ */
+/**
+ * Who a thread is between.
+ *
+ * The kind is fixed when the thread is opened and is not a filter over its participants: it says which
+ * conversation this is, and each one is offered, or not, by the Modules a Site runs.
+ */
+export const PhisThreadKind = {
+    /** Staff to Staff, between people who share a group. */
+    Direct: 0,
+    /** Inside one group, its members among themselves. */
+    Group: 1,
+    /** Between groups, each participating as a whole. */
+    CrossGroup: 2,
+    /** A requester and a Support queue's group. */
+    Support: 3,
+};
+/**
+ * Where a thread stands.
+ *
+ * One row carries it, so archiving is the thread being closed for everyone in it rather than one reader
+ * hiding it from themselves.
+ */
+export const PhisThreadStatus = {
+    Open: 0,
+    Archived: 1,
+};
+/** What is true of a thread, as bit flags. */
+export const PhisThreadFlag = {
+    /** No new messages are accepted; what is there stays readable. */
+    Locked: 1 << 0,
+};
+/**
+ * What a participant is to the thread, as bit flags.
+ *
+ * `Requester` is the one that changes what a reader sees rather than what they may do: it marks the
+ * person a Support thread is *about*, and internal messages are written past them.
+ */
+export const PhisThreadParticipantFlag = {
+    /** The person this Support thread belongs to. At most one participant carries it. */
+    Requester: 1 << 0,
+    /**
+     * This requester has acknowledged that the conversation is mirrored outside.
+     *
+     * Their messages are exported only once it is set. A customer's words are their own, and handing them
+     * to a third party is not a decision Staff may take for them.
+     */
+    ExternalConsent: 1 << 1,
+    /** Left the thread; their messages stay, and nothing new reaches them. */
+    Left: 1 << 2,
+    /** Still in it, without being notified. */
+    Muted: 1 << 3,
+};
+/**
+ * What is true of one message, as bit flags.
+ *
+ * `Internal` and `Confidential` answer different questions and are deliberately independent. `Internal`
+ * is *who may read it* -- Staff participants, and not the requester the note is about. `Confidential`
+ * is *where it may go* -- nowhere outside Core: not to an integration, not into the body of a
+ * notification, and not to an Add-on, which is handed the message with its text withheld and this flag
+ * set. A customer may set it themselves, which is the case that matters: a password pasted into a
+ * Support thread must be readable by the people helping and must never be mirrored anywhere.
+ */
+export const PhisThreadMessageFlag = {
+    Internal: 1 << 0,
+    Confidential: 1 << 1,
+    /** Edited after it was written, at its source where it came from one. */
+    Edited: 1 << 2,
+    /** Withdrawn: the text is gone, the message stays so the conversation still reads. */
+    Redacted: 1 << 3,
+    /** Written by an integration from something outside, and therefore never exported back to it. */
+    Imported: 1 << 4,
+    /**
+     * `sourceLang` was recognised by a translator rather than declared by whoever delivered the message.
+     *
+     * The difference between an assertion and a guess, which is why it is a flag and not a shrug. An
+     * integration states the language from something it actually has -- a mail header, the locale of the
+     * page a form was submitted from -- and a translator states what a model made of the text: right for a
+     * paragraph, a coin toss for "bongo". Anything routing or counting on the column has to be able to see
+     * which of the two it is looking at.
+     *
+     * It is set where a translation reported a language for a message that declared none, because the
+     * recognition arrives as a field on a translation that was paid for anyway and throwing it away would
+     * leave the column empty for every message a person ever wrote. Never set by a caller: Core sets it
+     * together with the value, and a declared language is never overwritten by a detected one.
+     */
+    LangDetected: 1 << 5,
+};
+/**
+ * Which kinds of thread a Site offers at all, as bit flags.
+ *
+ * Not a switch anybody flips. It is the union of what the Site's active Modules declare, materialized
+ * the way declared Media Space kinds are, so a Site gains a kind by running a Module that needs it. A
+ * kind that stops being declared hides its threads and deletes nothing.
+ */
+export const PhisSiteThreadKindFlag = {
+    Direct: 1 << 0,
+    Group: 1 << 1,
+    CrossGroup: 1 << 2,
+    Support: 1 << 3,
+};
+/**
+ * How a Module names the kind it needs, in the Area preset.
+ *
+ * A declaration travels as text, not as a number: it is written into a published Area preset by the
+ * Builder and read back by the control plane, and a stored bit would freeze the numbering of a
+ * vocabulary that is still allowed to grow. Two ends therefore have to spell these identically, which
+ * is why they are here and not in either of them.
+ *
+ * The order is the serialization order, so an unchanged selection writes byte-identically.
+ */
+export const PHIS_DECLARABLE_THREAD_KINDS = [
+    "direct",
+    "group",
+    "crossGroup",
+    "support",
+];
+/** What a declared name means, for whoever has to turn one into a thread or a Site flag. */
+export const PHIS_THREAD_KIND_BY_DECLARATION = {
+    direct: PhisThreadKind.Direct,
+    group: PhisThreadKind.Group,
+    crossGroup: PhisThreadKind.CrossGroup,
+    support: PhisThreadKind.Support,
+};
+export const PHIS_SITE_THREAD_KIND_FLAG_BY_DECLARATION = {
+    direct: PhisSiteThreadKindFlag.Direct,
+    group: PhisSiteThreadKindFlag.Group,
+    crossGroup: PhisSiteThreadKindFlag.CrossGroup,
+    support: PhisSiteThreadKindFlag.Support,
+};

package/dist/translation.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The Translation service kind, as a Provider implements it.
+ *
+ * Core owns the question -- which text, out of which language, into which one -- and keeps asking it
+ * from the places that already translate: the global and Site message stores, and a conversation
+ * message somebody asked to read in their own language. A Provider answers it and nothing else.
+ * Nothing here reaches a database, a request, or a secret store: the Provider gets configuration and a
+ * context, and answers about text.
+ *
+ * What a Provider talks to is its own business, and deliberately not described here. A vendor over
+ * HTTP, a model on the machine, a catalogue it maintains itself and a CDN it consults first are all the
+ * same shape from Core's side, which is the reason this is a service kind rather than a list of
+ * vendors Core knows the names of.
+ */
+export type PhisTranslationProviderId = `@${string}/${string}`;
+/**
+ * How the text is to be read.
+ *
+ * `text` includes Markdown. Control characters survive a translation unchanged, so a Provider is not
+ * told about Markdown and has no reason to be: the markup arrives as part of the text and leaves as
+ * part of it. `html` is the case where tags must be recognised rather than carried, because a
+ * translator that reorders words around them has to know which spans it may not split.
+ */
+export type PhisTranslationFormat = "text" | "html";
+export type PhisTranslationRequest = {
+    /**
+     * A batch, and the ordinary case rather than the exception.
+     *
+     * Core asks for everything it needs in one call -- a page of labels, a store's worth of messages --
+     * and splits only where a Provider's own request limit forces it. The answer holds exactly as many
+     * entries as the request, in its order; a Provider never drops, merges or reorders one, because the
+     * caller matches them back by position and nothing else.
+     *
+     * One text is a batch of one and takes the same path.
+     */
+    texts: readonly string[];
+    /**
+     * What the text is written in, or `null` to let the Provider decide.
+     *
+     * `null` is a real case and not an omission: a Site message may carry no declared source, and a
+     * conversation message written before anybody was asked carries none either. What Core must not do
+     * is invent one, which is why this is nullable rather than defaulted.
+     */
+    sourceLang: string | null;
+    targetLang: string;
+    format: PhisTranslationFormat;
+    /**
+     * Context for the translator, and never translated itself.
+     *
+     * Natural language that influences how the text is read -- the subject matter, the surrounding
+     * sentence, the register to keep. It is not a description of where the text sits: resource identity,
+     * URLs, message keys and source languages are excluded by contract, and a Provider given those would
+     * be given noise to translate around.
+     *
+     * Core's own storage flags travel in the same field internally and are stripped before this one is
+     * built, so a Provider never sees `[html]` and has no reason to know such a thing exists. Absent
+     * where there is nothing to say, which is every conversation message.
+     */
+    context?: string;
+    /**
+     * Told that nobody is waiting for this any more.
+     *
+     * A translation is one request in flight to somewhere else. A Provider that ignores this still
+     * finishes and still costs what it costs; honouring it is how it stops paying for an answer nobody
+     * will read.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * Both stores ask the same way.
+ *
+ * A global message is authored in English and a Site message in that Site's own immutable source
+ * locale, and the difference lands in `sourceLang` and nowhere else. A Provider is not told which store
+ * a text came from, because knowing would let it answer differently for one -- and the two are the same
+ * question asked about different text.
+ */
+export type PhisTranslationResult = {
+    /** As many entries as the request had, in its order. */
+    texts: readonly string[];
+};
+/**
+ * What this Provider was found to be able to do, asked once when it is configured.
+ *
+ * Not per translation, for the reason the Storage probe is not per upload: an installation has to be
+ * able to offer a choice of target language before anybody presses anything, and a list fetched at the
+ * moment of use is a list that decides whether a control can be drawn after it has been drawn.
+ *
+ * A Provider that cannot be reached answers `usable: false` with a finding rather than throwing. Not
+ * being reachable is an answer, and an operator configuring one needs to be told which of the two it
+ * is.
+ */
+export type PhisTranslationProbe = {
+    usable: boolean;
+    /**
+     * The languages it accepts as a source, as locale keys.
+     *
+     * Empty means it accepts any, or decides for itself -- a Provider that only ever detects has nothing
+     * to list. It does not mean it accepts none; a Provider that accepts none is not usable.
+     */
+    sourceLangs: string[];
+    /** The languages it can produce. An installation offers the intersection with what a Site has. */
+    targetLangs: string[];
+    /** What did not answer, in an operator's terms. Empty when everything did. */
+    findings: string[];
+};
+export interface PhisTranslationAdapter {
+    probeCapabilities(): Promise<PhisTranslationProbe>;
+    translate(input: PhisTranslationRequest): Promise<PhisTranslationResult>;
+}
+/**
+ * What a Provider is given, and the whole of it.
+ *
+ * A Provider needs its credential and must not be able to reach anything else, so the context carries
+ * no database handle and no general secret accessor: `readSecret` resolves the one reference this
+ * Provider's own configuration names, and there is no argument that could make it resolve another.
+ *
+ * There is no Site here. Which translator an installation uses is an installation's decision and not a
+ * Site's, unlike a Storage Profile, so a Provider is never handed a Site to branch on and can never
+ * come to treat one differently from another.
+ */
+export type PhisTranslationServiceContext = {
+    providerId: PhisTranslationProviderId;
+    /** The Provider's own secret, or null when its configuration names none. */
+    readSecret: () => Promise<string | null>;
+};

package/dist/translation.js

@@ -0,0 +1,15 @@
+/**
+ * The Translation service kind, as a Provider implements it.
+ *
+ * Core owns the question -- which text, out of which language, into which one -- and keeps asking it
+ * from the places that already translate: the global and Site message stores, and a conversation
+ * message somebody asked to read in their own language. A Provider answers it and nothing else.
+ * Nothing here reaches a database, a request, or a secret store: the Provider gets configuration and a
+ * context, and answers about text.
+ *
+ * What a Provider talks to is its own business, and deliberately not described here. A vendor over
+ * HTTP, a model on the machine, a catalogue it maintains itself and a CDN it consults first are all the
+ * same shape from Core's side, which is the reason this is a service kind rather than a list of
+ * vendors Core knows the names of.
+ */
+export {};