From e718f9846e1c63e554f27cb40b98ad5d75a639dd Mon Sep 17 00:00:00 2001
From: Luke Wagner <mail@lukewagner.name>
Date: Fri, 16 Jun 2023 18:46:59 -0500
Subject: [PATCH 1/2] Add Wit.md section for resource items

---
 design/mvp/WIT.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md
index cbd51b36..1ceba008 100644
--- a/design/mvp/WIT.md
+++ b/design/mvp/WIT.md
@@ -1002,6 +1002,59 @@ union-cases ::= ty
               | ty ',' union-cases?
 ```
 
+### Item: `resource`
+
+A `resource` statement defines a new abstract type for a *resource*, which is
+an entity with a lifetime that can only be passed around indirectly via [handle
+values](#handles). Resource types are used in interfaces to describe things
+that can't or shouldn't be copied by value.
+
+For example, the following Wit defines a resource type and a function that
+takes and returns a handle to a `blob`:
+```wit
+resource blob
+transform: func(blob) -> blob
+```
+
+As syntactic sugar, resource statements can also declare any number of
+*methods*, which are functions that implicitly takes a `self` borrowed handle
+parameter. A resource statement can also contain any number of *static
+functions*, which do not have an implicit `self` parameter but are meant to be
+lexically nested in the scope of the resource type. Lastly, a resource
+statement can contain at most one *constructor* function, which is syntactic
+sugar for a function returning a handle of the containing resource type.
+
+For example, the following resource definition:
+```wit
+resource blob {
+    constructor(init: list<u8>)
+    write: func(bytes: list<u8>)
+    read: func(n: u32) -> list<u8>
+    merge: static func(lhs: borrow<blob>, rhs: borrow<blob>) -> blob
+}
+```
+desugars into:
+```wit
+resource blob
+%[constructor]blob: func(self: borrow<blob>, bytes: list<u8>) -> blob
+%[method]blob.write: func(self: borrow<blob>, bytes: list<u8>)
+%[method]blob.read: func(self: borrow<blob>, n: u32) -> list<u8>
+%[static]blob.merge: func(lhs: borrow<blob>, rhs: borrow<blob>) -> blob
+```
+These `%`-prefixed [`name`s](Explainer.md) embed the resource type name so that
+bindings generators can generate idiomatic syntax for the target language or
+(for languages like C) fall back to an appropriately-prefixed free function
+name.
+
+Specifically, the syntax for a `resource` definition is:
+```ebnf
+resource-item ::= 'resource' id resource-methods?
+resource-methods ::= '{' resource-method* '}'
+resource-method ::= func-item
+                  | id ':' 'static' func-type
+                  | 'constructor' param-list
+```
+
 ## Types
 
 As mentioned previously the intention of `wit` is to allow defining types

From 10346b5b84fb8b93ca382e8b60a5d2924ec9c2e0 Mon Sep 17 00:00:00 2001
From: Luke Wagner <mail@lukewagner.name>
Date: Mon, 19 Jun 2023 11:32:09 -0500
Subject: [PATCH 2/2] Add introductory text about own/borrow handles in
 resource section

---
 design/mvp/WIT.md | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md
index 1ceba008..05fc955c 100644
--- a/design/mvp/WIT.md
+++ b/design/mvp/WIT.md
@@ -1017,8 +1017,8 @@ transform: func(blob) -> blob
 ```
 
 As syntactic sugar, resource statements can also declare any number of
-*methods*, which are functions that implicitly takes a `self` borrowed handle
-parameter. A resource statement can also contain any number of *static
+*methods*, which are functions that implicitly take a `self` parameter that is
+a handle. A resource statement can also contain any number of *static
 functions*, which do not have an implicit `self` parameter but are meant to be
 lexically nested in the scope of the resource type. Lastly, a resource
 statement can contain at most one *constructor* function, which is syntactic
@@ -1046,6 +1046,14 @@ bindings generators can generate idiomatic syntax for the target language or
 (for languages like C) fall back to an appropriately-prefixed free function
 name.
 
+When a resource type name is used directly (e.g. when `blob` is used as the
+return value of the constructor above), it stands for an "owning" handle
+that will call the resource's destructor when dropped. When a resource
+type name is wrapped with `borrow<...>`, it stands for a "borrowed" handle
+that will *not* call the destructor when dropped. As shown above, methods
+always desugar to a borrowed self parameter whereas constructors always
+desugar to an owned return value.
+
 Specifically, the syntax for a `resource` definition is:
 ```ebnf
 resource-item ::= 'resource' id resource-methods?
@@ -1055,6 +1063,8 @@ resource-method ::= func-item
                   | 'constructor' param-list
 ```
 
+The syntax for handle types is presented [below](#handles).
+
 ## Types
 
 As mentioned previously the intention of `wit` is to allow defining types