@pii: carry the reason/lawful-basis documentation, not just the marker

[woksin]

Summary

@pii (and @sensitive) are bare markers. Real applications annotate PII with why it is personal data — purpose, lawful basis, whose subject it lives under, erasability — and that documentation is exactly what a compliance reader wants from a Screenplay. Today it has nowhere to go, so generators must throw it away.

Evidence (real application)

Ada carries 36 [PII("…")] attributes on concepts, each a small GDPR record:

[PII("Partner payout bank account — financial data. Remits self-billing payments; lawful basis: contract performance / legal obligation. Fraud-sensitive; personal only for sole-proprietor (ENK) partners.")]
public record BankAccountNumber(string Value) : ConceptAs<string>(Value);

[PII("Reason a user account was deactivated — personal data about that user. Audit of the decision; lawful basis: legitimate interest / legal obligation; under the user's own subject, erasable with their key.")]
public record DeactivationReason(string Value) : ConceptAs<string>(Value);

The generated document (Cratis.Arc.Screenplay 20.65.0) reduces every one of these to:

concept BankAccountNumber : String @pii

Screenplay's stated design goal is that "concepts carry compliance" — with a bare marker, they carry the flag but not the compliance.

Solution

Use an indented form with reason:

concept BankAccountNumber : String @pii
  pii reason "Partner payout bank account — financial data. …"

The concept-attribute regex currently accepts any @word with no arguments; whichever form is chosen should keep unknown attributes tolerated as today.

Context

Found while validating a generated 5,348-line document from a production Arc application against its source — all 36 PII rationales were lost in generation.

[woksin]

Implemented in #45, which is open for review and deliberately not merged — it carries several language decisions together and they are worth deciding as a set.

See the reviewer notes on the PR for the breaking-change surface and the choices that were not forced.

[woksin]

Revisiting the syntax choice, because I think I under-weighted your form.

#45 implements the argument form @pii("…") rather than the indented pii reason "…" you proposed. My reasoning was that it keeps the attribute on one line where the other attributes already are, applies uniformly to any @word, and needs no new block. I still think those hold. But I measured the thing I was actually worried about and it does not favour my choice the way I assumed:

concept BankAccountNumber : String @pii("Partner payout bank account — financial data. …")   240 chars
concept BankAccountNumber : String @pii                                                       39 chars
  pii reason "Partner payout bank account — financial data. …"                               212 chars

Both are long, because the reason dominates either way — so "the argument form is more compact" is not true in any useful sense. What is different is that the indented form keeps the declaration line scannable. With the argument form, every PII concept's declaration runs off the screen, and a reader skimming the concept list — which is a normal way to read the top of a document — can no longer see the shape of it. At the 36 rationales you measured, that is 36 unreadable declaration lines.

And it compounds: @pii("…") @sensitive("…") on one line is unbounded in a way the indented form is not.

So the honest summary of the trade-off:

• @pii("…") — uniform across any attribute, no new block, one place to look. Costs declaration-line scannability, and gets worse with multiple reasoned attributes.
• pii reason "…" — declaration line stays short and skimmable, each reason gets its own line, scales to several attributes. Costs a second kind of thing in the concept body (which today holds validate blocks) and a per-attribute prefix convention.

I would now call this closer than I did in the PR notes, and I no longer have a strong preference. @einari — it is a small change to switch #45 to the indented form if you prefer it; the parsing and printing work is the same either way, and I would rather change it before the syntax ships than after.