tshex-cli 1.0.26 → 1.0.28

package/docs/shared/application/http/json-web-token.md

@@ -0,0 +1,209 @@
+### JSON Web Tokens
+
+`json-web-token.ts` declares a type-only implementation of the JOSE and JWT
+family of RFCs (JWS, JWE, JWK, JWT, and related extensions such as DPoP and
+selective disclosure). It lets an adapter describe tokens and keys precisely
+without depending on a specific JOSE library's own types.
+
+This module has no runtime implementation. Pair it with a concrete JOSE
+library (for signing, encryption, or verification) and use these types to
+annotate its inputs and outputs.
+
+#### Branded Wire Values
+
+Wire-format primitives are branded so a plain `string` cannot be passed where
+an encoded value is expected: `Base64Url`, `Base64`, `NumericDate`,
+`StringOrURI`, `UriString`, `MediaType`, and `KeyId`. `BinaryData` is the
+union `ArrayBuffer | Uint8Array` used wherever a JOSE library accepts raw
+bytes.
+
+#### JSON Web Keys
+
+Every JWK shares `JwkCommonParameters` (`kty`, `use`, `key_ops`, `alg`, `kid`,
+the `x5*` certificate members, and the OpenID Federation `iat`/`nbf`/`exp`/
+`revoked` members). `JwkKeyType` (`kty`) then selects one of five key-family
+options, each with a public and a private variant where the family supports
+one:
+
+| `kty` | Curve/size parameter | Public type | Private type |
+| --- | --- | --- | --- |
+| `'EC'` | `EcCurve` (`P-256`, `P-384`, `P-521`, `secp256k1`) | `EcPublicJwk` (`x`, `y`) | `EcPrivateJwk` (adds `d`) |
+| `'RSA'` | — | `RsaPublicJwk` (`n`, `e`) | `RsaPrivateJwk` (adds `d`, `p`, `q`, `dp`, `dq`, `qi`, `oth`) |
+| `'oct'` | — | — (symmetric only) | `OctJwk` (`k`) |
+| `'OKP'` | `OkpCurve` (`Ed25519`, `Ed448`, `X25519`, `X448`) | `OkpPublicJwk` (`x`) | `OkpPrivateJwk` (adds `d`) |
+| `'AKP'` | `MldsaAlgorithm` (`ML-DSA-44`/`65`/`87`) | `AkpPublicJwk` (`pub`) | `AkpPrivateJwk` (adds `priv`) |
+
+`PublicJwk` and `PrivateJwk` are the unions across all five families;
+`JsonWebKey` is `PublicJwk | PrivateJwk`.
+
+```ts
+import type { EcPublicJwk, RsaPrivateJwk, OctJwk } from '../../../shared/application/http/json-web-token.js'
+
+const ecKey: EcPublicJwk = { kty: 'EC', crv: 'P-256', x: '...' as Base64Url, y: '...' as Base64Url }
+const rsaKey: RsaPrivateJwk = { kty: 'RSA', n: '...' as Base64Url, e: '...' as Base64Url, d: '...' as Base64Url }
+const symmetricKey: OctJwk = { kty: 'oct', k: '...' as Base64Url }
+```
+
+`JsonWebKeySet` wraps a `keys` array of mixed key types; `PublicJsonWebKeySet`
+narrows that array to public keys only, for a key set safe to publish. A
+thumbprint (`JwkThumbprint`) is a `Base64Url`; `JwkThumbprintUri` is the
+`urn:ietf:params:oauth:jwk-thumbprint:` URI form.
+
+#### Headers
+
+`JoseCommonHeaderParameters` covers the parameters shared by both header
+kinds (`jku`, `jwk`, `kid`, the `x5*` members, `typ`, `cty`, `crit`).
+`JwsHeaderParameters` and `JweHeaderParameters` extend it with the two
+distinct options:
+
+| Type | Required members | Extra members |
+| --- | --- | --- |
+| `JwsHeaderParameters` | `alg: JwsAlgorithm` | `b64`, `ppt`, `url`, `nonce`, `svt`, `jwt`, `client_id`, `trust_chain`, `peer_trust_chain` |
+| `JweHeaderParameters` | `alg: JweKeyManagementAlgorithm`, `enc: JweContentEncryptionAlgorithm` | `zip`, `epk`, `apu`, `apv`, `iv`, `tag`, `p2s`, `p2c`, replicated `iss`/`sub`/`aud`, `url`, `nonce` |
+
+`JwsHeader<CustomHeader>` and `JweHeader<CustomHeader>` intersect the
+respective parameters with a caller-supplied custom header shape.
+
+#### Serializations
+
+A JWS or a JWE can be represented four ways: as a single delimited string
+(compact), or as JSON with either one signer/recipient inlined (flattened) or
+several (general).
+
+| Type | Kind | Shape |
+| --- | --- | --- |
+| `CompactJws` | JWS, compact | `` `${string}.${string}.${string}` `` branded string |
+| `GeneralJwsJsonSerialization` | JWS, JSON, general | `payload` + `signatures[]` |
+| `FlattenedJwsJsonSerialization` | JWS, JSON, flattened | `payload` + one signature inlined |
+| `CompactJwe` | JWE, compact | `` `${string}.${string}.${string}.${string}.${string}` `` branded string |
+| `GeneralJweJsonSerialization` | JWE, JSON, general | shared members + `recipients[]` |
+| `FlattenedJweJsonSerialization` | JWE, JSON, flattened | shared members + one recipient inlined |
+
+`JwsJsonSerialization` and `JweJsonSerialization` are the general/flattened
+unions for each. `UnsecuredCompactJws` types the `alg: 'none'` compact form
+(`` `${string}.${string}.` `` — an empty signature segment).
+
+```ts
+import type { CompactJws, FlattenedJwsJsonSerialization } from '../../../shared/application/http/json-web-token.js'
+
+const compact = 'eyJhbGciOiJFUzI1NiJ9.eyJzdWIiOiIxIn0.c2ln' as CompactJws
+
+const flattened: FlattenedJwsJsonSerialization = {
+    payload: 'eyJzdWIiOiIxIn0' as Base64Url,
+    protected: 'eyJhbGciOiJFUzI1NiJ9' as Base64Url,
+    signature: 'c2ln' as Base64Url,
+}
+```
+
+`DecodedJws` and `DecodedJwe` describe a decoded token's structure;
+`DecodedJwt` is their union, discriminated by a `kind: 'JWS' | 'JWE'` tag.
+`CompactJwt` is `CompactJws | CompactJwe`, matching how RFC 7519 allows a JWT
+to use either serialization.
+
+#### JWT Claims
+
+`JwtRegisteredClaims` covers the seven RFC 7519 claims (`iss`, `sub`, `aud`,
+`exp`, `nbf`, `iat`, `jti`). `IanaRegisteredJwtClaims` extends it with every
+claim name currently registered by IANA (OpenID Connect profile claims, SIP,
+CDNI, GNAP, EAT, RATS, RFC 9901 selective-disclosure claims, OpenID
+Federation claims, and more), so `JwtClaims<CustomClaims>` covers arbitrary
+custom claims through intersection while still typing every standard one.
+
+Four ready-made profiles fix `JwtRegisteredClaims` members to `required`
+where the profile mandates them, as distinct implementation options for
+common token kinds:
+
+| Type | Profile | Required beyond the base seven |
+| --- | --- | --- |
+| `OpenIdConnectIdTokenClaims` | OIDC ID Token | `iss`, `sub`, `aud`, `exp`, `iat` |
+| `OAuth2JwtAccessTokenClaims` | RFC 9068 OAuth 2.0 access token | `iss`, `exp`, `aud`, `sub`, `client_id`, `iat`, `jti` |
+| `DpopProofClaims` | RFC 9449 DPoP proof | `jti`, `htm`, `htu`, `iat` |
+| `SdJwtClaims` | RFC 9901 SD-JWT | none beyond `IanaRegisteredJwtClaims`, adds `_sd`/`_sd_alg` |
+
+```ts title="users/adapters/verify-access-token.ts"
+import {
+    JwsVerifier,
+    OAuth2JwtAccessTokenClaims,
+    CompactJws,
+    JsonWebKey,
+} from '../../shared/application/http/json-web-token.js'
+
+export function verifyAccessToken(
+    verifier: JwsVerifier,
+    token: CompactJws,
+    key: JsonWebKey,
+) {
+    return verifier.verify<OAuth2JwtAccessTokenClaims>(token, key)
+}
+```
+
+`SdJwtDisclosure`, `SdJwt`, and `SdJwtPresentation` brand the three distinct
+string forms used by selective disclosure: a single disclosure, an issued
+SD-JWT, and a presentation with disclosures appended.
+
+#### Service Contracts
+
+An adapter implements these interfaces against a concrete JOSE library. Each
+one exposes a distinct operation:
+
+| Contract | Method(s) | Responsibility |
+| --- | --- | --- |
+| `JwtDecoder` | `decode()` | Parse a compact token into a `DecodedJwt` without necessarily validating it. |
+| `JwsSigner` | `signCompact()`, `signFlattened()` | Produce a JWS in either serialization. |
+| `JwsVerifier` | `verify()` | Validate a JWS and return a `JwtValidationResult`. |
+| `JweEncrypter` | `encryptCompact()`, `encryptFlattened()` | Produce a JWE in either serialization. |
+| `JweDecrypter` | `decrypt()` | Decrypt a JWE back into `BinaryData`. |
+| `JwkThumbprinter` | `thumbprint()`, `thumbprintUri()` | Compute an RFC 7638 thumbprint, plain or as a URI. |
+| `JwksResolver` | `resolve()`, `select()` | Fetch a JWK Set and pick the key matching a header's `kid`/`x5t`/`x5t#S256`. |
+
+```ts
+import type { JwkThumbprinter, JsonWebKey } from '../../../shared/application/http/json-web-token.js'
+
+function fingerprint(thumbprinter: JwkThumbprinter, key: JsonWebKey) {
+    return thumbprinter.thumbprintUri(key)
+}
+```
+
+#### Validating A Token
+
+`JwtValidationResult` is the outcome of checking a token against a
+`JwtValidationPolicy` (`issuers`, `audiences`, `subjects`, `algorithms`,
+`requiredClaims`, `clockToleranceSeconds`, `maxTokenAgeSeconds`, `typ`). It
+has exactly two implementation options, discriminated by `valid`:
+
+| Type | `valid` | Payload |
+| --- | --- | --- |
+| `JwtValidationSuccess` | `true` | `value: DecodedJws<Claims>` |
+| `JwtValidationFailure` | `false` | `code`, `message`, optional `cause` |
+
+`JwtValidationFailure['code']` enumerates the recognized rejection reasons:
+`'malformed'`, `'unsupported_serialization'`, `'unsupported_algorithm'`,
+`'invalid_signature'`, `'decryption_failed'`, `'expired'`, `'not_active'`,
+`'issued_in_future'`, `'issuer_mismatch'`, `'audience_mismatch'`,
+`'subject_mismatch'`, `'missing_claim'`, `'critical_header_unsupported'`, and
+`'policy_rejected'` (plus an open string for adapter-specific codes).
+
+```ts
+import type { JwtValidationResult } from '../../../shared/application/http/json-web-token.js'
+
+function describeResult(result: JwtValidationResult): string {
+    if (result.valid) {
+        return `ok, subject=${result.value.claims.sub}`
+    }
+
+    return `rejected: ${result.code}`
+}
+```
+
+#### Registry Metadata
+
+`JoseAlgorithmRegistryEntry`, `JoseHeaderParameterRegistryEntry`, and
+`JwtClaimRegistryEntry` type the shape of a row describing an algorithm, a
+header parameter, or a claim, for adapters that want to render or validate
+against IANA's own registry data instead of hardcoding the unions above.
+
+> **Hint**
+> This module has no runtime implementation. Choose a JOSE library, then use
+> `JwsSigner`/`JwsVerifier`/`JweEncrypter`/`JweDecrypter`/`JwtDecoder` to
+> annotate its inputs and outputs so the rest of the codebase stays independent
+> from that library's own types.

package/docs/shared/application/http/opengraph.md

@@ -0,0 +1,161 @@
+### Open Graph
+
+`opengraph.ts` declares a type-only implementation of the
+[Open Graph protocol](https://ogp.me/), the Twitter Card meta tags, and
+Facebook's compatibility extensions. It is used when an adapter needs to build
+or read the social-sharing metadata of a page.
+
+This module has no runtime values or implementations, including no HTML
+rendering. Use it to build the data and a separate template or renderer to
+emit the actual `<meta>` tags.
+
+#### Base Shape
+
+Every Open Graph object shares `OpenGraphBase<TType>`: the required `title`,
+`type`, `images` (`OneOrMore<OpenGraphImage>`, first has precedence), and
+`url`, plus the optional `audio`, `description`, `determiner`, `locale`,
+`alternateLocales`, `siteName`, and `videos`. `OpenGraphObjectExtensions`
+adds an optional `extensions` map for CURIE-namespaced custom properties
+(`'product:color'`, etc.), kept as opaque strings.
+
+#### Standard Object Types
+
+`OpenGraphType` selects one of thirteen standard types
+(`OpenGraphStandardType`) or a custom CURIE type
+(`OpenGraphCustomType`, e.g. `'product:item'`). Each standard type has its
+own interface adding the fields that type requires:
+
+| `type` | Interface | Extra fields |
+| --- | --- | --- |
+| `'website'` | `OpenGraphWebsite` | none |
+| `'article'` | `OpenGraphArticle` | `publishedTime`, `modifiedTime`, `expirationTime`, `authors`, `section`, `tags` |
+| `'book'` | `OpenGraphBook` | `authors`, `isbn`, `releaseDate`, `tags` |
+| `'profile'` | `OpenGraphProfile` | `firstName`, `lastName`, `username`, `gender` |
+| `'music.song'` | `OpenGraphMusicSong` | `duration`, `albums`, `musicians` |
+| `'music.album'` | `OpenGraphMusicAlbum` | `songs`, `musicians`, `releaseDate` |
+| `'music.playlist'` | `OpenGraphMusicPlaylist` | `songs`, `creator` |
+| `'music.radio_station'` | `OpenGraphMusicRadioStation` | `creator` |
+| `'video.movie'` | `OpenGraphVideoMovie` | `actors`, `directors`, `writers`, `duration`, `releaseDate`, `tags` (`OpenGraphVideoMetadata`) |
+| `'video.episode'` | `OpenGraphVideoEpisode` | `OpenGraphVideoMetadata` + `series` |
+| `'video.tv_show'` | `OpenGraphVideoTvShow` | `OpenGraphVideoMetadata` |
+| `'video.other'` | `OpenGraphVideoOther` | `OpenGraphVideoMetadata` |
+| `'payment.link'` | `OpenGraphPaymentLink` | `paymentDescription`, `currency`, `amount`, `expiresAt`, `paymentStatus`, `paymentId`, `successUrl` (marked beta by the protocol) |
+| CURIE type | `OpenGraphCustomObject` | none beyond the base shape |
+
+`OpenGraphMetadata` is the union of all fourteen. Building one selects the
+type through the discriminant and, from there, TypeScript narrows to that
+type's own extra fields.
+
+```ts title="users/adapters/user-profile-metadata.ts"
+import { OpenGraphProfile } from '../../shared/application/http/opengraph.js'
+
+export function buildProfileMetadata(username: string): OpenGraphProfile {
+    return {
+        type: 'profile',
+        title: username,
+        url: `https://example.com/users/${username}`,
+        images: [{ url: `https://example.com/users/${username}/avatar.png` }],
+        username,
+    }
+}
+```
+
+```ts title="users/adapters/article-metadata.ts"
+import { OpenGraphArticle } from '../../shared/application/http/opengraph.js'
+
+export function buildArticleMetadata(slug: string): OpenGraphArticle {
+    return {
+        type: 'article',
+        title: 'How context ports work',
+        url: `https://example.com/blog/${slug}`,
+        images: [{ url: `https://example.com/blog/${slug}/cover.png` }],
+        publishedTime: new Date().toISOString(),
+        tags: ['architecture', 'typescript'],
+    }
+}
+```
+
+`OpenGraphPaymentStatus` (`'PENDING' | 'PAID' | 'FAILED' | 'EXPIRED'`) types
+`OpenGraphPaymentLink['paymentStatus']`.
+
+#### Twitter Cards
+
+`TwitterCardType` selects one of four card layouts. `TwitterCardBase<TCard>`
+carries the members every card shares (`site`, `siteId`, `creator`,
+`creatorId`, `title`, `description`); each concrete card adds the fields that
+layout needs:
+
+| `card` | Interface | Extra/required fields |
+| --- | --- | --- |
+| `'summary'` | `TwitterSummaryCard` | optional `image` |
+| `'summary_large_image'` | `TwitterSummaryLargeImageCard` | optional `image` |
+| `'player'` | `TwitterPlayerCard` | required `image`, `player`, `playerWidth`, `playerHeight`; optional `playerStream`, `playerStreamContentType` |
+| `'app'` | `TwitterAppCard` | optional `country`, `iphone`, `ipad`, `googlePlay` (each `TwitterAppPlatform`) |
+
+`TwitterCardMetadata` is the union of all four.
+
+```ts
+import type { TwitterPlayerCard } from '../../../shared/application/http/opengraph.js'
+
+const playerCard: TwitterPlayerCard = {
+    card: 'player',
+    image: { url: 'https://example.com/videos/1/thumb.png' },
+    player: 'https://example.com/videos/1/embed',
+    playerWidth: 640,
+    playerHeight: 360,
+}
+```
+
+#### Raw Meta Tag Representation
+
+`OpenGraphMetaTag`/`TwitterMetaTag` are the flat `property`/`content` and
+`name`/`content` tag forms closer to the actual `<meta>` markup, for a
+renderer that emits tags directly instead of consuming the structured
+objects above.
+
+| Tag family | Type | Attribute pair |
+| --- | --- | --- |
+| Open Graph (standard) | `OpenGraphStandardMetaTag` | `property`/`content`, e.g. `'og:title'` |
+| Open Graph (custom) | `OpenGraphCustomMetaTag` | any `` `${string}:${string}` `` property |
+| Twitter | `TwitterMetaTag` | `name`/`content`, e.g. `'twitter:card'` |
+| Facebook | `FacebookMetaTag` | `PropertyMetaTag<'fb:app_id'>` |
+| Standard HTML | `StandardHtmlMetaTag` | `'description'` \| `'theme-color'` |
+
+`SocialMetaTag` is the union of all five families. `CanonicalLinkTag` types
+the `<link rel="canonical">` element separately, since it is not a `<meta>`
+tag.
+
+#### Aggregate Document
+
+Two document shapes cover the two stages of building a page's social
+metadata:
+
+| Type | Shape | Use |
+| --- | --- | --- |
+| `SocialMetadataDocument` | `head?`, `openGraph` (required), `twitter?`, `facebook?` | Structured data a service builds before rendering |
+| `RawSocialMetadataDocument` | `title?`, `meta: SocialMetaTag[]`, `links?: CanonicalLinkTag[]` | The rendered, tag-list form a template consumes |
+
+```ts title="users/adapters/social-metadata-document.ts"
+import {
+    SocialMetadataDocument,
+    OpenGraphProfile,
+} from '../../shared/application/http/opengraph.js'
+
+export function buildSocialMetadata(profile: OpenGraphProfile): SocialMetadataDocument {
+    return {
+        head: { title: profile.title, description: profile.description },
+        openGraph: profile,
+        twitter: { card: 'summary', title: profile.title },
+    }
+}
+```
+
+Converting a `SocialMetadataDocument` into a `RawSocialMetadataDocument` is
+the responsibility of a renderer, which flattens each structured field into
+its corresponding `SocialMetaTag` entries; that conversion is not implemented
+by this module.
+
+> **Hint**
+> This module has no runtime implementation, including no HTML rendering. Use
+> `OpenGraphMetadata` to build the data and a separate template or renderer to
+> emit the `<meta>` tags described by `OpenGraphMetaTag`/`TwitterMetaTag`.

package/docs/shared/application/loggers.md

@@ -28,8 +28,8 @@ any adapter to use a particular logger implementation.
 `Logger` is responsible for receiving log data from the application layer.
 
 ```ts title="shared/application/loggers.ts"
-import { type TimeZone } from '../../types/iana.js'
-import { type Locale } from '../../types/cldr.js'
+import { type TimeZone } from '../../types/timezones.js'
+import { type Locale } from '../../types/locales.js'
 
 export abstract class Logger {
     [property: string]: unknown
@@ -74,8 +74,9 @@ request, while the adapter decides how those actions are persisted or displayed.
 `name` and `level` identify the logger instance and its minimum severity, so an
 adapter can decide which logs to emit or route. `datetimeLocales` and
 `datetimeFormatOptions` control how `getCurrentDatetime()` formats the current
-moment, using the `Locale` type from `types/cldr.d.ts` and the `TimeZone` type
-from `types/iana.d.ts`. Adapters can use `getCurrentDatetime()` to timestamp
+moment, using the `Locale` type from `types/locales.d.ts` (see
+`types/locales.md`) and the `TimeZone` type from `types/timezones.d.ts` (see
+`types/timezones.md`). Adapters can use `getCurrentDatetime()` to timestamp
 log entries consistently, regardless of the runtime environment's own locale
 or timezone.
 

package/docs/types/json.md

@@ -0,0 +1,82 @@
+### JSON
+
+The generated root also declares a small family of types that describe plain,
+serializable JSON data.
+They are used when a contract must guarantee that a value survives a round
+trip through `JSON.stringify()` / `JSON.parse()`.
+
+#### Declaration
+
+These types live in `types/json.d.ts`.
+
+```ts title="types/json.d.ts"
+export type JsonPrimitive = string | number | boolean | null
+
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray
+
+export type JsonArray = readonly JsonValue[]
+
+export type JsonObject = {
+    readonly [key: string]: JsonValue
+}
+```
+
+`JsonPrimitive` covers the scalar values allowed in JSON. `JsonValue` extends
+that with nested objects and arrays, so it recursively describes any JSON-safe
+value. `JsonObject` and `JsonArray` name the two composite shapes so other
+declarations can refer to them directly instead of repeating the union.
+
+#### Implementation Options
+
+A `JsonValue` is always one of four shapes. Each one is a distinct option a
+consumer must be ready to handle.
+
+| Shape | Type | Example |
+| --- | --- | --- |
+| Primitive | `JsonPrimitive` | `'active'`, `42`, `true`, `null` |
+| Object | `JsonObject` | `{ id: '1', active: true }` |
+| Array | `JsonArray` | `[1, 2, 3]`, `[{ id: '1' }]` |
+| Nested composite | `JsonValue` | `{ tags: ['a', 'b'], meta: { retries: 2 } }` |
+
+```ts
+import { type JsonValue } from './types/json.js'
+
+const primitive: JsonValue = 'ada@example.com'
+const object: JsonValue = { id: '1', active: true }
+const array: JsonValue = [1, 2, 3]
+const nested: JsonValue = { tags: ['a', 'b'], meta: { retries: 2 } }
+```
+
+All four are valid `JsonValue` values because the type is a recursive union;
+there is no separate constructor or runtime check to opt into a shape.
+
+#### Basic Usage
+
+```ts
+import { type JsonValue } from './types/json.js'
+
+function toLogPayload(value: JsonValue): string {
+    return JSON.stringify(value)
+}
+```
+
+Because `JsonValue` excludes functions, `undefined`, symbols, and other
+non-serializable values, `toLogPayload()` can call `JSON.stringify()` without
+guarding against values that would silently disappear or throw.
+
+#### JsonObject Versus Generic
+
+Use `JsonObject`/`JsonValue` when a contract must guarantee its data is plain
+and serializable, such as request payloads, stored metadata, or wire formats.
+Prefer `types/objects.md`'s `Generic<T>` instead when the value type is not
+required to be JSON-safe.
+
+`shared/application/http/json-api.ts` and
+`shared/application/http/json-web-token.ts` build on these types to describe
+JSON:API documents and JOSE/JWT structures; see `shared/application/http/json-api.md`
+and `shared/application/http/json-web-token.md`.
+
+> **Hint**
+> These declarations only provide compile-time structure. They do not validate
+> that a runtime value is actually JSON-safe; a value typed as `JsonValue` can
+> still contain a `Date` or a class instance if it was cast into the type.

package/docs/types/locales.md

@@ -0,0 +1,77 @@
+### Locales
+
+`Locale` is a literal string union of every locale identifier available in
+Unicode CLDR.
+It is used when a contract needs to accept only valid locale tags instead of
+an open `string`.
+
+#### Declaration
+
+`Locale` lives in `types/locales.d.ts` and is generated from Unicode CLDR
+48.2.1.
+
+```ts title="types/locales.d.ts"
+export type Locale =
+    | 'aa'
+    | 'af'
+    | 'am'
+    | 'ar'
+    | 'ar-EG'
+    | 'de'
+    | 'de-AT'
+    | 'en'
+    | 'en-GB'
+    | 'en-US'
+    | 'es'
+    | 'es-419'
+    | 'fr'
+    | 'ja'
+    | 'zh-Hans'
+    // ...every other CLDR locale identifier
+```
+
+The generated file lists every language identifier and every regional variant
+registered by CLDR, from bare language tags such as `'en'` to script- and
+region-qualified tags such as `'zh-Hant-HK'` or `'ca-ES-valencia'`.
+
+#### Basic Usage
+
+```ts
+import { type Locale } from './types/locales.js'
+
+function formatCount(value: number, locale: Locale): string {
+    return new Intl.NumberFormat(locale).format(value)
+}
+
+formatCount(1200, 'en-US')
+formatCount(1200, 'es-419')
+```
+
+Because `Locale` only accepts identifiers CLDR actually defines, a typo such
+as `'en-USA'` fails at compile time instead of silently reaching
+`Intl.NumberFormat`.
+
+#### Accepting Multiple Locales
+
+`Intl` APIs commonly accept a locale or a list of locales in priority order.
+`Locale[]` expresses that same option without widening to `string[]`.
+
+```ts
+import { type Locale } from './types/locales.js'
+
+const preferredLocales: Locale[] = ['fr-CA', 'fr', 'en']
+```
+
+The runtime resolves the first supported locale from the list; `Locale[]`
+only guarantees that every candidate is a real CLDR identifier.
+
+#### Where It Is Used
+
+`shared/application/loggers.ts` uses `Locale[]` for `Logger.datetimeLocales`,
+the locale list passed to `Date.prototype.toLocaleString()` when formatting a
+log timestamp. See `shared/application/loggers.md`.
+
+> **Hint**
+> `Locale` is a compile-time contract only. It does not validate that the
+> runtime's ICU data actually supports every listed locale; `Intl` APIs fall
+> back to a default when a requested locale is unsupported at runtime.

package/docs/types/objects.md

@@ -0,0 +1,70 @@
+### Objects
+
+The generated root declares `Generic<T>`, a plain object whose keys are strings
+and whose values share the same type.
+It provides a small common building block for code that works with object-like
+data but does not need a more specific shape yet.
+
+#### Declaration
+
+`Generic<T>` lives in `types/objects.d.ts`.
+
+```ts title="types/objects.d.ts"
+export type Generic<T = unknown> = Record<string, T>
+```
+
+This alias expands to `Record<string, T>`. When no type argument is provided,
+the values use `unknown`.
+
+#### With A Type Argument
+
+In the following example we use `Generic<string>` for a set of plain filters.
+
+```ts
+import { type Generic } from './types/objects.js'
+
+const filters: Generic<string> = {
+    status: 'active',
+    sort: 'email',
+}
+```
+
+`filters` can only store string values because the type argument fixes the
+value shape for the whole object.
+
+#### Without A Type Argument
+
+Now consider the same pattern without providing a type argument.
+
+```ts
+import { type Generic } from './types/objects.js'
+
+const metadata: Generic = {
+    retries: 2,
+    cached: true,
+}
+```
+
+In this case the values use `unknown`. This is useful when the object is plain
+and open-ended, but the caller must narrow each value before using it in a
+specific way.
+
+#### When To Use It
+
+Use `Generic<T>` when the code needs a simple object contract and the exact set
+of keys is not the main concern.
+
+Typical uses include:
+
+1. filter objects;
+2. metadata objects;
+3. plain configuration maps;
+4. transport-neutral dictionaries.
+
+When the object has a stable business meaning, prefer a named type instead of a
+generic record.
+
+> **Hint**
+> `Generic<T>` is intentionally small. It should support loose object contracts,
+> not replace explicit domain or application types. It is also the base shape
+> used by `types/json.md` when a value only needs to be JSON-safe.