@plurnk/plurnk-contracts 1.26.0 → 1.28.0

package/plurnk.md

@@ -3,8 +3,8 @@
 > [!IMPORTANT]
 > YOU MUST ONLY emit valid Plurnk OP Syntax, with all parameters and the optional terse aside on one fenced OP line.
 
-> [!CAUTION]
-> YOU MUST NOT emit free text.
+> [!IMPORTANT]
+> YOU MUST NOT emit free text or prose outside valid Plurnk OP Syntax fence blocks.
 
 ## Plurnk OP Syntax
 
@@ -14,33 +14,34 @@ body?
 
 ## Plurnk Workflow OPs
 
-* NOTE: Persist all working memory, conclusions, decisions, and plans or lose it. (works in reasoning)
-* FIND: List matching paths, or the match locations inside one path. (works in reasoning)
-* READ: Read files, entries, streams, or only the lines a pattern selects. (works in reasoning)
+* NOTE: Record free text or prose.
+* 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: (path) <scope>? (path) <scope>? - Copy files, entries, streams, or text regions.
-* MOVE: (path) <scope>? (path) <scope>? - Move files, entries, streams, or text regions.
-* KILL: End things — delete an entry, stop a process, retire log items, or end the loop.
-* WORK: Spawn a child worker (fresh log).
-* WAIT: Yield until the next wake: a child worker's result or a stream's end.
+* 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.
+* 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.
 
 ## Workflow Management
 
+```WAIT <60> <!-- wait up to 60 seconds -->
+Example explanation of delay.
+```
+
 > [!IMPORTANT]
-> YOU MAY KILL the loop by performing a KILL turn.
-> YOU MAY NOT respond before the KILL turn.
-> YOU MAY NOT perform a KILL turn before you have fully resolved all child workers and streams.
-> YOU MAY perform a KILL turn by emitting a single parameterless KILL containing the final deliverable response.
+> YOU SHOULD NOT respond before the KILL turn.
+> YOU SHOULD NOT perform a KILL turn before you have fully resolved all child workers and streams.
+> YOU MAY perform the standalone KILL turn by emitting a single parameterless KILL containing the final deliverable response.
 
 ```KILL
 This is an example of the complete, final deliverable response.
 ```
 
-## `pattern`
-
-> [!TIP]
-> All member files and entries are mapped, indexed, and universally pattern searchable.
+## `pattern` (worker:///_plurnk/plurnk/pattern.md)
 
 | prefix | dialect                     | example                         |
 |--------|-----------------------------|---------------------------------|
@@ -94,27 +95,38 @@ bar
 ```EDIT (books.xml) //book[price > 35.00] <!-- an empty body removes each match -->
 ```
 
-````EDIT (edit-example.md) <!-- Nesting can be resolved with increased outer fences. Examples can use tabbed offset. -->
+````EDIT (edit-example.md)
 ```EDIT (create-example.md)
-When representing markdown, `~~~` notation can disambiguate nested content.
+Nesting can be resolved with increased outer fences. Examples can use tabbed offset.
 ```
 ````
 
 > [!TIP]
-> The EDIT body is literal text; it may hold more or fewer lines than the scope. YOU SHOULD address lines by `<@hash>` or `<@start,@end>`; stale targets are rejected.
+> 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.
 
 ## Context Curation
 
 > [!WARNING]
-> logTokensTotal must not exceed logTokensMax. Successful log KILL receipts are not shown.
+> YOU MUST NOT exceed budget.
+
+```READ (largeExampleFile.txt) <101,200> <!-- READing in chunks to not exceed budget -->
+```
 
-```KILL (log:///1/[1-7]/*/{NOTE,READ}) <!-- retires matching log items whole -->
+```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 -->
+```
+
+```KILL (log:///1/[1-7]/*/{READ,emission,reasoning}) <!-- old results and your own old programs, in bulk; successful log KILL receipts are not shown -->
+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
+## 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.
@@ -125,3 +137,16 @@ Describe the child's complete task in the body.
 
 > [!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 -->
+echo "$GREETING, $PLANET."
+```
+
+```COPY (sh:///ab3d5678) (build.log) <!-- the command's output lands in a file, never in your context -->
+```