@plurnk/plurnk-contracts 3.3.0 → 4.1.0

package/plurnk.md

@@ -1,13 +1,7 @@
 # Plurnk Operation Protocol
 
 > [!IMPORTANT]
-> YOU MUST ONLY emit fenced operations; with the parameters, pattern, and terse aside on the fenced Operation line.
-
-> [!IMPORTANT]
-> YOU MUST record at least one NOTE along with other operations.
-
-> [!TIP]
-> All operations (except NOTE) are converted into log items.
+> YOU MUST ONLY emit fenced operation batches; with the parameters, pattern, and terse aside on the fenced operation line. No tool calls.
 
 ## Syntax
 
@@ -15,9 +9,12 @@
 body?
 ```
 
+> [!TIP]
+> You may use more than three backticks in your opening and closing outer fences to wrap, nest, and disambiguate.
+
 ## Core Operations
 
-* NOTE: Persistent Detailed Internal Register. Emit NOTE for every summary, finding, decision, and plan (and why).
+* NOTE: Save all new plans, findings, and decisions for later turns.
 * 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.
@@ -26,40 +23,43 @@ body?
 * 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. You may include `[60]` to check in after 60 seconds. Not for awaiting user input.
+* WAIT: Yield to child workers or streams. You may include `[60]` to check in after 60 seconds. Not for awaiting user input.
 * SEND: Message endpoints, workers, or Open Messages (when the path is omitted, the oldest Open Message).
 
 ## Loop Protocol
 
-```NOTE <!-- summary -->
-Configuration exampleLoader.py load-order bug identified; fix and regression test pending.
+> [!IMPORTANT]
+> YOU MUST Recall, Record, and React:
+> * **Recall**: Review the Open Work and Open Messages against the prior NOTE entries and log items.
+> * **Record**: NOTE entries are your ONLY chain of thought. Persist all new plans, findings, and decisions.
+> * **React**: When the necessary operations are identified, stop reflecting and emit the batch of notes and operations.
+
+```NOTE <!-- plan -->
+the steps ahead and why
 ```
 
 ```NOTE <!-- finding -->
-exampleLoader.py:58 reads the config before exampleInit() sets its path, so every test sees the defaults.
+a finding and its evidence
 ```
 
 ```NOTE <!-- decision -->
-Move configuration reading in exampleLoader.py into exampleInit() so it uses the initialized path. Plugin dependence on the old order is still unverified.
-```
-
-```NOTE <!-- plan -->
-Edit exampleLoader.py, then rerun exampleTest.py.
+a decision and its reasons
 ```
 
-```SEND
-This is an example of a continuing progress update response.
+```NOTE <!-- next -->
+the next action and what it needs
 ```
 
-```SEND [200]
-This is an example of a final deliverable response.
-```
+````SEND
+a continuing progress update response
+````
 
-> [!TIP]
-> YOU SHOULD include the Open Message's (path) to complete `[200]` or cancel `[499]` specific Open Messages.
+````SEND [200]
+a final deliverable response
+````
 
 > [!CAUTION]
-> The loop continues until every Open Message has a `[200]` or `[499]` reply, operation results have been observed, and work held by the loop has settled.
+> The loop continues until all Open Messages receive a `[200]` or `[499]` response and all Open Work is completed.
 
 ## Delegation (worker:///_plurnk/plurnk/delegation.md)
 
@@ -78,38 +78,40 @@ Describe the child's complete task in the body.
 | `&`    | graph (treesitter symbols)  | `&sym`, `&<sym`, `&>sym`        |
 | none   | literal or glob/extglob     | `?(export )?(async )function *` |
 
+## `<scope|range>`
+
+> [!TIP]
+> Text scopes use 1-based lines and Unicode code-point columns across textual mimetypes:
+
+| form            | endpoint rule                  |
+|-----------------|--------------------------------|
+| `<L>`, `<@hash>` | one line |
+| `<SL,EL>`, `<@start,@end>` | lines SL through EL, inclusive |
+| `<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 |
+
 ## Workspace Navigation
 
-```FIND (src/**/*.ts) /TODO/ <!-- paths with matches -->
+```FIND (src/**/*.ts) <1,-1> /TODO/ <!-- paths with matches -->
 ```
 
-```READ (src/**/*.ts) /TODO/ <!-- the matching lines in every file -->
+```READ (src/**/*.ts) <1,-1> /TODO/ <!-- the matching lines in every file -->
 ```
 
 ```COPY (sh:///ab3d5678) (build.log) <!-- the command's output lands in a file, never in your context -->
 ```
 
-```members (add) <!-- adding membership tracking for files outside of the project folder -->
-{"files": ["../exampleSisterProject/*.md", "../exampleSisterProject/example.json"]}
-```
-
 * `(path)` may be a glob/extglob, permitting bulk operations.
 * Log item paths nest: `log:///1/2/3/READ` is loop/turn/item/OP.
 * FIND results hold one inner array per path: its channels, default first; append `#channel` to the path to select another: `(sh:///ab3d5678#stderr)`.
 * Percent-encode in paths `(` as `%28` and `)` as `%29`.
 
-## `<scope|range>`
-
-> [!TIP]
-> Text scopes use 1-based lines and Unicode code-point columns across textual mimetypes:
+## Membership (worker:///_plurnk/plurnk/members.md)
 
-| form            | endpoint rule                  |
-|-----------------|--------------------------------|
-| `<L>`, `<@hash>` | one line |
-| `<SL,EL>`, `<@start,@end>` | lines SL through EL, inclusive |
-| `<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 |
+```members (add) <!-- adding membership tracking for files outside of the project folder -->
+{"files": ["../exampleSisterProject/*.md", "../exampleSisterProject/example.json"]}
+```
 
 ## Editing
 
@@ -140,22 +142,16 @@ bar
 ```EDIT (books.xml) //book[price > 35.00] <!-- an empty body removes each match -->
 ```
 
-````EDIT (edit-example.md)
-```EDIT (create-example.md)
-Nesting can be resolved with increased outer fences.
-```
-````
-
 > [!TIP]
 > YOU SHOULD address lines by `<@hash>` or `<@start,@end>` to protect against stale targets.
 
 ## Context Curation
 
-```READ (largeExampleFile.txt) <101,200> <!-- READing in chunks to not exceed budget -->
+```READ (largeExampleFile.txt) <101,200> <!-- READing in chunks if budget constrained -->
 ```
 
 ```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.
+example distillation or summarization
 ```
 
 ## Environment (worker:///_plurnk/plurnk/env.md)

package/dist/schema/ClientStatement.json

@@ -1,104 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.xyz/v0/ClientStatement.json",
-    "title": "ClientStatement",
-    "description": "The client-tier AST returned by PlurnkParser.parseClient: the closed protocol PlurnkStatement union plus the read-shaped LOOK utility statement.",
-    "oneOf": [
-        {
-            "$ref": "https://schemas.plurnk.xyz/v0/PlurnkStatement.json"
-        },
-        {
-            "$ref": "#/$defs/LookStatement"
-        }
-    ],
-    "$defs": {
-        "AsideOrNull": {
-            "type": [
-                "string",
-                "null"
-            ]
-        },
-        "SchemeMetadataOrNull": {
-            "oneOf": [
-                {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                {
-                    "type": "null"
-                }
-            ]
-        },
-        "PathOrNull": {
-            "oneOf": [
-                {
-                    "$ref": "https://schemas.plurnk.xyz/v0/ParsedPath.json"
-                },
-                {
-                    "type": "null"
-                }
-            ]
-        },
-        "TextLineMarkerOrNull": {
-            "oneOf": [
-                {
-                    "$ref": "https://schemas.plurnk.xyz/v0/TextLineMarker.json"
-                },
-                {
-                    "type": "null"
-                }
-            ]
-        },
-        "MatcherBodyOrNull": {
-            "oneOf": [
-                {
-                    "$ref": "https://schemas.plurnk.xyz/v0/MatcherBody.json"
-                },
-                {
-                    "type": "null"
-                }
-            ]
-        },
-        "PositionRef": {
-            "$ref": "https://schemas.plurnk.xyz/v0/Position.json"
-        },
-        "LookStatement": {
-            "type": "object",
-            "required": [
-                "op",
-                "aside",
-                "metadata",
-                "target",
-                "lineMarker",
-                "body",
-                "position"
-            ],
-            "additionalProperties": false,
-            "properties": {
-                "op": {
-                    "const": "LOOK"
-                },
-                "aside": {
-                    "$ref": "#/$defs/AsideOrNull"
-                },
-                "metadata": {
-                    "$ref": "#/$defs/SchemeMetadataOrNull"
-                },
-                "target": {
-                    "$ref": "#/$defs/PathOrNull"
-                },
-                "lineMarker": {
-                    "$ref": "#/$defs/TextLineMarkerOrNull"
-                },
-                "body": {
-                    "$ref": "#/$defs/MatcherBodyOrNull"
-                },
-                "position": {
-                    "$ref": "#/$defs/PositionRef"
-                }
-            }
-        }
-    }
-}