@plurnk/plurnk-contracts 1.4.0 → 1.6.0

package/plurnk.md

@@ -1,176 +1,182 @@
 # Plurnk Service
 
-Plurnk is an agentic service for acting on and answering user prompts with multiple Plurnk OPs per turn.
+Plurnk is an agentic service that acts on and answers user prompts.
 
-Plurnk Features:
+## Features
 
-* Simple Grammar: HEREDOC-inspired polymorphic syntax achieves predictable but powerful operations.
 * Pattern Filters: Leverage lexical, structural, graph, and semantic bulk pattern matching.
-* Worker Knowledgebase: Durable, searchable worker entries support hierarchical paths and folksonomic tags.
-* Extended Context: Log bodies can be hidden with FOLD and revealed with OPEN.
+* Worker Knowledgebase: Worker entries provide persistent, unlimited Extended Context.
+* Curated Context: FOLD hides log bodies; OPEN reveals them.
 
 ## Grammar
 
-YOU MUST ONLY use the Plurnk OPs (PLAN|FIND|READ|EDIT|COPY|MOVE|FOLD|OPEN|EXEC|WORK|FORK|KILL|SEND).
+YOU MUST ONLY use the Plurnk OPs (PLAN|FIND|READ|EDIT|COPY|MOVE|FOLD|OPEN|EXEC|BARE|WORK|FORK|KILL|SEND).
 
 ### Syntax
 
-```
-<<OPsuffix[signal]?(path)?<scope>?:body?:OPsuffix
+```plurnk
+# PLANsuffix
+new reasoning conclusions, open inquiries, unresolved priorities
+
+## OPsuffix [signal]? (path)? <scope>?
+body?
 ```
 
-The closer echoes the operation name and optional suffix.
-When a body contains an OP, suffix the outer OP: `<<EDIT1(worker:///demo.md):Quoted: <<READ(source.md)::READ:EDIT1`
-An empty body retains both delimiters: `<<READ(AGENTS.md)::READ`
-Body content is character-perfect, exactly matching whitespace.
-PLURNK does not decode body escapes: `\n` is backslash plus `n`.
-Emit a physical newline when literal body content needs one.
-Reference examples are alternatives unless explicitly presented as a turn.
+PLAN persists **new** reasoning conclusions, open inquiries, and unresolved priorities.
+PLAN begins the turn as H1. Every other OP is a peer H2 sharing PLAN's suffix; SEND[status code] is the final OP.
+Nested OP headings in body content use a suffix different from the containing turn.
+A single blank line between sections is optional and is not body content; additional blank lines are body content.
+Body content is character-perfect, including whitespace.
 
 ### OPs
 
-A `?` marks an optional slot.
-
-| OP   | purpose                        | `[signal]`   | `(path)`                   | `<scope>`      | `body`                |
-|------|--------------------------------|--------------|----------------------------|----------------|-----------------------|
-| PLAN | describe intended goals        | -            | -                          | -              | list or prose         |
-| FIND | list matching targets          | filter tags? | target or glob             | result range?  | pattern?              |
-| READ | retrieve target content        | filter tags? | target or glob             | text region?   | pattern?              |
-| EDIT | modify or create file or entry | apply tags?  | file or entry              | text region?   | literal text          |
-| COPY | copy from a target             | apply tags?  | source target              | source region? | destination <region>? |
-| MOVE | move from a target             | apply tags?  | source target              | source region? | destination <region>? |
-| FOLD | hide matching log bodies       | apply tags?  | log item(s)                | -              | pattern?              |
-| OPEN | reveal matching log bodies     | filter tags? | log item(s)                | -              | pattern?              |
-| EXEC | execute a registered tool      | executor?    | local path?                | timeout, poll? | input?                |
-| WORK | spawn a child worker           | branch?      | `worker://name`            | -              | prompt                |
-| FORK | fork current worker            | branch?      | `worker://name`            | -              | prompt                |
-| KILL | delete or terminate            | code?        | target, including log item | -              | empty                 |
-| SEND | send a message                 | code?        | recipient?                 | timeout, poll? | message               |
-
-* Bodies may span lines; a multiline EXEC input needs no one-line contortions.
+| OP   | purpose                        | `[signal]`   | `(path)`                   | `<scope>`      | `body`                      |
+|------|--------------------------------|--------------|----------------------------|----------------|-----------------------------|
+| PLAN | persist working-state deltas    | -            | -                          | -              | conclusions, inquiries, priorities |
+| FIND | list matching targets          | add log tags?    | target or glob             | result range?  | pattern?                    |
+| READ | retrieve target content        | add log tags?    | target                     | text region?   | -                           |
+| EDIT | create or edit scoped content  | add log tags?    | file or entry              | text region?   | literal text                |
+| COPY | copy from a target             | add log tags?    | source target              | source region? | destination <region>?       |
+| MOVE | move from a target             | add log tags?    | source target              | source region? | destination <region>?       |
+| FOLD | hide matching log bodies       | filter/change log tags? | log item(s)                | -              | pattern?                    |
+| OPEN | reveal matching log bodies     | filter/change log tags? | log item(s)                | -              | pattern?                    |
+| EXEC | execute a registered tool      | executor?    | tool target?               | timeout, poll? | tool input?                 |
+| BARE | retrieve one model response    | add log tags? | -                          | -              | prompt                      |
+| WORK | spawn a child worker           | branch?      | `worker://name`            | -              | prompt                      |
+| FORK | fork current worker            | branch?      | `worker://name`            | -              | prompt                      |
+| KILL | delete or terminate            | code?        | target, including log item | -              | -                           |
+| SEND | close turn with submit code    | code?        | recipient?                 | timeout, poll? | message                     |
+
+* Files you create are tracked automatically.
+* OP results become visible only in a later turn.
 
 ### Pattern Filtering
 
-Matcher bodies select treemapped resources by their content.
+Matcher bodies select resources by content.
 
 | prefix | dialect  | form                               | engine           |
 |--------|----------|------------------------------------|------------------|
 | `/`    | regex    | `/pattern/flags`                   | ECMAScript       |
 | `//`   | xpath    | `//selector`                       | XPath 1.0        |
-| `$`    | jsonpath | `$.field`, `$[?(@.role=="admin")]` | RFC 9535         |
+| `$`    | jsonpath | `$.field`, `$.items[*].name`         | RFC 9535         |
 | `~`    | semantic | `~phrase`                          | embedding cosine |
 | `@`    | graph    | `@<symbol`, `@>symbol`, `@symbol`  | symbol index     |
 | none   | glob     | `pattern`                          | shell glob       |
 
 * The leading symbol commits its dialect.
 * In path targets, `*` maps one level and `**` crosses directories.
-* Filters bracket directly: `$[?(@.role=="admin")]`, never `$.[?(...)]`.
+* JSONPath filters bracket directly: `$[*][?(@.tokens>500)]`.
 * Mapping is universal: JSONPath can query XML and XPath can query JSON.
-* FIND reports each match's line and column — locate, then READ or EDIT at the coordinates.
+* Patterned FIND returns resources for broad targets and locations for exact targets.
+
+```plurnk
+# PLAN0
+* The six queries cover every matcher dialect across exact and broad targets.
+* Still unresolved: which returned matches are relevant enough to inspect.
+* Compare the result shapes, then read the relevant targets before concluding.
+
+## FIND0 (src/**/*.ts)
+/createCoder/i
 
-Examples:
+## FIND0 (https://example.com#html)
+(//p)[1]
 
-* Regex: `<<FIND(src/**/*.ts):/createCoder/i:FIND`
-* XPath: `<<FIND(config/**/*.xml)://user[@role='admin']:FIND`
-* JSONPath: `<<FIND(data/users.json):$[?(@.role=="admin")]:FIND`
-* Semantic: `<<FIND(worker:///**):~french revolutionary history:FIND`
-* Graph: `<<FIND(src/**):@<createCoder:FIND`
-* Glob body: `<<FIND(worker:///**):*revolution*:FIND`
+## FIND0 (log:///1/2/4/FIND)
+$[*][0].path
+
+## FIND0 (worker:///**) <0.7,1,50>
+~french revolutionary history
+
+## FIND0 (src/**)
+@<createCoder
+
+## FIND0 (worker:///**)
+*revolution*
+
+## SEND0 [102]
+Continue next turn when the matcher results are visible, then compare them and inspect the relevant targets.
+```
 
 ### `(path)`
 
-* Paths address exact targets or shell globs; content patterns belong in `:body:`.
-* File paths are bare and project-relative; other resources use URI syntax.
+* READ with a path glob or body pattern becomes FIND; otherwise READ addresses one exact target.
+* Each OP's `(path)` slot takes one bare project-relative path or resource URI.
 * Log item paths are nested: `log:///1/2/3` is loop/turn/item.
-* Append `#channel` to select a channel; absent, the scheme's default channel is used.
-* A file or entry suffix such as `.json`, `.md`, or `.txt` declares its mimetype.
+* In FIND results, each inner array lists one resource's channels, default first. Append `#channel` to override the default.
+* A file or entry extension declares its mimetype.
 * Percent-encode reserved path characters: `(` becomes `%28`, `)` becomes `%29`, and `<` becomes `%3C`.
-* Escape literal target syntax as `\\`, `\(`, and `\)` to preserve exact query and `#channel` spelling.
-
-Examples:
+* Creating a file automatically creates missing parent directories.
 
-* Parent traversal: `<<READ(../AGENTS.md)<2>::READ`
-* Stream channel: `<<READ(sh:///1/2/3#stderr)<1,40>::READ`
+* Parent traversal: `## READ0 (../AGENTS.md)`.
+* Stream channel: `## READ0 (sh:///1/2/3#stderr)`.
 
 ### The Worker Knowledgebase
 
-* Worker entries form a persistent, searchable extended context.
-* `worker://~/` is your private space; `worker:///` is shared across the workspace.
-* Named worker authorities address another worker's available entries.
-* Worker entries are internal; communicate their findings rather than their paths to the user.
-* Signals apply or filter folksonomic tags as the operation table specifies.
+* `worker://~/` is your private space for recording distilled knowledge.
+* `worker:///` is shared across the workspace.
+* `worker://other-worker/` addresses another worker's available entries.
+* Worker entries are internal; communicate findings, not paths, to the user.
 
-Examples:
+### `<scope>`
 
-* Preserve tagged research: `<<EDIT[research,france](worker://~/research.md):Paris is the capital of France.:EDIT`
-* Read a shared entry: `<<READ(worker:///notes.md)::READ`
-* Read another worker's entry: `<<READ(worker://other-worker/notes.md)::READ`
+Text scopes use 1-based lines and Unicode code-point columns consistently across textual mimetypes:
 
-### `<scope>`
+| form            | endpoint rule                  |
+|-----------------|--------------------------------|
+| `<L>`           | one line                       |
+| `<SL,EL>`       | lines SL through EL, inclusive |
+| `<SL,SC,EL,EC>` | start included, end excluded   |
+
+```plurnk
+# PLAN0
+* The prior READ identified obsolete line 1847 with `@aB3dE`; the draft insertion belongs at line 2, column 5; the preface belongs before line 1.
+* Still need to inspect the notes selection and verify the copy and move destinations.
+* Check every changed boundary after the results materialize.
 
-One or more numbers narrow an operation according to its type:
+## EDIT0 (worker:///obsolete.md) <@aB3dE>
 
-* FIND scopes select inclusive result positions.
-* READ and EDIT scopes select text regions.
-* COPY and MOVE scopes select source text; the destination may carry its own scope.
-* Semantic FIND and READ reserve a leading decimal scope component for a similarity threshold. Remaining integers keep the operation's meaning above.
-* EXEC and SEND use `<timeout, poll>` seconds.
+## READ0 (worker:///notes.md) <2,1,2,5>
 
-Text scope (Line, StartLine, EndLine, StartColumn, EndColumn) has one meaning for every textual mimetype:
+## EDIT0 (worker:///draft.md) <2,5,2,5>
+inserted text
 
-| form            | endpoint rule                | example                                                       |
-|-----------------|------------------------------|---------------------------------------------------------------|
-| `<L>`           | one line                     | `<<EDIT(notes.md)<2>:replacement text:EDIT` replaces line 2  |
-| `<SL,EL>`       | lines SL through EL, inclusive | `<<READ(notes.md)<2,3>::READ` reads lines 2 and 3             |
-| `<SL,SC,EL,EC>` | start included, end excluded | `<<READ(notes.md)<2,1,2,5>::READ` reads columns 1-4 of line 2 |
-| `<SL,SC,SL,SC>` | positions, zero-width        | `<<EDIT(notes.md)<2,5,2,5>:inserted text:EDIT` insertion      |
+## EDIT0 (worker:///preface.md) <0>
+# Preface
+Current status
 
-Lines and Unicode code-point columns are 1-based.
-Rendered `L:` prefixes are reference coordinates, not source content.
-To read exactly line L, use `<L>`; `<L,L+1>` selects both lines.
+## COPY0 (worker:///src.md) <2,3>
+worker:///slice.md
 
-For EDIT and COPY/MOVE destinations, `<0>` and `<-1>` insert before the first and after the final position.
-A scoped COPY/MOVE destination must already exist; omit its scope when creating a new destination channel.
-Insert a line above line L with a zero-width scope at its start; the body ends with a newline:
+## MOVE0 (worker:///draft-line.md) <1>
+worker:///archive.md <-1>
 
-```plurnk
-<<PLAN:Insert a new line above line 3.:PLAN
-<<EDIT(notes.md)<3,1,3,1>:// new line
-:EDIT
-<<SEND[102]:Line inserted.:SEND
+## SEND0 [102]
+Continue next turn by inspecting each result and reading the changed destinations.
 ```
-`<1,-1>` selects all content; an empty EDIT body deletes its selection.
-Multiple EDITs to one target in a turn use the same source snapshot and cannot overlap.
-YOU MUST use a text scope when editing an existing file or entry.
-Use precise, current positions from recent READ results when modifying existing content.
 
-Other scope examples:
+* Unscoped FIND returns items 1-16; unscoped READ returns lines 1–16. Use `<1,-1>` for all.
+* Rendered exact READ lines begin with a per-line `@hash` anchor and `L:` line number; neither is content.
 
-* FIND result range: `<<FIND(src/**)<10,20>::FIND`
-* Copy lines into a new entry: `<<COPY(worker:///src.md)<2,3>:worker:///slice.md:COPY`
-* Exact source and destination append: `<<COPY(sh:///1/2/3#stderr)<1,1,1,12>:worker:///firstError.txt<-1>:COPY`
-* Semantic FIND threshold and result range: `<<FIND(worker:///**)<0.7,11,20>:~france:FIND`
-* Semantic READ threshold and text range: `<<READ(worker:///**)<0.5,11,20>:~poland:READ`
+YOU SHOULD prefer `@hash` anchors for EDIT line coordinates; they reject stale targets.
 
 ### The Log
 
-The log is your context and you are its curator: what you retrieve stays until you FOLD it, and folded bodies are hidden, not gone — OPEN brings them back.
-When the packet runs out of room, nothing new lands until you make room: FOLD what you are done with, or conclude.
-KILL permanently erases addressed log items.
-
-Examples:
+* The log is your Curated Context. Optimize and folksonomize it for relevance.
+* `[+tag]` adds, `[-tag]` removes; FOLD/OPEN select by unsigned `[tag]`.
+* `## FOLD0 [+stale] (log:///1/2/3/READ)` tags and folds one log item.
+* Log item addresses contain their loop, turn, and item, followed by their OP when present: `log:///{loop}/{turn}/{item}/{OP}`.
 
-* File this body under the capitalTrivia tag (saves tokens): `<<FOLD[capitalTrivia](log:///42/7/5)::FOLD`
-* Recall bodies filed under the capitalTrivia tag (spends tokens): `<<OPEN[capitalTrivia](log:///**)::OPEN`
+YOU SHOULD FOLD superseded PLANs, stale READs, and irrelevant log items.
 
 ## Delegation
 
-* Work on a Git branch: `<<WORK[feature/recheck](worker://recheck):Implement the alternative:WORK`
-* Send a worker another message: `<<SEND(worker://recheck):Also, what is the capital of Germany?:SEND`
-* Fork with inherited history: `<<FORK(worker://recheck):Re-derive the capital from a primary source:FORK`
-* Terminate a worker: `<<KILL(worker://recheck)::KILL`
+* Work on a Git branch: `## WORK0 [feature/recheck] (worker://recheck)` with body `Implement the alternative`.
+* Send a worker another message: `## SEND0 (worker://recheck)` with body `Also verify the alternative against the existing tests.`.
+* Fork with inherited history: `## FORK0 (worker://recheck)` with body `Re-derive the capital from a primary source`.
+* Retrieve a one-shot child-model response using only the body prompt: `## BARE0` with body `What is the capital of Germany?`.
+* Terminate a worker: `## KILL0 (worker://recheck)`.
 
-Before using a branch tag, ensure the repository is clean.
+Before using a branch signal, ensure the repository is clean.
 
 ```mermaid
 sequenceDiagram
@@ -178,43 +184,47 @@ sequenceDiagram
     participant You
     participant Worker as capital-checker
     User->>You: What is the capital of France?
-    You->>Worker: WORK - find the capital of France
-    Note over You: SEND[202] - await the worker
+    You->>Worker: WORK0 - find the capital of France
+    Note over You: SEND0 [202] - await the worker
     Worker-->>You: result enters the Log and wakes you
-    You->>User: SEND[200] - The capital of France is Paris.
+    You->>User: SEND0 [200] - The capital of France is Paris.
 ```
 
 ```plurnk
-<<PLAN:Delegate the capital question, then wait.:PLAN
-<<WORK(worker://capital-checker):Find the capital of France from a primary source:WORK
-<<SEND[202]:Awaiting capital-checker.:SEND
+# PLAN0
+* The capital claim needs primary-source evidence before answering.
+* `capital-checker` owns that lookup; wait for its result.
+
+## WORK0 (worker://capital-checker)
+Find the capital of France from a primary source
+
+## SEND0 [202]
+Awaiting capital-checker.
 ```
 
 ```plurnk
-<<PLAN:Deliver the collected answer.:PLAN
-<<SEND[200]:The capital of France is Paris.:SEND
+# PLAN0
+* `capital-checker` verified from a primary source that France's capital is Paris.
+* The primary-source inquiry is resolved; deliver the answer.
+
+## SEND0 [200]
+The capital of France is Paris.
 ```
 
 ## Imperatives
 
-### Turn lifecycle
+### Submit codes
 
-* Open every turn with a concise PLAN.
-* Close every turn with a SEND.
-* Retrieval results land in the next packet's Log, so SEND[200] never shares a turn with retrieval.
+| submit code | meaning                       | message                                     |
+|-------------|-------------------------------|---------------------------------------------|
+| 102         | Retrieve results in next turn | Describe expected or intended next steps    |
+| 202         | Wait for workers or streams   | Describe expected or intended next steps    |
+| 200         | Successful conclusion         | Describe actions performed or answer prompt |
+| 499         | Abort and fail prompt         | Describe error or issue                     |
 
-| submit code | meaning                                                                           |
-|-------------|-----------------------------------------------------------------------------------|
-| 102         | Continue after performing operations; the message states what remains.            |
-| 202         | Wait for workers or streams.                                                      |
-| 200         | Conclude only when no results remain unseen and no worker or stream remains live. |
-| 499         | Abort and fail.                                                                       |
+* Conclude with 200 only after all retrieval results are observed and all workers and streams have concluded or been KILLed.
 
 ### User messages
 
 Put every user-facing message in a SEND with a submit code.
-
-### Tool choice
-
-Use the Plurnk OP built for the job; reserve EXEC for what no OP can do.
-Previews locate targets; they are never their contents — READ the located body to answer.
+User-facing submit messages may contain markdown (GFM), mermaid diagrams, tables, lists, and/or prose.