Eve library

Route

Evidence

Revision 1

On this page

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 enumeration —
BreadcrumbMode type —
DeepLinkDescriptor interface —
Discoverability type —
DISCOVERABILITY enumeration —
effectivePaths function Every host a route answers on: the canonical one plus its aliases.
findRedirectCycles function —
FLAG_TARGETING enumeration —
FLAG_UNAVAILABLE_BEHAVIOUR enumeration —
FlagRequirement interface —
FlagTargeting type —
FlagUnavailableBehaviour type —
hostNavigation function —
HostNavigation interface —
HTTP_METHODS enumeration —
HttpMethod type —
NAV_PLACEMENTS enumeration —
NAV_TARGETS enumeration —
navigationAccountsForEveryRoute function Every route in the set is either in the tree or in the exclusion list.
NavigationExclusion interface —
NavigationNode interface —
NavigationPlacement interface —
NavPlacement type —
NavTarget type —
ParsedPath interface —
parseRouteDescriptor function —
parseRoutePath function —
ROUTE_SCOPES enumeration —
RouteDescriptor interface —
routeInventory function —
RouteInventoryRow interface —
RouteScope type —
RouteSurface type An API route or a UI route, never a thing that is both.
RouteValidationOptions interface —
RouteViolation interface —
SCOPE_BINDINGS enumeration —
ScopeBinding type —
SHARE_SAFETY enumeration —
ShareSafety type —
UI_KINDS enumeration —
UiKind type —
validateRoutes function —

Shapes#

Values: inherit, replace, hidden

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 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 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 required —
dependsOn string | null required —
expiresAt Instant | null — Instant required Exactly one of expiresAt and permanentReason is set.
permanentReason string | null required —
whenUnavailable 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 required —
audience Audience required —
tree readonly NavigationNode[] — NavigationNode required —
excluded readonly 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];

Values: primary, secondary, utility, contextual

Values: in-app, new-tab, embedded

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[] }
Field Type Required Notes
routeId string required —
reason | 'no-navigation-placement' | 'different-host' | 'audience-not-permitted' | 'not-discoverable' | 'retired' required —
Field Type Required Notes
routeId string required —
labelKey string required —
iconKey string | null required —
order number required —
placement NavPlacement required —
target NavTarget required —
children readonly NavigationNode[] — NavigationNode required —
Field Type Required Notes
placement NavPlacement required —
labelKey string required i18n KEYS, never literal text.
iconKey string | null required —
order number required —
parentRouteId string | null required —
breadcrumb BreadcrumbMode required —
discoverability Discoverability required —
target NavTarget required —
ts
(typeof NAV_PLACEMENTS)[number];
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 required —
path string required —
parameters readonly string[] required —
owningCapability CapabilityId required —
contractVersion SemanticVersion required —
lifecycle Lifecycle required —
redirectTo string | null required Where a retired or deprecated route sends a caller.
host Host required —
hostAliases readonly Host[] — Host required —
audiences readonly Audience[] — Audience required —
roles readonly string[] required —
scope RouteScope required —
scopeBinding ScopeBinding | null — ScopeBinding required —
dataClassification DataClassification required —
navigation NavigationPlacement | null — NavigationPlacement required —
deepLink DeepLinkDescriptor | null — DeepLinkDescriptor required —
flags readonly 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 required —
host Host required —
audiences readonly Audience[] — Audience required —
scope RouteScope required —
dataClassification DataClassification required —
flags readonly string[] required —
shareSafety ShareSafety | null — 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 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"
}

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