@plurnk/plurnk-contracts 1.4.0

package/dist/schema/EntryReadResult.json

@@ -0,0 +1,101 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/EntryReadResult.json",
+    "title": "EntryReadResult",
+    "description": "The runtime-neutral result of reading one client-visible entry, either completely or as one channel suffix.",
+    "oneOf": [
+        {
+            "type": "object",
+            "required": ["status", "entry"],
+            "additionalProperties": false,
+            "properties": {
+                "status": { "const": 200 },
+                "entry": { "$ref": "#/$defs/entry" }
+            }
+        },
+        {
+            "type": "object",
+            "required": ["status", "problem", "entry"],
+            "additionalProperties": false,
+            "properties": {
+                "status": {
+                    "type": "integer",
+                    "minimum": 400,
+                    "maximum": 599
+                },
+                "problem": { "$ref": "https://schemas.plurnk.dev/v0/ProblemDetails.json" },
+                "entry": { "type": "null" }
+            }
+        }
+    ],
+    "$defs": {
+        "entry": {
+            "title": "ClientEntry",
+            "type": "object",
+            "required": ["entryId", "target", "channels", "tags"],
+            "additionalProperties": false,
+            "properties": {
+                "entryId": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 9007199254740991
+                },
+                "target": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "channels": {
+                    "type": "object",
+                    "propertyNames": { "minLength": 1 },
+                    "additionalProperties": { "$ref": "#/$defs/channel" }
+                },
+                "tags": {
+                    "type": "array",
+                    "uniqueItems": true,
+                    "items": {
+                        "type": "string",
+                        "minLength": 1
+                    }
+                }
+            }
+        },
+        "channel": {
+            "title": "ClientEntryChannel",
+            "type": "object",
+            "required": [
+                "content",
+                "contentOffset",
+                "contentLength",
+                "mimetype",
+                "tokens",
+                "state"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "content": { "type": "string" },
+                "contentOffset": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                },
+                "contentLength": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                },
+                "mimetype": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "tokens": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                },
+                "state": {
+                    "enum": ["static", "active", "closed", "errored"]
+                }
+            }
+        }
+    }
+}

package/dist/schema/LineMarker.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/LineMarker.json",
+    "title": "LineMarker",
+    "description": "The ordered numeric components parsed from a `<scope>` slot. AstBuilder converts each lexical number to a JavaScript number; the operation owner assigns arity and meaning, including text coordinates, result positions, timing, mutation anchors, and an optional leading semantic threshold.",
+    "type": "object",
+    "required": ["marks"],
+    "additionalProperties": false,
+    "properties": {
+        "marks": {
+            "type": "array",
+            "items": { "type": "number" },
+            "minItems": 1
+        }
+    }
+}

package/dist/schema/LoopFlags.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/LoopFlags.json",
+    "title": "LoopFlags",
+    "description": "The complete effective policy posture of one model loop. Persisted partial objects are expanded to this shape by the runtime owner before use or projection.",
+    "type": "object",
+    "required": ["mode", "auto", "noWeb", "noInteraction", "noProposals"],
+    "additionalProperties": false,
+    "properties": {
+        "mode": { "enum": ["ask", "act"] },
+        "auto": { "type": "boolean" },
+        "noWeb": { "type": "boolean" },
+        "noInteraction": { "type": "boolean" },
+        "noProposals": { "type": "boolean" }
+    }
+}

package/dist/schema/MatcherBody.json

@@ -0,0 +1,84 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/MatcherBody.json",
+    "title": "MatcherBody",
+    "description": "Parsed body of a FIND/READ/OPEN/FOLD statement, discriminated on `dialect`. The dialect is determined by the body's leading characters (`//` xpath, `/` regex, `$` jsonpath, `~` semantic, `@` graph, else glob). The regex variant carries pattern and flags split out of the `/pattern/flags` literal; every variant remains JSON-serializable.",
+    "oneOf": [
+        { "$ref": "#/$defs/XPathBody" },
+        { "$ref": "#/$defs/RegexBody" },
+        { "$ref": "#/$defs/JsonPathBody" },
+        { "$ref": "#/$defs/SemanticBody" },
+        { "$ref": "#/$defs/GraphBody" },
+        { "$ref": "#/$defs/GlobBody" }
+    ],
+    "$defs": {
+        "XPathBody": {
+            "title": "XPathBody",
+            "description": "XPath 1.0 expression. Validated at parse time via the xpath library.",
+            "type": "object",
+            "required": ["dialect", "raw"],
+            "additionalProperties": false,
+            "properties": {
+                "dialect": { "const": "xpath" },
+                "raw": { "type": "string", "minLength": 2 }
+            }
+        },
+        "RegexBody": {
+            "title": "RegexBody",
+            "description": "ECMAScript regex literal `/pattern/flags`. Escape a literal delimiter as `\\/`. Pattern and flags are split out for direct use. `raw` preserves the literal form for round-tripping.",
+            "type": "object",
+            "required": ["dialect", "raw", "pattern", "flags"],
+            "additionalProperties": false,
+            "properties": {
+                "dialect": { "const": "regex" },
+                "raw": { "type": "string", "minLength": 2 },
+                "pattern": { "type": "string" },
+                "flags": { "type": "string" }
+            }
+        },
+        "JsonPathBody": {
+            "title": "JsonPathBody",
+            "description": "RFC 9535 JSONPath expression. Compiled at parse time with json-p3, the same engine used for runtime matching.",
+            "type": "object",
+            "required": ["dialect", "raw"],
+            "additionalProperties": false,
+            "properties": {
+                "dialect": { "const": "jsonpath" },
+                "raw": { "type": "string", "minLength": 1 }
+            }
+        },
+        "SemanticBody": {
+            "title": "SemanticBody",
+            "description": "Semantic similarity query. Body is `~phrase`: natural language after the tilde, with no parse step. Similarity thresholds and result ranges belong to the statement's scope; resolution happens service-side through the configured embedding implementation.",
+            "type": "object",
+            "required": ["dialect", "raw"],
+            "additionalProperties": false,
+            "properties": {
+                "dialect": { "const": "semantic" },
+                "raw": { "type": "string", "minLength": 1 }
+            }
+        },
+        "GraphBody": {
+            "title": "GraphBody",
+            "description": "Code-graph reference query. Body is `@symbol` for a neighborhood, `@<symbol` for inbound references, or `@>symbol` for outbound references. Resolution happens service-side through the symbol index; no parse step occurs in the language parser.",
+            "type": "object",
+            "required": ["dialect", "raw"],
+            "additionalProperties": false,
+            "properties": {
+                "dialect": { "const": "graph" },
+                "raw": { "type": "string", "minLength": 1 }
+            }
+        },
+        "GlobBody": {
+            "title": "GlobBody",
+            "description": "Pattern with no dialect prefix; treated as a glob/literal match.",
+            "type": "object",
+            "required": ["dialect", "raw"],
+            "additionalProperties": false,
+            "properties": {
+                "dialect": { "const": "glob" },
+                "raw": { "type": "string" }
+            }
+        }
+    }
+}

package/dist/schema/Notice.json

@@ -0,0 +1,67 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/Notice.json",
+    "title": "Notice",
+    "description": "A transient, nonterminal observation for clients and the next model packet. A Notice is never operation-failure truth and cannot determine durable history, lifecycle, scheduling, or recovery. Producers use the open `source` + `kind` discriminator; clients render the producer-owned `level` without inferring semantics from kind names.",
+    "type": "object",
+    "required": ["source", "kind", "level"],
+    "additionalProperties": true,
+    "properties": {
+        "source": {
+            "type": "string",
+            "pattern": "^[a-z]+(:[a-z][a-z0-9-]*)?$",
+            "description": "Producer identifier. Top-level for self-contained subsystems; colon-namespaced for parameterized producers such as `provider:openai` or `exec:search`."
+        },
+        "kind": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Open discriminator within a source. Examples include `grammar_unenforced`, `embed_progress`, `search_progress`, and `turn_awaiting_model`."
+        },
+        "level": {
+            "enum": ["error", "warn", "info"],
+            "description": "Display severity set by the producer. It does not make the Notice a durable operation result."
+        },
+        "message": {
+            "type": ["string", "null"],
+            "description": "Optional terse, factual display message."
+        },
+        "position": {
+            "oneOf": [
+                { "$ref": "#/$defs/ContentOffset" },
+                { "$ref": "#/$defs/LogCoordinate" },
+                { "type": "null" }
+            ],
+            "description": "Optional typed position for an observation. ContentOffset points into model output; LogCoordinate points at a durable log row without replacing it."
+        }
+    },
+    "$defs": {
+        "ContentOffset": {
+            "description": "A point in model output using the parser-point convention: 1-based line and 0-based Unicode-code-point column. Absence or a null Notice.position represents an unknown location.",
+            "type": "object",
+            "required": ["type", "line", "column"],
+            "additionalProperties": false,
+            "properties": {
+                "type": { "const": "content-offset" },
+                "line": { "type": "integer", "minimum": 1 },
+                "column": { "type": "integer", "minimum": 0 }
+            }
+        },
+        "LogCoordinate": {
+            "type": "object",
+            "required": ["type", "coordinate"],
+            "additionalProperties": false,
+            "properties": {
+                "type": { "const": "log-coordinate" },
+                "coordinate": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Log row identity, typically `log:///<loop>/<turn>/<sequence>`."
+                },
+                "op": {
+                    "type": "string",
+                    "description": "Optional op token (FIND/READ/EDIT/...) at the coordinate, for human-readable rendering."
+                }
+            }
+        }
+    }
+}

package/dist/schema/OperationResult.json

@@ -0,0 +1,44 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/OperationResult.json",
+    "title": "OperationResult",
+    "description": "Universal PLURNK operation result. Producer-owned metadata is open, but failures always carry one RFC 9457 Problem Details object and never a parallel error field.",
+    "type": "object",
+    "required": ["status"],
+    "additionalProperties": true,
+    "properties": {
+        "status": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 599
+        },
+        "problem": {
+            "$ref": "https://schemas.plurnk.dev/v0/ProblemDetails.json"
+        },
+        "error": false
+    },
+    "oneOf": [
+        {
+            "properties": {
+                "status": {
+                    "type": "integer",
+                    "minimum": 100,
+                    "maximum": 399
+                }
+            },
+            "not": {
+                "required": ["problem"]
+            }
+        },
+        {
+            "required": ["problem"],
+            "properties": {
+                "status": {
+                    "type": "integer",
+                    "minimum": 400,
+                    "maximum": 599
+                }
+            }
+        }
+    ]
+}

package/dist/schema/ParsedPath.json

@@ -0,0 +1,64 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ParsedPath.json",
+    "title": "ParsedPath",
+    "description": "A parsed target slot from a plurnk statement. Discriminated on `kind`: a bare local path or a WHATWG-decomposed URL. Targets carry an exact address or a path glob; content matching belongs in the statement body.",
+    "oneOf": [
+        { "$ref": "#/$defs/LocalPath" },
+        { "$ref": "#/$defs/UrlPath" }
+    ],
+    "$defs": {
+        "LocalPath": {
+            "title": "LocalPath",
+            "description": "A bare local path with no `scheme://` prefix. The raw string is stored verbatim; resolution is the runtime's job.",
+            "type": "object",
+            "required": ["kind", "raw"],
+            "additionalProperties": false,
+            "properties": {
+                "kind": { "const": "local" },
+                "raw": { "type": "string" }
+            }
+        },
+        "UrlPath": {
+            "title": "UrlPath",
+            "description": "A path with a `scheme://` prefix, fully decomposed via WHATWG URL.",
+            "type": "object",
+            "required": [
+                "kind", "raw", "scheme",
+                "username", "password",
+                "hostname", "port",
+                "pathname", "query", "fragment"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "kind": { "const": "url" },
+                "raw": { "type": "string" },
+                "scheme": { "type": "string", "minLength": 1 },
+                "username": { "type": ["string", "null"] },
+                "password": { "type": ["string", "null"] },
+                "hostname": { "type": ["string", "null"] },
+                "port": {
+                    "type": ["integer", "null"],
+                    "minimum": 0,
+                    "maximum": 65535
+                },
+                "pathname": { "type": "string" },
+                "query": {
+                    "description": "Canonical serialized WHATWG query component without the leading `?`. Null means no query; the empty string means an explicit empty query (`?`). Ordering, duplicate names, and encoded spelling are preserved.",
+                    "type": ["string", "null"]
+                },
+                "fragment": { "type": ["string", "null"] },
+                "headers": {
+                    "description": "Trailing `{key: value}` request-metadata blocks removed before WHATWG decomposition and preserved as ordered pairs. Order and duplicate names survive; the addressed scheme owns their meaning. Absent when no block was supplied.",
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "minItems": 2,
+                        "maxItems": 2
+                    }
+                }
+            }
+        }
+    }
+}