@lovrozagar/honey 0.7.2 → 1.0.0-rc.1

package/docs/meta-spec.md

@@ -1,555 +0,0 @@
-# `.metaSpec()` — declarative control over what reaches the OpenAPI document
-
-Status: implemented in `@lovrozagar/honey` (tree of record: `packages/core`).
-
-## 1. The problem
-
-Before this feature, `generateOpenApi` mapped route meta onto the operation object with a
-hardcoded allowlist of eight fields:
-
-<!-- snippet:skip -->
-
-```ts
-summary, description, tags, deprecated, operationId, security, invalidate → x-invalidate, mcp → x-mcp
-```
-
-Everything else on `.meta()` was **silently discarded**. That has three consequences:
-
-1. **Facts the framework already knows never leave the process.** An app that classifies every
-   route by rate-limit category, permission set, or tenancy carries those facts on route meta and
-   the document never sees them. Downstream consumers (SDK codegen, gateways, contract testers such
-   as [`oat`](https://github.com/lovrozagar/oat)) then re-derive them by heuristic, or don't run the
-   check at all.
-2. **Hiding is accidental, not deliberate.** Fields that _must not_ be published — a captcha
-   provider, a test-bypass surface, internal worker routing — were protected only because the
-   allowlist happened not to know about them. Nothing recorded the intent.
-3. **Rot is silent.** Adding a field to the app's meta type produced no signal anywhere. The
-   default outcome of growth was "dropped".
-
-`.metaSpec()` replaces the allowlist with a **declarative, total, per-document policy**.
-
-## 2. Public API
-
-```ts
-honey<Env>()
-	.meta<HoneyMeta<AppRouteMeta>>()
-	.metaSpec({
-		strict: "error",
-
-		meta: {
-			permissions: "x-permissions",
-			rateLimit: { key: "x-rate-limit", map: (v) => ({ category: v, rps: RPS[v] }) },
-			summary: { key: "summary" },
-			worker: false,
-			captcha: false,
-		},
-
-		schema: {
-			entity: {
-				from: ["output"],
-				search: "deep",
-				expand: (e) => ({
-					"x-entity": e.table,
-					"x-generated": e.generated,
-					"x-immutable": e.immutable,
-					"x-soft-delete": e.softDelete ? { field: e.softDelete } : undefined,
-				}),
-			},
-		},
-
-		profiles: {
-			// default-deny: a tag added tomorrow is absent here until someone opts it in
-			public: { include: ["x-entity", "x-query"] },
-		},
-	})
-```
-
-honey does not own the shape of `e` above. The descriptor is a contract between whatever stamps the
-schema (an ORM, a DTO layer) and the app's policy block; honey only carries it. Agree those field
-names once, on the publisher's side, before either end writes code against them.
-
-### 2.1 Entry forms
-
-A policy entry describes one **source key** (a meta key, or a key read off a schema) and what it
-contributes to the operation object.
-
-| Form                                     | Meaning                                                                                                      |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `false`                                  | **Hidden.** Never emitted, in any profile. Explicit and greppable.                                           |
-| `"x-foo"` / `"summary"`                  | **Verbatim.** The source value is written to that operation key unchanged.                                   |
-| `{ key, map?, schema?, on?, profiles? }` | **Single target.** `map` transforms the value; returning `undefined` omits it for that route.                |
-| `{ expand, schema?, on?, profiles? }`    | **Fan-out.** Returns a record of operation keys → values; `undefined` values and an `undefined` return omit. |
-
-Common options:
-
-- `on?: "http" | "ws" | "both"` — which operation kinds the entry applies to. Default `"both"`.
-- `profiles?: readonly string[]` — restrict the entry to named documents. Default: every profile.
-- `schema?: StandardSchemaLike` — validates the produced value (see §6).
-
-`map` / `expand` receive `(value, ctx)` where `ctx` is `{ method, path, meta, profile, source }`.
-
-### 2.2 Target keys
-
-An entry may target:
-
-- any **extension** key matching `x-*`, or
-- one of the **standard operation fields** honey allows a policy to set:
-  `summary`, `description`, `tags`, `deprecated`, `operationId`, `security`, `externalDocs`,
-  `servers`.
-
-`responses`, `parameters`, `requestBody` and `callbacks` are **reserved** — they are derived from
-schemas and error keys, and a policy that wrote them would produce a document that contradicts the
-route. Targeting them is a build error. Any other non-`x-` key is a build error too (it would be
-dropped by spec-conformant readers, which is the failure mode this feature exists to remove).
-
-### 2.3 Schema-derived facts
-
-The `schema` section is keyed by **the entry's own name**. `read` says which schema-metadata key it
-reads, defaulting to that name. Sources:
-
-```
-"output" | "input.json" | "input.search" | "input.form" | "input.headers" | "input.cookies"
-```
-
-`from` defaults to all of them, in that order; the first source that carries the key wins.
-`"output"` reads the JSON output schema of the lowest declared 2xx status.
-
-`search` decides how deeply to look:
-
-| `search`           | Behavior                                                                                                                                                                                            |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `"root"` (default) | the schema root, seeing through one level of `items` so a bare `array<Entity>` list output still finds the descriptor stamped on the item                                                           |
-| `"deep"`           | walks `properties`, `items` and composition members breadth-first (max depth 6) and takes the **shallowest** match — for envelope shapes like `{ articles: [Article], count, hasMore, nextCursor }` |
-
-A deep search that finds two _different_ values at the same depth is a build error
-(`AMBIGUOUS_SCHEMA_KEY`), not a guess. The same descriptor reached by several paths is fine.
-
-Reading is vendor-neutral: honey converts the schema to JSON Schema (it already does, for the
-request/response bodies) and reads app keys off the **root** of that JSON Schema. For Zod that is
-exactly what `.meta({ … })` produces, so an ORM that stamps a descriptor onto the schema it already
-uses to parse the request gets the extension for free — and the tag cannot drift from runtime
-behavior, because both read the same object.
-
-One schema key routinely fans out to several extensions, which is why `expand` exists.
-
-#### One reserved key carrying a union
-
-A publisher with more than one kind of fact does not want more than one collision surface, so the
-mature shape is a single reserved key holding a discriminated union with a version field —
-[comb](https://github.com/lovrozagar/comb) stamps `x-comb` with `{ v, kind: "entity" | "query", … }`.
-The two members arrive on _different schemas of the same operation_: the entity descriptor on the
-response, the query descriptor on the search input.
-
-`read` plus `match` expresses that. Several entries read one key and are told apart by the union's
-discriminant:
-
-<!-- snippet:skip -->
-
-```ts
-schema: {
-	entityFacts: {
-		read: "x-comb",
-		match: { kind: "entity" },
-		version: { max: 1 },
-		from: ["output"],
-		search: "deep",
-		expand: (e) => ({
-			"x-entity": e.name,
-			"x-identity": e.identity,
-			"x-soft-delete": e.softDelete ?? undefined,
-			"x-tenant-column": e.tenantColumn ?? undefined,
-		}),
-	},
-	queryFacts: {
-		read: "x-comb",
-		match: { kind: "query" },
-		version: { max: 1 },
-		from: ["input.search"],
-		expand: (q) => ({
-			"x-query": { filter: q.filterable, sort: q.sortable, maxLimit: q.maxLimit },
-			"x-searchable": q.searchable ?? undefined,
-		}),
-	},
-}
-```
-
-Resolution rules:
-
-- Sources are walked in `from` order. A descriptor that fails `match` **does not end the walk** —
-  an entity entry must be free to step past the query descriptor when both entries search every
-  source.
-- If no source yields a match but a descriptor _was_ found under `read`, that is a build error
-  (`DESCRIPTOR_MISMATCH`). A stamped fact nobody claimed is a misconfigured policy, not an absent
-  fact, and silently emitting nothing is how the gaps this feature exists to close came about.
-- `version` is checked **before** `match`, because a newer contract may have redefined the
-  discriminant itself. A descriptor newer than `max`, or carrying no integer version when a guard
-  is declared, fails the build (`UNSUPPORTED_VERSION`) rather than emitting a partly-understood tag.
-
-honey does not own the version number — it is the publisher's contract, and `max` is the app's
-statement of which contract its `expand` was written against. Bumping the publisher then becomes a
-build failure with a name, instead of tags that quietly change shape.
-
-The alternatives were an array of entries under one key, and per-source matches that each run
-`expand`. The array makes the policy value irregular (`entry | entry[]`) and leaves the two
-contributions unnamed, which costs diagnostics — `schema."x-comb"[0]` reads worse than
-`schema."entityFacts"`. Per-source matching would force one `expand` to handle every member of the
-union and to de-duplicate its own target keys, moving work into app code that the policy layer
-already does. Naming entries keeps one entry to one contribution, which is what the rest of the
-design assumes.
-
-> **Deliberate limit.** Deriving operation metadata from _schemas and table definitions_ is safe:
-> they are a separate, hand-reviewed layer, and a handler can still fail to honor them — which is
-> precisely the finding a contract tester should report. Deriving it from _observed handler
-> behavior_ is not safe: it makes the document a mirror of the implementation and the tester
-> self-confirming. honey has no record-from-runtime mode, and if one is ever added its output must
-> land in a committed, reviewable artifact rather than being regenerated at test time.
-
-### 2.4 Profiles (multi-document)
-
-<!-- snippet:skip -->
-
-```ts
-profiles: {
-  public:  { include: ["x-entity", "x-query"] },       // default-deny — preferred
-  partner: { include: ["x-entity", "x-query", "x-cost"] },
-  staging: { exclude: ["x-rate-limit"] },              // denylist — internal documents only
-}
-```
-
-- Profile filters operate on **emitted keys**, not source keys.
-- `include` is an allowlist of `x-*` keys (standard fields are always kept unless excluded);
-  `exclude` is a denylist; with both, `include` applies first. Both also filter `meta.extensions`,
-  so the escape hatch cannot route around a profile.
-- The implicit profile `"default"` filters nothing.
-
-**Use `include` for a public document.** `exclude` is a denylist: a tag introduced next month is
-published unless someone remembers to add it, and the failure mode is a leak. `include` is
-default-deny, which is the posture a security boundary wants — the same posture `false` already
-takes on individual keys. Reach for `exclude` only when the document is internal and the list of
-things to withhold is genuinely shorter than the list to publish.
-
-- A document selects a profile:
-
-<!-- snippet:skip -->
-
-```ts
-codegen: {
-  openApi: [
-    { path: "src/_gen/openapi.internal.json", title: "…", version: "1.0.0" },
-    { path: "src/_gen/openapi.public.json",   title: "…", version: "1.0.0", profile: "public" },
-  ],
-}
-```
-
-`generateOpenApi(app, { …, profile: "public" })` is the programmatic form.
-
-**Why document-level filtering rather than per-entry visibility as the primary model:** the
-question a reviewer asks is "what is in the public document?" — that must be answerable by reading
-one block, not by grepping forty entries for a visibility flag. Per-entry `profiles` remains
-available for the inverse case ("this entry exists only for the internal document"), and `false`
-covers "never, anywhere".
-
-### 2.5 Escape hatch
-
-`OpenApiMeta` now carries:
-
-<!-- snippet:skip -->
-
-```ts
-extensions?: Record<`x-${string}`, unknown>
-```
-
-emitted verbatim, at the highest precedence, and still subject to profile filtering. Runtime
-enforces the same contract the type states: only `x-*` keys are accepted, and anything else is an
-`UNKNOWN_FIELD` build error. Because passthrough outranks every policy entry and is untyped inside
-a `.meta()` call, letting it reach a standard field would let a stray key silently replace a
-route's own `summary`. It exists so a
-consumer that gains a tag before honey's policy is updated is not blocked. It is deliberately
-secondary: raw passthrough spreads stringly-typed keys across call sites, has no public/private
-separation, and fails on nothing.
-
-## 2.6 Middleware-contributed meta
-
-A fact enforced by middleware should not be retyped on every route it protects. Middleware can
-contribute meta to every route that mounts it:
-
-<!-- snippet:skip -->
-
-```ts
-export const shard = createMiddleware(fn, { meta: { tenant: "project_id" } })
-// or: defineMiddleware({ fn, errors: […], meta: { tenant: "project_id" } })
-
-app.use(shard)                    // every route on the chain
-app.use("/orgs", shard)           // every route under a prefix
-app.get("/x").use(shard).handler(…)  // one route
-```
-
-One line, every route the middleware covers, and the tag cannot disagree with the code that
-enforces it — a hand-written `tenant` on 104 routes can, and a wrong one is worse than a missing
-one, because it makes a consumer confident about the wrong parameter.
-
-Rules:
-
-- **Explicit always wins.** Chain `.meta()` and route `.meta()` both outrank a contributed value.
-  Among middleware, the one that runs later wins: chain, then scoped, then route level.
-- **Contributed meta is real meta.** It lands in the route's `mt`, so it appears on `ctx.meta`, in
-  the manifest, and — critically — it is subject to the policy. A middleware cannot smuggle an
-  untagged fact into the document: with `strict: "error"`, contributing `sla` with no policy entry
-  fails the build exactly as writing it on a route would.
-- **A scoped middleware registered after its routes still reaches them.** Meta is resolved from
-  the chain each route runs when the app finalizes, so registration order does not matter, and a
-  route mounted with `.route(sub)` gets the meta of the chain it is mounted on. A tag missing where
-  enforcement happens is the failure direction that matters.
-- **`internal` may not be contributed.** It controls whether a route appears in generated artifacts
-  at all; a middleware that removed 104 routes from the document would be invisible in both the
-  route and the middleware. `createMiddleware` throws.
-
-### Why it is resolved at finalize, not per request
-
-Contributed meta is collected once, when the app finalizes (first request, `toRouteTree()` or
-codegen), from the same resolved chain the route runs — so the request path, `ctx.meta`, the
-manifest and the document cannot disagree, with or without a loaded route tree. A lazily-derived
-value per request would make the served meta depend on timing. The generated `routes.gen.ts` carries
-the meta of the generating build; change what a middleware contributes, then regenerate.
-
-### Two things to put in a release note
-
-- **Adding a middleware can break a build.** Contributed meta is subject to totality, so mounting a
-  middleware that contributes `tenant` fails the build of any app whose policy has no `tenant`
-  entry — an app that never touched its own meta type. That is the correct trade (explicit beats
-  silent) but it is a surprising blast radius for what looks like a local change.
-- The tap interaction below.
-
-### One runtime interaction to know about
-
-Meta-driven taps fire for every registered tap key found on a route's meta. A middleware
-contributing `tenant` will therefore start firing an `app.tap("tenant", …)` handler on every route
-it covers. That is coherent — "run this for every tenant-scoped route" is what meta-driven taps are
-for — but it is a behavior change triggered from a distance, so it is worth grepping for tap keys
-that collide with meta keys a middleware contributes.
-
-## 2.7 `undefined` omits, `null` is emitted
-
-`map` returning `undefined`, an `undefined` value inside an `expand` record, and a source key absent
-from meta all mean **omit**. `null` is a value and is **emitted verbatim**.
-
-The difference is load-bearing whenever a publisher stamps facts it cannot always know. A schema
-stamped with `searchable: null` or `tenantColumn: null` means _"I don't know"_, but passing that
-straight through publishes `"x-searchable": null`, which a consumer reads as _"nothing is
-searchable"_ — a confident wrong answer, worse than silence. Normalize in the policy:
-
-<!-- snippet:skip -->
-
-```ts
-expand: (e) => ({
-	"x-entity": e.table,
-	"x-searchable": e.searchable ?? undefined, // unknown → key absent
-	"x-tenant": e.tenantColumn ? { column: e.tenantColumn } : undefined,
-})
-```
-
-honey does not collapse `null` to omitted for you, because "explicitly nothing" is a legitimate
-statement that some consumers want (`"x-soft-delete": null` = _this entity definitively has no soft
-delete_, as distinct from _unknown_). The framework carries what the policy produces; deciding which
-of the two you mean is the policy's job.
-
-This composes with precedence rather than fighting it. A publisher that stamps nothing for a fact
-only the routing layer knows leaves the key absent at rank 1; a route-meta or middleware-contributed
-value at rank 2 fills it wherever it exists, and where it does not, the key is simply missing —
-which is the honest answer.
-
-## 3. Precedence and merge rules
-
-Contributions are collected per operation and resolved by **rank**, highest wins:
-
-| Rank | Source                                                                         |
-| ---- | ------------------------------------------------------------------------------ |
-| 3    | `meta.extensions` passthrough                                                  |
-| 2    | route meta entries — `spec.meta` **and** the built-in default policy, one tier |
-| 1    | schema-derived entries (`spec.schema`)                                         |
-
-Rules, stated once:
-
-1. **Route meta beats schema-derived.** The built-in mappings are route meta too, so a route's
-   `summary` is never overwritten by a schema-derived entry. An app entry for a built-in key
-   replaces that built-in outright (same source key, so no clash).
-2. **Chain meta vs route meta is unchanged**: `.meta()` on a chain is merged into each route's meta
-   at registration; route meta wins. The policy layer sees the already-merged object.
-3. **Two entries of the same rank writing the same operation key is a build error**
-   (`DUPLICATE_TARGET`). Within-rank shadowing is always a mistake, never a feature.
-4. **Key order in the emitted document is the order of first contribution**: built-ins, then app
-   meta, then schema-derived, then `extensions`. Precedence is resolved independently of write
-   order, so a higher-ranked contribution overwrites a value in place and never reorders the JSON.
-5. **Aliasing a standard field from a second meta key requires hiding the built-in.**
-   `blurb: { key: "summary" }` alongside the built-in `summary` entry is a `DUPLICATE_TARGET` error;
-   write `summary: false` to say which one owns the field.
-6. `undefined` from `map`, an `undefined` value inside an `expand` record, and a source key absent
-   from meta all mean _omit_, silently. This is the sanctioned way to write a conditional entry.
-
-## 4. Totality
-
-**A key of the app's meta type with no policy entry is an error, not a silent drop.** This single
-rule is what stops the rot: adding a field to the meta type forces an emit-or-hide decision.
-
-Enforced at two levels:
-
-- **Type level.** The `meta` section is a mapped type over the app's meta type with `-?`, minus the
-  built-in `DefaultMeta` keys (which ship with default entries and may be _optionally_ overridden).
-  Omitting an app key is a TypeScript error at the `.metaSpec()` call site.
-- **Codegen level.** Any key observed on a route's meta with no entry is reported per `strict`.
-  This catches JavaScript consumers, dynamically-assigned meta, and meta from mounted sub-apps whose
-  types were erased.
-
-`strict` values: `"error"` (default when a `metaSpec` is declared), `"warn"`, `"off"`.
-
-**Known limit:** a _misspelled_ policy key is not rejected at the call site. `.metaSpec()` takes a
-generic `TSpec extends HoneyMetaSpec<TMeta>` — required to keep `Honey` from becoming invariant in
-`TMeta`, which would break assignability across the whole builder — and TypeScript does not
-excess-property-check a literal inferred as a generic. The typo is still caught, from the other
-side: the real key it was meant to name now has no entry, so `MISSING_ENTRY` fires for it. The
-misspelled entry itself is inert.
-
-Apps that never call `.metaSpec()` run with `strict: "off"` and the built-in policy only — see §7.
-
-## 5. Error taxonomy
-
-All diagnostics are collected across the whole document and thrown as one aggregated
-`Error` (first 20 listed, with a count), because failing on the first of 250 operations makes
-migration miserable.
-
-| Code                    | Level                                    | When                                                                                | Why this level                                                                       |
-| ----------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `MISSING_ENTRY`         | error (`strict:"error"`) / warn / silent | a meta key on some route has no policy entry                                        | the rot-stopper; downgradable during migration                                       |
-| `RESERVED_FIELD`        | error                                    | entry targets `responses` / `parameters` / `requestBody` / `callbacks`              | would contradict schema-derived content                                              |
-| `UNKNOWN_FIELD`         | error                                    | entry targets a non-`x-`, non-allowlisted field                                     | silently ignored by readers                                                          |
-| `DUPLICATE_TARGET`      | error                                    | two same-rank entries write one key                                                 | ambiguous, order-dependent output                                                    |
-| `INVALID_VALUE`         | error                                    | entry `schema` rejects the produced value                                           | a malformed tag is indistinguishable from a missing one downstream                   |
-| `ASYNC_VALIDATION`      | error                                    | entry `schema` validates asynchronously                                             | codegen value resolution is synchronous                                              |
-| `MAP_THREW`             | error                                    | `map` / `expand` threw                                                              | policy bugs must not produce a half-populated document                               |
-| `UNKNOWN_PROFILE`       | error                                    | a document requests a profile that is not declared                                  | almost always a typo that would silently emit everything                             |
-| `AMBIGUOUS_SCHEMA_KEY`  | error                                    | a `search: "deep"` entry matched two different values at one depth                  | guessing which entity a route serves is how a tester gets told the wrong thing       |
-| `DESCRIPTOR_MISMATCH`   | error                                    | a descriptor was found under `read` but satisfied no entry's `match`                | a stamped fact nobody claimed is a misconfigured policy, not an absent fact          |
-| `UNSUPPORTED_VERSION`   | error                                    | a descriptor is newer than the entry's `version.max`, or carries no integer version | a partly-understood tag is worse than none — the consumer cannot tell it is partial  |
-| `SUBAPP_ENTRY_CONFLICT` | warn                                     | a mounted sub-app's policy entry disagrees with this app's                          | silently dropping the sub's entry is how two documents drift without anyone noticing |
-| omitted value           | silent                                   | `map` returned `undefined`, or the meta key is absent                               | the sanctioned conditional                                                           |
-
-Every message carries `method`, `path`, source key and target key.
-
-## 6. Validating what is emitted
-
-<!-- snippet:skip -->
-
-```ts
-rateLimit: {
-  key: "x-rate-limit",
-  map: (v) => ({ category: v, rps: RPS[v] }),
-  schema: z.object({ category: z.string(), rps: z.number().int().positive() }),
-}
-```
-
-The schema validates the **produced** value (for `expand`, the produced record). It runs at codegen
-time only, synchronously, through Standard Schema — so any of honey's supported validators works.
-A failure is a build error, not a warning: shipping a tag that a consumer silently ignores is
-worse than not shipping it, because it looks like coverage.
-
-## 7. Default policy and the compatibility argument
-
-When an app declares no `metaSpec`, codegen runs the **built-in policy**, which is the previous
-eight mappings, unchanged, with the same truthiness gates and the same emit order:
-
-| Meta key      | Target                       | Gate             | HTTP | WS  |
-| ------------- | ---------------------------- | ---------------- | ---- | --- |
-| `summary`     | `summary`                    | truthy           | ✓    | ✓   |
-| `description` | `description`                | truthy           | ✓    | ✓   |
-| `tags`        | `tags` (string → `[string]`) | truthy           | ✓    | ✓   |
-| `deprecated`  | `deprecated`                 | truthy           | ✓    | —   |
-| `operationId` | `operationId`                | truthy           | ✓    | ✓   |
-| `security`    | `security` (normalized)      | truthy           | ✓    | —   |
-| `invalidate`  | `x-invalidate`               | array, non-empty | ✓    | —   |
-| `mcp`         | `x-mcp`                      | `=== true`       | ✓    | —   |
-| `internal`    | _route left out_             | `=== true`       | —    | —   |
-| `extensions`  | verbatim passthrough         | —                | ✓    | ✓   |
-
-A route with `internal: true` is left out of the served and generated OpenAPI document and the
-served `/manifest.json`; it still serves requests and still appears in `types.gen.d.ts`, so
-services can type against it. `security` must be a scheme name, a list of names, a list of name
-groups, or standard requirement objects — anything else fails generation instead of documenting the
-route as public — and every scheme it names must be in `securitySchemes`. `invalidate` selectors
-must name a registered route (`"GET /users/:id"`); a selector that names nothing fails generation
-unless the document is generated with `invalidate: "off"`.
-
-The WS column reproduces the previous WS mapping exactly (it was a strict subset). App entries
-default to `on: "both"`; the asymmetry is preserved only for the built-ins.
-
-Because the built-ins are compiled first and written first, and because precedence is resolved
-independently of write order, **a no-policy app produces a byte-identical document**. There is a
-test that asserts exactly this against the pre-change generator output.
-
-## 8. Migration path (≈250 operations, 9-field meta type)
-
-Mechanical, and reversible at every step.
-
-1. **Add `.metaSpec({ strict: "warn", meta: {} })`.** Generate. Every dropped key is now listed,
-   once, with the routes that carry it. Nothing about the document changed.
-2. **Triage the list into three buckets**: emit verbatim, emit transformed, hide. Write the entries.
-   `false` for anything internal — `worker`, `captcha`, `proxyTimeout` — so the intent is recorded
-   rather than implied.
-3. **Add the public profile** with `exclude` for the tags that must not be published, and add the
-   second `codegen.openApi` entry. Diff the two documents; the diff _is_ the review.
-4. **Flip `strict` to `"error"`.** The mapped type now also fails the typecheck if a tenth meta
-   field appears without a decision.
-5. **Move ORM-derived facts to the `schema` section** last, once the meta-driven tags are stable.
-   This is the step that removes per-route annotation: the descriptor the ORM already stamps on the
-   schema fans out to `x-entity` / `x-generated` / `x-immutable` / `x-soft-delete` with no route
-   edits at all.
-
-Steps 1–2 are per-meta-key (nine edits). Step 5 is per-entity, not per-route.
-
-## 9. Trade-offs rejected
-
-- **Flat spec object (`.metaSpec({ permissions: "x-permissions" })`) as the only form.** Reads well
-  until profiles, schema sources and `strict` need a home, and then every one of them collides with
-  a possible meta key name. Sections cost one nesting level and buy an unambiguous namespace.
-- **Per-entry visibility (`visible: ["internal"]`) as the primary profile model.** Rejected as the
-  primary: it distributes the answer to "what does the public document contain" across the whole
-  policy. Kept as a secondary `profiles` option on entries.
-- **Post-hoc stripping only** (the existing `sanitize.stripXExtensions`). It works, but it is a
-  denylist applied after the fact: a tag added later is published by default, and the failure mode
-  is a leak. Kept for spec-level surgery; not the mechanism for public/private separation.
-- **A honey-side vocabulary of blessed tags** (`x-entity`, `x-tenant`, …). Rejected outright:
-  binding a framework to one consumer's tag set is how vendor lock-in starts. honey controls
-  _emission_; the vocabulary is the app's.
-- **Deriving policy from a config file rather than the app builder.** The policy must be typed
-  against the app's meta type, which only exists in the app's own module graph.
-- **Runtime enforcement.** Everything here is codegen-time. `.metaSpec()` stores one object on the
-  route graph and is never consulted on a request.
-
-## 10. Composition
-
-`.metaSpec()` is app-global: one policy object on the route graph. Mounting a sub-app merges that
-object into the parent. Each app's _own_ document still uses only that app's policy — the merge
-writes the parent, never the sub — so a worker that hides a field keeps hiding it in the document
-it generates itself, regardless of what it is later mounted into.
-
-In the **aggregate** document the parent wins on conflict, with one exception. A sub-app entry of
-`false` hides the key in the aggregate too. Hiding is a safety claim: a worker that declares a
-field unpublishable must not have the gateway publish it. Wrongly hidden is a visible gap; wrongly
-published is a leak.
-
-Every other disagreement — two different target keys, two different `map` functions, two different
-schema or profile entries — keeps the parent's entry and reports `SUBAPP_ENTRY_CONFLICT` at
-codegen. The sub-app's own document is unaffected. Identical entries (the common case: five
-workers and a gateway importing one policy from a shared package) are not a conflict.
-
-There is no per-mount override and no way for a worker to _widen_ a gateway entry. If that is the
-shape you want, generate the worker's document from the worker, not from the gateway.
-
-## 11. Open questions
-
-- **Profile inheritance.** Profiles are flat. If real apps grow four or five documents, `extends`
-  will be wanted.
-- **Fan-out from a schema key into `parameters`.** `x-query` describes sortable/filterable columns
-  and duplicates information that could, in principle, be emitted as real query parameters. Both are
-  useful to different consumers; honey emits the extension and leaves parameters to the schema.
-- **Component-level policy.** Nothing yet maps schema meta onto `components.schemas` entries, only
-  onto operations.

package/docs/packaging.md

@@ -1,104 +0,0 @@
-# Packaging — why honey ships source, declarations and JavaScript
-
-## The problem
-
-honey shipped raw TypeScript: `"files": ["docs", "src"]`, and every `exports` subpath pointed at
-`./src/*.ts`. That is pleasant for us and hostile to a consumer, because **a package that ships
-`.ts` inherits the consumer's compiler flags**. There is no per-directory suppression for `.ts`
-under `node_modules`, and `skipLibCheck` does not help — it covers `.d.ts` only.
-
-Measured against the real published tarball, from a fixture with every plausible strictness flag on:
-
-```
-522 diagnostics originate inside @lovrozagar/honey
-
-    358  TS4111   Property 'x' comes from an index signature, must be accessed with ['x']
-     81  TS5097   An import path can only end with '.ts' when allowImportingTsExtensions is enabled
-     27  TS18048  'x' is possibly 'undefined'
-     22  TS2379   argument not assignable under exactOptionalPropertyTypes
-      …
-```
-
-A downstream app reported 482 under its own flag set. Same wall, different height.
-
-## Why "just fix the source" was not enough
-
-The obvious answer is to make our source satisfy those flags — `@lovrozagar/comb` ships raw `src`
-and produces zero errors in the same app, so it is demonstrably possible. Two things ruled it out:
-
-1. **TS5097 is not a style problem.** 81 of the diagnostics say the consumer must enable
-   `allowImportingTsExtensions`, which in turn requires `noEmit` or `emitDeclarationOnly` — we would
-   be dictating a consumer's build configuration. No amount of tidying our own source removes that;
-   it is inherent to importing `.ts` paths with extensions.
-2. **The flag set is unbounded.** Fixing 522 errors buys immunity to _today's_ flags. Tomorrow a
-   consumer enables something that does not exist yet, and we are back here. `skipLibCheck` over
-   `.d.ts` is a real, permanent boundary; matching an open set of lint flags is a treadmill.
-
-## What we do instead
-
-Ship source, declarations _and_ compiled JavaScript, and split the conditions:
-
-```json
-"exports": {
-	".": {
-		"honey-source": "./src/index.ts",
-		"types": "./dist/index.d.ts",
-		"bun": "./src/index.ts",
-		"default": "./dist/index.js"
-	}
-}
-```
-
-- **TypeScript** resolves `types` → generated `.d.ts`, which `skipLibCheck` covers. The consumer
-  never type-checks our source, so our lint posture is ours alone.
-- **Node, Deno, Workers bundlers and Vite** resolve `default` → `./dist/*.js`. Node refuses to strip
-  types from `.ts` files under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so
-  a package whose runtime entry is `.ts` cannot be imported on plain Node at all — not the core
-  entry, not the Vite plugin, not the CLI. Shipping only source made the package Bun-only in
-  practice while the README promised Node.
-- **Bun** resolves `bun` → `./src/*.ts`. It runs TypeScript natively, and the `honey` bin
-  (`bin/honey.js`) does the same split: Bun runs `src/cli.ts`, every other runtime `dist/cli.js`. In a
-  repository checkout (marked by `tsconfig.json`, which is not published) Node also runs the source,
-  through jiti, so `honey generate` never runs a stale `dist/`.
-- **`honey-source`** is this repository's own condition. Every tool here resolves it first —
-  `customConditions` in the tsconfigs, `resolve.conditions` in the vitest configs,
-  `--conditions=honey-source` for Node and Deno, `WRANGLER_BUILD_CONDITIONS` for wrangler — so
-  development and tests always run the source and never a stale `dist/`. A consumer never sets it.
-- **`declarationMap` and `sourceMap` are emitted and `src` still ships**, so go-to-definition and
-  stack traces land in real source.
-
-`bun run build` (`scripts/build.ts`) compiles `src` with `tsconfig.build.json` and copies the
-non-TypeScript assets codegen reads at run time (the Go, Python and Rust SDK runtimes, the Go CLI
-and MCP templates). `prepack` runs it; npm runs `prepack` for both `npm pack` and `npm publish`, so
-a tarball cannot ship with a stale or missing `dist`. The build tier (`bun run test:build`) also
-builds first, because its bundles resolve honey the way a consumer's do.
-
-## The trade-off, stated
-
-We pay: a build step, the compiled output and declarations in the tarball, and one more artifact that
-must stay in sync (it is generated, so it does — but it is a step that can be forgotten, which is why
-it hangs off `prepack` rather than a human).
-
-We keep: source shipping for Bun and for debugging.
-
-We buy: consumers are decoupled from our compiler flags, and the package runs on every runtime the
-README names.
-
-**This generalizes.** Any package of ours that ships source has the same exposure. The rule: ship
-compiled JavaScript for the runtime condition, declarations for the `types` condition, source for
-Bun and debugging, and gate it with a packaging test that runs on plain Node.
-
-## The regression test
-
-`bun run test:packaging` (`e2e/run-strict-consumer.ts`) packs the tarball exactly as npm would,
-installs it into a throwaway consumer, type-checks against `e2e/strict-consumer/` — a fixture with
-`strict`, `exactOptionalPropertyTypes`, `noPropertyAccessFromIndexSignature`,
-`noUncheckedIndexedAccess`, `verbatimModuleSyntax` and friends — and fails on any diagnostic whose
-path is inside the package.
-
-It then runs the installed package: on Bun, and on plain Node — the core entry, `honey generate`
-against a Vite config, and `vite build` with `honey()` and `createBuildPlugin`, whose output must
-serve `/health`. No tsx, no type stripping.
-
-It runs as its own CI job, on Node 22 and the current Node. Every other tier runs honey from source,
-so this is the only place the consumer's view is visible at all.