@plurnk/plurnk-contracts 1.4.0

package/dist/schema/PlurnkStatement.json

@@ -0,0 +1,264 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/PlurnkStatement.json",
+    "title": "PlurnkStatement",
+    "description": "The parsed AST union for one protocol statement, discriminated by `op`. Every variant has fixed signal, target, lineMarker, body, suffix, and source-position fields; operation-specific schemas constrain their types. A null field records an omitted tolerated slot and does not satisfy runtime requirements by itself.",
+    "oneOf": [
+        { "$ref": "#/$defs/FindStatement" },
+        { "$ref": "#/$defs/ReadStatement" },
+        { "$ref": "#/$defs/OpenStatement" },
+        { "$ref": "#/$defs/FoldStatement" },
+        { "$ref": "#/$defs/EditStatement" },
+        { "$ref": "#/$defs/CopyStatement" },
+        { "$ref": "#/$defs/MoveStatement" },
+        { "$ref": "#/$defs/SendStatement" },
+        { "$ref": "#/$defs/ExecStatement" },
+        { "$ref": "#/$defs/WorkStatement" },
+        { "$ref": "#/$defs/ForkStatement" },
+        { "$ref": "#/$defs/KillStatement" },
+        { "$ref": "#/$defs/PlanStatement" }
+    ],
+    "$defs": {
+        "TagSignal": {
+            "oneOf": [
+                { "type": "array", "items": { "type": "string" } },
+                { "type": "null" }
+            ]
+        },
+        "PathOrNull": {
+            "oneOf": [
+                { "$ref": "https://schemas.plurnk.dev/v0/ParsedPath.json" },
+                { "type": "null" }
+            ]
+        },
+        "LineMarkerOrNull": {
+            "oneOf": [
+                { "$ref": "https://schemas.plurnk.dev/v0/LineMarker.json" },
+                { "type": "null" }
+            ]
+        },
+        "MatcherBodyOrNull": {
+            "oneOf": [
+                { "$ref": "https://schemas.plurnk.dev/v0/MatcherBody.json" },
+                { "type": "null" }
+            ]
+        },
+        "SendBodyOrNull": {
+            "oneOf": [
+                { "$ref": "https://schemas.plurnk.dev/v0/SendBody.json" },
+                { "type": "null" }
+            ]
+        },
+        "ResourceSelectionOrNull": {
+            "oneOf": [
+                { "$ref": "https://schemas.plurnk.dev/v0/ResourceSelection.json" },
+                { "type": "null" }
+            ]
+        },
+        "PositionRef": {
+            "$ref": "https://schemas.plurnk.dev/v0/Position.json"
+        },
+        "FindStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "FIND" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/MatcherBodyOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "ReadStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "READ" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/MatcherBodyOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "OpenStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "OPEN" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "type": "null" },
+                "body": { "$ref": "#/$defs/MatcherBodyOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "FoldStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "FOLD" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "type": "null" },
+                "body": { "$ref": "#/$defs/MatcherBodyOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "EditStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "EDIT" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "type": ["string", "null"] },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "CopyStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "COPY" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/ResourceSelectionOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "MoveStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "MOVE" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/ResourceSelectionOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "SendStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "SEND" },
+                "suffix": { "type": "string" },
+                "signal": {
+                    "oneOf": [
+                        { "type": "number" },
+                        { "type": "null" }
+                    ]
+                },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/SendBodyOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "ExecStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "EXEC" },
+                "suffix": { "type": "string" },
+                "signal": { "type": ["string", "null"] },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "type": ["string", "null"] },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "PlanStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "PLAN" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "type": ["string", "null"] },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "KillStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "KILL" },
+                "suffix": { "type": "string" },
+                "signal": {
+                    "oneOf": [
+                        { "type": "number" },
+                        { "type": "null" }
+                    ]
+                },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "type": "null" },
+                "body": { "type": ["string", "null"] },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "WorkStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "WORK" },
+                "suffix": { "type": "string" },
+                "signal": {
+                    "oneOf": [
+                        { "type": "string", "minLength": 1 },
+                        { "type": "null" }
+                    ]
+                },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "type": "null" },
+                "body": { "type": "string", "minLength": 1 },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "ForkStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "FORK" },
+                "suffix": { "type": "string" },
+                "signal": {
+                    "oneOf": [
+                        { "type": "string", "minLength": 1 },
+                        { "type": "null" }
+                    ]
+                },
+                "target": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "type": "null" },
+                "body": { "type": "string", "minLength": 1 },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        }
+    }
+}

package/dist/schema/Position.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/Position.json",
+    "title": "Position",
+    "description": "A source point in parsed PLURNK input. Lines are 1-based; columns are 0-based Unicode code points. LF and CRLF delimit lines, while a lone CR occupies one column. The exact pair {line: 0, column: 0} is the sole unknown/degraded position.",
+    "type": "object",
+    "required": ["line", "column"],
+    "additionalProperties": false,
+    "properties": {
+        "line": { "type": "integer", "minimum": 0 },
+        "column": { "type": "integer", "minimum": 0 }
+    },
+    "if": {
+        "properties": { "line": { "const": 0 } },
+        "required": ["line"]
+    },
+    "then": {
+        "properties": { "column": { "const": 0 } }
+    }
+}

package/dist/schema/ProblemDetails.json

@@ -0,0 +1,51 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ProblemDetails.json",
+    "title": "ProblemDetails",
+    "description": "PLURNK operation failure using RFC 9457 Problem Details. Extension members are permitted so an owning boundary can add structured causal and recovery facts without inventing a second error envelope.",
+    "type": "object",
+    "required": ["type", "title", "status", "detail"],
+    "additionalProperties": true,
+    "properties": {
+        "type": {
+            "type": "string",
+            "pattern": "^[a-zA-Z][a-zA-Z0-9+.-]*:",
+            "description": "Absolute URI identifying the stable problem class."
+        },
+        "title": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Short, stable summary for this problem type."
+        },
+        "status": {
+            "type": "integer",
+            "minimum": 400,
+            "maximum": 599,
+            "description": "Operation status. It must equal the containing result status."
+        },
+        "detail": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Specific, causal explanation of this occurrence."
+        },
+        "instance": {
+            "type": "string",
+            "pattern": "^[a-zA-Z][a-zA-Z0-9+.-]*:",
+            "description": "Absolute URI identifying the failed durable operation, normally its log URI. Core adds it at persistence when a plugin cannot know the durable coordinate."
+        },
+        "stage": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable producer-owned stage at which the operation failed, when the operation has multiple independently recoverable stages."
+        },
+        "recovery": {
+            "type": "string",
+            "minLength": 1,
+            "description": "One generally valid next action. It is omitted when recovery depends on facts the producer does not know."
+        },
+        "retryable": {
+            "type": "boolean",
+            "description": "Whether the producer recommends automatically retrying the identical request."
+        }
+    }
+}

package/dist/schema/ProposalDisposition.json

@@ -0,0 +1,26 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ProposalDisposition.json",
+    "title": "ProposalDisposition",
+    "description": "The one core-owned settlement decision for a pending proposal. Client-owned proposals require an external resolution; loop-owned proposals carry the exact automatic resolution core applies.",
+    "oneOf": [
+        {
+            "type": "object",
+            "required": ["owner"],
+            "additionalProperties": false,
+            "properties": {
+                "owner": { "const": "client" }
+            }
+        },
+        {
+            "type": "object",
+            "required": ["owner", "decision"],
+            "additionalProperties": false,
+            "properties": {
+                "owner": { "const": "loop" },
+                "decision": { "enum": ["accept", "reject"] },
+                "outcome": { "type": "string", "minLength": 1 }
+            }
+        }
+    ]
+}

package/dist/schema/ProposalProjection.json

@@ -0,0 +1,44 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ProposalProjection.json",
+    "title": "ProposalProjection",
+    "description": "The runtime-neutral client-interface projection of one durable stopped-world proposal. Live delivery and reconnect discovery expose this same shape.",
+    "type": "object",
+    "required": [
+        "logEntryId",
+        "workerId",
+        "loopId",
+        "turnId",
+        "op",
+        "target",
+        "body",
+        "attrs",
+        "flags",
+        "staleClobberRisk",
+        "disposition"
+    ],
+    "additionalProperties": false,
+    "properties": {
+        "logEntryId": { "type": "integer", "minimum": 1 },
+        "workerId": { "type": "integer", "minimum": 1 },
+        "loopId": { "type": "integer", "minimum": 1 },
+        "turnId": { "type": "integer", "minimum": 1 },
+        "op": {
+            "enum": ["FIND", "READ", "EDIT", "COPY", "MOVE", "OPEN", "FOLD", "SEND", "EXEC", "WORK", "FORK", "KILL", "PLAN"]
+        },
+        "target": {
+            "type": "object",
+            "required": ["scheme", "pathname"],
+            "additionalProperties": false,
+            "properties": {
+                "scheme": { "type": ["string", "null"] },
+                "pathname": { "type": ["string", "null"] }
+            }
+        },
+        "body": { "type": "string" },
+        "attrs": { "type": "object", "additionalProperties": true },
+        "flags": { "$ref": "https://schemas.plurnk.dev/v0/LoopFlags.json" },
+        "staleClobberRisk": { "type": "boolean" },
+        "disposition": { "$ref": "https://schemas.plurnk.dev/v0/ProposalDisposition.json" }
+    }
+}

package/dist/schema/ProviderCost.json

@@ -0,0 +1,69 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://plurnk.dev/schema/ProviderCost.json",
+    "title": "ProviderCost",
+    "description": "Validated monetary evidence for one provider attempt. Unknown is never represented as zero.",
+    "oneOf": [
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "amount", "usdEquivalent", "source"],
+            "properties": {
+                "kind": { "const": "authoritative" },
+                "amount": { "$ref": "#/$defs/MonetaryAmount" },
+                "usdEquivalent": { "$ref": "#/$defs/DecimalAmount" },
+                "source": { "$ref": "#/$defs/NonEmptyString" }
+            }
+        },
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "usd", "source"],
+            "properties": {
+                "kind": { "const": "estimated" },
+                "usd": { "$ref": "#/$defs/DecimalAmount" },
+                "source": { "$ref": "#/$defs/NonEmptyString" }
+            }
+        },
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "source"],
+            "properties": {
+                "kind": { "const": "free" },
+                "source": { "$ref": "#/$defs/NonEmptyString" }
+            }
+        },
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "reason"],
+            "properties": {
+                "kind": { "const": "unknown" },
+                "reason": { "$ref": "#/$defs/NonEmptyString" }
+            }
+        }
+    ],
+    "$defs": {
+        "DecimalAmount": {
+            "type": "string",
+            "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"
+        },
+        "NonEmptyString": {
+            "type": "string",
+            "minLength": 1
+        },
+        "MonetaryAmount": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["amount", "currency"],
+            "properties": {
+                "amount": { "$ref": "#/$defs/DecimalAmount" },
+                "currency": {
+                    "type": "string",
+                    "pattern": "^[A-Z][A-Z0-9]{2,11}$"
+                }
+            }
+        }
+    }
+}

package/dist/schema/ResourceSelection.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ResourceSelection.json",
+    "title": "ResourceSelection",
+    "description": "A COPY/MOVE destination target and optional text scope. A target without a fragment selects the scheme's default channel; a fragment selects a named channel; lineMarker scopes the selected destination content.",
+    "type": "object",
+    "required": ["target", "lineMarker"],
+    "additionalProperties": false,
+    "properties": {
+        "target": {
+            "$ref": "https://schemas.plurnk.dev/v0/ParsedPath.json"
+        },
+        "lineMarker": {
+            "oneOf": [
+                { "$ref": "https://schemas.plurnk.dev/v0/LineMarker.json" },
+                { "type": "null" }
+            ]
+        }
+    }
+}

package/dist/schema/SendBody.json

@@ -0,0 +1,13 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/SendBody.json",
+    "title": "SendBody",
+    "description": "Parsed body of a SEND statement. `raw` is the literal body text; `json` is the best-effort `JSON.parse(raw)` result, or null when the body isn't valid JSON.",
+    "type": "object",
+    "required": ["raw", "json"],
+    "additionalProperties": false,
+    "properties": {
+        "raw": { "type": "string" },
+        "json": true
+    }
+}

package/dist/schema/TextRegion.json

@@ -0,0 +1,31 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/TextRegion.json",
+    "title": "TextRegion",
+    "description": "A contiguous region of text. Lines and Unicode code-point columns are 1-based; the start is included and the end is excluded.",
+    "type": "object",
+    "required": ["startLine", "startColumn", "endLine", "endColumn"],
+    "additionalProperties": false,
+    "properties": {
+        "startLine": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+        },
+        "startColumn": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+        },
+        "endLine": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+        },
+        "endColumn": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+        }
+    }
+}

package/dist/src/AstBuilder.d.ts

@@ -0,0 +1,24 @@
+import type { ClientStatement, ResourceSelection, ParsedPath, PlurnkStatement, Position } from "./types.ts";
+import type { ClientStatementContext, StatementContext, MidStatementContext } from "./generated/plurnkParser.ts";
+import { PlanStatementContext, SendStatementContext } from "./generated/plurnkParser.ts";
+declare module "xpath" {
+    function parse(expression: string): unknown;
+}
+export default class AstBuilder {
+    #private;
+    static build(ctx: StatementContext | MidStatementContext | PlanStatementContext | SendStatementContext): PlurnkStatement;
+    static buildClient(ctx: ClientStatementContext): ClientStatement;
+    /**
+     * Parse a COPY/MOVE body into its destination target and optional trailing
+     * scope. The scope is adjacent to the destination it selects:
+     * `destination.txt<12,5,12,5>`.
+     */
+    static parseResourceSelection(raw: string, pos?: Position): ResourceSelection | null;
+    /**
+     * 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

@@ -0,0 +1 @@
+{"version":3,"file":"AstBuilder.d.ts","sourceRoot":"","sources":["../../src/AstBuilder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGR,eAAe,EAaf,iBAAiB,EACjB,UAAU,EAGV,eAAe,EACf,QAAQ,EAMX,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAER,sBAAsB,EAgBtB,gBAAgB,EAChB,mBAAmB,EAGtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAGH,oBAAoB,EACpB,oBAAoB,EAIvB,MAAM,6BAA6B,CAAC;AAMrC,OAAO,QAAQ,OAAO,CAAC;IACnB,SAAgB,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CACtD;AASD,MAAM,CAAC,OAAO,OAAO,UAAU;;IAK3B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,mBAAmB,GAAG,oBAAoB,GAAG,oBAAoB,GAAG,eAAe,CA4BvH;IAmBD,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,sBAAsB,GAAG,eAAe,CAK/D;IAmVD;;;;OAIG;IACH,MAAM,CAAC,sBAAsB,CACzB,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,QAAiC,GACvC,iBAAiB,GAAG,IAAI,CAW1B;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,QAAiC,GAAG,UAAU,GAAG,IAAI,CAoCvF;CAuHJ"}