@amboras-dev/capability-kit 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,313 @@
+import { z } from "zod/v4";
+//#region src/canonical-json.d.ts
+/** Sorted keys, no whitespace. Throws on BigInt and circular values; `undefined` at the top serializes as `null`. */
+export declare function canonicalJson(v: unknown): string;
+//#endregion
+//#region src/ids.d.ts
+export declare const AREAS: readonly ["promotions", "catalog", "inventory", "setup", "content", "orders", "payments", "domains", "publish"];
+type Area = (typeof AREAS)[number];
+/** `<area>.<verb>` or `<area>.<entity>.<verb>`: lowercase segments of `a-z` and `_`. */
+type CapabilityId = `${Area}.${string}`;
+type Role = 'owner' | 'manager' | 'staff';
+/** Higher rank includes every lower one: an owner can do what a manager can. */
+export declare const ROLE_RANK: Readonly<Record<Role, number>>;
+/** True for a well-formed id in a known area. */
+export declare function isCapabilityId(value: unknown): value is CapabilityId;
+/** The area an id belongs to (`promotions.create` → `promotions`). */
+export declare function areaOf(id: CapabilityId): Area;
+//#endregion
+//#region src/context.d.ts
+type Actor = {
+  kind: 'member';
+  profileId: string;
+  role: Role | null;
+} | {
+  kind: 'internal';
+  service: string;
+};
+/** A label for logs. Never trusted for a policy decision. */
+type Surface = 'ai' | 'admin' | 'api';
+interface CapabilityCallContext {
+  tenantId: string;
+  actor: Actor;
+  surface: Surface;
+  runId?: string;
+}
+//#endregion
+//#region src/json-schema.d.ts
+type JsonSchema = {
+  [key: string]: unknown;
+};
+/**
+ * A copy of `schema` without the hidden fields (`agent.hideFields`), also
+ * dropped from `required`. Adapters build the model-facing input with this.
+ */
+export declare function omitFields(schema: JsonSchema, fields: readonly string[]): JsonSchema;
+//#endregion
+//#region src/policy-types.d.ts
+interface CapabilityPolicy {
+  minRole: Role;
+  planFeature?: string;
+  effect: 'read' | 'write' | 'destructive';
+  /** True = safe to retry without a key (reads, set-to-value). */
+  idempotent: boolean;
+  /** Grants or moves value: fail closed everywhere. */
+  money?: boolean;
+  confirm: 'never' | 'always' | {
+    when: {
+      recordsAtLeast: number;
+    };
+  };
+  rateLimit?: {
+    perMinute: number;
+  };
+}
+//#endregion
+//#region src/define.d.ts
+interface CapabilityAgentSpec {
+  /** What it does and when to use it, written for the model. */
+  description: string;
+  /** Only what the schema shape cannot carry. */
+  rules?: string[];
+  examples?: Array<{
+    input: unknown;
+    note: string;
+  }>;
+  /** Dotted input paths the model never sees; each must exist and be optional. */
+  hideFields?: string[];
+  exposure: 'task-tool' | 'long-tail' | 'hidden';
+  /** Phase 1: keeps the legacy tool name (e.g. 'create_promotion') so prompts, evals and TOOL_CAPABILITIES keys stay stable. */
+  toolName?: string;
+}
+interface CapabilityDefinition<I = unknown, O = unknown, Ctx = unknown> {
+  id: CapabilityId;
+  /** Integer ≥ 1; bump on a breaking input or output change. */
+  version: number;
+  owner: 'medusa' | 'orchestrator';
+  http: {
+    method: 'GET' | 'POST' | 'DELETE';
+    path: string;
+    runsOn: 'custom' | 'core';
+  };
+  input: z.ZodType<I>;
+  output: z.ZodType<O>;
+  run?(ctx: Ctx, input: I): Promise<O>;
+  policy: CapabilityPolicy;
+  agent: CapabilityAgentSpec;
+}
+/**
+ * Checks a definition and returns a frozen copy. Throws CapabilityDefinitionError
+ * on: a bad id or unknown area; a version that is not a positive integer; an
+ * input that is not an object, accepts undeclared keys or any value, or names a
+ * store / tenant / profile / environment id at any depth; runsOn 'custom'
+ * without run; hideFields naming a missing (or required) field; a schema JSON
+ * Schema cannot express; a money() field without its unit sentence or with a
+ * currencyField that is not a string field at the input root; an invalid
+ * minRole, confirm threshold, rate limit or toolName.
+ */
+export declare function defineCapability<I, O, Ctx = unknown>(def: CapabilityDefinition<I, O, Ctx>): Readonly<CapabilityDefinition<I, O, Ctx>>;
+//#endregion
+//#region src/errors.d.ts
+type CapabilityErrorCode = 'invalid_input' | 'forbidden' | 'not_found' | 'conflict' | 'confirmation_required' | 'rate_limited' | 'idempotency_conflict' | 'unavailable' | 'internal';
+interface CapabilityErrorBody {
+  code: CapabilityErrorCode;
+  message: string;
+  /** Dotted input path the error is about (`discount.amount_off`). */
+  field?: string;
+  /** Stable id of the business rule that refused (`idempotency_key_required`). */
+  rule?: string;
+  retryable: boolean;
+  issues?: Array<{
+    field: string;
+    message: string;
+  }>;
+  /** Small structured facts the caller can act on (duplicate_code → { existing_id, existing_status }). Never secrets or PII. */
+  details?: Record<string, string | number | boolean | null>;
+}
+export declare function httpStatusFor(code: CapabilityErrorCode): number;
+type CapabilityErrorInit = Omit<CapabilityErrorBody, 'retryable'> & {
+  retryable?: boolean;
+};
+export declare class CapabilityError extends Error {
+  readonly body: CapabilityErrorBody;
+  readonly status: number;
+  /** `retryable` defaults to true for `rate_limited` and `unavailable`, else false. */
+  constructor(init: CapabilityErrorInit);
+}
+/** A definition that breaks a kit rule. Thrown at boot, never per request. */
+export declare class CapabilityDefinitionError extends Error {
+  constructor(message: string);
+}
+/** A manifest that fails its shape or hash check. */
+export declare class CapabilityManifestError extends Error {
+  constructor(message: string);
+}
+interface FromZodErrorOptions {
+  /**
+   * Fields that no longer exist, keyed by the old name, valued with what to use
+   * instead. An unrecognized key listed here (strict objects only) answers
+   * `"value" was removed: use percent_off or amount_off (major units).` with
+   * rule `field_renamed`, instead of zod's generic message.
+   */
+  renamed?: Readonly<Record<string, string>>;
+}
+/**
+ * `invalid_input`: `field` is the dotted path of the first issue, `issues` lists
+ * all of them. Renamed-field issues (`options.renamed`) come first and make the headline. A custom issue's `params.rule` becomes `body.rule`; see
+ * `options.renamed` for steering removed field names.
+ */
+export declare function fromZodError(err: z.ZodError, options?: FromZodErrorOptions): CapabilityError;
+//#endregion
+//#region src/idempotency.d.ts
+/**
+ * 8–100 of `A-Z a-z 0-9 . _ : -`. The underscore is there because the
+ * orchestrator's key is `cap.{runId}.{toolCallId}` and model tool call ids
+ * contain one (`toolu_…`, `call_…`).
+ */
+export declare const IDEMPOTENCY_KEY_PATTERN: RegExp;
+/** A non-read capability that is not naturally idempotent needs an `Idempotency-Key`. */
+export declare function requiresIdempotencyKey(policy: Pick<CapabilityPolicy, 'effect' | 'idempotent'>): boolean;
+/** sha256 hex of canonicalJson({ id, input }): same key + different fingerprint = a different request. */
+export declare function requestFingerprint(id: CapabilityId, input: unknown): string;
+//#endregion
+//#region src/manifest.d.ts
+interface ManifestEntry {
+  id: CapabilityId;
+  version: number;
+  owner: 'medusa' | 'orchestrator';
+  http: CapabilityDefinition['http'];
+  input: JsonSchema;
+  output: JsonSchema;
+  policy: CapabilityPolicy;
+  agent: CapabilityAgentSpec;
+}
+interface CapabilityManifest {
+  schemaVersion: 1;
+  source: 'medusa' | 'orchestrator';
+  hash: string;
+  capabilities: ManifestEntry[];
+}
+/** Any definition, whatever its input, output and context types. */
+type AnyCapabilityDefinition = Readonly<CapabilityDefinition<unknown, unknown, never>>;
+/**
+ * Deterministic: entries sorted by id, schemas converted with
+ * `{ target: 'draft-2020-12', io }`, no timestamps. Every definition is checked
+ * again (the defineCapability rules). Throws on a duplicate id.
+ *
+ * The JSON Schema text depends on the zod version that emits it (zod 3.25 writes
+ * a discriminated union as anyOf, 4.3 as oneOf), so the hash is only comparable
+ * between emits on the SAME zod version. Consumers verify a received manifest
+ * with parseManifest; they never re-emit it to compare.
+ */
+export declare function emitManifest(defs: readonly AnyCapabilityDefinition[], source: 'medusa' | 'orchestrator'): CapabilityManifest;
+/**
+ * Validates the shape, re-runs the definition rules on every entry (tenant ids,
+ * open inputs, money sentence …) and recomputes the hash from the JSON as
+ * received, never from schemas. Throws CapabilityManifestError on any failure.
+ * The hash proves the file is intact, not who wrote it: trust comes from where
+ * the file is read (the committed copy), not from the hash.
+ */
+export declare function parseManifest(json: unknown): CapabilityManifest;
+//#endregion
+//#region src/money.d.ts
+/** The one unit sentence every money field carries, for the model and for people. */
+export declare const MONEY_UNIT_SENTENCE = "Amount in normal currency units as the merchant says it (99 means 99.00; 1.5 means 1.50). Never cents or minor units.";
+/** JSON Schema keyword marking a money field. */
+export declare const MONEY_META_KEY = "x-amboras-money";
+/**
+ * A bad amount or currency code. It is an `invalid_input` CapabilityError, so an
+ * adapter that maps CapabilityError answers 400 with the rule (and the field,
+ * when the caller passed one) instead of a 500.
+ */
+export declare class MoneyError extends CapabilityError {
+  constructor(message: string, rule: 'money_precision' | 'money_invalid' | 'currency_invalid', field?: string);
+}
+/**
+ * Where the amount's currency comes from. `currencyField` names a field resolved
+ * from the INPUT ROOT, at any depth of the money field (`discount.amount_off`
+ * with `{ currencyField: 'currency_code' }` reads the top-level `currency_code`).
+ */
+type MoneyCurrency = {
+  currencyField: string;
+} | {
+  currency: 'store';
+};
+type MoneyOptions = MoneyCurrency & {
+  /** What the amount is; prepended to the unit sentence. */
+  describe?: string;
+  /** Strict lower bound (`0` = must be more than zero). Default: amounts are ≥ 0. */
+  exclusiveMinimum?: number;
+  /** Inclusive upper bound. */
+  max?: number;
+};
+/**
+ * A major-unit amount: finite, ≥ 0 (or > `exclusiveMinimum`), at most `max`,
+ * described with MONEY_UNIT_SENTENCE and marked `x-amboras-money` in JSON Schema.
+ *
+ * Chained checks (`.positive()`, `.max()`, `.int()`) and `.optional()`,
+ * `.nullable()`, `.nullish()` are safe: the kit's JSON Schema keeps the sentence
+ * and the marker. `.describe()` replaces the sentence, which `defineCapability`
+ * rejects: pass `describe` here instead.
+ */
+export declare function money(opts: MoneyOptions): z.ZodNumber;
+/** ISO 4217 minor-unit digits: 0 for JPY/KRW/VND…, 3 for KWD/BHD/OMR/TND/JOD/IQD/LYD, else 2 (also for unknown codes). */
+export declare function fractionDigits(currency: string): 0 | 2 | 3;
+/**
+ * Amboras storage rule: ×1000 for the seven three-decimal codes, ×100 for every
+ * other code INCLUDING zero-decimal ones (¥5 is stored as 500). By design; see
+ * Medusa `divisorFor`.
+ */
+export declare function storageScale(currency: string): 100 | 1000;
+/**
+ * Major → stored minor integer. Throws MoneyError (`invalid_input`) when the
+ * amount has more fraction digits than the currency allows (19.999 USD, 5.5 JPY),
+ * is not finite, or does not fit a safe integer. Pass `field` to name the input
+ * field in the error.
+ *
+ * An amount is accepted when its decimal text has at most the allowed digits
+ * (exact at any magnitude), or when it is within float noise of such an amount
+ * (0.1 + 0.2 → 0.30). Noise is bounded absolutely, so a real extra digit is never
+ * rounded away, however large the amount.
+ */
+export declare function toStorageAmount(major: number, currency: string, field?: string): number;
+/** Stored minor amount → major units. */
+export declare function fromStorageAmount(minor: number, currency: string): number;
+interface MoneyView {
+  amount: number;
+  currency: string;
+  display: string;
+}
+/** Output schema for a MoneyView (what `moneyView` returns), for capability outputs. */
+export declare const moneyViewSchema: z.ZodType<MoneyView>;
+/**
+ * A stored amount as the merchant reads it. Fraction digits are pinned (not left
+ * to the runtime's ICU data): ISO digits, widened only to show a stored value
+ * that is not a whole minor unit (¥5.5 stays visible).
+ */
+export declare function moneyView(minor: number, currency: string): MoneyView;
+//#endregion
+//#region src/policy.d.ts
+/** Phase 1 adapters pass observe/observe. */
+interface PolicyEnforcement {
+  role: 'enforce' | 'observe';
+  plan: 'enforce' | 'observe';
+}
+/** `observed` holds the rule ids an 'observe' check would have denied, for logging. */
+type PolicyDecision = {
+  allow: true;
+  observed: string[];
+} | {
+  allow: false;
+  error: CapabilityError;
+};
+export declare function evaluatePolicy(policy: CapabilityPolicy, ctx: CapabilityCallContext, facts: {
+  planFeatures?: string[];
+}, enforcement: PolicyEnforcement): PolicyDecision;
+/**
+ * True when the call needs an explicit confirmation before it runs. `records` is
+ * how many records it touches. A threshold policy with no count, or a count that
+ * is not a non-negative integer, requires confirmation (the adapter could not count).
+ */
+export declare function confirmationRequired(policy: Pick<CapabilityPolicy, 'confirm'>, records?: number): boolean;
+//#endregion
+export type { Actor, AnyCapabilityDefinition, Area, CapabilityAgentSpec, CapabilityCallContext, CapabilityDefinition, CapabilityErrorBody, CapabilityErrorCode, CapabilityErrorInit, CapabilityId, CapabilityManifest, CapabilityPolicy, FromZodErrorOptions, JsonSchema, ManifestEntry, MoneyCurrency, MoneyOptions, MoneyView, PolicyDecision, PolicyEnforcement, Role, Surface };

package/dist/index.d.ts

@@ -0,0 +1,313 @@
+import { z } from "zod/v4";
+//#region src/canonical-json.d.ts
+/** Sorted keys, no whitespace. Throws on BigInt and circular values; `undefined` at the top serializes as `null`. */
+export declare function canonicalJson(v: unknown): string;
+//#endregion
+//#region src/ids.d.ts
+export declare const AREAS: readonly ["promotions", "catalog", "inventory", "setup", "content", "orders", "payments", "domains", "publish"];
+type Area = (typeof AREAS)[number];
+/** `<area>.<verb>` or `<area>.<entity>.<verb>`: lowercase segments of `a-z` and `_`. */
+type CapabilityId = `${Area}.${string}`;
+type Role = 'owner' | 'manager' | 'staff';
+/** Higher rank includes every lower one: an owner can do what a manager can. */
+export declare const ROLE_RANK: Readonly<Record<Role, number>>;
+/** True for a well-formed id in a known area. */
+export declare function isCapabilityId(value: unknown): value is CapabilityId;
+/** The area an id belongs to (`promotions.create` → `promotions`). */
+export declare function areaOf(id: CapabilityId): Area;
+//#endregion
+//#region src/context.d.ts
+type Actor = {
+  kind: 'member';
+  profileId: string;
+  role: Role | null;
+} | {
+  kind: 'internal';
+  service: string;
+};
+/** A label for logs. Never trusted for a policy decision. */
+type Surface = 'ai' | 'admin' | 'api';
+interface CapabilityCallContext {
+  tenantId: string;
+  actor: Actor;
+  surface: Surface;
+  runId?: string;
+}
+//#endregion
+//#region src/json-schema.d.ts
+type JsonSchema = {
+  [key: string]: unknown;
+};
+/**
+ * A copy of `schema` without the hidden fields (`agent.hideFields`), also
+ * dropped from `required`. Adapters build the model-facing input with this.
+ */
+export declare function omitFields(schema: JsonSchema, fields: readonly string[]): JsonSchema;
+//#endregion
+//#region src/policy-types.d.ts
+interface CapabilityPolicy {
+  minRole: Role;
+  planFeature?: string;
+  effect: 'read' | 'write' | 'destructive';
+  /** True = safe to retry without a key (reads, set-to-value). */
+  idempotent: boolean;
+  /** Grants or moves value: fail closed everywhere. */
+  money?: boolean;
+  confirm: 'never' | 'always' | {
+    when: {
+      recordsAtLeast: number;
+    };
+  };
+  rateLimit?: {
+    perMinute: number;
+  };
+}
+//#endregion
+//#region src/define.d.ts
+interface CapabilityAgentSpec {
+  /** What it does and when to use it, written for the model. */
+  description: string;
+  /** Only what the schema shape cannot carry. */
+  rules?: string[];
+  examples?: Array<{
+    input: unknown;
+    note: string;
+  }>;
+  /** Dotted input paths the model never sees; each must exist and be optional. */
+  hideFields?: string[];
+  exposure: 'task-tool' | 'long-tail' | 'hidden';
+  /** Phase 1: keeps the legacy tool name (e.g. 'create_promotion') so prompts, evals and TOOL_CAPABILITIES keys stay stable. */
+  toolName?: string;
+}
+interface CapabilityDefinition<I = unknown, O = unknown, Ctx = unknown> {
+  id: CapabilityId;
+  /** Integer ≥ 1; bump on a breaking input or output change. */
+  version: number;
+  owner: 'medusa' | 'orchestrator';
+  http: {
+    method: 'GET' | 'POST' | 'DELETE';
+    path: string;
+    runsOn: 'custom' | 'core';
+  };
+  input: z.ZodType<I>;
+  output: z.ZodType<O>;
+  run?(ctx: Ctx, input: I): Promise<O>;
+  policy: CapabilityPolicy;
+  agent: CapabilityAgentSpec;
+}
+/**
+ * Checks a definition and returns a frozen copy. Throws CapabilityDefinitionError
+ * on: a bad id or unknown area; a version that is not a positive integer; an
+ * input that is not an object, accepts undeclared keys or any value, or names a
+ * store / tenant / profile / environment id at any depth; runsOn 'custom'
+ * without run; hideFields naming a missing (or required) field; a schema JSON
+ * Schema cannot express; a money() field without its unit sentence or with a
+ * currencyField that is not a string field at the input root; an invalid
+ * minRole, confirm threshold, rate limit or toolName.
+ */
+export declare function defineCapability<I, O, Ctx = unknown>(def: CapabilityDefinition<I, O, Ctx>): Readonly<CapabilityDefinition<I, O, Ctx>>;
+//#endregion
+//#region src/errors.d.ts
+type CapabilityErrorCode = 'invalid_input' | 'forbidden' | 'not_found' | 'conflict' | 'confirmation_required' | 'rate_limited' | 'idempotency_conflict' | 'unavailable' | 'internal';
+interface CapabilityErrorBody {
+  code: CapabilityErrorCode;
+  message: string;
+  /** Dotted input path the error is about (`discount.amount_off`). */
+  field?: string;
+  /** Stable id of the business rule that refused (`idempotency_key_required`). */
+  rule?: string;
+  retryable: boolean;
+  issues?: Array<{
+    field: string;
+    message: string;
+  }>;
+  /** Small structured facts the caller can act on (duplicate_code → { existing_id, existing_status }). Never secrets or PII. */
+  details?: Record<string, string | number | boolean | null>;
+}
+export declare function httpStatusFor(code: CapabilityErrorCode): number;
+type CapabilityErrorInit = Omit<CapabilityErrorBody, 'retryable'> & {
+  retryable?: boolean;
+};
+export declare class CapabilityError extends Error {
+  readonly body: CapabilityErrorBody;
+  readonly status: number;
+  /** `retryable` defaults to true for `rate_limited` and `unavailable`, else false. */
+  constructor(init: CapabilityErrorInit);
+}
+/** A definition that breaks a kit rule. Thrown at boot, never per request. */
+export declare class CapabilityDefinitionError extends Error {
+  constructor(message: string);
+}
+/** A manifest that fails its shape or hash check. */
+export declare class CapabilityManifestError extends Error {
+  constructor(message: string);
+}
+interface FromZodErrorOptions {
+  /**
+   * Fields that no longer exist, keyed by the old name, valued with what to use
+   * instead. An unrecognized key listed here (strict objects only) answers
+   * `"value" was removed: use percent_off or amount_off (major units).` with
+   * rule `field_renamed`, instead of zod's generic message.
+   */
+  renamed?: Readonly<Record<string, string>>;
+}
+/**
+ * `invalid_input`: `field` is the dotted path of the first issue, `issues` lists
+ * all of them. Renamed-field issues (`options.renamed`) come first and make the headline. A custom issue's `params.rule` becomes `body.rule`; see
+ * `options.renamed` for steering removed field names.
+ */
+export declare function fromZodError(err: z.ZodError, options?: FromZodErrorOptions): CapabilityError;
+//#endregion
+//#region src/idempotency.d.ts
+/**
+ * 8–100 of `A-Z a-z 0-9 . _ : -`. The underscore is there because the
+ * orchestrator's key is `cap.{runId}.{toolCallId}` and model tool call ids
+ * contain one (`toolu_…`, `call_…`).
+ */
+export declare const IDEMPOTENCY_KEY_PATTERN: RegExp;
+/** A non-read capability that is not naturally idempotent needs an `Idempotency-Key`. */
+export declare function requiresIdempotencyKey(policy: Pick<CapabilityPolicy, 'effect' | 'idempotent'>): boolean;
+/** sha256 hex of canonicalJson({ id, input }): same key + different fingerprint = a different request. */
+export declare function requestFingerprint(id: CapabilityId, input: unknown): string;
+//#endregion
+//#region src/manifest.d.ts
+interface ManifestEntry {
+  id: CapabilityId;
+  version: number;
+  owner: 'medusa' | 'orchestrator';
+  http: CapabilityDefinition['http'];
+  input: JsonSchema;
+  output: JsonSchema;
+  policy: CapabilityPolicy;
+  agent: CapabilityAgentSpec;
+}
+interface CapabilityManifest {
+  schemaVersion: 1;
+  source: 'medusa' | 'orchestrator';
+  hash: string;
+  capabilities: ManifestEntry[];
+}
+/** Any definition, whatever its input, output and context types. */
+type AnyCapabilityDefinition = Readonly<CapabilityDefinition<unknown, unknown, never>>;
+/**
+ * Deterministic: entries sorted by id, schemas converted with
+ * `{ target: 'draft-2020-12', io }`, no timestamps. Every definition is checked
+ * again (the defineCapability rules). Throws on a duplicate id.
+ *
+ * The JSON Schema text depends on the zod version that emits it (zod 3.25 writes
+ * a discriminated union as anyOf, 4.3 as oneOf), so the hash is only comparable
+ * between emits on the SAME zod version. Consumers verify a received manifest
+ * with parseManifest; they never re-emit it to compare.
+ */
+export declare function emitManifest(defs: readonly AnyCapabilityDefinition[], source: 'medusa' | 'orchestrator'): CapabilityManifest;
+/**
+ * Validates the shape, re-runs the definition rules on every entry (tenant ids,
+ * open inputs, money sentence …) and recomputes the hash from the JSON as
+ * received, never from schemas. Throws CapabilityManifestError on any failure.
+ * The hash proves the file is intact, not who wrote it: trust comes from where
+ * the file is read (the committed copy), not from the hash.
+ */
+export declare function parseManifest(json: unknown): CapabilityManifest;
+//#endregion
+//#region src/money.d.ts
+/** The one unit sentence every money field carries, for the model and for people. */
+export declare const MONEY_UNIT_SENTENCE = "Amount in normal currency units as the merchant says it (99 means 99.00; 1.5 means 1.50). Never cents or minor units.";
+/** JSON Schema keyword marking a money field. */
+export declare const MONEY_META_KEY = "x-amboras-money";
+/**
+ * A bad amount or currency code. It is an `invalid_input` CapabilityError, so an
+ * adapter that maps CapabilityError answers 400 with the rule (and the field,
+ * when the caller passed one) instead of a 500.
+ */
+export declare class MoneyError extends CapabilityError {
+  constructor(message: string, rule: 'money_precision' | 'money_invalid' | 'currency_invalid', field?: string);
+}
+/**
+ * Where the amount's currency comes from. `currencyField` names a field resolved
+ * from the INPUT ROOT, at any depth of the money field (`discount.amount_off`
+ * with `{ currencyField: 'currency_code' }` reads the top-level `currency_code`).
+ */
+type MoneyCurrency = {
+  currencyField: string;
+} | {
+  currency: 'store';
+};
+type MoneyOptions = MoneyCurrency & {
+  /** What the amount is; prepended to the unit sentence. */
+  describe?: string;
+  /** Strict lower bound (`0` = must be more than zero). Default: amounts are ≥ 0. */
+  exclusiveMinimum?: number;
+  /** Inclusive upper bound. */
+  max?: number;
+};
+/**
+ * A major-unit amount: finite, ≥ 0 (or > `exclusiveMinimum`), at most `max`,
+ * described with MONEY_UNIT_SENTENCE and marked `x-amboras-money` in JSON Schema.
+ *
+ * Chained checks (`.positive()`, `.max()`, `.int()`) and `.optional()`,
+ * `.nullable()`, `.nullish()` are safe: the kit's JSON Schema keeps the sentence
+ * and the marker. `.describe()` replaces the sentence, which `defineCapability`
+ * rejects: pass `describe` here instead.
+ */
+export declare function money(opts: MoneyOptions): z.ZodNumber;
+/** ISO 4217 minor-unit digits: 0 for JPY/KRW/VND…, 3 for KWD/BHD/OMR/TND/JOD/IQD/LYD, else 2 (also for unknown codes). */
+export declare function fractionDigits(currency: string): 0 | 2 | 3;
+/**
+ * Amboras storage rule: ×1000 for the seven three-decimal codes, ×100 for every
+ * other code INCLUDING zero-decimal ones (¥5 is stored as 500). By design; see
+ * Medusa `divisorFor`.
+ */
+export declare function storageScale(currency: string): 100 | 1000;
+/**
+ * Major → stored minor integer. Throws MoneyError (`invalid_input`) when the
+ * amount has more fraction digits than the currency allows (19.999 USD, 5.5 JPY),
+ * is not finite, or does not fit a safe integer. Pass `field` to name the input
+ * field in the error.
+ *
+ * An amount is accepted when its decimal text has at most the allowed digits
+ * (exact at any magnitude), or when it is within float noise of such an amount
+ * (0.1 + 0.2 → 0.30). Noise is bounded absolutely, so a real extra digit is never
+ * rounded away, however large the amount.
+ */
+export declare function toStorageAmount(major: number, currency: string, field?: string): number;
+/** Stored minor amount → major units. */
+export declare function fromStorageAmount(minor: number, currency: string): number;
+interface MoneyView {
+  amount: number;
+  currency: string;
+  display: string;
+}
+/** Output schema for a MoneyView (what `moneyView` returns), for capability outputs. */
+export declare const moneyViewSchema: z.ZodType<MoneyView>;
+/**
+ * A stored amount as the merchant reads it. Fraction digits are pinned (not left
+ * to the runtime's ICU data): ISO digits, widened only to show a stored value
+ * that is not a whole minor unit (¥5.5 stays visible).
+ */
+export declare function moneyView(minor: number, currency: string): MoneyView;
+//#endregion
+//#region src/policy.d.ts
+/** Phase 1 adapters pass observe/observe. */
+interface PolicyEnforcement {
+  role: 'enforce' | 'observe';
+  plan: 'enforce' | 'observe';
+}
+/** `observed` holds the rule ids an 'observe' check would have denied, for logging. */
+type PolicyDecision = {
+  allow: true;
+  observed: string[];
+} | {
+  allow: false;
+  error: CapabilityError;
+};
+export declare function evaluatePolicy(policy: CapabilityPolicy, ctx: CapabilityCallContext, facts: {
+  planFeatures?: string[];
+}, enforcement: PolicyEnforcement): PolicyDecision;
+/**
+ * True when the call needs an explicit confirmation before it runs. `records` is
+ * how many records it touches. A threshold policy with no count, or a count that
+ * is not a non-negative integer, requires confirmation (the adapter could not count).
+ */
+export declare function confirmationRequired(policy: Pick<CapabilityPolicy, 'confirm'>, records?: number): boolean;
+//#endregion
+export type { Actor, AnyCapabilityDefinition, Area, CapabilityAgentSpec, CapabilityCallContext, CapabilityDefinition, CapabilityErrorBody, CapabilityErrorCode, CapabilityErrorInit, CapabilityId, CapabilityManifest, CapabilityPolicy, FromZodErrorOptions, JsonSchema, ManifestEntry, MoneyCurrency, MoneyOptions, MoneyView, PolicyDecision, PolicyEnforcement, Role, Surface };