@plurnk/plurnk-contracts 4.0.0 → 4.1.0

package/SPEC.md

@@ -410,7 +410,7 @@ repaired reading: a complete nested interpretation takes precedence. Each class
 | Counted | Complete readings | Repaired readings | Why |
 |---|---|---|---|
 | Hidden operations: a heading that will not run, written at its block's width or wider | 1, together with the next row | 1 | Every operation the author wrote should run |
-| Repairs: a supplied closer (except a message's run to the end of the input, {§message-run-on}), a fence read as a stray, a narrower closer accepted, a body under an operation that takes none (FIND, READ, COPY, MOVE, non-log targeted KILL), a body not well-formed in the media type its runtime declares ({§executor-invocation}) | none by definition | 2 | The least-errors distance |
+| Repairs: a supplied closer (except a message's run to the end of the input, {§message-run-on}), a fence read as a stray, a narrower closer accepted, a body under an operation that takes none (COPY, MOVE, non-log targeted KILL), a body not well-formed in the media type its runtime declares ({§executor-invocation}) | none by definition | 2 | The least-errors distance |
 | Literal by declaration: a heading narrower than its block, or no wider than the labeled block or example holding it, or inside a quotation or a KILL, or an executor heading inside a SEND, WORK, FORK or BARE body ({§prose-code-blocks}); a labeled fence in a body read as text | 1, together with the row above | 3 | Every code block the author declared should stand |
 | Supplied closers | 2 | 4 | A block the author opened should end at a fence the author wrote |
 | Other fences read as text | 3 | 5 | The least departure from the fences as written |
@@ -747,8 +747,7 @@ matcher." ({§diagnostic-observation}).
 §operation-aside The final header modifier may be one single-line HTML
 comment. AstBuilder removes its delimiters and surrounding whitespace into
 `aside: string | null`. It is durable descriptive text, not authority,
-routing, timing, or body input. Comments inside a body remain literal except
-for the narrowly owned {§misplaced-aside-advisory}.
+routing, timing, or body input. Comments inside a body remain literal.
 
 §scheme-metadata-modifier A target may carry one single-line `[metadata]`
 block, placed under {§slot-order}; executor and SEND fences also admit it without a target.
@@ -786,13 +785,10 @@ the owner verbatim, and the owner's reader treats `pattern` as reserved. The
 language lifts only from one block that parses as a JSON array of objects;
 anything else lifts nothing and reaches the owner's `400` untouched. A
 `pattern` that is present but not a string is the language's own positioned
-diagnostic, as is a matcher of a claimed dialect that fails admission. FIND,
-READ, and targeted KILL take no body: a body beneath their heading is not used and
-the operation still runs, with one warning-severity advisory naming the lines not
-used (`FIND takes no body; lines 4–6 were not used.`); it is never silently read as a
-matcher, and it never strikes ({§matcher-body-redirect}). The heading line itself
-is the matcher's home ({§naked-pattern}). A body that is only an HTML comment is
-still the aside under {§misplaced-aside-advisory}. EDIT keeps its literal body:
+diagnostic, as is a matcher of a claimed dialect that fails admission. FIND and
+READ bodies become memory under {§retrieval-annotation}; a non-log KILL's body is
+unused and receives the advisory under {§matcher-body-redirect}. The heading line
+is the matcher's home ({§naked-pattern}). EDIT keeps its literal body:
 with a matcher it is the replacement for every selected span ({§edit-pattern}),
 and an absent body deletes them. `PlurnkParser.stringify` writes a lifted matcher
 whose block left no metadata back bare when the bare form reads back identically
@@ -817,8 +813,8 @@ governed by {§canonical-statement}; runtime conditions remain explicit below.
 
 | OP   | `(path)`                                     | `<scope>`                       | `body`                         |
 |------|----------------------------------------------|---------------------------------|--------------------------------|
-| FIND | required target or glob                      | optional result range           | empty                          |
-| READ | required target                              | optional text region            | empty                          |
+| FIND | required target or glob                      | optional result range           | annotation normalized to NOTE |
+| READ | required target                              | optional text region            | annotation normalized to NOTE |
 | EDIT | required file or entry                       | required for an existing target | literal text                   |
 | COPY | required source and destination              | optional region after each path | empty                          |
 | MOVE | required source and destination              | optional region after each path | empty                          |
@@ -831,11 +827,22 @@ governed by {§canonical-statement}; runtime conditions remain explicit below.
 | NOTE | none | none | literal working memory |
 | WAIT | optional label ({§send-wait-scope}) | none; duration is `[seconds]` metadata | explanation of the wait |
 
+§retrieval-annotation **A retrieval's authored body is memory, not selection or output.**
+A nonblank body beneath FIND or READ becomes one ordinary NOTE immediately before
+the retrieval, including a body consisting of a pattern or an HTML comment. A
+grouped READ contributes one NOTE before its expanded statements. The retrieval
+itself has no body; its selector comes only from its header. Normalization is the
+same in content and exposed reasoning and never executes quoted body text. The
+canonical rendering is NOTE followed by bodyless retrieval; exact submitted text
+remains source evidence. The NOTE persists independently of retrieval success and
+is curated normally. Explicit NOTE remains the taught form.
+
 §note-value NOTE retains its literal body as ordinary model-owned working memory.
 It has no target, scope, metadata, or lifecycle effect. Its full body participates
 in ordinary log token accounting and model-driven curation; prior notes are not
-automatically hidden. A NOTE-only turn does not request completion; ordinary
-repetition and strike rules still apply.
+automatically hidden. Each turn may contain zero or more NOTEs; their omission
+produces neither a notice nor a failure. A NOTE-only turn does not request
+completion; ordinary repetition and strike rules still apply.
 
 §reasoning-operations The shared fence parser admits complete, line-leading NOTE,
 FIND and READ statements from exposed provider reasoning. Admission is part of
@@ -1779,7 +1786,7 @@ not infer it from diagnostic wording. It does not independently prescribe a stri
 §parse-recovery **Every hard diagnostic carries its working form.** A `severity: "error"`
 diagnostic names, in `recovery`, the form of the construct it refused, in the model's terms: a
 refused heading carries the operation's canonical line (`` `READ (path) <L,M>? pattern? <!-- aside -->?`
-on the opening fence line; READ takes no body. ``), a refused scope the scope's form, and a refused
+on the opening fence line. ``), a refused scope the scope's form, and a refused
 matcher its dialect's form with an example (`` A pattern is a regex written `/pattern/flags`, such
 as `/timeout/i`. ``). The working form is the language's, never a reconstruction of the input
 ({§diagnostic-observation}). The runtime projects `recovery` as the Problem's `recovery` beside the
@@ -1868,7 +1875,7 @@ diagnostics are:
   that already names a channel keeps such a token as its pattern. Those
   matchers remain independent of owner options: a block without `pattern` never
   erases the heading matcher, and invalid blocks still reach the owning validator.
-  These operations take no body, so heading-line text can mean nothing else. On EDIT only
+  Their heading-line text owns selection independently of annotation or distillation bodies. On EDIT only
   a sigil lifts, because plain heading-line text is the replacement body it always
   was; the lines beneath the heading are then the replacement, and none deletes each
   match ({§edit-pattern}). A trailing `<!-- aside -->` on the same line stays the
@@ -1929,15 +1936,12 @@ diagnostics are:
   body instead, the anchor would be written into the file, or the EDIT refused for want of a line
   marker (14 distinct recorded headings). On READ and KILL the same text stays a literal matcher,
   since `@patch` is a search a model means.
-- §matcher-body-redirect **Unread body text on bodyless operations.** FIND, READ and bodyless
-  KILL keep the statement but do not use text the matcher did not consume, with one warning
-  naming where it stands: `READ takes no body; lines 4–38 were not used.`, or `the text after its
-  heading on line 3` when it shares the heading's line. KILL's advisory says `This KILL`, limiting the claim to that invocation:
-  log distillation bodies remain valid. Delivered like
-  {§misplaced-aside-advisory} as a `parse_advisory` notice (a warning, never an error).
-  One sigil line beneath a bodyless heading is the bare form written a line low and still lifts;
-  nothing else is promoted into a matcher from below the heading. An option block's `pattern`
-  prevents that lift, and the advisory never echoes the discarded text.
+- §matcher-body-redirect **Unread selector text.** An option block's `pattern` owns the
+  selector; surplus heading text is unused with one warning naming its location.
+  A non-log KILL's body is likewise unused: `This KILL takes no body; line 2 was not used.`
+  Neither warning echoes discarded text. No operation recovers a matcher from below
+  its header. READ/FIND bodies follow {§retrieval-annotation}; log KILL bodies follow
+  {§log-kill-distillation}.
 - §combined-anchor-tolerance **Combined line number and anchor in a scope.** A
   text-coordinate scope written `L<@hash>` — digits immediately before the opener — is the
   displayed `42<@abcde>` row prefix copied whole: the scope is the anchor, the number is dropped, and one
@@ -1953,15 +1957,6 @@ diagnostics are:
   states the anchor rule instead, with the scope marked: `` every line anchor carries
   its `@`: `<@abcde,@fghij>` ``. Spacing and boundary-loss diagnostics retain their own
   contracts.
-- §misplaced-aside-advisory **Aside in the body.** A READ or FIND whose
-  body is solely an HTML comment (`<!-- … -->`) can never carry a matcher: it is
-  the aside the model put on the line below the heading. The builder takes
-  the comment as the aside when the heading has none, builds the operation
-  with no body, and raises one warning-severity advisory stating that observed
-  normalization; the parser places the advisory right after its statement and
-  the service delivers it as a `parse_advisory` notice with its position. A body
-  with any other content is ignored under the same advisory path
-  ({§matcher-body-redirect}).
 
 §error-shape The diagnostic class determines the parts of a message; every class says what
 happened, never why ({§diagnostic-observation}). Advisories belong to one successfully built statement. A rejected

package/dist/schema/PlurnkStatement.json

@@ -153,7 +153,7 @@
                 },
                 "body": {
                     "type": "null",
-                    "description": "FIND takes no body; its matcher is the `pattern` option."
+                    "description": "Retrieval bodies normalize to separate NOTE statements; selection belongs to the header ({§retrieval-annotation})."
                 },
                 "position": {
                     "$ref": "#/$defs/PositionRef"

package/dist/src/types.generated.d.ts

@@ -228,7 +228,7 @@ export interface FindStatement {
      */
     matcher: (MatcherBody | null);
     /**
-     * FIND takes no body; its matcher is the `pattern` option.
+     * Retrieval bodies normalize to separate NOTE statements; selection belongs to the header ({§retrieval-annotation}).
      */
     body: null;
     position: Position;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plurnk/plurnk-contracts",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Canonical PLURNK language contract, schemas, generated types, and runtime-neutral wire contracts",
   "keywords": [
     "plurnk",
@@ -72,5 +72,5 @@
   "devDependencies": {
     "json-schema-to-typescript": "^16.0.0"
   },
-  "gitHead": "9f92ceac0af7bdb64e57ebc73c0288bb0f36b720"
+  "gitHead": "52020b981eb3c10ddab9dc9b91c0e199eb7598ab"
 }

package/plurnk.md

@@ -1,7 +1,7 @@
 # Plurnk Operation Protocol
 
 > [!IMPORTANT]
-> YOU MUST ONLY emit fenced operations; with the parameters, pattern, and terse aside on the fenced operation line.
+> YOU MUST ONLY emit fenced operation batches; with the parameters, pattern, and terse aside on the fenced operation line. No tool calls.
 
 ## Syntax
 
@@ -9,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: Internal Working Memory Register recording **every** plan, finding, decision, and next action.
+* 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.
@@ -25,8 +28,11 @@ body?
 
 ## Loop Protocol
 
-> [!TIP]
-> YOU SHOULD record every plan, finding, decision, and next action in detailed NOTEs to avoid permanent loss of information.
+> [!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
@@ -44,13 +50,13 @@ a decision and its reasons
 the next action and what it needs
 ```
 
-```SEND
+````SEND
 a continuing progress update response
-```
+````
 
-```SEND [200]
+````SEND [200]
 a final deliverable response
-```
+````
 
 > [!CAUTION]
 > The loop continues until all Open Messages receive a `[200]` or `[499]` response and all Open Work is completed.
@@ -72,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>`
+## Membership (worker:///_plurnk/plurnk/members.md)
 
-> [!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 |
+```members (add) <!-- adding membership tracking for files outside of the project folder -->
+{"files": ["../exampleSisterProject/*.md", "../exampleSisterProject/example.json"]}
+```
 
 ## Editing
 
@@ -134,12 +142,6 @@ 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.