@plurnk/plurnk-contracts 1.24.0 → 1.26.0

package/SPEC.md

@@ -17,10 +17,10 @@ runtime-neutral wire envelopes; `@plurnk/plurnk-parser` implements the language
 | Client-owned interaction contract                                               | `ClientInteractionRequest`, `ClientInteractionProjection`, `ClientInteractionResolution` |
 | Client capability presentation                                                 | `ClientDisplayCapabilities`                         |
 | Exterior adapter application calls                                             | `ApplicationPort`                                   |
-| Workspace MCP configuration                                                    | `McpServerDefinition`, `McpServerOptions`, `McpConfigurationOverlay` |
+| Workspace MCP configuration                                                    | `McpServerDefinition`, `McpOAuth` |
 | Worker Agent Skills definition                                                 | `SkillDefinition` |
 | Worker outbound A2A agent definition                                           | `A2aAgentDefinition` |
-| Worker Functionality lifecycle projections (family-neutral)                     | `FunctionalityCandidate`, `FunctionalityDiscoverQuery`, `FunctionalityDiscoverResult`, `FunctionalityDefinitionState`, `FunctionalityListResult`, `FunctionalityMutationResult` |
+| Worker Functionality lifecycle projections (family-neutral)                     | `FunctionalityProvenance`, `FunctionalityCandidate`, `FunctionalityDiscoverQuery`, `FunctionalityDiscoverResult`, `FunctionalityDefinitionState`, `FunctionalityListResult`, `FunctionalityMutationResult` |
 | AG-UI discovery, client accounting, and shared conformance specimens           | `AguiDiscovery`, `AguiClientConformance`, `AguiConformanceKit` |
 | JSON Schemas                                                                    | `@plurnk/plurnk-contracts/schema/*.json`            |
 | Generated JSON result rendering                                                 | `renderJsonResult`                                  |
@@ -178,7 +178,7 @@ vocabulary of `proposals`. Capability admission precedes effect
 classification and proposal settlement.
 
 §effort-wire `Effort` is exactly `off | adaptive | low |
-medium | high`. The schema owns this shared wire vocabulary. Providers own the
+medium | high | xhigh | max`. The schema owns this shared wire vocabulary. Providers own the
 supported subset and native projection for a selected route; core owns the
 durable worker value.
 
@@ -300,10 +300,11 @@ fence only as the nesting form. Every producer of a statement — the parser, a
 `/look`, a client's tab-completion — writes `PLURNK_FENCE` rather than its own literal
 (plurnk/plurnk#92).
 
-§naked-operation **A native operation's name alone on a line opens it without a fence.** A
-column-zero line outside any block that is exactly an operation's name, with nothing but
-horizontal whitespace after it, opens that operation as if it were fenced with the taught three
-backticks: no target, no modifiers, and a body that runs to a line that is exactly the name
+§naked-operation **A native name with only an optional aside opens without a fence.** A
+column-zero line outside any block containing a native operation's name and at most one complete
+`<!-- aside -->`, with only horizontal whitespace otherwise, opens that operation as if it were
+fenced with the taught three backticks. The aside retains its ordinary meaning: no target or
+modifiers are inferred. Its body runs to a line that is exactly the name
 again, to the next heading ({§fence-heading-in-body}), or to the end of the turn. A fence inside
 naming nothing known is body; the block expects no closer, so its body is never cut
 back ({§closer-fallback}). A naked `KILL` alone holds every fence inside it as text ({§naked-kill}). It runs, and one warning-severity receipt follows its statement —
@@ -312,10 +313,10 @@ operation: a naked `WAIT` parks, a naked `NOTE` takes its text, a naked `READ` m
 missing-target refusal. A closer the author wrote anyway is still not body: when the body's last line is
 a bare backtick fence that no other fence line in the body pairs with (an odd count of fence lines), that
 line is the block's closer and leaves the body, so `KILL`, then the answer, then a closing fence delivers
-the answer alone. Only the bare name qualifies; a name with anything else on its line is
-the unfenced form and still refuses ({§unfenced-operation}), executors are runtimes rather than
-operations, and reasoning is never read this way. In 9,196 recorded emissions, all 48 naked
-`KILL` lines were followed by the deliverable.
+the answer alone. An aside-bearing name inside a body is not a closer. An incomplete or repeated
+aside, an operand, or other heading text does not qualify and remains the unfenced form
+({§unfenced-operation}). Executors are runtimes rather than operations, and reasoning is never
+read this way.
 
 §fence-heading-in-body Outside a complete nested block ({§balanced-fences}), a fence
 line of three or more backticks and a name that is a native operation or a known executor
@@ -458,15 +459,11 @@ operations the author wrote than the best repaired reading, the repaired reading
 inner fence keep what followed it (the qflash run192, run90 and run210 deliverables regain their last
 sections), one echoed transcript (glm run155) runs one more operation, and none loses one.
 
-§naked-kill **A naked KILL is the whole rest of the turn.** A parameterless `KILL` opened by its
-name alone ({§naked-operation}) is a completion, and nothing can follow a completion: every fenced
+§naked-kill **A naked KILL is the whole rest of the turn.** A parameterless `KILL` opened without
+a fence ({§naked-operation}), with or without an aside, is a completion: every fenced
 block inside it, a native operation heading included, is text the deliverable shows, exactly as
 inside a fenced KILL ({§terminal-kill}), and the block ends only at its name alone on a line or at
-the end of the input. No operation the deliverable shows runs. In the rtx5070 demo
-`demo-show-dont-run-sJU8zO` the model, asked to show a deletion without doing it, answered with a
-naked `KILL` whose deliverable quoted ```` ```KILL (notes.md) ````; read as a heading that ended
-the deliverable, the quoted KILL ran and deleted the file. The fenced form of the same answer had
-already read as quotation; this rule makes the two forms one.
+the end of the input. No operation the deliverable shows runs.
 
 §pairing-witness **Witnesses.**
 
@@ -616,10 +613,7 @@ its slots, and `parameter` tags around the content are debris, as are a copied f
 (`{"lines":6}`) under the heading, a `comment` attribute (the aside), and `<｜｜DSML｜｜tool_calls>`
 spelled without spaces. An executor's unknown parameter is one of its options, `[{"maxTokens":
 "2500"}]`, for its owner to accept or refuse; `bash` names `sh` when `sh` is the registered shell.
-Of 69 distinct recorded emissions carrying DSML markup (the 11,500 distinct emissions recorded
-through run429), 60 read this way and 9 draw the {§native-tool-call-receipt}: a bare
-`<｜｜DSML｜｜ calls>` with nothing inside, and calls whose native operation carries a parameter
-plurnk has no slot for.
+Calls that cannot be mapped draw {§native-tool-call-receipt}.
 Qwen's own shapes read the same way: a flat JSON call whose operation is the value
 of an `op`, `action` or `cmd` key in any case (`{"op": "READ", "path": …, "range": …}`),
 an XML element named by the operation (`<NOTE>…</NOTE>`, `<FIND (path) <1,3></FIND>`,
@@ -634,17 +628,17 @@ unknown name or parameter, or a FIND, READ, EDIT, COPY or MOVE naming no target,
 whole emission as it was. An emission that already yields an operation is never
 rewritten. No diagnostic, notice or teaching mentions a successful reading (#760).
 
-§native-tool-call-receipt **Markup that was not read is named.** When an emission yields no
-operation and carries native tool-call markup that could not be read, the parse reports one
-hard diagnostic at the markup, naming it and the fenced form that runs — `` `<tool_call>` is
-tool-call markup, which plurnk does not run, so nothing ran. An operation is a fenced block:
-three backticks and `READ (django/forms/widgets.py)` on the opening line. `` The form names
-the operation and target the markup itself names where it names them (`sh` for a shell
-command, `NOTE` for a note or narration), and otherwise the generic "the operation with its target,
-such as `READ (path)`". The model believes it
-acted; silence would let it wait on a result that never comes. Of 107 distinct recorded
-no-operation qflash emissions carrying call-like markup, 63 read under {§native-tool-calls}, 42 draw
-this receipt, and 2, a bare JSON object of narration with no tool-call marker, draw neither.
+Bare `invoke` elements use the same slots as wrapped calls. A complete JSON object
+inside an invoke supplies arguments when no explicit parameter elements are
+present; parameter bodies remain literal. Unknown native-operation arguments
+are not guessed.
+
+§native-tool-call-receipt **Unexecuted native markup draws a warning.** After exact
+recovery, the first remaining native-call block in outside text receives one
+warning naming its markup and the fenced form. It does not invalidate real OPs
+beside it, become an operation, or independently earn a strike. A turn with no
+operation follows {§empty-turn}. Quoted examples and operation bodies are not
+attempted calls. Outside text remains unchanged evidence under {§outside-text}.
 
 §empty-section Both the compact bodyless form and an empty multiline block
 normalize optional bodies to null. Closing fences are conventional, never required
@@ -808,17 +802,22 @@ in ordinary log token accounting and model-driven curation; prior notes are not
 automatically hidden. A NOTE-only turn does not request completion; ordinary
 repetition and strike rules still apply.
 
-§reasoning-notes NOTE is the only operation admitted from exposed provider
-reasoning. The shared fence parser selects line-leading NOTE statements in a
-quotation-preserving reasoning context: other backtick or tilde code blocks are
-opaque, and operation-heading recovery cannot escape them. Blockquoted and inline
-examples are not headings. Program parsing is unchanged; other reasoned operations
-never execute.
-Selected notes precede the content program in the admitted turn and use the
-ordinary dispatcher, persistence and log projection. Reasoning bytes and content
-bytes remain separate, unchanged forensic sources. Rejected or superseded
-provider attempts cannot commit notes. Non-thinking models use NOTE in their
-ordinary program. No task inventory is inferred from notes or lifecycle prose.
+§reasoning-operations The shared fence parser admits complete, line-leading NOTE,
+FIND and READ statements from exposed provider reasoning. Admission is part of
+the language, not an optional compatibility mode. Other backtick or tilde
+code blocks are opaque; heading and missing-closer recovery cannot escape them or
+complete an unfinished reasoning operation. Blockquoted and inline examples are
+not headings. Other reasoned operations never execute.
+
+Operations are admitted only after the provider response completes; their
+presence never interrupts generation. Selected operations precede the content
+program, in source order without deduplication, and use ordinary dispatch,
+permissions, persistence and log
+projection. FIND/READ count as operational work for admission and continuation;
+NOTE alone does not rescue an empty or inadmissible content program. Reasoning
+and content remain separate, unchanged forensic sources. Rejected or superseded
+provider attempts execute none of their operations. All three operations remain
+available in the ordinary program; no task inventory is inferred from reasoning.
 
 §exec-executor-slot The fence name selects the executor directly: for example,
 `python3 (tools/report.py)` or `gitea (issue_list)` on the opening fence line.
@@ -964,8 +963,9 @@ Mutation semantics:
 | KILL | Status of deletion or termination                                                 |
 | NOTE / WAIT | Literal memory or wait explanation                              |
 
-§find-result-unit For FIND, authored target shape fixes the paginated result
-unit. An exact target with a matcher pages flat match locations; a glob or
+§find-result-unit For FIND, target selection fixes the paginated result
+unit after scheme address resolution ({§entry-address-resolution}). An exact
+resource target with a matcher pages flat match locations; a glob or
 folder target, and every matcher-less FIND, pages resources. Resolving a glob to
 one resource does not make it exact. The same `<N>`, inclusive `<N,M>`,
 configured markerless first page ({§markerless-first-page}), and explicit-all
@@ -1185,11 +1185,11 @@ operation receives empty-turn recovery, not successful completion ({§empty-turn
 
 | Intent | Nominal status | Meaning |
 |---|---|---|
-| Unanswered messages or unobserved results | 102 | Continue silently |
+| Unobserved messages or results | 102 | Continue silently |
 | No authored response operations or fresh operation/parser failure, without WAIT | 102 | Recover before automatic parking |
 | WAIT | 202 | Park when a live obligation exists; otherwise continue at 102 |
 | Eligible parameterless KILL ({§kill-conclusion}), live work remains, no fresh failure | 202 | Join the held work without delivering its body |
-| Eligible parameterless KILL, results observed, no held work, messages answered or answered by its body | 200 | Deliver the answer and conclude under {§kill-conclusion}; an empty KILL need not repeat a delivered response |
+| Eligible parameterless KILL, messages and results observed, no held work | 200 | Conclude under {§kill-conclusion}; deliver a nonempty body, or finish silently without inventing or repeating a reply |
 | Other admitted program | 102 | Continue regardless of earlier replies or live work |
 | KILL own worker | 499 | Cancel unfinished work in that worker and its descendants |
 | Runtime or infrastructure failure | 5xx | Not a model-authored task status |
@@ -1284,8 +1284,8 @@ intent.
 so.** An outside-text line that opens at column zero with an operation's name and anything else
 — `KILL The answer…`, `READ (a.md)`, `KILL (notes.md)` — draws one warning: `` `KILL` has no
 fence, so it did not run. `` The line is not response text ({§response-text}): it is neither stored
-as outside text nor echoed into the next packet, and the exact emission remains at `ops://`; the bare name alone
-opens the operation instead ({§naked-operation}). A registered executor's name followed by an
+as outside text nor echoed into the next packet, and the exact emission remains at `ops://`; a name
+with only an optional complete aside opens the operation instead ({§naked-operation}). A registered executor's name followed by an
 operand slot — `gitea (list_issues)`, `sh(build.sh)` — draws the same warning under the executor's
 own spelling; quoted blocks, offset lines and names inside a sentence draw nothing, since `sh`,
 `env` and `members` are ordinary words. The model that wrote it believes it ran: stored as
@@ -1553,42 +1553,29 @@ model-language syntax or model packet teaching.
 
 ### §mcp-server-definition 13.8 MCP server definitions
 
-`McpServerDefinition` is the transport-neutral normalized definition of one
-workspace MCP server. It is a closed `stdio`/`http` union. The schema
-owns transport-specific fields, enabled/read tool sets, supported HTTP
-authorization choices, and symbolic credential references; it carries no
-workspace identifier, connection state, discovered catalog, or secret value.
-`Validator.assertMcpServerDefinition` is the MCP host's admission boundary
-before persistence or connection work.
-
-§mcp-server-options `McpServerOptions` is the closed client/daemon-shared
-supplement accepted when adding an MCP server by alias and target. It reuses
-only `McpServerDefinition` option fields and cannot repeat identity, target, or
-transport. The target determines the transport; normalization through
-`McpServerDefinition` rejects options belonging to the other transport.
-
-Interactive OAuth always requires a callback URL. Its structurally exclusive
-identity modes are an HTTPS Client ID Metadata Document URL, a pre-registered
-client ID plus symbolic secret, or neither for server-advertised Dynamic Client
-Registration fallback. A definition cannot combine those identity modes.
-
-§mcp-configuration-overlay `McpConfigurationOverlay` is the bounded raw
-configuration projection a client may carry to MCP list and enable actions: its
-string-valued `PLURNK_MCP_*` variables, whole. Which of those names are the
-host's own controls is the host's fact alone — its parser skips every control
-it owns, so a carried timeout or enabled list has no effect and no client or
-contract restates that vocabulary.
-The client does not interpret this map. The MCP host composes it over the
-lower normalized definition through the same parser that admits service
-environment declarations, then validates the resulting
-`McpServerDefinition`. Carrying the overlay does not connect, persist, or
-expand credentials by itself.
+`McpServerDefinition` is the one definition the workspace `mcp` Functionality family
+accepts and persists: one complete connection definition with its alias `name`.
+It is a closed union of the two supported transports, `stdio`
+(`command`, optional `args`, `env`, `cwd`) and `streamable-http` (`url`, optional
+`headers` and `authorization`). Source provenance, workspace scope, connection
+state, catalog and resolved credentials are not definition fields. Adding or
+removing a definition does not install or remove a plugin. Transport and
+authentication fields replace together ({§configuration-definition-resolution}).
+
+§mcp-oauth `McpOAuth` is the client-managed OAuth plurnk holds for one Streamable
+HTTP server, included in that server's `authorization`. Interactive OAuth always requires a callback URL, and
+its structurally exclusive identity modes are an HTTPS Client ID Metadata Document URL,
+a pre-registered client ID with a symbolic secret, or neither for server-advertised
+Dynamic Client Registration. A client-credentials grant names its client ID and
+symbolic secret, optionally binding an issuer. Every secret is one complete `${NAME}`
+reference to the operator environment; `Validator.assertMcpOAuth` validates the shape.
 
 `SkillDefinition` is the one definition the workspace `skills` Functionality
-family accepts and persists: the standard `name`, source `scope`, and optional
-installer `source`. `Validator.assertSkillDefinition` validates the wire shape;
+family accepts and persists: the standard `name`, its `source`, an optional git
+`ref`, and the `commit` the service recorded. Only host-provided trees omit
+`source`; installation scopes are not part of this shape. `Validator.assertSkillDefinition` validates the wire shape;
 the schema's name grammar is exposed as `SKILL_NAME` for loaders and discovery
-({§agent-skills-name}). Core owns installation truth and lifecycle
+({§agent-skills-name}). Core owns source resolution and lifecycle
 ({§skills-functionality}).
 
 `A2aAgentDefinition` is the one definition the Worker `a2a` Functionality
@@ -1609,6 +1596,14 @@ An exterior adapter owns its own protocol validation, identity binding, and
 projection while reusing the same workspace, worker, loop, operation, proposal,
 interaction, and event owners through this port.
 
+`ApplicationOperationEvent` is the schema-owned dispatch observation consumed
+through that subscription; its production boundary is {§notifications-operation-event}.
+
+`configurationNotices` exposes current launcher-owned configuration diagnostics
+without acquiring a workspace or provider. Adapters use the existing Notice
+projection; model turns combine these with workspace diagnostics according to
+{§configuration-repair-path}.
+
 `runLoop.source` is trusted causal provenance supplied by an adapter, distinct
 from user-authored prompt content. An adapter may expose no public means to set
 it; Core validates and records it through the same prompt admission path.
@@ -1826,7 +1821,8 @@ diagnostics are:
   of a FIND, READ or targeted KILL is a body, and those operations take none: the builder
   keeps the statement without it and raises one warning-severity advisory (`READ
   takes no body; the body was ignored. A pattern belongs on the opening fence line
-  after the path.`), delivered like {§misplaced-aside-advisory} as a
+  after the path.`). KILL's advisory names `KILL with a target`; it must not
+  prohibit parameterless completion bodies. Delivered like {§misplaced-aside-advisory} as a
   `parse_advisory` notice (a warning, never an error). One sigil line beneath the heading is the bare form
   written a line low and still lifts; nothing else is promoted into a matcher from
   below the heading, and the advisory never echoes the body.

package/dist/conformance/agui-v1.json

@@ -70,6 +70,7 @@
                                 "model": null,
                                 "loopId": null,
                                 "packetCount": 0,
+                                "preparation": [],
                                 "activity": null
                             }
                         },
@@ -79,6 +80,15 @@
                 {
                     "type": "STATE_DELTA",
                     "delta": [
+                        { "op": "replace", "path": "/plurnk/status/preparation", "value": [
+                            { "family": "mcp", "alias": "search", "phase": "preparing", "since": "2026-09-29T00:00:00.000Z" }
+                        ] }
+                    ]
+                },
+                {
+                    "type": "STATE_DELTA",
+                    "delta": [
+                        { "op": "replace", "path": "/plurnk/status/preparation", "value": [] },
                         { "op": "replace", "path": "/plurnk/status/lifecycle", "value": "running" },
                         { "op": "replace", "path": "/plurnk/status/loopId", "value": 1 },
                         { "op": "replace", "path": "/plurnk/status/packetCount", "value": 1 }
@@ -134,7 +144,7 @@
             ],
             "expect": {
                 "completion": "success",
-                "families": ["log/entry", "loop/packet", "loop/terminated"],
+                "families": ["log/entry", "loop/packet", "loop/terminated", "workspace/preparation"],
                 "status": 200
             }
         },

package/dist/schema/ApplicationOperationEvent.json

@@ -0,0 +1,27 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/ApplicationOperationEvent.json",
+    "title": "ApplicationOperationEvent",
+    "description": "A core-owned dispatch boundary. A settled dispatch has its exact result; it does not assert asynchronous process completion.",
+    "type": "object",
+    "required": ["workerId", "loopId", "turnId", "sequence", "origin", "projectRoot", "statement", "phase"],
+    "additionalProperties": false,
+    "properties": {
+        "workerId": { "type": "integer", "minimum": 1 },
+        "loopId": { "type": "integer", "minimum": 1 },
+        "turnId": { "type": "integer", "minimum": 1 },
+        "sequence": { "type": "integer", "minimum": 1 },
+        "origin": { "enum": ["model", "client", "_plurnk", "plugin"] },
+        "projectRoot": { "type": ["string", "null"] },
+        "statement": { "$ref": "https://schemas.plurnk.xyz/v0/PlurnkStatement.json" },
+        "phase": { "enum": ["started", "settled"] },
+        "result": { "$ref": "https://schemas.plurnk.xyz/v0/OperationResult.json" }
+    },
+    "allOf": [
+        {
+            "if": { "properties": { "phase": { "const": "settled" } } },
+            "then": { "required": ["result"] },
+            "else": { "not": { "required": ["result"] } }
+        }
+    ]
+}

package/dist/schema/FunctionalityCandidate.json

@@ -19,15 +19,6 @@
             "description": "The exact family definition, conforming to the family's definition schema.",
             "type": "object"
         },
-        "provenance": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["kind", "source"],
-            "properties": {
-                "kind": { "type": "string", "minLength": 1 },
-                "source": { "type": "string", "minLength": 1 },
-                "reference": { "type": "string", "minLength": 1 }
-            }
-        }
+        "provenance": { "$ref": "https://schemas.plurnk.xyz/v0/FunctionalityProvenance.json" }
     }
 }

package/dist/schema/FunctionalityDefinitionState.json

@@ -13,10 +13,14 @@
             "enum": ["service", "workspace", "worker"]
         },
         "state": {
-            "description": "disabled: available, model-invisible. active: enabled and prepared. unavailable: enabled but preparation has an exact Problem. authorization-required: enabled and awaiting a protocol continuation.",
-            "enum": ["disabled", "active", "unavailable", "authorization-required"]
+            "description": "disabled: available, model-invisible. dormant: enabled without a resident publication. active: enabled and prepared. unavailable: enabled but preparation has an exact Problem. authorization-required: enabled and awaiting a protocol continuation.",
+            "enum": ["disabled", "dormant", "active", "unavailable", "authorization-required"]
         },
         "definition": { "type": "object" },
+        "provenance": {
+            "description": "The winning configuration input, when supplied by a source reader. Independent of origin and readiness; absent for locally owned definitions or host-provided resources without a configuration input.",
+            "$ref": "https://schemas.plurnk.xyz/v0/FunctionalityProvenance.json"
+        },
         "inherited": {
             "description": "The Worker this entry was copied from when this Worker was created (WORK or FORK), preserved across generations until this Worker changes the entry. Absent for an entry this Worker set itself. Worker-scoped families only.",
             "type": "string",

package/dist/schema/FunctionalityDiscoverQuery.json

@@ -9,7 +9,7 @@
         "query": { "type": "string", "minLength": 1 },
         "source": { "type": "string", "minLength": 1 },
         "configuration": {
-            "description": "Caller-supplied configuration material the family interprets as candidates (a client's own PLURNK_MCP_* environment, a local directory list). It contributes candidates with client-configuration provenance; it never becomes durable authority.",
+            "description": "Caller-supplied configuration material the family interprets as candidates (a client's own PLURNK_A2A_* environment, a local directory list). It contributes candidates with client-configuration provenance; it never becomes durable authority.",
             "type": "object"
         }
     }

package/dist/schema/FunctionalityPreparationActivity.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/FunctionalityPreparationActivity.json",
+    "title": "FunctionalityPreparationActivity",
+    "description": "Current workspace capability preparation, not a published outcome. No definitions or credentials.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["family", "alias", "phase", "since"],
+    "properties": {
+        "family": { "type": "string", "minLength": 1 },
+        "alias": { "type": ["string", "null"], "minLength": 1 },
+        "phase": { "enum": ["preparing", "publishing"] },
+        "since": { "type": "string", "format": "date-time" }
+    }
+}

package/dist/schema/FunctionalityProvenance.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/FunctionalityProvenance.json",
+    "title": "FunctionalityProvenance",
+    "description": "The input supplying a definition or discovery candidate, separate from ownership, preparation and authority.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["kind", "source"],
+    "properties": {
+        "kind": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "reference": { "type": "string", "minLength": 1 }
+    }
+}

package/dist/schema/McpOAuth.json

@@ -0,0 +1,64 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/McpOAuth.json",
+    "title": "McpOAuth",
+    "description": "OAuth configuration within one Streamable HTTP MCP server definition. Every secret is a ${NAME} reference to the operator environment.",
+    "oneOf": [
+        {
+            "type": "object",
+            "description": "Interactive OAuth identified by an HTTPS Client ID Metadata Document.",
+            "additionalProperties": false,
+            "required": ["type", "redirectUrl", "clientMetadataUrl"],
+            "properties": {
+                "type": { "const": "oauth" },
+                "redirectUrl": { "type": "string", "format": "uri" },
+                "clientMetadataUrl": { "type": "string", "format": "uri", "pattern": "^https://.+/.+" },
+                "scope": { "type": "string", "minLength": 1 }
+            }
+        },
+        {
+            "type": "object",
+            "description": "Interactive OAuth with a pre-registered client ID and secret.",
+            "additionalProperties": false,
+            "required": ["type", "redirectUrl", "clientId", "clientSecret"],
+            "properties": {
+                "type": { "const": "oauth" },
+                "redirectUrl": { "type": "string", "format": "uri" },
+                "clientId": { "type": "string", "minLength": 1 },
+                "clientSecret": { "$ref": "#/$defs/environmentReference" },
+                "scope": { "type": "string", "minLength": 1 }
+            }
+        },
+        {
+            "type": "object",
+            "description": "Interactive OAuth through server-advertised Dynamic Client Registration.",
+            "additionalProperties": false,
+            "required": ["type", "redirectUrl"],
+            "properties": {
+                "type": { "const": "oauth" },
+                "redirectUrl": { "type": "string", "format": "uri" },
+                "scope": { "type": "string", "minLength": 1 }
+            }
+        },
+        {
+            "type": "object",
+            "description": "A noninteractive client-credentials grant; issuer optionally binds the credentials to one authorization server.",
+            "additionalProperties": false,
+            "required": ["type", "clientId", "clientSecret"],
+            "properties": {
+                "type": { "const": "client-credentials" },
+                "clientId": { "type": "string", "minLength": 1 },
+                "clientSecret": { "$ref": "#/$defs/environmentReference" },
+                "scope": { "type": "string", "minLength": 1 },
+                "issuer": { "type": "string", "minLength": 1 }
+            }
+        }
+    ],
+    "$defs": {
+        "environmentReference": {
+            "description": "An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.",
+            "type": "string",
+            "pattern": "^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
+        }
+    }
+}