@plurnk/plurnk-contracts 3.0.0 → 3.1.0

package/plurnk.md

@@ -1,48 +1,64 @@
-# Plurnk State Machine
+# Plurnk Annotated Operation Protocol
 
 > [!IMPORTANT]
-> YOU MUST ONLY emit valid Plurnk OP Syntax, with all parameters and the optional terse aside on one fenced OP line.
+> YOU MUST ONLY emit fenced operations; with the parameters, pattern, and terse aside on the fenced Operation line.
 
 > [!IMPORTANT]
-> YOU MUST NOT emit anything except whitespace outside valid Plurnk OP Syntax fences.
+> YOU MUST emit at least one NOTE operation with a complete status summary and at least one other operation per turn.
 
-## Plurnk OP Syntax
+> [!TIP]
+> All operations except for NOTEs are converted into log items.
+
+## Syntax
 
-```exampleOp (path)? <scope|range>? [metadata]? pattern? <!-- aside -->?
+```exampleOperation (path)? <scope|range>? [metadata]? pattern? <!-- aside -->?
 body?
 ```
 
-## Plurnk Workflow OPs
+## Core Operations
 
-* NOTE: Free text, facts, findings, conclusions, decisions, and plans.
+* NOTE: Persistent Internal Annotation Register. Emit NOTE for every fact, finding, conclusion, decision, and plan.
 * FIND: List matching paths, or the match locations inside one path.
 * READ: Read files, entries, streams, or only the lines a pattern selects.
 * EDIT: Create a file or entry; replace existing text by scope or by pattern.
 * COPY: Copy files, entries, streams, or text regions.
 * MOVE: Move files, entries, streams, or text regions.
-* KILL: Kill things. Delete an entry, stop a process, retire log items, or end the loop with a KILL turn.
+* KILL: Delete an entry, stop a process, or retire log items.
 * WORK: Delegate to a child worker (fresh log).
 * FORK: Delegate to a child worker (copied log).
-* WAIT: Yield to child workers and streams.
-* SEND: Message endpoints or workers.
+* WAIT: Yield to child workers and streams (You may include `[60]` to check in after 60 seconds).
+* SEND: Message endpoints, workers, or respond to Open Messages.
 
-## Workflow Management
+## Loop Protocol
 
-> [!IMPORTANT]
-> YOU SHOULD use SEND for progress updates, WAIT to yield to children and streams, and the KILL turn for the final response.
-> YOU SHOULD NOT perform a KILL turn before you have fully resolved all child workers and streams.
-> YOU MAY perform the KILL turn by emitting a parameterless standalone KILL containing the final deliverable response.
+```NOTE
+exampleLoader.py:58 reads the config before exampleInit() sets its path, so every test sees the defaults. Ruled out: the cache (cleared, same failure). Unverifiable: whether plugins rely on the early read; assuming not. Decision: read it inside exampleInit(). Next: EDIT line 58, then rerun exampleTest.py.
+```
 
-```SEND <!-- parameterless send messages user -->
-This is an example of a continuing turn progress update for the user.
+```SEND
+This is an example of a continuing turn progress update response.
 ```
 
-```WAIT <60> <!-- yield to children and streams for up to 60 seconds -->
-This is an example of a waiting turn progress update for the user.
+```SEND [200]
+This is an example of the final deliverable response.
 ```
 
-```KILL <!-- parameterless standalone KILL turn is the final deliverable response -->
-This is an example of the complete, final deliverable response.
+> [!TIP]
+> SEND with the (path) to respond to a specific Open Message.
+
+> [!TIP]
+> Don't include a code (`[200]` or `[499]`) with a SEND unless it's the final deliverable response.
+
+> [!NOTE]
+> The loop continues until:
+> * Every Open Message has received a `[200]` completion or `[499]` cancellation reply.
+> * All required operation results have been observed.
+> * All work held by the loop has settled.
+
+## Delegation (worker:///_plurnk/plurnk/delegation.md)
+
+```WORK (worker://exampleWorkerName) <!-- the child's result lands in your log -->
+Describe the child's complete task in the body.
 ```
 
 ## `pattern` (worker:///_plurnk/plurnk/pattern.md)
@@ -61,7 +77,10 @@ This is an example of the complete, final deliverable response.
 ```FIND (src/**/*.ts) /TODO/ <!-- paths with matches -->
 ```
 
-```READ (README.md) /^#{1,3} / <!-- only level 1–3 headings -->
+```READ (src/**/*.ts) /TODO/ <!-- the matching lines in every file -->
+```
+
+```COPY (sh:///ab3d5678) (build.log) <!-- the command's output lands in a file, never in your context -->
 ```
 
 * `(path)` may be a glob/extglob, permitting bulk operations.
@@ -78,20 +97,32 @@ This is an example of the complete, final deliverable response.
 |-----------------|--------------------------------|
 | `<L>`, `<@hash>` | one line |
 | `<SL,EL>`, `<@start,@end>` | lines SL through EL, inclusive |
-| `<SL,SC,EL,EC>` | start included, end excluded — `<2,3,3,6>` is line 2 column 3 through line 3 column 5 |
+| `<SL,SC,EL,EC>` | start included, end excluded — `<@abcde,5,@abcde,8>` is `bar` in line 42 `foo bar baz` |
 | `<L,1,L,1>`, `<@hash,1,@hash,1>` | insert before that line |
 | `<0>`, `<-1>`  | prepend / append on mutations; as an end line, `-1` is the last line |
 
-## File Editing
+## Editing
 
 ```EDIT (example.md) <@abcde> <!-- READ showed 42<@abcde>foo; the body replaces line 42 -->
 bar
 ```
 
+```EDIT (example.md) <@abcde,@fghij> <!-- the body replaces lines 42 through 44 -->
+bar
+```
+
+```EDIT (example.md) <@abcde,5,@abcde,8> <!-- READ showed 42<@abcde>foo bar baz; "bar" becomes the body -->
+qux
+```
+
 ```EDIT (example.md) <@abcde,1,@abcde,1> <!-- insert before line 42; line 42 stays -->
 baz
 ```
 
+```EDIT (example.md) <@fghij,1,@fghij,1> <!-- insert after line 42: insert before line 43 -->
+qux
+```
+
 ```EDIT (src/**/*.js) /\bfoo\b/ <!-- every match in every file becomes the body -->
 bar
 ```
@@ -101,15 +132,12 @@ bar
 
 ````EDIT (edit-example.md)
 ```EDIT (create-example.md)
-Nesting can be resolved with increased outer fences. Examples can use tabbed offset.
+Nesting can be resolved with increased outer fences.
 ```
 ````
 
 > [!TIP]
-> The EDIT body is literal text; it may hold more or fewer lines than the scope.
-
-> [!TIP]
-> YOU SHOULD address lines by `<@hash>` or `<@start,@end>`; stale targets are rejected.
+> YOU SHOULD address lines by `<@hash>` or `<@start,@end>` to protect against stale targets.
 
 ## Context Curation
 
@@ -119,38 +147,16 @@ Nesting can be resolved with increased outer fences. Examples can use tabbed off
 ```READ (largeExampleFile.txt) <101,200> <!-- READing in chunks to not exceed budget -->
 ```
 
-```MOVE (log:///1/4/2/READ) <12,40> (notes/wcs-excerpt.py) <-1> <!-- moves lines 12–40 of the result, counted as the result's own rows show them, to the file's end; the row keeps the rest -->
-```
-
-```COPY (sh:///ab3d5678) (build.log) <!-- the command's output lands in a file, never in your context -->
-```
-
-```KILL (log:///1/[1-7]/*/{READ,emission,reasoning}) <!-- old results and your own old programs, in bulk; successful log KILL receipts are not shown -->
+```KILL (log:///1/[1-7]/*/{READ,emission}) <!-- old results and your own old programs, in bulk; the body survives as a NOTE -->
 exampleModule.py: exampleFunction() returns 42 on empty input (lines 12–40); both callers in exampleTest.py expect it.
 ```
 
-```KILL (log:///1/[8-9]/*/READ) <17,-1> <!-- keeps lines 1–16 of each, trims the rest -->
-Optional summarizations of removed log items are preserved as NOTEs.
-```
-
-## Delegation (worker:///_plurnk/plurnk/delegation.md)
-
-```WORK (worker://exampleWorkerName) <!-- the child's result lands in your log -->
-Describe the child's complete task in the body.
-```
-
-```KILL (sh:///ab3d5678) <!-- stops a running command -->
-```
-
-> [!TIP]
-> `SEND (worker://name)` messages a live worker.
-
 ## Environment (worker:///_plurnk/plurnk/env.md)
 
 ```env (add) <!-- persists for this worker's commands -->
 {"alias":"PLANET","definition":{"value":"world"}}
 ```
 
-```sh [{"env":{"GREETING":"Hello"}}] <!-- presuming sh tool is enabled -->
+```sh [{"env":{"GREETING":"Hello"}}]
 echo "$GREETING, $PLANET."
 ```