From a3c3700b26163939772a92e996d8e0b4b4e8a7f5 Mon Sep 17 00:00:00 2001
From: Tony Garnock-Jones <tonyg@leastfixedpoint.com>
Date: Tue, 6 Feb 2024 00:11:04 +0100
Subject: [PATCH] Switch embedded preserves syntax from `#!` to `#:`

---
 src/glossary.md                              |  4 ++--
 src/guide/preserves.md                       | 18 +++++++++---------
 src/guide/tracing.md                         |  8 ++++----
 src/operation/builtin/gatekeeper.md          |  8 ++++----
 src/operation/builtin/relay-listener.md      |  4 ++--
 src/operation/scripting.md                   |  2 +-
 src/protocol.md                              | 14 +++++++-------
 src/protocols/syndicate/dataspace.md         |  2 +-
 src/protocols/syndicate/dataspacePatterns.md |  2 +-
 src/protocols/syndicate/gatekeeper.md        |  8 ++++----
 src/protocols/synit/modem.md                 | 12 ++++++------
 src/protocols/synit/telephony.md             |  4 ++--
 src/protocols/synit/ui.md                    |  4 ++--
 src/protocols/synit/userSettings.md          |  2 +-
 14 files changed, 46 insertions(+), 46 deletions(-)

diff --git a/src/glossary.md b/src/glossary.md
index 4f7cef7..8342097 100644
--- a/src/glossary.md
+++ b/src/glossary.md
@@ -308,8 +308,8 @@ portions of a datum referring to SAM entities.
 
 Concretely, in [Preserves text
 syntax](https://preserves.dev/preserves-text.html), embedded values
-appear prepended with `#!`. In messages transferred across links using the [Syndicate network
-protocol][], references might appear as `#![0 123]`, `#![1 555]`, etc. etc.
+appear prepended with `#:`. In messages transferred across links using the [Syndicate network
+protocol][], references might appear as `#:[0 123]`, `#:[1 555]`, etc. etc.
 
 ## Entity
 [Target Entity]: #entity
diff --git a/src/guide/preserves.md b/src/guide/preserves.md
index aa6503f..b84190f 100644
--- a/src/guide/preserves.md
+++ b/src/guide/preserves.md
@@ -78,7 +78,7 @@ grammar):
     Sequence   : [value1 value2 ...]
     Set        : #{value1 value2 ...}
     Dictionary : {key1: value1 key2: value2 ...: ...}
-    Embedded   : #!value
+    Embedded   : #:value
 
 Commas are optional in sequences, sets, and dictionaries.
 
@@ -108,24 +108,24 @@ is
 
 ### Capabilities
 
-Preserves values can include *embedded references*, written as values with a `#!` prefix. For
+Preserves values can include *embedded references*, written as values with a `#:` prefix. For
 example, a command adding `<some-setting>` to the user settings database might look like this
 as it travels over a Unix pipe connecting a program to the root dataspace:
 
 ```preserves
-<user-settings-command <assert <some-setting>> #![0 123]>
+<user-settings-command <assert <some-setting>> #:[0 123]>
 ```
 
 The `user-settings-command` structure includes the `assert` command itself, plus an embedded
-capability reference, `#![0 123]`, which encodes a transport-specific reference to an object.
+capability reference, `#:[0 123]`, which encodes a transport-specific reference to an object.
 (See the [Syndicate Protocol](../protocol.md#capabilities-on-the-wire) for an concrete example
 of this.)
 
-The syntax of values under `#!` differs depending on the medium carrying the message.
-For example, point-to-point transports need to be able to refer to "my references" (`#![0 `*n*`]`) and "your
-references" (`#![1 `*n*`]`), while multicast/broadcast media (like Ethernet) need to be able to name
-references within specific, named conversational participants (`#![<udp [192 168 1 10] 5999>
-`*n*`]`), and in-memory representations need to use direct pointers (`#!140425190562944`).
+The syntax of values under `#:` differs depending on the medium carrying the message.
+For example, point-to-point transports need to be able to refer to "my references" (`#:[0 `*n*`]`) and "your
+references" (`#:[1 `*n*`]`), while multicast/broadcast media (like Ethernet) need to be able to name
+references within specific, named conversational participants (`#:[<udp [192 168 1 10] 5999>
+`*n*`]`), and in-memory representations need to use direct pointers (`#:140425190562944`).
 
 In every case, the references themselves work like Unix file descriptors: an integer or similar
 that unforgeably denotes, in a local context, some complex data structure on the other side of
diff --git a/src/guide/tracing.md b/src/guide/tracing.md
index 6abc50a..50d178b 100644
--- a/src/guide/tracing.md
+++ b/src/guide/tracing.md
@@ -27,10 +27,10 @@ The contents of the file will look a bit like this:
 <trace 1643236405.7960613 61 <start <named tcp_relay_listener>>>
 <trace 1643236405.7960687 71 <start <named unix_relay_listener>>>
 <trace 1643236405.7960766 81 <start <named logger>>>
-<trace 1643236405.7960895 1 <turn 9 <external "top-level actor"> [<facet-start [12 2]> <spawn #f 11> <spawn #f 21> <spawn #f 31> <spawn #f 41> <spawn #f 51> <spawn #f 61> <spawn #f 71> <enqueue <event <entity 1 12 140358591713488> <assert <value <run-service <config-watcher "config" {config: #!"1/12:00007fa7c80010d0" gatekeeper: #!"1/12:00007fa7c8005420" log: #!"1/12:00007fa7c80011b0"}>>> 3>>> <spawn #f 81>]>>
-<trace 1643236405.7961453 1 <turn 29 <caused-by 9> [<dequeue <event <entity 1 12 140358591713488> <assert <value <run-service <config-watcher "config" {config: #!"1/12:00007fa7c80010d0" gatekeeper: #!"1/12:00007fa7c8005420" log: #!"1/12:00007fa7c80011b0"}>>> 3>>>]>>
-<trace 1643236405.7962394 81 <turn 49 <caused-by 9> [<facet-start [122 92]> <enqueue <event <entity 1 12 140358591713712> <assert <value <Observe <rec log [<bind <_>> <bind <_>>]> #!"81/122:00007fa7c800ff10">> 13>>>]>>
-<trace 1643236405.796323 11 <turn 19 <caused-by 9> [<facet-start [102 22]> <enqueue <event <entity 1 12 140358591713488> <assert <value <Observe <rec require-service [<bind <_>>]> #!"11/102:00007fa75c0010b0">> 23>>>]>>
+<trace 1643236405.7960895 1 <turn 9 <external "top-level actor"> [<facet-start [12 2]> <spawn #f 11> <spawn #f 21> <spawn #f 31> <spawn #f 41> <spawn #f 51> <spawn #f 61> <spawn #f 71> <enqueue <event <entity 1 12 140358591713488> <assert <value <run-service <config-watcher "config" {config: #:"1/12:00007fa7c80010d0" gatekeeper: #:"1/12:00007fa7c8005420" log: #:"1/12:00007fa7c80011b0"}>>> 3>>> <spawn #f 81>]>>
+<trace 1643236405.7961453 1 <turn 29 <caused-by 9> [<dequeue <event <entity 1 12 140358591713488> <assert <value <run-service <config-watcher "config" {config: #:"1/12:00007fa7c80010d0" gatekeeper: #:"1/12:00007fa7c8005420" log: #:"1/12:00007fa7c80011b0"}>>> 3>>>]>>
+<trace 1643236405.7962394 81 <turn 49 <caused-by 9> [<facet-start [122 92]> <enqueue <event <entity 1 12 140358591713712> <assert <value <Observe <rec log [<bind <_>> <bind <_>>]> #:"81/122:00007fa7c800ff10">> 13>>>]>>
+<trace 1643236405.796323 11 <turn 19 <caused-by 9> [<facet-start [102 22]> <enqueue <event <entity 1 12 140358591713488> <assert <value <Observe <rec require-service [<bind <_>>]> #:"11/102:00007fa75c0010b0">> 23>>>]>>
 ...
 ```
 
diff --git a/src/operation/builtin/gatekeeper.md b/src/operation/builtin/gatekeeper.md
index db1d2a5..cfb3eac 100644
--- a/src/operation/builtin/gatekeeper.md
+++ b/src/operation/builtin/gatekeeper.md
@@ -11,8 +11,8 @@ the other end of [relay listener](./relay-listener.md) connections.
  - Relevant schema: [[syndicate-protocol]/schemas/gatekeeper.prs](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/gatekeeper.prs)
 
 ```preserves-schema
-Resolve = <resolve @step Step @observer #!Resolved> .
-Resolved = <accepted @responderSession #!any> / Rejected .
+Resolve = <resolve @step Step @observer #:Resolved> .
+Resolved = <accepted @responderSession #:any> / Rejected .
 Step = <<rec> @stepType symbol [@detail any]> .
 Rejected = <rejected @detail any> .
 ```
@@ -21,9 +21,9 @@ When a request to resolve a given credential, a `Step`, appears, the gatekeeper
 dataspace (by default, the server's top-level `$config` dataspace) for `bind` assertions:
 
 ```preserves-schema
-Bind = <bind @description Description @target #!any @observer BindObserver> .
+Bind = <bind @description Description @target #:any @observer BindObserver> .
 Description = <<rec> @stepType symbol [@detail any]> .
-BindObserver = @present #!Bound / @absent #f .
+BindObserver = @present #:Bound / @absent #f .
 Bound = <bound @pathStep PathStep> / Rejected .
 ```
 
diff --git a/src/operation/builtin/relay-listener.md b/src/operation/builtin/relay-listener.md
index b6586fc..c8a1648 100644
--- a/src/operation/builtin/relay-listener.md
+++ b/src/operation/builtin/relay-listener.md
@@ -18,7 +18,7 @@ and `port`, exposing the `gatekeeper` [entity reference](../../glossary.md#refer
 [initial ref](../../glossary.md#initial-ref) of incoming connections:
 
 ```preserves-schema
-TcpRelayListener = <relay-listener @addr Tcp @gatekeeper #!gatekeeper.Resolve> .
+TcpRelayListener = <relay-listener @addr Tcp @gatekeeper #:gatekeeper.Resolve> .
 Tcp = <tcp @host string @port int>.
 ```
 
@@ -46,7 +46,7 @@ Assertions [requiring](../service.md#require-service) a service with name matchi
 [initial ref](../../glossary.md#initial-ref) of incoming connections:
 
 ```preserves-schema
-UnixRelayListener = <relay-listener @addr Unix @gatekeeper #!gatekeeper.Resolve> .
+UnixRelayListener = <relay-listener @addr Unix @gatekeeper #:gatekeeper.Resolve> .
 Unix = <unix @path string>.
 ```
 
diff --git a/src/operation/scripting.md b/src/operation/scripting.md
index 3a5367f..ceb55d0 100644
--- a/src/operation/scripting.md
+++ b/src/operation/scripting.md
@@ -148,7 +148,7 @@ These instructions establish event handlers of one kind or another.
 *DuringInstruction* = `? `*PatternExpr*` `*Instruction*  
 *OnMessageInstruction* = `?? `*PatternExpr*` `*Instruction*
 
-These instructions publish assertions of the form `<Observe `*pat*` #!`*ref*`>` at the entity
+These instructions publish assertions of the form `<Observe `*pat*` #:`*ref*`>` at the entity
 denoted by the active target register, where *pat* is the [dataspace
 pattern](../glossary.md#dataspace-pattern) resulting from evaluation of *PatternExpr*, and
 *ref* is a fresh [entity](../glossary.md#entity) whose behaviour is to execute *Instruction* in
diff --git a/src/protocol.md b/src/protocol.md
index 58032a2..b4fe824 100644
--- a/src/protocol.md
+++ b/src/protocol.md
@@ -102,7 +102,7 @@ Event     = Assert / Retract / Message / Sync .
 Assert = <assert @assertion Assertion @handle Handle>.
 Retract = <retract @handle Handle>.
 Message = <message @body Assertion>.
-Sync = <sync @peer #!#t>.
+Sync = <sync @peer #:#t>.
 
 Assertion = any .
 Handle    = int .
@@ -146,11 +146,11 @@ References embedded in `Turn` packets denote *capabilities* for interacting with
 For example, assertion of a capability-bearing record could appear as the following `Event`:
 
 ```preserves
-<assert <please-reply-to #![0 555]>>
+<assert <please-reply-to #:[0 555]>>
 ```
 
-The `#![0 555]` is [concrete Preserves text syntax](./guide/preserves.md#concrete-syntax) for
-an embedded (`#!`) value (`[0 555]`).
+The `#:[0 555]` is [concrete Preserves text syntax](./guide/preserves.md#concrete-syntax) for
+an embedded (`#:`) value (`[0 555]`).
 
 In the Syndicate Protocol, these embedded values MUST conform to the `WireRef`
 schema:[^slightly-silly-wireref]
@@ -161,8 +161,8 @@ Oid = int .
 ```
 
 The `mine` variant denotes capability references managed by the *sender* of a given packet; the
-`yours` variant, the *receiver* of the packet. A relay receiving a packet mentioning `#![0
-555]` will use `#![1 555]` in later responses that refer to that same entity, and *vice versa*.
+`yours` variant, the *receiver* of the packet. A relay receiving a packet mentioning `#:[0
+555]` will use `#:[1 555]` in later responses that refer to that same entity, and *vice versa*.
 
 ### Attenuation of authority
 
@@ -768,7 +768,7 @@ TurnEvent = [@oid Oid @event Event].
 Assert = <assert @assertion Assertion @handle Handle>.
 Retract = <retract @handle Handle>.
 Message = <message @body Assertion>.
-Sync = <sync @peer #!#t>.
+Sync = <sync @peer #:#t>.
 ```
 
 ### Capabilities, WireRefs, and attenuations
diff --git a/src/protocols/syndicate/dataspace.md b/src/protocols/syndicate/dataspace.md
index dfd0c13..b2fe6e5 100644
--- a/src/protocols/syndicate/dataspace.md
+++ b/src/protocols/syndicate/dataspace.md
@@ -11,7 +11,7 @@ The sole exception is *assertions of interest in other assertions*.
 These are called "Observe" assertions, or *subscriptions*:
 
 ```preserves-schema
-Observe = <Observe @pattern dataspacePatterns.Pattern @observer #!any>.
+Observe = <Observe @pattern dataspacePatterns.Pattern @observer #:any>.
 ```
 
 An `Observe` assertion contains a [pattern](./dataspacePatterns.md) and a reference to an
diff --git a/src/protocols/syndicate/dataspacePatterns.md b/src/protocols/syndicate/dataspacePatterns.md
index 059ef65..8539a14 100644
--- a/src/protocols/syndicate/dataspacePatterns.md
+++ b/src/protocols/syndicate/dataspacePatterns.md
@@ -76,7 +76,7 @@ AnyAtom =
     / @string string
     / @bytes bytes
     / @symbol symbol
-    / @embedded #!any
+    / @embedded #:any
 .
 ```
 
diff --git a/src/protocols/syndicate/gatekeeper.md b/src/protocols/syndicate/gatekeeper.md
index 9e8ef56..c0cf77d 100644
--- a/src/protocols/syndicate/gatekeeper.md
+++ b/src/protocols/syndicate/gatekeeper.md
@@ -13,11 +13,11 @@ built-in gatekeeper entity](../../operation/builtin/gatekeeper.md).
 [`syndicate-server`](../../operation/system-bus.md) program.
 
 ```
-Resolve = <resolve @step Step @observer #!Resolved> .
-Bind = <bind @description Description @target #!any @observer BindObserver> .
-BindObserver = @present #!Bound / @absent #f .
+Resolve = <resolve @step Step @observer #:Resolved> .
+Bind = <bind @description Description @target #:any @observer BindObserver> .
+BindObserver = @present #:Bound / @absent #f .
 
-Resolved = <accepted @responderSession #!any> / Rejected .
+Resolved = <accepted @responderSession #:any> / Rejected .
 Bound = <bound @pathStep PathStep> / Rejected .
 Rejected = <rejected @detail any> .
 
diff --git a/src/protocols/synit/modem.md b/src/protocols/synit/modem.md
index df92802..18c136c 100644
--- a/src/protocols/synit/modem.md
+++ b/src/protocols/synit/modem.md
@@ -22,7 +22,7 @@ Hayes-style modems announce their presence with a subtype of the general `ModemP
 assertion schema.
 
 ```
-ModemPresent = <modem =hayes @devicePath string @dataspace #!InternalProtocol> .
+ModemPresent = <modem =hayes @devicePath string @dataspace #:InternalProtocol> .
 ```
 
 (TODO: specify the `InternalProtocol` properly)
@@ -47,7 +47,7 @@ along with any responses, will be send to the `replyTo` entity reference. Altern
 completion notification or response is desired, send a `CommandEvent` message.
 
 ```
-CommandRPC = <execute-command @commandText string @replyTo #!CommandResult> .
+CommandRPC = <execute-command @commandText string @replyTo #:CommandResult> .
 CommandEvent = <execute-command @commandText string> .
 ```
 
@@ -87,7 +87,7 @@ are implemented entirely in the SqueakPhone Smalltalk image, in class
 The modem announces its presence with a subtype of the general `ModemPresent` assertion schema.
 
 ```
-ModemPresent = <modem =samsung-galaxy-s7 @devicePath string @dataspace #!InternalProtocol> .
+ModemPresent = <modem =samsung-galaxy-s7 @devicePath string @dataspace #:InternalProtocol> .
 ```
 
 (TODO: specify the `InternalProtocol` properly)
@@ -102,8 +102,8 @@ InternalProtocol = any .
 ModemPacket = @in <from-modem @packet any> / @out <to-modem @packet any> .
 
 # The bodies are instances of SamsungFmtMessage and SamsungRfsMessage, respectively.
-FmtPacket = <fmt @body #!any> .
-RfsPacket = <rfs @body #!any> .
+FmtPacket = <fmt @body #:any> .
+RfsPacket = <rfs @body #:any> .
 ```
 
 ### Executing commands
@@ -112,7 +112,7 @@ Analogous to AT command execution for Hayes-style modems.
 
 ```
 # Assertion. Asks the modem to execute the given command.
-CommandRPC = <execute-command @command FmtPacket @replyTo #!FmtPacket> .
+CommandRPC = <execute-command @command FmtPacket @replyTo #:FmtPacket> .
 # Message. Asks the modem to execute the given command, but not to send back the reply.
 CommandEvent = <execute-command @command FmtPacket> .
 ```
diff --git a/src/protocols/synit/telephony.md b/src/protocols/synit/telephony.md
index 155b75f..7022522 100644
--- a/src/protocols/synit/telephony.md
+++ b/src/protocols/synit/telephony.md
@@ -19,7 +19,7 @@ the `devicePath` is a Linux device path representative of the modem, for example
 `/dev/umts_boot0` or `/dev/EG25.AT`.
 
 ```
-ModemPresent = <modem @type symbol @devicePath string @dataspace #!any> .
+ModemPresent = <modem @type symbol @devicePath string @dataspace #:any> .
 ```
 
 ## Telephony addresses (telephone numbers)
@@ -146,7 +146,7 @@ transmission has been processed by the modem.
 
 ```
 # Assertion. An outgoing SMS should be transmitted.
-SmsTransmission = <sms-transmission @smsc Address @peer Address @body string @continuation #!=ok > .
+SmsTransmission = <sms-transmission @smsc Address @peer Address @body string @continuation #:=ok > .
 ```
 
 ## <span id="Speakerphone"></span>Speakerphone mode
diff --git a/src/protocols/synit/ui.md b/src/protocols/synit/ui.md
index 02ff48b..6b32d4e 100644
--- a/src/protocols/synit/ui.md
+++ b/src/protocols/synit/ui.md
@@ -21,7 +21,7 @@ client's interest, and in response, creates a fresh dataspace for configuration
 relating to the new window, and asserts a `Window` record mapping the `id` to the new `space`.
 
 ```
-Window = <window @id WidgetId @space #!any> .
+Window = <window @id WidgetId @space #:any> .
 WidgetId = any .
 ```
 
@@ -126,7 +126,7 @@ by monitoring `WidgetInstance` assertions. (This is not a sustainable technique,
 replaced in future by an entity-reference-based system.)
 
 ```
-WidgetInstance = <widget-instance @id WidgetId @instance #!any> .
+WidgetInstance = <widget-instance @id WidgetId @instance #:any> .
 ```
 
 ## <span id="attribute-keys"></span>Widget attributes
diff --git a/src/protocols/synit/userSettings.md b/src/protocols/synit/userSettings.md
index 1691603..c3ebdff 100644
--- a/src/protocols/synit/userSettings.md
+++ b/src/protocols/synit/userSettings.md
@@ -16,7 +16,7 @@ assert a `CommandReply` using the `reply` capability. Alternatively, send a `Com
 message containing an `action` if you do not require notification of completion.
 
 ```
-CommandRPC = <user-settings-command @action Action @reply #!CommandReply> .
+CommandRPC = <user-settings-command @action Action @reply #:CommandReply> .
 CommandEvent = <user-settings-command @action Action> .
 CommandReply = =done .
 Action = <assert @item any> / <retract @item any> .