/** The dependency-free contract leaf (L0): every crossing type, closed unions only; * one home per shape. This module imports NOTHING. */ export type Json = string | number | boolean | null | readonly Json[] | { readonly [k: string]: Json; }; export type Effect = 'read' | 'write' | 'destructive'; export type Done = 'yes' | 'no' | 'unknown'; export type Status = 'done' | 'not-done' | 'unknown'; export type Reason = 'held' | 'refused' | 'blocked'; export type ReportWord = 'done' | 'held' | 'refused' | 'unknown' | 'no_tool_called'; export type Evidence = 'executor' | 'engine'; /** How an open question ends without its code: declined by the operator, superseded by * the act that ran, expired by the clock or the turn ttl, vetoed by a rule, or WITHDRAWN * by the desk itself — its closing report says `refused` for the held call, so the act is * never put to the operator. */ export type QuestionClose = 'declined' | 'superseded' | 'expired' | 'vetoed' | 'withdrawn'; export type QuestionState = 'open' | 'consumed' | { readonly closed: QuestionClose; }; export interface ChatMsg { readonly role: 'user' | 'assistant'; readonly text: string; } /** What this turn's calls did, typed — the seat renders it in its own dialect * (native tool messages on a provider seat; ignored by a scripted seat). */ export interface ActsMsg { readonly role: 'acts'; readonly acts: readonly Act[]; } export type Msg = ChatMsg | ActsMsg; export interface ToolAnswer { readonly result: Json; readonly done: Done; } /** One world change: set fields on an existing record, make a new record whole, * or remove one. A set/remove naming a missing record refuses; a make naming an * existing one refuses — patches validate all-then-apply, never half. */ export type Patch = { readonly entity: string; readonly id: string; readonly set: Readonly>; } | { readonly entity: string; readonly id: string; readonly make: Readonly>; } | { readonly entity: string; readonly id: string; readonly remove: true; }; /** The call as the executor receives it: the tool name and the coerced REAL args — nothing else. * No other field exists: no options, no flags, no attestation override. */ export interface ReadyCall { readonly tool: string; readonly args: Readonly>; } /** The frozen data form of a canonical call. Where it is RECORDED or DELIVERED (Act.call, * Question.call), args are masked; the executable form lives only in engine-private state. */ export interface CanonicalCallData { readonly tool: string; readonly args: Readonly>; readonly key: string; } /** What a check answers when it refuses: the sentence that rides after the card's rule, or — * where the check refuses for something the rule does not state — the sentence that stands in * its place. A check that could not decide at all has not been refused BY the law, and saying * so in the law's words tells the operator something that is not true of them. */ export type Denial = string | { readonly says: string; }; export type Verdict = { readonly kind: 'allow'; } | { readonly kind: 'refuse'; readonly guardName: string; readonly detail: string; /** The check spoke for itself: the detail IS the refusal, and the card's rule * states a law that is not what refused this call. */ readonly says: boolean; } | { readonly kind: 'hold'; readonly guardName: string; readonly sentence: string; } | { readonly kind: 'restate'; readonly actId: string; } | { readonly kind: 'owe'; readonly guardName: string; readonly rule: string; readonly reads: readonly OwedRead[]; }; export interface OwedRead { readonly alias: string; readonly tool: string; readonly args: Readonly>; } export type Correction = { readonly kind: 'redrive'; readonly guardName: string; readonly detail: string; } | { readonly kind: 'postToolFinding'; readonly guardName: string; readonly detail: string; } | { readonly kind: 'earlyFinish'; } | { readonly kind: 'staleFinish'; } | { readonly kind: 'forcedFinish'; } | { readonly kind: 'judgeUnreadable'; readonly guardName: string; } | { readonly kind: 'proseReader'; readonly check: 'wallEcho' | 'language'; readonly detail: string; } | { readonly kind: 'deliveryFigure'; readonly detail: string; } | { readonly kind: 'closeRefused'; readonly attempt: number; readonly text: string; } | { readonly kind: 'rowDropped'; readonly tool: string; readonly target: string; } | { readonly kind: 'returnRefused'; readonly detail: string; }; export interface Act { readonly id: string; readonly turn: number; readonly origin: 'model' | 'engine' | 'licence'; readonly call: CanonicalCallData; readonly effect: Effect; readonly said: Done | null; readonly status: Status; readonly reason: Reason | null; readonly evidence: Evidence; readonly sentence: string; readonly owed: { readonly kind: 'receipt' | 'refusal'; readonly text: string; } | null; readonly result: Json; readonly questionId: string | null; readonly guard: string | null; } export interface ReportLine { readonly tool: string; readonly target: string; readonly word: ReportWord; } export interface FinishPayload { readonly message: string; readonly report: readonly ReportLine[]; /** The id of every owed fact the message expresses — the * engine's own labels, F1, F2 …, never words the operator reads */ readonly facts: readonly string[]; } export interface RawCall { readonly tool: string; readonly args: Readonly>; } export interface ToolCard { readonly name: string; readonly does: string; readonly schema: Json; } export interface StepInput { readonly system: string; readonly messages: readonly Msg[]; readonly tools: readonly ToolCard[]; readonly forceFinish: boolean; readonly llmParams: LlmParams; } export interface StepUsage { readonly inputTokens: number; readonly outputTokens: number; readonly cachedInputTokens: number; /** Thinking tokens the provider billed as output — zero when * thinking is off, which is the engine's default. */ readonly reasoningTokens: number; } export interface ModelStep { readonly calls: readonly RawCall[]; readonly text: string; /** What the provider reported for this step; absent = the * port has no numbers. */ readonly usage?: StepUsage; } export interface Question { readonly id: string; readonly code: string; readonly call: CanonicalCallData; readonly sentence: string; readonly state: QuestionState; readonly bornAtTurn: number; } /** One prior turn's user text and reply text, as the front desk carries it across a * desk hop — the tail of one exchange, never a whole transcript. */ export interface ForeignExchange { readonly desk: string; readonly userText: string; readonly replyText: string; } /** One id the conversation's own acts produced, and the act that produced it — * `desk:tool`. A mark is MINTED from a sealed record's acts; an id a reply merely * states carries none. */ export interface ProvenanceMark { readonly id: string; readonly origin: string; } /** The front desk's verdict for one turn: the desk it chose, or null when the house * never routed. `returned` names the desk that declined the message and why, set * only when this turn is itself a return. `grounded` carries the marks that rode INTO * the turn — the provenance the desk was allowed to stand on; absent when none did. */ export interface TurnRouting { readonly desk: string | null; readonly returned: null | { readonly by: string; readonly reason: string; }; readonly grounded?: readonly ProvenanceMark[]; /** The front desk matched no desk and the house's default * desk served the turn: `desk` names who spoke, and this * says the router never chose them. */ readonly unmatched?: true; } /** A desk's own decision to hand a message back to the front desk, with the reason the * operator reads and what the desk spent reading the message. A returning turn seals no * record, so `usage` is the only place those model calls are ever named — the front desk * carries them onto the record of the turn it re-routes. */ export interface TurnReturned { readonly returned: { readonly reason: string; }; readonly usage: StepUsage & { readonly modelCalls: number; }; } /** Chat-door options: `before` seeds prior exchanges across desks, `returnable` * lets the active desk hand a message back to the front desk, and `grounded` * carries the ids the conversation's own recorded acts returned at other * desks — engine-minted provenance, never text-scraped. */ export interface ChatOpts { readonly before?: readonly ForeignExchange[]; readonly returnable?: boolean; readonly grounded?: readonly string[]; /** The intent gate's answer for this message: on 'yes' the * finish leaves the tool list until a non-read attempt * stands — the tool list is the law. */ readonly act?: 'yes' | 'no' | 'unclear'; } /** How the turn's reply reached the operator: the desk's own finish delivered as it * was written, the desk's close-step when the engine ended the turn, or the * deterministic floor — with the owed facts that were on the table either way. */ export interface DeliveryMarks { readonly by: 'desk' | 'prose' | 'floor'; readonly retried: boolean; readonly facts: readonly { readonly kind: 'ask' | 'code' | 'receipt' | 'refusal' | 'closure' | 'note'; readonly text: string; readonly state: 'ran' | 'refused' | 'held' | null; }[]; } export interface TurnRecord { readonly turn: number; readonly servedBy: string; readonly userText: string; readonly acts: readonly Act[]; readonly questions: { readonly issued: readonly Question[]; readonly consumed: readonly string[]; readonly closed: readonly { readonly id: string; readonly why: QuestionClose; }[]; }; readonly finish: FinishPayload | null; readonly corrections: readonly Correction[]; readonly text: string; readonly delivery: DeliveryMarks; readonly closedBy: 'model' | 'engine'; /** What the turn cost, summed over every model call it made — the main loop, the * owed-read micro-step and the judged pass alike; zeros where the port reports * no numbers. */ readonly usage: StepUsage & { readonly modelCalls: number; }; /** The front desk's decision when the turn arrived routed; absent on a desk-pinned path. */ readonly routing?: TurnRouting; } export declare class TurnFailure extends Error { readonly kind: 'provider-auth' | 'provider-quota' | 'network' | 'executor' | 'construction'; readonly detail: string; constructor(kind: TurnFailure['kind'], detail: string); } export declare class CardError extends Error { readonly problems: readonly { readonly code: string; readonly sentence: string; }[]; constructor(problems: CardError['problems']); } export interface InputCtx { readonly userText: string; readonly turnActs: readonly Act[]; readonly pastActs: readonly Act[]; } export interface CallCtx { readonly call: CanonicalCallData; readonly effect: Effect; readonly consented: boolean; readonly reads: ReadsView; readonly userText: string; readonly userTexts: readonly string[]; /** Ids the conversation's own acts returned at other desks — * engine-minted provenance a grounding check may accept. */ readonly grounded?: readonly string[]; readonly turnActs: readonly Act[]; readonly pastActs: readonly Act[]; } export interface ResultCtx { readonly call: CanonicalCallData; readonly result: Json; readonly userText: string; readonly turnActs: readonly Act[]; readonly pastActs: readonly Act[]; } export interface ReplyCtx { readonly message: string; readonly report: readonly ReportLine[]; readonly userText: string; readonly turnActs: readonly Act[]; readonly pastActs: readonly Act[]; } export type StateSnapshot = { readonly [entity: string]: { readonly [id: string]: Readonly>; }; }; /** What this conversation's tool calls answered, as a guard consults it: the last * valid answer of a read, opaque — a condition walks it with its own declared * knowledge of the surface, and the engine walks only declared paths. */ export interface ReadsView { latest(tool: string, argsKey?: string): { readonly answer: Json; readonly at: number; } | null; } /** The empty view: nothing has been read. A stateless ctx and a test both stand on it. */ export declare const NO_READS: ReadsView; export interface InstalledGuard { readonly name: string; readonly rule: string; readonly home: 'spec' | 'contract' | 'engine'; readonly on: 'input' | 'preTool' | 'postTool' | 'reply'; readonly tools: readonly string[]; readonly kind: string; readonly judged: boolean; readonly installedBecause: string; } export type RewriteKind = 'purgePattern' | 'maskPattern' | 'swapTerms' | 'spokenDates'; export interface Rewrite { readonly name: string; readonly kind: RewriteKind; apply(text: string): string; } export interface GuardCensus { readonly guards: readonly InstalledGuard[]; readonly rewrites: readonly { readonly name: string; readonly kind: RewriteKind; }[]; readonly limits: { readonly calls: number; readonly destructive: number; readonly retries: number; readonly questionTurns: number; }; } export type EngineSentenceKey = 'approvalInstruction' | 'exhaustionClosure' | 'unknownStatus' | 'questionExpired' | 'questionSuperseded' | 'questionDeclined' | 'deniedByGuard' | 'nothingOwed'; /** The fully-resolved wording table: every engine sentence and every user-facing * status word present, defaults filled — the table never carries a hole. */ export interface ResolvedWording { readonly status: Readonly>; readonly sentence: Readonly>; } export type RoutingStrategy = 'sequential' | 'random' | 'rate-limit' | 'backup-only' | 'round-robin'; export interface ModelTarget { readonly id: string; readonly provider: string; readonly keyEnv: string | null; readonly tier: 'cloud' | { readonly local: string; }; readonly certified: boolean; } export type ModelChoice = string | { readonly targets: readonly string[]; readonly strategy: RoutingStrategy; }; export type ProviderPreset = 'gemini:thinking-on'; export interface LlmParams { readonly temperature?: number; readonly topP?: number; readonly maxOutputTokens?: number; readonly preset?: ProviderPreset; } /** Request options a TARGET declares, namespaced by the provider that understands * them: the outer key names the provider, the inner keys are that provider's own * request fields. The engine forwards them to every model call untouched and spells * no field itself — a local llama.cpp target declares `{ llamacpp: { cache_prompt: * true } }`, and a cloud target that declares nothing sends nothing. */ export type ProviderOptions = Readonly>>>; export interface ServingHandle { readonly baseUrl: string; readonly servedModel: string; stop(): Promise; } export interface TierSpec { readonly alias: string; readonly speculative: 'none' | 'draft-mtp'; readonly kv: 'f16' | 'q8_0'; readonly ctx: number; readonly cacheRam: number; readonly slots: number; } /** Engine-internal tool truth — one fact per declared tool. No authoring name exists * for this shape; cards/facts.ts re-exports it for the compile layer, the way * LlmParams is re-exported for authors. */ export interface ToolFact { readonly name: string; readonly label: string | null; readonly does: string; readonly effect: Effect; readonly target: string | null; readonly entity: string | null; readonly schema: Json; readonly destructiveWhen: ConsentWhen | null; readonly proxy: string | { readonly compose: readonly string[]; } | null; } /** The whole declared surface as facts, keyed by tool name. */ export interface SurfaceFacts { readonly tools: Readonly>; /** The birth register: the acts that mint a record * that did not exist, whatever effect block they * sit in; null = the card names none. */ readonly creates?: readonly string[] | null; } /** The world vocabulary — crossing types for the three surface-card kinds. * world/world.ts re-exports them for authors, the way cards.ts re-exports LlmParams; * cards/facts.ts derives SurfaceFacts from them without importing world/. */ /** A declared precondition on a tool's target record, evaluated on EVERY tool kind. * A missing record is a refusal with the gate's sentence, never a silent pass. */ export type Gate = { readonly kind: 'exists'; } | { readonly kind: 'stateIs'; readonly field: string; readonly value: Json; } | { readonly kind: 'fieldAtLeast'; readonly field: string; readonly min: number; }; /** The action forms a world tool can take, as data; 'run' names a custom executor. */ export type ActionForm = 'list' | 'get' | 'make' | 'set' | 'remove' | 'run'; /** One declared world tool: the form, the entity it acts on, and its user-facing words. */ /** The one destructive-branch declaration: a call whose named arg carries one of * the listed values is the destructive branch (holds for consent); any other call * of the same tool runs as a write. */ export interface ConsentWhen { readonly arg: string; readonly oneOf: readonly Json[]; } export interface WorldToolEntry { readonly form: ActionForm; readonly entity: string; readonly label: string; readonly does?: string; readonly gates?: readonly Gate[]; /** Declared args; omitted = the form's own schema. */ readonly schema?: Json; /** The target arg; omitted = the form's own. */ readonly target?: string; readonly when?: ConsentWhen; } /** The declarative world: records + the three effect blocks + presets. Closed data — * no functions, no regexes, no clock inside the card; custom executors pass OUTSIDE. */ export interface WorldCard { readonly records: StateSnapshot; readonly reads?: Readonly>; readonly writes?: Readonly>; readonly destructive?: Readonly>; /** The birth register: the acts that mint a record that * did not exist. The block a tool sits in is its effect; * this list is its birth register, and a consented act * that mints on every call belongs on it too. */ readonly creates?: readonly string[]; readonly presets?: Readonly>; } /** One typed approval: the tool whose open question this turn licenses; args only * to split open SIBLINGS of one tool — a code is never extracted from prose. */ export interface ApproveRef { readonly tool: string; readonly args?: Readonly>; } /** One scripted exam turn: user text, one or several typed approvals (several = * one message licensing several open questions), or one typed decline. */ export type ExamTurn = string | { readonly approve: ApproveRef | readonly ApproveRef[]; } | { readonly decline: true; }; /** A deterministic act matcher: the named call happened (required) or took no * effect (noEffect), with an args subset when the case pins one. `anyOf` widens * a required call to alternative reads that ground the same fact — the * requirement is the grounding, never one path to it. */ export interface ToolMatcher { readonly name: string; readonly anyOf?: readonly string[]; readonly anyArgs?: Readonly>; } /** One exam case: the turns, the split discipline, and the rubric the in-session * judge reads. `agent` names the desk on a multi-agent subject; `preset` names * the world scenario; `covers` names the guards this case exists to fire (the * census key); `invariants` are checked deterministically against the records; * `red` names the attack class when the case is an adversarial row; `route` * pins the expected desk for every operator turn on a routed case — 'none' * names the front desk's own refusal, and an inner array names a defensible * SET, any member of which counts. A case with `route` and no `agent` plays * through the routed house instead of one pinned desk. */ export interface ExamCase { readonly id: string; readonly split: 'fix' | 'held-out'; readonly agent?: string; readonly preset?: string; readonly red?: string; readonly covers?: readonly string[]; readonly invariants?: { readonly requiredToolCalls?: readonly ToolMatcher[]; readonly noEffectToolCalls?: readonly ToolMatcher[]; }; readonly route?: readonly (string | readonly string[])[]; readonly turns: readonly ExamTurn[]; readonly rubric: string; } /** One remote tool on an MCP or live surface: words and bindings, no action form. * proxy as a string is a declared RENAME to the real live tool; proxy as a compose * block executes the listed live reads and merges their results in order. */ export interface RemoteToolEntry { readonly label: string; readonly target?: string; readonly proxy?: string | { readonly compose: readonly string[]; }; readonly when?: ConsentWhen; readonly does?: string; readonly schema?: Json; } /** The MCP sibling: the same effect blocks over remote entries — no records, no gates. */ export interface McpWorldCard { readonly reads?: Readonly>; readonly writes?: Readonly>; readonly destructive?: Readonly>; } /** The live sibling: tools that execute themselves on a named host. */ export interface LiveWorldCard extends McpWorldCard { readonly host: string; } /** One row of the world's own audit trail: the row states the result; the mechanism * is its own field. */ export interface AuditRow { readonly call: ReadyCall; readonly done: Done; readonly executor: 'declared' | 'custom'; } /** A custom executor: coerced args + a deep-frozen records CLONE + the id mint; its * patches apply through the shared gated, audited path — never directly. A refusal * is its own channel and prices done:'no' — a refusing tool never reads as done. */ export type CustomExecutor = (ctx: { readonly args: Readonly>; readonly records: StateSnapshot; readonly mintId: (entity: string) => string; }) => { readonly result: Json; readonly patches: readonly Patch[]; } | { readonly refuse: Json; }; /** A validated, frozen world declaration: the card plus its custom executors. */ export interface DeclaredWorld { readonly card: WorldCard; readonly executors: Readonly>; } //# sourceMappingURL=vocabulary.d.ts.map