# Route

The descriptor three audiences read: a router mounts it, a menu renders it, a
share link resolves it.

Generated from `libs/oshun/workbench-kit/src/routes.ts` by
`node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs`. Ledger:
S1.8. Do not edit by hand.

## Summary

- `src/routes.ts`

| Entry point                   | Runtime class | Authorized by |
| ----------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/routes` | `contract`    | S1.8          |

## Exports

| Symbol                                                              | Kind        | Summary                                                                |
| ------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------- |
| [BREADCRUMB_MODES](#breadcrumb_modes)                               | enumeration | —                                                                      |
| [BreadcrumbMode](#breadcrumbmode)                                   | type        | —                                                                      |
| [DeepLinkDescriptor](#deeplinkdescriptor)                           | interface   | —                                                                      |
| [Discoverability](#discoverability)                                 | type        | —                                                                      |
| [DISCOVERABILITY](#discoverability)                                 | enumeration | —                                                                      |
| [effectivePaths](#effectivepaths)                                   | function    | Every host a route answers on: the canonical one plus its aliases.     |
| [findRedirectCycles](#findredirectcycles)                           | function    | —                                                                      |
| [FLAG_TARGETING](#flag_targeting)                                   | enumeration | —                                                                      |
| [FLAG_UNAVAILABLE_BEHAVIOUR](#flag_unavailable_behaviour)           | enumeration | —                                                                      |
| [FlagRequirement](#flagrequirement)                                 | interface   | —                                                                      |
| [FlagTargeting](#flagtargeting)                                     | type        | —                                                                      |
| [FlagUnavailableBehaviour](#flagunavailablebehaviour)               | type        | —                                                                      |
| [hostNavigation](#hostnavigation)                                   | function    | —                                                                      |
| [HostNavigation](#hostnavigation)                                   | interface   | —                                                                      |
| [HTTP_METHODS](#http_methods)                                       | enumeration | —                                                                      |
| [HttpMethod](#httpmethod)                                           | type        | —                                                                      |
| [NAV_PLACEMENTS](#nav_placements)                                   | enumeration | —                                                                      |
| [NAV_TARGETS](#nav_targets)                                         | enumeration | —                                                                      |
| [navigationAccountsForEveryRoute](#navigationaccountsforeveryroute) | function    | Every route in the set is either in the tree or in the exclusion list. |
| [NavigationExclusion](#navigationexclusion)                         | interface   | —                                                                      |
| [NavigationNode](#navigationnode)                                   | interface   | —                                                                      |
| [NavigationPlacement](#navigationplacement)                         | interface   | —                                                                      |
| [NavPlacement](#navplacement)                                       | type        | —                                                                      |
| [NavTarget](#navtarget)                                             | type        | —                                                                      |
| [ParsedPath](#parsedpath)                                           | interface   | —                                                                      |
| [parseRouteDescriptor](#parseroutedescriptor)                       | function    | —                                                                      |
| [parseRoutePath](#parseroutepath)                                   | function    | —                                                                      |
| [ROUTE_SCOPES](#route_scopes)                                       | enumeration | —                                                                      |
| [RouteDescriptor](#routedescriptor)                                 | interface   | —                                                                      |
| [routeInventory](#routeinventory)                                   | function    | —                                                                      |
| [RouteInventoryRow](#routeinventoryrow)                             | interface   | —                                                                      |
| [RouteScope](#routescope)                                           | type        | —                                                                      |
| [RouteSurface](#routesurface)                                       | type        | An API route or a UI route, never a thing that is both.                |
| [RouteValidationOptions](#routevalidationoptions)                   | interface   | —                                                                      |
| [RouteViolation](#routeviolation)                                   | interface   | —                                                                      |
| [SCOPE_BINDINGS](#scope_bindings)                                   | enumeration | —                                                                      |
| [ScopeBinding](#scopebinding)                                       | type        | —                                                                      |
| [SHARE_SAFETY](#share_safety)                                       | enumeration | —                                                                      |
| [ShareSafety](#sharesafety)                                         | type        | —                                                                      |
| [UI_KINDS](#ui_kinds)                                               | enumeration | —                                                                      |
| [UiKind](#uikind)                                                   | type        | —                                                                      |
| [validateRoutes](#validateroutes)                                   | function    | —                                                                      |

## Shapes

#### BREADCRUMB_MODES

Values: `inherit`, `replace`, `hidden`

#### BreadcrumbMode

```ts
(typeof BREADCRUMB_MODES)[number];
```

#### DeepLinkDescriptor

| Field             | Type                                                             | Required | Notes                                                                   |
| ----------------- | ---------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
| `entityParameter` | `string`                                                         | required | The path parameter naming the entity a link points at.                  |
| `subviews`        | `readonly string[]`                                              | required | —                                                                       |
| `filterKeys`      | `readonly string[]`                                              | required | —                                                                       |
| `inspectorKeys`   | `readonly string[]`                                              | required | —                                                                       |
| `anchorKinds`     | `readonly AnchorKind[]` — [AnchorKind](./identity.md#anchorkind) | required | Which S1.4 anchor kinds a link into this route may carry.               |
| `expirySeconds`   | `number \| null`                                                 | required | Null only when the link is never shared, so there is nothing to expire. |
| `shareSafety`     | [ShareSafety](#sharesafety)                                      | required | —                                                                       |

#### Discoverability

```ts
(typeof DISCOVERABILITY)[number];
```

#### DISCOVERABILITY

Values: `listed`, `search-only`, `hidden`

#### effectivePaths

Every host a route answers on: the canonical one plus its aliases.

```ts
effectivePaths(route: RouteDescriptor): readonly string[]
```

#### findRedirectCycles

```ts
findRedirectCycles(byId: ReadonlyMap<string, RouteDescriptor>): readonly string[][]
```

#### FLAG_TARGETING

Values: `global`, `tenant`, `workspace`, `user`, `percentage`

#### FLAG_UNAVAILABLE_BEHAVIOUR

Values: `hide`, `disable`, `fail-closed`, `fail-open`

#### FlagRequirement

| Field             | Type                                                  | Required | Notes                                                     |
| ----------------- | ----------------------------------------------------- | -------- | --------------------------------------------------------- |
| `flagId`          | `string`                                              | required | —                                                         |
| `defaultEnabled`  | `boolean`                                             | required | —                                                         |
| `targeting`       | [FlagTargeting](#flagtargeting)                       | required | —                                                         |
| `dependsOn`       | `string \| null`                                      | required | —                                                         |
| `expiresAt`       | `Instant \| null` — [Instant](./identity.md#instant)  | required | Exactly one of `expiresAt` and `permanentReason` is set.  |
| `permanentReason` | `string \| null`                                      | required | —                                                         |
| `whenUnavailable` | [FlagUnavailableBehaviour](#flagunavailablebehaviour) | required | What a consumer does when the flag service cannot answer. |

#### FlagTargeting

```ts
(typeof FLAG_TARGETING)[number];
```

#### FlagUnavailableBehaviour

```ts
(typeof FLAG_UNAVAILABLE_BEHAVIOUR)[number];
```

#### hostNavigation

```ts
hostNavigation(routes: readonly RouteDescriptor[], host: Host, audience: Audience): HostNavigation
```

#### HostNavigation

| Field      | Type                                                                           | Required | Notes                                          |
| ---------- | ------------------------------------------------------------------------------ | -------- | ---------------------------------------------- |
| `host`     | [Host](./capability.md#host)                                                   | required | —                                              |
| `audience` | [Audience](./capability.md#audience)                                           | required | —                                              |
| `tree`     | `readonly NavigationNode[]` — [NavigationNode](#navigationnode)                | required | —                                              |
| `excluded` | `readonly NavigationExclusion[]` — [NavigationExclusion](#navigationexclusion) | required | Every route this projection left out, and why. |

#### HTTP_METHODS

Values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`

#### HttpMethod

```ts
(typeof HTTP_METHODS)[number];
```

#### NAV_PLACEMENTS

Values: `primary`, `secondary`, `utility`, `contextual`

#### NAV_TARGETS

Values: `in-app`, `new-tab`, `embedded`

#### navigationAccountsForEveryRoute

Every route in the set is either in the tree or in the exclusion list.

```ts
navigationAccountsForEveryRoute(routes: readonly RouteDescriptor[], navigation: HostNavigation): { readonly unaccounted: readonly string[]; readonly doubleCounted: readonly string[] }
```

#### NavigationExclusion

| Field     | Type                                                                                                              | Required | Notes |
| --------- | ----------------------------------------------------------------------------------------------------------------- | -------- | ----- |
| `routeId` | `string`                                                                                                          | required | —     |
| `reason`  | `\| 'no-navigation-placement' \| 'different-host' \| 'audience-not-permitted' \| 'not-discoverable' \| 'retired'` | required | —     |

#### NavigationNode

| Field       | Type                                                            | Required | Notes |
| ----------- | --------------------------------------------------------------- | -------- | ----- |
| `routeId`   | `string`                                                        | required | —     |
| `labelKey`  | `string`                                                        | required | —     |
| `iconKey`   | `string \| null`                                                | required | —     |
| `order`     | `number`                                                        | required | —     |
| `placement` | [NavPlacement](#navplacement)                                   | required | —     |
| `target`    | [NavTarget](#navtarget)                                         | required | —     |
| `children`  | `readonly NavigationNode[]` — [NavigationNode](#navigationnode) | required | —     |

#### NavigationPlacement

| Field             | Type                                | Required | Notes                          |
| ----------------- | ----------------------------------- | -------- | ------------------------------ |
| `placement`       | [NavPlacement](#navplacement)       | required | —                              |
| `labelKey`        | `string`                            | required | i18n KEYS, never literal text. |
| `iconKey`         | `string \| null`                    | required | —                              |
| `order`           | `number`                            | required | —                              |
| `parentRouteId`   | `string \| null`                    | required | —                              |
| `breadcrumb`      | [BreadcrumbMode](#breadcrumbmode)   | required | —                              |
| `discoverability` | [Discoverability](#discoverability) | required | —                              |
| `target`          | [NavTarget](#navtarget)             | required | —                              |

#### NavPlacement

```ts
(typeof NAV_PLACEMENTS)[number];
```

#### NavTarget

```ts
(typeof NAV_TARGETS)[number];
```

#### ParsedPath

| Field        | Type                | Required | Notes |
| ------------ | ------------------- | -------- | ----- |
| `path`       | `string`            | required | —     |
| `parameters` | `readonly string[]` | required | —     |

#### parseRouteDescriptor

```ts
parseRouteDescriptor(input: unknown): ParseResult<RouteDescriptor>
```

#### parseRoutePath

```ts
parseRoutePath(input: unknown): ParseResult<ParsedPath>
```

#### ROUTE_SCOPES

Values: `platform`, `tenant`, `workspace`

#### RouteDescriptor

| Field                | Type                                                                        | Required | Notes                                               |
| -------------------- | --------------------------------------------------------------------------- | -------- | --------------------------------------------------- |
| `routeId`            | `string`                                                                    | required | —                                                   |
| `surface`            | [RouteSurface](#routesurface)                                               | required | —                                                   |
| `path`               | `string`                                                                    | required | —                                                   |
| `parameters`         | `readonly string[]`                                                         | required | —                                                   |
| `owningCapability`   | [CapabilityId](./identity.md#capabilityid)                                  | required | —                                                   |
| `contractVersion`    | [SemanticVersion](./capability.md#semanticversion)                          | required | —                                                   |
| `lifecycle`          | [Lifecycle](./capability.md#lifecycle)                                      | required | —                                                   |
| `redirectTo`         | `string \| null`                                                            | required | Where a retired or deprecated route sends a caller. |
| `host`               | [Host](./capability.md#host)                                                | required | —                                                   |
| `hostAliases`        | `readonly Host[]` — [Host](./capability.md#host)                            | required | —                                                   |
| `audiences`          | `readonly Audience[]` — [Audience](./capability.md#audience)                | required | —                                                   |
| `roles`              | `readonly string[]`                                                         | required | —                                                   |
| `scope`              | [RouteScope](#routescope)                                                   | required | —                                                   |
| `scopeBinding`       | `ScopeBinding \| null` — [ScopeBinding](#scopebinding)                      | required | —                                                   |
| `dataClassification` | [DataClassification](./capability.md#dataclassification)                    | required | —                                                   |
| `navigation`         | `NavigationPlacement \| null` — [NavigationPlacement](#navigationplacement) | required | —                                                   |
| `deepLink`           | `DeepLinkDescriptor \| null` — [DeepLinkDescriptor](#deeplinkdescriptor)    | required | —                                                   |
| `flags`              | `readonly FlagRequirement[]` — [FlagRequirement](#flagrequirement)          | required | —                                                   |

#### routeInventory

```ts
routeInventory(routes: readonly RouteDescriptor[]): readonly RouteInventoryRow[]
```

#### RouteInventoryRow

| Field                | Type                                                         | Required | Notes |
| -------------------- | ------------------------------------------------------------ | -------- | ----- |
| `routeId`            | `string`                                                     | required | —     |
| `effectivePaths`     | `readonly string[]`                                          | required | —     |
| `surface`            | `'api' \| 'ui'`                                              | required | —     |
| `kind`               | `string`                                                     | required | —     |
| `owningCapability`   | `string`                                                     | required | —     |
| `contractVersion`    | `string`                                                     | required | —     |
| `lifecycle`          | [Lifecycle](./capability.md#lifecycle)                       | required | —     |
| `host`               | [Host](./capability.md#host)                                 | required | —     |
| `audiences`          | `readonly Audience[]` — [Audience](./capability.md#audience) | required | —     |
| `scope`              | [RouteScope](#routescope)                                    | required | —     |
| `dataClassification` | [DataClassification](./capability.md#dataclassification)     | required | —     |
| `flags`              | `readonly string[]`                                          | required | —     |
| `shareSafety`        | `ShareSafety \| null` — [ShareSafety](#sharesafety)          | required | —     |

#### RouteScope

```ts
(typeof ROUTE_SCOPES)[number];
```

#### RouteSurface

An API route or a UI route, never a thing that is both.

```ts
| { readonly surface: 'api'; readonly method: HttpMethod }
| { readonly surface: 'ui'; readonly uiKind: UiKind }
```

#### RouteValidationOptions

| Field                 | Type                                                                                   | Required | Notes                                                                  |
| --------------------- | -------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------- |
| `knownCapabilities`   | `readonly string[]`                                                                    | optional | Capability ids the registry knows. Empty means the check does not run. |
| `capabilityAudiences` | `Readonly<Record<string, readonly Audience[]>>` — [Audience](./capability.md#audience) | optional | Audiences each capability serves, so a route cannot widen one.         |

#### RouteViolation

| Field     | Type                                                                                                                                                                                                                               | Required | Notes |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----- |
| `kind`    | `\| 'duplicate-route-id' \| 'duplicate-effective-path' \| 'unknown-capability' \| 'unknown-parent' \| 'unnavigable-parent' \| 'redirect-cycle' \| 'redirect-to-missing' \| 'redirect-to-retired' \| 'audience-exceeds-capability'` | required | —     |
| `subject` | `string`                                                                                                                                                                                                                           | required | —     |
| `detail`  | `string`                                                                                                                                                                                                                           | required | —     |

#### SCOPE_BINDINGS

Values: `path-parameter`, `session`

#### ScopeBinding

```ts
(typeof SCOPE_BINDINGS)[number];
```

#### SHARE_SAFETY

Values: `public`, `tenant-only`, `never-share`

#### ShareSafety

```ts
(typeof SHARE_SAFETY)[number];
```

#### UI_KINDS

Values: `page`, `panel`, `dialog`, `overlay`, `wizard-step`

#### UiKind

```ts
(typeof UI_KINDS)[number];
```

#### validateRoutes

```ts
validateRoutes(routes: readonly RouteDescriptor[], options: RouteValidationOptions = {}): readonly RouteViolation[]
```

## Valid examples

No committed fixture corpus covers this page's accepted cases; they are
unit-level and live in the module's own spec.

## Invalid examples

##### descriptor/alias-repeats-canonical-host

the alias list is what a route is ALSO reachable from, and including the
canonical host makes a duplicate-path check see two

Must produce: `invariant-violated`

```json
{
  "audiences": ["creator"],
  "contractVersion": "1.0.0",
  "dataClassification": "internal",
  "deepLink": null,
  "flags": [],
  "host": "studio-web",
  "hostAliases": ["studio-web"],
  "lifecycle": "general-availability",
  "navigation": null,
  "owningCapability": "capability:workbench-shell",
  "path": "/studio",
  "redirectTo": null,
  "roles": [],
  "routeId": "studio.unnamed",
  "scope": "platform",
  "scopeBinding": null,
  "surface": "ui",
  "uiKind": "page"
}
```

##### descriptor/api-route-with-navigation

a menu entry that resolves to a JSON endpoint is a link nobody can follow

Must produce: `invariant-violated`

```json
{
  "audiences": ["creator"],
  "contractVersion": "1.0.0",
  "dataClassification": "internal",
  "deepLink": null,
  "flags": [],
  "host": "studio-web",
  "hostAliases": [],
  "lifecycle": "general-availability",
  "method": "GET",
  "navigation": {
    "breadcrumb": "inherit",
    "discoverability": "listed",
    "iconKey": null,
    "labelKey": "nav.studio.workbench",
    "order": 10,
    "parentRouteId": null,
    "placement": "primary",
    "target": "in-app"
  },
  "owningCapability": "capability:workbench-shell",
  "path": "/studio",
  "redirectTo": null,
  "roles": [],
  "routeId": "studio.unnamed",
  "scope": "platform",
  "scopeBinding": null,
  "surface": "api"
}
```

##### descriptor/deep-link-entity-not-in-path

a link built from it would resolve to the route's default entity, not the one
shared

Must produce: `invariant-violated`

```json
{
  "audiences": ["creator"],
  "contractVersion": "1.0.0",
  "dataClassification": "internal",
  "deepLink": {
    "anchorKinds": [],
    "entityParameter": "itemId",
    "expirySeconds": 3600,
    "filterKeys": [],
    "inspectorKeys": [],
    "shareSafety": "tenant-only",
    "subviews": []
  },
  "flags": [],
  "host": "studio-web",
  "hostAliases": [],
  "lifecycle": "general-availability",
  "navigation": null,
  "owningCapability": "capability:workbench-shell",
  "path": "/studio/items",
  "redirectTo": null,
  "roles": [],
  "routeId": "studio.unnamed",
  "scope": "platform",
  "scopeBinding": null,
  "surface": "ui",
  "uiKind": "page"
}
```

3 of 24 refused case(s) shown. The full corpus is committed at
`evidence/v1-workbenches/workbench-kit-route-fixtures.json` and is what the gate
runs.

## Authorization and scope

| Symbol                         | Type          | Notes |
| ------------------------------ | ------------- | ----- | --- |
| `ROUTE_SCOPES`                 | `enumeration` | —     |
| `RouteDescriptor.scope`        | `RouteScope`  | —     |
| `RouteDescriptor.scopeBinding` | `ScopeBinding | null` | —   |
| `RouteInventoryRow.scope`      | `RouteScope`  | —     |
| `RouteScope`                   | `type`        | —     |
| `SCOPE_BINDINGS`               | `enumeration` | —     |
| `ScopeBinding`                 | `type`        | —     |

## Idempotency and concurrency

Not applicable: nothing on this page is retried or applied twice: these are
declarations, not operations.

## Pagination

Not applicable: nothing on this page returns a collection a caller reads in
pages.

## State and failure

| Symbol                            | Type                       | Notes                                                     |
| --------------------------------- | -------------------------- | --------------------------------------------------------- |
| `FLAG_UNAVAILABLE_BEHAVIOUR`      | `enumeration`              | —                                                         |
| `FlagRequirement.whenUnavailable` | `FlagUnavailableBehaviour` | What a consumer does when the flag service cannot answer. |
| `FlagUnavailableBehaviour`        | `type`                     | —                                                         |

## Compatibility

| Symbol                              | Type              | Notes |
| ----------------------------------- | ----------------- | ----- |
| `RouteDescriptor.contractVersion`   | `SemanticVersion` | —     |
| `RouteInventoryRow.contractVersion` | `string`          | —     |

## Deprecation

| Symbol                        | Type        | Notes |
| ----------------------------- | ----------- | ----- |
| `RouteDescriptor.lifecycle`   | `Lifecycle` | —     |
| `RouteInventoryRow.lifecycle` | `Lifecycle` | —     |

## Evidence

- `evidence/v1-workbenches/workbench-kit-export-map.json`
- `evidence/v1-workbenches/workbench-kit-route-fixtures.json`
- `libs/oshun/workbench-kit/src/routes.ts`
