@treeseed/sdk 0.13.0-rc.11 → 0.13.0-rc.111

package/dist/operator-contracts/inbox/contracts.js

@@ -0,0 +1,134 @@
+import { z } from "zod";
+const inboxItemKindSchema = z.enum(["proposal", "question"]);
+const inboxItemStatusSchema = z.enum(["outstanding", "answered", "approved", "rejected", "closed", "deleted"]);
+const inboxActionKindSchema = z.enum(["publish_revision", "approve", "reject", "comment", "answer", "reply", "reopen"]);
+const inboxProvenanceSchema = z.object({
+  repositoryId: z.string().nullable(),
+  contentPath: z.string().nullable(),
+  commitSha: z.string().nullable(),
+  digest: z.string().nullable()
+}).strict();
+const inboxActionDescriptorSchema = z.object({
+  action: inboxActionKindSchema,
+  label: z.string(),
+  enabled: z.boolean(),
+  reason: z.string().nullable(),
+  requiresFeedback: z.boolean(),
+  confirmation: z.enum(["never", "input_required"])
+}).strict();
+const inboxCommentSchema = z.object({
+  id: z.string(),
+  parentId: z.string().nullable(),
+  kind: z.enum(["comment", "answer", "reply"]),
+  authorId: z.string(),
+  authorLabel: z.string(),
+  markdown: z.string(),
+  createdAt: z.string().datetime(),
+  provenance: inboxProvenanceSchema
+}).strict();
+const inboxItemSchema = z.object({
+  schemaVersion: z.literal("treeseed.inbox-item/v1"),
+  id: z.string(),
+  teamId: z.string(),
+  projectId: z.string(),
+  projectSlug: z.string(),
+  kind: inboxItemKindSchema,
+  title: z.string(),
+  markdown: z.string(),
+  status: inboxItemStatusSchema,
+  authorId: z.string(),
+  authorLabel: z.string(),
+  version: z.number().int().positive(),
+  discussionId: z.string().nullable(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  provenance: inboxProvenanceSchema,
+  availableActions: z.array(inboxActionDescriptorSchema),
+  comments: z.array(inboxCommentSchema),
+  etag: z.string()
+}).strict();
+const inboxItemSummarySchema = inboxItemSchema.pick({
+  id: true,
+  teamId: true,
+  projectId: true,
+  projectSlug: true,
+  kind: true,
+  title: true,
+  status: true,
+  authorId: true,
+  authorLabel: true,
+  version: true,
+  createdAt: true,
+  updatedAt: true,
+  etag: true
+});
+const inboxItemPageSchema = z.object({
+  schemaVersion: z.literal("treeseed.inbox-page/v1"),
+  items: z.array(inboxItemSummarySchema),
+  cursor: z.string().nullable()
+}).strict();
+const inboxEventSchema = z.object({
+  schemaVersion: z.literal("treeseed.inbox-event/v1"),
+  sequence: z.string(),
+  id: z.string(),
+  teamId: z.string(),
+  itemId: z.string().nullable(),
+  type: z.enum(["item.created", "item.updated", "item.deleted", "draft.updated", "comment.created", "question.answered", "question.reopened", "proposal.revised", "proposal.decided"]),
+  actorId: z.string(),
+  occurredAt: z.string().datetime(),
+  summary: z.string(),
+  payload: z.record(z.unknown())
+}).strict();
+const inboxTimelineSchema = z.object({ events: z.array(inboxEventSchema), cursor: z.string() }).strict();
+const inboxDraftPurposeSchema = z.enum(["feedback", "proposal_revision"]);
+const inboxDraftSchema = z.object({
+  schemaVersion: z.literal("treeseed.inbox-draft/v1"),
+  itemId: z.string(),
+  purpose: inboxDraftPurposeSchema,
+  markdown: z.string(),
+  baseVersion: z.number().int().positive(),
+  revision: z.number().int().nonnegative(),
+  updatedAt: z.string().datetime(),
+  etag: z.string()
+}).strict();
+const inboxDraftWriteSchema = z.object({ markdown: z.string().max(1e5), baseVersion: z.number().int().positive() }).strict();
+const inboxQuestionCreateSchema = z.object({
+  projectId: z.string(),
+  title: z.string().trim().min(1).max(180),
+  markdown: z.string().trim().min(1).max(1e5),
+  recipients: z.array(z.string()).max(64).default([]),
+  relatedObjectives: z.array(z.string()).max(64).default([])
+}).strict();
+const inboxActionRequestSchema = z.object({
+  action: inboxActionKindSchema,
+  markdown: z.string().max(1e5).optional(),
+  parentId: z.string().optional(),
+  changeReason: z.string().max(2e3).optional(),
+  draftRevision: z.number().int().nonnegative().optional()
+}).strict();
+const inboxMutationReceiptSchema = z.object({
+  schemaVersion: z.literal("treeseed.inbox-mutation-receipt/v1"),
+  item: inboxItemSchema,
+  action: inboxActionKindSchema.optional(),
+  replayed: z.boolean(),
+  receipts: z.array(z.record(z.unknown())).default([])
+}).strict();
+export {
+  inboxActionDescriptorSchema,
+  inboxActionKindSchema,
+  inboxActionRequestSchema,
+  inboxCommentSchema,
+  inboxDraftPurposeSchema,
+  inboxDraftSchema,
+  inboxDraftWriteSchema,
+  inboxEventSchema,
+  inboxItemKindSchema,
+  inboxItemPageSchema,
+  inboxItemSchema,
+  inboxItemStatusSchema,
+  inboxItemSummarySchema,
+  inboxMutationReceiptSchema,
+  inboxProvenanceSchema,
+  inboxQuestionCreateSchema,
+  inboxTimelineSchema
+};

package/dist/operator-contracts/index.d.ts

@@ -6,3 +6,9 @@ export * from './control-plane-operation.js';
 export * from './control-plane-operations.js';
 export * from './mcp.js';
 export * from './oauth.js';
+export * from './communication/contracts.js';
+export * from './communication/addressing.js';
+export * from './inbox/contracts.js';
+export * from './knowledge/contracts.js';
+export * from '../capacity-provider/capability-ontology.js';
+export * from './seed/seed-bundle.js';

package/dist/operator-contracts/index.js

@@ -6,3 +6,9 @@ export * from "./control-plane-operation.js";
 export * from "./control-plane-operations.js";
 export * from "./mcp.js";
 export * from "./oauth.js";
+export * from "./communication/contracts.js";
+export * from "./communication/addressing.js";
+export * from "./inbox/contracts.js";
+export * from "./knowledge/contracts.js";
+export * from "../capacity-provider/capability-ontology.js";
+export * from "./seed/seed-bundle.js";

package/dist/operator-contracts/knowledge/contracts.d.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+export declare const knowledgeShareOperationSchema: z.ZodEnum<["read", "query", "context", "graph"]>;
+export declare const knowledgeShareGrantInputSchema: z.ZodObject<{
+    targetTeamId: z.ZodString;
+    projectIds: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>;
+    contentModels: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    paths: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    operations: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEnum<["read", "query", "context", "graph"]>, "many">, ("read" | "context" | "query" | "graph")[], ("read" | "context" | "query" | "graph")[]>>;
+    expiresAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    expiresAt: string | null;
+    operations: ("read" | "context" | "query" | "graph")[];
+    paths: string[];
+    targetTeamId: string;
+    projectIds: string[];
+    contentModels: string[];
+}, {
+    targetTeamId: string;
+    projectIds: string[];
+    expiresAt?: string | null | undefined;
+    operations?: ("read" | "context" | "query" | "graph")[] | undefined;
+    paths?: string[] | undefined;
+    contentModels?: string[] | undefined;
+}>;
+export declare const knowledgeShareSchema: z.ZodEffects<z.ZodObject<{
+    targetTeamId: z.ZodString;
+    projectIds: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>;
+    contentModels: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    paths: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    operations: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEnum<["read", "query", "context", "graph"]>, "many">, ("read" | "context" | "query" | "graph")[], ("read" | "context" | "query" | "graph")[]>>;
+    expiresAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+} & {
+    schemaVersion: z.ZodLiteral<"treeseed.knowledge-share/v1">;
+    id: z.ZodString;
+    sourceTeamId: z.ZodString;
+    status: z.ZodEnum<["active", "revoked", "expired"]>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    revokedAt: z.ZodNullable<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "active" | "revoked" | "expired";
+    id: string;
+    expiresAt: string | null;
+    schemaVersion: "treeseed.knowledge-share/v1";
+    createdAt: string;
+    operations: ("read" | "context" | "query" | "graph")[];
+    paths: string[];
+    updatedAt: string;
+    targetTeamId: string;
+    projectIds: string[];
+    contentModels: string[];
+    sourceTeamId: string;
+    revokedAt: string | null;
+}, {
+    status: "active" | "revoked" | "expired";
+    id: string;
+    schemaVersion: "treeseed.knowledge-share/v1";
+    createdAt: string;
+    updatedAt: string;
+    targetTeamId: string;
+    projectIds: string[];
+    sourceTeamId: string;
+    revokedAt: string | null;
+    expiresAt?: string | null | undefined;
+    operations?: ("read" | "context" | "query" | "graph")[] | undefined;
+    paths?: string[] | undefined;
+    contentModels?: string[] | undefined;
+}>, {
+    status: "active" | "revoked" | "expired";
+    id: string;
+    expiresAt: string | null;
+    schemaVersion: "treeseed.knowledge-share/v1";
+    createdAt: string;
+    operations: ("read" | "context" | "query" | "graph")[];
+    paths: string[];
+    updatedAt: string;
+    targetTeamId: string;
+    projectIds: string[];
+    contentModels: string[];
+    sourceTeamId: string;
+    revokedAt: string | null;
+}, {
+    status: "active" | "revoked" | "expired";
+    id: string;
+    schemaVersion: "treeseed.knowledge-share/v1";
+    createdAt: string;
+    updatedAt: string;
+    targetTeamId: string;
+    projectIds: string[];
+    sourceTeamId: string;
+    revokedAt: string | null;
+    expiresAt?: string | null | undefined;
+    operations?: ("read" | "context" | "query" | "graph")[] | undefined;
+    paths?: string[] | undefined;
+    contentModels?: string[] | undefined;
+}>;
+export declare const teamKnowledgeRequestSchema: z.ZodObject<{
+    projectIds: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    projectSlugs: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    sharedSources: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        teamId: z.ZodString;
+        projectIds: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    }, "strict", z.ZodTypeAny, {
+        teamId: string;
+        projectIds: string[];
+    }, {
+        teamId: string;
+        projectIds?: string[] | undefined;
+    }>, "many">>;
+    request: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strict", z.ZodTypeAny, {
+    request: Record<string, unknown>;
+    projectIds: string[];
+    projectSlugs: string[];
+    sharedSources: {
+        teamId: string;
+        projectIds: string[];
+    }[];
+}, {
+    request: Record<string, unknown>;
+    projectIds?: string[] | undefined;
+    projectSlugs?: string[] | undefined;
+    sharedSources?: {
+        teamId: string;
+        projectIds?: string[] | undefined;
+    }[] | undefined;
+}>;
+export type KnowledgeShare = z.infer<typeof knowledgeShareSchema>;
+export type KnowledgeShareGrantInput = z.infer<typeof knowledgeShareGrantInputSchema>;
+export type TeamKnowledgeRequest = z.infer<typeof teamKnowledgeRequestSchema>;

package/dist/operator-contracts/knowledge/contracts.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+const nonEmpty = z.string().trim().min(1);
+const uniqueStrings = (minimum = 0) => z.array(nonEmpty).min(minimum).superRefine((values, context) => {
+  if (new Set(values).size !== values.length) context.addIssue({ code: z.ZodIssueCode.custom, message: "Values must be unique." });
+});
+const knowledgeShareOperationSchema = z.enum(["read", "query", "context", "graph"]);
+const knowledgeShareGrantInputSchema = z.object({
+  targetTeamId: nonEmpty,
+  projectIds: uniqueStrings(1),
+  contentModels: uniqueStrings().default([]),
+  paths: uniqueStrings(1).default(["**"]),
+  operations: z.array(knowledgeShareOperationSchema).min(1).superRefine((values, context) => {
+    if (new Set(values).size !== values.length) context.addIssue({ code: z.ZodIssueCode.custom, message: "Operations must be unique." });
+  }).default(["read", "query", "context", "graph"]),
+  expiresAt: z.string().datetime({ offset: true }).nullable().default(null)
+}).strict();
+const knowledgeShareSchema = knowledgeShareGrantInputSchema.extend({
+  schemaVersion: z.literal("treeseed.knowledge-share/v1"),
+  id: nonEmpty,
+  sourceTeamId: nonEmpty,
+  status: z.enum(["active", "revoked", "expired"]),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+  revokedAt: z.string().datetime({ offset: true }).nullable()
+}).strict().superRefine((value, context) => {
+  if (value.sourceTeamId === value.targetTeamId) context.addIssue({ code: z.ZodIssueCode.custom, path: ["targetTeamId"], message: "Knowledge shares are only for another team." });
+});
+const teamKnowledgeRequestSchema = z.object({
+  projectIds: uniqueStrings().default([]),
+  projectSlugs: uniqueStrings().default([]),
+  sharedSources: z.array(z.object({ teamId: nonEmpty, projectIds: uniqueStrings().default([]) }).strict()).default([]),
+  request: z.record(z.unknown())
+}).strict();
+export {
+  knowledgeShareGrantInputSchema,
+  knowledgeShareOperationSchema,
+  knowledgeShareSchema,
+  teamKnowledgeRequestSchema
+};

package/dist/operator-contracts/mcp.d.ts

@@ -34,6 +34,7 @@ export interface InputRequired {
     prompt: string;
     confirmation: ConfirmationState;
 }
+export declare function encodeConfirmationState(state: ConfirmationState): string;
 export interface McpToolDescriptor {
     name: string;
     description: string;
@@ -74,5 +75,9 @@ export interface McpCatalog {
         resourceSubscriptions: true;
     };
 }
+export declare const TREESEED_MCP_PROMPTS: readonly McpPromptDescriptor[];
+export declare function operationToMcpResource(operation: ControlPlaneOperationDescriptor): McpResourceDescriptor | null;
 export declare function operationToMcpTool(operation: ControlPlaneOperationDescriptor): McpToolDescriptor | null;
 export declare function buildMcpTools(operations: readonly ControlPlaneOperationDescriptor[]): McpToolDescriptor[];
+export declare function buildMcpResources(operations: readonly ControlPlaneOperationDescriptor[]): McpResourceDescriptor[];
+export declare function buildMcpCatalog(operations: readonly ControlPlaneOperationDescriptor[]): McpCatalog;

package/dist/operator-contracts/mcp.js

@@ -1,4 +1,44 @@
 const MCP_PROTOCOL_VERSION = "2026-07-28";
+function encodeConfirmationState(state) {
+  const bytes = new TextEncoder().encode(JSON.stringify(state));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/gu, "");
+}
+const TREESEED_MCP_PROMPTS = [
+  { name: "operate", description: "Operate TreeSeed through currently discoverable capabilities.", argumentSchemaId: "treeseed.prompt.objective/v1", requiredScopes: ["treeseed:read"] },
+  { name: "research", description: "Research a governed TreeSeed question and accumulate knowledge.", argumentSchemaId: "treeseed.prompt.objective/v1", requiredScopes: ["treeseed:read"] },
+  { name: "governance-review", description: "Review a proposal or decision using current governance evidence.", argumentSchemaId: "treeseed.prompt.objective/v1", requiredScopes: ["treeseed:read"] },
+  { name: "workday-planning", description: "Plan a time-based workday without bypassing API authority.", argumentSchemaId: "treeseed.prompt.objective/v1", requiredScopes: ["treeseed:read"] },
+  { name: "project-agent-chat", description: "Prepare an explicit governed team-topic chat invocation for project agents.", argumentSchemaId: "treeseed.prompt.objective/v1", requiredScopes: ["treeseed:read"] }
+];
+function resourcePath(restPath) {
+  const [root, version, ...segments] = restPath.split("/");
+  if (root !== "" || version !== "v1" || segments.length === 0) throw new Error(`MCP resource requires a versioned control-plane REST path: ${restPath}`);
+  const path = segments.join("/");
+  if (path === "me") return "accounts/current";
+  return path.replace(/^platform\/operations(?=\/|$)/u, "operations").replace(/^capacity-plans(?=\/|$)/u, "plans").replace(/\/workday-runs(?=\/|$)/u, "/workdays").replace(/\/capacity\/assignments(?=\/|$)/u, "/assignments");
+}
+function operationToMcpResource(operation) {
+  if (!operation.surfaces.includes("mcp_resource")) return null;
+  if (operation.kind !== "read" || operation.rest.method !== "GET") {
+    throw new Error(`MCP resource operation ${operation.operationId} must be a read-only GET operation.`);
+  }
+  const uriTemplate = `treeseed://${resourcePath(operation.rest.path)}`;
+  const parameters = (value) => [...value.matchAll(/\{([^}]+)\}/gu)].map((match) => match[1]).sort();
+  if (JSON.stringify(parameters(uriTemplate)) !== JSON.stringify(parameters(operation.rest.path))) {
+    throw new Error(`MCP resource ${operation.operationId} must preserve its REST path parameter names.`);
+  }
+  return {
+    uriTemplate,
+    name: operation.operationId,
+    description: operation.description,
+    mimeType: "application/json",
+    operationId: operation.operationId,
+    subscribable: true,
+    ...operation.operationId === "status.show" ? { cacheTtlSeconds: 10 } : {}
+  };
+}
 function operationToMcpTool(operation) {
   if (!operation.surfaces.includes("mcp_tool")) return null;
   return {
@@ -16,8 +56,29 @@ function operationToMcpTool(operation) {
 function buildMcpTools(operations) {
   return operations.map(operationToMcpTool).filter((tool) => tool !== null).sort((left, right) => left.name.localeCompare(right.name));
 }
+function buildMcpResources(operations) {
+  const resources = operations.map(operationToMcpResource).filter((resource) => resource !== null).sort((left, right) => left.uriTemplate.localeCompare(right.uriTemplate));
+  const uriTemplates = new Set(resources.map(({ uriTemplate }) => uriTemplate));
+  if (uriTemplates.size !== resources.length) throw new Error("MCP resource URI templates must be unique.");
+  return resources;
+}
+function buildMcpCatalog(operations) {
+  return {
+    schemaVersion: "treeseed.mcp-catalog/v1",
+    protocolVersion: MCP_PROTOCOL_VERSION,
+    tools: buildMcpTools(operations),
+    resources: buildMcpResources(operations),
+    prompts: [...TREESEED_MCP_PROMPTS],
+    capabilities: { completion: true, progress: true, cancellation: true, inputRequired: true, resourceSubscriptions: true }
+  };
+}
 export {
   MCP_PROTOCOL_VERSION,
+  TREESEED_MCP_PROMPTS,
+  buildMcpCatalog,
+  buildMcpResources,
   buildMcpTools,
+  encodeConfirmationState,
+  operationToMcpResource,
   operationToMcpTool
 };

package/dist/operator-contracts/oauth.d.ts

@@ -1,4 +1,9 @@
 import type { OAuthScope } from './control-plane-operation.js';
+export declare const OAUTH_CLIENT_IDS: {
+    readonly cli: "trsd";
+    readonly admin: "treeseed-admin";
+};
+export type OAuthClientId = typeof OAUTH_CLIENT_IDS[keyof typeof OAUTH_CLIENT_IDS];
 export interface ApiPrincipal {
     id: string;
     displayName?: string;
@@ -18,6 +23,36 @@ export interface OAuthAuthorizationServerMetadata {
     code_challenge_methods_supported: ['S256'];
     scopes_supported: OAuthScope[];
 }
+export interface OAuthAuthorizationPresentation {
+    schemaVersion: 'treeseed.oauth.authorization-presentation/v1';
+    clientId: string;
+    clientName: string;
+    redirectUri: string;
+    redirectOrigin: string;
+    responseType: 'code';
+    codeChallenge: string;
+    codeChallengeMethod: 'S256';
+    scopes: OAuthScope[];
+    state: string | null;
+}
+export interface OAuthAuthorizationDecisionRequest {
+    clientId: string;
+    redirectUri: string;
+    responseType: 'code';
+    codeChallenge: string;
+    codeChallengeMethod: 'S256';
+    scope: OAuthScope[];
+    state?: string | null;
+    decision: 'approve' | 'deny';
+    identifier?: string;
+    password?: string;
+}
+export interface OAuthAuthorizationDecisionResult {
+    schemaVersion: 'treeseed.oauth.authorization-decision/v1';
+    approved: boolean;
+    redirectTo: string;
+    expiresIn?: number;
+}
 export interface OAuthProtectedResourceMetadata {
     resource: string;
     authorization_servers: string[];
@@ -36,6 +71,16 @@ export interface OAuthDeviceAuthorizationResponse {
     expiresIn: number;
     interval: number;
 }
+/** Safe browser presentation of a pending device grant. It never contains the device code. */
+export interface OAuthDeviceApprovalPresentation {
+    schemaVersion: 'treeseed.oauth.device-approval-presentation/v1';
+    clientId: string;
+    clientName: string;
+    userCode: string;
+    scopes: OAuthScope[];
+    expiresAt: string;
+    status: 'pending';
+}
 export interface OAuthTokenReceipt {
     tokenType: 'Bearer';
     accessToken: string;

package/dist/operator-contracts/oauth.js

@@ -0,0 +1,7 @@
+const OAUTH_CLIENT_IDS = {
+  cli: "trsd",
+  admin: "treeseed-admin"
+};
+export {
+  OAUTH_CLIENT_IDS
+};

package/dist/operator-contracts/operation-builder.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { type ControlPlaneOperationBinding, type ControlPlaneOperationDescriptor } from './control-plane-operation.js';
+type Definition = Omit<ControlPlaneOperationDescriptor, 'schemaVersion' | 'schemas' | 'idempotency' | 'concurrency' | 'audited' | 'receipt' | 'redactedPaths' | 'authentication'> & {
+    parameters?: string;
+    redactedPaths?: string[];
+    idempotencyRequired?: boolean;
+    concurrencyRequired?: boolean;
+    authentication?: ControlPlaneOperationDescriptor['authentication'];
+};
+export declare function defineReadOperation(operationId: `${string}.${string}`, path: `/v1/${string}`, capability: string, surfaces?: ControlPlaneOperationDescriptor['surfaces']): ControlPlaneOperationBinding<{}, {}, undefined, Record<string, unknown>>;
+export declare function defineOperation<TPath, TQuery, TBody, TOutput>(definition: Definition, schema: ControlPlaneOperationBinding<TPath, TQuery, TBody, TOutput>['schema']): ControlPlaneOperationBinding<TPath, TQuery, TBody, TOutput>;
+export declare function defineTreeDxProxyOperation<T extends z.ZodRawShape>(operationId: `${string}.${string}`, upstreamOperationId: string | null, method: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT', path: `/v1/${string}`, pathShape: T, options?: {
+    read?: boolean;
+    risk?: ControlPlaneOperationDescriptor['riskClass'];
+    surfaces?: ControlPlaneOperationDescriptor['surfaces'];
+    pagination?: ControlPlaneOperationDescriptor['pagination'];
+}): ControlPlaneOperationBinding<z.objectUtil.addQuestionMarks<z.baseObjectOutputType<T>, any> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+export {};

package/dist/operator-contracts/operation-builder.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { TREEDX_OPENAPI_CONTRACT } from "@treeseed/treedx/openapi";
+import {
+  CONTROL_PLANE_OPERATION_SCHEMA_VERSION
+} from "./control-plane-operation.js";
+function defineReadOperation(operationId, path, capability, surfaces = ["rest"]) {
+  return defineOperation({
+    operationId,
+    description: `Read ${operationId}.`,
+    rest: { method: "GET", path },
+    capability,
+    authentication: "oauth",
+    oauthScopes: ["treeseed:read"],
+    kind: "read",
+    riskClass: "ordinary",
+    confirmation: "never",
+    surfaces,
+    cacheScope: "principal",
+    pagination: "none"
+  }, { path: z.object({}).strict(), query: z.object({}).strict(), body: z.undefined(), output: z.record(z.unknown()) });
+}
+function defineOperation(definition, schema) {
+  const { parameters, redactedPaths = [], idempotencyRequired, concurrencyRequired, ...descriptor } = definition;
+  const mutation = definition.kind === "mutation";
+  return {
+    descriptor: {
+      ...descriptor,
+      authentication: definition.authentication ?? (definition.oauthScopes.length ? "oauth" : "anonymous"),
+      schemaVersion: CONTROL_PLANE_OPERATION_SCHEMA_VERSION,
+      schemas: {
+        input: `treeseed.${definition.operationId}.input/v1`,
+        output: `treeseed.${definition.operationId}.output/v1`,
+        errors: "treeseed.problem/v1",
+        ...parameters ? { parameters } : {}
+      },
+      idempotency: { required: idempotencyRequired ?? mutation, header: "Idempotency-Key" },
+      concurrency: { required: concurrencyRequired ?? false, readHeader: "ETag", writeHeader: "If-Match" },
+      audited: definition.surfaces.some((surface) => surface !== "internal"),
+      receipt: mutation,
+      redactedPaths
+    },
+    schema
+  };
+}
+const empty = z.object({}).strict();
+const none = z.undefined();
+const record = z.record(z.unknown());
+function defineTreeDxProxyOperation(operationId, upstreamOperationId, method, path, pathShape, options = {}) {
+  const kind = options.read ?? method === "GET" ? "read" : "mutation";
+  const riskClass = options.risk ?? "ordinary";
+  const surfaces = options.surfaces ?? ["rest", "mcp_tool", ...method === "GET" ? ["mcp_resource"] : []];
+  return defineOperation({
+    operationId,
+    description: `${kind === "read" ? "Read" : "Apply"} ${operationId} through the project-scoped TreeDX proxy.`,
+    ...surfaces.includes("rest") ? { rest: { method, path } } : {},
+    ...Object.keys(pathShape).length ? { parameters: `treeseed.${operationId}.parameters/v1` } : {},
+    capability: kind === "read" ? "treedx.read" : "treedx.write",
+    authentication: "oauth_or_provider",
+    oauthScopes: kind === "read" ? ["treeseed:read"] : ["treeseed:projects:write"],
+    kind,
+    riskClass,
+    confirmation: riskClass === "ordinary" ? "never" : "input_required",
+    surfaces,
+    cacheScope: kind === "read" ? "project" : "none",
+    pagination: options.pagination ?? "none",
+    ...upstreamOperationId ? { upstream: { service: "treedx", operationId: upstreamOperationId, contractVersion: TREEDX_OPENAPI_CONTRACT.openapiVersion, contractDigest: TREEDX_OPENAPI_CONTRACT.openapiSha256 } } : {}
+  }, {
+    path: z.object(pathShape).strict(),
+    query: method === "GET" ? record : empty,
+    body: method === "GET" ? none : record,
+    output: record
+  });
+}
+export {
+  defineOperation,
+  defineReadOperation,
+  defineTreeDxProxyOperation
+};