@deepwatch/dsh-contracts 0.1.0

package/lib/execution.d.ts

@@ -0,0 +1,259 @@
+/**
+ * What one tool call did, recorded because it happened rather than because the
+ * model mentioned it.
+ *
+ * **Why this exists.** An owner evaluation ran 47 model rounds and 76 tool
+ * calls — 30 shell, 30 reads, 5 writes, 4 greps, 3 subagents — and Watch
+ * recorded none of them. Not because the recording failed: because nothing was
+ * listening. Watch's tools were tools the model could choose to call, so a
+ * model that never thought about Watch left a product whose entire subject is
+ * evidence with an empty ledger, a Library reporting `Index is behind the
+ * store`, and a Compare with nothing to compare. The agent wrote its own
+ * `verification.json`, reread it with a second generic tool, and reported PASS.
+ *
+ * The fix is not a better prompt. A capability that depends on the model
+ * remembering it exists is not a capability, it is a suggestion. These records
+ * are minted from the Harness's own tool-dispatch lifecycle, so a call is
+ * recorded whether or not anything in the conversation has ever heard of Watch.
+ *
+ * **What a record is not.** It is not a verdict. `state: 'completed'` means the
+ * dispatch returned; it says nothing about whether the thing the caller wanted
+ * is true. Every record starts `UNVERIFIED` and only a verification contract
+ * evaluated against evidence may move it — never a tool's own exit code, and
+ * never a file the model wrote claiming success. That separation is the reason
+ * {@link AgentExecutionState} and {@link Verdict} are two types in this package
+ * and not one.
+ *
+ * @module @deepwatch/dsh-contracts/execution
+ */
+import type { AgentExecutionState, Verdict } from './index.js';
+/**
+ * The contract version these records are written under.
+ *
+ * Read by the Bridge and by the Library indexer: a record from a newer writer
+ * is refused rather than half-understood. Bumped when a field's meaning
+ * changes, not when one is added with a safe absence.
+ */
+export declare const EXECUTION_RECORD_VERSION = 1;
+/**
+ * What a call did to the world, as far as the Host can tell from the boundary.
+ *
+ * Classified from the tool's declared surface rather than guessed from its
+ * name, and `unknown` is a real answer: a tool this distribution has never
+ * seen is not assumed harmless. Verification treats `unknown` as unproved
+ * rather than as `none`, so a classification gap fails closed.
+ */
+export type SideEffectClass = 
+/** Observed state without changing it. */
+'read'
+/** Changed durable state. */
+ | 'write'
+/** Ran a process. */
+ | 'execute'
+/** Reached beyond this machine. */
+ | 'network'
+/** Changed nothing outside the conversation — a todo edit, a plan note. */
+ | 'none'
+/** Not classifiable from the boundary. Never treated as `none`. */
+ | 'unknown';
+/**
+ * Where a call's paths resolved, relative to the workspace a person chose.
+ *
+ * `outside_workspace` is recorded rather than hidden. The evaluation that
+ * prompted this work searched other drives, read unrelated locations and wrote
+ * under the system temporary directory, and none of it appeared anywhere a
+ * person could see. An attempt that was refused is still something the owner
+ * is entitled to know happened.
+ */
+export type WorkspaceScope = 
+/** Every affected path resolved inside the selected workspace. */
+'inside'
+/** At least one path resolved outside it. Recorded whether or not it ran. */
+ | 'outside_workspace'
+/** No workspace is selected, so containment could not be decided. */
+ | 'no_workspace'
+/** The call names no path. */
+ | 'not_applicable';
+/** What the containment gate did about it. */
+export type ScopeDecision = 'allowed' | 'denied' | 'approved' | 'not_evaluated';
+/**
+ * The identity that makes a retry a retry rather than a second action.
+ *
+ * Four parts, all of them stable across an attempt: the session, the turn, the
+ * call the model asked for, and which attempt this is. Two records sharing the
+ * first three are attempts at one action; a ledger that keyed on the call alone
+ * would show a retried write as two writes, which is the difference between
+ * "this happened twice" and "this was tried twice and happened once".
+ */
+export interface ExecutionIdentity {
+    readonly sessionId: string;
+    /** The agent turn this call belongs to, as the loop numbers it. */
+    readonly turnId: string;
+    /** The model-requested call id. Nested dispatches carry their own. */
+    readonly callId: string;
+    /** 1 for the first attempt. */
+    readonly attempt: number;
+}
+/**
+ * One tool call, from the boundary that dispatched it.
+ *
+ * Every field here is either observed at the lifecycle or derived from it. None
+ * of it is reported by the tool about itself, and none of it is asserted by the
+ * model.
+ */
+export interface ToolExecutionRecord extends ExecutionIdentity {
+    readonly version: number;
+    /**
+     * `<sessionId>/<turnId>/<callId>#<attempt>`, the one spelling.
+     *
+     * Written by {@link executionKey} so two producers cannot disagree about
+     * whether a retry is a duplicate.
+     */
+    readonly idempotencyKey: string;
+    /** The root model-requested call, when this is a nested dispatch. */
+    readonly rootCallId: string | null;
+    /**
+     * The subagent whose turn this call belongs to, and the parent turn that
+     * spawned it. Both null for a call the top-level agent made directly.
+     */
+    readonly subagentId: string | null;
+    readonly parentTurnId: string | null;
+    readonly toolName: string;
+    readonly state: AgentExecutionState;
+    readonly startedAt: string;
+    readonly endedAt: string | null;
+    readonly durationMs: number | null;
+    /**
+     * How the dispatch ended, in the boundary's own words: `ok`, the tool's
+     * failure code, `denied`, or `cancelled`. Not a verdict.
+     */
+    readonly exitStatus: string | null;
+    readonly sideEffect: SideEffectClass;
+    readonly scope: WorkspaceScope;
+    readonly scopeDecision: ScopeDecision;
+    /**
+     * Paths the call affected, workspace-relative.
+     *
+     * Relative because an absolute path carries the operating system user's name
+     * and the shape of somebody's disk, and neither belongs in a record that is
+     * exported, indexed and shown. A path outside the workspace is not recorded
+     * as a path at all — {@link WorkspaceScope} says it happened and
+     * `outsidePathCount` says how many, which is the fact without the disclosure.
+     */
+    readonly paths: readonly string[];
+    readonly outsidePathCount: number;
+    /** The arguments, redacted and bounded. Never the raw argument object. */
+    readonly inputSummary: string;
+    /** The result, redacted and bounded. Never the full output. */
+    readonly outputSummary: string;
+    /** `sha256:…` over the full untruncated output, so the summary is checkable. */
+    readonly outputDigest: string;
+    /**
+     * The provenance turn that authorised the provider request this call belongs
+     * to, correlating a tool action back to the person who asked for it. Null
+     * when the call ran outside any authorised turn, which is itself worth
+     * seeing.
+     */
+    readonly authorisedBy: string | null;
+    /**
+     * Always `UNVERIFIED` at mint.
+     *
+     * A tool that returned is a tool that returned. Only
+     * {@link VerificationOutcome} moves this, and only from evidence.
+     */
+    readonly verification: Verdict;
+}
+/** The one spelling of an execution's identity. */
+export declare function executionKey(identity: ExecutionIdentity): string;
+/**
+ * Whether two records describe attempts at the same action.
+ *
+ * The question a ledger asks before it shows a person "this ran twice".
+ */
+export declare function isSameAction(a: ExecutionIdentity, b: ExecutionIdentity): boolean;
+/**
+ * How long the bounded summaries may be.
+ *
+ * Bounded because the evaluation that prompted this recorded 2.9M tokens of
+ * context, and a ledger that stored every shell transcript would be a second
+ * copy of it. Long enough to identify what happened, short enough that a
+ * thousand records stay readable and indexable.
+ */
+/**
+ * The states a record can no longer leave.
+ *
+ * A dispatch that finished, failed or was refused has an answer. Anything
+ * arriving afterwards is a second observation of the same event -- a retried
+ * emit, a late listener, an out-of-order post-execute -- and not a new outcome.
+ */
+export declare const TERMINAL_STATES: readonly AgentExecutionState[];
+/** Whether a state is the end of an execution's story. */
+export declare function isTerminalState(state: AgentExecutionState): boolean;
+/**
+ * How far through its life an execution is, so progress can be compared.
+ *
+ * Ranked rather than ordered by name because the only question ever asked of
+ * it is "is this observation older than the one already recorded", and a
+ * comparison that answers that in one place cannot answer it differently in
+ * another.
+ */
+export declare function stateRank(state: AgentExecutionState): number;
+/**
+ * How firmly a scope decision is held.
+ *
+ * `denied` outranks everything, and that is the whole point. A call the
+ * boundary refused is refused; a later observation that did not know about the
+ * refusal must not be able to describe it as permitted. This is the single
+ * asymmetry in the record, and it is deliberate: softening a denial is the one
+ * error that turns a boundary into a label.
+ */
+export declare function scopeDecisionRank(decision: ScopeDecision): number;
+/**
+ * Merge two observations of one execution into the single canonical record.
+ *
+ * Both producers of a record -- the containment screen and the settling of a
+ * result -- write through here, so neither can overwrite the other by arriving
+ * second. The rules are few and each exists because breaking it produced a
+ * record that lied:
+ *
+ *   - A denial is permanent. A refused call still travels back through the
+ *     dispatch layer as an error, and settling that error as an ordinary
+ *     outcome once rewrote `denied` into `allowed`.
+ *   - A terminal state is final. Two terminal observations of one execution
+ *     are the same ending seen twice, not two endings.
+ *   - Progress only moves forward. A late `running` cannot un-finish a call.
+ *
+ * Returns `existing` unchanged -- by identity, so a caller can test whether
+ * anything moved -- when the incoming observation adds nothing.
+ */
+export declare function reconcileExecutionRecords(existing: ToolExecutionRecord, incoming: ToolExecutionRecord): ToolExecutionRecord;
+export declare const SUMMARY_LIMIT = 512;
+/**
+ * Cut a summary to {@link SUMMARY_LIMIT}, saying so when it was cut.
+ *
+ * The marker matters: a reader who cannot tell a short output from a truncated
+ * one will eventually read a truncation as the whole answer.
+ */
+export declare function boundSummary(text: string, limit?: number): string;
+/** What a redacted secret is replaced by, so the fact survives the value. */
+export declare const SECRET_PLACEHOLDER = "<redacted>";
+/**
+ * Remove secret-shaped material from text bound for a record.
+ *
+ * Deliberately conservative about what it calls a secret and deliberately
+ * blunt about what it does with one: the replacement keeps the shape of the
+ * line so a reader can still see that a token was passed, without the token.
+ *
+ * This is not the only defence and must not be treated as one. The Host does
+ * not put environment dumps or credential values into summaries in the first
+ * place; this is what catches the ones that arrive inside something else.
+ */
+export declare function redactSecrets(text: string): string;
+/**
+ * Whether a string still looks like it carries a credential.
+ *
+ * Used by the export gate and by tests, which need to assert absence rather
+ * than trust the redactor that produced the text.
+ */
+export declare function looksLikeSecret(text: string): boolean;
+//# sourceMappingURL=execution.d.ts.map

package/lib/execution.js

@@ -0,0 +1,213 @@
+/**
+ * What one tool call did, recorded because it happened rather than because the
+ * model mentioned it.
+ *
+ * **Why this exists.** An owner evaluation ran 47 model rounds and 76 tool
+ * calls — 30 shell, 30 reads, 5 writes, 4 greps, 3 subagents — and Watch
+ * recorded none of them. Not because the recording failed: because nothing was
+ * listening. Watch's tools were tools the model could choose to call, so a
+ * model that never thought about Watch left a product whose entire subject is
+ * evidence with an empty ledger, a Library reporting `Index is behind the
+ * store`, and a Compare with nothing to compare. The agent wrote its own
+ * `verification.json`, reread it with a second generic tool, and reported PASS.
+ *
+ * The fix is not a better prompt. A capability that depends on the model
+ * remembering it exists is not a capability, it is a suggestion. These records
+ * are minted from the Harness's own tool-dispatch lifecycle, so a call is
+ * recorded whether or not anything in the conversation has ever heard of Watch.
+ *
+ * **What a record is not.** It is not a verdict. `state: 'completed'` means the
+ * dispatch returned; it says nothing about whether the thing the caller wanted
+ * is true. Every record starts `UNVERIFIED` and only a verification contract
+ * evaluated against evidence may move it — never a tool's own exit code, and
+ * never a file the model wrote claiming success. That separation is the reason
+ * {@link AgentExecutionState} and {@link Verdict} are two types in this package
+ * and not one.
+ *
+ * @module @deepwatch/dsh-contracts/execution
+ */
+/**
+ * The contract version these records are written under.
+ *
+ * Read by the Bridge and by the Library indexer: a record from a newer writer
+ * is refused rather than half-understood. Bumped when a field's meaning
+ * changes, not when one is added with a safe absence.
+ */
+export const EXECUTION_RECORD_VERSION = 1;
+/** The one spelling of an execution's identity. */
+export function executionKey(identity) {
+    return `${identity.sessionId}/${identity.turnId}/${identity.callId}#${String(identity.attempt)}`;
+}
+/**
+ * Whether two records describe attempts at the same action.
+ *
+ * The question a ledger asks before it shows a person "this ran twice".
+ */
+export function isSameAction(a, b) {
+    return a.sessionId === b.sessionId && a.turnId === b.turnId && a.callId === b.callId;
+}
+/**
+ * How long the bounded summaries may be.
+ *
+ * Bounded because the evaluation that prompted this recorded 2.9M tokens of
+ * context, and a ledger that stored every shell transcript would be a second
+ * copy of it. Long enough to identify what happened, short enough that a
+ * thousand records stay readable and indexable.
+ */
+/**
+ * The states a record can no longer leave.
+ *
+ * A dispatch that finished, failed or was refused has an answer. Anything
+ * arriving afterwards is a second observation of the same event -- a retried
+ * emit, a late listener, an out-of-order post-execute -- and not a new outcome.
+ */
+export const TERMINAL_STATES = ['completed', 'failed', 'cancelled'];
+/** Whether a state is the end of an execution's story. */
+export function isTerminalState(state) {
+    return TERMINAL_STATES.includes(state);
+}
+/**
+ * How far through its life an execution is, so progress can be compared.
+ *
+ * Ranked rather than ordered by name because the only question ever asked of
+ * it is "is this observation older than the one already recorded", and a
+ * comparison that answers that in one place cannot answer it differently in
+ * another.
+ */
+export function stateRank(state) {
+    if (state === 'queued')
+        return 0;
+    if (state === 'running')
+        return 1;
+    return 2;
+}
+/**
+ * How firmly a scope decision is held.
+ *
+ * `denied` outranks everything, and that is the whole point. A call the
+ * boundary refused is refused; a later observation that did not know about the
+ * refusal must not be able to describe it as permitted. This is the single
+ * asymmetry in the record, and it is deliberate: softening a denial is the one
+ * error that turns a boundary into a label.
+ */
+export function scopeDecisionRank(decision) {
+    if (decision === 'denied')
+        return 3;
+    if (decision === 'approved')
+        return 2;
+    if (decision === 'allowed')
+        return 1;
+    return 0;
+}
+/**
+ * Merge two observations of one execution into the single canonical record.
+ *
+ * Both producers of a record -- the containment screen and the settling of a
+ * result -- write through here, so neither can overwrite the other by arriving
+ * second. The rules are few and each exists because breaking it produced a
+ * record that lied:
+ *
+ *   - A denial is permanent. A refused call still travels back through the
+ *     dispatch layer as an error, and settling that error as an ordinary
+ *     outcome once rewrote `denied` into `allowed`.
+ *   - A terminal state is final. Two terminal observations of one execution
+ *     are the same ending seen twice, not two endings.
+ *   - Progress only moves forward. A late `running` cannot un-finish a call.
+ *
+ * Returns `existing` unchanged -- by identity, so a caller can test whether
+ * anything moved -- when the incoming observation adds nothing.
+ */
+export function reconcileExecutionRecords(existing, incoming) {
+    // Two records that are not the same execution must never be merged; the
+    // caller keyed them wrongly and silently blending them would hide that.
+    if (existing.idempotencyKey !== incoming.idempotencyKey)
+        return existing;
+    const scopeDecision = scopeDecisionRank(existing.scopeDecision)
+        >= scopeDecisionRank(incoming.scopeDecision)
+        ? existing.scopeDecision
+        : incoming.scopeDecision;
+    const settled = isTerminalState(existing.state)
+        || stateRank(incoming.state) <= stateRank(existing.state);
+    if (settled) {
+        return scopeDecision === existing.scopeDecision ? existing : { ...existing, scopeDecision };
+    }
+    // The incoming observation is genuinely further along. It carries the newer
+    // outcome, but identity and origin belong to the record that opened.
+    return {
+        ...incoming,
+        sessionId: existing.sessionId,
+        turnId: existing.turnId,
+        callId: existing.callId,
+        attempt: existing.attempt,
+        idempotencyKey: existing.idempotencyKey,
+        startedAt: existing.startedAt,
+        scopeDecision,
+    };
+}
+export const SUMMARY_LIMIT = 512;
+/**
+ * Cut a summary to {@link SUMMARY_LIMIT}, saying so when it was cut.
+ *
+ * The marker matters: a reader who cannot tell a short output from a truncated
+ * one will eventually read a truncation as the whole answer.
+ */
+export function boundSummary(text, limit = SUMMARY_LIMIT) {
+    const collapsed = text.replace(/\s+/gu, ' ').trim();
+    if (collapsed.length <= limit)
+        return collapsed;
+    return `${collapsed.slice(0, limit)}… (${String(collapsed.length)} chars)`;
+}
+/**
+ * Patterns whose *value* must never reach a record.
+ *
+ * Keys, bearer tokens and the assignment forms they arrive in. This is a
+ * belt-and-braces pass over text that has already been shaped by the caller: the
+ * summaries are built from arguments and results the Host chose to include, and
+ * this catches the case where a secret is inside one of them — a shell command
+ * line with an inline token, an error quoting an Authorization header.
+ */
+const SECRET_PATTERNS = [
+    // Provider key shapes: sk-…, sk-ant-…, ghp_…, and friends.
+    /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{12,}/gu,
+    /\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]{12,}/gu,
+    /\bxox[abposr]-[A-Za-z0-9-]{10,}/gu,
+    // Bearer and Basic credentials wherever they appear.
+    /\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gu,
+    // `KEY=value`, `--token value`, `"apiKey": "value"` and their neighbours.
+    /\b[A-Za-z_][A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL)\s*[=:]\s*\S+/giu,
+    /--(?:api-?key|token|password|secret)(?:[=\s]+)\S+/giu,
+];
+/** What a redacted secret is replaced by, so the fact survives the value. */
+export const SECRET_PLACEHOLDER = '<redacted>';
+/**
+ * Remove secret-shaped material from text bound for a record.
+ *
+ * Deliberately conservative about what it calls a secret and deliberately
+ * blunt about what it does with one: the replacement keeps the shape of the
+ * line so a reader can still see that a token was passed, without the token.
+ *
+ * This is not the only defence and must not be treated as one. The Host does
+ * not put environment dumps or credential values into summaries in the first
+ * place; this is what catches the ones that arrive inside something else.
+ */
+export function redactSecrets(text) {
+    let out = text;
+    for (const pattern of SECRET_PATTERNS)
+        out = out.replace(pattern, SECRET_PLACEHOLDER);
+    return out;
+}
+/**
+ * Whether a string still looks like it carries a credential.
+ *
+ * Used by the export gate and by tests, which need to assert absence rather
+ * than trust the redactor that produced the text.
+ */
+export function looksLikeSecret(text) {
+    return SECRET_PATTERNS.some((pattern) => {
+        // `RegExp` with `g` carries `lastIndex` between calls; a fresh one per test
+        // keeps this a pure predicate.
+        const probe = new RegExp(pattern.source, pattern.flags.replace('g', ''));
+        return probe.test(text);
+    });
+}
+//# sourceMappingURL=execution.js.map

package/lib/failures.d.ts

@@ -0,0 +1,145 @@
+/**
+ * What a person is told when a conversation cannot run, and what they are not.
+ *
+ * A prompt failed and the Chat surface showed the reader
+ * `@deepseek-ai/dsh-system-prompt`, the route id `llm-deepseek`, the provider
+ * key `deepseek-official`, the environment variable `DEEPSEEK_API_KEY`, and a
+ * paragraph of sandbox-policy text. Every one of those is true, and not one of
+ * them told the reader what to do. Worse, two of them named a provider they had
+ * never chosen, so the message actively misled: it read as *DeepWatch is a
+ * DeepSeek product that is broken* rather than *nothing is bound yet*.
+ *
+ * This module draws the line. A raw provider or runtime failure is classified
+ * into one of a small closed set of {@link FailureKind}s, each of which becomes
+ * a card with a title, one sentence, and exactly one next action. The detailed
+ * technical facts are not destroyed — they go to Diagnostics and the Session
+ * Log, redacted — but they never render in an ordinary conversation.
+ *
+ * **Two rules hold everything here together.**
+ *
+ * The first is that a card carries no implementation identity.
+ * {@link assertNoInternalDisclosure} is the executable form of that rule, and
+ * it is applied to every card this module produces rather than trusted to
+ * review.
+ *
+ * The second is that nothing here ever carries credential material — and
+ * "material" includes the things people reach for when they are trying to be
+ * helpful about a key without printing it: a prefix, a suffix, a length, a
+ * fingerprint, a hash. A reader does not need to be told their key is 51
+ * characters long, and an attacker reading a shared screenshot does.
+ *
+ * @module @deepwatch/dsh-contracts/failures
+ */
+import type { ReadinessBlocker } from './readiness.js';
+/**
+ * The closed set of things a person can be told went wrong.
+ *
+ * Closed on purpose. Every raw failure maps onto one of these or onto
+ * {@link FailureKind.unavailable}, and there is no passthrough case that
+ * renders a provider's own words: a provider message is written for an API
+ * consumer, arrives unlocalised, and has no obligation to avoid naming
+ * internals.
+ */
+export type FailureKind = 
+/** No model is bound to this capability. The first-run case. */
+'not_configured'
+/** A complete binding exists, but no provider request has succeeded. */
+ | 'not_tested'
+/** A credential is referenced and the store could not produce it. */
+ | 'credential_unavailable'
+/** The provider answered and rejected the credential. */
+ | 'credential_rejected'
+/** The bound model is not one the provider offers any more. */
+ | 'model_unavailable'
+/** The provider did not answer usefully. */
+ | 'provider_unreachable'
+/** The provider answered and declined for rate reasons. */
+ | 'rate_limited'
+/** Policy on this machine forbids the request. */
+ | 'policy_forbids'
+/** Something else. Deliberately vague to the reader, detailed in Diagnostics. */
+ | 'unavailable';
+/** Where a card's action sends a person. */
+export type FailureActionTarget = 
+/** The Role Bindings screen, at the role that is blocked. */
+'role-bindings'
+/** The provider credential screen. */
+ | 'provider-credential'
+/** The model picker for the bound provider. */
+ | 'model-selection'
+/** Diagnostics, for the redacted technical detail. */
+ | 'diagnostics'
+/** Nothing to configure; the reader can only try again. */
+ | 'retry';
+/** One card, as a conversation renders it. */
+export interface FailureCard {
+    readonly kind: FailureKind;
+    /** A short heading, in a person's words. Never an error code. */
+    readonly title: string;
+    /** One sentence saying what is true. Never a stack trace, never a route id. */
+    readonly detail: string;
+    /** The label of the single action that fixes this. */
+    readonly action: string;
+    readonly target: FailureActionTarget;
+    /**
+     * Whether Diagnostics holds more about this.
+     *
+     * Every card offers the path; this says whether following it will find
+     * anything, so the product does not send somebody to an empty screen.
+     */
+    readonly hasDiagnostics: boolean;
+}
+/**
+ * The card for one kind.
+ *
+ * @param kind - the classified failure.
+ * @param hasDiagnostics - whether a redacted record was written for it.
+ * @returns a card safe to render in an ordinary conversation.
+ */
+export declare function failureCard(kind: FailureKind, hasDiagnostics?: boolean): FailureCard;
+/**
+ * The card a readiness blocker becomes.
+ *
+ * The two vocabularies are separate because they answer different questions —
+ * a blocker is "what is missing", a card is "what a person sees when they tried
+ * anyway" — and this is the one place they are joined, so a blocker can never
+ * reach a reader with no card defined for it.
+ */
+export declare function cardForBlocker(blocker: ReadinessBlocker): FailureCard;
+/**
+ * Classify a raw failure without letting its words through.
+ *
+ * The input is read for *signals* — an HTTP status, a taxonomy code the
+ * Harness already normalised — and the output is a kind. The raw text is
+ * never returned, never embedded, and never partially quoted, because a
+ * provider's message is exactly where the internal identifiers come from.
+ *
+ * @param signal - what the runtime managed to normalise about the failure.
+ * @returns the kind a reader is told about.
+ */
+export declare function classifyFailure(signal: {
+    /** HTTP status observed at the provider boundary, when there was one. */
+    readonly status?: number | undefined;
+    /** The Harness's own taxonomy code (`AUTH`, `RATE_LIMIT`, `NO_ADAPTER`, …). */
+    readonly code?: string | undefined;
+}): FailureKind;
+/**
+ * Throw when text bound for an ordinary conversation carries an internal name.
+ *
+ * Applied to cards at construction rather than to the screen at review time.
+ * The failure it prevents is not hypothetical: every shape above is one that
+ * actually reached a reader, and the reason each got there was that some layer
+ * passed a provider or runtime string through "just this once".
+ *
+ * @param where - the surface being guarded, so a failure says what to fix.
+ * @param text - the candidate copy.
+ */
+export declare function assertNoInternalDisclosure(where: string, text: string): void;
+/**
+ * Whether a card is safe to render, as a boolean rather than a throw.
+ *
+ * The same check for callers that are validating a table of copy rather than
+ * building one value — a test over every kind, typically.
+ */
+export declare function isDisclosureSafe(text: string): boolean;
+//# sourceMappingURL=failures.d.ts.map