@opice/harness 0.6.1 → 0.8.0

package/src/reporter.ts

@@ -8,7 +8,7 @@
  * The CLI handles end-of-run finalization: the reporter writes a
  * handoff file under $TMPDIR with the runId and credentials, the
  * `opice test` wrapper picks it up after `bun test` exits and POSTs
- * /api/v1/runs/<id>/finish so the dashboard sees the run as completed.
+ * /api/v1/<slug>/runs/<id>/finish so the dashboard sees the run as completed.
  *
  * When env vars aren't configured, the reporter falls back to a no-op so
  * harness behavior matches the bindx prototype.
@@ -19,6 +19,7 @@ import { mkdirSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import { parseOpiceDsn } from './dsn.js'
+import { resolveSelectedTier } from './tier.js'
 
 /** Per-request cap, so a hung connection can't stall a scenario's afterAll. */
 const REQUEST_TIMEOUT_MS = 10_000
@@ -28,11 +29,37 @@ const FLUSH_BUDGET_MS = 15_000
 export interface ReporterConfig {
 	endpoint: string
 	projectId: string
-	apiKey: string
+	/** Service-token credentials (the OPICE_DSN userinfo / OPICE_CLIENT_ID+SECRET). */
+	clientId: string
+	clientSecret: string
 	branch?: string
 	commit?: string
 	/** 'ci' for runs from automation, 'local' for opted-in dev runs. */
 	source?: 'ci' | 'local'
+	/**
+	 * The tier this run SELECTED (from `OPICE_TIER`) — recorded on the run so the
+	 * dashboard can explain why scenarios were skipped. Omitted when no tier
+	 * filter was set (the run ran everything).
+	 */
+	tier?: string
+}
+
+/**
+ * Strict reporting policy, resolved once from the env in {@link configureFromEnv}.
+ *
+ * Reporting is best-effort by design — a flaky uplink or a dashboard outage must
+ * never redden an otherwise-green test run. But that decoupling hides a real
+ * failure mode: a misconfigured token or an unreachable endpoint means the run
+ * is silently NOT recorded, while CI stays green. Strict mode (opt in via
+ * `OPICE_REPORT_STRICT` / `opice test --fail-on-report-error`) makes that loud —
+ * any reporting failure fails the run (the harness throws from a scenario's
+ * `afterAll`; the CLI escalates a failed `POST /finish` to a non-zero exit).
+ */
+let strictReporting = false
+
+/** Whether strict reporting is active (see {@link strictReporting}). */
+export function isStrictReporting(): boolean {
+	return strictReporting
 }
 
 export interface StepEvent {
@@ -86,6 +113,17 @@ export interface ScenarioStart {
 	seeds?: string[]
 	/** Identities / roles the scenario acts as. */
 	roles?: string[]
+	/** Declared tier (critical | standard | extended) — when it runs. */
+	tier?: string
+}
+
+/**
+ * A scenario the tier filter excluded from this run — registered for the record
+ * but never executed. Reported `skipped`, carrying a `reason` (which tier it
+ * declared vs the selected one) so the dashboard can explain the absence.
+ */
+export interface ScenarioSkip extends ScenarioStart {
+	reason?: string
 }
 
 export interface ScenarioFinish {
@@ -101,18 +139,30 @@ export interface ScenarioFinish {
 
 export interface Reporter {
 	startScenario(input: ScenarioStart): Promise<string>
+	/** Record a scenario the tier filter skipped (created already-finished as `skipped`). */
+	skipScenario(input: ScenarioSkip): Promise<void>
 	recordStep(event: StepEvent): Promise<void>
 	finishScenario(input: ScenarioFinish): Promise<void>
 	flush(): Promise<void>
+	/**
+	 * True if any report to the platform failed (network error or non-2xx). Used
+	 * by the harness to fail the run under strict reporting — see
+	 * {@link isStrictReporting}. Always false for the no-op reporter.
+	 */
+	hadFailures(): boolean
 }
 
 class NoopReporter implements Reporter {
 	async startScenario(input: ScenarioStart): Promise<string> {
 		return `noop-${input.name}-${Date.now()}`
 	}
+	async skipScenario(_input: ScenarioSkip): Promise<void> {}
 	async recordStep(_event: StepEvent): Promise<void> {}
 	async finishScenario(_input: ScenarioFinish): Promise<void> {}
 	async flush(): Promise<void> {}
+	hadFailures(): boolean {
+		return false
+	}
 }
 
 export const HANDOFF_DIR = path.join(tmpdir(), 'opice-handoffs')
@@ -123,7 +173,11 @@ function handoffPath(pid = process.pid): string {
 
 export interface RunHandoff {
 	endpoint: string
-	apiKey: string
+	/** Project slug — the CLI builds /api/v1/<project>/runs/<id>/finish from it. */
+	project: string
+	/** Service-token credentials so the CLI can POST /finish with the CF-Access-Client-* headers. */
+	clientId: string
+	clientSecret: string
 	runId: string
 }
 
@@ -131,9 +185,15 @@ class HttpReporter implements Reporter {
 	private runIdPromise: Promise<string> | null = null
 	private readonly pending: Set<Promise<unknown>> = new Set()
 	private warnedUnreachable = false
+	/** Count of failed reports (network error or non-2xx). Drives strict mode. */
+	private failures = 0
 
 	constructor(private readonly config: ReporterConfig) {}
 
+	hadFailures(): boolean {
+		return this.failures > 0
+	}
+
 	private async ensureRun(): Promise<string> {
 		if (!this.runIdPromise) {
 			this.runIdPromise = this.startRun()
@@ -142,17 +202,24 @@ class HttpReporter implements Reporter {
 	}
 
 	private async startRun(): Promise<string> {
-		const response = await this.fetch('POST', '/api/v1/runs', {
+		const response = await this.fetch('POST', `/api/v1/${this.config.projectId}/runs`, {
 			branch: this.config.branch,
 			commit: this.config.commit,
 			source: this.config.source,
+			tier: this.config.tier,
 		})
 		const runId = response['runId'] as string
 		// Synchronous write so the CLI can pick this up even if the test
 		// process exits abruptly (process.on('exit') runs sync).
 		try {
 			mkdirSync(HANDOFF_DIR, { recursive: true })
-			const handoff: RunHandoff = { endpoint: this.config.endpoint, apiKey: this.config.apiKey, runId }
+			const handoff: RunHandoff = {
+				endpoint: this.config.endpoint,
+				project: this.config.projectId,
+				clientId: this.config.clientId,
+				clientSecret: this.config.clientSecret,
+				runId,
+			}
 			writeFileSync(handoffPath(), JSON.stringify(handoff), 'utf-8')
 		} catch {
 			// best-effort
@@ -162,17 +229,35 @@ class HttpReporter implements Reporter {
 
 	async startScenario(input: ScenarioStart): Promise<string> {
 		const runId = await this.ensureRun()
-		const response = await this.fetch('POST', `/api/v1/runs/${runId}/scenarios`, {
+		const response = await this.fetch('POST', `/api/v1/${this.config.projectId}/runs/${runId}/scenarios`, {
 			name: input.name,
 			hash: input.hash,
 			testFile: input.testFile,
 			feature: input.feature,
 			seeds: input.seeds,
 			roles: input.roles,
+			tier: input.tier,
 		})
 		return response['scenarioId'] as string
 	}
 
+	async skipScenario(input: ScenarioSkip): Promise<void> {
+		const runId = await this.ensureRun()
+		// A skipped scenario is created already-finished on the platform — no
+		// steps follow, so we don't keep the returned id.
+		await this.fetch('POST', `/api/v1/${this.config.projectId}/runs/${runId}/scenarios`, {
+			name: input.name,
+			hash: input.hash,
+			testFile: input.testFile,
+			feature: input.feature,
+			seeds: input.seeds,
+			roles: input.roles,
+			tier: input.tier,
+			skipped: true,
+			reason: input.reason,
+		})
+	}
+
 	recordStep(event: StepEvent): Promise<void> {
 		// Track synchronously so flush() awaits the entire pipeline (including
 		// encodeScreenshot's fs.readFile and the upload), not just whatever
@@ -187,7 +272,7 @@ class HttpReporter implements Reporter {
 		const screenshot = event.screenshotPath
 			? await this.encodeScreenshot(event.screenshotPath)
 			: undefined
-		await this.fetch('POST', `/api/v1/runs/${runId}/scenarios/${event.scenarioId}/steps`, {
+		await this.fetch('POST', `/api/v1/${this.config.projectId}/runs/${runId}/scenarios/${event.scenarioId}/steps`, {
 			attempt: event.attempt,
 			sequence: event.sequence,
 			kind: event.kind,
@@ -206,7 +291,7 @@ class HttpReporter implements Reporter {
 		const runId = await this.ensureRun()
 		// Awaited inline so the scenario status is committed before the
 		// bun:test afterAll returns.
-		await this.fetch('PATCH', `/api/v1/runs/${runId}/scenarios/${input.scenarioId}`, {
+		await this.fetch('PATCH', `/api/v1/${this.config.projectId}/runs/${runId}/scenarios/${input.scenarioId}`, {
 			status: input.status,
 			durationMs: input.durationMs,
 			attempts: input.attempts,
@@ -245,7 +330,9 @@ class HttpReporter implements Reporter {
 			response = await fetch(this.config.endpoint + path, {
 				method,
 				headers: {
-					'authorization': `Bearer ${this.config.apiKey}`,
+					// Cloudflare Access service-token pair — validated at the edge, never the origin.
+					'cf-access-client-id': this.config.clientId,
+					'cf-access-client-secret': this.config.clientSecret,
 					'content-type': 'application/json',
 				},
 				body: body == null ? undefined : JSON.stringify(body),
@@ -257,25 +344,34 @@ class HttpReporter implements Reporter {
 			// DOM and routes fetch through a same-origin policy). Callers swallow
 			// reporter errors so the test still runs, so this is the one place the
 			// failure is visible — make it loud and actionable.
-			this.warnUnreachable(`${method} ${path}`, err instanceof Error ? err.message : String(err))
+			this.noteFailure(`${method} ${path}`, err instanceof Error ? err.message : String(err))
 			throw err
 		}
 		if (!response.ok) {
 			const detail = `${response.status} ${await response.text()}`.trim()
-			this.warnUnreachable(`${method} ${path}`, detail)
+			this.noteFailure(`${method} ${path}`, detail)
 			throw new Error(`opice reporter ${method} ${path} failed: ${detail}`)
 		}
 		return (await response.json()) as Record<string, unknown>
 	}
 
 	/**
-	 * A configured reporter that can't reach the platform means the run is
-	 * silently NOT recorded — the most confusing failure mode in onboarding
-	 * (the test passes, but nothing shows on the dashboard). Surface it once,
-	 * with the usual culprits, instead of letting the swallowed throw vanish.
+	 * Record a reporting failure and surface it. Callers swallow reporter errors
+	 * so the test still runs (reporting is best-effort), which makes this the one
+	 * place a failure is visible — so every failure is logged to stderr (a
+	 * configured reporter that can't reach the platform means the run is silently
+	 * NOT recorded, the most confusing failure mode in onboarding: the test
+	 * passes but nothing shows on the dashboard). The first failure prints the
+	 * full hint with the usual culprits; the rest a concise one-liner so a
+	 * recurring failure is visible without flooding the log. Counts toward
+	 * {@link hadFailures}, which strict mode fails the run on.
 	 */
-	private warnUnreachable(call: string, detail: string): void {
-		if (this.warnedUnreachable) return
+	private noteFailure(call: string, detail: string): void {
+		this.failures++
+		if (this.warnedUnreachable) {
+			console.error(`[opice] reporter error (${call}): ${detail} — this report was NOT recorded.`)
+			return
+		}
 		this.warnedUnreachable = true
 		console.error(
 			`[opice] reporter could not reach the platform (${call}: ${detail}). `
@@ -284,7 +380,8 @@ class HttpReporter implements Reporter {
 			+ `[opice]   - the test runner's global setup installs a DOM (happy-dom/jsdom) or mocks\n`
 			+ `[opice]     fetch, so the cross-origin POST is blocked (look for "Cross-Origin Request\n`
 			+ `[opice]     Blocked" / an OPTIONS … 401). Scope that setup so it skips the e2e dir.\n`
-			+ `[opice]   - a missing / expired OPICE_DSN api key (401), or an unreachable endpoint.`,
+			+ `[opice]   - a missing / expired OPICE_DSN api key (401), or an unreachable endpoint.\n`
+			+ `[opice] (set OPICE_REPORT_STRICT=1 / opice test --fail-on-report-error to fail the run on this.)`,
 		)
 	}
 }
@@ -299,13 +396,39 @@ export function setReporter(reporter: Reporter): void {
 	active = reporter
 }
 
+function isTruthy(value: string | undefined): boolean {
+	if (!value) return false
+	const v = value.toLowerCase()
+	return v === '1' || v === 'true' || v === 'yes' || v === 'on'
+}
+
+/**
+ * Strict reporting is requested but the reporter is a no-op — it can never fail,
+ * so strict mode has nothing to enforce. Warn rather than silently ignoring it:
+ * the user asked for "fail if reporting fails" and is instead getting no
+ * reporting at all, which strict can't catch.
+ */
+function warnStrictNoop(why: string): void {
+	console.error(
+		`[opice] OPICE_REPORT_STRICT is set but ${why} — strict reporting has no effect `
+		+ `(there is nothing to report, so nothing can fail).`,
+	)
+}
+
 export function configureFromEnv(env: NodeJS.ProcessEnv = process.env): Reporter {
+	// Strict reporting: fail the run if any report to the platform fails. Opt-in
+	// (default best-effort is locked design), resolved once here for the whole
+	// process. The CLI's `--fail-on-report-error` sets OPICE_REPORT_STRICT in the
+	// child env, so a bare `bun test` honours it too.
+	strictReporting = isTruthy(env['OPICE_REPORT_STRICT'])
 	// Individual vars win; OPICE_DSN fills any gaps (see dsn.ts).
 	const dsn = parseOpiceDsn(env['OPICE_DSN'])
 	const endpoint = env['OPICE_ENDPOINT'] ?? dsn?.endpoint
 	const projectId = env['OPICE_PROJECT'] ?? dsn?.project
-	const apiKey = env['OPICE_API_KEY'] ?? dsn?.apiKey
-	if (!endpoint || !projectId || !apiKey) {
+	const clientId = env['OPICE_CLIENT_ID'] ?? dsn?.clientId
+	const clientSecret = env['OPICE_CLIENT_SECRET'] ?? dsn?.clientSecret
+	if (!endpoint || !projectId || !clientId || !clientSecret) {
+		if (strictReporting) warnStrictNoop('reporter credentials are not configured (no OPICE_DSN / OPICE_* vars)')
 		return new NoopReporter()
 	}
 	// Reporting is opt-in outside CI. A local `bun test` while authoring would
@@ -317,15 +440,20 @@ export function configureFromEnv(env: NodeJS.ProcessEnv = process.env): Reporter
 	const mode = (env['OPICE_REPORT'] ?? 'auto').toLowerCase()
 	const shouldReport = mode === 'never' ? false : mode === 'always' ? true : isCI
 	if (!shouldReport) {
+		if (strictReporting) warnStrictNoop(`reporting is disabled here (OPICE_REPORT=${mode}, CI=${isCI})`)
 		return new NoopReporter()
 	}
 	const reporter = new HttpReporter({
 		endpoint,
 		projectId,
-		apiKey,
+		clientId,
+		clientSecret,
 		branch: env['OPICE_BRANCH'] ?? env['GITHUB_REF_NAME'],
 		commit: env['OPICE_COMMIT'] ?? env['GITHUB_SHA'],
 		source: isCI ? 'ci' : 'local',
+		// Record the selected tier only when one was explicitly requested — a run
+		// with no OPICE_TIER ran everything and carries no tier filter.
+		tier: env['OPICE_TIER'] ? resolveSelectedTier(env) : undefined,
 	})
 	setReporter(reporter)
 	return reporter

package/src/scenario.ts

@@ -2,8 +2,9 @@ import { createRequire } from 'node:module'
 import path from 'node:path'
 import { closePage, getContext, launchPage } from './context.js'
 import { screenshot } from './element.js'
-import { getReporter, type Reporter } from './reporter.js'
+import { getReporter, isStrictReporting, type Reporter } from './reporter.js'
 import { loadUserSetup } from './setup.js'
+import { isTierSkipped, normalizeTier, parseSelectedTier, type Tier, TIER_ORDER } from './tier.js'
 
 /**
  * `bun:test` is resolved lazily, at the moment `browserTest` registers a
@@ -44,6 +45,18 @@ export interface BrowserTestMeta {
 	hash?: string
 	/** Feature / requirement id this scenario covers (e.g. `'F-SML-03a'`). */
 	feature?: string
+	/**
+	 * Test tier — *when* this scenario runs (critical < standard < extended).
+	 * A run selects a tier via `OPICE_TIER` / `opice test --tier`; selection is a
+	 * threshold (running `standard` runs critical + standard). A scenario above
+	 * the selected tier is **skipped**: reported as `skipped` (so it still shows
+	 * on the dashboard) but never opens a browser. Defaults to `standard`.
+	 *
+	 *   critical — the must-pass core, every push
+	 *   standard — the normal suite (default), PRs / merges
+	 *   extended — slow / edge / expensive, nightly or on demand
+	 */
+	tier?: Tier
 	/**
 	 * Seeds that must be loaded for this scenario to run — machine-checkable
 	 * preconditions, not prose. e.g. `['initial-data', 'crm-master-data']`.
@@ -107,6 +120,40 @@ function captureTestFile(): string | undefined {
 	return undefined
 }
 
+// The tier this run selected (OPICE_TIER), resolved + cached once. An
+// unrecognized value warns once and falls back to running everything.
+let cachedSelectedTier: Tier | undefined
+function getSelectedTier(): Tier {
+	if (cachedSelectedTier === undefined) {
+		const parsed = parseSelectedTier()
+		if (!parsed.recognized) {
+			console.warn(
+				`[opice] unknown OPICE_TIER="${process.env['OPICE_TIER']}" — running all tiers `
+				+ `(use one of: ${TIER_ORDER.join(', ')}).`,
+			)
+		}
+		cachedSelectedTier = parsed.tier
+	}
+	return cachedSelectedTier
+}
+
+// Names of scenarios skipped by the tier filter, summarized once at process
+// exit so a tiered run prints "N skipped" instead of a line per scenario.
+const skippedScenarioNames: string[] = []
+let skipSummaryHooked = false
+function noteSkipped(name: string): void {
+	skippedScenarioNames.push(name)
+	if (skipSummaryHooked) return
+	skipSummaryHooked = true
+	process.on('exit', () => {
+		if (skippedScenarioNames.length === 0) return
+		console.warn(
+			`[opice] ${skippedScenarioNames.length} scenario(s) skipped — above the selected `
+			+ `tier '${getSelectedTier()}' (OPICE_TIER).`,
+		)
+	})
+}
+
 let currentScenarioId: string | null = null
 let currentScenarioStart: number = 0
 let currentScenarioFailures = 0
@@ -165,6 +212,14 @@ export function browserTest(meta: BrowserTestMeta, fn: () => void | Promise<void
 	// fn is the legacy registrar (it registers its own test()/hooks).
 	const isBody = fn.constructor.name === 'AsyncFunction'
 
+	// Tier gate: a scenario above the selected tier is registered but not run —
+	// reported `skipped` so the dashboard shows the full inventory.
+	const scenarioTier = normalizeTier(meta.tier)
+	if (isTierSkipped(scenarioTier, getSelectedTier())) {
+		registerSkipped(meta, scenarioTier, testFile, reporter)
+		return
+	}
+
 	describe(meta.name, () => {
 		beforeAll(async () => {
 			currentScenarioStart = Date.now()
@@ -180,6 +235,7 @@ export function browserTest(meta: BrowserTestMeta, fn: () => void | Promise<void
 					feature: meta.feature,
 					seeds: meta.seeds,
 					roles: meta.roles,
+					tier: scenarioTier,
 				})
 			} catch {
 				currentScenarioId = null
@@ -250,6 +306,18 @@ export function browserTest(meta: BrowserTestMeta, fn: () => void | Promise<void
 				}
 			}
 			currentScenarioId = null
+			// Strict reporting: a swallowed report failure (here or in any earlier
+			// hook/step) must turn the run red. afterAll always runs (beforeAll
+			// catches its own report failures), so throwing here is enough to make
+			// bun exit non-zero even when every assertion passed. The detail was
+			// already logged at the point of failure (reporter.noteFailure).
+			if (isStrictReporting() && reporter.hadFailures()) {
+				throw new Error(
+					`[opice] reporting to the platform failed and strict reporting is on `
+					+ `(OPICE_REPORT_STRICT / opice test --fail-on-report-error) — failing the run. `
+					+ `See the [opice] reporter error(s) above for the cause.`,
+				)
+			}
 		}, 30_000)
 
 		if (isBody) {
@@ -285,6 +353,38 @@ export function browserTest(meta: BrowserTestMeta, fn: () => void | Promise<void
 	})
 }
 
+/**
+ * Register a scenario the tier filter excluded. It's reported to the platform as
+ * `skipped` (so the dashboard shows it alongside what ran) but never opens a
+ * browser. The report runs in a real — instant, browser-free — `test`, not a
+ * `test.skip`: bun won't run a describe's hooks if every test in it is skipped,
+ * so a skip body is the only place left to POST from. With reporting off (local
+ * authoring), the body is a no-op against the NoopReporter.
+ */
+function registerSkipped(meta: BrowserTestMeta, tier: Tier, testFile: string | undefined, reporter: Reporter): void {
+	noteSkipped(meta.name)
+	const { describe, test } = bunTest()
+	const reason = `tier '${tier}' above the selected tier '${getSelectedTier()}'`
+	describe(meta.name, () => {
+		test('skipped (tier)', async () => {
+			try {
+				await reporter.skipScenario({
+					name: meta.name,
+					hash: meta.hash,
+					testFile,
+					feature: meta.feature,
+					seeds: meta.seeds,
+					roles: meta.roles,
+					tier,
+					reason,
+				})
+			} catch {
+				// Best-effort: reporting a skip must never fail the run.
+			}
+		})
+	})
+}
+
 /**
  * Open a fresh isolated browser context + page for `meta` and navigate to its
  * scenario URL. `launchPage()` closes any previous context first, so calling

package/src/tier.ts

@@ -0,0 +1,67 @@
+/**
+ * Test tiers — an ordered hierarchy for *when* a scenario runs.
+ *
+ * A scenario declares its tier in `browserTest` meta (default `standard`); a run
+ * selects a tier via `OPICE_TIER` (the `opice test --tier` flag). Selection is a
+ * THRESHOLD: running a tier runs every scenario AT OR BELOW it — the standard
+ * `smoke ⊂ regression ⊂ full` model. Scenarios above the selected tier are
+ * *skipped*: still registered and reported as `skipped` (so the dashboard shows
+ * the full inventory, not just what ran), but they never open a browser.
+ *
+ *   critical  — the must-pass core. Run on every push.
+ *   standard  — the normal suite (the default for an untagged scenario). PRs / merges.
+ *   extended  — slow / edge / expensive. Run nightly or on demand.
+ *
+ *   OPICE_TIER=critical → critical only
+ *   OPICE_TIER=standard → critical + standard
+ *   OPICE_TIER=extended → everything (also the default when OPICE_TIER is unset)
+ */
+export type Tier = 'critical' | 'standard' | 'extended'
+
+/** Tiers low → high. A scenario's index is its level; it runs when level <= selected level. */
+export const TIER_ORDER: readonly Tier[] = ['critical', 'standard', 'extended']
+
+/** A scenario with no declared tier sits in the middle `standard` tier. */
+export const DEFAULT_SCENARIO_TIER: Tier = 'standard'
+
+/** With no `OPICE_TIER` set, run everything — select the widest tier. */
+export const DEFAULT_SELECTED_TIER: Tier = 'extended'
+
+function isTier(value: string | undefined): value is Tier {
+	return value === 'critical' || value === 'standard' || value === 'extended'
+}
+
+/** Normalize a scenario's declared tier, defaulting (and tolerating junk) to `standard`. */
+export function normalizeTier(tier: string | undefined): Tier {
+	return isTier(tier) ? tier : DEFAULT_SCENARIO_TIER
+}
+
+export interface SelectedTier {
+	tier: Tier
+	/** false when `OPICE_TIER` held an unrecognized value (the caller may warn). */
+	recognized: boolean
+}
+
+/**
+ * The tier selected for this run, parsed from `OPICE_TIER`. Unset → run
+ * everything. `all`/`full` are friendly aliases for the widest tier. An
+ * unrecognized value resolves to "run everything" (`recognized: false`) rather
+ * than silently dropping tests — better to over-run than to skip on a typo.
+ */
+export function parseSelectedTier(env: NodeJS.ProcessEnv = process.env): SelectedTier {
+	const raw = env['OPICE_TIER']?.trim().toLowerCase()
+	if (!raw) return { tier: DEFAULT_SELECTED_TIER, recognized: true }
+	if (isTier(raw)) return { tier: raw, recognized: true }
+	if (raw === 'all' || raw === 'full') return { tier: 'extended', recognized: true }
+	return { tier: DEFAULT_SELECTED_TIER, recognized: false }
+}
+
+/** Convenience: the resolved selected tier, ignoring whether the value was recognized. */
+export function resolveSelectedTier(env: NodeJS.ProcessEnv = process.env): Tier {
+	return parseSelectedTier(env).tier
+}
+
+/** A scenario is skipped when its tier sits ABOVE the selected one. */
+export function isTierSkipped(scenarioTier: Tier, selectedTier: Tier): boolean {
+	return TIER_ORDER.indexOf(scenarioTier) > TIER_ORDER.indexOf(selectedTier)
+}