docs: document Rust-like #{ } record syntax (#218 step 5) (#223)

#222 (merged) made bare { = block in expression position; record/
struct construction uses the #{ } sigil. Bring the docs in line:

- spec.md: record grammar production '#{' …; field_init shorthand
  note; operational-semantics record-construction notation; +a new
  callout documenting the rule and the type/decl/pattern asymmetry
  (type positions, struct bodies, and record patterns keep plain {}).
- README.adoc, frontier-guide.adoc, migration-playbook.adoc,
  WHAT-MAKES-IT-BRILLIANT.md: updated all expression-position record
  examples to #{ }.
- idaptik-hitbox / idaptik-player-hp migration lessons: updated only
  the AffineScript 'after' record literals; ReScript 'before' blocks
  left intact.

Type annotations, struct/enum declarations, and record patterns left
as plain {} throughout (only value construction takes #{). Pre-existing
non-record parse issues in docs/guides/warmup/*.affine are unrelated
and out of scope.

Refs #218

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

README.adoc

@@ -192,7 +192,7 @@ This includes code such as:
 type Texture = own { id: Int, width: Int, height: Int }
 
 fn load_texture(path: ref String) -{IO + Exn[LoadError]}-> own Texture {
-  Texture { id: 42, width: 1024, height: 1024 }
+  Texture #{ id: 42, width: 1024, height: 1024 }
 }
 
 fn render(scene: ref Scene, texture: ref Texture) -{Render}-> () {
@@ -231,7 +231,7 @@ fn authenticate(
   @linear conn: own Connection[{status: Unauthenticated}]
 ) -{Session + IO}-> Connection[{status: Authenticated, user: String}] {
   let creds = recv();
-  Connection { socket: conn.socket, status: Authenticated, user: creds.user }
+  Connection #{ socket: conn.socket, status: Authenticated, user: creds.user }
 }
 
 fn query(
@@ -287,8 +287,8 @@ fn greet[..r](person: {name: String, ..r}) -> String {
   "Hello, " ++ person.name
 }
 
-let alice = {name: "Alice", age: 30, role: "Engineer"};
-let bob = {name: "Bob", department: "Sales"};
+let alice = #{name: "Alice", age: 30, role: "Engineer"};
+let bob = #{name: "Bob", department: "Sales"};
 
 greet(alice);
 greet(bob);

docs/guides/WHAT-MAKES-IT-BRILLIANT.md

@@ -183,9 +183,9 @@ fn updateAge[R](person: {age: Int, ...R}, newAge: Int) -> {age: Int, ...R} {
   {...person, age: newAge}  // Preserves all other fields!
 }
 
-let alice = {name: "Alice", age: 30, city: "NYC"};
+let alice = #{name: "Alice", age: 30, city: "NYC"};
 let older = updateAge(alice, 31);
-// older = {name: "Alice", age: 31, city: "NYC"} ✅
+// older = #{name: "Alice", age: 31, city: "NYC"} ✅
 ```
 
 **Brilliance:** **Flexibility of duck typing** + **safety of static types**.

docs/guides/frontier-guide.adoc

@@ -290,8 +290,8 @@ type Person = {name: String, age: Int}
 type Company = {name: String, employees: Int, revenue: Float}
 
 // Both work — the row variable absorbs the extra fields:
-greet(Person { name: "Alice", age: 30 })
-greet(Company { name: "Acme", employees: 100, revenue: 9999.0 })
+greet(Person #{ name: "Alice", age: 30 })
+greet(Company #{ name: "Acme", employees: 100, revenue: 9999.0 })
 ----
 
 Row polymorphism is also how effects compose:
@@ -465,14 +465,14 @@ type FetchError = { message: String }
 
 // Open a request (produces a linear resource):
 fn make_request(url: String, config: ref Config) -> own Request {
-  Request { url: url, config: config }
+  Request #{ url: url, config: config }
 }
 
 // Send the request (consumes it — can't send twice):
 fn send(req: own Request) -> Result[Response, FetchError] / IO {
   IO.println("Sending request to " ++ req.url);
   // Real implementation would use the Async effect
-  Ok(Response { body: "OK", status: 200 })
+  Ok(Response #{ body: "OK", status: 200 })
 }
 
 // The return type tells you: this can fail, and it does IO.

docs/guides/lessons/migrations/idaptik-hitbox.adoc

@@ -44,7 +44,7 @@ fn contains(r: Rect, p: Point) -> Bool {
 }
 
 fn from_center(c: Point, size: Size) -> Rect {
-  { x: c.x - size.w / 2, y: c.y - size.h / 2, w: size.w, h: size.h }
+  #{ x: c.x - size.w / 2, y: c.y - size.h / 2, w: size.w, h: size.h }
 }
 ----
 

docs/guides/lessons/migrations/idaptik-player-hp.adoc

@@ -178,14 +178,14 @@ fn update(p: mut Player, dt_ms: Int) -> Velocity {
   // Knockback decay + velocity emission
   if p.knockback.remaining_ms > 0 {
     p.knockback.remaining_ms = max(0, p.knockback.remaining_ms - dt_ms)
-    let v = Velocity { x: p.knockback.vel_x, y: p.knockback.vel_y }
+    let v = Velocity #{ x: p.knockback.vel_x, y: p.knockback.vel_y }
     if p.knockback.remaining_ms <= 0 {
       p.knockback.vel_x = 0
       p.knockback.vel_y = 0
     }
     v
   } else {
-    Velocity { x: 0, y: 0 }
+    Velocity #{ x: 0, y: 0 }
   }
 }
 ----

docs/guides/migration-playbook.adoc

@@ -252,7 +252,7 @@ type FileBuffer = own {
   open_: mut Bool,
 }
 
-fn make() -> own FileBuffer { FileBuffer { data: [], open_: true } }
+fn make() -> own FileBuffer { FileBuffer #{ data: [], open_: true } }
 
 fn read(b: ref FileBuffer) -> String {
   if b.open_ { String.join(b.data, "") } else { panic("closed") }
@@ -279,7 +279,7 @@ type ClosedBuffer = own { data: Array[String] }
 
 effect IO { fn log(s: String); }
 
-fn make() -> own OpenBuffer { OpenBuffer { data: [] } }
+fn make() -> own OpenBuffer { OpenBuffer #{ data: [] } }
 
 // read takes a borrow — caller keeps the buffer:
 fn read(b: ref OpenBuffer) -> String { String.join(b.data, "") }
@@ -291,7 +291,7 @@ fn write(b: mut OpenBuffer, s: String) -> () / IO {
 }
 
 // close consumes Open and returns Closed — "use after close" becomes a type error:
-fn close(b: own OpenBuffer) -> own ClosedBuffer { ClosedBuffer { data: b.data } }
+fn close(b: own OpenBuffer) -> own ClosedBuffer { ClosedBuffer #{ data: b.data } }
 ----
 
 What changed:

docs/spec.md

@@ -401,14 +401,26 @@ primary_expr  = literal
               | '(' expr ')'
               | '(' expr { ',' expr } ')'          (* tuple *)
               | '[' [ expr { ',' expr } ] ']'      (* array *)
-              | '{' [ field_init { ',' field_init } ] [ '..' expr ] '}'  (* record *)
+              | '#{' [ field_init { ',' field_init } ] [ '..' expr ] '}'  (* record *)
               | 'resume' '(' [ expr ] ')' ;        (* effect handler resume *)
 
-field_init    = ident [ ':' expr ] ;               (* shorthand: {x} means {x: x} *)
+field_init    = ident [ ':' expr ] ;               (* shorthand: #{x} means #{x: x} *)
 
 literal       = int_lit | float_lit | char_lit | string_lit | bool_lit | unit_lit ;
 ```
 
+> **Record-literal syntax (`#{ … }`).** In *expression* position a bare
+> `{ … }` is always a **block**; record/struct construction uses the
+> `#{ … }` sigil — both anonymous (`#{ x: 1, y: 2 }`) and typed
+> (`Point #{ x: 1, y: 2 }`). This removes the block-vs-record ambiguity
+> by construction (and the struct-literal-in-`if`/`match`-scrutinee
+> hazard). Note the asymmetry: **type** positions (`fn f(r: {x: Int, ..s})`,
+> `type Box[T] = own { ptr: RawPtr[T] }`), **`struct` declaration bodies**,
+> and **record patterns** (`match r { { x, .. } => … }`) keep the plain
+> `{ … }` — only value construction takes `#{`. Migrating older sources:
+> rewrite each expression-position record literal `{`→`#{`; leave
+> declarations, type annotations, and patterns unchanged.
+
 ## 2.11 Patterns
 
 ```ebnf
@@ -740,7 +752,7 @@ E ::= []
     | E e                        Function position
     | v E                        Argument position
     | let x = E in e             Let binding
-    | {ℓ₁: v₁, ..., ℓᵢ: E, ...}  Record construction
+    | #{ℓ₁: v₁, ..., ℓᵢ: E, ...}  Record construction
     | E.ℓ                        Field access
     | E[e]                       Array index (array position)
     | v[E]                       Array index (index position)
@@ -870,12 +882,12 @@ fn leakResource(file: own File) -> () / Pure {
 ```affinescript
 fn stackOnly() -> Int / Pure {
   let x = 42;           // Stack
-  let r = {a: 1, b: 2}; // Stack (doesn't escape)
+  let r = #{a: 1, b: 2}; // Stack (doesn't escape)
   r.a + x
 }
 
 fn needsHeap() -> own {x: Int} / Pure {
-  let r = {x: 42};  // Heap - returned (escapes)
+  let r = #{x: 42};  // Heap - returned (escapes)
   r
 }
 ```
@@ -886,7 +898,7 @@ fn needsHeap() -> own {x: Int} / Pure {
 type Box[T] = own { ptr: RawPtr[T] }
 
 fn box[T](value: own T) -> own Box[T] / Pure {
-  Box { ptr: heapAlloc(value) }
+  Box #{ ptr: heapAlloc(value) }
 }
 
 fn unbox[T](b: own Box[T]) -> own T / Pure {
@@ -1128,12 +1140,12 @@ fn getX[..r](record: {x: Int, ..r}) -> Int / Pure {
 
 // Add a field to any record
 fn withY[..r](record: {..r}, y: Int) -> {y: Int, ..r} / Pure {
-  {y: y, ..record}
+  #{y: y, ..record}
 }
 
 // Update a field
 fn mapX[..r](record: {x: Int, ..r}, f: Int -> Int / Pure) -> {x: Int, ..r} / Pure {
-  {x: f(record.x), ..record}
+  #{x: f(record.x), ..record}
 }
 
 // Remove a field
@@ -1305,7 +1317,7 @@ fn Buffer.write[cap: Nat](
   where (self.len + len(data) <= cap)
 {
   copy(data, mut self.data[self.len..]);
-  Ok(Buffer { data: self.data, len: self.len + len(data) })
+  Ok(Buffer #{ data: self.data, len: self.len + len(data) })
 }
 
 fn Buffer.free[cap: Nat](own self: Buffer[cap]) -> () / Pure {