@astrale-os/cli 1.0.0-beta.30 → 1.0.0-beta.32

package/src/connection/__tests__/exchange.test.ts

@@ -101,9 +101,7 @@ describe('Domain token exchange', () => {
       },
     })
     const delegatedTtl = kernelRequests[1]!.body!.call.input.ttlSeconds
-    expect(delegatedTtl).toBeGreaterThan(0)
-    expect(delegatedTtl).toBeGreaterThanOrEqual(295)
-    expect(delegatedTtl).toBeLessThanOrEqual(300)
+    expect(delegatedTtl).toBe(75)
     expect(sourceAudiences).toEqual([KERNEL, KERNEL])
     expect(
       observed.filter((entry) => entry.url.endsWith('/.well-known/astrale/token')),
@@ -173,6 +171,87 @@ describe('Domain token exchange', () => {
     })
   })
 
+  test('requests and retains a carrier that covers a supported long command deadline', async () => {
+    const expiresAt = Math.floor(Date.now() / 1_000) + 250
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', expiresAt)
+    const observed: Record<string, any>[] = []
+    const base = exchangeFetch(exchanged, { expiresAt })
+    const fetch: Fetch = async (input, init) => {
+      if (String(input) === INVOCATION) {
+        observed.push(JSON.parse(await new Response(init?.body).text()))
+      }
+      return base(input, init)
+    }
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => sourceToken('user-1', expiresAt + 50) },
+      fetch,
+      180_000,
+      new ExchangeCredentialCache(join(directory, 'long-credential.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).resolves.toBe(exchanged)
+    expect(observed[1]!.call.input.ttlSeconds).toBe(200)
+  })
+
+  /** @evidence TEST-CLI-EXCHANGE-REJECTS-INSUFFICIENT-LIFETIME */
+  test('rejects a too-short Domain exchange credential before destination dispatch', async () => {
+    const expiresAt = Math.floor(Date.now() / 1_000) + 150
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', expiresAt)
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => sourceToken('user-1', expiresAt + 150) },
+      exchangeFetch(exchanged, { expiresAt }),
+      180_000,
+      new ExchangeCredentialCache(join(directory, 'short-credential.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_LIFETIME_INSUFFICIENT',
+    })
+  })
+
+  test('rejects a long outer Domain token whose carried Kernel proof is too short', async () => {
+    const outerExpiresAt = Math.floor(Date.now() / 1_000) + 250
+    const proofExpiresAt = Math.floor(Date.now() / 1_000) + 150
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', outerExpiresAt, proofExpiresAt)
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => sourceToken('user-1', outerExpiresAt + 50) },
+      exchangeFetch(exchanged, { expiresAt: outerExpiresAt }),
+      180_000,
+      new ExchangeCredentialCache(join(directory, 'short-proof.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_LIFETIME_INSUFFICIENT',
+    })
+  })
+
+  test('rejects the real 300-second Domain ceiling for a 600-second command before destination dispatch', async () => {
+    const expiresAt = Math.floor(Date.now() / 1_000) + 300
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', expiresAt)
+    const observed: string[] = []
+    const base = exchangeFetch(exchanged, { expiresAt })
+    const fetch: Fetch = async (input, init) => {
+      observed.push(String(input))
+      return base(input, init)
+    }
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => sourceToken('user-1', expiresAt + 700) },
+      fetch,
+      600_000,
+      new ExchangeCredentialCache(join(directory, 'domain-ceiling.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_LIFETIME_INSUFFICIENT',
+    })
+    expect(observed.filter((url) => url === INVOCATION)).toHaveLength(2)
+    expect(observed.filter((url) => url.endsWith('/.well-known/astrale/token'))).toHaveLength(1)
+  })
+
   test('rejects success responses without no-store or with malformed fields', async () => {
     const exchanged = token(DOMAIN, KERNEL, 'user-1', EXPIRES_AT)
     const cache = () => new ExchangeCredentialCache(join(directory, crypto.randomUUID()))
@@ -237,7 +316,11 @@ describe('Domain token exchange', () => {
 
 function exchangeFetch(
   exchanged: string,
-  options: { readonly body?: unknown; readonly cacheControl?: boolean } = {},
+  options: {
+    readonly body?: unknown
+    readonly cacheControl?: boolean
+    readonly expiresAt?: number
+  } = {},
 ): Fetch {
   return async (input, init) => {
     const url = String(input)
@@ -253,7 +336,9 @@ function exchangeFetch(
     }
     if (url.endsWith('/.well-known/openid-configuration')) return jsonResponse(configuration(true))
     const response = new Response(
-      JSON.stringify(options.body ?? { token: exchanged, expiresAt: EXPIRES_AT }),
+      JSON.stringify(
+        options.body ?? { token: exchanged, expiresAt: options.expiresAt ?? EXPIRES_AT },
+      ),
       {
         status: 200,
         headers: {
@@ -290,13 +375,13 @@ function jsonResponse(value: unknown, status = 200, contentType = 'application/j
   })
 }
 
-function token(iss: string, aud: string, user: string, exp: number): string {
+function token(iss: string, aud: string, user: string, exp: number, proofExp = exp): string {
   const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
   const proof = `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
     iss: aud,
     sub: user,
     aud,
-    exp,
+    exp: proofExp,
     delegation: { v: 1, expr: { kind: 'identity', id: user } },
   })}.signature`
   return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
@@ -308,12 +393,12 @@ function token(iss: string, aud: string, user: string, exp: number): string {
   })}.signature`
 }
 
-function sourceToken(subject: string | undefined): string {
+function sourceToken(subject: string | undefined, expiresAt = SOURCE_EXPIRES_AT): string {
   const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
   return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
     iss: 'https://workos.example',
     ...(subject === undefined ? {} : { sub: subject }),
     aud: KERNEL,
-    exp: SOURCE_EXPIRES_AT,
+    exp: expiresAt,
   })}.signature`
 }

package/src/connection/auth.ts

@@ -47,7 +47,12 @@ export async function bindCredentialIdentity<Options extends ConnectionOptions>(
  *      registration for the target instance, use that target-issued `(iss, sub)`.
  */
 export async function resolveCredential(
-  opts: { as?: string; creds?: string; defaultIdentity?: string },
+  opts: {
+    as?: string
+    creds?: string
+    defaultIdentity?: string
+    minimumRemainingSeconds?: number
+  },
   config: AstraleConfig,
   audience: string = config.issuer,
   registrationKey?: string,
@@ -69,7 +74,12 @@ export async function resolveCredential(
       resolvedIdentity = identity
       resolvedName = identityName
       if ((identity.source ?? 'key') === 'idp')
-        return await resolveIdpAccessToken(identityName, identity, audience)
+        return await resolveIdpAccessToken(
+          identityName,
+          identity,
+          audience,
+          opts.minimumRemainingSeconds,
+        )
       return await signAs(
         identity.subject,
         KEYS_DIR,
@@ -81,7 +91,12 @@ export async function resolveCredential(
     resolvedIdentity = identity
     resolvedName = identity.name
     if ((identity.source ?? 'key') === 'idp') {
-      return await resolveIdpAccessToken(identity.name, identity, audience)
+      return await resolveIdpAccessToken(
+        identity.name,
+        identity,
+        audience,
+        opts.minimumRemainingSeconds,
+      )
     }
 
     return await signAs(
@@ -164,10 +179,11 @@ async function resolveIdpAccessToken(
   identityName: string,
   identity: Identity,
   audience: string,
+  minimumRemainingSeconds?: number,
 ): Promise<string> {
   let resolved
   try {
-    resolved = await ensureFreshSession(identityName, { audience })
+    resolved = await ensureFreshSession(identityName, { audience, minimumRemainingSeconds })
   } catch (e) {
     if (e instanceof IdpSessionMissingError) {
       throw new Error(

package/src/connection/credential.ts

@@ -7,8 +7,10 @@ import type { AstraleConfig } from '../lib/config'
 import type { ConnectionOptions, ConnectionTarget } from './target'
 
 import { AstraleError } from '../errors'
+import { remainingCredentialLifetimeSeconds } from '../lib/credential-lifetime'
 import { resolveCredential } from './auth'
 import { createExchangeCredentialResolver } from './exchange'
+import { exchangeCredentialTtlSeconds, invocationCredentialTtlSeconds } from './lifetime'
 import { registrationKeyForTarget } from './target'
 
 const DELEGATION_TTL_SECONDS = 60
@@ -21,32 +23,46 @@ export interface SourceCredentialResolver {
 export function createConnectionCredential(
   expectedSourceIssuer: IssuerId,
   source: SourceCredentialResolver,
+  ttlSeconds = DELEGATION_TTL_SECONDS,
 ): SessionAuth {
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1) {
+    throw new TypeError('Connection credential ttlSeconds must be a positive safe integer.')
+  }
   const resolveSource = source.resolve.bind(source)
   return Object.freeze({
-    ttlSeconds: DELEGATION_TTL_SECONDS,
+    ttlSeconds,
     async resolve(
       _call: Parameters<SessionAuth['resolve']>[0],
       signal: Parameters<SessionAuth['resolve']>[1],
     ) {
       const resolved = await resolveSource(expectedSourceIssuer, signal)
-      const ttlSeconds = sourceBoundDelegationTtl(resolved)
+      const delegatedTtlSeconds = sourceBoundDelegationTtl(resolved, ttlSeconds)
       return Object.freeze({
         credential: resolved,
-        ...(ttlSeconds === undefined ? {} : { delegate: { ttlSeconds } }),
+        ...(delegatedTtlSeconds === undefined
+          ? {}
+          : { delegate: { ttlSeconds: delegatedTtlSeconds } }),
       })
     },
   })
 }
 
 /** Never request a destination carrier that could outlive its current source bearer. */
-function sourceBoundDelegationTtl(input: string): number | undefined {
+function sourceBoundDelegationTtl(input: string, requestedTtlSeconds: number): 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 {
+    const remaining = remainingCredentialLifetimeSeconds(expiresAt)
+    if (remaining < requestedTtlSeconds) {
+      throw new AstraleError(
+        'CREDENTIAL_LIFETIME_INSUFFICIENT',
+        'The selected credential cannot cover the requested command timeout.',
+        `Use a fresh identity session or a shorter --timeout; ${Math.max(0, remaining)} seconds remain but ${requestedTtlSeconds} are required.`,
+      )
+    }
+    return Math.max(1, Math.min(requestedTtlSeconds, remaining))
+  } catch (cause) {
+    if (cause instanceof AstraleError) throw cause
     // Preserve opaque explicit credentials; the Kernel remains their authority.
     return undefined
   }
@@ -66,6 +82,10 @@ export function createCliCredential(
     ...(options.as === undefined ? {} : { as: options.as }),
     ...(options.creds === undefined ? {} : { creds: options.creds }),
     ...(target.defaultIdentity === undefined ? {} : { defaultIdentity: target.defaultIdentity }),
+    minimumRemainingSeconds:
+      target.domainIssuer === undefined
+        ? invocationCredentialTtlSeconds(timeoutMs)
+        : exchangeCredentialTtlSeconds(timeoutMs),
   })
   const source: SourceCredentialResolver = {
     async resolve(audience, signal) {
@@ -89,7 +109,8 @@ export function createCliCredential(
           fetch,
           timeoutMs,
         )
-  return createConnectionCredential(target.kernelIssuer, effective)
+  const ttlSeconds = invocationCredentialTtlSeconds(timeoutMs)
+  return createConnectionCredential(target.kernelIssuer, effective, ttlSeconds)
 }
 
 /** Reject contradictory explicit credential selections before identity or network access. */

package/src/connection/exchange.ts

@@ -2,16 +2,17 @@ import type { IssuerId } from '@astrale-os/sdk/auth'
 import type { Fetch } from '@astrale-os/sdk/client'
 
 import { createAuth } from '@astrale-os/sdk/auth'
-import { credential, exchange as exchangeProtocol } from '@astrale-os/sdk/auth'
+import { credential, exchange as exchangeProtocol, grant } from '@astrale-os/sdk/auth'
 import { call, Client } from '@astrale-os/sdk/client'
 
 import type { SourceCredentialResolver } from './credential'
 import type { ConnectionTarget } from './target'
 
 import { AstraleError } from '../errors'
+import { remainingCredentialLifetimeSeconds } from '../lib/credential-lifetime'
 import { ExchangeCredentialCache } from '../state/exchange-credentials'
+import { cachedCredentialTtlSeconds, exchangeCredentialTtlSeconds } from './lifetime'
 
-const EXCHANGE_TTL_SECONDS = 5 * 60
 const MAXIMUM_RESPONSE_BYTES = 256 * 1024
 
 /** Exchange exact authenticated User authority for a Domain bearer bound to this Kernel. */
@@ -23,6 +24,8 @@ export function createExchangeCredentialResolver(
   cache = new ExchangeCredentialCache(),
 ): SourceCredentialResolver {
   requireExchangeTransport(target)
+  const cacheTtlSeconds = cachedCredentialTtlSeconds(timeoutMs)
+  const exchangeTtlSeconds = exchangeCredentialTtlSeconds(timeoutMs)
   return Object.freeze({
     async resolve(kernelIssuer: IssuerId, signal: AbortSignal): Promise<string> {
       requireLive(signal)
@@ -37,8 +40,9 @@ export function createExchangeCredentialResolver(
           sourceIssuer: sourceIdentity.issuer,
           sourceSubject: sourceIdentity.subject,
         }),
+        cacheTtlSeconds,
         async () => {
-          const delegationTtlSeconds = delegationLifetime(sourceToken)
+          const delegationTtlSeconds = delegationLifetime(sourceToken, exchangeTtlSeconds)
           const client = new Client({ url: `${kernelIssuer}/invoke`, fetch, timeoutMs })
           try {
             const authenticated = client.as(sourceToken)
@@ -69,7 +73,14 @@ export function createExchangeCredentialResolver(
             }
             if (envelope === undefined) throw new Error('Token delegation returned no credential.')
             return {
-              ...(await exchange(target.domainIssuer, kernelIssuer, envelope, fetch, signal)),
+              ...(await exchange(
+                target.domainIssuer,
+                kernelIssuer,
+                envelope,
+                cacheTtlSeconds,
+                fetch,
+                signal,
+              )),
               user: user.id,
               sourceIssuer: sourceIdentity.issuer,
               sourceSubject: sourceIdentity.subject,
@@ -107,7 +118,7 @@ function unknownFunctionOutcome(cause: unknown): boolean {
   return (error.reason as { readonly code?: unknown }).code === 'FUNCTION_OUTCOME_UNKNOWN'
 }
 
-function delegationLifetime(sourceToken: string): number {
+function delegationLifetime(sourceToken: string, requiredTtlSeconds: number): number {
   const expiresAt = credential.inspect(sourceToken).claims.exp
   if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt)) {
     throw new AstraleError(
@@ -115,20 +126,28 @@ function delegationLifetime(sourceToken: string): number {
       'The source identity credential has no valid expiration.',
     )
   }
-  const remaining = expiresAt - Math.ceil(Date.now() / 1_000) - 1
+  const remaining = remainingCredentialLifetimeSeconds(expiresAt)
   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)
+  if (remaining < requiredTtlSeconds) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_SOURCE_LIFETIME_INSUFFICIENT',
+      'The source credential cannot cover the requested command timeout.',
+      `Refresh the identity session or use a shorter --timeout; ${remaining} seconds remain but ${requiredTtlSeconds} are required.`,
+    )
+  }
+  return requiredTtlSeconds
 }
 
 async function exchange(
   domainIssuer: IssuerId,
   kernelIssuer: IssuerId,
   envelope: string,
+  requiredTtlSeconds: number,
   fetch: Fetch,
   signal: AbortSignal,
 ): Promise<{ readonly credential: string; readonly expiresAt: number }> {
@@ -225,9 +244,48 @@ async function exchange(
       'Token exchange returned a credential inconsistent with the requested Domain and Kernel.',
     )
   }
+  const remaining = effectiveExchangeLifetime(inspected, exchanged.expiresAt)
+  if (remaining < requiredTtlSeconds) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_LIFETIME_INSUFFICIENT',
+      'The Domain exchange credential cannot cover the requested command timeout.',
+      `The Domain issuer returned ${Math.max(0, remaining)} seconds but ${requiredTtlSeconds} are required. Use a shorter --timeout or update the Domain execution service.`,
+    )
+  }
   return Object.freeze({ credential: exchanged.token, expiresAt: exchanged.expiresAt })
 }
 
+/** The outer Domain bearer and its carried Kernel proof must both survive the operation. */
+function effectiveExchangeLifetime(
+  inspected: ReturnType<typeof credential.inspect>,
+  outerExpiresAt: number,
+): number {
+  let proofExpiresAt: number
+  try {
+    const carried = grant.acceptUnresolved(inspected.claims.grant).expr
+    if (
+      carried.kind !== 'identity' ||
+      !('credential' in carried) ||
+      typeof carried.credential !== 'string'
+    ) {
+      throw new TypeError('Domain credential does not carry an identity proof.')
+    }
+    const value = credential.inspect(carried.credential).claims.exp
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+      throw new TypeError('Domain credential carries an identity proof without an expiration.')
+    }
+    proofExpiresAt = value
+  } catch (cause) {
+    if (!(cause instanceof TypeError)) throw cause
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      'Token exchange returned an invalid carried identity proof.',
+      cause.message,
+    )
+  }
+  return remainingCredentialLifetimeSeconds(Math.min(outerExpiresAt, proofExpiresAt))
+}
+
 async function fetchExchange(
   fetch: Fetch,
   input: string,

package/src/connection/lifetime.ts

@@ -0,0 +1,25 @@
+const MINIMUM_CREDENTIAL_TTL_SECONDS = 60
+const INVOCATION_RECEIPT_MARGIN_SECONDS = 5
+const CACHE_HANDOFF_MARGIN_SECONDS = 5
+const TOKEN_EXCHANGE_SETTLEMENT_MARGIN_SECONDS = 15
+
+/** Cover the complete command deadline while preserving the existing short-command floor. */
+export function invocationCredentialTtlSeconds(timeoutMs: number): number {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw new TypeError('Invocation credential timeout must be a positive safe integer.')
+  }
+  return Math.max(
+    MINIMUM_CREDENTIAL_TTL_SECONDS,
+    Math.ceil(timeoutMs / 1_000) + INVOCATION_RECEIPT_MARGIN_SECONDS,
+  )
+}
+
+/** Leave the final carrier lifetime intact after source delegation and issuer exchange settle. */
+export function exchangeCredentialTtlSeconds(timeoutMs: number): number {
+  return invocationCredentialTtlSeconds(timeoutMs) + TOKEN_EXCHANGE_SETTLEMENT_MARGIN_SECONDS
+}
+
+/** Refresh a cached token before the final Session carrier can cross a second boundary. */
+export function cachedCredentialTtlSeconds(timeoutMs: number): number {
+  return invocationCredentialTtlSeconds(timeoutMs) + CACHE_HANDOFF_MARGIN_SECONDS
+}

package/src/graph/.spec/api.d.ts

@@ -11,7 +11,7 @@ export function classKey(input: string, label: string): ClassKey
 /** Untrusted CLI fields used to author or admit one exact Query V6 request. */
 export interface QueryCommandInput {
   readonly sources: readonly string[]
-  readonly definition?: string
+  readonly class?: string
   readonly ast?: unknown
   readonly edge?: string
   readonly direction?: QueryDirection

package/src/graph/.spec/laws/documents.ts

@@ -1,14 +1,14 @@
 import { defineLaw } from '@astrale-os/spec/authoring'
 
-export const CLI_GRAPH_QUERY_V5 = defineLaw({
-  id: 'CLI-GRAPH-QUERY-V5',
+export const CLI_GRAPH_QUERY_V6 = defineLaw({
+  id: 'CLI-GRAPH-QUERY-V6',
   statement:
-    'CLI query input becomes exactly one canonical Query V5 document with an explicit finite limit; exact Property ordering and Node or Edge projection profiles are admitted through the canonical AST surface, while legacy versions and unsupported selector combinations fail before a Graph call.',
+    'CLI query input becomes exactly one canonical Query V6 document with an explicit finite limit; --class authors one exact Class source, exact Property ordering and Node or Edge projection profiles are admitted through the canonical AST surface, and legacy versions or unsupported selector combinations fail before a Graph call.',
   tests: [
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-AUTHORS-QUERY-V5' },
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-AUTHORS-DEFINITION-QUERY' },
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-QUERY-V5-ORDERING' },
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-QUERY-V5-PROJECTIONS' },
+    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-AUTHORS-QUERY-V6' },
+    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-AUTHORS-CLASS-QUERY' },
+    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-QUERY-V6-ORDERING' },
+    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-QUERY-V6-PROJECTIONS' },
     { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-REJECTS-LEGACY-QUERY' },
   ],
 })

package/src/graph/__tests__/query.test.ts

@@ -37,11 +37,11 @@ describe('prepareQuery', () => {
     })
   })
 
-  /** @evidence TEST-CLI-GRAPH-AUTHORS-DEFINITION-QUERY */
+  /** @evidence TEST-CLI-GRAPH-AUTHORS-CLASS-QUERY */
   test('authors an exact Class source without backend query text', () => {
     const prepared = prepareQuery({
       sources: [],
-      definition: '/:issues.astrale.ai:class.Issue',
+      class: '/:issues.astrale.ai:class.Issue',
       limit: '201',
     })
 
@@ -67,7 +67,7 @@ describe('prepareQuery', () => {
   test('unions positional Paths and one Class source in authored order', () => {
     const prepared = prepareQuery({
       sources: ['@note'],
-      definition: '/:issues.astrale.ai:class.Issue',
+      class: '/:issues.astrale.ai:class.Issue',
     })
 
     expect(JSON.parse(JSON.stringify(prepared.ast.source))).toEqual({
@@ -167,7 +167,14 @@ describe('prepareQuery', () => {
       prepareQuery({ sources: ['/:notes.example.dev:class.Note'], limit: 'all' }),
     ).toThrow('--limit must be a positive integer')
     expect(() =>
-      prepareQuery({ sources: [], definition: '/:notes.example.dev:view.note' }),
-    ).toThrow('--definition must be one canonical Class Path')
+      prepareQuery({
+        sources: [],
+        ast: {},
+        class: '/:notes.example.dev:class.Note',
+      }),
+    ).toThrow('--ast/--file cannot be combined with sources, --class, --edge, or --direction')
+    expect(() => prepareQuery({ sources: [], class: '/:notes.example.dev:view.note' })).toThrow(
+      '--class must be one canonical Class Path',
+    )
   })
 })

package/src/graph/query.ts

@@ -12,7 +12,7 @@ import { classReference } from './class'
 
 export interface QueryCommandInput {
   readonly sources: readonly string[]
-  readonly definition?: string
+  readonly class?: string
   readonly ast?: unknown
   readonly edge?: string
   readonly direction?: QueryDirection
@@ -27,36 +27,34 @@ export interface PreparedQuery {
 
 const DEFAULT_LIMIT = 100
 
-/** Admit canonical Query V6 or author the intentionally small Path/Definition/one-edge subset. */
+/** Admit canonical Query V6 or author the intentionally small Path/Class/one-edge subset. */
 export function prepareQuery(input: QueryCommandInput): PreparedQuery {
   const limit = positiveInteger(input.limit, '--limit', DEFAULT_LIMIT)
   if (input.ast !== undefined) {
     if (
       input.sources.length > 0 ||
-      input.definition !== undefined ||
+      input.class !== undefined ||
       input.edge !== undefined ||
       input.direction !== undefined
     ) {
       throw new TypeError(
-        '--ast/--file cannot be combined with sources, --definition, --edge, or --direction',
+        '--ast/--file cannot be combined with sources, --class, --edge, or --direction',
       )
     }
     return withPage(QueryAST.decode(input.ast), limit, input.cursor)
   }
 
-  if (input.sources.length === 0 && input.definition === undefined) {
-    throw new TypeError(
-      'query requires a Path source, --definition, or a canonical Query V6 document',
-    )
+  if (input.sources.length === 0 && input.class === undefined) {
+    throw new TypeError('query requires a Path source, --class, or a canonical Query V6 document')
   }
   if (input.direction !== undefined && input.edge === undefined) {
     throw new TypeError('--direction requires --edge')
   }
 
   const paths = input.sources.map((source) => Path.parse(source))
-  const definition =
-    input.definition === undefined ? undefined : classReference(input.definition, '--definition')
-  const nodes = definition === undefined ? paths : [...paths, definition]
+  const selectedClass =
+    input.class === undefined ? undefined : classReference(input.class, '--class')
+  const nodes = selectedClass === undefined ? paths : [...paths, selectedClass]
   const query: NodeQueryBuilder<unknown> = Query.from({
     nodes: nodes as [QueryNodeInput, ...QueryNodeInput[]],
   })

package/src/lib/__tests__/idp-session.driver.ts

@@ -13,6 +13,9 @@ import { ensureFreshSession } from '../idp-session'
 
 const scenario = process.argv[2]
 const audience = process.env.DRIVER_AUDIENCE || undefined
+const minimumRemainingSeconds = process.env.DRIVER_MINIMUM_SECONDS
+  ? Number(process.env.DRIVER_MINIMUM_SECONDS)
+  : undefined
 let orgHintCalls = 0
 const resolveOrganizationId = async (): Promise<string | undefined> => {
   orgHintCalls += 1
@@ -25,12 +28,16 @@ function print(result: Record<string, unknown>): void {
 
 try {
   if (scenario === 'ensure') {
-    const session = await ensureFreshSession('alice', { audience, resolveOrganizationId })
+    const session = await ensureFreshSession('alice', {
+      audience,
+      minimumRemainingSeconds,
+      resolveOrganizationId,
+    })
     print({ ok: true, token: accessTokenForAudience(session, audience), orgHintCalls })
   } else if (scenario === 'ensure-concurrent') {
     const [a, b] = await Promise.all([
-      ensureFreshSession('alice', { audience, resolveOrganizationId }),
-      ensureFreshSession('alice', { audience, resolveOrganizationId }),
+      ensureFreshSession('alice', { audience, minimumRemainingSeconds, resolveOrganizationId }),
+      ensureFreshSession('alice', { audience, minimumRemainingSeconds, resolveOrganizationId }),
     ])
     print({
       ok: true,

package/src/lib/__tests__/idp-session.test.ts

@@ -80,6 +80,31 @@ describe('ensureFreshSession', () => {
     }
   })
 
+  test('refreshes at the conservative whole-second lifetime boundary', async () => {
+    const server = rotationServer()
+    try {
+      await writeIdpConfig(server.url)
+      const shortToken = unsignedJwt({ aud: AUD, exp: Math.ceil(Date.now() / 1_000) + 200 })
+      await writeSession({
+        access_token: shortToken,
+        // The loose millisecond timestamp appears sufficient. Delegation uses
+        // the JWT exp and its conservative second-boundary handoff instead.
+        expires_at: new Date(Date.now() + 201_000).toISOString(),
+      })
+
+      const result = await runDriver('ensure', {
+        DRIVER_AUDIENCE: AUD,
+        DRIVER_MINIMUM_SECONDS: '200',
+      })
+
+      expect(result.ok).toBe(true)
+      expect(server.refreshCount()).toBe(1)
+      expect(result.token).not.toBe(shortToken)
+    } finally {
+      await server.stop()
+    }
+  })
+
   test('refreshes with the client that issued the session instead of the IdP default', async () => {
     const server = rotationServer()
     try {