@@ -0,0 +1,90 @@
+import { b64uDecodeString, b64uEncode } from './base64.js'
+
+export const SELECTION_CONTEXT_HEADER = 'X-OA-Selection-Context'
+export const MAX_SELECTION_CONTEXT_LENGTH = 2048
+const MAX_ID_LENGTH = 256
+
+/** Safe selectors, never credentials, subjects, emails, roles, or authority. */
+export interface SelectionContext {
+  browserSetId: string
+  sessionId: string | null
+  version: number
+}
+
+function validId(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= MAX_ID_LENGTH
+}
+
+function validContext(value: unknown): value is SelectionContext {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const context = value as Partial<SelectionContext>
+  return validId(context.browserSetId)
+    && (context.sessionId === null || validId(context.sessionId))
+    && typeof context.version === 'number'
+    && Number.isSafeInteger(context.version) && context.version >= 0
+    && !Object.is(context.version, -0)
+}
+
+/** Canonical unpadded base64url JSON; opaque to clients, not encrypted or signed. */
+export function serializeSelectionContext(context: SelectionContext): string {
+  if (!validContext(context)) throw new TypeError('Invalid selection context')
+  const { browserSetId, sessionId, version } = context
+  const header = b64uEncode(new TextEncoder().encode(JSON.stringify({ browserSetId, sessionId, version })))
+  if (header.length > MAX_SELECTION_CONTEXT_LENGTH) throw new RangeError('Selection context is too large')
+  return header
+}
+
+/** Missing, oversized, noncanonical, or malformed assertions are invalid. */
+export function parseSelectionContext(header: string | null): SelectionContext | null {
+  if (!header || header.length > MAX_SELECTION_CONTEXT_LENGTH || !/^[A-Za-z0-9_-]+$/.test(header)) return null
+  // Invalid client input is expected; invalid trusted server contexts throw instead.
+  try {
+    const context: unknown = JSON.parse(b64uDecodeString(header))
+    if (!validContext(context) || serializeSelectionContext(context) !== header) return null
+    return context
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Persist this increment atomically with every selection change (including
+ * sign-out and A -> B -> A). Never reset/reuse a version within a browser set.
+ * At exhaustion, fail closed or establish a new, unique browser-set ID.
+ */
+export function nextSelectionVersion(version: number): number {
+  if (!Number.isSafeInteger(version) || version < 0 || Object.is(version, -0)) {
+    throw new TypeError('Invalid selection version')
+  }
+  if (version === Number.MAX_SAFE_INTEGER) throw new RangeError('Selection version exhausted')
+  return version + 1
+}
+
+/**
+ * Run after authentication/authorization, before mutation side effects. `current`
+ * must come from the caller's validated selection for this gate and browser set;
+ * browser-set IDs must not be reused across gates. Retain that authenticated
+ * actor for the request, and coordinate concurrent switches/mutations in the
+ * caller's transaction when necessary. This comparison is not a store/CAS lock.
+ *
+ * The header is only a concurrency assertion, NOT authentication or CSRF
+ * protection. A match even for sessionId:null confers no authority. On conflict,
+ * refresh selection and ask the user to review; never automatically replay a
+ * mutation under the new identity. No client field supplies an actor.
+ */
+export function checkSelectionContext(
+  intendedHeader: string | null,
+  current: SelectionContext,
+): Response | null {
+  const actual = serializeSelectionContext(current)
+  const intended = parseSelectionContext(intendedHeader)
+  if (intended !== null && intendedHeader === actual) return null
+  return new Response(JSON.stringify({
+    error: 'selection_context_conflict',
+    recoverable: true,
+    action: 'refresh_selection',
+  }) + '\n', {
+    status: 409,
+    headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+  })
+}
@@ -73,6 +73,15 @@ export {
   verifySessionClaims,
 } from './core/session.js'
 export type { CookieOpts, SessionClaims } from './core/session.js'
+export {
+  SELECTION_CONTEXT_HEADER,
+  MAX_SELECTION_CONTEXT_LENGTH,
+  serializeSelectionContext,
+  parseSelectionContext,
+  nextSelectionVersion,
+  checkSelectionContext,
+} from './core/selection-context.js'
+export type { SelectionContext } from './core/selection-context.js'
 export type {
   AllowEntry,
   AllowlistStore,
 
@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest'
+import {
+  checkSelectionContext,
+  MAX_SELECTION_CONTEXT_LENGTH,
+  nextSelectionVersion,
+  parseSelectionContext,
+  SELECTION_CONTEXT_HEADER,
+  serializeSelectionContext,
+  type SelectionContext,
+} from '../src/core/selection-context.js'
+
+const current: SelectionContext = { browserSetId: 'browser-1', sessionId: 'session-A', version: 4 }
+const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
+
+describe('selection context', () => {
+  it('serializes a canonical header and round-trips safe metadata only', () => {
+    expect(SELECTION_CONTEXT_HEADER).toBe('X-OA-Selection-Context')
+    const header = serializeSelectionContext(current)
+    expect(header).toBe(encode({ browserSetId: 'browser-1', sessionId: 'session-A', version: 4 }))
+    expect(parseSelectionContext(header)).toEqual(current)
+    expect(serializeSelectionContext({ version: 4, sessionId: 'session-A', browserSetId: 'browser-1' })).toBe(header)
+    expect(serializeSelectionContext({ ...current, actor: 'forged' } as SelectionContext)).toBe(header)
+    expect(parseSelectionContext(encode({ ...current, actor: 'forged' }))).toBe(null)
+  })
+
+  it.each([null, 'session-A', 'unicode-\u00e9'])('accepts exact selection %s without granting authority', sessionId => {
+    const context = { ...current, sessionId }
+    expect(parseSelectionContext(serializeSelectionContext(context))).toEqual(context)
+    expect(checkSelectionContext(serializeSelectionContext(context), context)).toBe(null)
+  })
+
+  it.each([
+    null, '', '!', 'e30=', 'e30', 'x'.repeat(MAX_SELECTION_CONTEXT_LENGTH + 1),
+    encode(null), encode([]), encode({}),
+    encode({ ...current, version: -1 }), encode({ ...current, version: 0.5 }),
+    encode({ ...current, version: Number.MAX_SAFE_INTEGER + 1 }),
+    encode({ ...current, version: '4' }), encode({ ...current, sessionId: 1 }),
+    encode({ ...current, browserSetId: '' }), encode({ ...current, sessionId: '' }),
+    encode({ ...current, browserSetId: 'x'.repeat(257) }),
+    encode({ ...current, sessionId: 'x'.repeat(257) }),
+    encode({ version: 4, sessionId: 'session-A', browserSetId: 'browser-1' }),
+    Buffer.from('{"browserSetId":"browser-1","sessionId":"session-A","version":4,"version":4}').toString('base64url'),
+  ])('rejects absent or malformed headers: %s', async header => {
+    expect(parseSelectionContext(header)).toBe(null)
+    const response = checkSelectionContext(header, current)!
+    expect(response.status).toBe(409)
+    expect(Object.fromEntries(response.headers)).toEqual({
+      'cache-control': 'no-store',
+      'content-type': 'application/json; charset=utf-8',
+    })
+    expect(await response.text()).toBe('{"error":"selection_context_conflict","recoverable":true,"action":"refresh_selection"}\n')
+  })
+
+  it.each([
+    { ...current, version: 3 },
+    { ...current, version: 5 },
+    { ...current, sessionId: 'session-B' },
+    { ...current, sessionId: null },
+    { ...current, browserSetId: 'other-browser-or-gate' },
+  ])('rejects stale, future, signed-out, and cross-browser/gate assertions', async intended => {
+    const response = checkSelectionContext(serializeSelectionContext(intended), current)!
+    expect(response.status).toBe(409)
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    expect(await response.json()).toEqual({ error: 'selection_context_conflict', recoverable: true, action: 'refresh_selection' })
+  })
+
+  it('detects A -> B -> A and sign-out without resetting versions', () => {
+    const before = serializeSelectionContext(current)
+    const switched = { ...current, sessionId: 'session-B', version: nextSelectionVersion(current.version) }
+    const returned = { ...current, version: nextSelectionVersion(switched.version) }
+    const signedOut = { ...returned, sessionId: null, version: nextSelectionVersion(returned.version) }
+    expect([switched.version, returned.version, signedOut.version]).toEqual([5, 6, 7])
+    expect(checkSelectionContext(before, returned)!.status).toBe(409)
+    expect(checkSelectionContext(before, signedOut)!.status).toBe(409)
+  })
+
+  it.each([-1, -0, 0.1, NaN, Infinity, Number.MAX_SAFE_INTEGER + 1])('throws for invalid trusted version %s', version => {
+    expect(() => serializeSelectionContext({ ...current, version })).toThrow('Invalid selection context')
+    expect(() => checkSelectionContext(null, { ...current, version })).toThrow('Invalid selection context')
+    expect(() => nextSelectionVersion(version)).toThrow('Invalid selection version')
+  })
+
+  it('supports safe integer boundaries and refuses overflow', () => {
+    for (const version of [0, Number.MAX_SAFE_INTEGER]) {
+      const context = { ...current, version }
+      expect(parseSelectionContext(serializeSelectionContext(context))).toEqual(context)
+    }
+    expect(nextSelectionVersion(0)).toBe(1)
+    expect(nextSelectionVersion(Number.MAX_SAFE_INTEGER - 1)).toBe(Number.MAX_SAFE_INTEGER)
+    expect(() => nextSelectionVersion(Number.MAX_SAFE_INTEGER)).toThrow('Selection version exhausted')
+  })
+})