@plurnk/plurnk-grammar 0.28.0 → 0.31.0

package/README.md

@@ -19,7 +19,7 @@ const result = PlurnkParser.parse(input);
 // result.unparsedTail?: { from, reason }
 ```
 
-Discriminate on `item.kind`. For `statement` items, narrow on `statement.op` (one of `FIND READ EDIT COPY MOVE OPEN FOLD SEND EXEC KILL`) to access per-OP typed fields. Full API: [SPEC.md §12](SPEC.md#12-public-api).
+Discriminate on `item.kind`. For `statement` items, narrow on `statement.op` (one of `FIND READ EDIT COPY MOVE OPEN FOLD SEND EXEC KILL PLAN`) to access per-OP typed fields. Full API: [SPEC.md §12](SPEC.md#12-public-api).
 
 ## cli
 
@@ -38,7 +38,7 @@ Exit `0` on clean parse, `1` on any error or unparsed tail.
 
 | slot     | shape                                              |
 |----------|----------------------------------------------------|
-| `OP`     | `FIND READ EDIT COPY MOVE OPEN FOLD SEND EXEC KILL` |
+| `OP`     | `FIND READ EDIT COPY MOVE OPEN FOLD SEND EXEC KILL PLAN` |
 | `suffix` | `[A-Za-z0-9_]*` glued to `OP`; used for nesting    |
 | `[…]`    | optional CSV; per-OP semantics                     |
 | `(…)`    | optional URI                                       |
@@ -57,6 +57,7 @@ Exit `0` on clean parse, `1` on any error or unparsed tail.
 | SEND | HTTP status int  | payload (JSON conv.)  | n/a                |
 | EXEC | executor         | command or code       | n/a                |
 | KILL | unix signal int  | annotation (opaque)   | n/a                |
+| PLAN | tags             | reasoning text        | n/a                |
 
 Matcher body dialect by leading char: `//` xpath · `/…/flags` regex · `$` jsonpath · `~` semantic · `@` graph · else glob. A body that fails its prefix-indicated dialect falls back to glob.
 
@@ -158,7 +159,7 @@ Nesting: outer body may contain inner `<<OP:…:OP` statements; outer must use a
 	<<SEND[200]:{"answer":"Paris","confidence":0.95}:SEND
 
 28. Report a client error (JSON body the model can traverse with jsonpath)
-	<<SEND[400]:{"reason":"unrecognized OP","got":"FOOBAR","expected":["FIND","READ","EDIT","COPY","MOVE","OPEN","FOLD","SEND","EXEC","KILL"]}:SEND
+	<<SEND[400]:{"reason":"unrecognized OP","got":"FOOBAR","expected":["FIND","READ","EDIT","COPY","MOVE","OPEN","FOLD","SEND","EXEC","KILL","PLAN"]}:SEND
 
 29. Report a server error with explicit recipient
 	<<SEND[503](log://errors):{"reason":"git unavailable","command":"git status"}:SEND
@@ -172,7 +173,10 @@ Nesting: outer body may contain inner `<<OP:…:OP` statements; outer must use a
 32. Permanently delete an entry
 	<<KILL(known://obsolete/note)::KILL
 
-33. Quote a plurnk operation inside another (nesting via suffix discipline)
+33. Think aloud — reasoning recorded to the log
+	<<PLAN:Need the capital fact; discover via wiki, record to known, deliver.:PLAN
+
+34. Quote a plurnk operation inside another (nesting via suffix discipline)
 	<<EDITouter(known://demo):
 	The following is a quoted plurnk operation, preserved verbatim:
 	<<EDIT(known://inner):hello world:EDIT
@@ -184,7 +188,13 @@ Errors are JSON-serializable. Shape: `{ line, column, source, message }` where `
 
 ## gbnf
 
-`dist/plurnk.gbnf` ships in the package — a generated [GBNF](https://github.com/ggml-org/llama.cpp/blob/master/grammars/README.md) grammar for llama.cpp constrained sampling. It dictates the canonical form (digit suffixes, comma line markers, three-digit SEND signals); the parser remains the permissive contract — everything the GBNF can generate, the parser accepts. The root encodes the turn shape: a batch of ops (mid-batch SENDs allowed) closed by a final pathless `SEND[102]`/`SEND[200]` status update, after which nothing is admissible — termination is structural (forced EOS), not an optional stop a near-greedy decoder can skip.
+Three generated [GBNF](https://github.com/ggml-org/llama.cpp/blob/master/grammars/README.md) grammars ship in the package for llama.cpp constrained sampling, most→least permissive. All dictate the canonical statement form (digit suffixes, comma line markers, three-digit SEND signals); free text can never contain a complete `<<OP` opener — emitting one commits the sampler into statement mode, so operations stay fully enforced everywhere.
+
+- **`plurnk.gbnf` (default, open)** — free reasoning text and statements interleave; EOS is admissible at any boundary, so termination is the model's own choice. The grammar filter sits below the reasoning/content split on llama.cpp; the open root lets reasoning-tuned models think — including reasoning *about* concluding without being forced to conclude.
+- **`plurnk-closed.gbnf`** — text allowed, but the turn must close with a final pathless `SEND[102]`/`SEND[200]` status update, after which nothing is admissible (forced EOS). For models that ramble past optional stopping points.
+- **`plurnk-strict.gbnf`** — ops only, bounded newline separators. The tightest rail, for models that don't reason.
+
+The parser remains the permissive contract — everything any of the three can generate, the parser accepts (interstatement text surfaces as `kind: "text"` items).
 
 ```ts
 import.meta.resolve("@plurnk/plurnk-grammar/plurnk.gbnf")