@astrale-os/cli 0.8.0-alpha.0 → 0.8.1-alpha.2

package/src/{kernel/run.ts → connection/command.ts}

@@ -1,19 +1,19 @@
 import chalk from 'chalk'
 
-import type { ClientContext } from './client'
-import type { KernelCommandOpts } from './types'
+import type { ConnectionContext } from './session'
+import type { ConnectionOptions } from './target'
 
 import { formatElapsed } from '../lib/format'
 import { spinner } from '../lib/log'
 import { isMachine, present } from '../lib/output'
-import { withKernelClient } from './client'
 import { formatKernelError } from './errors'
+import { withClientSession } from './session'
 
-type RunOpts<T> = {
-  opts: KernelCommandOpts
-  label: string
-  fn: (ctx: ClientContext) => Promise<T>
-  format?: (result: T, opts: KernelCommandOpts, isRaw: boolean) => void | Promise<void>
+export interface KernelCommandOpts extends ConnectionOptions {
+  readonly raw?: boolean
+  readonly json?: boolean
+  readonly format?: 'yaml' | 'json'
+  readonly debug?: boolean
 }
 
 /**
@@ -24,21 +24,30 @@ type RunOpts<T> = {
  * `format` callback for custom output. If `format` is omitted, the
  * result is passed to the standard `output()` function.
  */
-export async function runKernelCommand<T>(run: RunOpts<T>): Promise<void> {
-  const { opts, label, fn } = run
+export async function runKernelCommand<T>(input: {
+  readonly opts: KernelCommandOpts
+  readonly label: string
+  readonly fn: (context: ConnectionContext) => Promise<T>
+  readonly format?: (
+    result: T,
+    options: KernelCommandOpts,
+    machine: boolean,
+  ) => void | Promise<void>
+}): Promise<void> {
+  const { opts, label, fn } = input
   const isRaw = isMachine(opts)
   const spin = !isRaw ? spinner(`${label}...`) : null
   const startTime = performance.now()
 
   try {
-    const result = await withKernelClient(opts, fn)
+    const result = await withClientSession(opts, fn)
     const elapsed = performance.now() - startTime
 
     spin?.succeed(`${label} ${chalk.dim(formatElapsed(elapsed))}`)
     if (!isRaw) console.log('')
 
-    if (run.format) {
-      await run.format(result, opts, isRaw)
+    if (input.format) {
+      await input.format(result, opts, isRaw)
     } else {
       present(result, opts)
     }

package/src/connection/credential.ts

@@ -0,0 +1,114 @@
+import type { Fetch } from '@astrale-os/kernel-client'
+import type { SessionAuth } from '@astrale-os/kernel-client/session'
+
+import { credential, type IssuerId } from '@astrale-os/sdk/auth'
+
+import type { AstraleConfig } from '../lib/config'
+import type { ConnectionOptions, ConnectionTarget } from './target'
+
+import { AstraleError } from '../errors'
+import { resolveCredential } from './auth'
+import { createExchangeCredentialResolver } from './exchange'
+import { registrationKeyForTarget } from './target'
+
+const DELEGATION_TTL_SECONDS = 60
+
+export interface SourceCredentialResolver {
+  resolve(audience: IssuerId, signal: AbortSignal): Promise<string>
+}
+
+/** Resolve source authority; an omitted Session delegation preserves exact current authority. */
+export function createConnectionCredential(
+  expectedSourceIssuer: IssuerId,
+  source: SourceCredentialResolver,
+): SessionAuth {
+  const resolveSource = source.resolve.bind(source)
+  return Object.freeze({
+    ttlSeconds: DELEGATION_TTL_SECONDS,
+    async resolve(
+      _call: Parameters<SessionAuth['resolve']>[0],
+      signal: Parameters<SessionAuth['resolve']>[1],
+    ) {
+      const resolved = await resolveSource(expectedSourceIssuer, signal)
+      const ttlSeconds = sourceBoundDelegationTtl(resolved)
+      return Object.freeze({
+        credential: resolved,
+        ...(ttlSeconds === undefined ? {} : { delegate: { ttlSeconds } }),
+      })
+    },
+  })
+}
+
+/** Never request a destination carrier that could outlive its current source bearer. */
+function sourceBoundDelegationTtl(input: string): number | undefined {
+  try {
+    const expiresAt = credential.inspect(input).claims.exp
+    if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt)) return undefined
+    const remaining = expiresAt - Math.ceil(Date.now() / 1_000) - 1
+    return Math.max(1, Math.min(DELEGATION_TTL_SECONDS, remaining))
+  } catch {
+    // Preserve opaque explicit credentials; the Kernel remains their authority.
+    return undefined
+  }
+}
+
+/** Bind CLI identity state and Core Auth delegation to one Session auth capability. */
+export function createCliCredential(
+  target: ConnectionTarget,
+  options: ConnectionOptions,
+  config: AstraleConfig,
+  fetch: Fetch = globalThis.fetch,
+  timeoutMs = 30_000,
+): SessionAuth | undefined {
+  validateCredentialSelection(options)
+  if (options.anonymous === true) return undefined
+  const authOptions = Object.freeze({
+    ...(options.as === undefined ? {} : { as: options.as }),
+    ...(options.creds === undefined ? {} : { creds: options.creds }),
+    ...(target.defaultIdentity === undefined ? {} : { defaultIdentity: target.defaultIdentity }),
+  })
+  const source: SourceCredentialResolver = {
+    async resolve(audience, signal) {
+      requireLive(signal)
+      const credential = await resolveCredential(
+        authOptions,
+        config,
+        audience,
+        registrationKeyForTarget(target),
+      )
+      requireLive(signal)
+      return credential
+    },
+  }
+  const effective =
+    target.domainIssuer === undefined || options.creds !== undefined
+      ? source
+      : createExchangeCredentialResolver(
+          { ...target, domainIssuer: target.domainIssuer },
+          source,
+          fetch,
+          timeoutMs,
+        )
+  return createConnectionCredential(target.kernelIssuer, effective)
+}
+
+/** Reject contradictory explicit credential selections before identity or network access. */
+export function validateCredentialSelection(options: ConnectionOptions): void {
+  if (options.anonymous !== true) return
+  const conflicting = [
+    ...(options.as === undefined ? [] : ['--as']),
+    ...(options.creds === undefined ? [] : ['--creds']),
+  ]
+  if (conflicting.length === 0) return
+  throw new AstraleError(
+    'INVALID_FLAG',
+    `--anonymous cannot be combined with ${conflicting.join(' or ')}.`,
+  )
+}
+
+function requireLive(signal: AbortSignal): void {
+  if (!signal.aborted) return
+  throw signal.reason instanceof Error
+    ? signal.reason
+    : new DOMException('The operation was aborted.', 'AbortError')
+}

package/src/{kernel → connection}/errors.ts

@@ -1,6 +1,6 @@
 import chalk from 'chalk'
 
-import type { SelfExpansionMeta } from './expand'
+import type { SelfExpansionMeta } from './self'
 
 import { AstraleError } from '../errors'
 import { decodeJwtExpiration, readLocalStatus, type LocalStatus } from '../lib/local-status'
@@ -120,7 +120,7 @@ export async function formatKernelError(
       const selfMeta = (error as Error & { expandedFromSelf?: SelfExpansionMeta }).expandedFromSelf
       // kernel-client maps both NOT_FOUND (the node doesn't exist) and
       // METHOD_NOT_FOUND (the method doesn't exist on a real node) to
-      // `NotFoundError`. Firing the "refresh registration" hint for the
+      // `NotFoundError`. Firing the authenticated-principal hint for the
       // method case is misleading. Gate on the message referencing the
       // expanded id — node lookup errors mention `@<id>` whereas method
       // errors mention the method path.
@@ -133,13 +133,11 @@ export async function formatKernelError(
         log.error(`Not found: ${cleanMsg}`)
         log.dim('  Check the path/ID and that the instance is booted')
         if (selfHintApplies && selfMeta) {
-          const who = selfMeta.identity ?? 'your identity'
           const where = selfMeta.slug ? ` on "${selfMeta.slug}"` : ''
-          log.dim(`  @self expanded to @${selfMeta.selfId} from ${who}'s registration${where}.`)
-          const fixCmd = `astrale identity register${
-            selfMeta.identity ? ` ${selfMeta.identity}` : ''
-          }${selfMeta.slug ? ` -i ${selfMeta.slug}` : ''}`
-          log.dim(`  If the node was deleted, refresh with: ${fixCmd}`)
+          log.dim(
+            `  @self resolved through authenticated Identity.whoami to @${selfMeta.selfId}${where}.`,
+          )
+          log.dim('  Check that the requested node path still exists for that principal.')
         }
       }
       break
@@ -176,6 +174,31 @@ export async function formatKernelError(
       break
     }
 
+    case 'ResponseError': {
+      const code = (error as { readonly code?: unknown }).code
+      const reason = (error as { readonly reason?: unknown }).reason
+      if (isRaw) {
+        writeRaw({
+          error: 'RESPONSE_ERROR',
+          ...(code === undefined ? {} : { code }),
+          message: error.message,
+          ...(reason === undefined ? {} : { reason }),
+        })
+      } else {
+        log.error(
+          `${chalk.bold(code === undefined ? 'RESPONSE_ERROR' : `RESPONSE_ERROR(${String(code)})`)}: ${error.message}`,
+        )
+        if (
+          reason !== null &&
+          typeof reason === 'object' &&
+          typeof (reason as { readonly code?: unknown }).code === 'string'
+        ) {
+          log.dim(`  reason: ${(reason as { readonly code: string }).code}`)
+        }
+      }
+      break
+    }
+
     case 'KernelError': {
       const code = (error as { code?: number | string }).code ?? 'UNKNOWN'
       const type = (error as { type?: string }).type ?? 'KERNEL_ERROR'
@@ -194,7 +217,7 @@ export async function formatKernelError(
 }
 
 /** Strip internal `::methodName` suffixes from paths in error messages (e.g., "/path::listChildren" → "/path") */
-function stripMethodSuffix(msg: string): string {
+export function stripMethodSuffix(msg: string): string {
   return msg.replace(/(\/[^"\s:]+)::([a-zA-Z]\w*)/g, '$1')
 }
 

package/src/connection/exchange.ts

@@ -0,0 +1,274 @@
+import type { Fetch } from '@astrale-os/kernel-client'
+import type { IssuerId } from '@astrale-os/sdk/auth'
+
+import { call, Client } from '@astrale-os/kernel-client'
+import { createAuth } from '@astrale-os/kernel-client/auth'
+import { credential, exchange as exchangeProtocol } from '@astrale-os/sdk/auth'
+
+import type { SourceCredentialResolver } from './credential'
+import type { ConnectionTarget } from './target'
+
+import { AstraleError } from '../errors'
+import { ExchangeCredentialCache } from '../state/exchange-credentials'
+
+const EXCHANGE_TTL_SECONDS = 120
+const MAXIMUM_RESPONSE_BYTES = 256 * 1024
+
+/** Exchange exact authenticated User authority for a Domain bearer bound to this Kernel. */
+export function createExchangeCredentialResolver(
+  target: ConnectionTarget & { readonly domainIssuer: IssuerId },
+  source: SourceCredentialResolver,
+  fetch: Fetch,
+  timeoutMs: number,
+  cache = new ExchangeCredentialCache(),
+): SourceCredentialResolver {
+  requireExchangeTransport(target)
+  return Object.freeze({
+    async resolve(kernelIssuer: IssuerId, signal: AbortSignal): Promise<string> {
+      requireLive(signal)
+      const sourceToken = await source.resolve(kernelIssuer, signal)
+      const delegationTtlSeconds = delegationLifetime(sourceToken)
+      requireLive(signal)
+
+      const client = new Client({ url: `${kernelIssuer}/invoke`, fetch, timeoutMs })
+      try {
+        const authenticated = client.as(sourceToken)
+        const auth = createAuth((path, input, options) =>
+          authenticated.call(call(path, input), {
+            ...options,
+            delegate: { ttlSeconds: delegationTtlSeconds },
+          }),
+        )
+        const user = await auth.whoami({ signal })
+        const key = Object.freeze({
+          kernelIssuer,
+          domainIssuer: target.domainIssuer,
+          user: user.id,
+        })
+        return await cache.getOrRefresh(key, async () => {
+          let envelope: string | undefined
+          for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+              envelope = await auth.delegate(
+                user.id,
+                {
+                  audience: target.domainIssuer,
+                  ttlSeconds: delegationTtlSeconds,
+                  attenuation: { kind: 'identity', self: true },
+                },
+                { signal },
+              )
+              break
+            } catch (cause) {
+              if (attempt === 2 || !unknownFunctionOutcome(cause)) throw cause
+            }
+          }
+          if (envelope === undefined) throw new Error('Token delegation returned no credential.')
+          return exchange(target.domainIssuer, kernelIssuer, envelope, fetch, signal)
+        })
+      } finally {
+        client.close()
+      }
+    },
+  })
+}
+
+function unknownFunctionOutcome(cause: unknown): boolean {
+  if (cause === null || typeof cause !== 'object') return false
+  const error = cause as { readonly code?: unknown; readonly reason?: unknown }
+  if (error.code === 5002) return true
+  if (error.reason === null || typeof error.reason !== 'object') return false
+  return (error.reason as { readonly code?: unknown }).code === 'FUNCTION_OUTCOME_UNKNOWN'
+}
+
+function delegationLifetime(sourceToken: string): number {
+  const expiresAt = credential.inspect(sourceToken).claims.exp
+  if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt)) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_SOURCE_INVALID',
+      'The source identity credential has no valid expiration.',
+    )
+  }
+  const remaining = expiresAt - Math.ceil(Date.now() / 1_000) - 1
+  if (!Number.isSafeInteger(remaining) || remaining < 1) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_SOURCE_EXPIRED',
+      'The source identity credential has no lifetime available for token exchange.',
+    )
+  }
+  return Math.min(EXCHANGE_TTL_SECONDS, remaining)
+}
+
+async function exchange(
+  domainIssuer: IssuerId,
+  kernelIssuer: IssuerId,
+  envelope: string,
+  fetch: Fetch,
+  signal: AbortSignal,
+): Promise<{ readonly credential: string; readonly expiresAt: number }> {
+  const configurationUrl = new URL(
+    exchangeProtocol.paths(domainIssuer).configuration,
+    domainIssuer,
+  ).toString()
+  const configurationResponse = await fetch(configurationUrl, {
+    method: 'GET',
+    redirect: 'error',
+    credentials: 'omit',
+    cache: 'no-store',
+    referrerPolicy: 'no-referrer',
+    headers: { accept: 'application/json' },
+    signal,
+  })
+  if (!configurationResponse.ok) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_DISCOVERY_FAILED',
+      `Domain issuer discovery failed with HTTP ${configurationResponse.status}.`,
+    )
+  }
+  const configuration = exchangeProtocol.acceptConfiguration(
+    await boundedJson(configurationResponse, signal),
+    domainIssuer,
+  )
+  const endpoint = configuration.token_exchange_endpoint
+  if (endpoint === undefined) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_UNSUPPORTED',
+      `Domain issuer ${domainIssuer} does not advertise token exchange.`,
+      'This command has no legacy token fallback.',
+    )
+  }
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    redirect: 'error',
+    credentials: 'omit',
+    cache: 'no-store',
+    referrerPolicy: 'no-referrer',
+    headers: {
+      authorization: `Bearer ${envelope}`,
+      accept: exchangeProtocol.MEDIA_TYPE,
+    },
+    signal,
+  })
+  const body = await boundedJson(response, signal)
+  if (!response.ok) {
+    let admitted: exchangeProtocol.ErrorResponse
+    try {
+      admitted = exchangeProtocol.acceptErrorResponse(body)
+    } catch (cause) {
+      throw new AstraleError(
+        'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+        `Token exchange failed with HTTP ${response.status} and an invalid error response.`,
+        cause instanceof Error ? cause.message : undefined,
+      )
+    }
+    throw new AstraleError(String(admitted.error.code), admitted.error.message)
+  }
+  requireExchangeResponseHeaders(response)
+  const exchanged = exchangeProtocol.acceptResponse(body)
+  const inspected = credential.inspect(exchanged.token)
+  if (
+    inspected.iss !== domainIssuer ||
+    inspected.aud !== kernelIssuer ||
+    inspected.claims.exp !== exchanged.expiresAt
+  ) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      'Token exchange returned a credential inconsistent with the requested Domain and Kernel.',
+    )
+  }
+  return Object.freeze({ credential: exchanged.token, expiresAt: exchanged.expiresAt })
+}
+
+function requireExchangeTransport(
+  target: ConnectionTarget & { readonly domainIssuer: IssuerId },
+): void {
+  const kernel = new URL(target.kernelIssuer)
+  const domain = new URL(target.domainIssuer)
+  if (domain.protocol === 'https:') return
+  if (domain.protocol === 'http:' && kernel.protocol === 'http:') return
+  throw new AstraleError(
+    'TOKEN_EXCHANGE_INSECURE',
+    'An HTTP Domain issuer is allowed only with an explicitly configured HTTP Kernel target.',
+  )
+}
+
+function requireExchangeResponseHeaders(response: Response): void {
+  const contentType = response.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase()
+  if (contentType !== exchangeProtocol.MEDIA_TYPE) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      'Token exchange returned an unsupported Content-Type.',
+    )
+  }
+  if (
+    !response.headers
+      .get('cache-control')
+      ?.toLowerCase()
+      .split(',')
+      .some((v) => v.trim() === 'no-store')
+  ) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      'Token exchange response is missing Cache-Control: no-store.',
+    )
+  }
+}
+
+async function boundedJson(response: Response, signal: AbortSignal): Promise<unknown> {
+  const declared = response.headers.get('content-length')
+  if (
+    declared !== null &&
+    (!/^\d+$/u.test(declared) || Number(declared) > MAXIMUM_RESPONSE_BYTES)
+  ) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      'Issuer response exceeds the size limit.',
+    )
+  }
+  if (response.body === null) {
+    throw new AstraleError('TOKEN_EXCHANGE_PROTOCOL_ERROR', 'Issuer response body is missing.')
+  }
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  try {
+    for (;;) {
+      requireLive(signal)
+      const next = await reader.read()
+      if (next.done) break
+      size += next.value.byteLength
+      if (size > MAXIMUM_RESPONSE_BYTES) {
+        throw new AstraleError(
+          'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+          'Issuer response exceeds the size limit.',
+        )
+      }
+      chunks.push(next.value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  try {
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)) as unknown
+  } catch (cause) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      'Issuer response is not valid UTF-8 JSON.',
+      cause instanceof Error ? cause.message : undefined,
+    )
+  }
+}
+
+function requireLive(signal: AbortSignal): void {
+  if (!signal.aborted) return
+  throw signal.reason instanceof Error
+    ? signal.reason
+    : new DOMException('The operation was aborted.', 'AbortError')
+}

package/src/connection/index.ts

@@ -0,0 +1,8 @@
+export { createPathCall } from './call'
+export { runKernelCommand } from './command'
+export type { KernelCommandOpts } from './command'
+export { expandSelfInCall, expandSelfInPath, withSelfHint } from './self'
+export type { SelfExpansionMeta } from './self'
+export { withAdminClientSession, withClientSession, type ConnectionContext } from './session'
+export { registrationKeyForTarget } from './target'
+export type { AdminConnectionOptions, ConnectionOptions, ConnectionTarget } from './target'

package/src/connection/self.ts

@@ -0,0 +1,120 @@
+import type { KernelCommandOpts } from './command'
+
+import { containsSelfRef, expandSelfReferences } from '../lib/self'
+import { withClientSession } from './session'
+
+/** Metadata attached to errors after an authenticated caller-authored @self expansion. */
+export interface SelfExpansionMeta {
+  readonly original: string
+  readonly expanded: string
+  readonly selfId: string
+  readonly slug?: string
+}
+
+/**
+ * Run `action`; if it throws a node NotFoundError, retain the authenticated
+ * expansion for precise diagnostics. The error is re-thrown either way.
+ */
+export async function withSelfHint<T>(
+  action: () => Promise<T>,
+  meta: SelfExpansionMeta | undefined,
+): Promise<T> {
+  if (!meta) return action()
+  try {
+    return await action()
+  } catch (err) {
+    if (err instanceof Error && err.name === 'NotFoundError') {
+      ;(err as Error & { expandedFromSelf?: SelfExpansionMeta }).expandedFromSelf = meta
+    }
+    throw err
+  }
+}
+
+type AuthenticatedSelf = {
+  readonly id?: unknown
+  readonly slug?: string
+}
+
+export type ResolveSelfIdDependencies = {
+  readonly whoami?: (opts: KernelCommandOpts) => Promise<AuthenticatedSelf>
+}
+
+/** Resolve @self only from the effective principal authenticated by the selected Kernel. */
+export async function resolveSelfIdAuthenticated(
+  opts: KernelCommandOpts,
+  dependencies: ResolveSelfIdDependencies = {},
+): Promise<{ readonly id: string; readonly slug?: string }> {
+  const resolved = await (dependencies.whoami ?? whoamiSelfId)(opts)
+  if (typeof resolved.id !== 'string' || resolved.id.trim().length === 0) {
+    const error = new Error(
+      '`@self` could not be resolved: authenticated Identity.whoami returned no NodeId.',
+    )
+    error.name = 'SelfResolutionError'
+    throw error
+  }
+  return resolved.slug === undefined
+    ? { id: resolved.id }
+    : { id: resolved.id, slug: resolved.slug }
+}
+
+async function whoamiSelfId(opts: KernelCommandOpts): Promise<AuthenticatedSelf> {
+  return withClientSession(opts, async ({ auth, target }) => ({
+    ...(await auth.whoami()),
+    ...(target.slug === undefined ? {} : { slug: target.slug }),
+  }))
+}
+
+/** Expand @self in path-like commands and return metadata for NotFound diagnostics. */
+export async function expandSelfInPath(
+  path: string,
+  options: KernelCommandOpts,
+): Promise<{ readonly path: string; readonly meta?: SelfExpansionMeta }> {
+  const expanded = await expandSelfValues(path, [], options)
+  return expanded.meta === undefined
+    ? { path: expanded.path }
+    : { path: expanded.path, meta: expanded.meta }
+}
+
+/** Expand @self once across one Call path and its CLI-authored string parameters. */
+export async function expandSelfInCall(
+  path: string,
+  parameters: readonly string[],
+  options: KernelCommandOpts,
+): Promise<{
+  readonly path: string
+  readonly parameters: readonly string[]
+  readonly meta?: SelfExpansionMeta
+}> {
+  return expandSelfValues(path, parameters, options)
+}
+
+async function expandSelfValues(
+  path: string,
+  parameters: readonly string[],
+  options: KernelCommandOpts,
+): Promise<{
+  readonly path: string
+  readonly parameters: readonly string[]
+  readonly meta?: SelfExpansionMeta
+}> {
+  if (!containsSelfRef(path) && !parameters.some(containsSelfRef)) {
+    return { path, parameters }
+  }
+  const self = await resolveSelfIdAuthenticated(options)
+  const expandedPath = expandSelfReferences(path, self.id)
+  const expandedParameters = parameters.map((parameter) => expandSelfReferences(parameter, self.id))
+  const changed =
+    expandedPath !== path ||
+    expandedParameters.some((parameter, index) => parameter !== parameters[index])
+  if (!changed) return { path, parameters }
+  return {
+    path: expandedPath,
+    parameters: expandedParameters,
+    meta: {
+      original: path,
+      expanded: expandedPath,
+      selfId: self.id,
+      ...(self.slug === undefined ? {} : { slug: self.slug }),
+    },
+  }
+}