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

package/README.md

@@ -1,3 +1,159 @@
-# Temporary Holding Version
+# `@amboras-dev/capability-kit`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The capability contract shared by Medusa (which defines and runs capabilities)
+and the orchestrator (which exposes them as AI tools). One definition per
+merchant action: id, zod input/output, policy and agent text. The kit checks it
+once, converts money at one boundary, answers errors in one shape and emits a
+hashed manifest the other repo re-checks on load. CommonJS + ESM + types; Node >= 20 and
+browsers. One runtime dependency, `@amboras-dev/money` (the storage rule, conversion
+and money view; the kit pins its exact version), and the `zod` peer (`^3.25.76 || ^4.0.0`,
+imported only as `zod/v4`; zod 3.25.0 ships without `dist/` and cannot load `zod/v4`).
+
+```ts
+import { defineCapability, money, toStorageAmount, moneyView, emitManifest, parseManifest } from '@amboras-dev/capability-kit'
+import { z } from 'zod/v4'
+
+export const createPromotion = defineCapability({
+  id: 'promotions.create',
+  version: 1,
+  owner: 'medusa',
+  http: { method: 'POST', path: '/admin/capabilities/promotions.create', runsOn: 'custom' },
+  input: z.object({
+    code: z.string(),
+    currency_code: z.string().length(3),
+    amount_off: money({ currencyField: 'currency_code' }),
+    min_subtotal: money({ currencyField: 'currency_code', describe: 'Minimum cart subtotal.' }).optional(),
+  }),
+  output: z.object({ id: z.string(), summary: z.string() }),
+  run: async (ctx, input) => { /* toStorageAmount(input.amount_off, input.currency_code) … */ },
+  policy: { minRole: 'manager', effect: 'write', idempotent: false, money: true, confirm: 'never' },
+  agent: { description: 'Create a discount code …', exposure: 'task-tool', toolName: 'create_promotion' },
+})
+
+toStorageAmount(19.99, 'USD')  // 1999
+toStorageAmount(5, 'JPY')      // 500   (×100 storage for zero-decimal codes too)
+toStorageAmount(1.5, 'KWD')    // 1500  (×1000 for the seven three-decimal codes)
+toStorageAmount(5.5, 'JPY')    // throws MoneyError: more than 0 decimal places
+moneyView(1999, 'USD')         // { amount: 19.99, currency: 'USD', display: '$19.99' }
+
+const manifest = emitManifest([createPromotion], 'medusa')   // deterministic, hashed
+parseManifest(JSON.parse(text))                               // shape + hash check, throws on mismatch
+```
+
+## API
+
+| Area | Exports |
+|---|---|
+| ids | `AREAS`, `Area`, `CapabilityId`, `Role`, `ROLE_RANK`, `isCapabilityId`, `areaOf` |
+| context | `Actor`, `Surface`, `CapabilityCallContext` (filled by adapters, never from input) |
+| definition | `defineCapability`, `CapabilityDefinition`, `CapabilityPolicy`, `CapabilityAgentSpec`, `CapabilityDefinitionError` |
+| money | `money`, `MoneyOptions`, `moneyViewSchema`, `fractionDigits`, `storageScale`, `toStorageAmount`, `fromStorageAmount`, `moneyView`, `MoneyView`, `MoneyError`, `MONEY_UNIT_SENTENCE`, `MONEY_META_KEY` |
+| errors | `CapabilityError`, `CapabilityErrorBody` (with optional `details`), `CapabilityErrorCode`, `httpStatusFor`, `fromZodError`, `FromZodErrorOptions` |
+| policy | `evaluatePolicy`, `PolicyEnforcement`, `PolicyDecision`, `confirmationRequired` |
+| idempotency | `IDEMPOTENCY_KEY_PATTERN`, `requestFingerprint`, `requiresIdempotencyKey` |
+| manifest | `emitManifest`, `parseManifest`, `canonicalJson`, `CapabilityManifest`, `ManifestEntry`, `AnyCapabilityDefinition`, `JsonSchema`, `omitFields`, `CapabilityManifestError` |
+
+`defineCapability` throws at boot on:
+- a bad id or unknown area, or a version that is not a positive integer;
+- an input that is not an object schema, that accepts undeclared keys
+  (`z.record` with open keys, `z.looseObject`, `.passthrough()`), or that has a
+  field accepting any value (`z.any()`, `z.unknown()`);
+- an input field that carries a store, tenant, profile, environment, shop or
+  merchant id at any depth (records, unions, intersections, arrays and tuples
+  included; any case or separator: `storeId`, `store-id`, `env_id`, `store: { id }`);
+- `runsOn: 'custom'` without `run`; `hideFields` naming a missing or required field;
+- a schema JSON Schema cannot express (`z.date()`, `z.bigint()`, `z.custom()`);
+- a `money()` field whose unit sentence was replaced, or whose `currencyField`
+  is not a string field at the input root;
+- an invalid `minRole`, confirm threshold, rate limit or `toolName`.
+
+`emitManifest` runs the same checks again on every definition, and
+`parseManifest` runs the JSON-level ones on every received entry.
+
+`evaluatePolicy` checks tenant → role → plan. A missing tenant always denies.
+Members need `ROLE_RANK[role] >= ROLE_RANK[minRole]`; a `null` role denies;
+internal actors pass the role check. A `planFeature` with no plan facts denies
+as retryable `unavailable` (fail closed). In `observe` mode role and plan never
+deny; their rule ids come back in `observed`. An enforcement mode that is not
+exactly `'enforce'` or `'observe'` denies (`internal`, rule `policy_mode_invalid`).
+`confirmationRequired` requires confirmation when a threshold policy gets no
+count, or a count that is not a non-negative integer.
+
+## Decisions
+
+- **Major units at every boundary.** `money()` is the only money field type; its
+  description is the one unit sentence. Storage is Medusa's: ×1000 for KWD, BHD,
+  OMR, TND, JOD, IQD, LYD and ×100 for everything else, zero-decimal codes
+  included. The rule has one owner, `@amboras-dev/money`: `storageScale`,
+  `fractionDigits`, `toStorageAmount`, `fromStorageAmount` and `moneyView` are thin
+  wrappers over its `storageScale`, `storageDigits`, `fromMajor`, `toMajorNumber` and
+  `/ai` `moneyView`. Codes are validated by the package's `currencyCode`: an unknown
+  code (`ZZZ`) throws `currency_invalid`; retired codes (BGN) still read. A stored
+  amount must be a safe integer.
+- **Excess decimals throw, float noise rounds.** `19.99 × 100 = 1998.999…` stores
+  1999 and `0.1 + 0.2` stores 30; `19.999 USD` and `5.5 JPY` throw. The digit
+  check reads the number's decimal text, so it holds at any magnitude; amounts
+  above 2^46 units of the currency's precision (USD 703 billion) refuse as too large.
+- **`MoneyError` is an `invalid_input` `CapabilityError`** (rules `money_precision`,
+  `money_invalid`, `currency_invalid`), mapped from the package's `MoneyError` codes
+  (`precision` → `money_precision`; `amount_invalid`, `overflow` → `money_invalid`;
+  `currency_invalid` → `currency_invalid`). `toStorageAmount(major, currency, field)`
+  names the field, so an adapter answers 400 with it. A bad `money()` option is
+  a `CapabilityDefinitionError` (boot).
+- **Display digits are pinned**, not read from the runtime's ICU data (HUF/IDR
+  differ between Node images). `moneyView` shows the currency's display digits from
+  the package registry, widened to keep a finer stored value: HUF 435000 is
+  `HUF 4,350` (was `HUF 4,350.00`), HUF 435050 `HUF 4,350.5`, IQD 1500 `IQD 1.5`
+  (was `IQD 1.500`); `amount` is always exact.
+- **Chaining on `money()` is safe; `.describe()` is not.** `money()` adds a
+  no-op refinement as a brand. zod copies checks into every clone, so the brand
+  survives `.positive()`, `.max()`, `.int()`, `.optional()`, `.nullish()`, even
+  on zod 3.25 and 4.0–4.2, where the metadata itself is dropped. The kit's JSON
+  Schema emission puts the marker (and the sentence, when it went missing) back
+  on every branded node. `.describe()` or `.meta({ description })` REPLACES the
+  sentence; `defineCapability` rejects that: pass `money({ ..., describe })`.
+  Bounds can also go in the options: `money({ currencyField, exclusiveMinimum: 0, max })`.
+- **`currencyField` is resolved from the input root**, wherever the money field
+  sits: `discount.amount_off` with `{ currencyField: 'currency_code' }` reads the
+  top-level `currency_code` (a dotted path reaches a nested one).
+  `defineCapability` rejects a `currencyField` that does not resolve.
+- **Outputs echo `moneyViewSchema`** (`{ amount, currency, display }`), built with
+  `moneyView` from the stored row.
+- **`details`** on an error body holds small flat facts the caller can act on
+  (`duplicate_code` → `{ existing_id, existing_status }`); never secrets or PII.
+- **Removed field names steer**: `fromZodError(err, { renamed: { value: 'percent_off
+  or amount_off (major units)' } })` turns a strict object's unrecognized `value`
+  into `"value" was removed: use percent_off or amount_off (major units).`, rule
+  `field_renamed`, field = its dotted path.
+- **Pure SHA-256**, not `node:crypto` or Web Crypto: the package stays
+  `platform: neutral` and synchronous, so the Next.js admin can call
+  `parseManifest` in the browser. Cross-checked against `node:crypto` in tests.
+- **Manifest hash is over the emitted JSON.** zod lines emit different JSON
+  Schema for the same definition (3.25 and 4.0 write a discriminated union as
+  `anyOf`, 4.3 as `oneOf`), so a hash is only comparable between emits on the same
+  zod version. Consumers verify a received manifest with `parseManifest`, which
+  hashes the JSON as received; they never re-emit it to compare. Entries parse as
+  loose objects, so a field added by a newer kit passes through and stays covered
+  by the hash. The hash proves integrity, not origin: trust comes from reading the
+  committed file.
+- **zod 3.25 and 4.x.** The suite runs three times: on zod 4.3.6, on zod 4.0.0
+  (`vitest.zod40.config.ts`) and on zod 3.25.76's `zod/v4`
+  (`vitest.zod3.config.ts`); types are checked against all three. A manifest
+  emitted on 3.25 (`test-fixtures/manifest.zod-3.25.json`) parses on every line,
+  and each line's hash is pinned. zod 3.25's
+  `zod/v4` keeps its metadata registry per module copy (4.x shares it on
+  `globalThis`), so a consumer must load the kit and zod in the same module format.
+  Medusa (CommonJS) and the admin bundle (ESM) both do.
+- **Error rules from zod refinements**: `.refine(fn, { params: { rule: 'x' } })`
+  becomes `body.rule = 'x'` in `fromZodError`. A renamed-field issue leads the
+  headline. A plain union reports its closest branch with full paths instead of
+  "Invalid input".
+
+## Testing
+
+```bash
+pnpm test        # vitest + 100% coverage on zod 4.3.6, then the same suite on 3.25.76 and 4.0.0
+pnpm typecheck   # src (no Node types), tests, and src+tests against zod 3.25 and 4.0 types
+# regenerate the 3.25 manifest fixture after a deliberate change:
+UPDATE_FIXTURES=1 npx vitest run --config vitest.zod3.config.ts src/manifest-cross-zod.test.ts
+```