From 51b7f1b14b0689c680b58094d3b3116564996f80 Mon Sep 17 00:00:00 2001
From: Daniel Sainati <sainatidaniel@gmail.com>
Date: Mon, 16 Oct 2023 15:08:42 -0400
Subject: [PATCH 1/3] add flip

---
 .../20231016-entitlement-mapping-syntax.md    | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 cadence/20231016-entitlement-mapping-syntax.md

diff --git a/cadence/20231016-entitlement-mapping-syntax.md b/cadence/20231016-entitlement-mapping-syntax.md
new file mode 100644
index 00000000..cb1fa44c
--- /dev/null
+++ b/cadence/20231016-entitlement-mapping-syntax.md
@@ -0,0 +1,43 @@
+---
+status: draft 
+flip: NNN (set to the issue number)
+authors: Daniel Sainati (daniel.sainati@dapperlabs.com)
+sponsor: Daniel Sainati (daniel.sainati@dapperlabs.com)
+updated: 2023-10-16
+---
+
+# FLIP NNN: Improve Entitlement Mapping Syntax
+
+## Objective
+
+This proposes a syntax change to make entitlement-mapped fields more visually distinct from entitled fields.
+
+## Motivation
+
+User feedback has indicated that entitlement mappings are too easy to confuse with entitlements, 
+and since one of them has default behavior for public access and the other prevents it, 
+it can be difficult to reason about what fields and functions are publicly available in the presence
+of both entitled and mapped fields
+
+## User Benefit
+
+This will make it easier for users to distinguish between entitled members and mapped members. 
+
+## Design Proposal
+
+Currently, an entitlement mapped field or an entitlement mapped reference is specified by using the
+name of a mapping (e.g. `M`) in an `access` or `auth` modifier (e.g. `access(M)` or `auth(M)`).  
+
+Instead, we would require the keyword `mapping` to be present in the modifiers to indicate
+that `M` is a mapping here, rather than an entitlement. 
+So the above modifiers would become `access(mapping M)` and `auth(mapping M)`
+
+### Drawbacks
+
+This makes the creation of entitlement mapped fields and functions 16 characters more verbose. I.e. a function
+that was previously declared as `access(M) fun foo(): auth(M) &T` would instead have to be declared as 
+`access(mapping M) fun foo(): auth(mapping M) &T`, which is more verbose. 
+
+### Alternatives Considered
+
+We have not discussed alternative syntactic changes, but are open to suggestions. 
\ No newline at end of file

From 9a98d1c3404dcd9d3532f93a921069e40d3d11e2 Mon Sep 17 00:00:00 2001
From: Daniel Sainati <sainatidaniel@gmail.com>
Date: Tue, 24 Oct 2023 12:14:47 -0400
Subject: [PATCH 2/3] Apply suggestions from code review

---
 cadence/20231016-entitlement-mapping-syntax.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/cadence/20231016-entitlement-mapping-syntax.md b/cadence/20231016-entitlement-mapping-syntax.md
index cb1fa44c..debe614b 100644
--- a/cadence/20231016-entitlement-mapping-syntax.md
+++ b/cadence/20231016-entitlement-mapping-syntax.md
@@ -1,6 +1,6 @@
 ---
-status: draft 
-flip: NNN (set to the issue number)
+status: approved 
+flip: 210
 authors: Daniel Sainati (daniel.sainati@dapperlabs.com)
 sponsor: Daniel Sainati (daniel.sainati@dapperlabs.com)
 updated: 2023-10-16

From df2d4b1273cd121ac366cdbb358523e9b6dcba9e Mon Sep 17 00:00:00 2001
From: Daniel Sainati <sainatidaniel@gmail.com>
Date: Tue, 24 Oct 2023 13:04:40 -0400
Subject: [PATCH 3/3] clarify

---
 cadence/20231016-entitlement-mapping-syntax.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/cadence/20231016-entitlement-mapping-syntax.md b/cadence/20231016-entitlement-mapping-syntax.md
index cb1fa44c..aa2e4f71 100644
--- a/cadence/20231016-entitlement-mapping-syntax.md
+++ b/cadence/20231016-entitlement-mapping-syntax.md
@@ -17,7 +17,23 @@ This proposes a syntax change to make entitlement-mapped fields more visually di
 User feedback has indicated that entitlement mappings are too easy to confuse with entitlements, 
 and since one of them has default behavior for public access and the other prevents it, 
 it can be difficult to reason about what fields and functions are publicly available in the presence
-of both entitled and mapped fields
+of both entitled and mapped fields.
+
+For example, given some definitions:
+
+```
+entitlement X
+entitlement Y
+entitlement mapping M {
+    X -> Y
+}
+resource R {
+    access(X) let foo: T
+    access(M) let bar: T
+}
+```
+
+It is not immediately obvious that given a reference `r` of type `&R`, `r.foo` would fail statically but `r.bar` would succeed and produce a `&T` reference.
 
 ## User Benefit