import { z } from "zod";
import { type ShapeType } from "./shape.js";
/**
 * Field semantics: what a tool-response field MEANS (cents money, ISO date,
 * enum vocabulary, id, percent scale, a readable code), beyond its
 * structural shape. Carried per tool inside `.vendo/tools.json` (the machine
 * layer, overlaid by the host's `overrides.json` annotations) and consumed by
 * generation context as annotated shape cards
 * ({@link describeShapeWithSemantics}).
 */
export type FieldSemantic = {
    kind: "money";
    unit: "cents" | "dollars";
    currency?: string;
} | {
    kind: "date";
    format: "iso" | "epoch";
} | {
    kind: "enum";
    labels: Record<string, string>;
} | {
    kind: "id";
    entity?: string;
} | {
    kind: "percent";
    scale: "ratio" | "0-100";
}
/** An identifier a person READS — a sha, a branch, a path, a ticket key.
 *  Distinct from `id`, which is a handle a screen passes back to a tool and
 *  usually never shows: `code` is text on the page, and what it declares is a
 *  FACE. `feat/timeline-brick` is the case no shape can catch — it is a plain
 *  string by every structural test, and only the host knows it is a ref. */
 | {
    kind: "code";
} | {
    kind: "plain";
};
export declare const fieldSemanticSchema: z.ZodType<FieldSemantic>;
/** One tool's field semantics, keyed by COLLAPSED dot path into the response:
 *  object fields by name, array levels collapsed (no numeric segments) —
 *  `data.amountCents` covers `/data/3/amountCents`. */
export type ToolSemantics = Record<string, FieldSemantic>;
export declare const toolSemanticsSchema: z.ZodType<ToolSemantics>;
/**
 * What the HOST declared about one tool-input field's money unit.
 *
 * `"cents"` / `"dollars"` — declared, in the property's description or by a
 * name that states its own unit (`amountCents`). `"unknown"` — the field is
 * money-shaped but nobody said in which unit, so a renderer must NOT present it
 * as an amount. `undefined` — not money at all; leave it alone.
 *
 * Why this exists: a $47.50 payment's consent card rendered `amount 4750`,
 * which reads as $4,750 — a 100× misread on the one surface that gates
 * irreversible money movement. Declaration only, never a guess from the value:
 * mislabelling a non-money integer as currency would be the same defect
 * pointing the other way.
 */
export declare function declaredMoneyUnit(field: string, schema: Record<string, unknown> | undefined): "cents" | "dollars" | "unknown" | undefined;
/**
 * The tokens a READ SITE can act on — the closed half of
 * {@link describeFieldSemantic}'s vocabulary.
 *
 * A shape card prints a field's semantic as one of these, and a Kit column or
 * field is annotated with the same token, so a writer copies across what it was
 * shown instead of translating it (`@vendoai/vendo/ui` kit/row.ts). Declared here
 * because the printer and the reader must never drift: a token the card prints
 * and the Kit refuses is a dead end for whoever copied it.
 *
 * `enum(a|b)` and a currency-qualified `money.cents(USD)` are deliberately out —
 * they carry a payload rather than naming a kind, and no read site reads one.
 */
export declare const SEMANTIC_TOKENS: readonly ["money.cents", "money.dollars", "date.iso", "date.epoch", "percent.ratio", "percent.0-100", "code", "id"];
export type SemanticToken = (typeof SEMANTIC_TOKENS)[number];
/** The compact semantic annotation appended to a field's kind in a shape
 *  card: `number:money.cents`, `string:date.iso`, `string:enum(a|b)`. */
export declare const describeFieldSemantic: (semantic: FieldSemantic) => string;
/** {@link describeShape}, with each classified field annotated
 *  (`amountCents: number:money.cents`). Identical to describeShape when no
 *  semantics apply. */
export declare function describeShapeWithSemantics(shape: ShapeType, semantics: ToolSemantics): string;