@treeseed/sdk 0.13.0-rc.17 → 0.13.0-rc.19

package/dist/content/validation/portable-content-data.d.ts

@@ -650,8 +650,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 }>, "many">>;
                 requiresArtifactKinds: import("zod").ZodOptional<import("zod").ZodEffects<import("zod").ZodArray<import("zod").ZodString, "many">, string[], string[]>>;
             }, "strict", import("zod").ZodTypeAny, {
-                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 objective?: string | undefined;
+                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 proposalTypes?: string[] | undefined;
                 artifactKind?: string | undefined;
                 subjectModel?: string | undefined;
@@ -681,8 +681,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 }[] | undefined;
                 requiresArtifactKinds?: string[] | undefined;
             }, {
-                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 objective?: string | undefined;
+                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 proposalTypes?: string[] | undefined;
                 artifactKind?: string | undefined;
                 subjectModel?: string | undefined;
@@ -728,8 +728,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 }, "strict", import("zod").ZodTypeAny, {
                     kind: "team-human" | "human-or-agent" | "specific-human" | "specific-agent";
                     projectId?: string | undefined;
-                    teamId?: string | undefined;
                     agentSlug?: string | undefined;
+                    teamId?: string | undefined;
                     requiredRoles?: string[] | undefined;
                     allowedRoles?: string[] | undefined;
                     allowedAgentIds?: string[] | undefined;
@@ -739,8 +739,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 }, {
                     kind: "team-human" | "human-or-agent" | "specific-human" | "specific-agent";
                     projectId?: string | undefined;
-                    teamId?: string | undefined;
                     agentSlug?: string | undefined;
+                    teamId?: string | undefined;
                     requiredRoles?: string[] | undefined;
                     allowedRoles?: string[] | undefined;
                     allowedAgentIds?: string[] | undefined;
@@ -752,8 +752,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 defaultAnswerPolicy?: {
                     kind: "team-human" | "human-or-agent" | "specific-human" | "specific-agent";
                     projectId?: string | undefined;
-                    teamId?: string | undefined;
                     agentSlug?: string | undefined;
+                    teamId?: string | undefined;
                     requiredRoles?: string[] | undefined;
                     allowedRoles?: string[] | undefined;
                     allowedAgentIds?: string[] | undefined;
@@ -766,8 +766,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 defaultAnswerPolicy?: {
                     kind: "team-human" | "human-or-agent" | "specific-human" | "specific-agent";
                     projectId?: string | undefined;
-                    teamId?: string | undefined;
                     agentSlug?: string | undefined;
+                    teamId?: string | undefined;
                     requiredRoles?: string[] | undefined;
                     allowedRoles?: string[] | undefined;
                     allowedAgentIds?: string[] | undefined;
@@ -976,8 +976,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 publishes?: string[] | undefined;
             } | undefined;
             planningIntent?: {
-                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 objective?: string | undefined;
+                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 proposalTypes?: string[] | undefined;
                 artifactKind?: string | undefined;
                 subjectModel?: string | undefined;
@@ -1011,8 +1011,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 defaultAnswerPolicy?: {
                     kind: "team-human" | "human-or-agent" | "specific-human" | "specific-agent";
                     projectId?: string | undefined;
-                    teamId?: string | undefined;
                     agentSlug?: string | undefined;
+                    teamId?: string | undefined;
                     requiredRoles?: string[] | undefined;
                     allowedRoles?: string[] | undefined;
                     allowedAgentIds?: string[] | undefined;
@@ -1149,8 +1149,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 publishes?: string[] | undefined;
             } | undefined;
             planningIntent?: {
-                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 objective?: string | undefined;
+                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 proposalTypes?: string[] | undefined;
                 artifactKind?: string | undefined;
                 subjectModel?: string | undefined;
@@ -1184,8 +1184,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 defaultAnswerPolicy?: {
                     kind: "team-human" | "human-or-agent" | "specific-human" | "specific-agent";
                     projectId?: string | undefined;
-                    teamId?: string | undefined;
                     agentSlug?: string | undefined;
+                    teamId?: string | undefined;
                     requiredRoles?: string[] | undefined;
                     allowedRoles?: string[] | undefined;
                     allowedAgentIds?: string[] | undefined;
@@ -1322,8 +1322,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 publishes?: string[] | undefined;
             } | undefined;
             planningIntent?: {
-                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 objective?: string | undefined;
+                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 proposalTypes?: string[] | undefined;
                 artifactKind?: string | undefined;
                 subjectModel?: string | undefined;
@@ -1357,8 +1357,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 defaultAnswerPolicy?: {
                     kind: "team-human" | "human-or-agent" | "specific-human" | "specific-agent";
                     projectId?: string | undefined;
-                    teamId?: string | undefined;
                     agentSlug?: string | undefined;
+                    teamId?: string | undefined;
                     requiredRoles?: string[] | undefined;
                     allowedRoles?: string[] | undefined;
                     allowedAgentIds?: string[] | undefined;
@@ -1495,8 +1495,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 publishes?: string[] | undefined;
             } | undefined;
             planningIntent?: {
-                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 objective?: string | undefined;
+                stage?: "closeout" | "revision" | "discovery" | "synthesis" | "deliberation" | "evaluation" | undefined;
                 proposalTypes?: string[] | undefined;
                 artifactKind?: string | undefined;
                 subjectModel?: string | undefined;
@@ -1530,8 +1530,8 @@ export declare function validatePortableContentData(model: string, value: unknow
                 defaultAnswerPolicy?: {
                     kind: "team-human" | "human-or-agent" | "specific-human" | "specific-agent";
                     projectId?: string | undefined;
-                    teamId?: string | undefined;
                     agentSlug?: string | undefined;
+                    teamId?: string | undefined;
                     requiredRoles?: string[] | undefined;
                     allowedRoles?: string[] | undefined;
                     allowedAgentIds?: string[] | undefined;
@@ -1568,10 +1568,10 @@ export declare function validatePortableContentData(model: string, value: unknow
             model: string;
             priority: number;
             status?: string | undefined;
+            reason?: string | undefined;
             title?: string | undefined;
             slug?: string | undefined;
             estimatedCredits?: number | undefined;
-            reason?: string | undefined;
         }[];
         totalTasks: number;
         completedTasks: number;
@@ -1635,9 +1635,9 @@ export declare function validatePortableContentData(model: string, value: unknow
         fulfillment: {
             source: {
                 kind: "git";
-                ref: string;
                 repoUrl: string;
                 directory: string;
+                ref: string;
                 integrity?: string | undefined;
             } | {
                 version: string;
@@ -1709,9 +1709,9 @@ export declare function validatePortableContentData(model: string, value: unknow
         id: string;
         required: boolean;
         description: string;
+        query: string;
         title: string;
         revision: number;
-        query: string;
         filters: Record<string, unknown>;
         target: {
             kind: "code" | "content" | "mixed" | "graph";
@@ -1720,8 +1720,8 @@ export declare function validatePortableContentData(model: string, value: unknow
         };
         depth: number;
         purpose: string;
-        relations: import("../../sdk-types/support/sdk-search-request.js").SdkGraphDslRelation[];
         maturity: "draft" | "validated" | "simulated" | "proven";
+        relations: import("../../sdk-types/support/sdk-search-request.js").SdkGraphDslRelation[];
         resultLimit: number;
         contextBudget: {
             maxItems: number;
@@ -1763,15 +1763,15 @@ export declare function validatePortableContentData(model: string, value: unknow
         id: string;
         status: "active" | "completed" | "ready" | "superseded" | "draft";
         projectId: string;
+        teamId: string;
+        objective: string;
         completed: {
             id: string;
             description: string;
             title: string;
         }[];
-        teamId: string;
         title: string;
         revision: number;
-        objective: string;
         createdAt: Date;
         remaining: {
             id: string;
@@ -1804,10 +1804,10 @@ export declare function validatePortableContentData(model: string, value: unknow
         sequence: number;
         phase: string;
         description?: string | undefined;
+        reason?: string | undefined;
         assignmentId?: string | undefined;
         updatedAt?: Date | undefined;
         workdayId?: string | undefined;
-        reason?: string | undefined;
         previousStatusRef?: {
             id: string;
             revision: number;
@@ -1825,8 +1825,8 @@ export declare function validatePortableContentData(model: string, value: unknow
         artifactRefs: string[];
         lessons: string[];
         performance: {
-            metrics: Record<string, number>;
             outcome: string;
+            metrics: Record<string, number>;
         };
         verificationRefs: string[];
         description?: string | undefined;
@@ -2066,11 +2066,11 @@ export declare function validatePortableContentData(model: string, value: unknow
     } | {
         title: string;
         sequence?: number | undefined;
-        refs?: string[] | undefined;
         phase?: string | undefined;
         group_ids?: string[] | undefined;
         discussion_id?: string | undefined;
         occurred_at?: Date | undefined;
+        refs?: string[] | undefined;
     } | {
         id: string;
         classification: string;

package/dist/entrypoints/clients/control-plane-client.d.ts

@@ -1,5 +1,6 @@
 import type { ControlPlaneOperationBinding, ControlPlaneOperationBody, ControlPlaneOperationOutput, ControlPlaneOperationPath, ControlPlaneOperationQuery, OAuthScope } from '../../operator-contracts/control-plane-operation.js';
 import type { ApiPrincipal } from '../../operator-contracts/oauth.js';
+import type { InputRequired } from '../../operator-contracts/mcp.js';
 export declare const DEFAULT_CONTROL_PLANE_BASE_URL = "http://127.0.0.1:3002";
 export declare const CONTROL_PLANE_BASE_URL_ENV = "TREESEED_API_BASE_URL";
 export interface ControlPlaneServerProfile {
@@ -58,6 +59,7 @@ export interface ProblemDetails {
     requestId?: string;
     traceId?: string;
     fields?: Record<string, string[]>;
+    inputRequired?: InputRequired;
 }
 export interface ControlPlaneCallOptions {
     method?: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';

package/dist/entrypoints/clients/control-plane-client.js

@@ -67,7 +67,8 @@ function problemFrom(payload, status) {
     code: typeof source.code === "string" ? source.code : "control_plane_request_failed",
     requestId: typeof source.requestId === "string" ? source.requestId : void 0,
     traceId: typeof source.traceId === "string" ? source.traceId : void 0,
-    fields: source.fields && typeof source.fields === "object" ? source.fields : void 0
+    fields: source.fields && typeof source.fields === "object" ? source.fields : void 0,
+    inputRequired: source.inputRequired && typeof source.inputRequired === "object" ? source.inputRequired : void 0
   };
 }
 class ControlPlaneClient {
@@ -132,7 +133,12 @@ class ControlPlaneClient {
   async exchangeOAuthToken(values, signal) {
     const response = await this.fetchImpl(`${this.baseUrl}/oauth/token`, { method: "POST", headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(values), signal });
     const payload = await responsePayload(response);
-    if (!response.ok) throw new ControlPlaneClientError(String(payload.error_description ?? payload.error ?? "OAuth token exchange failed."), response.status, problemFrom(payload, response.status), response.headers);
+    if (!response.ok) {
+      const problem = problemFrom(payload, response.status);
+      problem.code = typeof payload.error === "string" ? payload.error : problem.code;
+      problem.detail = typeof payload.error_description === "string" ? payload.error_description : problem.detail;
+      throw new ControlPlaneClientError(problem.detail ?? problem.code, response.status, problem, response.headers);
+    }
     return { tokenType: "Bearer", accessToken: String(payload.access_token), refreshToken: typeof payload.refresh_token === "string" ? payload.refresh_token : void 0, expiresIn: Number(payload.expires_in), scope: String(payload.scope ?? "").split(/\s+/u).filter(Boolean), audience: String(payload.audience ?? this.baseUrl), principal: payload.principal && typeof payload.principal === "object" ? payload.principal : void 0 };
   }
   async request(options) {

package/dist/operator-contracts/canonical-command-tree.js

@@ -1,3 +1,61 @@
+const unavailable = (reason = "This capability is not enabled until its control-plane operation is accepted.") => ({
+  kind: "unavailable",
+  code: "standards_migration_not_enabled",
+  reason
+});
+const protocol = (handlerId) => ({ kind: "protocol", handlerId });
+const local = (handlerId) => ({ kind: "local", handlerId });
+const field = (target, name, source, sourceName = name, required = false, transform = "identity") => ({ target, field: name, source, name: sourceName, required, transform });
+const operation = (operationId, input = []) => ({ kind: "operation", operationId, input });
+const page = () => [field("query", "status", "option"), field("query", "limit", "option", "limit", false, "integer"), field("query", "cursor", "option")];
+const operationBindings = {
+  "auth login": protocol("protocol.oauth.device.login"),
+  "auth logout": protocol("protocol.oauth.revoke"),
+  "auth status": operation("accounts.current.show"),
+  "secrets list": local("local.secrets.list"),
+  "secrets status": local("local.secrets.status"),
+  "secrets unlock": local("local.secrets.unlock"),
+  "secrets lock": local("local.secrets.lock"),
+  "secrets rotate": local("local.secrets.rotate"),
+  "agents list": operation("agents.list", [field("path", "projectId", "context", "project", true), ...page()]),
+  "agents show": operation("agents.show", [field("path", "projectId", "context", "project", true), field("path", "agentSlug", "argument", "agent", true)]),
+  "agents classes list": operation("agents.classes.list", [field("path", "projectId", "context", "project", true)]),
+  "agents classes show": operation("agents.classes.show", [field("path", "projectId", "context", "project", true), field("path", "classId", "argument", "class", true)]),
+  "providers list": operation("services.providers.list", page()),
+  "providers show": operation("services.connections.show", [field("path", "teamId", "context", "team", true), field("path", "connectionId", "argument", "provider", true)]),
+  "providers status": operation("services.connections.show", [field("path", "teamId", "context", "team", true), field("path", "connectionId", "argument", "provider", true)]),
+  "providers connect": operation("services.connections.create", [field("path", "teamId", "context", "team", true), field("body", "providerId", "option", "provider", true)]),
+  "providers disconnect": operation("services.connections.disconnect", [field("path", "teamId", "context", "team", true), field("path", "connectionId", "argument", "connection", true), field("body", "reason", "option")]),
+  "providers credentials status": operation("services.credential.authorities.list", [field("path", "teamId", "context", "team", true), field("path", "connectionId", "argument", "connection", true)]),
+  "capacity status": operation("capacity.status", [field("path", "teamId", "context", "team", true), ...page()]),
+  "capacity usage": operation("capacity.usage", [field("path", "teamId", "context", "team", true)]),
+  "capacity ledger": operation("capacity.ledger", [field("path", "teamId", "context", "team", true), ...page()]),
+  "plans list": operation("plans.list", [field("path", "decisionId", "option", "decision", true), ...page()]),
+  "plans show": operation("plans.show", [field("path", "capacityPlanId", "argument", "plan", true)]),
+  "workdays plan": operation("workdays.plan", [field("path", "teamId", "context", "team", true), field("body", "profile", "option"), field("body", "projects", "option", "projects", false, "csv"), field("body", "start", "option"), field("body", "end", "option"), field("body", "duration", "option", "duration", false, "integer"), field("body", "objective", "option")]),
+  "workdays start": operation("workdays.start", [field("path", "teamId", "context", "team", true), field("body", "preflightId", "option", "preflight", true), field("body", "digest", "option", "digest", true)]),
+  "workdays list": operation("workdays.list", [field("path", "teamId", "context", "team", true), ...page()]),
+  "workdays show": operation("workdays.show", [field("path", "teamId", "context", "team", true), field("path", "runId", "argument", "workday", true)]),
+  "workdays schedules list": operation("workdays.schedules.list", [field("path", "teamId", "context", "team", true)]),
+  "workdays schedules start": operation("workdays.schedules.create", [field("path", "teamId", "context", "team", true), field("body", "profile", "option"), field("body", "projects", "option", "projects", false, "csv"), field("body", "duration", "option", "duration", false, "integer")]),
+  "assignments list": operation("assignments.list", [field("path", "teamId", "context", "team", true), ...page()]),
+  "assignments show": operation("assignments.show", [field("path", "teamId", "context", "team", true), field("path", "assignmentId", "argument", "assignment", true)]),
+  "assignments explain": operation("assignments.explain", [field("path", "teamId", "context", "team", true), field("path", "assignmentId", "argument", "assignment", true)]),
+  "assignments retry": operation("assignments.retry", [field("path", "teamId", "context", "team", true), field("path", "assignmentId", "argument", "assignment", true), field("body", "reason", "option")]),
+  "assignments cancel": operation("assignments.cancel", [field("path", "teamId", "context", "team", true), field("path", "assignmentId", "argument", "assignment", true), field("body", "reason", "option")]),
+  "projects treedx show": operation("treedx.library.show", [field("path", "projectId", "argument", "project", true)]),
+  "projects treedx bind": operation("treedx.library.bind", [field("path", "projectId", "argument", "project", true), field("body", "connectionId", "option", "connection", true)]),
+  "projects treedx status": operation("treedx.health.show", [field("path", "projectId", "argument", "project", true)]),
+  "projects treedx diagnose": operation("treedx.service.contract", [field("path", "projectId", "argument", "project", true)]),
+  "projects treedx capabilities": operation("treedx.capabilities.list", [field("path", "projectId", "argument", "project", true)]),
+  "projects treedx workspaces list": operation("treedx.workspaces.list", [field("path", "projectId", "argument", "project", true), ...page()]),
+  "projects treedx workspaces show": operation("treedx.workspaces.show", [field("path", "projectId", "context", "project", true), field("path", "workspaceId", "argument", "workspace", true)]),
+  "projects treedx workspaces abandon": operation("treedx.workspaces.abandon", [field("path", "projectId", "context", "project", true), field("path", "workspaceId", "argument", "workspace", true)]),
+  "status": operation("status.show"),
+  "save": unavailable("Unified GitHub-backed save is intentionally fail-closed during this cutover."),
+  "stage": unavailable("Unified GitHub-backed stage is intentionally fail-closed during this cutover."),
+  "release": unavailable("Production release is intentionally fail-closed during this cutover.")
+};
 const planOption = { name: "--plan", description: "Return the exact proposed outcome without mutation.", type: "boolean" };
 function leaf(segment, kind = "read", argument, confirmation = "never") {
   const value = {
@@ -7,14 +65,15 @@ function leaf(segment, kind = "read", argument, confirmation = "never") {
     arguments: argument ? [{ name: argument, description: `${argument} identity or path.`, required: true }] : void 0,
     options: kind === "mutation" ? [planOption] : void 0,
     authorization: kind === "mutation" ? { capability: `command.${segment}`, confirmation } : void 0,
-    resultSchemaId: `treeseed.command.${segment}/v1`
+    resultSchemaId: `treeseed.command.${segment}/v1`,
+    execution: unavailable()
   };
   return { nodeType: "leaf", ...value };
 }
 function branch(segment, children) {
   return { nodeType: "branch", segment, description: `${segment[0].toUpperCase()}${segment.slice(1)} operations.`, children };
 }
-const TREESEED_COMMAND_TREE_V1 = {
+const commandTree = {
   schemaVersion: "treeseed.command-tree/v1",
   executable: "trsd",
   commands: [
@@ -41,10 +100,10 @@ const TREESEED_COMMAND_TREE_V1 = {
       branch("offers", [leaf("show", "read", "connection"), leaf("validate", "read", "file"), leaf("plan", "read", "file"), leaf("apply", "mutation", "file", "authority")])
     ]),
     branch("capacity", [leaf("status"), leaf("explain"), leaf("usage"), leaf("ledger"), leaf("audit")]),
-    branch("plans", [leaf("list"), leaf("show", "read", "plan"), leaf("explain", "read", "plan"), { nodeType: "leaf", segment: "diff", description: "Compare two API-derived plans.", kind: "read", arguments: [{ name: "left", description: "Left plan identity.", required: true }, { name: "right", description: "Right plan identity.", required: true }], resultSchemaId: "treeseed.command.plans.diff/v1" }]),
+    branch("plans", [leaf("list"), leaf("show", "read", "plan"), leaf("explain", "read", "plan"), { nodeType: "leaf", segment: "diff", description: "Compare two API-derived plans.", kind: "read", arguments: [{ name: "left", description: "Left plan identity.", required: true }, { name: "right", description: "Right plan identity.", required: true }], resultSchemaId: "treeseed.command.plans.diff/v1", execution: unavailable() }]),
     branch("workdays", [
       branch("profiles", [leaf("list"), leaf("show", "read", "profile"), leaf("validate", "read", "file")]),
-      leaf("plan"),
+      leaf("plan", "mutation"),
       leaf("start", "mutation", void 0, "authority"),
       leaf("list"),
       leaf("show", "read", "workday"),
@@ -56,6 +115,14 @@ const TREESEED_COMMAND_TREE_V1 = {
       branch("schedules", [leaf("list"), leaf("show", "read", "schedule"), leaf("plan"), leaf("start", "mutation", void 0, "authority"), leaf("pause", "mutation", "schedule", "authority"), leaf("resume", "mutation", "schedule", "authority"), leaf("retire", "mutation", "schedule", "destructive")])
     ]),
     branch("assignments", [leaf("list"), leaf("show", "read", "assignment"), leaf("explain", "read", "assignment"), leaf("watch", "read", "assignment"), leaf("retry", "mutation", "assignment", "authority"), leaf("cancel", "mutation", "assignment", "destructive"), leaf("artifacts", "read", "assignment")]),
+    branch("projects", [branch("treedx", [
+      leaf("show", "read", "project"),
+      leaf("bind", "mutation", "project"),
+      leaf("status", "read", "project"),
+      leaf("diagnose", "read", "project"),
+      leaf("capabilities", "read", "project"),
+      branch("workspaces", [leaf("list", "read", "project"), leaf("show", "read", "workspace"), leaf("abandon", "mutation", "workspace", "destructive")])
+    ])]),
     leaf("save", "mutation"),
     leaf("stage", "mutation", void 0, "authority"),
     leaf("release", "mutation", void 0, "production"),
@@ -63,6 +130,15 @@ const TREESEED_COMMAND_TREE_V1 = {
     leaf("diagnose")
   ]
 };
+function attachExecution(nodes, parent = []) {
+  for (const node of nodes) {
+    const path = [...parent, node.segment];
+    if (node.nodeType === "branch") attachExecution(node.children, path);
+    else node.execution = operationBindings[path.join(" ")] ?? node.execution;
+  }
+}
+attachExecution(commandTree.commands);
+const TREESEED_COMMAND_TREE_V1 = commandTree;
 function listCommandPaths(tree = TREESEED_COMMAND_TREE_V1) {
   const paths = [];
   const visit = (nodes, parent) => {

package/dist/operator-contracts/command-tree.d.ts

@@ -1,3 +1,4 @@
+import type { ControlPlaneOperationBinding } from './control-plane-operation.js';
 export type CommandOperationKind = 'read' | 'mutation';
 export type CommandExecutionMode = 'execute' | 'plan';
 export type CommandErrorCategory = 'unknown_command' | 'invalid_input' | 'ambiguous_context' | 'authentication_required' | 'authorization_denied' | 'confirmation_required' | 'policy_blocked' | 'stale_preflight' | 'conflict' | 'not_found' | 'provider_unavailable' | 'rate_limited' | 'internal_error';
@@ -19,6 +20,31 @@ export interface CommandAuthorizationDescriptor {
     capability: string;
     confirmation: 'never' | 'destructive' | 'credential' | 'authority' | 'production' | 'irreversible';
 }
+export type CommandInputSource = 'argument' | 'context' | 'option';
+export type CommandInputTarget = 'path' | 'query' | 'body';
+export interface CommandInputBinding {
+    field: string;
+    source: CommandInputSource;
+    name: string;
+    target: CommandInputTarget;
+    required?: boolean;
+    transform?: 'identity' | 'integer' | 'csv';
+}
+export type CommandExecutionBinding = {
+    kind: 'operation';
+    operationId: `${string}.${string}`;
+    input: CommandInputBinding[];
+} | {
+    kind: 'protocol';
+    handlerId: `protocol.${string}`;
+} | {
+    kind: 'local';
+    handlerId: `local.${string}`;
+} | {
+    kind: 'unavailable';
+    code: string;
+    reason: string;
+};
 export interface CommandLeafDescriptor {
     segment: string;
     description: string;
@@ -27,6 +53,7 @@ export interface CommandLeafDescriptor {
     options?: CommandOptionDescriptor[];
     authorization?: CommandAuthorizationDescriptor;
     resultSchemaId: string;
+    execution: CommandExecutionBinding;
 }
 export interface CommandBranchDescriptor {
     segment: string;
@@ -76,4 +103,5 @@ export interface CommandTreeDiagnostic {
     message: string;
 }
 export declare function validateCommandTree(tree: CommandTreeDescriptor): CommandTreeDiagnostic[];
+export declare function validateCommandOperationBindings(tree: CommandTreeDescriptor, operations: readonly ControlPlaneOperationBinding<any, any, any, any>[]): CommandTreeDiagnostic[];
 export declare function createCommandResult<TResult>(input: Omit<CommandResultEnvelope<TResult>, 'schemaVersion'>): CommandResultEnvelope<TResult>;

package/dist/operator-contracts/command-tree.js

@@ -1,3 +1,4 @@
+import { ZodUndefined } from "zod";
 const SEGMENT = /^[a-z][a-z0-9]*$/;
 const FORBIDDEN_AGENT_MANAGEMENT_OPTIONS = /* @__PURE__ */ new Set([
   "--commit",
@@ -31,6 +32,17 @@ function validateCommandTree(tree) {
       }
       if ("children" in raw) diagnostics.push({ code: "command_node_ambiguous", path: diagnosticPath, message: "Leaf command nodes cannot contain child commands." });
       if (!node.resultSchemaId.trim()) diagnostics.push({ code: "result_schema_required", path: `${diagnosticPath}.resultSchemaId`, message: "Leaf commands require a stable result schema." });
+      if (!node.execution) diagnostics.push({ code: "command_execution_required", path: `${diagnosticPath}.execution`, message: "Every leaf must declare one authoritative execution binding." });
+      if (node.execution?.kind === "operation") {
+        const targets = /* @__PURE__ */ new Set();
+        for (const binding of node.execution.input) {
+          const key = `${binding.target}.${binding.field}`;
+          if (targets.has(key)) diagnostics.push({ code: "command_input_target_duplicate", path: `${diagnosticPath}.execution.input`, message: `Duplicate command input target ${key}.` });
+          targets.add(key);
+          if (!binding.field.trim() || !binding.name.trim()) diagnostics.push({ code: "command_input_binding_invalid", path: `${diagnosticPath}.execution.input`, message: "Command input bindings require field and source names." });
+        }
+      }
+      if (node.execution?.kind === "unavailable" && (!node.execution.code.trim() || !node.execution.reason.trim())) diagnostics.push({ code: "command_unavailable_reason_required", path: `${diagnosticPath}.execution`, message: "Unavailable commands require a stable code and explanation." });
       const optionNames = /* @__PURE__ */ new Set();
       for (const option of node.options ?? []) {
         if (optionNames.has(option.name)) diagnostics.push({ code: "command_option_duplicate", path: `${diagnosticPath}.options.${index}`, message: `Duplicate option ${option.name}.` });
@@ -44,10 +56,47 @@ function validateCommandTree(tree) {
   visit(tree.commands, []);
   return diagnostics;
 }
+function validateCommandOperationBindings(tree, operations) {
+  const diagnostics = [];
+  const catalog = new Map(operations.map((operation) => [operation.descriptor.operationId, operation]));
+  const visit = (nodes, parent) => {
+    for (const node of nodes) {
+      const path = [...parent, node.segment];
+      if (node.nodeType === "branch") {
+        visit(node.children, path);
+        continue;
+      }
+      if (node.execution.kind !== "operation") continue;
+      const binding = catalog.get(node.execution.operationId);
+      const diagnosticPath = `commands.${path.join(".")}.execution`;
+      if (!binding) {
+        diagnostics.push({ code: "command_operation_unknown", path: diagnosticPath, message: `Unknown control-plane operation ${node.execution.operationId}.` });
+        continue;
+      }
+      if (!binding.descriptor.surfaces.includes("cli")) diagnostics.push({ code: "command_operation_surface_missing", path: diagnosticPath, message: `Operation ${node.execution.operationId} does not declare the CLI surface.` });
+      if (binding.descriptor.kind !== node.kind) diagnostics.push({ code: "command_operation_kind_mismatch", path: diagnosticPath, message: `Command and operation ${node.execution.operationId} disagree about mutation behavior.` });
+      const expectedConfirmation = binding.descriptor.confirmation === "input_required" ? binding.descriptor.riskClass : "never";
+      if ((node.authorization?.confirmation ?? "never") !== expectedConfirmation) diagnostics.push({ code: "command_operation_confirmation_mismatch", path: diagnosticPath, message: `Command and operation ${node.execution.operationId} disagree about confirmation.` });
+      const shapes = {
+        path: "shape" in binding.schema.path ? Object.keys(binding.schema.path.shape) : null,
+        query: "shape" in binding.schema.query ? Object.keys(binding.schema.query.shape) : null,
+        body: "shape" in binding.schema.body ? Object.keys(binding.schema.body.shape) : null
+      };
+      for (const input of node.execution.input) {
+        const keys = shapes[input.target];
+        const undefinedSchema = binding.schema[input.target] instanceof ZodUndefined;
+        if (keys !== null && !keys.includes(input.field) || undefinedSchema) diagnostics.push({ code: "command_operation_input_unknown", path: `${diagnosticPath}.input.${input.target}.${input.field}`, message: `Operation ${node.execution.operationId} does not accept ${input.target} field ${input.field}.` });
+      }
+    }
+  };
+  visit(tree.commands, []);
+  return diagnostics.sort((left, right) => `${left.path}:${left.code}`.localeCompare(`${right.path}:${right.code}`));
+}
 function createCommandResult(input) {
   return { schemaVersion: "treeseed.command-result/v1", ...input };
 }
 export {
   createCommandResult,
+  validateCommandOperationBindings,
   validateCommandTree
 };

package/dist/operator-contracts/control-plane-operation.d.ts

@@ -27,6 +27,12 @@ export interface ControlPlaneConcurrencyContract {
     readHeader: 'ETag';
     writeHeader: 'If-Match';
 }
+export interface ControlPlaneUpstreamBinding {
+    service: 'treedx';
+    operationId: string;
+    contractVersion: string;
+    contractDigest: `sha256:${string}`;
+}
 export interface ControlPlaneOperationDescriptor {
     schemaVersion: typeof CONTROL_PLANE_OPERATION_SCHEMA_VERSION;
     operationId: `${string}.${string}`;
@@ -47,6 +53,7 @@ export interface ControlPlaneOperationDescriptor {
     audited: boolean;
     receipt: boolean;
     redactedPaths: string[];
+    upstream?: ControlPlaneUpstreamBinding;
 }
 export interface ControlPlaneOperationInput<TPath = Record<string, never>, TQuery = Record<string, never>, TBody = undefined> {
     path: TPath;

package/dist/operator-contracts/control-plane-operation.js

@@ -52,6 +52,9 @@ function validateControlPlaneCatalog(catalog) {
     }
     for (const duplicate of duplicates(operation.surfaces)) diagnostics.push({ code: "surface_duplicate", path: `${path}.surfaces`, message: `Duplicate operation surface ${duplicate}.` });
     for (const duplicate of duplicates(operation.oauthScopes)) diagnostics.push({ code: "oauth_scope_duplicate", path: `${path}.oauthScopes`, message: `Duplicate OAuth scope ${duplicate}.` });
+    if (operation.upstream && (!operation.upstream.operationId || !/^sha256:[0-9a-f]{64}$/u.test(operation.upstream.contractDigest))) {
+      diagnostics.push({ code: "upstream_binding_invalid", path: `${path}.upstream`, message: "Upstream bindings require an operation ID and exact SHA-256 contract digest." });
+    }
     const elevatedRisk = operation.riskClass !== "ordinary";
     if (elevatedRisk !== (operation.confirmation === "input_required")) {
       diagnostics.push({ code: "confirmation_policy_invalid", path: `${path}.confirmation`, message: "Elevated-risk operations require input_required; ordinary operations must not." });