@@ -0,0 +1,18 @@
+---
+'@objectstack/scenarios': patch
+---
+
+feat(scenarios): a scenario card declares which seed fields hold a user handle and which seed row each scoped persona is, and a refused seed row takes out only the turns whose answer it changes
+
+Clause-②: yes (narrowing) — the published card schema (`ScenarioCardSchema` in the `.` entry) gains `run.userHandleFields` and `personas[].record`, and the loader (`loadScenarios`, `loadScenarioFile`) refuses a card it loaded before: a persona `scope` rule ending on a field that is neither `id`, a declared lookup or select, nor a declared user-handle field, and a scoped persona that names no person. `truthsOver` is a new export of the same entry. In `./runner`, `seedDependence` now takes the loaded scenario (it was handed the card) and its `question` takes the persona the turn is asked as, and `RunHalf.seed` gains `rewritten`.
+Metadata-protocol: none
+
+<!-- adr-0087: not-required (no-migration-prescription) The card format is QA tooling in a devx package, not the metadata protocol: no key of any platform schema is added, removed, renamed or re-shaped, and nothing an app author writes is refused. What moves is which scenario cards the loader accepts; a card author adds the two declarations the refusal names, and there is nothing for a metadata migration to rewrite. -->
+
+**BREAKING** accept-set narrowing at the scenario card loader (`@objectstack/scenarios`): a card that leaves the runner to infer what a scope value names is refused until it declares it. All nine cards in `docs/qa/scenarios/` carry the declarations and load as before.
+
+- **User-handle fields, declared.** `run.userHandleFields: [{ object, field }]` lists the seed fields whose text stands for a user (`account.owner` = `u_sam`). The runner loads each such cell with the user's id, and `userHandleFields` (runner `prompts.ts`) reads this list instead of inferring it from what the card does not declare. The loader refuses a scope rule whose last field is none of `id`, a declared lookup, a declared select or a declared handle field, and a handle declaration on the row id, a lookup, a select or a field no seed row carries. The run record's `seed.rewritten` lists the fields the seed rewrote. Across the nine cards the rewritten set is unchanged: `account.owner`, `invoice.owner`, `task.assignee`.
+- **The person a persona is.** `personas[].record: { object, id }` names the seed row that is this person (`{ object: "employee", id: "e06" }`). It is required for a persona with a `scope`, unless the persona is named by a direct scope rule on a declared handle field (the three control cards), and optional for a global persona. The loader refuses a record that names no seeded row. The person object's user field is `user` by name. The runner does not read `record` yet.
+- **Seed dependence per turn.** When the app refuses a seed row, the runner computes each question's truth again over the seed less the refused rows and their children (`truthsOver`, the loader's own rules), and marks not measured only the turns whose expected answer changes. Before, every question on an object holding a refused row was not measured. On `crm_account_with_contacts`, refusing contact `ct4` now leaves `contacts_per_account` as `sdr` (whose scope never reads it) measured.
+
+**Who moves.** An author of a scenario card in a private overlay: add `run.userHandleFields` for each field holding a user handle, and `record` on each scoped persona that is a seed row. A caller of `seedDependence` from `@objectstack/scenarios/runner` passes the `LoadedScenario` and asks `question(q, persona)` per turn (`null` for a turn over all rows).
@@ -33,7 +33,7 @@ question's computed truth; a card that does not load is red in CI.
 | 1 | `prompt` | `{ short, detailed }`, each `{ zh?, en? }` with at least one language. |
 | 2 | `expect` | The structural expectation the deterministic scorer reads, field for field: `objects`, `minFieldsPerObject?`, `selectFields?` (`{ object, field, minOptions }`), `lookups?` (`{ object, field, to }`), `dashboards?`, `appNavTargets?`. The runner's build prompt states every row by name ([Build checks trace to the prompt](#build-checks-trace-to-the-prompt)). |
 | 3 | `capabilities`, `businessFunctions` | Tags `<area>.<name>`, where `<area>` is a closed set: the basenames of `docs/qa/platform-checklist/areas/*.json`, read from the tree. `businessFunctions` is the marketplace taxonomy's business-function facet, read from `@objectstack/spec/marketplace` (`MarketplaceBusinessFunctionsSchema`, defined once in `packages/spec/src/marketplace/taxonomy.zod.ts`): 1-3 distinct values, the primary one first — the card is classified the way the template it graduates into will be listed. |
-| 4 | `run.seed`, `run.questions`, `run.personas` | Seed rows per object; at least five read-only questions, each with a **declarative** truth spec; at least two personas, each a role, the objects or fields it must NOT see, and optionally a row `scope`. |
+| 4 | `run.seed`, `run.userHandleFields?`, `run.questions`, `run.personas` | Seed rows per object, and which seed fields hold a user handle; at least five read-only questions, each with a **declarative** truth spec; at least two personas, each a role, the objects or fields it must NOT see, and optionally a row `scope` and the person `record` it is. |
 | 5 | `run.operations`, `run.guardrails`, `run.agentActions?` | At least two writes, each acting as a persona and declaring its `outcome`; the five guardrail checks; optionally the agent-callable business actions. |
 | 6 | `iterate` | A one-sentence change request plus the `expectDelta` it should add to `expect`. |
 
@@ -159,7 +159,23 @@ one of three shapes: `{ kind: "scalar", value }`, `{ kind: "groups", groups: [{
 ## Personas, operations and guardrails
 
 A persona names at least one object or field it must not see; its references must resolve
-against `expect.objects` and the seed. An operation is a `create` (with `values`), an
+against `expect.objects` and the seed.
+
+**What a scope value names is declared, never inferred.** The field a `scope` rule ends on
+(the last hop of a path) is `id` or a declared lookup (the value names a row), a declared
+select (an option), or a **user-handle field**: a seed field listed in
+`run.userHandleFields` (`[{ "object": "account", "field": "owner" }]`), whose text
+(`u_sam`) stands for a user. The runner loads a handle field's cells with that user's id and
+never the text, and the run record lists the fields it rewrote (`seed.rewritten`). The loader
+refuses a scope rule ending on any other field, and a handle declaration on the row id, a
+declared lookup or select, or a field no seed row carries.
+
+**A scoped persona names the person it is.** `record: { "object": "employee", "id": "e06" }`
+is the seed row that is this person (an employee, an agent, a customer); the loader refuses
+one naming no seeded row. It is required on a persona with a `scope`, unless that persona is
+named through a handle instead (a direct scope rule on a declared user-handle field,
+`owner: u_sam`, as on the three controls), and optional on a global one. The person object's
+user field is `user`, fixed by name: no card chooses it. An operation is a `create` (with `values`), an
 `update` (with `target` and `values`) or a `delete` (with `target`); a target is a seeded row
 id, and every written field is one the seed carries. Every operation names the persona it
 acts for (`actingAs`) and declares its `outcome`, so grading reads it with code only:
 
@@ -767,6 +767,7 @@
       {
         "id": "employee",
         "role": "Employee (asset holder), Sales - e06",
+        "record": {"object": "employee", "id": "e06"},
         "hidden": {
           "objects": ["depreciation_entry"],
           "fields": [
@@ -787,6 +788,7 @@
       {
         "id": "dept_manager",
         "role": "Department manager, Sales - e05",
+        "record": {"object": "employee", "id": "e05"},
         "hidden": {"fields": [{"object": "employee", "field": "home_address"}]},
         "scope": [
           {"object": "department", "field": "id", "value": "dep_sales"},
 
@@ -39,6 +39,7 @@
         {"id": "ct5", "full_name": "Eli Moss", "email": "eli@bitworks.test", "account": "ac3"}
       ]
     },
+    "userHandleFields": [{"object": "account", "field": "owner"}],
     "questions": [
       {
         "id": "tech_accounts",
 
@@ -46,6 +46,7 @@
         {"id": "l5", "invoice": "i3", "product": "Gadget", "quantity": 3, "unit_price": 25, "amount": 75}
       ]
     },
+    "userHandleFields": [{"object": "invoice", "field": "owner"}],
     "questions": [
       {
         "id": "invoices_not_draft",
 
@@ -817,6 +817,7 @@
       {
         "id": "employee",
         "role": "Employee, Engineering, two years of service — e07",
+        "record": {"object": "employee", "id": "e07"},
         "hidden": {"fields": [{"object": "employee", "field": "personal_phone"}]},
         "scope": [
           {"object": "leave_request", "field": "employee", "value": "e07"},
@@ -828,6 +829,7 @@
       {
         "id": "dept_manager",
         "role": "Department manager, Engineering — e05",
+        "record": {"object": "employee", "id": "e05"},
         "hidden": {
           "fields": [
             {"object": "employee", "field": "personal_phone"},
 
@@ -838,6 +838,7 @@
       {
         "id": "sales_rep",
         "role": "Sales rep, team east, owner of Cedar Logistics and Bluebird Outfitters — e03",
+        "record": {"object": "employee", "id": "e03"},
         "hidden": {"objects": ["payment"], "fields": [{"object": "product", "field": "unit_cost"}]},
         "scope": [
           {"object": "account", "field": "owner", "value": "e03"},
@@ -850,6 +851,7 @@
       {
         "id": "sales_manager",
         "role": "Sales manager, team east — e01",
+        "record": {"object": "employee", "id": "e01"},
         "hidden": {"fields": [{"object": "payment", "field": "bank_reference"}]},
         "scope": [
           {"object": "account", "field": "owner.team", "value": "east"},
 
@@ -48,6 +48,7 @@
         }
       ]
     },
+    "userHandleFields": [{"object": "task", "field": "assignee"}],
     "questions": [
       {
         "id": "open_tasks",
 
@@ -848,6 +848,7 @@
       {
         "id": "requester",
         "role": "Requester (employee), Sales — e02",
+        "record": {"object": "employee", "id": "e02"},
         "hidden": {
           "fields": [{"object": "department", "field": "budget"}, {"object": "supplier", "field": "bank_account"}]
         },
@@ -862,6 +863,7 @@
       {
         "id": "dept_manager",
         "role": "Department manager, Sales — e13",
+        "record": {"object": "employee", "id": "e13"},
         "hidden": {"fields": [{"object": "supplier", "field": "bank_account"}]},
         "scope": [
           {"object": "department", "field": "id", "value": "dep_sales"},
 
@@ -691,6 +691,7 @@
       {
         "id": "support_agent",
         "role": "Support agent, Billing group — a02",
+        "record": {"object": "agent", "id": "a02"},
         "hidden": {
           "fields": [{"object": "customer", "field": "contract_value"}, {"object": "agent", "field": "hourly_cost"}]
         },
@@ -703,6 +704,7 @@
       {
         "id": "team_lead",
         "role": "Team lead, Technical group — a04",
+        "record": {"object": "agent", "id": "a04"},
         "hidden": {"fields": [{"object": "agent", "field": "hourly_cost"}]},
         "scope": [
           {"object": "agent", "field": "group", "value": "grp_tech"},
@@ -714,6 +716,7 @@
       {
         "id": "portal_customer",
         "role": "Customer portal user, Harbor & Pine Foods — cus_03",
+        "record": {"object": "customer", "id": "cus_03"},
         "hidden": {
           "objects": ["escalation_rule"],
           "fields": [
Original file line number	Diff line number	Diff line change
`@@ -39,6 +39,7 @@`
`39`	`39`	`{"id": "ct5", "full_name": "Eli Moss", "email": "eli@bitworks.test", "account": "ac3"}`
`40`	`40`	`]`
`41`	`41`	`},`
	`42`	`+ "userHandleFields": [{"object": "account", "field": "owner"}],`
`42`	`43`	`"questions": [`
`43`	`44`	`{`
`44`	`45`	`"id": "tech_accounts",`
Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,7 @@`
`46`	`46`	`{"id": "l5", "invoice": "i3", "product": "Gadget", "quantity": 3, "unit_price": 25, "amount": 75}`
`47`	`47`	`]`
`48`	`48`	`},`
	`49`	`+ "userHandleFields": [{"object": "invoice", "field": "owner"}],`
`49`	`50`	`"questions": [`
`50`	`51`	`{`
`51`	`52`	`"id": "invoices_not_draft",`
Original file line number	Diff line number	Diff line change
`@@ -48,6 +48,7 @@`
`48`	`48`	`}`
`49`	`49`	`]`
`50`	`50`	`},`
	`51`	`+ "userHandleFields": [{"object": "task", "field": "assignee"}],`
`51`	`52`	`"questions": [`
`52`	`53`	`{`
`53`	`54`	`"id": "open_tasks",`