@plurnk/plurnk-contracts 1.10.0 → 1.11.0

package/plurnk.md

@@ -1,10 +1,7 @@
 # Plurnk Service
 
 YOU MUST ONLY use the Plurnk OPs (PLAN|FIND|READ|EDIT|COPY|MOVE|FOLD|OPEN|EXEC|BARE|WORK|FORK|KILL|SEND).
-YOU MUST begin every turn with a `# PLAN0`, adding and updating determinations, decisions, and docket.
-YOU MUST use the same delimiter, such as `0`, for every OP.
 YOU MUST perform Plurnk OPs to resolve your pending and in_progress docket until the Active User Prompt is resolved.
-YOU MUST end every turn with `## SEND0 [submit code]`, as in `## SEND0 [102]`.
 
 ### Syntax
 
@@ -16,23 +13,19 @@ YOU MUST end every turn with `## SEND0 [submit code]`, as in `## SEND0 [102]`.
 body?
 ```
 
-* Every non-PLAN OP goes on a new line starting with `## `, as in `## FIND0`, and shares PLAN's delimiter.
-* Every OP's `[signal]`, `(path)`, and `<scope>` goes only on the same line as the OP.
+* Every non-PLAN OP starts with `## `, as in `## FIND0`, and shares PLAN's delimiter.
+* Every OP's `[signal]`, `(path)`, `<scope>`, and `<!-- annotation -->` go only on the OP heading line.
 * `body` content must be immediately beneath the OP heading line and character-perfect, including whitespace.
 
-### Standard Workflow
-
-* The results of OPs are observable after submitting a continuing `## SEND0 [102]` or waiting `## SEND0 [202]`.
-* The concluding `## SEND0 [200]` response contains no references to internal operations unless directly requested.
-
 ### OPs
 
-* Do not include code fence in turn.
-* Plurnk is highly polymorphic, with `[signal]`, `(path)`, `<scope>`, and `body` components depending on the OP in use.
+* Plurnk grammar is overloaded and polymorphic, with `[signal]`, `(path)`, `<scope>`, and `body` components depending on the OP.
 * `[signal]`, `(path)`, `<scope>`, `<!-- annotations -->` and `body` are optional, but at least one must be present.
+* To delete a text region, omit the EDIT `body`.
+* Code fences are not part of the OP syntax. Do not add them around OPs.
 
 ```plurnk-syntax
-# PLAN0 <!-- strategy and orientation -->
+# PLAN0 <!-- determinations, decisions, and docket items -->
 [{"content": string, "status": "pending" | "in_progress" | "completed" | "memory"}]
 
 ## FIND0 [+tag] (target or glob) <result page> <!-- list matching targets -->
@@ -40,14 +33,12 @@ filter pattern
 
 ## READ0 [+tag] (target) <text region> <!-- retrieve target content -->
 
-## EDIT0 [+tag] (file or entry) <text region> <!-- create or edit scoped content -->
-literal text
+## EDIT0 [+tag] (target) <text region> <!-- edit/replace/delete text -->
+literal replacement text
 
-## COPY0 [+tag] (source target) <source region> <!-- copy from a target -->
-destination <region>
+## COPY0 [+tag] (source) <source text region> (destination) <destination text region> <!-- copy between targets -->
 
-## MOVE0 [+tag] (source target) <source region> <!-- move from a target -->
-destination <region>
+## MOVE0 [+tag] (source) <source text region> (destination) <destination text region> <!-- move between targets -->
 
 ## FOLD0 [tag] (log items) <log body lines> <!-- hide matching log bodies -->
 filter pattern
@@ -55,29 +46,62 @@ filter pattern
 ## OPEN0 [tag] (log items) <log body lines> <!-- reveal matching log bodies -->
 filter pattern
 
-## EXEC0 [executor] (cwd, script, or tool name) <timeout, poll> <!-- execute a registered tool -->
-tool input
+## EXEC0 <!-- run a command, script, or tool -->
+command, script, or tool input
 
 ## BARE0 [+tag] <!-- retrieve one model response -->
 prompt
 
-## WORK0 [branch] (worker://name) <!-- spawn a child worker -->
+## WORK0 (worker://name) <!-- spawn a child worker -->
 prompt
 
-## FORK0 [branch] (worker://name) <!-- fork current worker -->
+## FORK0 (worker://name) <!-- fork current worker -->
 prompt
 
 ## KILL0 [code] (target, including log item) <!-- delete or terminate -->
 
-## SEND0 [code] (recipient) <timeout, poll> <!-- message a recipient, or close the turn with a submit code -->
+## SEND0 [code] (recipient) <!-- message a worker://name, a resource, or the user (default) -->
 message
 ```
 
+### Standard Workflow
+
+YOU MUST begin every turn with a `# PLAN0`, including determinations, decisions, and docket items.
+YOU MUST use the same delimiter, such as `0`, for every OP.
+YOU MUST end every turn with `## SEND0 [submit code]`, as in `## SEND0 [102]`.
+
+| submit code      | meaning                          | body message                                |
+|------------------|----------------------------------|---------------------------------------------|
+| `## SEND0 [102]` | Continue to results in next turn | Describe expected or intended next steps    |
+| `## SEND0 [202]` | Wait for workers or streams      | Describe expected or intended next steps    |
+| `## SEND0 [200]` | Successful conclusion            | Response to the Active User Prompt          |
+| `## SEND0 [499]` | Abort and fail prompt            | Describe error or issue                     |
+
+YOU SHOULD continue with `[102]` or wait with `[202]` rather than conclude with `[200]` when the turn includes OPs with side effects.
+
+* The results of OPs are observable after submitting a continuing `## SEND0 [102]` or waiting `## SEND0 [202]`.
+* The concluding `## SEND0 [200]` response contains no references to internal operations unless directly requested.
+
+```plurnk-example
+# PLAN0
+[{"content":"report.md is very large, requiring chunking.","status":"memory"},
+{"content":"Update the existing private summary entry with relevant findings from report.md.","status":"in_progress"}]
+## EDIT0 [+quarterly] (worker://~/report-summary.md) <@wCf7x>
+* Q3 results: 42%
+
+## EDIT0 [+quarterly] (worker://~/report-summary.md) <-1>
+* Q4 results exceeded Q3
+
+## READ0 [+quarterly] (report.md) <501,700>
+## SEND0 [102]
+Next: Distill relevant findings from this chunk, then continue reading.
+```
+
 ### The PLAN
 
-* Determinations: Add and update all "memory" entries recording findings, learnings, or open questions.
-* Decisions: Add and update all "memory" entries recording conclusions, decisions, or policies.
-* Docket: Add and update all "pending", "in_progress", or "completed" work.
+* Determinations: "memory" entries recording findings or learnings.
+* Decisions: "memory" entries recording conclusions, decisions, or policies.
+* Docket: "pending", "in_progress", or "completed" work.
 
 ### Pattern Filtering
 
@@ -89,7 +113,7 @@ message
 | `//`   | xpath    | `//selector`                       | XPath 1.0        |
 | `$`    | jsonpath | `$.field`, `$.items[*].name`       | RFC 9535         |
 | `~`    | semantic | `~phrase`                          | embedding cosine |
-| `@`    | graph    | `@<symbol`, `@>symbol`, `@symbol`  | symbol index     |
+| `&`    | graph    | `&<symbol`, `&>symbol`, `&symbol`  | symbol index     |
 | none   | glob     | `pattern`                          | glob / literal   |
 
 * The leading symbol commits its dialect.
@@ -123,11 +147,12 @@ message
 * Unscoped FIND returns items 1-16; unscoped READ returns lines 1–16. `<1,-1>` returns all.
 * Rendered exact READ lines begin with a per-line `@hash` anchor and `L:` line number; neither is content.
 
-YOU SHOULD prefer `@hash` anchors for EDIT line coordinates; they reject stale targets.
+YOU SHOULD prefer `<@hash>` or `<@start,@end>` for EDIT line coordinates; they reject stale targets.
 
 ### The Log
 
-* `[+tag]` adds, `[-tag]` removes; FOLD/OPEN select by unsigned `[tag]`.
+* `[+tag]` adds, `[-tag]` removes; FOLD/OPEN apply signed tags or select by unsigned `[tag]` for folksonomic log curation.
+* `## KILL0 (log:///1/[1-7]/*/{PLAN,READ})` removes irrelevant log items.
 * `## FOLD0 [+trimmed] (log:///**/READ) <17,-1>` tags every READ and folds each body after line 16.
 * `## OPEN0 (log:///1/2/3/READ) <@aB3dE>` restores one anchored line.
 * Log item paths contain their loop, turn, and item: `log:///{loop}/{turn}/{item}/{OP}`.
@@ -138,23 +163,12 @@ YOU SHOULD FOLD, KILL, or trim superseded, stale, or irrelevant log content.
 
 | OP    | inherits   | typical use                     | body |
 |-------|------------|---------------------------------|------|
-| WORK  | fresh log  | Divide and conquer              | self-contained task with necessary context |
-| FORK  | forked log | Do two things at once           | distinct objective; prior context is inherited |
+| WORK  | fresh log  | Divide and conquer              | self-contained task prompt, with necessary context |
+| FORK  | forked log | Do two things at once           | distinct objective prompt; prior context is inherited |
 | BARE  | no log     | Context-free one-shot inference | complete standalone prompt |
 
-* Before delegating a worker with a git branch signal, ensure the repository is clean.
+* Delegation `body` must contain a prompt, not OPs.
 * Send a worker another message: `## SEND0 (worker://recheck)` with body `Also verify the alternative against the existing tests.`.
 * Terminate a worker: `## KILL0 (worker://recheck)`.
 
 YOU SHOULD decompose distinct subtasks into separate WORKers.
-
-## Submit codes
-
-| submit code      | meaning                          | body message                                |
-|------------------|----------------------------------|---------------------------------------------|
-| `## SEND0 [102]` | Continue to results in next turn | Describe expected or intended next steps    |
-| `## SEND0 [202]` | Wait for workers or streams      | Describe expected or intended next steps    |
-| `## SEND0 [200]` | Successful conclusion            | Response to the Active User Prompt          |
-| `## SEND0 [499]` | Abort and fail prompt            | Describe error or issue                     |
-
-YOU SHOULD continue or wait rather than conclude when submitting OPs with side effects.

package/dist/schema/LoopFlags.json

@@ -1,16 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.xyz/v0/LoopFlags.json",
-    "title": "LoopFlags",
-    "description": "The complete effective policy posture of one model loop. Persisted partial objects are expanded to this shape by the runtime owner before use or projection.",
-    "type": "object",
-    "required": ["mode", "auto", "noWeb", "noInteraction", "noProposals"],
-    "additionalProperties": false,
-    "properties": {
-        "mode": { "enum": ["ask", "act"] },
-        "auto": { "type": "boolean" },
-        "noWeb": { "type": "boolean" },
-        "noInteraction": { "type": "boolean" },
-        "noProposals": { "type": "boolean" }
-    }
-}