@plurnk/plurnk-contracts 1.17.0 → 1.19.0

package/plurnk.md

@@ -1,53 +1,40 @@
 # Plurnk Harness
 
-## Harness Operation Syntax
+Pattern Lookup Universal Resource NetworK: find anything by pattern, read it by address, change it by operation.
+
+## Operation Syntax
 
     ````OP (path)? <scope|range>? [metadata]? pattern? <!-- aside -->?
     body?
     ````
 
 > [!IMPORTANT]
-> YOU MUST ONLY perform OPs (helper operations, registered executors, or enabled MCP services).
-
-> [!IMPORTANT]
-> YOU MUST include the OP and its parameters on the opening fence line.
-
-* `[metadata]`: optional one-line JSON array of option objects.
-* `<!-- aside -->`: optional terse note beside (never below) the operation line.
-
-## Helper Operations
-
-* 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
-* COPY (from) (to): copy files, entries, streams, or text regions
-* MOVE (from) (to): move files, entries, streams, or text regions
-* SEND: message workers or endpoints; without a path, respond to Active Prompts
-* WORK: deploy a child worker (fresh log)
-* FORK: deploy a forked worker (forked log)
-* BARE: deploy an isolated inference query (no log or tools)
-* KILL: delete, terminate, or curate the log
-* TASK: task inventory
+> YOU MUST ONLY respond with either valid Operation Syntax OPs or prose (concludes loop, may contain GFM). Not both.
+
+* `[metadata]`: optional one-line JSON array of special configuration.
+* `<!-- aside -->`: optional terse note.
+* All parameters and the aside must appear on the same line as OP.
+* OP may be either a Plurnk Operation or one of the tools.
+
+## Plurnk Operations
+
+* NOTE: Retain conclusions, decisions, and working memory (also works inside reasoning).
+* 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.
+* COPY: (path) <scope>? (path) <scope>? - Copy files, entries, streams, or text regions.
+* MOVE: (path) <scope>? (path) <scope>? - Move files, entries, streams, or text regions.
+* KILL: Delete, terminate, or curate the log.
+* SEND: Message workers and endpoints, not tools.
+* WORK: Deploy a child worker (fresh log).
+* FORK: Deploy a forked worker (forked log).
+* BARE: Deploy an isolated inference query (no log or tools).
+* WAIT: Yield until the next wake: a child's result, a message, a stream's end.
 
 ## Workflow Management
 
-    ````TASK <!-- status of tasks necessary to resolve Active Prompts -->
-    [{"content": string, "status": "pending" | "waiting" | "in_progress" | "completed" | "failed"}]
-    ````
-
-* `pending`: blocked until a task it depends on is `completed`.
-* `waiting`: parked until a stream or worker finishes (doesn't block other in_progress work).
-* `in_progress`: active work.
-* `completed`, `failed`: resolved, successfully or not.
-
-> [!IMPORTANT]
-> YOU SHOULD conclude every turn with one TASK operation.
-
-> [!IMPORTANT]
-> A turn holding only the final response SEND and a TASK with every task `completed` or `failed` finishes the loop.
-
-> [!IMPORTANT]
-> YOU MAY NOT finish the loop while a task, worker, or stream is unfinished.
+> [!INFO]
+> To cancel all unfinished work in your worker and its descendants, KILL your own worker address.
 
 ## Workspace Navigation
 
@@ -57,9 +44,6 @@
     ````READ (belfry.md) /\bbats?\b/i <!-- only the lines matching "bat" or "bats" -->
     ````
 
-> [!TIP]
-> Locate with FIND, then READ a scope or a pattern; prefer glob-filtered paths over broad scans.
-
 * `(path)` may be a glob, permitting bulk operations.
 * Log item paths nest: `log:///1/2/3/READ` is loop/turn/item/operation.
 * FIND results hold one inner array per path: its channels, default first; append `#channel` to select another.
@@ -77,26 +61,16 @@
 
     ````42EDIT (edit-example.md) <!-- resolve nested OP conflicts with matching numeric delimiters after fencing -->
     ````EDIT (edit-example.md)
-    An edit example.
+    OPs always begin and end with exactly four backticks, both immediately after a newline.
     ````
     ````42
 
 > [!TIP]
 > The EDIT body is literal text. YOU SHOULD address lines by `<@hash>` or `<@start,@end>`; stale targets are rejected.
 
-## Messaging
-
-    ````SEND (node:///c4e56789) <!-- SEND with a (path) sends the message to the path -->
-    With a running node script, SEND passes this message to stdin.
-    ````
-
-    ````SEND <!-- SEND without a (path) responds to Active Prompts -->
-    YOU SHOULD format responses to the Active Prompts in Markdown, using Mermaid diagrams, tables, lists, or prose.
-    ````
-
 ## Delegation
 
-    ````WORK (worker://reviewer) <!-- the child's result lands in your log -->
+    ````WORK (worker://reviewer) [{"env": {"NODE_ENV": "test"}}] <!-- the child's result lands in your log -->
     Review src/ for unhandled promise rejections.
     ````
 
@@ -104,18 +78,18 @@
     ````
 
 > [!TIP]
-> `SEND (worker://name)` messages a live worker. The packet's `## Delegation` lists your live workers and streams.
+> `SEND (worker://name)` messages a live worker.
 
 ## Context Curation
 
-    ````KILL (log:///1/[1-7]/*/{TASK,READ}) <!-- removes matching log items -->
-    ````
+> [!CAUTION]
+> logTokensTotal must not exceed logTokensMax. Successful log KILL receipts are not shown; one that matched nothing says so, once.
 
-    ````KILL (log:///**/READ) <17,-1> <!-- trims each item's log lines from 17 on -->
+    ````KILL (log:///1/[1-7]/*/{NOTE,READ}) <!-- removes matching log items, recovering context -->
     ````
 
-> [!CAUTION]
-> logTokensTotal must not exceed logTokensMax. KILL on log items and lines hides them from your context without deleting anything; successful log KILL receipts are not shown.
+    ````KILL (log:///**/READ) <17,-1> <!-- trims each item's log lines from 17 on, recovering context -->
+    ````
 
 ## `<scope|range>`
 
@@ -125,23 +99,25 @@ Text scopes use 1-based lines and Unicode code-point columns across textual mime
 |-----------------|--------------------------------|
 | `<L>`, `<@hash>` | one line |
 | `<SL,EL>`, `<@start,@end>` | lines SL through EL, inclusive |
-| `<SL,SC,EL,EC>` | start included, end excluded — `<2,1,2,5>` is columns 1-4 of line 2 |
+| `<SL,SC,EL,EC>` | start included, end excluded — `<2,3,3,6>` is line 2 column 3 through line 3 column 5 |
 | `<0>`, `<-1>`  | prepend / append on mutations; as an end line, `-1` is the last line |
 
 > [!CAUTION]
 > The hash anchor and line number (`@abcde 42:`) shown on editable text are not content.
 
-## `pattern`
+> [!TIP]
+> The log often presents partial preview ranges. READ more if it's relevant and you have the logTokensMax room for it.
 
-| prefix | dialect                  | example                         |
-|--------|--------------------------|---------------------------------|
-| `/`    | regex (ECMAScript)       | `/\btimeout\b/i`                |
-| `^`    | regex anchored to a line | `^Note:.*`                      |
-| `//`   | xpath (1.0)              | `//dependencies/*`              |
-| `$`    | jsonpath (RFC 9535)      | `$.items[?(@.price>500)]`       |
-| `~`    | full-text (SQLite FTS5)  | `~retry`                        |
-| `&`    | graph: `&sym` all relations, `&<sym` referrers, `&>sym` referents | `&<parseTurn` |
-| none   | glob, or a literal       | `?(export )?(async )function *` |
+## `pattern`
 
-> [!TIP]
-> The `[metadata]` parameter accepts a `[{"pattern":"matcher"}]` option for patterns that cannot be inline.
+All member files and entries are mapped, indexed, and universally pattern searchable.
+
+| prefix | dialect                     | example                         |
+|--------|-----------------------------|---------------------------------|
+| `/`    | regex (ECMAScript)          | `/\btimeout\b/i`                |
+| `^`    | regex anchored to a line    | `^ERROR:.*`                     |
+| `//`   | xpath (1.0)                 | `//dependencies/*`              |
+| `$`    | jsonpath (RFC 9535)         | `$.items[?(@.price>500)]`       |
+| `~`    | full-text (SQLite FTS5)     | `~retry`                        |
+| `&`    | graph: (treesitter symbols) | `&sym`, `&<sym`, `&>sym`        |
+| none   | literal or extglob          | `?(export )?(async )function *` |

package/bin/plurnk-contracts.js

@@ -1,43 +0,0 @@
-#!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { parseArgs } from "node:util";
-import { PlurnkParser } from "../dist/src/index.js";
-
-const USAGE = `Usage:
-  plurnk-contracts [file]      Parse plurnk source from a file (or stdin if omitted or '-')
-                     and print the result as JSON.
-  plurnk-contracts --help      Show this message.
-
-Exit codes:
-  0   parse succeeded with no errors and no unparsed tail
-  1   parse produced one or more errors, or left an unparsed tail`;
-
-const { values, positionals } = parseArgs({
-    args: process.argv.slice(2),
-    options: {
-        help: { type: "boolean", short: "h" },
-    },
-    allowPositionals: true,
-});
-
-if (values.help) {
-    process.stdout.write(`${USAGE}\n`);
-    process.exit(0);
-}
-
-const target = positionals[0];
-const input = !target || target === "-"
-    ? readFileSync(0, "utf8")
-    : readFileSync(target, "utf8");
-
-const result = PlurnkParser.parse(input);
-
-const serialized = JSON.stringify(
-    result,
-    (_key, value) => (value instanceof RegExp ? value.toString() : value),
-    2,
-);
-process.stdout.write(`${serialized}\n`);
-
-const hasIssues = result.items.some((i) => i.kind === "error") || result.unparsedTail !== undefined;
-process.exit(hasIssues ? 1 : 0);

package/dist/schema/AcpPlan.json

@@ -1,63 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.xyz/v0/AcpPlan.json",
-    "$comment": "ACP v1 Plan, pinned to schema-v1.21.0 / 272bf799f35a258c6a4107a0410ed361e83683d3.",
-    "title": "AcpPlan",
-    "description": "The standards-facing ACP v1 execution plan.",
-    "type": "object",
-    "properties": {
-        "entries": {
-            "description": "The complete list of current plan entries.",
-            "type": "array",
-            "items": { "$ref": "#/$defs/AcpPlanEntry" }
-        },
-        "_meta": {
-            "description": "Metadata reserved by ACP. Consumers must not assume meanings for its keys.",
-            "type": ["object", "null"],
-            "additionalProperties": true
-        }
-    },
-    "required": ["entries"],
-    "$defs": {
-        "AcpPlanEntry": {
-            "description": "One task or goal in an ACP execution plan.",
-            "type": "object",
-            "properties": {
-                "content": {
-                    "description": "Human-readable description of what this task aims to accomplish.",
-                    "type": "string"
-                },
-                "priority": {
-                    "description": "The relative importance of this task.",
-                    "$ref": "#/$defs/AcpPlanEntryPriority"
-                },
-                "status": {
-                    "description": "The current execution status of this task.",
-                    "$ref": "#/$defs/AcpPlanEntryStatus"
-                },
-                "_meta": {
-                    "description": "Metadata reserved by ACP. Consumers must not assume meanings for its keys.",
-                    "type": ["object", "null"],
-                    "additionalProperties": true
-                }
-            },
-            "required": ["content", "priority", "status"]
-        },
-        "AcpPlanEntryPriority": {
-            "description": "ACP v1 priority levels.",
-            "oneOf": [
-                { "type": "string", "const": "high" },
-                { "type": "string", "const": "medium" },
-                { "type": "string", "const": "low" }
-            ]
-        },
-        "AcpPlanEntryStatus": {
-            "description": "ACP v1 plan-entry lifecycle states.",
-            "oneOf": [
-                { "type": "string", "const": "pending" },
-                { "type": "string", "const": "in_progress" },
-                { "type": "string", "const": "completed" }
-            ]
-        }
-    }
-}

package/dist/schema/Plan.json

@@ -1,65 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.xyz/v0/Plan.json",
-    "$comment": "Plurnk's model-native Plan is a bare array of {content, status} task entries. ACP projection (separately owned by AcpPlan.json) supplies the required priority at the edge.",
-    "title": "Plan",
-    "description": "Plurnk's model-native task inventory.",
-    "type": "array",
-    "items": {
-        "$ref": "#/$defs/PlanEntry"
-    },
-    "$defs": {
-        "PlanEntry": {
-            "description": "One task or goal in the model's plan.",
-            "type": "object",
-            "properties": {
-                "content": {
-                    "description": "Human-readable description of what this task aims to accomplish.",
-                    "type": "string"
-                },
-                "status": {
-                    "description": "The current execution status of this task.",
-                    "$ref": "#/$defs/PlanEntryStatus"
-                },
-                "_meta": {
-                    "description": "Opaque entry metadata preserved through standards projection.",
-                    "type": [
-                        "object",
-                        "null"
-                    ],
-                    "additionalProperties": true
-                }
-            },
-            "required": [
-                "content",
-                "status"
-            ],
-            "additionalProperties": false
-        },
-        "PlanEntryStatus": {
-            "description": "Model-native task states; ACP projection is separately owned.",
-            "oneOf": [
-                {
-                    "type": "string",
-                    "const": "pending"
-                },
-                {
-                    "type": "string",
-                    "const": "in_progress"
-                },
-                {
-                    "type": "string",
-                    "const": "waiting"
-                },
-                {
-                    "type": "string",
-                    "const": "completed"
-                },
-                {
-                    "type": "string",
-                    "const": "failed"
-                }
-            ]
-        }
-    }
-}

package/dist/src/AcpPlanValue.d.ts

@@ -1,6 +0,0 @@
-import type { AcpPlan } from "./types.ts";
-export default class AcpPlanValue {
-    static project(value: unknown): AcpPlan;
-    static assertCanonical(value: unknown): AcpPlan;
-}
-//# sourceMappingURL=AcpPlanValue.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"AcpPlanValue.d.ts","sourceRoot":"","sources":["../../src/AcpPlanValue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAK1C,MAAM,CAAC,OAAO,OAAO,YAAY;IAC7B,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAsBtC;IAED,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK9C;CAEJ"}

package/dist/src/AcpPlanValue.js

@@ -1,36 +0,0 @@
-import PlanValue from "./PlanValue.js";
-import Validator from "./Validator.js";
-// {§plan-acp-projection}
-export default class AcpPlanValue {
-    static project(value) {
-        const plan = PlanValue.assertCanonical(value);
-        const projected = {
-            entries: plan.map((entry) => {
-                const metadata = Object.fromEntries(Object.entries(entry._meta ?? {}).filter(([key]) => key !== "plurnk.xyz/status"));
-                const { _meta: _ignored, ...fields } = entry;
-                if (entry.status !== "waiting" && entry.status !== "failed")
-                    return {
-                        ...fields,
-                        status: entry.status,
-                        priority: "medium",
-                        ...(Object.keys(metadata).length === 0 ? {} : { _meta: metadata }),
-                    };
-                return {
-                    ...entry,
-                    content: `${entry.status === "waiting" ? "Waiting" : "Failed"}: ${entry.content}`,
-                    status: entry.status === "waiting" ? "in_progress" : "completed",
-                    priority: "medium",
-                    _meta: { ...metadata, "plurnk.xyz/status": entry.status },
-                };
-            }),
-        };
-        return AcpPlanValue.assertCanonical(projected);
-    }
-    static assertCanonical(value) {
-        if (!Validator.validateAcpPlan(value).valid) {
-            throw new TypeError("Expected a canonical ACP Plan.");
-        }
-        return value;
-    }
-}
-//# sourceMappingURL=AcpPlanValue.js.map

package/dist/src/AcpPlanValue.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"AcpPlanValue.js","sourceRoot":"","sources":["../../src/AcpPlanValue.ts"],"names":[],"mappings":"AACA,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,SAAS,MAAM,gBAAgB,CAAC;AAEvC,yBAAyB;AACzB,MAAM,CAAC,OAAO,OAAO,YAAY;IAC7B,MAAM,CAAC,OAAO,CAAC,KAAc;QACzB,MAAM,IAAI,GAAG,SAAS,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,SAAS,GAAG;YACd,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;gBACxB,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,mBAAmB,CAAC,CAAC,CAAC;gBACtH,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC;gBAC7C,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ;oBAAE,OAAO;wBAChE,GAAG,MAAM;wBACT,MAAM,EAAE,KAAK,CAAC,MAAM;wBACpB,QAAQ,EAAE,QAAiB;wBAC3B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;qBACrE,CAAC;gBACF,OAAO;oBACH,GAAG,KAAK;oBACR,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE;oBACjF,MAAM,EAAE,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,aAAsB,CAAC,CAAC,CAAC,WAAoB;oBAClF,QAAQ,EAAE,QAAiB;oBAC3B,KAAK,EAAE,EAAE,GAAG,QAAQ,EAAE,mBAAmB,EAAE,KAAK,CAAC,MAAM,EAAE;iBAC5D,CAAC;YACN,CAAC,CAAC;SACa,CAAC;QACpB,OAAO,YAAY,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,CAAC,eAAe,CAAC,KAAc;QACjC,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC;YAC1C,MAAM,IAAI,SAAS,CAAC,gCAAgC,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,KAAgB,CAAC;IAC5B,CAAC;CAEJ"}

package/dist/src/AstBuilder.d.ts

@@ -1,21 +0,0 @@
-import type { ClientStatement, ParsedPath, PlurnkStatement, Position } from "./types.ts";
-import type { ClientStatementContext, StatementContext, MidStatementContext } from "./generated/plurnkParser.ts";
-import { DispositionStatementContext, SendStatementContext } from "./generated/plurnkParser.ts";
-import PlurnkParseError from "./PlurnkParseError.ts";
-declare module "xpath" {
-    function parse(expression: string): unknown;
-}
-export default class AstBuilder {
-    #private;
-    static takeAdvisories(): PlurnkParseError[];
-    static build(ctx: StatementContext | MidStatementContext | DispositionStatementContext | SendStatementContext): PlurnkStatement;
-    static buildClient(ctx: ClientStatementContext): ClientStatement;
-    static executorSpellings: ReadonlyMap<string, string>;
-    /**
-     * Apply target-slot decomposition without round-tripping through a statement.
-     * Returns null for empty input and throws PlurnkParseError when a scheme URL
-     * fails WHATWG admission. {§path-syntax}
-     */
-    static parsePath(raw: string, pos?: Position): ParsedPath | null;
-}
-//# sourceMappingURL=AstBuilder.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"AstBuilder.d.ts","sourceRoot":"","sources":["../../src/AstBuilder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAER,eAAe,EAaf,UAAU,EACV,eAAe,EACf,QAAQ,EAOX,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAER,sBAAsB,EActB,gBAAgB,EAChB,mBAAmB,EACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAIH,2BAA2B,EAC3B,oBAAoB,EAGvB,MAAM,6BAA6B,CAAC;AAErC,OAAO,gBAAgB,MAAM,uBAAuB,CAAC;AAMrD,OAAO,QAAQ,OAAO,CAAC;IACnB,SAAgB,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CACtD;AAQD,MAAM,CAAC,OAAO,OAAO,UAAU;;IAK3B,MAAM,CAAC,cAAc,IAAI,gBAAgB,EAAE,CAI1C;IAwJD,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,mBAAmB,GAAG,2BAA2B,GAAG,oBAAoB,GAAG,eAAe,CAmB9H;IA8BD,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,sBAAsB,GAAG,eAAe,CAI/D;IA4ID,MAAM,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAa;IAgSlE;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,QAAiC,GAAG,UAAU,GAAG,IAAI,CAmCvF;CAiLJ"}