@plurnk/plurnk-contracts 1.16.5 → 1.18.0

package/dist/src/types.generated.d.ts

@@ -185,7 +185,10 @@ export interface MimetypeDisplayCapability {
     display: CapabilityDisplay;
 }
 export interface CapabilityDescriptor {
-    operation: ("FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SEND" | "EXEC" | "BARE" | "WORK" | "FORK" | "KILL");
+    /**
+     * An operation keyword, or a runtime tag: an execution's operation is its runtime.
+     */
+    operation: "FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SEND" | "BARE" | "WORK" | "FORK" | "KILL" | Lowercase<string>;
     scheme?: string;
     runtime?: string;
     tool?: string;
@@ -200,7 +203,10 @@ export interface CapabilityPolicy {
  * One exact, conjunctive selector over a routed PLURNK capability demand. Omitted fields are wildcards; at least one field is required.
  */
 export interface CapabilitySelector {
-    operation?: ("FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SEND" | "EXEC" | "BARE" | "WORK" | "FORK" | "KILL");
+    /**
+     * An operation keyword, or a runtime tag: an execution's operation is its runtime.
+     */
+    operation?: "FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SEND" | "BARE" | "WORK" | "FORK" | "KILL" | Lowercase<string>;
     scheme?: string;
     runtime?: string;
     tool?: string;
@@ -213,8 +219,6 @@ export interface CapabilitySelector {
 export interface CapabilityProjection {
     service: CapabilityPolicy;
     workspace: CapabilityPolicy;
-    workerBound: CapabilityPolicy;
-    worker: CapabilityPolicy;
     effective: CapabilityPolicy;
 }
 /**
@@ -246,48 +250,54 @@ export type ClientInteractionResolution = ({
 } | {
     status: "cancelled";
 });
-export type ClientStatement = (PlurnkStatement | LookStatement | BuffStatement);
+export type ClientStatement = (PlurnkStatement | LookStatement);
 /**
- * The parsed AST union for one protocol statement, discriminated by `op`. Every variant has fixed signal, target, metadata, lineMarker, annotation, body, delimiter, 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.
+ * The parsed AST union for one protocol statement, discriminated by `op`. Every variant has fixed signal, target, metadata, lineMarker, aside, body, and source-position fields, and the text and log operations add a matcher lifted from the `pattern` option; operation-specific schemas constrain their types. A null field records an omitted tolerated slot and does not satisfy runtime requirements by itself.
  */
-export type PlurnkStatement = (FindStatement | ReadStatement | EditStatement | CopyStatement | MoveStatement | SendStatement | ExecStatement | BareStatement | WorkStatement | ForkStatement | KillStatement | PlanStatement);
+export type PlurnkStatement = (FindStatement | ReadStatement | EditStatement | CopyStatement | MoveStatement | SendStatement | ExecStatement | BareStatement | WorkStatement | ForkStatement | KillStatement | DispositionStatement);
 /**
  * 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.
  */
 export type ParsedPath = (LocalPath | UrlPath);
 /**
- * Parsed single-line body of a matcher-bearing 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.
+ * Parsed single-line body of a matcher-bearing statement, discriminated on `dialect`. The dialect is determined by the body's leading characters (`//` xpath, `/` regex, `$` jsonpath, `~` full-text, `&` graph, else glob). The regex variant carries pattern and flags split out of the `/pattern/flags` literal; every variant remains JSON-serializable.
  */
-export type MatcherBody = (XPathBody | RegexBody | JsonPathBody | SemanticBody | GraphBody | GlobBody);
+export type MatcherBody = (XPathBody | RegexBody | JsonPathBody | FtsBody | GraphBody | GlobBody);
 /**
- * Plurnk's complete model-native working-memory Plan entries.
+ * Plurnk's model-native task inventory.
  */
 export type Plan = PlanEntry[];
-export type AnnotationOrNull = (string | null);
+export type AsideOrNull = (string | null);
 export type SchemeMetadataOrNull = (string[] | null);
 export type PathOrNull = (ParsedPath | null);
 export type TextLineMarkerOrNull = (TextLineMarker | null);
 export type MatcherBodyOrNull = (MatcherBody | null);
-export type LineMarkerOrNull = (LineMarker | null);
 export interface FindStatement {
     op: "FIND";
-    delimiter: string;
-    annotation: (string | null);
+    aside: (string | null);
     /**
      * Opaque ordered scheme-metadata modifier blocks. Contracts preserve each block's raw inner text; the addressed scheme exclusively owns interpretation and validation.
      */
     metadata: (string[] | null);
     target: (ParsedPath | null);
     lineMarker: (LineMarker | null);
-    body: (MatcherBody | null);
+    /**
+     * The selection matcher lifted from the heading's `[{"pattern": …}]` option ({§matcher-option}); null when the heading carries none.
+     */
+    matcher: (MatcherBody | null);
+    /**
+     * FIND takes no body; its matcher is the `pattern` option.
+     */
+    body: null;
     position: Position;
 }
 /**
- * A bare local path with no `scheme://` prefix. The raw string is stored verbatim; resolution is the runtime's job.
+ * A bare local path with no `scheme://` prefix. `raw` is the path as authored, minus any `#channel`, which is `fragment` exactly as on a URL; resolution is the runtime's job.
  */
 export interface LocalPath {
     kind: "local";
     raw: string;
+    fragment?: (string | null);
 }
 /**
  * A path with a `scheme://` prefix, fully decomposed via WHATWG URL.
@@ -308,7 +318,7 @@ export interface UrlPath {
     fragment: (string | null);
 }
 /**
- * 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.
+ * 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, and mutation anchors.
  */
 export interface LineMarker {
     /**
@@ -340,10 +350,10 @@ export interface JsonPathBody {
     raw: string;
 }
 /**
- * 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.
+ * Native SQLite FTS5 query after the `~` prefix. SQLite owns query validation, tokenization, matching and ranking; the statement's scope selects ordinary result positions.
  */
-export interface SemanticBody {
-    dialect: "semantic";
+export interface FtsBody {
+    dialect: "fts";
     raw: string;
 }
 /**
@@ -369,14 +379,17 @@ export interface Position {
 }
 export interface ReadStatement {
     op: "READ";
-    delimiter: string;
-    annotation: (string | null);
+    aside: (string | null);
     /**
      * Opaque ordered scheme-metadata modifier blocks. Contracts preserve each block's raw inner text; the addressed scheme exclusively owns interpretation and validation.
      */
     metadata: (string[] | null);
     target: (ParsedPath | null);
     lineMarker: (TextLineMarker | null);
+    /**
+     * The selection matcher lifted from the heading's `[{"pattern": …}]` option ({§matcher-option}); null when the heading carries none.
+     */
+    matcher: (MatcherBody | null);
     body: null;
     position: Position;
 }
@@ -391,21 +404,23 @@ export interface TextLineMarker {
 }
 export interface EditStatement {
     op: "EDIT";
-    delimiter: string;
-    annotation: (string | null);
+    aside: (string | null);
     /**
      * Opaque ordered scheme-metadata modifier blocks. Contracts preserve each block's raw inner text; the addressed scheme exclusively owns interpretation and validation.
      */
     metadata: (string[] | null);
     target: (ParsedPath | null);
     lineMarker: (TextLineMarker | null);
+    /**
+     * The selection matcher lifted from the heading's `[{"pattern": …}]` option ({§matcher-option}); null when the heading carries none.
+     */
+    matcher: (MatcherBody | null);
     body: (string | null);
     position: Position;
 }
 export interface CopyStatement {
     op: "COPY";
-    delimiter: string;
-    annotation: (string | null);
+    aside: (string | null);
     source: ResourceSelection;
     destination: ResourceSelection;
     position: Position;
@@ -420,19 +435,21 @@ export interface ResourceSelection {
      */
     metadata: (string[] | null);
     lineMarker: (TextLineMarker | null);
+    /**
+     * The selection matcher lifted from the operand's `[{"pattern": …}]` option; meaningful on the source operand, refused by the owner on a destination.
+     */
+    matcher: (MatcherBody | null);
 }
 export interface MoveStatement {
     op: "MOVE";
-    delimiter: string;
-    annotation: (string | null);
+    aside: (string | null);
     source: ResourceSelection;
     destination: ResourceSelection;
     position: Position;
 }
 export interface SendStatement {
     op: "SEND";
-    delimiter: string;
-    annotation: (string | null);
+    aside: (string | null);
     /**
      * Opaque ordered scheme-metadata modifier blocks. Contracts preserve each block's raw inner text; the addressed scheme exclusively owns interpretation and validation.
      */
@@ -441,10 +458,6 @@ export interface SendStatement {
     lineMarker: (LineMarker | null);
     body: (SendBody | null);
     position: Position;
-    /**
-     * The turn disposition the label names ({§send-label}): NEXT 102, WAIT 202, TERM 200, FAIL 499; null for a mid-turn message to a recipient.
-     */
-    status: ((102 | 200 | 202 | 499) | null);
 }
 /**
  * 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.
@@ -454,17 +467,19 @@ export interface SendBody {
     json: unknown;
 }
 export interface ExecStatement {
-    op: "EXEC";
-    delimiter: string;
-    annotation: (string | null);
     /**
-     * Opaque ordered scheme-metadata modifier blocks. Contracts preserve each block's raw inner text; the addressed scheme exclusively owns interpretation and validation.
+     * The runtime tag the fence names, in its registered lowercase spelling. An execution has no operation keyword: the fence name is the runtime, and the log row's op shows it as written.
      */
-    metadata: (string[] | null);
+    runtime: Lowercase<string>;
     /**
-     * The `[executor]` slot: the registered executor that runs the program; null is the default shell.
+     * Never present: an execution is named by its runtime.
      */
-    executor: (string | null);
+    op?: never;
+    aside: (string | null);
+    /**
+     * Opaque ordered scheme-metadata modifier blocks. Contracts preserve each block's raw inner text; the addressed scheme exclusively owns interpretation and validation.
+     */
+    metadata: (string[] | null);
     target: (ParsedPath | null);
     lineMarker: (LineMarker | null);
     body: (string | null);
@@ -472,21 +487,19 @@ export interface ExecStatement {
 }
 export interface BareStatement {
     op: "BARE";
-    delimiter: string;
-    annotation: (string | null);
+    aside: (string | null);
     /**
      * Opaque ordered scheme-metadata modifier blocks. Contracts preserve each block's raw inner text; the addressed scheme exclusively owns interpretation and validation.
      */
     metadata: (string[] | null);
-    target: null;
+    target: (ParsedPath | null);
     lineMarker: null;
     body: string;
     position: Position;
 }
 export interface WorkStatement {
     op: "WORK";
-    delimiter: string;
-    annotation: (string | null);
+    aside: (string | null);
     /**
      * Opaque ordered scheme-metadata modifier blocks. Contracts preserve each block's raw inner text; the addressed scheme exclusively owns interpretation and validation.
      */
@@ -498,8 +511,7 @@ export interface WorkStatement {
 }
 export interface ForkStatement {
     op: "FORK";
-    delimiter: string;
-    annotation: (string | null);
+    aside: (string | null);
     /**
      * Opaque ordered scheme-metadata modifier blocks. Contracts preserve each block's raw inner text; the addressed scheme exclusively owns interpretation and validation.
      */
@@ -511,8 +523,7 @@ export interface ForkStatement {
 }
 export interface KillStatement {
     op: "KILL";
-    delimiter: string;
-    annotation: (string | null);
+    aside: (string | null);
     /**
      * Opaque ordered scheme-metadata modifier blocks. Contracts preserve each block's raw inner text; the addressed scheme exclusively owns interpretation and validation.
      */
@@ -523,23 +534,26 @@ export interface KillStatement {
      */
     lineMarker: (TextLineMarker | null);
     /**
-     * A body pattern selects log items for a scoped KILL, as a FIND body does ({§kill-scope}); null otherwise.
+     * The selection matcher lifted from the heading's `[{"pattern": …}]` option ({§matcher-option}); null when the heading carries none.
      */
-    body: (MatcherBody | null);
+    matcher: (MatcherBody | null);
+    /**
+     * KILL takes no body; its matcher is the `pattern` option.
+     */
+    body: null;
     position: Position;
 }
-export interface PlanStatement {
-    op: "PLAN";
-    delimiter: string;
-    annotation: (string | null);
+export interface DispositionStatement {
+    op: "TASK";
+    aside: (string | null);
     metadata: null;
     target: null;
-    lineMarker: null;
+    lineMarker: (LineMarker | null);
     body: Plan;
     position: Position;
 }
 /**
- * One finding, task, or goal in the model's working-memory plan.
+ * One task or goal in the model's plan.
  */
 export interface PlanEntry {
     /**
@@ -549,7 +563,7 @@ export interface PlanEntry {
     /**
      * The current execution status of this task.
      */
-    status: ("pending" | "in_progress" | "completed" | "memory");
+    status: ("todo" | "in_progress" | "waiting" | "completed" | "failed");
     /**
      * Opaque entry metadata preserved through standards projection.
      */
@@ -559,24 +573,13 @@ export interface PlanEntry {
 }
 export interface LookStatement {
     op: "LOOK";
-    delimiter: string;
-    annotation: AnnotationOrNull;
+    aside: AsideOrNull;
     metadata: SchemeMetadataOrNull;
     target: PathOrNull;
     lineMarker: TextLineMarkerOrNull;
     body: MatcherBodyOrNull;
     position: Position;
 }
-export interface BuffStatement {
-    op: "BUFF";
-    delimiter: string;
-    annotation: AnnotationOrNull;
-    metadata: SchemeMetadataOrNull;
-    target: PathOrNull;
-    lineMarker: LineMarkerOrNull;
-    body: MatcherBodyOrNull;
-    position: Position;
-}
 export type EntryReadResult = ({
     status: 200;
     entry: ClientEntry;
@@ -656,12 +659,19 @@ export interface FunctionalityCandidate {
 }
 export type FunctionalityDefinitionState = {
     alias: string;
-    origin: ("service" | "worker");
+    /**
+     * Who owns this definition: the service baseline, the workspace, or one worker. A worker-scoped family (env) owns its definitions per worker, so origin names ownership rather than scope.
+     */
+    origin: ("service" | "workspace" | "worker");
     /**
      * disabled: available, model-invisible. active: enabled and prepared. unavailable: enabled but preparation has an exact Problem. authorization-required: enabled and awaiting a protocol continuation.
      */
     state: ("disabled" | "active" | "unavailable" | "authorization-required");
     definition?: {};
+    /**
+     * 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.
+     */
+    inherited?: string;
     /**
      * Family-owned presentation facts about an active definition (a server's protocol version and tool names, an agent card summary). Never credentials, never authority.
      */
@@ -707,28 +717,51 @@ export interface FunctionalityMutationResult {
  * 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.
  */
 export interface LoopPolicy {
-    capabilities: CapabilityPolicy;
     proposals: ("review" | "accept" | "reject");
 }
-/**
- * One purely subtractive capability-policy layer. Deny wins; when only is present, a demand must match at least one selector.
- */
 export interface McpConfigurationOverlay {
     [k: string]: string;
 }
 export type McpServerDefinition = {
+    /**
+     * Server alias: the runtime tag whose fence invokes it, and its resource scheme.
+     */
     name: string;
+    /**
+     * stdio launches a local command; http connects to a remote MCP endpoint.
+     */
     transport: ("stdio" | "http");
+    /**
+     * Executable to launch for stdio; arguments belong in args.
+     */
     command?: string;
+    /**
+     * Arguments passed to the stdio executable in order.
+     */
     args?: string[];
+    /**
+     * Working directory for the stdio process.
+     */
     cwd?: string;
+    /**
+     * Environment overrides for the stdio process; values may reference ${ENV_NAME}.
+     */
     env?: {
         [k: string]: string;
     };
+    /**
+     * HTTP MCP endpoint URL.
+     */
     url?: string;
+    /**
+     * HTTP request headers; values may reference ${ENV_NAME}. Authorization cannot also be configured here when authorization is set.
+     */
     headers?: {
         [k: string]: string;
     };
+    /**
+     * HTTP authentication. Secret fields reference the operator environment rather than embedding credentials.
+     */
     authorization?: ({
         type: "bearer";
         token: EnvironmentReference;
@@ -754,13 +787,28 @@ export type McpServerDefinition = {
         scope?: string;
         issuer?: string;
     });
+    /**
+     * Exact enabled tool names; omitted enables all tools, an empty array enables none.
+     */
     tools?: string[];
+    /**
+     * Exact tool names the operator designates as read effects rather than host effects requiring proposal review.
+     */
     read?: string[];
 };
+/**
+ * An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.
+ */
 export type EnvironmentReference = string;
 export type McpServerArguments = string[];
+/**
+ * HTTP authentication. Secret fields reference the operator environment rather than embedding credentials.
+ */
 export type McpServerAuthorization = ({
     type: "bearer";
+    /**
+     * An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.
+     */
     token: string;
 } | {
     type: "oauth";
@@ -771,6 +819,9 @@ export type McpServerAuthorization = ({
     type: "oauth";
     redirectUrl: string;
     clientId: string;
+    /**
+     * An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.
+     */
     clientSecret: string;
     scope?: string;
 } | {
@@ -780,14 +831,26 @@ export type McpServerAuthorization = ({
 } | {
     type: "client-credentials";
     clientId: string;
+    /**
+     * An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.
+     */
     clientSecret: string;
     scope?: string;
     issuer?: string;
 });
+/**
+ * Exact enabled tool names; omitted enables all tools, an empty array enables none.
+ */
 export type McpServerToolNames = string[];
+/**
+ * Exact tool names the operator designates as read effects rather than host effects requiring proposal review.
+ */
 export type McpServerReadTools = string[];
 export interface McpServerOptions {
     args?: McpServerArguments;
+    /**
+     * Working directory for the stdio process.
+     */
     cwd?: string;
     env?: McpServerEnvironment;
     headers?: McpServerHeaders;
@@ -795,12 +858,22 @@ export interface McpServerOptions {
     tools?: McpServerToolNames;
     read?: McpServerReadTools;
 }
+/**
+ * Environment overrides for the stdio process; values may reference ${ENV_NAME}.
+ */
 export interface McpServerEnvironment {
     [k: string]: string;
 }
+/**
+ * HTTP request headers; values may reference ${ENV_NAME}. Authorization cannot also be configured here when authorization is set.
+ */
 export interface McpServerHeaders {
     [k: string]: string;
 }
+export type ReasoningPolicy = ("off" | "adaptive" | "low" | "medium" | "high" | "xhigh" | "max");
+/**
+ * One deterministic bounded page from the release-pinned model catalog.
+ */
 export interface ModelCatalogPage {
     /**
      * @maxItems 100
@@ -828,6 +901,12 @@ export interface ModelCatalogLimits {
 export interface ModelCatalogCapabilities {
     attachment: boolean;
     reasoning: boolean;
+    /**
+     * Portable reasoning policies admitted for this exact route by the installed provider adapter and provider-wide operator declarations; not a worker's combined model/spawn policy intersection.
+     *
+     * @minItems 1
+     */
+    reasoningPolicies: [ReasoningPolicy, ...(ReasoningPolicy)[]];
     toolCall: boolean;
     structuredOutput?: boolean;
     temperature?: boolean;
@@ -857,15 +936,15 @@ export interface ModelCatalogQuery {
     offset?: number;
     limit?: number;
 }
-export type ReasoningPolicy = ("off" | "adaptive" | "low" | "medium" | "high" | "xhigh" | "max");
-/**
- * A client-visible resolved provider/model identity. Alias is present only when a declared alias supplied the route; provider configuration remains private to the daemon. reasoningPolicy is the worker's durable effort selection — absent when the model has no reasoning dimension.
- */
 export interface ModelRoute {
     alias?: string;
     provider: string;
     model: string;
     reasoningPolicy?: ReasoningPolicy;
+    /**
+     * Whether reasoningPolicy was chosen through worker.reasoning.set (explicit) or seeded from the alias configuration (default). Present exactly when reasoningPolicy is.
+     */
+    reasoningSource?: ("default" | "explicit");
 }
 export interface Notice {
     /**
@@ -873,7 +952,7 @@ export interface Notice {
      */
     source: string;
     /**
-     * Open discriminator within a source. Examples include `grammar_unenforced`, `embed_progress`, `search_progress`, and `turn_awaiting_model`.
+     * Open discriminator within a source. Examples include `grammar_unenforced`, `search_progress`, and `turn_awaiting_model`.
      */
     kind: string;
     /**
@@ -937,9 +1016,13 @@ export interface RangeExtent {
     requested: RequestedRange;
     returned?: ReturnedRange;
 }
+export type LineMarkerOrNull = (LineMarker | null);
+/**
+ * Parsed single-line body of a matcher-bearing statement, discriminated on `dialect`. The dialect is determined by the body's leading characters (`//` xpath, `/` regex, `$` jsonpath, `~` full-text, `&` graph, else glob). The regex variant carries pattern and flags split out of the `/pattern/flags` literal; every variant remains JSON-serializable.
+ */
 export type SendBodyOrNull = (SendBody | null);
 /**
- * Plurnk's complete model-native working-memory Plan entries.
+ * Plurnk's model-native task inventory.
  */
 export interface ProblemProjection {
     /**
@@ -979,7 +1062,10 @@ export interface ProposalProjection {
     workerId: number;
     loopId: number;
     turnId: number;
-    op: ("FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SEND" | "EXEC" | "BARE" | "WORK" | "FORK" | "KILL" | "PLAN");
+    /**
+     * An operation keyword, or a runtime tag: an execution's operation is its runtime.
+     */
+    op: "FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SEND" | "BARE" | "WORK" | "FORK" | "KILL" | "TASK" | Lowercase<string>;
     target: {
         scheme: (string | null);
         authority: (string | null);
@@ -993,7 +1079,7 @@ export interface ProposalProjection {
     disposition: ProposalDisposition;
 }
 /**
- * The complete immutable policy snapshot for one loop. Capability admission precedes proposal disposition.
+ * The immutable proposal disposition for one loop. Workspace capability admission precedes proposals.
  */
 export type ProviderCost = ({
     kind: "charged";
@@ -1060,9 +1146,9 @@ export interface SkillDefinition {
      */
     name: string;
     /**
-     * The universal Agent Skills root: the project's `.agents/skills` or the user's `~/.agents/skills`.
+     * Source: project `.agents/skills`, global `~/.agents/skills`, or a service-provided resource tree. Service sources are not installer targets.
      */
-    scope: ("project" | "global");
+    scope: ("project" | "global" | "service");
     /**
      * The standard installer package reference (`owner/repo`, a git URL, or a local path) that provides the skill; required to add a skill that is not yet installed.
      */