@plurnk/plurnk-contracts 1.11.0 → 1.13.0

package/dist/src/types.d.ts

@@ -1,9 +1,15 @@
 export * from "./types.generated.ts";
-import type { CapabilityPolicy, LoopPolicy, Position, PlurnkStatement, ReasoningPolicy } from "./types.generated.ts";
+import type { CapabilityPolicy, LoopPolicy, Position, PlurnkStatement, ProviderRequestAccounting, ReasoningPolicy } from "./types.generated.ts";
 import type PlurnkParseError from "./PlurnkParseError.ts";
 export declare const PLURNK_OPS: readonly ["FIND", "READ", "EDIT", "COPY", "MOVE", "OPEN", "FOLD", "SEND", "EXEC", "BARE", "WORK", "FORK", "KILL", "PLAN"];
 export declare const DEFAULT_RETRIEVAL_LIMIT = 16;
 export type PlurnkOp = (typeof PLURNK_OPS)[number];
+export interface ProviderRequestIdentity {
+    readonly provider: string;
+    readonly model: string;
+}
+export type ProviderRequestSettlement = (accounting: ProviderRequestAccounting) => Promise<void>;
+export type ProviderRequestObserver = (identity: ProviderRequestIdentity) => Promise<ProviderRequestSettlement>;
 export declare const REASONING_POLICIES: readonly ReasoningPolicy[];
 export declare const DEFAULT_CAPABILITY_POLICY: CapabilityPolicy;
 export declare const DEFAULT_LOOP_POLICY: LoopPolicy;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAC;AAGrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACrH,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAC;AAM1D,eAAO,MAAM,UAAU,YACnB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CACxG,CAAC;AAIX,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAInD,eAAO,MAAM,kBAAkB,EAE1B,SAAS,eAAe,EAAE,CAAC;AAEhC,eAAO,MAAM,yBAAyB,EAAE,gBAAoC,CAAC;AAE7E,eAAO,MAAM,mBAAmB,EAAE,UAGhC,CAAC;AAGH,eAAO,MAAM,WAAW,QAAyC,CAAC;AAGlE,eAAO,MAAM,oBAAoB,gCAAgD,CAAC;AAGlF,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,QAAQ,CAAyC,CAAC;AAI1F,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAIvC,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,eAAe,IACnC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,CAAC,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,eAAe,IAAI;IAC3C,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;IACtB,YAAY,CAAC,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAC;AAGrC,OAAO,KAAK,EACR,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,eAAe,EACf,yBAAyB,EACzB,eAAe,EAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAC;AAM1D,eAAO,MAAM,UAAU,YACnB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CACxG,CAAC;AAIX,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAKnD,MAAM,WAAW,uBAAuB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,yBAAyB,GAAG,CACpC,UAAU,EAAE,yBAAyB,KACpC,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,MAAM,uBAAuB,GAAG,CAClC,QAAQ,EAAE,uBAAuB,KAChC,OAAO,CAAC,yBAAyB,CAAC,CAAC;AAIxC,eAAO,MAAM,kBAAkB,EAE1B,SAAS,eAAe,EAAE,CAAC;AAEhC,eAAO,MAAM,yBAAyB,EAAE,gBAAoC,CAAC;AAE7E,eAAO,MAAM,mBAAmB,EAAE,UAGhC,CAAC;AAGH,eAAO,MAAM,WAAW,QAAyC,CAAC;AAGlE,eAAO,MAAM,oBAAoB,gCAAgD,CAAC;AAGlF,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,QAAQ,CAAyC,CAAC;AAI1F,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAIvC,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,eAAe,IACnC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,CAAC,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,eAAe,IAAI;IAC3C,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;IACtB,YAAY,CAAC,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD,CAAC"}

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

@@ -1055,7 +1055,7 @@ export interface ProviderRequestAccounting {
     cost: ProviderCost;
 }
 /**
- * Known token quantities for one provider request. Omitted fields are unknown; explicit zero is observed or exactly derived.
+ * Known token quantities. Physical-request instances enforce their partition identities; aggregate projections sum each reported field independently. Omitted fields are unknown; explicit zero is observed or exactly derived.
  */
 export interface ProviderUsage {
     inputTokens?: number;
@@ -1079,7 +1079,7 @@ export type DecimalAmount = string;
 export type NonEmptyString = string;
 export type Tokens = number;
 /**
- * Known token quantities for one provider request. Omitted fields are unknown; explicit zero is observed or exactly derived.
+ * Known token quantities. Physical-request instances enforce their partition identities; aggregate projections sum each reported field independently. Omitted fields are unknown; explicit zero is observed or exactly derived.
  */
 export type ReasoningPolicy = ("off" | "adaptive" | "low" | "medium" | "high");
 export interface SkillDefinition {

package/dist/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,oFAAoF;AACpF,cAAc,sBAAsB,CAAC;AAErC,OAAO,qBAAqB,MAAM,gCAAgC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAIzF,0EAA0E;AAC1E,6CAA6C;AAE7C,4FAA4F;AAC5F,MAAM,CAAC,MAAM,UAAU,GAAG;IACtB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CACxG,CAAC;AAEX,+EAA+E;AAC/E,6EAA6E;AAC7E,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAI1C,2EAA2E;AAC3E,uEAAuE;AACvE,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAC3C,qBAAqB,CAAC,IAAyB,CACpB,CAAC;AAEhC,MAAM,CAAC,MAAM,yBAAyB,GAAqB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAE7E,MAAM,CAAC,MAAM,mBAAmB,GAAe,MAAM,CAAC,MAAM,CAAC;IACzD,YAAY,EAAE,yBAAyB;IACvC,SAAS,EAAE,QAAQ;CACtB,CAAC,CAAC;AAEH,wFAAwF;AACxF,MAAM,CAAC,MAAM,WAAW,GAAG,sCAAsC,CAAC;AAElE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAU,CAAC,CAAC;AAElF,sFAAsF;AACtF,MAAM,CAAC,MAAM,gBAAgB,GAAuB,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,oFAAoF;AACpF,cAAc,sBAAsB,CAAC;AAErC,OAAO,qBAAqB,MAAM,gCAAgC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAWzF,0EAA0E;AAC1E,6CAA6C;AAE7C,4FAA4F;AAC5F,MAAM,CAAC,MAAM,UAAU,GAAG;IACtB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CACxG,CAAC;AAEX,+EAA+E;AAC/E,6EAA6E;AAC7E,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAoB1C,2EAA2E;AAC3E,uEAAuE;AACvE,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAC3C,qBAAqB,CAAC,IAAyB,CACpB,CAAC;AAEhC,MAAM,CAAC,MAAM,yBAAyB,GAAqB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAE7E,MAAM,CAAC,MAAM,mBAAmB,GAAe,MAAM,CAAC,MAAM,CAAC;IACzD,YAAY,EAAE,yBAAyB;IACvC,SAAS,EAAE,QAAQ;CACtB,CAAC,CAAC;AAEH,wFAAwF;AACxF,MAAM,CAAC,MAAM,WAAW,GAAG,sCAAsC,CAAC;AAElE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAU,CAAC,CAAC;AAElF,sFAAsF;AACtF,MAAM,CAAC,MAAM,gBAAgB,GAAuB,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-contracts",
-    "version": "1.11.0",
+    "version": "1.13.0",
     "description": "Canonical PLURNK language, schemas, generated types, parser, rails, and runtime-neutral wire contracts",
     "keywords": [
         "plurnk",

package/plurnk.md

@@ -1,7 +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 perform Plurnk OPs to resolve your pending and in_progress docket until the Active User Prompt is resolved.
+YOU MUST ONLY use the Plurnk OPs (PLAN|FIND|READ|EDIT|COPY|MOVE|FOLD|OPEN|EXEC|WORK|FORK|KILL|SEND).
+YOU MUST continue performing OPs until every Active User Prompt requirement and every pending or in_progress item is completed.
 
 ### Syntax
 
@@ -21,7 +21,7 @@ body?
 
 * 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`.
+* A scoped EDIT with no `body` deletes the selected region; an unscoped EDIT only creates a new file or entry.
 * Code fences are not part of the OP syntax. Do not add them around OPs.
 
 ```plurnk-syntax
@@ -40,18 +40,15 @@ literal replacement text
 
 ## MOVE0 [+tag] (source) <source text region> (destination) <destination text region> <!-- move between targets -->
 
-## FOLD0 [tag] (log items) <log body lines> <!-- hide matching log bodies -->
+## FOLD0 [±tag] (log items) <log body lines> <!-- hide matching log bodies -->
 filter pattern
 
-## OPEN0 [tag] (log items) <log body lines> <!-- reveal matching log bodies -->
+## OPEN0 [±tag] (log items) <log body lines> <!-- reveal matching log bodies -->
 filter pattern
 
 ## EXEC0 <!-- run a command, script, or tool -->
 command, script, or tool input
 
-## BARE0 [+tag] <!-- retrieve one model response -->
-prompt
-
 ## WORK0 (worker://name) <!-- spawn a child worker -->
 prompt
 
@@ -107,25 +104,24 @@ Next: Distill relevant findings from this chunk, then continue reading.
 
 * Pattern matchers in the OP's `body` select resources by content:
 
-| prefix | dialect  | form                               | engine           |
-|--------|----------|------------------------------------|------------------|
-| `/`    | regex    | `/pattern/flags`                   | ECMAScript       |
-| `//`   | xpath    | `//selector`                       | XPath 1.0        |
-| `$`    | jsonpath | `$.field`, `$.items[*].name`       | RFC 9535         |
-| `~`    | semantic | `~phrase`                          | embedding cosine |
-| `&`    | graph    | `&<symbol`, `&>symbol`, `&symbol`  | symbol index     |
-| none   | glob     | `pattern`                          | glob / literal   |
+| prefix | dialect  | form                               | example                 | engine           |
+|--------|----------|------------------------------------|-------------------------|------------------|
+| `/`    | regex    | `/pattern/flags`                   | `/\btimeout\b/i`        | ECMAScript       |
+| `//`   | xpath    | `//selector`                       | `//dependencies/*`      | XPath 1.0        |
+| `$`    | jsonpath | `$.field`, `$.items[*].name`       | `$[*][?(@.tokensActive>500)]` | RFC 9535         |
+| `~`    | semantic | `~phrase`                          | `~retry` | embedding cosine |
+| `&`    | graph    | `&<symbol`, `&>symbol`, `&symbol`  | `&<parseTurn`           | symbol index     |
+| none   | glob     | `pattern`                          | `?(export )?(async )function *` | glob / literal   |
 
 * The leading symbol commits its dialect.
 * In a path target, `*` maps one level and `**` crosses directories.
-* JSONPath filters bracket directly: `$[*][?(@.tokensActive>500)]`.
 * Mapping is universal: JSONPath can query XML and XPath can query JSON.
 * Patterned FIND returns resources for broad targets and locations for exact targets.
 
 ### `(path)`
 
 * Each OP's `(path)` slot takes exactly one bare project-relative path or resource URI.
-* Log item paths are nested: `log:///1/2/3` is loop/turn/item.
+* Log item paths are nested: `log:///1/2/3/READ` is loop/turn/item/OP; omit the OP segment to match any OP.
 * 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`.
@@ -140,12 +136,15 @@ Next: Distill relevant findings from this chunk, then continue reading.
 
 | form            | endpoint rule                  |
 |-----------------|--------------------------------|
-| `<L>`           | one line                       |
+| `<L>`           | one line |
+| `<@hash>`       | one line |
 | `<SL,EL>`       | lines SL through EL, inclusive |
+| `<@start,@end>` | lines @start through @end, inclusive |
 | `<SL,SC,EL,EC>` | start included, end excluded — `<2,1,2,5>` is columns 1-4 of line 2 |
+| `<0>`, `<-1>`  | prepend / append on mutations; as an end line, `-1` is the last line |
 
-* 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.
+* Unscoped FIND returns items 1-16; unscoped READ returns lines 1–16.
+* Rendered READ lines and an applied EDIT's resulting lines begin with a per-line `@hash` anchor and `L:` line number; neither is content.
 
 YOU SHOULD prefer `<@hash>` or `<@start,@end>` for EDIT line coordinates; they reject stale targets.
 
@@ -155,7 +154,6 @@ YOU SHOULD prefer `<@hash>` or `<@start,@end>` for EDIT line coordinates; they r
 * `## 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}`.
 
 YOU SHOULD FOLD, KILL, or trim superseded, stale, or irrelevant log content.
 
@@ -165,10 +163,7 @@ YOU SHOULD FOLD, KILL, or trim superseded, stale, or irrelevant log content.
 |-------|------------|---------------------------------|------|
 | 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 |
 
 * 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.