@plurnk/plurnk-contracts 4.0.0 → 5.0.0

package/SPEC.md

@@ -291,7 +291,7 @@ rule.
 
 §balanced-fences A complete nested interpretation takes precedence over missing-closer
 recovery. Within a body, a line-leading labeled fence opens a literal block, and an equal or
-wider bare fence nests where closing there would cost the reading more
+wider bare fence nests unless closing there costs the reading less
 ({§fence-pairing}). A nested block ends at its first valid closer, as a CommonMark code block
 does. So a wider outer fence holds any narrower body, finished or not, and equal widths nest
 when every inner block closes. Preserve every nested body byte, including apparent operations
@@ -409,13 +409,18 @@ 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 |
-| 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 |
+| Hidden operations: a heading that will not run, written at its block's width or wider | 1, together with discarded code | 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 (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 shown as a code block inside a SEND, WORK, FORK or BARE body ({§prose-code-blocks}) | none: the author's enclosure wrote it as an example | 3, together with the row below | A heading the author wrapped is the example it was written as |
+| Discarded code: a labeled fence in a body read as text, or such an executor heading read as text | 1, together with hidden operations | 3, together with the row above | 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 |
 
-Complete readings compare exactly as a single least-errors order would. Once every reading of an
+Complete readings compare as a single least-errors order over departures from the fences as written,
+and a heading the author enclosed in a wider or labeled fence is the example it was written as, not a
+departure. So a message whose own fence is narrower than the fences wrapping its examples still holds
+them: the reading that lets a wrapper close the message and runs the examples ties on cost and loses on
+preference, since a body nests before it closes ({§balanced-fences}). Once every reading of an
 emission needs a repair, its shape is already broken, and saving a repair is not worth an operation
 the author wrote: across the corpus, readings that traded operations for repairs held a WORK in a
 BARE behind two stray fences, wrote 11,485 characters of operation text into a file as an EDIT
@@ -747,8 +752,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 +790,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 +818,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 +832,23 @@ 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. A continuing or parked turn that carried no NOTE is told so in
+the next packet ({§continued-without-note}); the omission is never 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 +1792,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 +1881,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 +1942,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 +1963,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/Functionality.d.ts

@@ -58,6 +58,7 @@ export interface FunctionalityPrepared<Runtime = never> {
     readonly documents: readonly FunctionalityDocument[];
     readonly outcomes: ReadonlyMap<string, FunctionalityOutcome>;
     readonly snapshot: unknown;
+    publish(): (() => void) | undefined;
     commit(): Promise<void>;
     abort(): Promise<void>;
 }

package/dist/src/Functionality.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Functionality.d.ts","sourceRoot":"","sources":["../../src/Functionality.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Functionality.d.ts","sourceRoot":"","sources":["../../src/Functionality.ts"],"names":[],"mappings":"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"}

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": "5.0.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": "c75c4bc760db609905a8a0932bd1f50bb4d8886c"
 }

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: Working memory. Save all new facts, ideas, and plans 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,32 +28,28 @@ body?
 
 ## Loop Protocol
 
-> [!TIP]
-> YOU SHOULD record every plan, finding, decision, and next action in detailed NOTEs to avoid permanent loss of information.
-
-```NOTE <!-- plan -->
-the steps ahead and why
-```
+> [!IMPORTANT]
+> YOU MUST persist all new facts, ideas, and plans in NOTEs on every turn.
 
-```NOTE <!-- finding -->
-a finding and its evidence
+```NOTE <!-- fact -->
+a finding or conclusion and its evidence
 ```
 
-```NOTE <!-- decision -->
-a decision and its reasons
+```NOTE <!-- idea -->
+a thought, working theory, or decision, and why
 ```
 
-```NOTE <!-- next -->
-the next action and what it needs
+```NOTE <!-- plan -->
+the steps ahead and why
 ```
 
-```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 +71,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
 
@@ -134,12 +135,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.