lineCode
diff --git a/‎docs/guides/LiveCode Builder Language Reference.md‎
Lines changed: 26 additions & 1 deletion b/‎docs/guides/LiveCode Builder Language Reference.md‎
Lines changed: 26 additions & 1 deletion
diff --git a/‎docs/lcb/notes/feature-unsafe_attribs.md‎
Lines changed: 27 additions & 0 deletions b/‎docs/lcb/notes/feature-unsafe_attribs.md‎
Lines changed: 27 additions & 0 deletions
@@ -334,7 +334,7 @@ a value.
 ### Handlers
 
     HandlerDefinition
-      : 'handler' <Name: Identifier> '(' [ ParameterList ] ')' [ 'returns' <ReturnType: Type> ] SEPARATOR
+      : [ 'unsafe' ] 'handler' <Name: Identifier> '(' [ ParameterList ] ')' [ 'returns' <ReturnType: Type> ] SEPARATOR
           { Statement }
         'end' 'handler'
 
@@ -383,6 +383,10 @@ to be *optional any* meaning it can be of any type.
 > inout or out parameters. It is a checked compile-time error to pass a
 > non-assignable expression to such a parameter.
 
+If 'unsafe' is specified for the handler, then the handler itself is considered
+to be unsafe, and may only be called from other unsafe handlers or unsafe
+statement blocks.
+
 ### Foreign Handlers
 
     ForeignHandlerDefinition
@@ -476,6 +480,10 @@ non-Windows platform then it is taken to be 'default'.
 Foreign handler's bound symbols are resolved on first use and an error
 is thrown if the symbol cannot be found.
 
+Foreign handlers are always considered unsafe, and thus may only be called
+from unsafe context - i.e. from within an unsafe handler, or unsafe statement
+block.
+
 > **Note:** The current foreign handler definition is an initial
 > version, mainly existing to allow binding to implementation of the
 > syntax present in the standard language modules. It will be expanded
@@ -529,6 +537,7 @@ environment.
       | GetStatement
       | CallStatement
       | BytecodeStatement
+      | UnsafeStatement
 
 There are a number of built-in statements which define control flow,
 variables, and basic variable transfer. The remaining syntax for
@@ -760,9 +769,25 @@ Register definitions define a named register which is local to the current
 bytecode block. Registers are the same as handler-local variables except
 that they do not undergo default initialization.
 
+Bytecode statements are considered to be unsafe and can only appear inside
+unsafe handlers or unsafe statement blocks.
+
 > **Note:** Bytecode blocks are not intended for general use and the actual
 > available operations are subject to change.
 
+### Unsafe Statements
+
+    UnsafeStatement
+      : 'unsafe' SEPARATOR
+            { Statement }
+        'end' 'unsafe'
+
+The unsafe statement allows a block of unsafe code to be written in a safe
+context.
+
+In particular, calls to unsafe handlers (including all foreign handlers) and
+bytecode blocks are allowed in unsafe statement blocks but nowhere else.
+
 ## Expressions
 
     Expression
 
@@ -0,0 +1,27 @@
+# LiveCode Builder Language
+## Unsafe Attributes
+
+* The compiler now understands the idea of 'safety' of handlers and blocks of
+  code.
+
+* Handlers can be marked as being 'unsafe', e.g.
+
+      unsafe handler Foo()
+          ... do unsafe things ...
+      end handler
+
+* Blocks of statements can be marked as being 'unsafe', e.g.
+
+      unsafe
+          ... do unsafe things ...
+      end unsafe
+
+* All foreign handlers are considered to be 'unsafe'.
+
+* All bytecode blocks are considered to be 'unsafe'.
+
+* Calls to foreign handlers and unsafe handlers can only be made within unsafe
+  handlers or unsafe statement blocks.
+
+* Usage of bytecode blocks can only be made within unsafe handlers or unsafe
+  statement blocks.