@deepwatch/dsh-contracts 0.1.0

package/lib/query.js

@@ -0,0 +1,431 @@
+/**
+ * The read plane: how a Watch mode asks the host what it should render.
+ *
+ * Watch contributes tools, and a tool result is how evidence reaches the
+ * *conversation*. It is not how a surface populates itself. A
+ * `conversation.view` entry is handed `{ inspect, onInspectDone }` and nothing
+ * else, so Live, Memory, Library and Compare had no way to obtain their own
+ * data and each defaulted to an empty array. Four of the seven modes rendered
+ * an honest empty state, which is a truthful surface and not a working one.
+ *
+ * The seam this uses is DSH's own. `packages/typert` defines Remote services
+ * dispatched through a Gateway that already owns request correlation, abort
+ * signals and structured failure, and `ctx.remote` is the client face of it.
+ * An earlier note in this distribution described `ctx.remote` as an event bus
+ * rather than a query client. That is true of `$on`/`$dispatch` and misses the
+ * typed invocation path beside them, and the conclusion drawn from it -- that
+ * populating these modes would mean building a second data path -- was the
+ * wrong one. Nothing here is a second path.
+ *
+ * Every operation is enumerated. There is no open `operation: string` with a
+ * free-form `params` object: a request is one member of a discriminated union
+ * or it is refused, so a surface cannot ask for something the host does not
+ * implement and the host cannot receive a shape it did not expect.
+ *
+ * Four properties this exists to guarantee.
+ *
+ * **Reads cannot express a write.** Every operation answers a question. A
+ * request that changes something is not in the union, so a surface cannot
+ * acquire a side effect by accident and captured or model-generated content
+ * reaching these fields cannot become an action.
+ *
+ * **Nothing here names a location.** Identifiers are drawn from a charset with
+ * no separator, no colon and no dot-dot, so a parameter cannot carry a
+ * filesystem path, a UNC share, an executable name or a storage URL. The host
+ * decides where it reads; the caller only says which record.
+ *
+ * **Every answer carries a revision, and a stale one is dropped.** Two reads
+ * issued in order can return out of order, and a surface that renders whichever
+ * arrived last shows older data than it had a moment ago -- intermittently, and
+ * under load, which is where that bug survives review.
+ *
+ * **Everything is bounded.** Request size, string length, array length, nesting
+ * depth, identifier length and cursor length all have limits, because the cost
+ * of a malformed request must not be a function of how malformed it is.
+ *
+ * Cancellation is deliberately absent from this module. Typert dispatches with
+ * an `AbortSignal`, and a second cancellation protocol carried in the payload
+ * would be a way for the two to disagree about whether a call is still live.
+ *
+ * Browser-safe like the rest of this package: no Node imports, no runtime
+ * identity, nothing a client bundle would have to deduplicate.
+ *
+ * @module @deepwatch/dsh-contracts/query
+ */
+import { watchError } from './index.js';
+/** The read-plane contract version this build speaks. */
+export const WATCH_QUERY_PROTOCOL_VERSION = 1;
+/** The oldest read-plane contract this build still answers. */
+export const WATCH_QUERY_PROTOCOL_MIN = 1;
+/**
+ * Every bound the read plane enforces.
+ *
+ * Stated in one place so a reviewer can see the whole budget at once, and so a
+ * test can assert against the same numbers the parser uses.
+ */
+export const QUERY_LIMITS = {
+    /** A whole request, serialised. Generous for a query, useless as a channel. */
+    requestBytes: 8192,
+    /** Any single string the caller supplies. */
+    stringLength: 2048,
+    /** A free-text search term. Shorter than a general string on purpose. */
+    queryLength: 512,
+    /** Any array the caller supplies. */
+    arrayLength: 64,
+    /** How deep a params object may nest before it is refused. */
+    depth: 6,
+    /** An identifier: record ids, session ids, scope names. */
+    identifierLength: 128,
+    /** A request id. */
+    requestIdLength: 64,
+    /** A cursor, which the host issued and the caller returns unchanged. */
+    cursorLength: 512,
+    /** The most records one page may carry, whatever the caller asked for. */
+    limit: 200,
+    /** The longest a surface may wait before it must show something. */
+    deadlineMs: 30_000,
+};
+/** The namespaces a mode may read from. Reads only; there is no write here. */
+export const QUERY_NAMESPACES = ['library', 'memory', 'compare', 'live'];
+/**
+ * Every operation the host implements, by namespace.
+ *
+ * The parser rejects anything absent from this table, so adding an operation
+ * is one edit and forgetting to implement one is a refusal rather than an
+ * undefined call.
+ */
+export const QUERY_OPERATIONS = {
+    library: ['search', 'get'],
+    memory: ['list', 'get'],
+    compare: ['pair'],
+    live: ['state'],
+};
+/** Encode a cursor. Opaque to the caller, checkable by the host. */
+export function encodeCursor(cursor) {
+    return [
+        'v1', cursor.namespace, cursor.operation, cursor.scope,
+        String(cursor.revision), String(cursor.offset),
+    ].join(':');
+}
+/**
+ * Decode a cursor and confirm it belongs here.
+ *
+ * Returns null for anything that does not decode or does not match the scope
+ * it is being replayed into. The caller turns that into `cursor_expired`,
+ * which is the honest description: the host cannot serve it, and saying why in
+ * more detail would describe another session's state.
+ */
+export function decodeCursor(value, expected) {
+    if (value.length > QUERY_LIMITS.cursorLength)
+        return null;
+    const parts = value.split(':');
+    if (parts.length !== 6 || parts[0] !== 'v1')
+        return null;
+    const [, namespace, operation, scope, revision, offset] = parts;
+    if (namespace !== expected.namespace)
+        return null;
+    if (operation !== expected.operation)
+        return null;
+    if (scope !== expected.scope)
+        return null;
+    if (!isSafeCount(Number(revision)) || Number(revision) !== expected.revision)
+        return null;
+    if (!isSafeCount(Number(offset)))
+        return null;
+    return {
+        namespace: expected.namespace,
+        operation,
+        scope,
+        revision: Number(revision),
+        offset: Number(offset),
+    };
+}
+// ── primitives ──────────────────────────────────────────────────────────────
+/** A non-negative safe integer. Protocol numbers and revisions must be one. */
+export function isSafeCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+/**
+ * An identifier this contract will carry.
+ *
+ * No slash, no backslash, no colon, no leading dot: an id cannot become a
+ * relative path, an absolute path, a UNC share, a drive letter or a URL. This
+ * is the single reason a caller cannot name a location.
+ */
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Whether a value is an identifier of an acceptable shape and length. */
+export function isIdentifier(value) {
+    return typeof value === 'string'
+        && value.length > 0
+        && value.length <= QUERY_LIMITS.identifierLength
+        && !value.includes('..')
+        && IDENTIFIER.test(value);
+}
+/** Whether a value is a namespace this host serves. */
+export function isQueryNamespace(value) {
+    return typeof value === 'string' && QUERY_NAMESPACES.includes(value);
+}
+/** Whether an operation exists in a namespace. */
+export function isQueryOperation(namespace, operation) {
+    return typeof operation === 'string'
+        && QUERY_OPERATIONS[namespace].includes(operation);
+}
+/** Negotiate the read-plane contract, or null when there is no overlap. */
+export function negotiateQueryProtocol(peerMin, peerMax) {
+    if (!isSafeCount(peerMin) || !isSafeCount(peerMax))
+        return null;
+    const agreed = Math.min(peerMax, WATCH_QUERY_PROTOCOL_VERSION);
+    return agreed >= Math.max(peerMin, WATCH_QUERY_PROTOCOL_MIN) ? agreed : null;
+}
+/**
+ * Whether an arriving snapshot is newer than what a surface already shows.
+ *
+ * The equal case is deliberately false. Re-rendering an identical revision
+ * costs a frame and gains nothing, and treating equal as newer would let two
+ * in-flight answers to the same revision fight.
+ */
+export function isNewerRevision(arriving, showing) {
+    if (!isSafeCount(arriving))
+        return false;
+    if (showing === null)
+        return true;
+    return arriving > showing;
+}
+/** Bring a caller deadline inside what the host will honour. */
+export function clampDeadline(requested) {
+    if (!isSafeCount(requested) || requested === 0)
+        return QUERY_LIMITS.deadlineMs;
+    return Math.min(requested, QUERY_LIMITS.deadlineMs);
+}
+/** Bring a caller page size inside what the host will return. */
+export function clampLimit(requested) {
+    if (!isSafeCount(requested) || requested === 0)
+        return QUERY_LIMITS.limit;
+    return Math.min(requested, QUERY_LIMITS.limit);
+}
+/** How deeply a value nests, stopping as soon as the budget is blown. */
+function depthOf(value, budget) {
+    if (budget < 0)
+        return Number.POSITIVE_INFINITY;
+    if (Array.isArray(value)) {
+        let deepest = 1;
+        for (const entry of value)
+            deepest = Math.max(deepest, 1 + depthOf(entry, budget - 1));
+        return deepest;
+    }
+    if (typeof value === 'object' && value !== null) {
+        let deepest = 1;
+        for (const entry of Object.values(value))
+            deepest = Math.max(deepest, 1 + depthOf(entry, budget - 1));
+        return deepest;
+    }
+    return 0;
+}
+/** Build the refusal a host returns when a read could not be produced. */
+export function queryRefusal(code, message, fix, options = {}) {
+    const retryableByDefault = code === 'deadline_exceeded' || code === 'unavailable';
+    return watchError(`watch.query.${code}`, message, fix, {
+        retryable: options.retryable ?? retryableByDefault,
+        correlationId: options.requestId ?? null,
+    });
+}
+// ── request parsing ─────────────────────────────────────────────────────────
+const refuse = (code, message, fix) => queryRefusal(code, message, fix);
+/** Parse the parameters of one operation, or refuse them. */
+function parseParams(namespace, operation, raw) {
+    const strings = (value, max) => typeof value === 'string' && value.length <= max;
+    if (namespace === 'library' && operation === 'search') {
+        if (!strings(raw.query, QUERY_LIMITS.queryLength)) {
+            return refuse('malformed_request', `library/search needs a query string of at most ${String(QUERY_LIMITS.queryLength)} characters.`, 'Shorten the search term.');
+        }
+        const modalities = raw.modalities ?? [];
+        if (!Array.isArray(modalities) || modalities.length > QUERY_LIMITS.arrayLength) {
+            return refuse('malformed_request', 'library/search modalities must be an array within bounds.', `Send at most ${String(QUERY_LIMITS.arrayLength)} modalities.`);
+        }
+        if (!modalities.every(entry => isIdentifier(entry))) {
+            return refuse('malformed_request', 'every modality must be a plain identifier.', 'Modalities carry no path separators.');
+        }
+        return { ok: true, value: {
+                query: raw.query, limit: clampLimit(raw.limit), modalities,
+            } };
+    }
+    if (namespace === 'library' && operation === 'get') {
+        if (!isIdentifier(raw.recordId)) {
+            return refuse('malformed_request', 'library/get needs a recordId identifier.', 'A record id carries no path separator, colon or dot-dot.');
+        }
+        return { ok: true, value: { recordId: raw.recordId } };
+    }
+    if (namespace === 'memory' && operation === 'list') {
+        if (!isIdentifier(raw.scope)) {
+            return refuse('malformed_request', 'memory/list needs a scope identifier.', 'A scope names a store the host knows, not a location.');
+        }
+        return { ok: true, value: {
+                scope: raw.scope, limit: clampLimit(raw.limit),
+            } };
+    }
+    if (namespace === 'memory' && operation === 'get') {
+        if (!isIdentifier(raw.cardId)) {
+            return refuse('malformed_request', 'memory/get needs a cardId identifier.', 'Send a card id.');
+        }
+        return { ok: true, value: { cardId: raw.cardId } };
+    }
+    if (namespace === 'compare' && operation === 'pair') {
+        if (!isIdentifier(raw.leftId) || !isIdentifier(raw.rightId)) {
+            return refuse('malformed_request', 'compare/pair needs two record identifiers.', 'Send leftId and rightId.');
+        }
+        return { ok: true, value: {
+                leftId: raw.leftId, rightId: raw.rightId,
+            } };
+    }
+    if (namespace === 'live' && operation === 'state') {
+        if (Object.keys(raw).length > 0) {
+            return refuse('malformed_request', 'live/state takes no parameters.', 'Send an empty params object.');
+        }
+        const empty = {};
+        return { ok: true, value: empty };
+    }
+    return refuse('unknown_operation', `${namespace}/${operation} is not implemented.`, `Use one of: ${QUERY_OPERATIONS[namespace].join(', ')}.`);
+}
+/**
+ * Validate a request at the boundary.
+ *
+ * Everything crossing into the host is parsed here, including requests this
+ * distribution's own client produced: a surface is reachable by anything that
+ * can reach the page, and "our own code sent it" is an assumption rather than
+ * a guarantee. Returns the normalised request, or the refusal to send back.
+ */
+export function parseQueryRequest(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return refuse('malformed_request', 'A query request must be an object.', 'Send a QueryRequest.');
+    }
+    // Size first: everything after this walks the structure, and the cost of
+    // rejecting a request must not scale with how large the caller made it.
+    let serialised;
+    try {
+        serialised = JSON.stringify(value);
+    }
+    catch {
+        return refuse('malformed_request', 'A query request must be serialisable.', 'Remove cycles and non-JSON values.');
+    }
+    if (serialised.length > QUERY_LIMITS.requestBytes) {
+        return refuse('request_too_large', `A query request may be at most ${String(QUERY_LIMITS.requestBytes)} bytes.`, 'Narrow the query, or page with the cursor the host returned.');
+    }
+    const raw = value;
+    if (!isSafeCount(raw.protocol) || negotiateQueryProtocol(raw.protocol, raw.protocol) === null) {
+        return refuse('protocol_mismatch', `The request declares read-plane protocol ${String(raw.protocol)}; this host speaks `
+            + `${String(WATCH_QUERY_PROTOCOL_MIN)}-${String(WATCH_QUERY_PROTOCOL_VERSION)}.`, 'Upgrade the half that is behind; the handshake reports both versions.');
+    }
+    if (typeof raw.requestId !== 'string' || !isIdentifier(raw.requestId)
+        || raw.requestId.length > QUERY_LIMITS.requestIdLength) {
+        return refuse('malformed_request', `A requestId must be an identifier of at most ${String(QUERY_LIMITS.requestIdLength)} characters.`, 'Generate one per request; it appears in logs and correlates the answer.');
+    }
+    if (!isQueryNamespace(raw.namespace)) {
+        return refuse('unknown_namespace', `${String(raw.namespace)} is not a readable namespace.`, `Use one of: ${QUERY_NAMESPACES.join(', ')}.`);
+    }
+    if (!isQueryOperation(raw.namespace, raw.operation)) {
+        return refuse('unknown_operation', `${raw.namespace}/${String(raw.operation)} is not implemented.`, `Use one of: ${QUERY_OPERATIONS[raw.namespace].join(', ')}.`);
+    }
+    if (raw.cursor !== null && raw.cursor !== undefined
+        && (typeof raw.cursor !== 'string' || raw.cursor.length > QUERY_LIMITS.cursorLength)) {
+        return refuse('malformed_request', `A cursor must be the string the host issued, at most ${String(QUERY_LIMITS.cursorLength)} characters.`, 'Pass nextCursor back unchanged, or null to start a new snapshot.');
+    }
+    if (typeof raw.params !== 'object' || raw.params === null || Array.isArray(raw.params)) {
+        return refuse('malformed_request', 'Query params must be an object.', 'Send params as an object.');
+    }
+    if (depthOf(raw.params, QUERY_LIMITS.depth) > QUERY_LIMITS.depth) {
+        return refuse('request_too_large', `Query params may nest at most ${String(QUERY_LIMITS.depth)} deep.`, 'Flatten the request; the read plane takes no nested structures.');
+    }
+    const params = parseParams(raw.namespace, raw.operation, raw.params);
+    if (!params.ok)
+        return params;
+    return {
+        ok: true,
+        value: {
+            protocol: raw.protocol,
+            requestId: raw.requestId,
+            namespace: raw.namespace,
+            operation: raw.operation,
+            deadlineMs: clampDeadline(raw.deadlineMs),
+            cursor: raw.cursor ?? null,
+            params: params.value,
+        },
+    };
+}
+// ── response parsing ────────────────────────────────────────────────────────
+/**
+ * Validate a snapshot before a surface renders it.
+ *
+ * The host is trusted to be the host and not trusted to be correct. A response
+ * that does not satisfy this contract is a defect somewhere, and rendering it
+ * anyway turns a defect into a wrong answer displayed confidently.
+ */
+export function parseQuerySnapshot(value, parseItem) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return refuse('malformed_response', 'A snapshot must be an object.', 'The host returned something else.');
+    }
+    const raw = value;
+    if (!isSafeCount(raw.protocol) || negotiateQueryProtocol(raw.protocol, raw.protocol) === null) {
+        return refuse('protocol_mismatch', `The host answered with read-plane protocol ${String(raw.protocol)}.`, 'Upgrade the half that is behind.');
+    }
+    if (typeof raw.requestId !== 'string') {
+        return refuse('malformed_response', 'A snapshot must name the request it answers.', 'Report this as a defect.');
+    }
+    if (!isSafeCount(raw.revision)) {
+        return refuse('malformed_response', 'A snapshot must carry a non-negative revision.', 'Without one, a stale answer cannot be told from a fresh one.');
+    }
+    if (!Array.isArray(raw.items)) {
+        return refuse('malformed_response', 'A snapshot must carry an items array.', 'Report this as a defect.');
+    }
+    if (raw.nextCursor !== null && typeof raw.nextCursor !== 'string') {
+        return refuse('malformed_response', 'nextCursor must be a string or null.', 'Report this as a defect.');
+    }
+    if (typeof raw.complete !== 'boolean') {
+        return refuse('malformed_response', 'A snapshot must say whether it is complete.', 'A partial answer presented as whole is worse than no answer.');
+    }
+    const items = [];
+    for (const entry of raw.items) {
+        const parsed = parseItem(entry);
+        if (parsed === null) {
+            return refuse('malformed_response', 'A record in the snapshot did not satisfy its contract.', 'Report this as a defect; the surface will not render a shape it cannot read.');
+        }
+        items.push(parsed);
+    }
+    return {
+        ok: true,
+        value: {
+            protocol: raw.protocol,
+            requestId: raw.requestId,
+            revision: raw.revision,
+            items,
+            nextCursor: raw.nextCursor ?? null,
+            complete: raw.complete,
+        },
+    };
+}
+/** Read a Library record off the wire, or null when it is not one. */
+export function parseLibraryRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    if (!isIdentifier(raw.recordId))
+        return null;
+    if (typeof raw.title !== 'string' || raw.title.length > QUERY_LIMITS.stringLength)
+        return null;
+    if (typeof raw.modality !== 'string')
+        return null;
+    if (raw.capturedAt !== null && typeof raw.capturedAt !== 'string')
+        return null;
+    if (typeof raw.provenance !== 'string')
+        return null;
+    if (!Array.isArray(raw.evidenceIds) || !raw.evidenceIds.every(id => isIdentifier(id)))
+        return null;
+    return {
+        recordId: raw.recordId,
+        title: raw.title,
+        modality: raw.modality,
+        capturedAt: raw.capturedAt ?? null,
+        provenance: raw.provenance,
+        evidenceIds: raw.evidenceIds,
+    };
+}
+//# sourceMappingURL=query.js.map

package/lib/readiness.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Whether a role can actually run, kept as four separate facts.
+ *
+ * This module exists because they were one. A provider row showed a green dot
+ * the moment a credential was saved, and a person reasonably read that as "the
+ * product is ready" — so they typed a prompt, and the runtime routed it to a
+ * provider they had never configured, failed on a missing environment
+ * variable, and left a failed turn in their session. Every step of that was a
+ * consequence of one indicator standing for four different questions:
+ *
+ *   1. is there a credential?          {@link ProviderCredentialStatus}
+ *   2. does the provider answer?       {@link ProviderReachability}
+ *   3. is a model chosen?              {@link ModelSelectionStatus}
+ *   4. is a role bound and runnable?   {@link RoleBindingStatus}
+ *
+ * A credential is the *first* of those and implies none of the others.
+ * {@link roleReadiness} is the only thing in this product allowed to answer
+ * "ready", and it requires all four to line up, plus a route that supports the
+ * role and a policy state that permits the request.
+ *
+ * **Nothing here ever carries secret material.** Not a value, not a prefix, a
+ * suffix, a length or a hash. A credential appears in these types only as a
+ * *reference* — an opaque handle the Host can resolve — and as a status word.
+ * `configured_unverified` is the honest state after a save: something is
+ * stored, and nobody has asked the provider whether it works.
+ *
+ * Verification is deliberately not automatic. Saving a credential must not
+ * quietly spend a request, and discovering models must be distinguishable from
+ * a billable completion — so both are user actions with their own results, and
+ * {@link ProviderReachability} stays `unknown` until one of them runs.
+ *
+ * @module @deepwatch/dsh-contracts/readiness
+ */
+/**
+ * What is known about a stored credential — never anything about its value.
+ *
+ * `configured_unverified` is the state a save produces and the one the UI has
+ * to be honest about: it means stored, not working. `inaccessible` is separate
+ * from `absent` because a credential store that cannot be opened is a fault to
+ * report, not an empty slot to fill.
+ */
+export type ProviderCredentialStatus = 
+/** No credential is stored for this provider. */
+'absent'
+/** Stored, and never checked against the provider. The state after a save. */
+ | 'configured_unverified'
+/** A real request to the provider accepted it. */
+ | 'verified'
+/** A real request to the provider rejected it. */
+ | 'rejected'
+/** A credential is recorded but the store could not be read. */
+ | 'inaccessible';
+/**
+ * Whether the provider itself answered, as distinct from whether it liked the
+ * credential.
+ *
+ * `unknown` is the default and stays the default: this product does not
+ * contact a provider because a settings page was opened.
+ */
+export type ProviderReachability = 
+/** Never contacted from this installation. */
+'unknown' | 'reachable'
+/** Contacted and no usable answer came back. */
+ | 'unreachable'
+/** Answered, and declined this request for rate reasons. */
+ | 'rate_limited'
+/** Answered, and rejected the credential. */
+ | 'unauthorized';
+/** Whether a model has been chosen, and whether the choice still holds. */
+export type ModelSelectionStatus = 
+/** Nothing chosen. A provider with a credential is still in this state. */
+'none' | 'selected'
+/** Chosen once, and the provider no longer lists it. */
+ | 'unavailable'
+/** Chosen, and not a well-formed model id for this provider. */
+ | 'invalid';
+/** Whether a role is wired to something that could run. */
+export type RoleBindingStatus = 
+/** No binding. Never a silent fallback to another role's model. */
+'unbound'
+/** A binding exists and has not been proved end to end. */
+ | 'bound_unverified'
+/** Every requirement below is satisfied. The only state that may say "ready". */
+ | 'executable'
+/** A binding exists and something forbids running it. */
+ | 'blocked';
+/**
+ * Why a role is not executable.
+ *
+ * One reason per missing requirement, so the UI can name the exact next step
+ * rather than saying "not configured" and leaving a person to guess which of
+ * six things is missing.
+ */
+export type ReadinessBlocker = 'no_binding' | 'provider_unknown' | 'credential_absent' | 'credential_rejected' | 'credential_inaccessible' | 'provider_untested' | 'provider_unreachable' | 'provider_rate_limited' | 'model_unset' | 'model_unavailable' | 'model_invalid' | 'route_lacks_role' | 'modality_unsupported' | 'consent_required' | 'policy_forbids' | 'contract_mismatch';
+/** A modality a role may need a route to support. */
+export type Modality = 'text' | 'vision' | 'audio' | 'embedding';
+/**
+ * What a route can do.
+ *
+ * Supplied by whatever knows the provider catalogue; this module only compares
+ * it against what a role asks for.
+ */
+export interface RouteCapability {
+    /** The provider route id, as the catalogue names it. */
+    readonly provider: string;
+    /** Roles this route can serve at all. */
+    readonly roles: readonly string[];
+    readonly modalities: readonly Modality[];
+    /** Model ids the provider listed, or null when nobody has asked it. */
+    readonly models: readonly string[] | null;
+}
+/**
+ * One role's binding, as stored.
+ *
+ * `credentialRef` is an opaque handle, never a value: the Host resolves it
+ * against its own credential store, and nothing that crosses into a browser or
+ * a log ever holds more than this string.
+ */
+export interface RoleBinding {
+    readonly role: string;
+    readonly provider: string;
+    readonly model: string;
+    /** Opaque handle to a credential the Host holds. Never a secret. */
+    readonly credentialRef: string | null;
+    /** Modalities the bound work will actually need. */
+    readonly modalities: readonly Modality[];
+}
+/** Everything {@link roleReadiness} is allowed to consider. */
+export interface ReadinessInputs {
+    readonly binding: RoleBinding | null;
+    readonly credential: ProviderCredentialStatus;
+    readonly reachability: ProviderReachability;
+    readonly model: ModelSelectionStatus;
+    readonly route: RouteCapability | null;
+    /** False when a required consent has not been granted for this work. */
+    readonly consentGranted: boolean;
+    /** False when policy forbids the request regardless of consent. */
+    readonly policyPermits: boolean;
+    /** False when the wire contract the route speaks is not one this build has. */
+    readonly contractMatches: boolean;
+}
+/** What the product knows about one role. */
+export interface RoleReadiness {
+    readonly role: string;
+    readonly status: RoleBindingStatus;
+    /** Empty exactly when the status is `executable`. */
+    readonly blockers: readonly ReadinessBlocker[];
+    /** The single next thing to fix, or null when there is nothing to fix. */
+    readonly primaryBlocker: ReadinessBlocker | null;
+}
+/**
+ * Whether a role can run, and if not, exactly what is missing.
+ *
+ * The single gate. A caller may not assemble "ready" from parts: every surface
+ * that shows readiness, and both halves of preflight, ask this function, so
+ * there is one definition of executable and it is testable on its own.
+ *
+ * @param inputs - every fact that bears on the decision.
+ * @param role - the role being asked about.
+ * @returns the status and the blockers, in the order they must be fixed.
+ */
+export declare function roleReadiness(role: string, inputs: ReadinessInputs): RoleReadiness;
+/**
+ * Whether a role may be described to a person as ready.
+ *
+ * A helper rather than a comparison at each call site, because "ready" is
+ * exactly the word this whole module exists to stop being used loosely.
+ */
+export declare function isExecutable(readiness: RoleReadiness): boolean;
+/**
+ * One sentence a person can act on, for the blocker that matters most.
+ *
+ * Deliberately free of route ids, package names and environment variables:
+ * those belong in Diagnostics, and a person reading their first error should
+ * be told what to do rather than what broke internally.
+ */
+export declare function blockerMessage(readiness: RoleReadiness): string | null;
+/**
+ * Whether a status word may be drawn with the affordance that reads as "good".
+ *
+ * Only a proved binding earns it. `bound_unverified` deliberately does not:
+ * that is the state a green dot used to claim, and claiming it is what sent a
+ * prompt to an unconfigured provider.
+ */
+export declare function isPositiveBindingStatus(status: RoleBindingStatus): boolean;
+/**
+ * The accessible label for a status, so colour is never the only signal.
+ *
+ * Every surface uses these words, so a screen reader and a sighted reader are
+ * told the same thing, and a red or green dot is decoration on top of text
+ * rather than the fact itself.
+ */
+export declare const BINDING_STATUS_LABEL: Readonly<Record<RoleBindingStatus, string>>;
+/** The accessible label for a credential status. */
+export declare const CREDENTIAL_STATUS_LABEL: Readonly<Record<ProviderCredentialStatus, string>>;
+/** The accessible label for provider reachability. */
+export declare const REACHABILITY_LABEL: Readonly<Record<ProviderReachability, string>>;
+//# sourceMappingURL=readiness.d.ts.map