@lovrozagar/oat 0.9.1 → 0.10.0

package/README.md

@@ -40,6 +40,7 @@ This file is the operator manual. An agent that has read it can install oat, wri
 - [Complete configs](#complete-configs)
 - [Commands](#commands)
   - [oat run](#oat-run)
+  - [Targeted runs (`--ops`)](#targeted-runs---ops)
   - [oat doctor](#oat-doctor)
   - [oat plan](#oat-plan)
   - [oat serve](#oat-serve)
@@ -255,19 +256,20 @@ oat help
 
 Requires `--config`. CLI flags override the same field in the config when both are set.
 
-| flag                                       | default                          | meaning                                                                                                                                 |
-| ------------------------------------------ | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `--config`                                 | required                         | module or JSON file, default export                                                                                                     |
-| `--base-url`                               | `config.baseUrl`                 | backend origin                                                                                                                          |
-| `--only`                                   | `config.only` or all entities    | comma-separated entity names as `oat plan` prints them (singularised)                                                                   |
-| `--seed`                                   | `config.seed` or `1`             | fixture generation seed (reproducible)                                                                                                  |
-| `--out`                                    | `config.outDir` or `./.oat/runs` | history root; each run writes `<out>/<datetime>/` and updates `latest`                                                                  |
-| `--max-in-flight`                          | `config.maxInFlight` or `4`      | HTTP requests allowed at once                                                                                                           |
-| `--keep-fixtures`                          | `config.keepFixtures` or false   | do not DELETE what the run created                                                                                                      |
-| `--quiet`                                  | false                            | no stderr progress; files under `--out` still update                                                                                    |
-| `--save-exchanges` / `--no-save-exchanges` | on unless `--profile cheap`      | persist every HTTP exchange under the run dir (`exchanges.jsonl`, `exchanges/`, `blobs/`). Does **not** change in-memory transcript RAM |
-
-**Exit codes:** `0` no defects, `1` at least one root-cause finding (`BACKEND_BUG`, `SPEC_BUG`, `SECURITY`, `AMBIGUITY`) **or** the run stopped because the network never came back, `2` usage error (missing `--config`, no principals, unknown flag). `COVERAGE_GAP` and `BLOCKED` do not fail the process.
+| flag                                       | default                          | meaning                                                                                                                                         |
+| ------------------------------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--config`                                 | required                         | module or JSON file, default export                                                                                                             |
+| `--base-url`                               | `config.baseUrl`                 | backend origin                                                                                                                                  |
+| `--ops`                                    | `config.ops` or every operation  | comma-separated operationIds to grade; everything else is support. `*` globs, `<originId>:` prefixes. See [Targeted runs](#targeted-runs---ops) |
+| `--only`                                   | `config.only` or all entities    | comma-separated entity names as `oat plan` prints them (singularised); each grades every operation it owns. Joins `--ops` as a union            |
+| `--seed`                                   | `config.seed` or `1`             | fixture generation seed (reproducible)                                                                                                          |
+| `--out`                                    | `config.outDir` or `./.oat/runs` | history root; each run writes `<out>/<datetime>/` and updates `latest`                                                                          |
+| `--max-in-flight`                          | `config.maxInFlight` or `4`      | HTTP requests allowed at once                                                                                                                   |
+| `--keep-fixtures`                          | `config.keepFixtures` or false   | do not DELETE what the run created                                                                                                              |
+| `--quiet`                                  | false                            | no stderr progress; files under `--out` still update                                                                                            |
+| `--save-exchanges` / `--no-save-exchanges` | on unless `--profile cheap`      | persist every HTTP exchange under the run dir (`exchanges.jsonl`, `exchanges/`, `blobs/`). Does **not** change in-memory transcript RAM         |
+
+**Exit codes:** `0` no defects, `1` at least one root-cause finding (`BACKEND_BUG`, `SPEC_BUG`, `SECURITY`, `AMBIGUITY`) **or** the run stopped because the network never came back **or**, on a targeted run, a target that did not end `held`, `2` usage error (missing `--config`, no principals, unknown flag, an `--ops` / `--only` name that matches nothing, a target the profile excludes). `COVERAGE_GAP` and `BLOCKED` do not fail a full run.
 
 Example:
 
@@ -275,10 +277,47 @@ Example:
 oat run --config oat.config.ts --only store,product --out .oat/runs/prod
 ```
 
-`--only store,product` matches the **entity names** from `oat plan`, not path segments. `/v1/stores` is usually the entity `store`. If a name is unknown, that entity is simply not tested (the others still run).
+`--only store,product` matches the **entity names** from `oat plan`, not path segments. `/v1/stores` is usually the entity `store`. An unknown name exits `2` with the nearest names.
 
 A run with no principals exits `2`. Isolation checks then need a second principal; they are skipped, not failed, when only one is present.
 
+### Targeted runs (`--ops`)
+
+A full run grades every operation. After changing two endpoints you usually want those two, not the whole API:
+
+```bash
+oat run --config oat.config.ts --ops table.create,row.list
+oat run --config oat.config.ts --ops 'row.*'            # glob within an operationId
+oat run --config oat.config.ts --ops cdn:asset.get      # an operation on the origin with id "cdn"
+oat plan --config oat.config.ts --ops table.create      # dry run: what would be graded, queued, called
+```
+
+**Targets** are graded: every check whose subjects include a target runs the full matrix against it. **Support** operations are called and never graded: principal sign-up, parent creates, the cohort create behind a list, reads used as an oracle, teardown deletes. A list route cannot be tested without rows in it, so its create still runs, but a defect in that create is out of this run's scope.
+
+How the scope is decided:
+
+- Every check declares its **subjects**, the operations whose contract it judges (`filter.*` judges the list route, `patch.minimality` the update, `effects.declared-effect-occurs` each `x-effects` operation). A check runs when one of its subjects is a target. Others are **out of scope**: not run, not skipped.
+- An entity is seeded only when one of its checks grades a target. Declared edges pull in the other direction too: targeting a read route that another entity's create names in `x-invalidate` queues that entity, so its invalidation check grades the route.
+- Checks that judge several operations (`effects.*`, `async.*`, `response.status-is-documented`, `schema.error-response-matches-document`, `invalidation.declared-route-changes`) invoke and judge only the targeted ones. An untargeted `x-effects` upload is never POSTed.
+- Every finding names the operations it judges (`operations` in `oat-report.json`).
+- An operation counts as graded only when a check exercised it. A check that judges after the fact (`response.status-is-documented` reads the transcript) grades only the operations it saw. A check that reports a coverage gap for an operation did not grade it. `--only <entity>` therefore surfaces every action no check can reach as `untested`.
+
+Each target ends with one status:
+
+| status         | meaning                                                                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `held`         | at least one check graded it and none failed                                                                                                            |
+| `failed`       | a defect finding is attributed to it                                                                                                                    |
+| `inconclusive` | checks ran and none could decide                                                                                                                        |
+| `blocked`      | every check was suppressed, or a support operation it needed failed (named, with evidence)                                                              |
+| `untested`     | nothing exercised it. The reason says why (`unmodeled`, `entity-not-testable`, `coverage gap: …`, `no check applied: needs …`, `no check exercised it`) |
+
+A targeted run exits `0` only when every target is `held`. A target nothing could grade must not read as a pass.
+
+Validation happens before any principal signs up: a name that matches nothing exits `2` with the nearest operationIds; an exact target the active `--profile` excludes exits `2`; a glob or `--only` match the profile excludes is dropped and listed. An origin no target names is not run.
+
+A targeted run is for iterating. It grades what you named and what those operations observably affect through declared edges. It does not catch a regression in an untargeted operation caused by shared code, so run the full suite before a release.
+
 ### `oat doctor`
 
 Offline. Loads the document, builds the model, prints coverage.
@@ -337,6 +376,8 @@ store               CLRU·  id         2 route(s) (inferred)
 
 `--json` is `{ entities, operations, roots }` — the full `SpecModel` maps, including conventions, query capability, async, invite, and path params. Use this when you need to know what oat will call something.
 
+With `--ops` / `--only` (flag or config), `plan` prints the targeted scope instead: each target with its entity and the checks that would grade it, untestable targets with the reason, the entities that would be queued, and the support operations predicted from the graph. `--json` adds a `scope` object with the same fields. An unknown name exits `2`.
+
 ### `oat serve`
 
 In-process demo API. Same fixture as conformance.
@@ -433,7 +474,8 @@ export default defineConfig({
 	seed: 42, // fixture generation; a failing run with the same seed is identical
 	cohortSize: 12, // records created per entity (default 7)
 	maxInFlight: 4, // HTTP in flight
-	only: ["store", "product"], // restrict entities
+	ops: ["store.create", "product.*"], // grade only these operationIds; the rest is support
+	only: ["store", "product"], // grade every operation these entities own (union with ops)
 	keepFixtures: false,
 	outDir: "./.oat/runs",
 	saveExchanges: true, // default on unless --profile cheap; --quiet does not turn this off
@@ -483,7 +525,7 @@ export default defineConfig({
 
 `spec` may be a path relative to `baseUrl` (`/v1/openapi/spec`) or an absolute URL or a file.
 
-CLI `--base-url`, `--only`, `--seed`, `--out`, `--max-in-flight`, `--keep-fixtures`, `--save-exchanges` / `--no-save-exchanges` override these when passed.
+CLI `--base-url`, `--ops`, `--only`, `--seed`, `--out`, `--max-in-flight`, `--keep-fixtures`, `--save-exchanges` / `--no-save-exchanges` override these when passed.
 
 ### Spec loading
 
@@ -1686,7 +1728,7 @@ Coverage is split **never** (zero entities could run it) vs **partial** (ran on
 
 Cascade suppression is transitive: one root cause is one finding, not a page of consequences. A blocked check has **not** been verified; re-run after the cause is fixed.
 
-`oat run` exit `1` if any finding has a failing verdict. Gaps and blocked entries do not fail CI.
+`oat run` exit `1` if any finding has a failing verdict. Gaps and blocked entries do not fail a full run. A targeted run (`--ops`) also exits `1` when any target did not end `held`.
 
 Console (stdout) after a run:
 
@@ -1715,20 +1757,20 @@ Written under `--out` (default `./.oat/runs`). Each invocation creates a UTC tim
 
 `--out` / `outDir` replace the root, not the leaf — `--out .oat/runs/prod` writes `.oat/runs/prod/<datetime>/`.
 
-| file                         |                                                                                                        |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `oat-report.md`              | human report: summary, findings with request/response excerpts, coverage, latency p50/p95/max          |
-| `oat-report.json`            | same data for CI. Summary only — full exchanges are not inlined here                                   |
-| `matrix.html`                | visual matrix of entities × checks                                                                     |
-| `matrix.json`                | the same graph (AI-friendly), including a mermaid string                                               |
-| `issue-repro/*.sh`           | one executable `curl` script per finding that has evidence. Directory is omitted when the run is clean |
-| `progress.log`               | logfmt, one event per line, never truncated                                                            |
-| `progress.jsonl`             | same events as JSON                                                                                    |
-| `progress.tsv`               | same columns, tab-separated. `req_id` is the join key to the exchange journal                          |
-| `progress.json`              | latest snapshot only (overwritten ~1s)                                                                 |
-| `exchanges.jsonl`            | one line per request (`seq`, `requestId`, method, url, status, bytes, …). Greppable                    |
-| `exchanges/<requestId>.json` | full exchange: status, headers, described bodies. Missing id → `seq-<n>.json`. Duplicate id → `-<seq>` |
-| `blobs/<sha256>`             | content-addressed file parts and oversized / binary bodies                                             |
+| file                         |                                                                                                                            |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `oat-report.md`              | human report: scope, per-operation status, summary, findings with request/response excerpts, coverage, latency p50/p95/max |
+| `oat-report.json`            | same data for CI. Summary only — full exchanges are not inlined here                                                       |
+| `matrix.html`                | visual matrix of entities × checks                                                                                         |
+| `matrix.json`                | the same graph (AI-friendly), including a mermaid string                                                                   |
+| `issue-repro/*.sh`           | one executable `curl` script per finding that has evidence. Directory is omitted when the run is clean                     |
+| `progress.log`               | logfmt, one event per line, never truncated                                                                                |
+| `progress.jsonl`             | same events as JSON                                                                                                        |
+| `progress.tsv`               | same columns, tab-separated. `req_id` is the join key to the exchange journal                                              |
+| `progress.json`              | latest snapshot only (overwritten ~1s)                                                                                     |
+| `exchanges.jsonl`            | one line per request (`seq`, `requestId`, method, url, status, bytes, …). Greppable                                        |
+| `exchanges/<requestId>.json` | full exchange: status, headers, described bodies. Missing id → `seq-<n>.json`. Duplicate id → `-<seq>`                     |
+| `blobs/<sha256>`             | content-addressed file parts and oversized / binary bodies                                                                 |
 
 The journal is oat `Exchange` JSON, not HAR (HAR export is out of scope). Default **on** unless `--profile cheap`. `--no-save-exchanges` skips `exchanges/` entirely. `--quiet` does not. **`--no-save-exchanges` does not reduce transcript RAM** — it only skips the disk journal. The in-memory transcript always drops live `FormData` / `Blob` / `ArrayBuffer` / multi-MiB strings after each hop, keeping citeable metadata and content-addressed body descriptors. Reconstruct bytes from `blobs/<sha256>` when a check genuinely needs them.
 
@@ -1739,6 +1781,8 @@ Redaction is on by default (not opt-in), applied on write:
 - Headers: `authorization`, `cookie`, `set-cookie`, `proxy-authorization`, and any `x-*-key` / `x-*-secret` / `x-ia-tester-key` (case-insensitive).
 - JSON bodies, any depth: `access_token`, `refresh_token`, `id_token`, `password`, `token`, `secret`, `api_key` → `"<redacted>"`.
 
+Every report names its scope. The console prints `scope: full · 141 of 212 operations graded` or `scope: targeted · 2 operations (--ops …)` followed by one line per target. `oat-report.md` has a **Scope** line and an **Operations** table: on a full run, every operation in the document with its status (so operations no check ever grades are visible); on a targeted run, the targets only, followed by **Support operations** with call and non-2xx counts. In `matrix.html` / `matrix.json` a check a targeted run did not ask for is `out-of-scope`, distinct from `skipped` (not applicable).
+
 Join `progress.tsv` `req_id` to `exchanges.jsonl` `requestId` (response `x-request-id` / `request-id` / `x-correlation-id` / `correlation-id` wins; else what oat sent). `oat-report.md` includes one line such as `1841 exchanges → exchanges/`.
 
 ### `oat-report.json`
@@ -1750,6 +1794,30 @@ Join `progress.tsv` `req_id` to `exchanges.jsonl` `requestId` (response `x-reque
 	"durationMs": 41200,
 	"requests": 842,
 	"entitiesTested": ["store", "product"],
+	"scope": {
+		"mode": "targeted",
+		"requested": { "ops": ["product.update"], "only": [] },
+		"operations": [
+			{
+				"operationId": "product.update",
+				"entity": "product",
+				"status": "failed",
+				"checks": {
+					"held": ["concurrency.no-lost-update"],
+					"failed": ["patch.minimality"],
+					"suppressed": [],
+					"inconclusive": [],
+					"gaps": []
+				},
+				"findings": 1,
+				"reason": null
+			}
+		],
+		"support": [{ "operationId": "product.create", "calls": 9, "non2xx": 0 }],
+		"excluded": [],
+		"originsSkipped": []
+	},
+	"checksOutOfScope": [{ "check": "filter.in-is-union-of-eq", "entity": "product" }],
 	"checksRun": ["list.read-after-write", "patch.minimality"],
 	"checksSkipped": [{ "check": "async.reaches-terminal-state", "entity": "store", "needs": "…" }],
 	"checksSuppressed": [{ "check": "query.axes-compose", "entity": "store", "because": "list.read-after-write" }],
@@ -1918,7 +1986,9 @@ const result = await run({
 })
 
 // result.findings, result.checksSkipped, result.checksSuppressed,
-// result.inconclusive, result.entitiesTested, result.teardown, result.created
+// result.inconclusive, result.entitiesTested, result.teardown, result.created,
+// result.scope (per-operation status), result.checksOutOfScope
+// pass `ops: ["product.update"]` to run() for a targeted run; ScopeError on an unknown name
 ```
 
 `loadConfig(path)` loads `.ts` / `.js` / `.mjs` / `.json` the same way the CLI does. The CLI then expands `${NAME}` in every string. `defineConfig` is an identity function for typing; it does not interpolate. If you call `run()` with an in-process object, resolve secrets yourself (template literals, `process.env`) before passing it.
@@ -2058,6 +2128,7 @@ These are deliberate. An agent should not invent a flag for them.
 - **`or()` is postgrest-only.**
 - **Leftover rows on a shared DB** poison numeric and filter checks. Wipe between runs.
 - **`--only` uses plan names** (`store`, not `stores` or `/v1/stores`).
+- **`--ops` trusts support operations.** A targeted green means the targets held, given that what they needed worked. A defect in an untargeted operation is out of scope, even when a target called it.
 - **Default cohort is 7.** `pagination.limit-respects-documented-max` needs `cohortSize > maxLimit`.
 - **First principal is the writer.** Extra principals are peers / lattice, not a pool of writers.
 

package/dist/cli.js

@@ -10,6 +10,7 @@ import { ISSUE_REPRO_DIR, renderConsole, renderJson, renderMarkdown, renderRepro
 import { createProgressPump, createStderrProgress, formatProgressJsonl, formatProgressLine, formatProgressTsv, PROGRESS_GLOSSARY, PROGRESS_TSV_HEADER, } from "./runtime/progress.js";
 import { resolveSaveExchanges } from "./runtime/exchanges.js";
 import { allocateRunDir, DEFAULT_RUNS_ROOT } from "./runtime/runs.js";
+import { authStepOperationIds, planScope, resolveTargetScope, ScopeError } from "./runtime/scope.js";
 import { renderTeardown } from "./runtime/teardown.js";
 import { buildModel } from "./spec/graph.js";
 import { dereference, loadSpec } from "./spec/load.js";
@@ -19,6 +20,7 @@ export const KNOWN_FLAGS = new Set([
     "spec",
     "base-url",
     "only",
+    "ops",
     "profile",
     "seed",
     "out",
@@ -74,7 +76,8 @@ Flags
   --config     oat config module (.ts/.js/.mjs/.json) with a default export
   --spec       OpenAPI document, http(s) URL or filesystem path
   --base-url   backend under test, overriding the config
-  --only       comma-separated entity names to restrict the run to
+  --ops        comma-separated operationIds to grade (row.*, cdn:asset.get); the rest is support
+  --only       comma-separated entity names; each grades every operation it owns
   --profile    named profile gating which operations run (built-in: full, cheap)
   --seed       integer seed for fixture generation (default 1)
   --out        history root; each run is <out>/<datetime>/ (default ./.oat/runs)
@@ -97,6 +100,26 @@ function str(flags, key) {
     const value = flags[key];
     return typeof value === "string" ? value : undefined;
 }
+function list(flags, key) {
+    return str(flags, key)
+        ?.split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/**
+ * Exit code for a finished run. Root causes fail it, not raw findings: gaps and blocked entries
+ * are information. A targeted run also fails unless every target held — under `--ops` a target
+ * nothing graded must not read as a pass.
+ */
+export function exitCode(result) {
+    if (result.network?.incomplete === true)
+        return 1;
+    if (result.findings.some((f) => f.verdict !== "COVERAGE_GAP" && f.verdict !== "BLOCKED"))
+        return 1;
+    if (result.scope.mode === "targeted" && result.scope.operations.some((op) => op.status !== "held"))
+        return 1;
+    return 0;
+}
 async function commandRun(flags) {
     const configPath = str(flags, "config");
     if (configPath === undefined) {
@@ -107,11 +130,8 @@ async function commandRun(flags) {
     const config = interpolate(await loadConfig(configPath));
     const baseUrl = str(flags, "base-url") ?? config.baseUrl;
     const seedFlag = str(flags, "seed");
-    const onlyFromFlag = str(flags, "only")
-        ?.split(",")
-        .map((s) => s.trim())
-        .filter(Boolean);
-    const only = onlyFromFlag ?? config.only?.filter((name) => name.trim() !== "");
+    const only = list(flags, "only") ?? config.only?.filter((name) => name.trim() !== "");
+    const ops = list(flags, "ops") ?? config.ops?.filter((name) => name.trim() !== "");
     const profile = str(flags, "profile") ?? config.profile;
     const saveExchanges = resolveSaveExchanges({
         ...(flags["no-save-exchanges"] === true ? { flag: false } : flags["save-exchanges"] === true ? { flag: true } : {}),
@@ -169,6 +189,7 @@ async function commandRun(flags) {
             ...(config.roots === undefined ? {} : { roots: config.roots }),
             ...(config.cohortSize === undefined ? {} : { cohortSize: config.cohortSize }),
             ...(only === undefined || only.length === 0 ? {} : { only }),
+            ...(ops === undefined || ops.length === 0 ? {} : { ops }),
             ...(profile === undefined ? {} : { profile }),
             ...(config.profiles === undefined ? {} : { profiles: config.profiles }),
             ...(config.rateLimits === undefined ? {} : { rateLimits: config.rateLimits }),
@@ -184,6 +205,12 @@ async function commandRun(flags) {
             ...(config.network === undefined ? {} : { network: config.network }),
         });
     }
+    catch (error) {
+        if (!(error instanceof ScopeError))
+            throw error;
+        process.stderr.write(`${error.message}\n`);
+        return 2;
+    }
     finally {
         stderrProgress?.stop();
         fileProgress.stop();
@@ -205,6 +232,7 @@ async function commandRun(flags) {
         model: result.model,
         profile: result.profile,
         profileExclusions: result.profileExclusions,
+        scope: result.scope,
         startedAt,
         ...(result.exchanges === undefined ? {} : { exchanges: result.exchanges }),
         ...(result.network === undefined ? {} : { network: result.network }),
@@ -237,11 +265,7 @@ async function commandRun(flags) {
         process.stdout.write(`  network: ${result.network.kind} — run incomplete\n`);
     }
     process.stdout.write(`  latest: ${allocated.latest}\n\n`);
-    /* Exit code counts root causes, not raw findings: gaps and blocked entries are information,
-     * not failures, and a CI gate should react to defects only. */
-    if (result.network?.incomplete === true)
-        return 1;
-    return result.findings.filter((f) => f.verdict !== "COVERAGE_GAP" && f.verdict !== "BLOCKED").length > 0 ? 1 : 0;
+    return exitCode(result);
 }
 export async function main() {
     const { command, flags } = parseArgs(process.argv.slice(2));
@@ -436,7 +460,8 @@ export async function main() {
         return commandRun(flags);
     const specFlag = str(flags, "spec");
     const configPath = str(flags, "config");
-    const specSource = specFlag ?? (configPath === undefined ? undefined : (await loadConfig(configPath)).spec);
+    const loaded = configPath === undefined ? undefined : await loadConfig(configPath);
+    const specSource = specFlag ?? loaded?.spec;
     if (specSource === undefined) {
         process.stderr.write("oat: --spec (or --config) is required\n\n" + USAGE);
         return 2;
@@ -454,9 +479,26 @@ export async function main() {
             throw error;
     }
     switch (command) {
-        case "plan":
-            process.stdout.write(report.plan(model, flags.json === true));
+        case "plan": {
+            const ops = list(flags, "ops") ?? loaded?.ops;
+            const only = list(flags, "only") ?? loaded?.only;
+            let scope;
+            try {
+                scope = planScope(model, resolveTargetScope(model, {
+                    ...(ops === undefined ? {} : { ops }),
+                    ...(only === undefined ? {} : { only }),
+                    authCreates: authStepOperationIds(loaded?.principals ?? []),
+                }));
+            }
+            catch (error) {
+                if (!(error instanceof ScopeError))
+                    throw error;
+                process.stderr.write(`${error.message}\n`);
+                return 2;
+            }
+            process.stdout.write(report.plan(model, flags.json === true, scope.mode === "targeted" ? scope : undefined));
             return 0;
+        }
         case "doctor": {
             const config = configPath === undefined ? undefined : interpolate(await loadConfig(configPath));
             const output = report.doctor(model, externalRefs, flags.json === true, config === undefined

package/dist/config/define-config.d.ts

@@ -395,8 +395,14 @@ export interface OatConfig {
     cohortSize?: number;
     /** Requests allowed in flight at once. Past a server's comfort this makes runs slower. */
     maxInFlight?: number;
-    /** Restrict the run to these entity names. */
+    /** Grade every operation these entities own, and nothing else. Joins `ops` as a union. */
     only?: string[];
+    /**
+     * Grade only these operationIds; every other operation is support — called to reach or observe
+     * a target, never graded. `*` globs within an id (`row.*`); `<originId>:<operationId>` targets a
+     * secondary origin. `--ops` on the CLI replaces this list.
+     */
+    ops?: string[];
     /**
      * Named profiles this run can select between, keyed by name. `"full"` and `"cheap"` exist
      * implicitly and need no entry here; add one only for a profile a cost band can't express.

package/dist/config/define-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"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"}

package/dist/config/define-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwIH,MAAM,UAAU,UAAU,CAAC,IAAmB;IAC7C,OAAO,UAAU,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,CAAA;AACrF,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAmB;IAC7C,OAAO,OAAO,IAAI,IAAI,CAAA;AACvB,CAAC;AA4VD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC7C,OAAO,MAAM,CAAA;AACd,CAAC"}
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwIH,MAAM,UAAU,UAAU,CAAC,IAAmB;IAC7C,OAAO,UAAU,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,CAAA;AACrF,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAmB;IAC7C,OAAO,OAAO,IAAI,IAAI,CAAA;AACvB,CAAC;AAkWD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC7C,OAAO,MAAM,CAAA;AACd,CAAC"}

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export { NetworkError, classifyNetworkError, isNetworkError } from "./runtime/ne
 export type { NetworkKind } from "./runtime/network.ts";
 export { run } from "./runtime/run.ts";
 export type { RunOptions, RunResult } from "./runtime/run.ts";
+export { planScope, resolveTargetScope, ScopeError } from "./runtime/scope.ts";
+export type { OperationCoverage, OperationStatus, ScopePlan, ScopeReport, SupportUse, TargetScope, } from "./runtime/scope.ts";
 export type { Actor } from "./runtime/checks.ts";
 export type { Finding, Verdict } from "./runtime/finding.ts";
 export { buildMatrixGraph, matrixViewFromReport, renderMatrixGraph, renderMatrixHtml } from "./report/matrix.ts";

package/dist/index.js

@@ -9,6 +9,7 @@ export { dereference, loadSpec, normalisePath, parseRouteRef } from "./spec/load
 export { AuthRefreshRequiredError } from "./runtime/auth.js";
 export { NetworkError, classifyNetworkError, isNetworkError } from "./runtime/network.js";
 export { run } from "./runtime/run.js";
+export { planScope, resolveTargetScope, ScopeError } from "./runtime/scope.js";
 export { buildMatrixGraph, matrixViewFromReport, renderMatrixGraph, renderMatrixHtml } from "./report/matrix.js";
 export { coverageByCheck, renderConsole, renderJson, renderMarkdown, renderRepros } from "./report/render.js";
 //# sourceMappingURL=index.js.map

package/dist/report/console.d.ts

@@ -7,6 +7,7 @@
  */
 import type { EntityConfig, OatConfig, QueryCapabilities } from "../config/define-config.ts";
 import type { SpecModel } from "../spec/graph.ts";
+import { type ScopePlan } from "../runtime/scope.ts";
 export interface DoctorConfig {
     query?: QueryCapabilities;
     entities?: Record<string, EntityConfig>;
@@ -27,7 +28,7 @@ export interface DoctorConfig {
  * not apply.
  */
 export declare const TAG_UNLOCKS: Record<string, readonly string[]>;
-declare function plan(model: SpecModel, asJson: boolean): string;
+declare function plan(model: SpecModel, asJson: boolean, scope?: ScopePlan): string;
 declare function doctor(model: SpecModel, externalRefs: string[], asJson: boolean, config?: DoctorConfig): {
     text: string;
     blocking: number;

package/dist/report/console.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/report/console.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAE5F,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAU9D,MAAM,WAAW,YAAY;IAC5B,KAAK,CAAC,EAAE,iBAAiB,CAAA;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACvC,KAAK,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,0BAA0B,CAAC,CAAA;CACzE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CA+BzD,CAAA;AA0CD,iBAAS,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAoEvD;AA+KD,iBAAS,MAAM,CACd,KAAK,EAAE,SAAS,EAChB,YAAY,EAAE,MAAM,EAAE,EACtB,MAAM,EAAE,OAAO,EACf,MAAM,CAAC,EAAE,YAAY,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CA8OpC;AAED,eAAO,MAAM,MAAM;;;CAAmB,CAAA"}
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/report/console.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAE5F,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAUvE,MAAM,WAAW,YAAY;IAC5B,KAAK,CAAC,EAAE,iBAAiB,CAAA;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACvC,KAAK,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,0BAA0B,CAAC,CAAA;CACzE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CA+BzD,CAAA;AA0CD,iBAAS,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,CAuE1E;AA2MD,iBAAS,MAAM,CACd,KAAK,EAAE,SAAS,EAChB,YAAY,EAAE,MAAM,EAAE,EACtB,MAAM,EAAE,OAAO,EACf,MAAM,CAAC,EAAE,YAAY,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CA8OpC;AAED,eAAO,MAAM,MAAM;;;CAAmB,CAAA"}

package/dist/report/console.js

@@ -6,6 +6,7 @@
  * and work the list down.
  */
 import { formatUniqueSets } from "../spec/extensions.js";
+import { describeRequested } from "../runtime/scope.js";
 import { canWriteFilterOp } from "../spec/conventions.js";
 import { anyFieldAllows, fieldAllowsNulls, mergeQueryCapabilities, opsAreClosed, } from "../spec/query-capabilities.js";
 /**
@@ -89,17 +90,20 @@ function lifecycleGlyphs(entity) {
     ];
     return slots.map(([letter, opId]) => (opId === undefined ? "·" : letter)).join("");
 }
-function plan(model, asJson) {
+function plan(model, asJson, scope) {
     if (asJson) {
         return `${JSON.stringify({
             entities: [...model.entities.values()],
             operations: model.operations,
             roots: model.roots,
+            ...(scope === undefined ? {} : { scope }),
             unique: [...model.entities.values()]
                 .filter((entity) => entity.unique !== null)
                 .map((entity) => ({ entity: entity.name, unique: entity.unique })),
         }, null, 2)}\n`;
     }
+    if (scope !== undefined)
+        return planScopeText(scope);
     const lines = [];
     const entities = [...model.entities.values()].sort((a, b) => a.name.localeCompare(b.name));
     lines.push("");
@@ -147,6 +151,34 @@ function plan(model, asJson) {
     lines.push("");
     return lines.join("\n");
 }
+/** What a targeted run would grade, queue and call — the dry run behind `oat plan --ops`. */
+function planScopeText(scope) {
+    const lines = ["", `  scope: targeted (${describeRequested(scope.requested)})`, ""];
+    const width = Math.max(12, ...[...scope.targets, ...scope.untestable].map((t) => t.operationId.length)) + 2;
+    lines.push("  targets");
+    if (scope.targets.length === 0)
+        lines.push("    — none gradable");
+    for (const target of scope.targets) {
+        lines.push(`    ${target.operationId.padEnd(width)}entity ${(target.entity ?? "—").padEnd(14)}${target.checks.length} check(s)`);
+    }
+    if (scope.untestable.length > 0) {
+        lines.push("  untestable — a run reports these untested and exits 1");
+        for (const item of scope.untestable)
+            lines.push(`    ${item.operationId.padEnd(width)}${item.reason}`);
+    }
+    if (scope.excluded.length > 0) {
+        lines.push("  excluded by the profile");
+        for (const item of scope.excluded)
+            lines.push(`    ${item.operationId.padEnd(width)}${item.reason}`);
+    }
+    for (const [origin, ops] of Object.entries(scope.origins)) {
+        lines.push(`  origin ${origin}: ${ops.join(", ")}`);
+    }
+    lines.push(`  entities queued: ${scope.entities.length === 0 ? "none" : scope.entities.join(", ")}`);
+    lines.push(`  support (called, never graded): ${scope.support.length === 0 ? "none" : scope.support.join(", ")}`);
+    lines.push("");
+    return lines.join("\n");
+}
 function inviteAcceptMode(spec) {
     if (spec === null)
         return "—";