@plurnk/plurnk-grammar 0.1.0 → 0.2.0

package/schema/PlurnkStatement.json

@@ -0,0 +1,183 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/PlurnkStatement.json",
+    "title": "PlurnkStatement",
+    "description": "The parsed AST of one plurnk statement. Discriminated on `op`. SEND and EXEC have no `<L>` slot — `lineMarker` is always null for those. Body shape varies per op: matcher dialect for FIND/READ/SHOW/HIDE, raw string for EDIT/EXEC, ParsedPath for COPY/MOVE, SendBody for SEND.",
+    "oneOf": [
+        { "$ref": "#/$defs/FindStatement" },
+        { "$ref": "#/$defs/ReadStatement" },
+        { "$ref": "#/$defs/ShowStatement" },
+        { "$ref": "#/$defs/HideStatement" },
+        { "$ref": "#/$defs/EditStatement" },
+        { "$ref": "#/$defs/CopyStatement" },
+        { "$ref": "#/$defs/MoveStatement" },
+        { "$ref": "#/$defs/SendStatement" },
+        { "$ref": "#/$defs/ExecStatement" }
+    ],
+    "$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" }
+            ]
+        },
+        "PositionRef": {
+            "$ref": "https://schemas.plurnk.dev/v0/Position.json"
+        },
+        "FindStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "path", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "FIND" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "path": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/MatcherBodyOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "ReadStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "path", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "READ" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "path": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/MatcherBodyOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "ShowStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "path", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "SHOW" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "path": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/MatcherBodyOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "HideStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "path", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "HIDE" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "path": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/MatcherBodyOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "EditStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "path", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "EDIT" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "path": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "type": ["string", "null"] },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "CopyStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "path", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "COPY" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "path": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/PathOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "MoveStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "path", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "MOVE" },
+                "suffix": { "type": "string" },
+                "signal": { "$ref": "#/$defs/TagSignal" },
+                "path": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },
+                "body": { "$ref": "#/$defs/PathOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "SendStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "path", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "SEND" },
+                "suffix": { "type": "string" },
+                "signal": {
+                    "oneOf": [
+                        { "type": "number" },
+                        { "type": "null" }
+                    ]
+                },
+                "path": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "type": "null" },
+                "body": { "$ref": "#/$defs/SendBodyOrNull" },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        },
+        "ExecStatement": {
+            "type": "object",
+            "required": ["op", "suffix", "signal", "path", "lineMarker", "body", "position"],
+            "additionalProperties": false,
+            "properties": {
+                "op": { "const": "EXEC" },
+                "suffix": { "type": "string" },
+                "signal": { "type": ["string", "null"] },
+                "path": { "$ref": "#/$defs/PathOrNull" },
+                "lineMarker": { "type": "null" },
+                "body": { "type": ["string", "null"] },
+                "position": { "$ref": "#/$defs/PositionRef" }
+            }
+        }
+    }
+}

package/schema/Position.json

@@ -0,0 +1,13 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/Position.json",
+    "title": "Position",
+    "description": "A line/column position in a parsed plurnk document. ANTLR emits 1-based lines and 0-based columns; degraded positions may use 0 for both when the source token's location is unknown.",
+    "type": "object",
+    "required": ["line", "column"],
+    "additionalProperties": false,
+    "properties": {
+        "line": { "type": "integer", "minimum": 0 },
+        "column": { "type": "integer", "minimum": 0 }
+    }
+}

package/schema/ProviderDeclaration.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ProviderDeclaration.json",
+    "title": "ProviderDeclaration",
+    "description": "Declaration of the active provider for an agent. The grammar package owns these four fields; auth/connection config lives in the agent repo.",
+    "type": "object",
+    "required": ["provider", "family", "model", "contextSize", "currency"],
+    "additionalProperties": false,
+    "properties": {
+        "provider": { "type": "string", "minLength": 1, "description": "API vendor identifier (e.g. \"anthropic\", \"openai\", \"google\", \"local\")." },
+        "family": { "type": "string", "minLength": 1, "description": "Model family (e.g. \"claude\", \"gpt\", \"gemini\", \"llama\")." },
+        "model": { "type": "string", "minLength": 1, "description": "Specific model id (e.g. \"claude-opus-4-7\")." },
+        "contextSize": { "type": "integer", "minimum": 1, "description": "Total context window in tokens." },
+        "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 code; the unit `cost_pico` is denominated in." }
+    }
+}

package/schema/Run.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/Run.json",
+    "title": "Run",
+    "description": "A stretch of work within a session. Forkable via parent_run_id. Owns per-run logs and visibility state.",
+    "type": "object",
+    "required": ["id", "version", "session_id", "created_at", "parent_run_id", "cost_pico"],
+    "additionalProperties": false,
+    "properties": {
+        "id": { "type": "integer", "minimum": 1 },
+        "version": { "type": "integer", "minimum": 0 },
+        "session_id": { "type": "integer", "minimum": 1 },
+        "created_at": { "type": "string", "format": "date-time" },
+        "parent_run_id": {
+            "type": ["integer", "null"],
+            "minimum": 1,
+            "description": "FK to parent run when this is a fork; null for the trunk run."
+        },
+        "cost_pico": { "type": "integer", "minimum": 0, "description": "Cumulative cost across this run's turns, in pico-units of the active provider's currency." }
+    }
+}

package/schema/SchemeRegistration.json

@@ -0,0 +1,31 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/SchemeRegistration.json",
+    "title": "SchemeRegistration",
+    "description": "A scheme entry in the agent's scheme registry. Defines what `<name>://` resolves to and how it's accessible.",
+    "type": "object",
+    "required": ["name", "model_visible", "category", "default_scope", "default_channel", "writable_by", "volatile", "handler"],
+    "additionalProperties": false,
+    "properties": {
+        "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9+.\\-]*$",
+            "description": "Scheme name without `://`. Matches the URL scheme character class."
+        },
+        "model_visible": { "type": "boolean" },
+        "category": { "type": "string", "minLength": 1 },
+        "default_scope": { "enum": ["agent", "session"] },
+        "default_channel": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_-]*$",
+            "description": "Channel name selected when an op against this scheme has no fragment. Conventionally `body`; exec schemes typically declare `stdout`."
+        },
+        "writable_by": {
+            "type": "array",
+            "items": { "enum": ["model", "client", "system", "plugin"] },
+            "uniqueItems": true
+        },
+        "volatile": { "type": "boolean" },
+        "handler": { "type": ["string", "null"] }
+    }
+}

package/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/schema/Session.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/Session.json",
+    "title": "Session",
+    "description": "A durable user-named workspace. Never ends except by explicit removal. Shares session-scoped entries and any scheme-registry additions across all its runs.",
+    "type": "object",
+    "required": ["id", "version", "name", "created_at", "cost_pico", "scheme_registry_additions"],
+    "additionalProperties": false,
+    "properties": {
+        "id": { "type": "integer", "minimum": 1 },
+        "version": { "type": "integer", "minimum": 0 },
+        "name": { "type": "string", "minLength": 1, "description": "Unique within the agent. Default form: `{modelAlias}-{unixtime}` until renamed." },
+        "created_at": { "type": "string", "format": "date-time" },
+        "cost_pico": { "type": "integer", "minimum": 0, "description": "Cumulative cost across this session's runs." },
+        "scheme_registry_additions": {
+            "type": "array",
+            "items": { "$ref": "https://schemas.plurnk.dev/v0/SchemeRegistration.json" }
+        }
+    }
+}

package/schema/Turn.json

@@ -0,0 +1,30 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/Turn.json",
+    "title": "Turn",
+    "description": "The leaf of the envelope hierarchy. One model-provider exchange. Persists the full packet plus provider-returned usage and the turn-level status.",
+    "type": "object",
+    "required": ["id", "version", "loop_id", "sequence", "timestamp", "status", "usage", "packet"],
+    "additionalProperties": false,
+    "properties": {
+        "id": { "type": "integer", "minimum": 1 },
+        "version": { "type": "integer", "minimum": 0 },
+        "loop_id": { "type": "integer", "minimum": 1 },
+        "sequence": { "type": "integer", "minimum": 1, "description": "1-based within the loop; resets at each new loop." },
+        "timestamp": { "type": "string", "format": "date-time" },
+        "status": { "type": "integer", "minimum": 100, "maximum": 599 },
+        "usage": {
+            "type": "object",
+            "description": "Provider-returned token counts and computed cost.",
+            "required": ["prompt", "completion", "cached", "cost_pico"],
+            "additionalProperties": false,
+            "properties": {
+                "prompt": { "type": "integer", "minimum": 0 },
+                "completion": { "type": "integer", "minimum": 0 },
+                "cached": { "type": "integer", "minimum": 0 },
+                "cost_pico": { "type": "integer", "minimum": 0, "description": "Per-turn cost in pico-units of the active provider's currency." }
+            }
+        },
+        "packet": { "$ref": "https://schemas.plurnk.dev/v0/Packet.json" }
+    }
+}

package/schema/Visibility.json

@@ -0,0 +1,17 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/Visibility.json",
+    "title": "Visibility",
+    "description": "Per-run, per-channel visibility row. Pairs an (entry, channel) with an `indexed` boolean — true means the channel appears in the run's Index (visible to the model); false means Archive (out of working memory but addressable). Allows fine-grained promotion (e.g. exec://run-tests#stdout indexed while #stderr archived).",
+    "type": "object",
+    "required": ["entry_id", "channel", "indexed"],
+    "additionalProperties": false,
+    "properties": {
+        "entry_id": { "type": "integer", "minimum": 1 },
+        "channel": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_-]*$"
+        },
+        "indexed": { "type": "boolean" }
+    }
+}