query: express identity/organization scoping of results

[woksin]

Summary

Queries cannot express that their result set is scoped to the calling identity (or the caller's organization/tenant). authorize states who may call a query; nothing states what subset of the data the caller sees — yet "my items", "my organization's items" is one of the most common query shapes in a multi-actor application, and the distinction between All (advisor sees everything) and Mine (consultant sees their own) is precisely what a reader of the document needs in order to understand the access model.

Evidence (real application)

In Ada, at least 16 queries are identity-scoped, visible in their names and their IIdentityAccessor usage: Mine (×5), ForCurrentPartner (×6), ForCurrentCustomer (×4), ForCurrentAccess. Example:

public static ISubject<IEnumerable<Timesheet>> Mine(
    IMongoCollection<Timesheet> collection, IIdentityAccessor identityAccessor) => ...

The generated document renders these identically to unscoped queries:

query Mine => Timesheet[]
  authorize Consultant

which reads as "any consultant can query all timesheets" — the opposite of what the code does.

Suggested direction

A scoping declaration on the query (syntax open):

query Mine => Timesheet[]
  scoped to identity
  authorize Consultant

query ForCurrentPartner => PartnerEngagement[]
  scoped to identity organization

Alternatively a by $identity...-style parameter convention reusing the existing by clause. The ask is that caller-scoping is statable; the shape can follow whatever identity model Stage exposes.

Context

Found while validating a generated 5,348-line document from a production Arc application against its source (Cratis.Arc.Screenplay 20.65.0).

[woksin]

Verified

Re-verified against main. QuerySyntax carries Name, ReturnType, By, Filters and Authorize — plus IsObservable once #37 lands. authorize resolves to a policy and answers may this caller run the query; nothing anywhere answers which rows come back. ScreenParser binds a screen to a query by name only.

The fidelity problem in the issue is real and worth stating plainly: query GetOverdueInvoices => OverdueInvoicesReadModel[] with authorize IsAccountant (invoicing.play:696) reads as "accountants can see the overdue invoices" — all of them. If the implementation actually returns only the caller's own, the document asserts something close to the opposite of the code's behavior, and it does so silently. A document that quietly overstates who can see what is worse than one that says nothing.

The language does already know about identity: $context.identity.id is in the expression grammar (grammar.md, MappingSource) and is used in the sample at :163, :198 and :273 to stamp events with who caused them.

Design alternatives

1. A scoped to identity [<dimension>] directive in the query body.

query Mine => Timesheet[]
  scoped to identity
  authorize Consultant

query ForMyOrganization => Invoice[]
  scoped to identity organization
  authorize CustomerAdvisor

States the policy — results are narrowed to the caller — without stating the mechanism. It sits beside authorize where a reader looking for "who sees what" already looks, and it prints as one more body directive so round-tripping is trivial. The optional dimension covers the common organization/tenant case.

Cost: scoped to identity organization names a dimension the language does not otherwise know exists. Whatever organization means has to be defined somewhere — realistically the identity model — and if that model is per-application, this is product policy leaking into the language.

2. A parameter convention — by $identity / filter $identity.organization.

query Mine => Timesheet[]
  by $identity

Reuses the existing parameter slots and the $-prefixed expression vocabulary the language already has, so nothing new is invented — it is the same idea as $context.identity.id appearing as a mapping source. A generator can recover it mechanically.

Cost: by currently means "the caller supplies this value", and $identity means "the server supplies it". Overloading by with a parameter the caller cannot pass blurs what has been a clean distinction, and a screen binding data … via query Mine by … would have to know not to bind it.

3. Say nothing about scoping; make authorize honest instead.

Leave the query surface alone and treat this as a documentation problem: authorize means "may run", full stop, and result-level narrowing is realization detail behind file/handler. Consistent with #40 in one direction (the document does not pretend to describe code it cannot see) and inconsistent in the other — declarative-first says the document should be able to state the behavior, and "these results are the caller's own" is behavior, not realization.

Recommendation

Alternative 1, scoped to identity, with the dimension optional and free-form — and deliberately not enumerated by the language. The compiler records the dimension as an opaque name the way it records a policy name; what organization means is the application's identity model, which is exactly the kind of thing general.md calls product policy and keeps out of the shared corpus. That gets the fidelity win (a reader can no longer mistake authorize Consultant for "sees everything") without the language pretending to own an identity model it does not define.

I would resist alternative 2 despite it being cheaper. by meaning "caller-supplied" is a distinction worth keeping; the moment by $identity exists, every consumer of by needs a special case.

Sequencing

Depends on how Stage models identity, which I do not think is settled — this is the one issue in this batch where the language cannot go first, because the right shape follows from what Stage can actually enforce.

It pairs with #37 (now implemented): observable and scoped to identity are both "facts about the query that change what the reader must build", and they should end up as sibling body directives with the same shape. If scoped to lands later, matching #37's directive form costs nothing.

No dependency on the declarable-name work in #28/#29/#39 — a scoping dimension is not a declared entity under this recommendation.

@einari — the question is whether the language should carry the scoping dimension at all, or only the fact that scoping happens. I have argued for an opaque dimension name, but if Stage's identity model has a fixed set of dimensions, enumerating them in the grammar would be more checkable — that is your call, not mine.