@treeseed/sdk 0.12.62 → 0.13.0-rc.10

package/dist/model-registry/group-models.js

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { contentRoot, deriveFieldLists, field, graph } from "./content-root.js";
+function buildGroupModelRegistry(repoRoot) {
+  const root = contentRoot(repoRoot);
+  const groupFields = {
+    id: field("id", { filterable: true, sortable: true, contentKeys: ["id"], writeContentKey: "id" }),
+    slug: field("slug", { filterable: true, sortable: true, contentKeys: ["slug"], writeContentKey: "slug" }),
+    name: field("name", { filterable: true, sortable: true, contentKeys: ["name"], writeContentKey: "name" }),
+    classification: field("classification", { filterable: true, contentKeys: ["classification"], writeContentKey: "classification" }),
+    aliases: field("aliases", { filterable: true, comparableAs: "string_array", contentKeys: ["aliases"], writeContentKey: "aliases" }),
+    status: field("status", { filterable: true, contentKeys: ["status"], writeContentKey: "status" })
+  };
+  const edgeFields = {
+    id: field("id", { filterable: true, contentKeys: ["id"], writeContentKey: "id" }),
+    from_group_id: field("from_group_id", { aliases: ["fromGroupId"], filterable: true, contentKeys: ["from_group_id", "fromGroupId"], writeContentKey: "fromGroupId" }),
+    to_group_id: field("to_group_id", { aliases: ["toGroupId"], filterable: true, contentKeys: ["to_group_id", "toGroupId"], writeContentKey: "toGroupId" }),
+    predicate: field("predicate", { filterable: true, contentKeys: ["predicate"], writeContentKey: "predicate" }),
+    propagates_membership: field("propagates_membership", { aliases: ["propagatesMembership"], filterable: true, comparableAs: "boolean", contentKeys: ["propagates_membership", "propagatesMembership"], writeContentKey: "propagatesMembership" })
+  };
+  return {
+    group: {
+      name: "group",
+      aliases: ["groups"],
+      storage: "content",
+      operations: ["get", "read", "search", "follow", "pick", "create", "update"],
+      graph: graph({ entityType: "Group", titleField: "name", enableSections: true }),
+      fields: groupFields,
+      ...deriveFieldLists(groupFields),
+      pickField: "name",
+      contentCollection: "groups",
+      contentDir: path.join(root, "groups")
+    },
+    group_edge: {
+      name: "group_edge",
+      aliases: ["group_edges"],
+      storage: "content",
+      operations: ["get", "read", "search", "follow", "pick", "create", "update"],
+      graph: graph({ entityType: "GroupEdge", titleField: "id", enableSections: false, referenceFields: [
+        { field: "from_group_id", edgeType: "GROUP_SOURCE", targetModels: ["group"] },
+        { field: "to_group_id", edgeType: "GROUP_TARGET", targetModels: ["group"] }
+      ] }),
+      fields: edgeFields,
+      ...deriveFieldLists(edgeFields),
+      pickField: "id",
+      contentCollection: "group-edges",
+      contentDir: path.join(root, "group-edges")
+    }
+  };
+}
+export {
+  buildGroupModelRegistry
+};

package/dist/model-registry/knowledge-models.d.ts

@@ -0,0 +1,2 @@
+import type { SdkModelDefinition } from '../entrypoints/models/sdk-types.js';
+export declare function buildKnowledgeModelRegistry(repoRoot?: string): Record<'book' | 'knowledge', SdkModelDefinition>;

package/dist/model-registry/knowledge-models.js

@@ -0,0 +1,89 @@
+import path from "node:path";
+import { citationsField, contentRoot, field, graph } from "./content-root.js";
+function buildKnowledgeModelRegistry(repoRoot) {
+  const root = contentRoot(repoRoot);
+  return {
+    book: {
+      name: "book",
+      aliases: ["books"],
+      storage: "content",
+      operations: ["get", "read", "search", "follow", "pick", "create", "update"],
+      graph: graph({ entityType: "Book", titleField: "title", groupField: "group_ids", enableSections: true, referenceFields: [
+        { field: "related_books", edgeType: "RELATES_TO", targetModels: ["book"], multiple: true },
+        { field: "editorial_core_note", edgeType: "GUIDED_BY", targetModels: ["note"] }
+      ] }),
+      fields: {
+        schemaVersion: field("schemaVersion", { aliases: ["schema_version"], contentKeys: ["schemaVersion", "schema_version"], writeContentKey: "schemaVersion" }),
+        id: field("id", { filterable: true, contentKeys: ["id"], writeContentKey: "id" }),
+        title: field("title", { filterable: true, sortable: true, contentKeys: ["title"], writeContentKey: "title" }),
+        description: field("description", { contentKeys: ["description"], writeContentKey: "description" }),
+        summary: field("summary", { contentKeys: ["summary"], writeContentKey: "summary" }),
+        status: field("status", { filterable: true, contentKeys: ["status"], writeContentKey: "status" }),
+        visibility: field("visibility", { filterable: true, contentKeys: ["visibility"], writeContentKey: "visibility" }),
+        citations: citationsField(),
+        slug: field("slug", { filterable: true, contentKeys: ["slug"], writeContentKey: "slug" }),
+        group_ids: field("group_ids", { aliases: ["groupIds"], filterable: true, comparableAs: "string_array", contentKeys: ["group_ids", "groupIds"], writeContentKey: "groupIds" }),
+        audience: field("audience", { comparableAs: "string_array", contentKeys: ["audience"], writeContentKey: "audience" }),
+        related_books: field("related_books", { aliases: ["relatedBookIds"], filterable: true, comparableAs: "string_array", contentKeys: ["relatedBookIds", "related_books"], writeContentKey: "relatedBookIds" }),
+        editorial_core_note: field("editorial_core_note", { aliases: ["editorialCoreNoteId"], filterable: true, contentKeys: ["editorialCoreNoteId", "editorial_core_note"], writeContentKey: "editorialCoreNoteId" }),
+        section_label: field("section_label", { aliases: ["sectionLabel"], filterable: true, contentKeys: ["section_label", "sectionLabel"], writeContentKey: "section_label" }),
+        order: field("order", { sortable: true, comparableAs: "number", contentKeys: ["order"], writeContentKey: "order" }),
+        updated_at: field("updated_at", { aliases: ["updated", "updatedAt"], sortable: true, comparableAs: "date", contentKeys: ["updated_at", "updated", "updatedAt"], writeContentKey: "updated_at" })
+      },
+      filterableFields: ["title", "slug", "group_ids", "section_label", "related_books", "editorial_core_note"],
+      sortableFields: ["title", "order", "updated_at"],
+      pickField: "order",
+      contentCollection: "books",
+      contentDir: path.join(root, "books")
+    },
+    knowledge: {
+      name: "knowledge",
+      aliases: ["knowledge-base", "docs"],
+      storage: "content",
+      operations: ["get", "read", "search", "follow", "pick", "create", "update"],
+      graph: graph({ entityType: "Knowledge", titleField: "title", groupField: "group_ids", enableSections: true, referenceFields: [
+        { field: "book_id", edgeType: "BELONGS_TO", targetModels: ["book"] },
+        { field: "parent", edgeType: "BELONGS_TO", targetModels: ["knowledge"] },
+        { field: "related_knowledge", edgeType: "RELATES_TO", targetModels: ["knowledge"], multiple: true },
+        { field: "related_books", edgeType: "RELATES_TO", targetModels: ["book"], multiple: true },
+        { field: "related_notes", edgeType: "REFERENCES", targetModels: ["note"], multiple: true },
+        { field: "related_questions", edgeType: "REFERENCES", targetModels: ["question"], multiple: true },
+        { field: "related_objectives", edgeType: "REFERENCES", targetModels: ["objective"], multiple: true },
+        { field: "related_proposals", edgeType: "REFERENCES", targetModels: ["proposal"], multiple: true },
+        { field: "related_decisions", edgeType: "REFERENCES", targetModels: ["decision"], multiple: true }
+      ] }),
+      fields: {
+        schemaVersion: field("schemaVersion", { aliases: ["schema_version"], contentKeys: ["schemaVersion", "schema_version"], writeContentKey: "schemaVersion" }),
+        id: field("id", { filterable: true, contentKeys: ["id"], writeContentKey: "id" }),
+        title: field("title", { filterable: true, sortable: true, contentKeys: ["title"], writeContentKey: "title" }),
+        description: field("description", { contentKeys: ["description"], writeContentKey: "description" }),
+        summary: field("summary", { contentKeys: ["summary"], writeContentKey: "summary" }),
+        status: field("status", { filterable: true, contentKeys: ["status"], writeContentKey: "status" }),
+        visibility: field("visibility", { filterable: true, contentKeys: ["visibility"], writeContentKey: "visibility" }),
+        order: field("order", { sortable: true, comparableAs: "number", contentKeys: ["order"], writeContentKey: "order" }),
+        book_id: field("book_id", { aliases: ["bookId"], filterable: true, contentKeys: ["bookId", "book_id"], writeContentKey: "bookId" }),
+        citations: citationsField(),
+        group_ids: field("group_ids", { aliases: ["groupIds"], filterable: true, comparableAs: "string_array", contentKeys: ["group_ids", "groupIds"], writeContentKey: "groupIds" }),
+        parent: field("parent", { aliases: ["parentId"], filterable: true, contentKeys: ["parentId", "parent"], writeContentKey: "parentId" }),
+        related_knowledge: field("related_knowledge", { aliases: ["relatedKnowledgeIds"], filterable: true, comparableAs: "string_array", contentKeys: ["relatedKnowledgeIds", "related_knowledge"], writeContentKey: "relatedKnowledgeIds" }),
+        related_books: field("related_books", { aliases: ["relatedBookIds"], filterable: true, comparableAs: "string_array", contentKeys: ["relatedBookIds", "related_books"], writeContentKey: "relatedBookIds" }),
+        related_notes: field("related_notes", { aliases: ["relatedNoteIds"], filterable: true, comparableAs: "string_array", contentKeys: ["relatedNoteIds", "related_notes"], writeContentKey: "relatedNoteIds" }),
+        related_questions: field("related_questions", { aliases: ["relatedQuestionIds"], filterable: true, comparableAs: "string_array", contentKeys: ["relatedQuestionIds", "related_questions"], writeContentKey: "relatedQuestionIds" }),
+        related_objectives: field("related_objectives", { aliases: ["relatedObjectiveIds"], filterable: true, comparableAs: "string_array", contentKeys: ["relatedObjectiveIds", "related_objectives"], writeContentKey: "relatedObjectiveIds" }),
+        related_proposals: field("related_proposals", { aliases: ["relatedProposalIds"], filterable: true, comparableAs: "string_array", contentKeys: ["relatedProposalIds", "related_proposals"], writeContentKey: "relatedProposalIds" }),
+        related_decisions: field("related_decisions", { aliases: ["relatedDecisionIds"], filterable: true, comparableAs: "string_array", contentKeys: ["relatedDecisionIds", "related_decisions"], writeContentKey: "relatedDecisionIds" }),
+        guarantees: field("guarantees", { aliases: ["guaranteeIds"], filterable: true, comparableAs: "string_array", contentKeys: ["guaranteeIds", "guarantees"], writeContentKey: "guaranteeIds" }),
+        updated_at: field("updated_at", { aliases: ["updated", "updatedAt"], filterable: true, sortable: true, comparableAs: "date", contentKeys: ["updated_at", "updated", "updatedAt"], writeContentKey: "updated_at" }),
+        slug: field("slug", { filterable: true, contentKeys: ["slug"], writeContentKey: "slug" })
+      },
+      filterableFields: ["title", "book_id", "group_ids", "updated_at", "slug", "parent", "related_knowledge", "related_books", "related_notes", "related_questions", "related_objectives", "related_proposals", "related_decisions", "guarantees"],
+      sortableFields: ["title", "updated_at"],
+      pickField: "updated_at",
+      contentCollection: "docs",
+      contentDir: path.join(root, "knowledge")
+    }
+  };
+}
+export {
+  buildKnowledgeModelRegistry
+};

package/dist/model-registry/normalize-definition.d.ts

@@ -0,0 +1,8 @@
+import type { SdkModelDefinition, SdkModelRegistry } from '../entrypoints/models/sdk-types.js';
+export declare function normalizeDefinition(definition: SdkModelDefinition): SdkModelDefinition;
+export declare function mergeModelRegistries(baseRegistry: SdkModelRegistry, definitions?: SdkModelDefinition[]): SdkModelRegistry;
+export declare function buildModelRegistry(definitions?: SdkModelDefinition[]): SdkModelRegistry;
+export declare function buildScopedModelRegistry(repoRoot: string | undefined, definitions?: SdkModelDefinition[]): SdkModelRegistry;
+export declare const BUILTIN_MODEL_REGISTRY: SdkModelRegistry;
+export declare const MODEL_REGISTRY: SdkModelRegistry;
+export declare function resolveModelDefinition(model: string, registry?: SdkModelRegistry): SdkModelDefinition;

package/dist/model-registry/normalize-definition.js

@@ -0,0 +1,69 @@
+import { validateModelFieldAliases } from "../entrypoints/models/sdk-fields.js";
+import { buildBuiltinModelRegistry } from "./build-builtin-model-registry.js";
+function normalizeDefinition(definition) {
+  const normalizedFields = Object.fromEntries(
+    Object.entries(definition.fields ?? {}).map(([canonicalKey, binding]) => [
+      canonicalKey,
+      {
+        ...binding,
+        key: canonicalKey,
+        aliases: [...new Set((binding.aliases ?? []).map((alias) => alias.trim().toLowerCase()).filter(Boolean))],
+        contentKeys: [...new Set(binding.contentKeys ?? [])],
+        dbColumns: [...new Set(binding.dbColumns ?? [])],
+        payloadPaths: [...new Set(binding.payloadPaths ?? [])]
+      }
+    ])
+  );
+  const normalized = {
+    ...definition,
+    name: definition.name.trim(),
+    aliases: [...new Set((definition.aliases ?? []).map((alias) => alias.trim().toLowerCase()).filter(Boolean))],
+    fields: normalizedFields,
+    filterableFields: [...new Set(definition.filterableFields ?? Object.entries(normalizedFields).filter(([, binding]) => binding.filterable).map(([key]) => key))],
+    sortableFields: [...new Set(definition.sortableFields ?? Object.entries(normalizedFields).filter(([, binding]) => binding.sortable).map(([key]) => key))]
+  };
+  validateModelFieldAliases(normalized);
+  return normalized;
+}
+function mergeModelRegistries(baseRegistry, definitions = []) {
+  const registry = { ...baseRegistry };
+  for (const rawDefinition of definitions) {
+    const definition = normalizeDefinition(rawDefinition);
+    if (!definition.name) {
+      throw new Error("SDK model definitions require a non-empty name.");
+    }
+    registry[definition.name] = definition;
+  }
+  return registry;
+}
+function buildModelRegistry(definitions = []) {
+  return mergeModelRegistries(buildBuiltinModelRegistry(), definitions);
+}
+function buildScopedModelRegistry(repoRoot, definitions = []) {
+  return mergeModelRegistries(buildBuiltinModelRegistry(repoRoot), definitions);
+}
+const BUILTIN_MODEL_REGISTRY = buildBuiltinModelRegistry();
+const MODEL_REGISTRY = buildModelRegistry();
+function resolveModelDefinition(model, registry = MODEL_REGISTRY) {
+  const directMatch = registry[model];
+  if (directMatch) {
+    return directMatch;
+  }
+  const normalized = model.trim().toLowerCase();
+  const aliasMatch = Object.values(registry).find(
+    (definition) => definition.aliases.includes(normalized) || definition.name === normalized
+  );
+  if (!aliasMatch) {
+    throw new Error(`Unknown SDK model "${model}".`);
+  }
+  return aliasMatch;
+}
+export {
+  BUILTIN_MODEL_REGISTRY,
+  MODEL_REGISTRY,
+  buildModelRegistry,
+  buildScopedModelRegistry,
+  mergeModelRegistries,
+  normalizeDefinition,
+  resolveModelDefinition
+};

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

@@ -0,0 +1,3 @@
+import type { CommandTreeDescriptor } from './command-tree.js';
+export declare const TREESEED_COMMAND_TREE_V1: CommandTreeDescriptor;
+export declare function listCommandPaths(tree?: CommandTreeDescriptor): string[];

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

@@ -0,0 +1,81 @@
+const planOption = { name: "--plan", description: "Return the exact proposed outcome without mutation.", type: "boolean" };
+function leaf(segment, kind = "read", argument, confirmation = "never") {
+  const value = {
+    segment,
+    description: `${segment[0].toUpperCase()}${segment.slice(1)} the selected resource.`,
+    kind,
+    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`
+  };
+  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 = {
+  schemaVersion: "treeseed.command-tree/v1",
+  executable: "trsd",
+  commands: [
+    branch("auth", [leaf("login", "mutation", void 0, "credential"), leaf("logout", "mutation"), leaf("status")]),
+    branch("secrets", [leaf("list"), leaf("status"), leaf("unlock", "mutation", void 0, "credential"), leaf("lock", "mutation"), leaf("rotate", "mutation", void 0, "credential")]),
+    branch("agents", [
+      leaf("list"),
+      leaf("show", "read", "agent"),
+      leaf("validate"),
+      leaf("diff"),
+      leaf("diagnose"),
+      branch("classes", [leaf("list"), leaf("show", "read", "class")]),
+      branch("bindings", [leaf("list"), leaf("show", "read", "binding"), leaf("explain", "read", "binding")])
+    ]),
+    branch("providers", [
+      leaf("list"),
+      leaf("show", "read", "provider"),
+      leaf("status", "read", "provider"),
+      leaf("diagnose", "read", "provider"),
+      leaf("connect", "mutation", void 0, "credential"),
+      leaf("disconnect", "mutation", "connection", "destructive"),
+      branch("requests", [leaf("list"), leaf("show", "read", "request"), leaf("approve", "mutation", "request", "authority"), leaf("reject", "mutation", "request", "authority")]),
+      branch("credentials", [leaf("status", "read", "connection"), leaf("rotate", "mutation", "connection", "credential"), leaf("revoke", "mutation", "connection", "irreversible")]),
+      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("workdays", [
+      branch("profiles", [leaf("list"), leaf("show", "read", "profile"), leaf("validate", "read", "file")]),
+      leaf("plan"),
+      leaf("start", "mutation", void 0, "authority"),
+      leaf("list"),
+      leaf("show", "read", "workday"),
+      leaf("watch", "read", "workday"),
+      leaf("pause", "mutation", "workday", "authority"),
+      leaf("resume", "mutation", "workday", "authority"),
+      leaf("stop", "mutation", "workday", "destructive"),
+      leaf("cancel", "mutation", "workday", "destructive"),
+      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")]),
+    leaf("save", "mutation"),
+    leaf("stage", "mutation", void 0, "authority"),
+    leaf("release", "mutation", void 0, "production"),
+    leaf("status"),
+    leaf("diagnose")
+  ]
+};
+function listCommandPaths(tree = TREESEED_COMMAND_TREE_V1) {
+  const paths = [];
+  const visit = (nodes, parent) => {
+    for (const node of nodes) {
+      const path = [...parent, node.segment];
+      if (node.nodeType === "leaf") paths.push(path.join(" "));
+      else visit(node.children, path);
+    }
+  };
+  visit(tree.commands, []);
+  return paths;
+}
+export {
+  TREESEED_COMMAND_TREE_V1,
+  listCommandPaths
+};

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

@@ -0,0 +1,79 @@
+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';
+export interface CommandArgumentDescriptor {
+    name: string;
+    description: string;
+    required: boolean;
+    multiple?: boolean;
+}
+export interface CommandOptionDescriptor {
+    name: `--${string}`;
+    description: string;
+    type: 'boolean' | 'string' | 'number' | 'string[]';
+    required?: boolean;
+    defaultValue?: boolean | string | number | string[];
+    sensitive?: boolean;
+}
+export interface CommandAuthorizationDescriptor {
+    capability: string;
+    confirmation: 'never' | 'destructive' | 'credential' | 'authority' | 'production' | 'irreversible';
+}
+export interface CommandLeafDescriptor {
+    segment: string;
+    description: string;
+    kind: CommandOperationKind;
+    arguments?: CommandArgumentDescriptor[];
+    options?: CommandOptionDescriptor[];
+    authorization?: CommandAuthorizationDescriptor;
+    resultSchemaId: string;
+}
+export interface CommandBranchDescriptor {
+    segment: string;
+    description: string;
+    children: CommandNodeDescriptor[];
+}
+export type CommandNodeDescriptor = ({
+    nodeType: 'branch';
+} & CommandBranchDescriptor) | ({
+    nodeType: 'leaf';
+} & CommandLeafDescriptor);
+export interface CommandTreeDescriptor {
+    schemaVersion: 'treeseed.command-tree/v1';
+    executable: 'trsd';
+    commands: CommandNodeDescriptor[];
+}
+export interface CommandBlocker {
+    code: string;
+    message: string;
+    path?: string;
+}
+export interface CommandReceiptReference {
+    kind: string;
+    id: string;
+    digest?: string;
+    uri?: string;
+}
+export interface CommandResultEnvelope<TResult = unknown> {
+    schemaVersion: 'treeseed.command-result/v1';
+    commandPath: string[];
+    mode: CommandExecutionMode;
+    ok: boolean;
+    result: TResult | null;
+    error: {
+        category: CommandErrorCategory;
+        code: string;
+        message: string;
+    } | null;
+    warnings: string[];
+    blockers: CommandBlocker[];
+    receipts: CommandReceiptReference[];
+    nextActions: string[];
+}
+export interface CommandTreeDiagnostic {
+    code: string;
+    path: string;
+    message: string;
+}
+export declare function validateCommandTree(tree: CommandTreeDescriptor): CommandTreeDiagnostic[];
+export declare function createCommandResult<TResult>(input: Omit<CommandResultEnvelope<TResult>, 'schemaVersion'>): CommandResultEnvelope<TResult>;

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

@@ -0,0 +1,53 @@
+const SEGMENT = /^[a-z][a-z0-9]*$/;
+const FORBIDDEN_AGENT_MANAGEMENT_OPTIONS = /* @__PURE__ */ new Set([
+  "--commit",
+  "--commit-sha",
+  "--source-ref",
+  "--expected-base",
+  "--expected-commit",
+  "--branch",
+  "--checkpoint",
+  "--integration"
+]);
+function validateCommandTree(tree) {
+  const diagnostics = [];
+  if (tree.schemaVersion !== "treeseed.command-tree/v1") diagnostics.push({ code: "schema_version_invalid", path: "schemaVersion", message: "Command tree schemaVersion must be treeseed.command-tree/v1." });
+  if (tree.executable !== "trsd") diagnostics.push({ code: "executable_invalid", path: "executable", message: "trsd is the only public executable." });
+  const visit = (nodes, parent) => {
+    const segments = /* @__PURE__ */ new Set();
+    for (const [index, node] of nodes.entries()) {
+      const path = [...parent, node.segment];
+      const diagnosticPath = `commands.${path.join(".")}`;
+      if (!SEGMENT.test(node.segment)) diagnostics.push({ code: "command_segment_invalid", path: diagnosticPath, message: "Command path segments must be lowercase alphanumeric words without colons or hyphens." });
+      if (segments.has(node.segment)) diagnostics.push({ code: "command_path_duplicate", path: diagnosticPath, message: `Duplicate command segment ${node.segment}.` });
+      segments.add(node.segment);
+      const raw = node;
+      if ("alias" in raw || "aliases" in raw) diagnostics.push({ code: "command_alias_forbidden", path: diagnosticPath, message: "Public command aliases are forbidden." });
+      if (node.nodeType === "branch") {
+        if ("kind" in raw || "resultSchemaId" in raw || "options" in raw || "arguments" in raw) diagnostics.push({ code: "command_node_ambiguous", path: diagnosticPath, message: "Intermediate command nodes cannot also declare leaf behavior." });
+        if (!Array.isArray(node.children) || node.children.length === 0) diagnostics.push({ code: "command_branch_empty", path: diagnosticPath, message: "Intermediate command nodes must contain at least one child." });
+        visit(node.children ?? [], path);
+        continue;
+      }
+      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." });
+      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}.` });
+        optionNames.add(option.name);
+        if (option.name === "--execute") diagnostics.push({ code: "execute_option_forbidden", path: `${diagnosticPath}.options.${option.name}`, message: "Mutations execute by default; --plan is the only dry-run switch." });
+        if (parent[0] === "agents" && FORBIDDEN_AGENT_MANAGEMENT_OPTIONS.has(option.name)) diagnostics.push({ code: "agent_internal_option_forbidden", path: `${diagnosticPath}.options.${option.name}`, message: "Agent management commands cannot expose repository integration mechanics." });
+      }
+      if (node.kind === "mutation" && !optionNames.has("--plan")) diagnostics.push({ code: "mutation_plan_option_required", path: `${diagnosticPath}.options`, message: "Every mutation must expose universal zero-mutation --plan mode." });
+    }
+  };
+  visit(tree.commands, []);
+  return diagnostics;
+}
+function createCommandResult(input) {
+  return { schemaVersion: "treeseed.command-result/v1", ...input };
+}
+export {
+  createCommandResult,
+  validateCommandTree
+};

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

@@ -0,0 +1,80 @@
+import type { z } from 'zod';
+export declare const CONTROL_PLANE_OPERATION_SCHEMA_VERSION: "treeseed.control-plane-operation/v1";
+export type ControlPlaneHttpMethod = 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
+export type ControlPlaneOperationKind = 'read' | 'mutation';
+export type ControlPlaneRiskClass = 'ordinary' | 'destructive' | 'credential' | 'authority' | 'production' | 'irreversible';
+export type ControlPlaneConfirmationPolicy = 'never' | 'input_required';
+export type ControlPlaneOperationSurface = 'rest' | 'cli' | 'mcp_tool' | 'mcp_resource' | 'internal';
+export type ControlPlaneCacheScope = 'none' | 'principal' | 'team' | 'project' | 'public';
+export type ControlPlanePaginationKind = 'none' | 'cursor';
+export interface ControlPlaneRestBinding {
+    method: ControlPlaneHttpMethod;
+    path: `/v1/${string}`;
+}
+export interface ControlPlaneSchemaBinding {
+    input: string;
+    output: string;
+    parameters?: string;
+    errors: string;
+}
+export interface ControlPlaneIdempotencyContract {
+    required: boolean;
+    header: 'Idempotency-Key';
+}
+export interface ControlPlaneConcurrencyContract {
+    required: boolean;
+    readHeader: 'ETag';
+    writeHeader: 'If-Match';
+}
+export interface ControlPlaneOperationDescriptor {
+    schemaVersion: typeof CONTROL_PLANE_OPERATION_SCHEMA_VERSION;
+    operationId: `${string}.${string}`;
+    description: string;
+    rest?: ControlPlaneRestBinding;
+    schemas: ControlPlaneSchemaBinding;
+    capability: string;
+    oauthScopes: OAuthScope[];
+    kind: ControlPlaneOperationKind;
+    riskClass: ControlPlaneRiskClass;
+    confirmation: ControlPlaneConfirmationPolicy;
+    idempotency: ControlPlaneIdempotencyContract;
+    concurrency: ControlPlaneConcurrencyContract;
+    surfaces: ControlPlaneOperationSurface[];
+    cacheScope: ControlPlaneCacheScope;
+    pagination: ControlPlanePaginationKind;
+    audited: boolean;
+    receipt: boolean;
+    redactedPaths: string[];
+}
+export interface ControlPlaneOperationInput<TPath = Record<string, never>, TQuery = Record<string, never>, TBody = undefined> {
+    path: TPath;
+    query: TQuery;
+    body: TBody;
+}
+export interface ControlPlaneOperationSchemas<TPath, TQuery, TBody, TOutput> {
+    path: z.ZodType<TPath>;
+    query: z.ZodType<TQuery>;
+    body: z.ZodType<TBody>;
+    output: z.ZodType<TOutput>;
+}
+export interface ControlPlaneOperationBinding<TPath = Record<string, never>, TQuery = Record<string, never>, TBody = undefined, TOutput = unknown> {
+    descriptor: ControlPlaneOperationDescriptor;
+    schema: ControlPlaneOperationSchemas<TPath, TQuery, TBody, TOutput>;
+}
+export type ControlPlaneOperationPath<T> = T extends ControlPlaneOperationBinding<infer TPath, any, any, any> ? TPath : never;
+export type ControlPlaneOperationQuery<T> = T extends ControlPlaneOperationBinding<any, infer TQuery, any, any> ? TQuery : never;
+export type ControlPlaneOperationBody<T> = T extends ControlPlaneOperationBinding<any, any, infer TBody, any> ? TBody : never;
+export type ControlPlaneOperationOutput<T> = T extends ControlPlaneOperationBinding<any, any, any, infer TOutput> ? TOutput : never;
+export declare const TREESEED_OAUTH_SCOPES: readonly ["treeseed:read", "treeseed:knowledge:write", "treeseed:governance:write", "treeseed:projects:write", "treeseed:execution", "treeseed:admin"];
+export type OAuthScope = typeof TREESEED_OAUTH_SCOPES[number];
+export interface ControlPlaneCatalog {
+    schemaVersion: 'treeseed.control-plane-catalog/v1';
+    operations: ControlPlaneOperationDescriptor[];
+}
+export interface ControlPlaneCatalogDiagnostic {
+    code: string;
+    path: string;
+    message: string;
+}
+export declare function validateControlPlaneCatalog(catalog: ControlPlaneCatalog): ControlPlaneCatalogDiagnostic[];
+export declare function indexControlPlaneCatalog(catalog: ControlPlaneCatalog): Map<`${string}.${string}`, ControlPlaneOperationDescriptor>;

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

@@ -0,0 +1,75 @@
+const CONTROL_PLANE_OPERATION_SCHEMA_VERSION = "treeseed.control-plane-operation/v1";
+const TREESEED_OAUTH_SCOPES = [
+  "treeseed:read",
+  "treeseed:knowledge:write",
+  "treeseed:governance:write",
+  "treeseed:projects:write",
+  "treeseed:execution",
+  "treeseed:admin"
+];
+const OPERATION_ID = /^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/u;
+const PATH_PARAMETER = /\{([A-Za-z][A-Za-z0-9]*)\}/gu;
+function duplicates(values) {
+  const seen = /* @__PURE__ */ new Set();
+  return values.filter((value) => seen.size === seen.add(value).size);
+}
+function validateControlPlaneCatalog(catalog) {
+  const diagnostics = [];
+  const operationIds = /* @__PURE__ */ new Set();
+  const restBindings = /* @__PURE__ */ new Set();
+  for (const [index, operation] of catalog.operations.entries()) {
+    const path = `operations.${index}`;
+    if (operation.schemaVersion !== CONTROL_PLANE_OPERATION_SCHEMA_VERSION) {
+      diagnostics.push({ code: "operation_schema_version_invalid", path: `${path}.schemaVersion`, message: "Operation schemaVersion is not supported." });
+    }
+    if (!OPERATION_ID.test(operation.operationId)) {
+      diagnostics.push({ code: "operation_id_invalid", path: `${path}.operationId`, message: "Operation IDs must be stable dotted lowercase words." });
+    }
+    if (operationIds.has(operation.operationId)) {
+      diagnostics.push({ code: "operation_id_duplicate", path: `${path}.operationId`, message: `Duplicate operation ID ${operation.operationId}.` });
+    }
+    operationIds.add(operation.operationId);
+    if (operation.surfaces.includes("rest") !== Boolean(operation.rest)) {
+      diagnostics.push({ code: "rest_binding_mismatch", path: `${path}.rest`, message: "REST surface and REST binding must be declared together." });
+    }
+    if (operation.rest) {
+      const binding = `${operation.rest.method} ${operation.rest.path}`;
+      if (restBindings.has(binding)) diagnostics.push({ code: "rest_binding_duplicate", path: `${path}.rest`, message: `Duplicate REST binding ${binding}.` });
+      restBindings.add(binding);
+      const parameters = [...operation.rest.path.matchAll(PATH_PARAMETER)].map((match) => match[1]);
+      if (parameters.length > 0 && !operation.schemas.parameters) {
+        diagnostics.push({ code: "parameter_schema_required", path: `${path}.schemas.parameters`, message: "Parameterized REST paths require a parameter schema." });
+      }
+    }
+    for (const scope of operation.oauthScopes) {
+      if (!TREESEED_OAUTH_SCOPES.includes(scope)) diagnostics.push({ code: "oauth_scope_invalid", path: `${path}.oauthScopes`, message: `Unknown OAuth scope ${scope}.` });
+    }
+    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}.` });
+    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." });
+    }
+    if (operation.kind === "read" && (operation.idempotency.required || operation.concurrency.required || operation.receipt)) {
+      diagnostics.push({ code: "read_mutation_contract_invalid", path, message: "Read operations cannot require mutation idempotency, write concurrency, or mutation receipts." });
+    }
+    if (operation.kind === "mutation" && operation.surfaces.some((surface) => surface !== "internal") && !operation.audited) {
+      diagnostics.push({ code: "mutation_audit_required", path: `${path}.audited`, message: "Every externally reachable mutation must be audited." });
+    }
+    if (operation.kind === "mutation" && !operation.receipt) {
+      diagnostics.push({ code: "mutation_receipt_required", path: `${path}.receipt`, message: "Mutations must return durable receipts." });
+    }
+  }
+  return diagnostics.sort((left, right) => `${left.path}:${left.code}`.localeCompare(`${right.path}:${right.code}`));
+}
+function indexControlPlaneCatalog(catalog) {
+  const diagnostics = validateControlPlaneCatalog(catalog);
+  if (diagnostics.length > 0) throw new Error(`Invalid control-plane catalog: ${diagnostics.map((entry) => entry.code).join(", ")}`);
+  return new Map(catalog.operations.map((operation) => [operation.operationId, operation]));
+}
+export {
+  CONTROL_PLANE_OPERATION_SCHEMA_VERSION,
+  TREESEED_OAUTH_SCOPES,
+  indexControlPlaneCatalog,
+  validateControlPlaneCatalog
+};